From 4e9a12385f5b2142e26ba5c09e4883f3a504ab23 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sat, 19 Sep 2026 19:38:14 -0600 Subject: [PATCH 1/8] feat(cache): implement HybridCachingKnowledgeRetrievalPort and associated tests for caching knowledge retrieval --- .../HybridCachingKnowledgeRetrievalPort.cs | 105 ++++++++++++ .../Knowledge/KnowledgeCardCodec.cs | 52 ++++++ .../PublicAPI.Unshipped.txt | 6 + .../Startup/KnowledgeStartup.cs | 20 ++- ...ybridCachingKnowledgeRetrievalPortTests.cs | 159 ++++++++++++++++++ .../KnowledgeStartupTests.cs | 38 ++++- 6 files changed, 377 insertions(+), 3 deletions(-) create mode 100644 src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs create mode 100644 src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs create mode 100644 tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs diff --git a/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs b/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs new file mode 100644 index 00000000..5e0ff80b --- /dev/null +++ b/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs @@ -0,0 +1,105 @@ +using AgentCore.Application.Ports; +using AgentCore.Domain.Knowledge; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Caching.Hybrid; + +namespace AgentCore.Application.Knowledge; + +/// +/// Remembers each search's cards in the host's cache, so a repeat of the same query under the same +/// scope skips the store. A store answers the same way to the same question until it is re-indexed, +/// so the lifetime is short by default: a stale answer costs a wrong card, not a wrong embedding. +/// +public sealed class HybridCachingKnowledgeRetrievalPort : IKnowledgeRetrievalPort, IAsyncDisposable +{ + /// How long an entry lives when the host names no lifetime. + public static readonly TimeSpan DefaultLifetime = TimeSpan.FromMinutes(5); + + private const string KeyPrefix = "agentcore:knowledge:"; + + private readonly IKnowledgeRetrievalPort _inner; + + private readonly HybridCache _cache; + + private readonly HybridCacheEntryOptions _entry; + + /// Wraps one store in the cache. + /// The store that runs the search. + /// The host's cache. + /// How long one answer stays cached, or for . + /// The store or the cache is . + public HybridCachingKnowledgeRetrievalPort( + IKnowledgeRetrievalPort inner, + HybridCache cache, + TimeSpan? lifetime = null) + { + ArgumentNullException.ThrowIfNull(inner); + ArgumentNullException.ThrowIfNull(cache); + + _inner = inner; + _cache = cache; + _entry = new HybridCacheEntryOptions { Expiration = lifetime ?? DefaultLifetime }; + } + + /// + /// + /// The store's own exceptions pass straight through and cache nothing, so a store that is down + /// or a scope it refuses reads exactly as it does without the cache. + /// + public async ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(query); + + // The cards ride as one JSON string so the host's serializer configuration never sees them: + // Extras is an object tree, and only KnowledgeCardCodec knows how to read it back. + var json = await _cache + .GetOrCreateAsync( + CacheKey(query, scope), + (Port: _inner, Query: query, Scope: scope), + static async (state, token) => KnowledgeCardCodec.Encode( + await state.Port.SearchAsync(state.Query, state.Scope, token).ConfigureAwait(false)), + _entry, + cancellationToken: cancellationToken) + .ConfigureAwait(false); + + return KnowledgeCardCodec.Decode(json); + } + + /// + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + + return serviceKey is null && serviceType.IsInstanceOfType(this) + ? this + : _inner.GetService(serviceType, serviceKey); + } + + /// Closes the store this wraps. + public async ValueTask DisposeAsync() + { + switch (_inner) + { + case IAsyncDisposable asyncDisposable: + await asyncDisposable.DisposeAsync().ConfigureAwait(false); + break; + case IDisposable disposable: + disposable.Dispose(); + break; + } + } + + private static string CacheKey(string query, KnowledgeScope? scope) + { + string[][] facets = scope is null + ? [] + : [.. scope.Facets + .OrderBy(entry => entry.Key, StringComparer.Ordinal) + .Select(entry => new[] { entry.Key, entry.Value })]; + + return KeyPrefix + AIJsonUtilities.HashDataToString([query, facets], AIJsonUtilities.DefaultOptions); + } +} diff --git a/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs b/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs new file mode 100644 index 00000000..8d015872 --- /dev/null +++ b/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs @@ -0,0 +1,52 @@ +using System.Text.Json; +using AgentCore.Domain.Knowledge; + +namespace AgentCore.Application.Knowledge; + +/// +/// Writes a list of cards to JSON and reads it back with the same payload shape the store gave. +/// +internal static class KnowledgeCardCodec +{ + private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web); + + public static string Encode(IReadOnlyList cards) + => JsonSerializer.Serialize(cards, Options); + + public static IReadOnlyList Decode(string json) + { + var cards = JsonSerializer.Deserialize>(json, Options) ?? []; + + for (var index = 0; index < cards.Count; index++) + { + cards[index] = cards[index] with { Extras = RebuildMap(cards[index].Extras) }; + } + + return cards; + } + + private static Dictionary RebuildMap(IReadOnlyDictionary map) + => map.ToDictionary(entry => entry.Key, entry => Rebuild(entry.Value), StringComparer.Ordinal); + + private static object? Rebuild(object? value) => value switch + { + JsonElement element => Rebuild(element), + IReadOnlyDictionary map => RebuildMap(map), + _ => value, + }; + + /// Mirrors the shape QdrantPointConverter produces: long, double, bool, string, list, map. + private static object? Rebuild(JsonElement element) => element.ValueKind switch + { + JsonValueKind.String => element.GetString(), + // Boxed on each arm: a bare long/double conditional promotes the long to a double. + JsonValueKind.Number => element.TryGetInt64(out var whole) ? (object)whole : element.GetDouble(), + JsonValueKind.True => true, + JsonValueKind.False => false, + JsonValueKind.Array => (IReadOnlyList)[.. element.EnumerateArray().Select(Rebuild)], + JsonValueKind.Object => element + .EnumerateObject() + .ToDictionary(property => property.Name, property => Rebuild(property.Value), StringComparer.Ordinal), + _ => null, + }; +} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 45e5b98a..20217e6a 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -2334,3 +2334,9 @@ override AgentCore.Application.Cache.PassThroughHybridCache.RemoveByTagAsync(str AgentCore.Application.Embeddings.HybridCachingEmbeddingGenerator AgentCore.Application.Embeddings.HybridCachingEmbeddingGenerator.HybridCachingEmbeddingGenerator(Microsoft.Extensions.AI.IEmbeddingGenerator!>! inner, Microsoft.Extensions.Caching.Hybrid.HybridCache! cache, System.TimeSpan? lifetime = null) -> void static readonly AgentCore.Application.Embeddings.HybridCachingEmbeddingGenerator.DefaultLifetime -> System.TimeSpan +AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort +AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.HybridCachingKnowledgeRetrievalPort(AgentCore.Application.Ports.IKnowledgeRetrievalPort! inner, Microsoft.Extensions.Caching.Hybrid.HybridCache! cache, System.TimeSpan? lifetime = null) -> void +AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.SearchAsync(string! query, AgentCore.Domain.Knowledge.KnowledgeScope? scope = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.GetService(System.Type! serviceType, object? serviceKey = null) -> object? +AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.DisposeAsync() -> System.Threading.Tasks.ValueTask +static readonly AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.DefaultLifetime -> System.TimeSpan diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index 342d3579..509f8d19 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs @@ -26,7 +26,25 @@ internal static class KnowledgeStartup /// /// Cancels the adapter build. /// The port, open, or . - internal static ValueTask OpenAsync( + internal static async ValueTask OpenAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + AgentCoreStartup startup, + IEmbeddingGenerator>? embeddings, + bool scopeDeclared, + bool requireScope, + CancellationToken cancellationToken) + { + var port = await OpenStoreAsync( + configuration, options, startup, embeddings, scopeDeclared, requireScope, cancellationToken) + .ConfigureAwait(false); + + return port is null || options.Cache is not { } cache + ? port + : new HybridCachingKnowledgeRetrievalPort(port, cache); + } + + private static ValueTask OpenStoreAsync( AgentCoreConfiguration configuration, AgentCoreOptions options, AgentCoreStartup startup, diff --git a/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs b/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs new file mode 100644 index 00000000..852a785f --- /dev/null +++ b/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs @@ -0,0 +1,159 @@ +using AgentCore.Application.Knowledge; +using AgentCore.Application.Ports; +using AgentCore.Application.Tests.Knowledge.Fakes; +using AgentCore.Domain.Knowledge; +using Microsoft.Extensions.Caching.Hybrid; +using Microsoft.Extensions.DependencyInjection; +using Xunit; + +namespace AgentCore.Application.Tests.Knowledge; + +/// +/// The cache in front of the knowledge store. A repeat of one query under one scope must not +/// reach the store again; a different query or a different facet must. What comes back must be +/// the card the store gave, payload tree included. +/// +public sealed class HybridCachingKnowledgeRetrievalPortTests +{ + private static readonly KnowledgeCard Card = new() + { + CardId = "card-1", + Text = "Loosen the four bolts.", + ViaLink = false, + SourceRef = "manual-f85", + SourceLocator = "p.12", + Authority = 3, + Score = 0.91, + Extras = new Dictionary(StringComparer.Ordinal) + { + ["model"] = "f85-2019", + ["page"] = 12L, + ["weight"] = 1.5, + ["draft"] = false, + ["tags"] = (IReadOnlyList)["belt", "deck"], + ["source"] = new Dictionary(StringComparer.Ordinal) { ["doc"] = "owner-manual" }, + }, + }; + + private static HybridCache NewCache() + { + ServiceCollection services = new(); + services.AddHybridCache(); + return services.BuildServiceProvider().GetRequiredService(); + } + + private static KnowledgeScope Scope(params (string Key, string Value)[] facets) => new() + { + Facets = facets.ToDictionary(facet => facet.Key, facet => facet.Value, StringComparer.Ordinal), + }; + + [Fact] + public async Task Repeat_of_one_query_skips_the_store() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + + Assert.Equal(1, store.Calls); + } + + [Fact] + public async Task A_cached_card_reads_back_whole() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + var cards = await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + + var card = Assert.Single(cards); + Assert.Equal(Card with { Extras = card.Extras }, card); + Assert.Equal("f85-2019", PayloadPath.Read(card.Extras, "model")); + Assert.Equal(12L, PayloadPath.Read(card.Extras, "page")); + Assert.Equal(1.5, PayloadPath.Read(card.Extras, "weight")); + Assert.Equal(false, PayloadPath.Read(card.Extras, "draft")); + Assert.Equal("owner-manual", PayloadPath.Read(card.Extras, "source.doc")); + Assert.Equal(["belt", "deck"], Assert.IsAssignableFrom>(PayloadPath.Read(card.Extras, "tags"))); + } + + [Fact] + public async Task A_different_facet_value_reaches_the_store() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + await port.SearchAsync("belt slips", Scope(("model", "f85")), TestContext.Current.CancellationToken); + await port.SearchAsync("belt slips", Scope(("model", "f63")), TestContext.Current.CancellationToken); + + Assert.Equal(2, store.Calls); + } + + [Fact] + public async Task Facet_order_does_not_change_the_key() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + await port.SearchAsync("belt slips", Scope(("model", "f85"), ("code", "us")), TestContext.Current.CancellationToken); + await port.SearchAsync("belt slips", Scope(("code", "us"), ("model", "f85")), TestContext.Current.CancellationToken); + + Assert.Equal(1, store.Calls); + } + + [Fact] + public async Task A_store_that_is_down_caches_nothing() + { + ThrowingKnowledgePort store = new(new InvalidOperationException("down")); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + await Assert.ThrowsAsync( + () => port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken).AsTask()); + await Assert.ThrowsAsync( + () => port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken).AsTask()); + } + + [Fact] + public void A_capability_of_the_store_is_reachable_through_the_cache() + { + FacetCapablePort store = new(); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + Assert.Same(store, port.GetService()); + Assert.Same(port, port.GetService()); + } + + [Fact] + public async Task Closing_the_cache_closes_the_store() + { + DisposingPort store = new(); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + await port.DisposeAsync(); + + Assert.True(store.Closed); + } + + private sealed class FacetCapablePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + + public ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + + private sealed class DisposingPort : IKnowledgeRetrievalPort, IDisposable + { + public bool Closed { get; private set; } + + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + + public void Dispose() => Closed = true; + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs index 8f61baf7..6c65d1d7 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs @@ -1,5 +1,7 @@ +using AgentCore.Application.Cache; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Knowledge; using AgentCore.Application.Ports; using Microsoft.Extensions.AI; using AgentCore.AspNetCore.DependencyInjection; @@ -76,6 +78,34 @@ public async Task OpenAsync_UseKnowledgeRetrievalRegistered_InvokesItWithTheStar Assert.Same(startup, seen); } + [Fact] + public async Task OpenAsync_CacheSet_WrapsTheStoreAndStillReachesIt() + { + RecordingAdapter adapter = new("test"); + AgentCoreOptions options = new() { Cache = PassThroughHybridCache.Instance }; + options.UseKnowledgeStores(adapter); + + var configuration = Configuration(new KnowledgeProviderConfiguration + { + Kind = "test", + Collection = "manuals", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + }); + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); + + var port = await KnowledgeStartup.OpenAsync( + configuration, + options, + startup, + embeddings: null, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken); + + Assert.IsType(port); + Assert.Same(adapter.LastBuilt, port.GetService()); + } + [Fact] public async Task OpenAsync_NoKnowledgeBlockAndNoAgentKnowledge_OpensNothingAndAsksNoAdapter() { @@ -177,11 +207,15 @@ public ValueTask CreateSearchAsync( } } - /// A port that answers with nothing. Only its identity is asserted against. - private sealed class FakePort : IKnowledgeRetrievalPort + /// A port that answers with nothing. Its identity, and one extra capability, are asserted against. + private sealed class FakePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort { public ValueTask> SearchAsync( string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) => ValueTask.FromResult>([]); + + public ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); } } From 66bf0892f00afebe2c993b605e922e5189aff1d9 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sat, 19 Sep 2026 20:15:55 -0600 Subject: [PATCH 2/8] feat(llm): implement conversation id stamping for chat requests and related tests --- .../Compilation/ConfigurationCompiler.cs | 37 +------- .../Llm/ChatRequestProperties.cs | 16 ++++ .../Llm/ConversationRequestStamp.cs | 22 +++++ .../PublicAPI.Unshipped.txt | 2 + .../Runtime/ModelFacingChatClient.cs | 2 + .../Runtime/TurnInvocation.cs | 7 +- .../Llm/OpenAI/OpenAiChatClientAdapter.cs | 8 +- ...igurationCompilerConversationStampTests.cs | 87 +++++++++++++++++++ .../Llm/CapturingChatClient.cs | 36 ++++++++ .../Llm/OpenAiPromptCacheKeyTests.cs | 74 ++++++++++++++++ .../Llm/OpenAiReasoningEffortTests.cs | 38 +------- 11 files changed, 255 insertions(+), 74 deletions(-) create mode 100644 src/AgentCore.Application/Llm/ChatRequestProperties.cs create mode 100644 src/AgentCore.Application/Llm/ConversationRequestStamp.cs create mode 100644 tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs diff --git a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs index c528aedc..65838511 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs @@ -1,4 +1,5 @@ using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Llm; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; @@ -11,40 +12,6 @@ namespace AgentCore.Application.Configuration.Compilation; /// /// The compile table of section 8.2. It is a table, not a heuristic. /// -/// -/// -/// The entry holdsAgentCore builds -/// -/// agent: -/// : ChatClientAgent, with no runtime -/// -/// -/// policy: -/// : the machine picks a stage each turn, and the stage names one agent. Runtime is Stateless -/// -/// -/// graph: with pattern: -/// : one of the four AgentWorkflowBuilder shapes -/// -/// -/// graph: with nodes: and edges: -/// : WorkflowBuilder, agents bound as executors, then AsAIAgent() -/// -/// -/// two of agent:, policy:, graph:, or none of them -/// a load-time error -/// -/// -/// -/// Each entry selects one row, and each row is a . This class selects -/// the row each entry picks and builds what every entry shares: the agents.items entries, -/// their tools, and the per-entry turn-disposition layers. -/// -/// -/// Every failure here reports through and carries a JSON -/// Pointer, exactly as the eight checks of section 8.5 do. -/// -/// public static class ConfigurationCompiler { /// Picks the row of the compile table one entry selects. @@ -285,6 +252,7 @@ private static CompiledAgentSet BuildAgents( ChatHistoryProvider = history, AIContextProviders = providers, }); + path.RemoveAt(path.Count - 1); var instrumented = new AIAgentBuilder(built) @@ -303,6 +271,7 @@ private static CompiledAgentSet BuildAgents( private static AuditingFunctionInvokingChatClient WithToolFailureAuditing(IChatClient model) => new(model.AsBuilder() .UseOpenTelemetry(configure: static client => client.EnableSensitiveData = false) + .ConfigureOptions(ConversationRequestStamp.Apply) .Use(static innerClient => new ModelFacingChatClient(innerClient)) .Build()); diff --git a/src/AgentCore.Application/Llm/ChatRequestProperties.cs b/src/AgentCore.Application/Llm/ChatRequestProperties.cs new file mode 100644 index 00000000..99fd9ca3 --- /dev/null +++ b/src/AgentCore.Application/Llm/ChatRequestProperties.cs @@ -0,0 +1,16 @@ +namespace AgentCore.Application.Llm; + +/// +/// The keys AgentCore writes on ChatOptions.AdditionalProperties for a vendor adapter to +/// read. The runtime knows the conversation; the adapter knows the vendor's wire field. These +/// keys are the seam between the two. +/// +public static class ChatRequestProperties +{ + /// + /// The id of the conversation this request belongs to, as a . An adapter + /// hands it to the vendor as the prompt cache key, so every turn of one conversation routes to + /// the same cache. Absent on a request that runs outside a conversation turn. + /// + public const string ConversationId = "urn:agentcore:conversation-id"; +} diff --git a/src/AgentCore.Application/Llm/ConversationRequestStamp.cs b/src/AgentCore.Application/Llm/ConversationRequestStamp.cs new file mode 100644 index 00000000..1b9ebba9 --- /dev/null +++ b/src/AgentCore.Application/Llm/ConversationRequestStamp.cs @@ -0,0 +1,22 @@ +using AgentCore.Application.Runtime; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Llm; + +/// +/// Copies the running turn's conversation id onto the request, under +/// , where a vendor adapter can read it. +/// +internal static class ConversationRequestStamp +{ + internal static void Apply(ChatOptions options) + { + ArgumentNullException.ThrowIfNull(options); + + if (TurnInvocation.From(options) is { ConversationId: { Length: > 0 } conversationId }) + { + options.AdditionalProperties ??= []; + options.AdditionalProperties[ChatRequestProperties.ConversationId] = conversationId; + } + } +} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 20217e6a..17edeebd 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -2340,3 +2340,5 @@ AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.SearchAsync( AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.GetService(System.Type! serviceType, object? serviceKey = null) -> object? AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.DisposeAsync() -> System.Threading.Tasks.ValueTask static readonly AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.DefaultLifetime -> System.TimeSpan +AgentCore.Application.Llm.ChatRequestProperties +const AgentCore.Application.Llm.ChatRequestProperties.ConversationId = "urn:agentcore:conversation-id" -> string! diff --git a/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs b/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs index d3721a1e..7aba873d 100644 --- a/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs +++ b/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs @@ -36,7 +36,9 @@ private static IEnumerable Strip(IEnumerable messages) private sealed class KeyHider : IDisposable { private readonly ChatOptions? _options; + private readonly object? _held; + private readonly bool _took; private KeyHider(ChatOptions? options) diff --git a/src/AgentCore.Application/Runtime/TurnInvocation.cs b/src/AgentCore.Application/Runtime/TurnInvocation.cs index c19281e6..70446fd3 100644 --- a/src/AgentCore.Application/Runtime/TurnInvocation.cs +++ b/src/AgentCore.Application/Runtime/TurnInvocation.cs @@ -96,8 +96,11 @@ internal IReadOnlyList Attachments() /// Reads the turn filed on a run's options by , or null when there is none. internal static TurnInvocation? From(AgentRunOptions? options) - => options is ChatClientAgentRunOptions run - && run.ChatOptions?.AdditionalProperties?.TryGetValue(ArgumentsKey, out var filed) == true + => options is ChatClientAgentRunOptions run ? From(run.ChatOptions) : null; + + /// Reads the turn filed on the options one request carries, or null outside a turn. + internal static TurnInvocation? From(ChatOptions? options) + => options?.AdditionalProperties?.TryGetValue(ArgumentsKey, out var filed) == true ? filed as TurnInvocation : null; diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs index 3a42ed5b..ff80c9d2 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs @@ -6,6 +6,7 @@ using System.Globalization; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Llm; using AgentCore.Application.Ports; using AgentCore.Application.Secrets; using Microsoft.Extensions.AI; @@ -64,7 +65,7 @@ await secrets }; } - /// Puts store and reasoning_effort on every request this client sends. + /// Puts store, reasoning_effort and prompt_cache_key on every request this client sends. internal static IChatClient WithResponseDefaults(IChatClient client, string? effort) { var level = effort is { Length: > 0 } value ? Level(value) : (ResponseReasoningEffortLevel?)null; @@ -84,6 +85,11 @@ internal static IChatClient WithResponseDefaults(IChatClient client, string? eff raw.StoredOutputEnabled ??= false; + if (options.AdditionalProperties?.TryGetValue(ChatRequestProperties.ConversationId, out string? conversationId) == true) + { + raw.PromptCacheKey ??= conversationId; + } + if (level is { } chosen) { raw.ReasoningOptions ??= new ResponseReasoningOptions diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs new file mode 100644 index 00000000..2b3b6c68 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs @@ -0,0 +1,87 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Llm; +using AgentCore.Application.Runtime; +using AgentCore.Application.Tests.Fakes; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Configuration.Compilation; + +/// +/// A compiled agent stamps the running turn's conversation id on every request the vendor sees, +/// under . This proves the COMPILED chain, not +/// the stamp on its own. +/// +public sealed class ConfigurationCompilerConversationStampTests +{ + private const string Yaml = + """ + apiVersion: agentcore/v1 + agents: + items: + - { id: only, model: { ref: reply }, instructions: "greet the caller" } + entries: + main: + agent: only + """; + + [Fact] + public async Task ARunInsideATurn_CarriesTheConversationIdToTheVendor() + { + var turn = new TurnInvocation { ConversationId = "conversation-7", TurnIndex = 0, Stage = "" }; + OptionsCapturingChatClient model = new(); + var compiled = Compile(model); + + var session = await compiled.CreateSessionAsync(TestContext.Current.CancellationToken); + await compiled.RunAsync( + [new ChatMessage(ChatRole.User, "hi")], + session, + turn.RunOptions(), + TestContext.Current.CancellationToken); + + Assert.True(model.Seen!.AdditionalProperties!.TryGetValue(ChatRequestProperties.ConversationId, out string? stamped)); + Assert.Equal("conversation-7", stamped); + } + + [Fact] + public async Task ARunOutsideATurn_StampsNothing() + { + OptionsCapturingChatClient model = new(); + var compiled = Compile(model); + + var session = await compiled.CreateSessionAsync(TestContext.Current.CancellationToken); + await compiled.RunAsync([new ChatMessage(ChatRole.User, "hi")], session, cancellationToken: TestContext.Current.CancellationToken); + + Assert.False(model.Seen!.AdditionalProperties?.ContainsKey(ChatRequestProperties.ConversationId) ?? false); + } + + private static Microsoft.Agents.AI.AIAgent Compile(IChatClient model) + { + var document = ConfigurationLoader.LoadYaml(Yaml); + return ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(model)))["main"].Agent; + } + + private sealed class OptionsCapturingChatClient : IChatClient + { + public ChatOptions? Seen { get; private set; } + + public Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + Seen = options; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); + } + + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + => throw new NotSupportedException(); + + public object? GetService(Type serviceType, object? serviceKey = null) + => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + + public void Dispose() + { + } + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs b/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs new file mode 100644 index 00000000..7507c5d5 --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs @@ -0,0 +1,36 @@ +using System.Runtime.CompilerServices; +using Microsoft.Extensions.AI; + +namespace AgentCore.Infrastructure.Tests.Llm; + +/// Records the options it was called with, and answers nothing. +internal sealed class CapturingChatClient : IChatClient +{ + public ChatOptions? Seen { get; private set; } + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + Seen = options; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + Seen = options; + await Task.Yield(); + yield return new ChatResponseUpdate(ChatRole.Assistant, "ok"); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + + public void Dispose() + { + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs new file mode 100644 index 00000000..ed8086a1 --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs @@ -0,0 +1,74 @@ +#pragma warning disable OPENAI001 + +using AgentCore.Application.Llm; +using AgentCore.Infrastructure.Llm.OpenAI; +using Microsoft.Extensions.AI; +using OpenAI.Responses; +using Xunit; + +namespace AgentCore.Infrastructure.Tests.Llm; + +/// +/// The conversation id the runtime stamps under +/// reaches the vendor as prompt_cache_key, so every turn of one conversation lands on the +/// same prompt cache. Every test here runs offline. +/// +public sealed class OpenAiPromptCacheKeyTests +{ + [Fact] + public async Task AStampedConversationId_BecomesThePromptCacheKey() + { + CapturingChatClient inner = new(); + + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); + await client.GetResponseAsync( + "hi", + new ChatOptions + { + AdditionalProperties = new AdditionalPropertiesDictionary + { + [ChatRequestProperties.ConversationId] = "conv-42", + }, + }, + TestContext.Current.CancellationToken); + + var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + + Assert.Equal("conv-42", raw.PromptCacheKey); + } + + [Fact] + public async Task ARequestOutsideAConversation_SendsNoPromptCacheKey() + { + CapturingChatClient inner = new(); + + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); + await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + + var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + + Assert.Null(raw.PromptCacheKey); + } + + [Fact] + public async Task AKeyTheCallerSetItself_Wins() + { + CapturingChatClient inner = new(); + CreateResponseOptions mine = new() { PromptCacheKey = "caller-key" }; + + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); + await client.GetResponseAsync( + "hi", + new ChatOptions + { + RawRepresentationFactory = _ => mine, + AdditionalProperties = new AdditionalPropertiesDictionary + { + [ChatRequestProperties.ConversationId] = "conv-42", + }, + }, + TestContext.Current.CancellationToken); + + Assert.Equal("caller-key", mine.PromptCacheKey); + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs index e30fc848..c6a841c0 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs @@ -1,6 +1,5 @@ #pragma warning disable OPENAI001 -using System.Runtime.CompilerServices; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Infrastructure.Llm.OpenAI; @@ -25,7 +24,7 @@ namespace AgentCore.Infrastructure.Tests.Llm; /// Every test here runs offline. No request leaves the process and no key is real. /// /// -public sealed partial class OpenAiReasoningEffortTests +public sealed class OpenAiReasoningEffortTests { [Theory] [InlineData("none")] @@ -190,38 +189,3 @@ public void ResolveHostedTool_ForAnUnknownMarker_AnswersNull() WebSearch = webSearch, }; } - -public sealed partial class OpenAiReasoningEffortTests -{ - /// Records the options it was called with, and answers nothing. - private sealed class CapturingChatClient : IChatClient - { - public ChatOptions? Seen { get; private set; } - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - Seen = options; - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); - } - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - Seen = options; - await Task.Yield(); - yield return new ChatResponseUpdate(ChatRole.Assistant, "ok"); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - - public void Dispose() - { - } - } -} From 9ed9dfef96b493a0604d7e76e972ccdf7aaf87c7 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sat, 19 Sep 2026 20:34:34 -0600 Subject: [PATCH 3/8] feat(cache): implement caching mechanism for tools with cacheSeconds property and related tests --- .../Configuration/Schema/ToolConfiguration.cs | 17 +- .../Schema/agentcore-v1.schema.json | 16 +- .../PublicAPI.Unshipped.txt | 6 + src/AgentCore.Application/Tools/CachedTool.cs | 74 +++++++ .../Tools/Registry/ToolRegistryBuilder.cs | 24 ++- .../Tools/Registry/ToolSourceContext.cs | 7 + .../Startup/ToolRegistryStartup.cs | 2 +- .../ConfigurationSchemaValidatorTests.cs | 52 +++++ .../Tools/CachedToolTests.cs | 192 ++++++++++++++++++ 9 files changed, 373 insertions(+), 17 deletions(-) create mode 100644 src/AgentCore.Application/Tools/CachedTool.cs create mode 100644 tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs diff --git a/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs index 1cdad795..f89738dc 100644 --- a/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs @@ -19,12 +19,6 @@ public enum ToolKind /// /// A tool that runs another declared agent and returns its reply. agent: names it. /// - /// - /// This is agent-as-tool, and it is not handoff. The outer agent sees one function, calls it, - /// and keeps control. Handoff transfers control instead, and an entry's graph: with - /// pattern: handoff already carries it, so the two do not overlap. Check 8 of section 8.5 - /// walks the edges this kind declares. - /// Agent, } @@ -66,10 +60,6 @@ public sealed record ToolConfiguration /// /// Gets the id of the agent this tool runs. It is set when the kind is . /// - /// - /// The value names one entry of agents.items. It is the one explicit delegation edge in - /// the document, so check 8 reads this field and never a naming convention. - /// public string? Agent { get; init; } /// Gets the raw JSON Schema of the tool arguments, or when the tool takes none. @@ -78,6 +68,13 @@ public sealed record ToolConfiguration /// Gets the HTTP call. It is set when the kind is . public HttpRequestConfiguration? Request { get; init; } + /// + /// Gets how long one answer is served again for the same arguments, in seconds, or + /// when every call reaches the tool. Only a + /// or tool may set it. + /// + public int? CacheSeconds { get; init; } + /// Reserved. No kind: builtin tool reads it; setting it fails the load. public ModelReference? Model { get; init; } diff --git a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json index 2f585c7b..0a0c9670 100644 --- a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json +++ b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json @@ -319,6 +319,11 @@ "request": { "$ref": "#/$defs/httpRequest" }, + "cacheSeconds": { + "type": "integer", + "minimum": 1, + "description": "kind: http or binding. Serve one answer again for the same arguments for this long. Only for a tool that reads and changes nothing." + }, "model": { "$ref": "#/$defs/modelRef", "description": "kind: builtin. Reserved: setting it fails the load. No built-in tool reads it." @@ -346,9 +351,10 @@ "uses" ], "properties": { - "parameters": false + "parameters": false, + "cacheSeconds": false }, - "$comment": "kind: builtin reads fixed argument names in C# (BuiltinToolSource). A document that overrides the schema makes the model fill boxes the C# never reads, so parameters is forbidden here." + "$comment": "kind: builtin reads fixed argument names in C# (BuiltinToolSource). A document that overrides the schema makes the model fill boxes the C# never reads, so parameters is forbidden here. A built-in acts on the conversation (files, shell, search), so cacheSeconds is forbidden too." } }, { @@ -399,7 +405,11 @@ "then": { "required": [ "agent" - ] + ], + "properties": { + "cacheSeconds": false + }, + "$comment": "A kind: agent tool runs a model. Its answer is not a function of its arguments, so cacheSeconds is forbidden." } }, { diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 17edeebd..901fd8ff 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -2342,3 +2342,9 @@ AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.DisposeAsync static readonly AgentCore.Application.Knowledge.HybridCachingKnowledgeRetrievalPort.DefaultLifetime -> System.TimeSpan AgentCore.Application.Llm.ChatRequestProperties const AgentCore.Application.Llm.ChatRequestProperties.ConversationId = "urn:agentcore:conversation-id" -> string! +AgentCore.Application.Configuration.Schema.ToolConfiguration.CacheSeconds.get -> int? +AgentCore.Application.Configuration.Schema.ToolConfiguration.CacheSeconds.init -> void +AgentCore.Application.Tools.CachedTool +AgentCore.Application.Tools.CachedTool.CachedTool(Microsoft.Extensions.AI.AIFunction! inner, Microsoft.Extensions.Caching.Hybrid.HybridCache! cache, System.TimeSpan lifetime) -> void +AgentCore.Application.Tools.Registry.ToolSourceContext.Cache.get -> Microsoft.Extensions.Caching.Hybrid.HybridCache? +AgentCore.Application.Tools.Registry.ToolSourceContext.Cache.init -> void diff --git a/src/AgentCore.Application/Tools/CachedTool.cs b/src/AgentCore.Application/Tools/CachedTool.cs new file mode 100644 index 00000000..1049cf7f --- /dev/null +++ b/src/AgentCore.Application/Tools/CachedTool.cs @@ -0,0 +1,74 @@ +using System.Text.Json.Nodes; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Caching.Hybrid; + +namespace AgentCore.Application.Tools; + +/// +/// One tool whose answer is served again, for a while, to a repeat of the same arguments. +/// +public sealed class CachedTool : DelegatingAIFunction +{ + private const string KeyPrefix = "agentcore:tool:"; + + private static readonly HybridCacheEntryOptions ReadOnly = new() + { + Flags = HybridCacheEntryFlags.DisableUnderlyingData, + }; + + private readonly HybridCache _cache; + + private readonly HybridCacheEntryOptions _write; + + /// Creates the wrapper. + /// The tool whose answers are kept. + /// The host's cache. + /// How long one answer is served again. It must be positive. + public CachedTool(AIFunction inner, HybridCache cache, TimeSpan lifetime) + : base(inner) + { + ArgumentNullException.ThrowIfNull(cache); + ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(lifetime, TimeSpan.Zero); + + _cache = cache; + _write = new HybridCacheEntryOptions { Expiration = lifetime }; + } + + /// + protected override async ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(arguments); + + var key = CacheKey(arguments); + + var kept = await _cache + .GetOrCreateAsync(key, static _ => ValueTask.FromResult(null), ReadOnly, cancellationToken: cancellationToken) + .ConfigureAwait(false); + + if (kept is not null) + { + return JsonNode.Parse(kept); + } + + var result = await base.InvokeCoreAsync(arguments, cancellationToken).ConfigureAwait(false); + + if (ToolResultJson.ToNode(result) is { } node && !ToolErrorResult.IsError(node)) + { + await _cache.SetAsync(key, node.ToJsonString(), _write, cancellationToken: cancellationToken).ConfigureAwait(false); + } + + return result; + } + + /// The key reads the tool name and the model's arguments, in a fixed order. The side channel () is not part of the call. + private string CacheKey(AIFunctionArguments arguments) + { + var ordered = arguments + .OrderBy(argument => argument.Key, StringComparer.Ordinal) + .Select(argument => new[] { argument.Key, argument.Value }) + .ToArray(); + + return KeyPrefix + AIJsonUtilities.HashDataToString([Name, ordered], AIJsonUtilities.DefaultOptions); + } +} diff --git a/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs b/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs index 12d0264c..ec5976c2 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs @@ -40,7 +40,7 @@ public static async ValueTask BuildAsync( var registrations = await source.ProvideAsync(context, cancellationToken).ConfigureAwait(false); foreach (var registration in registrations) { - Add(tools, registration); + Add(tools, registration, context); } } @@ -49,7 +49,7 @@ public static async ValueTask BuildAsync( return new ToolRegistry(tools); } - private static void Add(Dictionary> tools, ToolRegistration registration) + private static void Add(Dictionary> tools, ToolRegistration registration, ToolSourceContext context) { if (string.IsNullOrWhiteSpace(registration.Description)) { @@ -60,7 +60,7 @@ private static void Add(Dictionary> tools, ToolRegistration // Every resolve runs on the single startup flow that compiles the document. Nothing resolves // once the host is serving, so no request thread can race the Lazy. - Lazy lazy = new(() => Limit(registration), LazyThreadSafetyMode.None); + Lazy lazy = new(() => Cache(Limit(registration), registration.Id, context), LazyThreadSafetyMode.None); if (!tools.TryAdd(registration.Id, lazy)) { @@ -92,6 +92,24 @@ private static AITool Limit(ToolRegistration registration) + "the timeout off the registration, or serve the tool as an AIFunction."); } + /// Wraps one tool in the cache when its declaration asks for one and the host has one. + private static AITool Cache(AITool tool, string id, ToolSourceContext context) + { + var declared = context.Configuration.Tools.FirstOrDefault(entry => string.Equals(entry.Id, id, StringComparison.Ordinal)); + + if (declared?.CacheSeconds is not { } seconds || context.Cache is not { } cache) + { + return tool; + } + + return tool is AIFunction function + ? new CachedTool(function, cache, TimeSpan.FromSeconds(seconds)) + : throw ToolSourceError.Fail( + $"the tool '{id}' declares cacheSeconds, but the source built a {tool.GetType().Name} " + + "rather than an AIFunction, which has no call to cache. Take cacheSeconds off the " + + "declaration, or serve the tool as an AIFunction."); + } + private static void VerifyEveryDeclarationIsServed( Dictionary> tools, AgentCoreConfiguration configuration) { diff --git a/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs b/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs index 067b0a60..4c244a29 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs @@ -1,4 +1,5 @@ using AgentCore.Application.Configuration.Schema; +using Microsoft.Extensions.Caching.Hybrid; namespace AgentCore.Application.Tools.Registry; @@ -8,6 +9,12 @@ namespace AgentCore.Application.Tools.Registry; /// The loaded document. A source reads the declarations that are its own. public sealed record ToolSourceContext(AgentCoreConfiguration Configuration) { + /// + /// Gets the cache a cacheSeconds: tool reads through, or when + /// the host set none, in which case every call reaches the tool. + /// + public HybridCache? Cache { get; init; } + /// Every declaration of one kind, in document order. /// The kind this source serves. /// The declarations. A source that serves a kind nothing declares gets none. diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs index 4661503a..719666b0 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs @@ -67,7 +67,7 @@ internal static async ValueTask BuildAsync( } var registry = await ToolRegistryBuilder - .BuildAsync(sources, new ToolSourceContext(configuration), cancellationToken) + .BuildAsync(sources, new ToolSourceContext(configuration) { Cache = options.Cache }, cancellationToken) .ConfigureAwait(false); var servedIds = registry.Ids.ToHashSet(StringComparer.Ordinal); diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs index 2154cb73..8677cd48 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs @@ -647,6 +647,58 @@ public void ABuiltinDialOnAKindThatNeverReadsIt_FailsWithThePointerOfTheKey(stri Assert.Contains(failure.Errors, error => error.Pointer.Contains(name, StringComparison.Ordinal)); } + /// + /// A cached call runs nothing. A built-in acts on the conversation and a kind: agent tool + /// runs a model, so neither may declare cacheSeconds:; a GET or a reading host delegate may. + /// + [Theory] + [InlineData("builtin", "uses: web.search")] + [InlineData("agent", "agent: reviewer")] + public void CacheSecondsOnAKindWhoseAnswerIsNotAFunctionOfItsArguments_FailsWithThePointerOfTheKey(string kind, string discriminatorField) + { + var document = "apiVersion: agentcore/v1\n" + + "agents:\n" + + " items:\n" + + " - { id: reviewer, instructions: \"ok\" }\n" + + "entries:\n" + + " main:\n" + + " agent: reviewer\n" + + "tools:\n" + + " - id: lookup\n" + + " kind: " + kind + "\n" + + " " + discriminatorField + "\n" + + " cacheSeconds: 60\n"; + + var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.Contains("cacheSeconds", StringComparison.Ordinal)); + } + + [Theory] + [InlineData("http", "request: { method: GET, url: \"https://example.test\" }")] + [InlineData("binding", "binds: host.lookup")] + public void CacheSecondsOnAToolThatReads_PassesCheckOne(string kind, string discriminatorField) + { + var document = "apiVersion: agentcore/v1\n" + + "agents:\n" + + " items:\n" + + " - { id: reviewer, instructions: \"ok\" }\n" + + "entries:\n" + + " main:\n" + + " agent: reviewer\n" + + "tools:\n" + + " - id: lookup\n" + + " kind: " + kind + "\n" + + " " + discriminatorField + "\n" + + " cacheSeconds: 60\n"; + + var parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); + + Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); + Assert.Equal(60, ConfigurationLoader.LoadYaml(document).Tools[0].CacheSeconds); + } + [Fact] public void ABuiltinToolWithNoParameters_PassesCheckOne() { diff --git a/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs b/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs new file mode 100644 index 00000000..c34089d6 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs @@ -0,0 +1,192 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Tools; +using AgentCore.Application.Tools.Registry; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Caching.Hybrid; +using Microsoft.Extensions.DependencyInjection; +using Xunit; + +namespace AgentCore.Application.Tests.Tools; + +/// +/// cacheSeconds: on a tool. A repeat of the same arguments must not reach the tool again; +/// different arguments must; a failure must never be served twice. +/// +public sealed class CachedToolTests +{ + private static CancellationToken Token => TestContext.Current.CancellationToken; + + private static HybridCache NewCache() + { + ServiceCollection services = new(); + services.AddHybridCache(); + return services.BuildServiceProvider().GetRequiredService(); + } + + [Fact] + public async Task ARepeatOfTheSameArguments_SkipsTheTool_AndReadsTheSameAnswer() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + var first = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + var second = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + + Assert.Equal(1, counter.Calls); + Assert.Equal(ToolResultJson.ToNode(first)!.ToJsonString(), ToolResultJson.ToNode(second)!.ToJsonString()); + } + + [Fact] + public async Task DifferentArguments_ReachTheTool() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "B2" }, Token); + + Assert.Equal(2, counter.Calls); + } + + [Fact] + public async Task TheOrderTheModelWroteTheArgumentsIn_DoesNotChangeTheKey() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1", ["region"] = "us" }, Token); + await tool.InvokeAsync(new AIFunctionArguments { ["region"] = "us", ["order"] = "A1" }, Token); + + Assert.Equal(1, counter.Calls); + } + + [Fact] + public async Task TheSideChannel_IsNotPartOfTheKey() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + await tool.InvokeAsync( + WithContext(new AIFunctionArguments { ["order"] = "A1" }, new Dictionary { ["turn"] = 2 }), + Token); + + Assert.Equal(1, counter.Calls); + } + + [Fact] + public async Task AFailure_IsNotServedTwice() + { + var calls = 0; + var flaky = AIFunctionFactory.Create( + (string order) => ++calls == 1 ? ToolErrorResult.Create("lookup", "down") : new JsonObject { ["status"] = "shipped" }, + "lookup", + "Looks up an order."); + CachedTool tool = new(flaky, NewCache(), TimeSpan.FromMinutes(5)); + + var first = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + var second = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + + Assert.True(ToolErrorResult.IsError(ToolResultJson.ToNode(first))); + Assert.Equal("shipped", ToolResultJson.ToNode(second)!["status"]!.GetValue()); + Assert.Equal(2, calls); + } + + [Fact] + public void TheWrapperShowsTheSameToolToTheModel() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromSeconds(1)); + + Assert.Equal(counter.Function.Name, tool.Name); + Assert.Equal(counter.Function.Description, tool.Description); + Assert.Equal(counter.Function.JsonSchema.GetRawText(), tool.JsonSchema.GetRawText()); + } + + [Fact] + public void ALifetimeOfNothing_IsRefused() + => Assert.Throws( + () => new CachedTool(new CountingTool().Function, NewCache(), TimeSpan.Zero)); + + // --------------------------------------------------------------------------------------------- + // The registry is what applies the cache, from the declaration and the host's cache. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ADeclarationWithCacheSeconds_ResolvesToACachedTool() + { + CountingTool counter = new(); + var registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("lookup", "d", () => counter.Function))], + new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup", CacheSeconds = 60 })) { Cache = NewCache() }, + Token); + + var tool = Assert.IsType(registry.Resolve("lookup")); + await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + + Assert.Equal(1, counter.Calls); + } + + [Fact] + public async Task ADeclarationWithCacheSeconds_ButAHostWithNoCache_ResolvesToTheToolItself() + { + var inner = new CountingTool().Function; + var registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("lookup", "d", () => inner))], + new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup", CacheSeconds = 60 })), + Token); + + Assert.Same(inner, registry.Resolve("lookup")); + } + + [Fact] + public async Task ADeclarationWithNoCacheSeconds_ResolvesToTheToolItself() + { + var inner = new CountingTool().Function; + var registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("lookup", "d", () => inner))], + new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup" })) { Cache = NewCache() }, + Token); + + Assert.Same(inner, registry.Resolve("lookup")); + } + + private static AIFunctionArguments WithContext(AIFunctionArguments arguments, IDictionary context) + { + arguments.Context = context; + return arguments; + } + + /// A tool that answers with the arguments it saw, and counts how often it ran. + private sealed class CountingTool + { + public int Calls { get; private set; } + + public AIFunction Function { get; } + + public CountingTool() + => Function = AIFunctionFactory.Create( + (string order, string? region = null) => + { + Calls++; + return new JsonObject { ["order"] = order, ["region"] = region, ["call"] = Calls }; + }, + "lookup", + "Looks up an order."); + } + + private sealed class StubSource(params ToolRegistration[] registrations) : Application.Ports.IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + => ValueTask.FromResult>(registrations); + } + + private static class Documents + { + public static AgentCoreConfiguration With(params ToolConfiguration[] tools) + => new() { ApiVersion = "agentcore/v1", Tools = tools, Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary() }; + } +} From 5f11cf61860b04a2ea7460e23f19e55b6003b655 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sun, 20 Sep 2026 17:45:10 -0600 Subject: [PATCH 4/8] feat(transcript): introduce TranscriptFloor and TranscriptWindow records for conversation management feat(transcript): add ViewMessage record to represent messages in compaction views refactor(transcript): change WithdrawnTurns to public for broader access refactor(conversation): delegate conversation operations to PostgresConversationWords for better separation of concerns feat(conversation): enhance PostgresConversationStore with new SQL commands for handling covers_up_to feat(database): update migration script to include covers_up_to column in conversation_message table feat(llm): add OpenAiContextWindows for managing OpenAI model context windows feat(llm): implement GetContextWindow method in OpenAiChatClientAdapter to retrieve context window size --- config/example.yaml | 21 +- .../Compilation/AgentCompaction.cs | 75 ------ .../Compilation/AgentCompilationContext.cs | 6 + .../AgentContextProviderCompiler.cs | 39 ++-- .../Compilation/ConfigurationCompiler.cs | 14 +- .../Schema/AgentsConfiguration.cs | 6 - .../Schema/CompactionConfiguration.cs | 64 ----- .../Schema/TitlerConfiguration.cs | 7 +- .../Schema/agentcore-v1.schema.json | 34 +-- .../Conversation/ChatConversationTitler.cs | 10 +- .../Conversation/Conversations.cs | 27 ++- .../Memory/InMemoryConversationClaims.cs | 29 +++ .../InMemoryConversationContinuations.cs | 27 +++ .../Memory/InMemoryConversationListing.cs | 39 ++++ .../Memory/InMemoryConversationStore.cs | 168 +++++--------- .../Memory/InMemoryConversationWords.cs | 164 +++++++++++++ .../Conversation/StoredConversation.cs | 11 +- src/AgentCore.Application/Diagnostics/Log.cs | 19 ++ .../Llm/CompositeChatClientFactory.cs | 24 +- .../Ports/IChatClientAdapter.cs | 9 + .../Ports/IChatClientFactory.cs | 10 + .../Ports/IConversationStore.cs | 40 +++- .../Ports/IConversations.cs | 19 +- .../PublicAPI.Unshipped.txt | 141 ++++++----- .../Compaction/CappedToolCallFormatter.cs | 68 ------ .../Runtime/Compaction/CompactionDefaults.cs | 17 ++ .../Runtime/Compaction/CompactionStages.cs | 13 ++ .../Compaction/CompactionStrategyFactory.cs | 79 ++++--- .../Runtime/Compaction/SummaryRowProvider.cs | 151 ++++++++++++ .../Compaction/ToolResultCapProvider.cs | 120 ++++++++++ .../ConversationSessionStateStore.cs | 42 +--- .../ConversationTranscriptLedger.cs | 72 ++++-- .../ConversationTurnCommit.cs | 56 +---- .../ConversationTurnRunner.cs | 110 ++++----- .../ConversationTurnStream.cs | 16 +- .../Runtime/TurnInvocation.cs | 6 +- .../AgentCoreChatHistoryProvider.cs | 142 ++++++------ .../Transcript/ConversationCut.cs | 6 + .../Transcript/ConversationGate.cs | 56 +++++ .../Transcript/ConversationMessage.cs | 10 +- .../Transcript/ConversationMessageDraft.cs | 6 +- .../Transcript/ConversationTranscript.cs | 173 ++++++++++++-- .../Transcript/TranscriptFloor.cs | 7 + .../Transcript/TranscriptWindow.cs | 24 ++ .../Transcript/ViewMessage.cs | 12 + .../Transcript/WithdrawnTurns.cs | 2 +- .../Postgres/PostgresConversationStore.cs | 152 ++---------- .../Postgres/PostgresConversationStoreSql.cs | 75 +++++- .../Postgres/PostgresConversationWords.cs | 219 ++++++++++++++++++ .../Postgres/Migrations/001_agentcore.sql | 138 +---------- .../Llm/OpenAI/OpenAiChatClientAdapter.cs | 8 + .../Llm/OpenAI/OpenAiContextWindows.cs | 45 ++++ .../PublicAPI.Unshipped.txt | 1 + 53 files changed, 1727 insertions(+), 1102 deletions(-) delete mode 100644 src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs delete mode 100644 src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs create mode 100644 src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs create mode 100644 src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs create mode 100644 src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs create mode 100644 src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs delete mode 100644 src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs create mode 100644 src/AgentCore.Application/Transcript/ConversationCut.cs create mode 100644 src/AgentCore.Application/Transcript/ConversationGate.cs create mode 100644 src/AgentCore.Application/Transcript/TranscriptFloor.cs create mode 100644 src/AgentCore.Application/Transcript/TranscriptWindow.cs create mode 100644 src/AgentCore.Application/Transcript/ViewMessage.cs create mode 100644 src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs create mode 100644 src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs diff --git a/config/example.yaml b/config/example.yaml index 365c85ab..5882b621 100644 --- a/config/example.yaml +++ b/config/example.yaml @@ -19,7 +19,7 @@ # 3. extractor the model call that fills the extractor slots # 4. guards named JSONLogic rules the stage machine tests # 5. tools what an agent may call -# 6. agents models, prompts, knowledge, compaction +# 6. agents models, prompts, knowledge # 7. entries what a caller reaches: a stage machine or one agent # 8. providers adapters: llm, conversation, speech, telephony, moderation, embeddings, knowledge, # telemetry @@ -227,7 +227,7 @@ tools: # ============================================================================================= -# 6. agents: models, prompts, knowledge, compaction +# 6. agents: models, prompts, knowledge # ============================================================================================= # # defaults: applies to every item. An item overrides a key by declaring it. @@ -269,23 +269,6 @@ agents: # whole corpus. knowledge: { mode: prefetch, limit: 5, citations: false } - # Bounds the conversation an agent carries. Every strategy is deterministic: the same messages - # give the same result. There is no summarization on purpose. A resumed conversation rebuilds from - # the replayed words, and a model-written summary would give one conversation two histories. - # strategy truncate | sliding_window | tool_result | context_window - # tool_result folds old function-tool groups into one short line each. - # context_window folds first, then truncates whole groups. - # trigger exactly ONE of tokens, messages, turns, groups. Zero or two is a load - # error. - # keep the newest groups the strategy never touches. - # foldResultChars how much of a tool result one fold keeps. - # There is no per-agent opt-out. An item with no block inherits this one. To compact some - # agents only, declare the block on those items instead of here. - # - # context_window, not tool_result, here: the analyst below carries search, a hosted tool. - # tool_result folds function tools only, so a hosted tool's results would grow for ever. - compaction: { strategy: context_window, trigger: { messages: 40 }, keep: 6, foldResultChars: 300 } - items: # Voice, scripted. One round trip, no source labels spoken. Inherit knowledge from defaults. - { id: greeter, instructions: "", tools: [] } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs b/src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs deleted file mode 100644 index 0393a7ae..00000000 --- a/src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs +++ /dev/null @@ -1,75 +0,0 @@ -using AgentCore.Application.Configuration.Schema; - -namespace AgentCore.Application.Configuration.Compilation; - -/// One agent's compaction: block, fully resolved. -/// The strategy to build. -/// The one condition that makes compaction run. -/// How many newest groups the strategy never touches. -/// How much of a tool result a fold carries forward. -public sealed record ResolvedCompaction( - CompactionStrategyKind Strategy, - CompactionTriggerConfiguration Trigger, - int Keep, - int FoldResultChars); - -/// -/// Composes one agent's compaction: block from agents.defaults.compaction and the -/// agent's own block, key by key. -/// -public static class AgentCompaction -{ - /// The strategy used when neither the agent nor the defaults name one. - public const CompactionStrategyKind DefaultStrategy = CompactionStrategyKind.ToolResult; - - /// The newest groups a strategy never touches, when nothing names a number. - public const int DefaultKeep = 4; - - /// - /// How much of a tool result a fold carries forward, when nothing names a number. Enough for - /// the model to recognise what a tool already returned, and not enough to refill the window. - /// - public const int DefaultFoldResultChars = 200; - - /// Composes one agent's resolved compaction settings. - /// The agents.defaults section, or . - /// The agent to resolve. - /// - /// The resolved settings, or when neither the defaults nor the agent - /// declares a compaction: block. - /// - /// The composed trigger names other than one condition. - public static ResolvedCompaction? Compose(AgentDefaults? defaults, AgentConfiguration agent) - { - ArgumentNullException.ThrowIfNull(agent); - - var own = agent.Compaction; - var shared = defaults?.Compaction; - - if (own is null && shared is null) - { - return null; - } - - var trigger = own?.Trigger ?? shared?.Trigger ?? new CompactionTriggerConfiguration(); - - var named = new int?[] { trigger.Tokens, trigger.Messages, trigger.Turns, trigger.Groups } - .Count(value => value is not null); - - if (named != 1) - { - // Zero would compact on every turn; two would leave the document silent about whether - // they are combined with All or Any. - throw new ArgumentException( - $"the agent '{agent.Id}' has a compaction trigger naming {named} conditions. It must " - + "name exactly one of tokens, messages, turns or groups.", - nameof(agent)); - } - - return new ResolvedCompaction( - own?.Strategy ?? shared?.Strategy ?? DefaultStrategy, - trigger, - own?.Keep ?? shared?.Keep ?? DefaultKeep, - own?.FoldResultChars ?? shared?.FoldResultChars ?? DefaultFoldResultChars); - } -} diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs b/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs index f4787b48..00d9a9f2 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs @@ -1,3 +1,4 @@ +using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Evaluation; using AgentCore.Application.Knowledge; @@ -87,4 +88,9 @@ public AgentCompilationContext(IChatClientFactory chatClients) /// references against, or to treat every such reference as unresolved. /// public ResolvedSecrets? Secrets { get; init; } + + /// + /// Gets or sets the compaction stages every agent runs. + /// + internal CompactionStages? Compaction { get; init; } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs index e1247b8e..fef13a5a 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs @@ -5,8 +5,9 @@ using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Runtime.Turn; using AgentCore.Application.Skills; +using AgentCore.Application.Transcript; using Microsoft.Agents.AI; -using Microsoft.Agents.AI.Compaction; + namespace AgentCore.Application.Configuration.Compilation; internal static class AgentContextProviderCompiler @@ -23,12 +24,14 @@ internal static class AgentContextProviderCompiler /// The compile-time seams. /// This agent's JSON pointer. /// Resolves an agents.items id to its compiled agent, or when undeclared. + /// Store 1, or on a row whose session carries no history and so has nothing to summarise. public static List Build( AgentsWalk walk, AgentConfiguration item, AgentCompilationContext context, string pointer, - Func resolve) + Func resolve, + AgentCoreChatHistoryProvider? history) { var defaults = walk.Defaults; List providers = []; @@ -45,29 +48,21 @@ public static List Build( providers.Add(SkillsProviderFactory.Create(RequireCatalog(item, context, pointer, "skills"), item.Skills, context.Loggers)); } - ResolvedCompaction? compaction; - try - { - compaction = AgentCompaction.Compose(defaults, item); - } - catch (ArgumentException exception) + var model = item.Model ?? defaults?.Model; + if (context.ChatClients.GetContextWindow(model) is not { } contextWindow) { throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "compaction"), "trigger"), - exception.Message); + ConfigurationError.AppendPointer(pointer, "model"), + $"the agent '{item.Id}' uses the model '{model?.Ref ?? "default"}' and its adapter " + + "reports no context window, so compaction cannot size itself. Add the model to the " + + "adapter's table."); } - if (compaction is { } resolved) - { - providers.Add(new ReaderContentFilterProvider()); - -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. - providers.Add(new CompactionProvider( - CompactionStrategyFactory.Create(resolved), - loggerFactory: context.Loggers)); -#pragma warning restore MAAI001 - } - + providers.Add(new ReaderContentFilterProvider()); + + var stages = context.Compaction ?? CompactionStrategyFactory.Create(context.ChatClients.GetChatClient(model), contextWindow); + providers.AddRange(CompactionStrategyFactory.BuildProviders(stages, history)); + AgentHarnessProviders.Add(providers, defaults, item, context, pointer, resolve, walk.Background); if (AgentKnowledge.Compose(defaults, item) is not { } composed) @@ -85,8 +80,6 @@ public static List Build( + $"{nameof(IKnowledgeRetrievalPort)}, or remove the knowledge: block."); } - // The document-level wiring, carried onto this agent's own resolved knowledge so the search - // side does not have to re-derive it. var knowledge = composed with { Clarification = walk.Clarification }; providers.Add(KnowledgeProviderFactory.Create( diff --git a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs index 65838511..ea0b1fa2 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs @@ -1,7 +1,7 @@ -using AgentCore.Application.Conversation.Memory; -using AgentCore.Application.Llm; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Llm; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Transcript; @@ -184,10 +184,6 @@ private static CompiledAgentSet BuildAgents( } } - // A kind: agent tool names another agents.items entry, so one agent may need a second one - // that this walk has not reached yet. The walk therefore resolves on demand instead of in - // declaration order, and it holds the agents it entered so a delegation loop becomes a - // compile error rather than a stack overflow. List path = []; AgentsWalk walk = new( @@ -207,8 +203,6 @@ private static CompiledAgentSet BuildAgents( { if (agents.TryGetValue(id, out var existing)) { - // Built once, then shared. A delegating agent reuses the inner agent and never - // compiles a second copy of it. See T44 and CompiledAgentRegistry. return existing; } @@ -234,8 +228,9 @@ private static CompiledAgentSet BuildAgents( var compiledTools = AgentToolCompiler.Build( item, item.Model ?? section.Defaults?.Model, tools, context, pointer, Resolve); - var providers = AgentContextProviderCompiler.Build(walk, item, context, pointer, Resolve); + var providers = AgentContextProviderCompiler.Build(walk, item, context, pointer, Resolve, history); harnessStateKeys.UnionWith(AgentHarnessProviders.StateKeysOf(providers)); + harnessStateKeys.UnionWith(AgentApproval.StateKeysFor(section.Defaults, item, compiledTools)); var built = new ChatClientAgent( @@ -261,6 +256,7 @@ private static CompiledAgentSet BuildAgents( var approved = AgentApproval.Apply(instrumented, section.Defaults, item); var looped = AgentHarnessProviders.ApplyLoop(approved, section.Defaults, item, pointer); + agents[id] = looped; return looped; } diff --git a/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs index 988985be..02dd5654 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs @@ -48,9 +48,6 @@ public sealed record AgentDefaults /// Gets the shared knowledge: block, or when the document declares none. public AgentKnowledgeConfiguration? Knowledge { get; init; } - /// Gets the shared compaction: block, or when the document declares none. - public CompactionConfiguration? Compaction { get; init; } - /// Gets whether agents inherit the todo tools, or to name nothing. public bool? Todos { get; init; } @@ -101,9 +98,6 @@ public sealed record AgentConfiguration /// Gets this agent's knowledge: block, or to inherit key by key. public AgentKnowledgeConfiguration? Knowledge { get; init; } - /// Gets this agent's compaction: block, or to inherit key by key. - public CompactionConfiguration? Compaction { get; init; } - /// Gets whether this agent gets the todo tools, or to inherit. public bool? Todos { get; init; } diff --git a/src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs deleted file mode 100644 index c47e2eb5..00000000 --- a/src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs +++ /dev/null @@ -1,64 +0,0 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// The strategies a compaction: block may name. -public enum CompactionStrategyKind -{ - /// - /// Folds old tool-call groups into one short line each. It folds only function tool calls — a - /// group built from and its result. A - /// provider-run tool, such as hosted web search, is not folded: its messages are not that - /// content type, so this strategy leaves them untouched. Use - /// for a conversation that mixes the two, since its truncate phase - /// drops whole groups regardless of what is inside them. - /// - ToolResult, - - /// Removes the oldest non-system groups. - Truncate, - - /// Removes the oldest user turns and everything that answered them. - SlidingWindow, - - /// - /// Folds tool results, then truncates. The name names the goal, not the mechanism: nothing here - /// reads the model's actual context window. The size this strategy holds to comes entirely from - /// this block's own and - /// . - /// - ContextWindow, -} - -/// When compaction runs. Exactly one member is set. -public sealed record CompactionTriggerConfiguration -{ - /// Gets the token count above which compaction runs. - public int? Tokens { get; init; } - - /// Gets the message count above which compaction runs. - public int? Messages { get; init; } - - /// Gets the turn count above which compaction runs. - public int? Turns { get; init; } - - /// Gets the group count above which compaction runs. - public int? Groups { get; init; } -} - -/// One agent's compaction: block, as the document writes it. -public sealed record CompactionConfiguration -{ - /// Gets the strategy, or to inherit. - public CompactionStrategyKind? Strategy { get; init; } - - /// Gets when compaction runs, or to inherit. - public CompactionTriggerConfiguration? Trigger { get; init; } - - /// Gets how many newest groups the strategy never touches, or null to inherit. - public int? Keep { get; init; } - - /// - /// Gets how many characters of each tool result a fold carries forward, or null to inherit. - /// only. - /// - public int? FoldResultChars { get; init; } -} diff --git a/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs index 952c3056..264e569f 100644 --- a/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs @@ -1,13 +1,8 @@ namespace AgentCore.Application.Configuration.Schema; /// -/// The conversation titler. It names a conversation from the first few messages of the conversation itself. +/// The conversation titler. It names a conversation from the newest messages of the conversation itself. /// -/// -/// The titler never speaks to the caller and writes nothing but the conversation's name. The block is -/// optional: a document that declares none leaves the titler on whichever providers.llm -/// entry the factory defaults to. -/// public sealed record TitlerConfiguration { /// Gets the model the titler conversations. diff --git a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json index 0a0c9670..0cc2dcf4 100644 --- a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json +++ b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json @@ -265,7 +265,7 @@ }, "titler": { "type": "object", - "description": "The model that names a conversation from its first few messages. The key is optional, and a document that omits it leaves the titler on the default providers.llm entry.", + "description": "The model that names a conversation from its newest messages. The key is optional, and a document that omits it leaves the titler on the default providers.llm entry.", "required": [ "model" ], @@ -659,9 +659,6 @@ "knowledge": { "$ref": "#/$defs/agentKnowledge" }, - "compaction": { - "$ref": "#/$defs/compaction" - }, "todos": { "type": "boolean", "description": "Whether agents inherit the todos tools." @@ -740,9 +737,6 @@ "knowledge": { "$ref": "#/$defs/agentKnowledge" }, - "compaction": { - "$ref": "#/$defs/compaction" - }, "todos": { "type": "boolean", "description": "The agent gets the todos tools (TodoProvider)." @@ -804,32 +798,6 @@ } } }, - "compaction": { - "type": ["object", "null"], - "description": "Decision 3: no strategy here calls a model. A resumed conversation rebuilds a new session and re-derives from the replayed words, so a strategy that called a model would give one conversation two histories.", - "additionalProperties": false, - "properties": { - "strategy": { - "type": "string", - "enum": ["tool_result", "truncate", "sliding_window", "context_window"] - }, - "trigger": { - "type": "object", - "additionalProperties": false, - "minProperties": 1, - "maxProperties": 1, - "description": "Exactly one condition. Zero would compact on every turn; two would leave the document silent about whether they are combined with All or Any.", - "properties": { - "tokens": { "type": "integer", "minimum": 1 }, - "messages": { "type": "integer", "minimum": 1 }, - "turns": { "type": "integer", "minimum": 1 }, - "groups": { "type": "integer", "minimum": 1 } - } - }, - "keep": { "type": "integer", "minimum": 0 }, - "foldResultChars": { "type": "integer", "minimum": 1 } - } - }, "agentStore": { "type": "string", "enum": [ diff --git a/src/AgentCore.Application/Conversation/ChatConversationTitler.cs b/src/AgentCore.Application/Conversation/ChatConversationTitler.cs index fd53e76e..c3e4b3fd 100644 --- a/src/AgentCore.Application/Conversation/ChatConversationTitler.cs +++ b/src/AgentCore.Application/Conversation/ChatConversationTitler.cs @@ -1,6 +1,7 @@ using System.Runtime.CompilerServices; using System.Text; using AgentCore.Application.Ports; +using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; namespace AgentCore.Application.Conversation; @@ -10,9 +11,6 @@ namespace AgentCore.Application.Conversation; /// The model that writes it. public sealed class ChatConversationTitler(IConversationStore conversations, IChatClient client) : IConversationTitler { - // Messages and not turns: one turn writes several when tools are called. A six-word title does - // not improve for having read the whole conversation, and the whole conversation is what the prompt would be - // charged for. The cap holds for a caller's messages too, which arrive unbounded. private const int MaxMessages = 6; // A system message @@ -31,18 +29,18 @@ public IAsyncEnumerable GenerateAsync( return GenerateCoreAsync(conversationId, cancellationToken); } - /// Reads the conversation's messages and streams the title writes. + /// Reads the conversation's newest messages and streams the title writes. private async IAsyncEnumerable GenerateCoreAsync( string conversationId, [EnumeratorCancellation] CancellationToken cancellationToken) { - var rows = await conversations.ReadAsync(conversationId, cancellationToken).ConfigureAwait(false); + var rows = await conversations.ReadWindowAsync(conversationId, new TranscriptWindow(null, MaxMessages), cancellationToken).ConfigureAwait(false); if (rows.Count == 0) { yield break; } - await foreach (var piece in NameAsync(conversationId, rows.Select(row => row.Content), cancellationToken) + await foreach (var piece in NameAsync(conversationId, rows.TakeLast(MaxMessages).Select(row => row.Content), cancellationToken) .ConfigureAwait(false)) { yield return piece; diff --git a/src/AgentCore.Application/Conversation/Conversations.cs b/src/AgentCore.Application/Conversation/Conversations.cs index 21340dd2..fb8ac666 100644 --- a/src/AgentCore.Application/Conversation/Conversations.cs +++ b/src/AgentCore.Application/Conversation/Conversations.cs @@ -33,7 +33,8 @@ public Conversations(IConversationStore conversations, IBlobStore? blobs) public IConversationStore Store => _conversations; /// - public async ValueTask LoadAsync(string conversationId, CancellationToken cancellationToken = default) + public async ValueTask LoadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) { ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); @@ -44,10 +45,16 @@ public Conversations(IConversationStore conversations, IBlobStore? blobs) return null; } - var messages = await _conversations.ReadAsync(conversationId, cancellationToken).ConfigureAwait(false); + var messages = await _conversations.ReadWindowAsync(conversationId, window, cancellationToken).ConfigureAwait(false); + var files = await LinkFilesAsync(conversationId, messages.Select(message => message.Content), cancellationToken).ConfigureAwait(false); - return new StoredConversation(record, messages, files); + var turns = messages.Select(message => message.TurnIndex).Distinct().Count(); + + return new StoredConversation(record, messages, files) + { + OlderBefore = turns == window.Turns ? messages.Min(message => message.TurnIndex) : null, + }; } /// Links every published file the messages carry and the store kept, each name once, in first-seen order. @@ -162,11 +169,19 @@ public ValueTask RewriteAsync(string conversationId, string messageId, ChatMessa => _conversations.RewriteAsync(conversationId, messageId, content, cancellationToken); /// - public ValueTask> ReadAsync(string conversationId, CancellationToken cancellationToken = default) - => _conversations.ReadAsync(conversationId, cancellationToken); + public ValueTask> ReadForSessionAsync(string conversationId, CancellationToken cancellationToken = default) + => _conversations.ReadForSessionAsync(conversationId, cancellationToken); + + /// + public ValueTask> ReadWindowAsync(string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + => _conversations.ReadWindowAsync(conversationId, window, cancellationToken); + + /// + public ValueTask OrdinalOfAsync(string conversationId, string messageId, CancellationToken cancellationToken = default) + => _conversations.OrdinalOfAsync(conversationId, messageId, cancellationToken); /// - public ValueTask TruncateAsync(string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + public ValueTask TruncateAsync(string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) => _conversations.TruncateAsync(conversationId, fromOrdinal, cancellationToken); /// diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs new file mode 100644 index 00000000..c8ef8980 --- /dev/null +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs @@ -0,0 +1,29 @@ +namespace AgentCore.Application.Conversation.Memory; + +/// +/// Which principal may see which conversation, held beside the in-memory store's conversations. Every +/// member runs under the owning store's lock; nothing here takes one. +/// +internal sealed class InMemoryConversationClaims +{ + private readonly HashSet<(string ConversationId, string PrincipalKey)> _claims = []; + + /// Gives a principal a claim on a conversation. + /// The conversation to claim. + /// The opaque key that claims it. + public void Attach(string conversationId, string principalKey) => _claims.Add((conversationId, principalKey)); + + /// Takes a principal's claim off a conversation. + /// The conversation to unclaim. + /// The key to remove. + public void Detach(string conversationId, string principalKey) => _claims.Remove((conversationId, principalKey)); + + /// Reads the ids of the conversations one principal has claimed. + /// The opaque key to look up. + public IEnumerable ConversationsOf(string principalKey) + => _claims.Where(claim => claim.PrincipalKey == principalKey).Select(claim => claim.ConversationId); + + /// Withdraws every claim on a conversation. + /// The conversation that is going. + public void Forget(string conversationId) => _claims.RemoveWhere(claim => claim.ConversationId == conversationId); +} diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs new file mode 100644 index 00000000..dd98c73d --- /dev/null +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs @@ -0,0 +1,27 @@ +using System.Text.Json; + +namespace AgentCore.Application.Conversation.Memory; + +/// +/// One serialized agent session per continuation id, held beside the in-memory store's conversations. +/// Every member runs under the owning store's lock; nothing here takes one. +/// +internal sealed class InMemoryConversationContinuations +{ + private readonly Dictionary _envelopes = []; + + /// Files one session envelope under one continuation id, replacing any envelope already there. + /// The continuation id: a conversation id or a response id. + /// The serialized session, as the agent wrote it. + public void Save(string continuationId, JsonElement envelope) => _envelopes[continuationId] = envelope.Clone(); + + /// Reads the envelope one continuation id names. + /// The continuation id to look up. + /// The envelope, or when nothing is filed under that id. + public JsonElement? Get(string continuationId) + => _envelopes.TryGetValue(continuationId, out var envelope) ? envelope : null; + + /// Withdraws whatever one continuation id names, if anything. + /// The continuation id to forget. + public void Forget(string continuationId) => _envelopes.Remove(continuationId); +} diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs new file mode 100644 index 00000000..8f17582a --- /dev/null +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs @@ -0,0 +1,39 @@ +namespace AgentCore.Application.Conversation.Memory; + +/// How the in-memory store ranks and pages one principal's conversations. +internal static class InMemoryConversationListing +{ + /// Takes one page of conversations, most recently active first. + /// Every conversation the principal has a claim on. + /// A cursor from an earlier page, or for the first. + /// How many rows this page may hold. + /// The one status to return, or for every status. + /// The page, and a cursor when a following page exists. + public static ConversationPage Page( + IEnumerable claimed, string? after, int limit, ConversationStatus? status) + { + var hasCursor = ConversationCursor.TryDecode(after, out var sortAt, out var cursorId); + + var ordered = claimed + .Where(conversation => status is null || conversation.Status == status) + .Where(conversation => !hasCursor + || SortValue(conversation) < sortAt + || (SortValue(conversation) == sortAt + && string.CompareOrdinal(conversation.ConversationId, cursorId) < 0)) + .OrderByDescending(SortValue) + .ThenByDescending(conversation => conversation.ConversationId, StringComparer.Ordinal) + .Take(limit) + .ToList(); + + var next = ordered.Count == limit + ? ConversationCursor.Encode(SortValue(ordered[^1]), ordered[^1].ConversationId) + : null; + + return new ConversationPage(ordered, next); + } + + /// The clock a conversation is ranked by: its last message, or its making when it holds none. + /// The conversation to rank. + public static DateTimeOffset SortValue(ConversationRecord conversation) + => conversation.LastMessageAt ?? conversation.CreatedAt; +} diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs index d3563838..9bbe33fa 100644 --- a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs @@ -12,18 +12,14 @@ public sealed class InMemoryConversationStore : IConversationStore private readonly Dictionary _conversations = []; - private readonly Dictionary<(string ConversationId, int Ordinal), ConversationMessage> _rows = []; + private readonly InMemoryConversationWords _words = new(); /// The resume blob of each conversation, beside the row rather than on it. private readonly Dictionary _state = []; - /// The next free ordinal of each conversation. Never rewound, even when its words are. - private readonly Dictionary _nextOrdinal = []; + private readonly InMemoryConversationClaims _claims = new(); - private readonly HashSet<(string ConversationId, string PrincipalKey)> _claims = []; - - /// One serialized agent session per continuation id, beside the conversations. - private readonly Dictionary _continuations = []; + private readonly InMemoryConversationContinuations _continuations = new(); private readonly TimeProvider _time; @@ -48,7 +44,7 @@ public ValueTask CreateAsync(string conversationId, Cancella return ValueTask.FromResult(existing with { State = _state.GetValueOrDefault(conversationId), - NextOrdinal = _nextOrdinal.GetValueOrDefault(conversationId), + NextOrdinal = _words.NextOrdinal(conversationId), }); } } @@ -67,7 +63,7 @@ public ValueTask CreateAsync(string conversationId, Cancella : conversation with { State = _state.GetValueOrDefault(conversationId), - NextOrdinal = _nextOrdinal.GetValueOrDefault(conversationId), + NextOrdinal = _words.NextOrdinal(conversationId), }); } } @@ -83,29 +79,14 @@ public ValueTask ListAsync( ArgumentNullException.ThrowIfNull(principalKey); ArgumentOutOfRangeException.ThrowIfNegativeOrZero(limit); - var hasCursor = ConversationCursor.TryDecode(after, out var sortAt, out var cursorId); - lock (_lock) { - var ordered = _claims - .Where(claim => claim.PrincipalKey == principalKey) - .Select(claim => _conversations.GetValueOrDefault(claim.ConversationId)) - .OfType() - .Where(conversation => status is null || conversation.Status == status) - .Where(conversation => !hasCursor - || SortValue(conversation) < sortAt - || (SortValue(conversation) == sortAt - && string.CompareOrdinal(conversation.ConversationId, cursorId) < 0)) - .OrderByDescending(SortValue) - .ThenByDescending(conversation => conversation.ConversationId, StringComparer.Ordinal) - .Take(limit) - .ToList(); - - var next = ordered.Count == limit - ? ConversationCursor.Encode(SortValue(ordered[^1]), ordered[^1].ConversationId) - : null; + var claimed = _claims + .ConversationsOf(principalKey) + .Select(_conversations.GetValueOrDefault) + .OfType(); - return ValueTask.FromResult(new ConversationPage(ordered, next)); + return ValueTask.FromResult(InMemoryConversationListing.Page(claimed, after, limit, status)); } } @@ -149,17 +130,10 @@ public ValueTask DeleteAsync(string conversationId, CancellationToken cancellati { ArgumentNullException.ThrowIfNull(conversationId); - _conversations.Remove(conversationId); - - _claims.RemoveWhere(claim => claim.ConversationId == conversationId); - - _state.Remove(conversationId); - - _nextOrdinal.Remove(conversationId); - - _continuations.Remove(conversationId); - - RemoveWords(conversationId); + lock (_lock) + { + Forget(conversationId); + } return default; } @@ -182,23 +156,13 @@ public ValueTask SweepAsync( // short in a durable backing, and this store has no transaction; honouring it here would // only make the caller loop for the same answer. var going = _conversations.Values - .Where(conversation => SortValue(conversation) < cutoff) + .Where(conversation => InMemoryConversationListing.SortValue(conversation) < cutoff) .Select(conversation => conversation.ConversationId) .ToList(); foreach (var conversationId in going) { - _conversations.Remove(conversationId); - - _claims.RemoveWhere(claim => claim.ConversationId == conversationId); - - _state.Remove(conversationId); - - _nextOrdinal.Remove(conversationId); - - _continuations.Remove(conversationId); - - RemoveWords(conversationId); + Forget(conversationId); } return ValueTask.FromResult(going.Count); @@ -215,7 +179,7 @@ public ValueTask AttachPrincipalAsync( lock (_lock) { - _claims.Add((conversationId, principalKey)); + _claims.Attach(conversationId, principalKey); } return default; @@ -230,7 +194,7 @@ public ValueTask DetachPrincipalAsync( lock (_lock) { - _claims.Remove((conversationId, principalKey)); + _claims.Detach(conversationId, principalKey); } return default; @@ -259,20 +223,7 @@ public ValueTask> AppendAsync( } var fallbackTurnIndex = _state.GetValueOrDefault(conversationId)?.NextTurnIndex ?? 0; - var first = _nextOrdinal.GetValueOrDefault(conversationId); - - var rows = new List(messages.Count); - for (var index = 0; index < messages.Count; index++) - { - var draft = messages[index]; - ConversationMessage row = new( - conversationId, first + index, draft.TurnIndex ?? fallbackTurnIndex, draft.Content, draft.MessageId); - - rows.Add(row); - _rows.Add((row.ConversationId, row.Ordinal), row); - } - - _nextOrdinal[conversationId] = first + messages.Count; + var rows = _words.Append(conversationId, messages, fallbackTurnIndex); var now = _time.GetUtcNow(); _conversations[conversationId] = conversation with { LastMessageAt = now }; @@ -282,7 +233,7 @@ public ValueTask> AppendAsync( _state[conversationId] = state; } - return ValueTask.FromResult>(rows); + return ValueTask.FromResult(rows); } } @@ -296,55 +247,58 @@ public ValueTask RewriteAsync( lock (_lock) { - foreach (var pair in _rows) - { - if (pair.Key.ConversationId != conversationId || pair.Value.MessageId != messageId) - { - continue; - } - - _rows[pair.Key] = pair.Value with { Content = content }; - break; - } + _words.Rewrite(conversationId, messageId, content); } return default; } /// - public ValueTask> ReadAsync( + public ValueTask> ReadForSessionAsync( string conversationId, CancellationToken cancellationToken = default) { ArgumentNullException.ThrowIfNull(conversationId); lock (_lock) { - IReadOnlyList rows = - [.. _rows.Values.Where(row => row.ConversationId == conversationId).OrderBy(row => row.Ordinal)]; + return ValueTask.FromResult(_words.ReadForSession(conversationId)); + } + } - return ValueTask.FromResult(rows); + /// + public ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + + lock (_lock) + { + return ValueTask.FromResult(_words.Read(conversationId, window)); } } /// - public ValueTask TruncateAsync( - string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + public ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) { ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); lock (_lock) { - var going = _rows.Keys - .Where(key => string.Equals(key.ConversationId, conversationId, StringComparison.Ordinal) - && key.Ordinal >= fromOrdinal) - .ToList(); + return ValueTask.FromResult(_words.OrdinalOf(conversationId, messageId)); + } + } - foreach (var key in going) - { - _rows.Remove(key); - } + /// + public ValueTask TruncateAsync( + string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - return ValueTask.FromResult(going.Count); + lock (_lock) + { + return ValueTask.FromResult(_words.Truncate(conversationId, fromOrdinal)); } } @@ -355,7 +309,7 @@ public ValueTask EraseAsync(string conversationId, CancellationToken cancel lock (_lock) { - return ValueTask.FromResult(RemoveWords(conversationId)); + return ValueTask.FromResult(_words.Erase(conversationId)); } } @@ -366,7 +320,7 @@ public ValueTask SaveContinuationAsync(string continuationId, JsonElement envelo lock (_lock) { - _continuations[continuationId] = envelope.Clone(); + _continuations.Save(continuationId, envelope); } return default; @@ -379,8 +333,7 @@ public ValueTask SaveContinuationAsync(string continuationId, JsonElement envelo lock (_lock) { - return ValueTask.FromResult( - _continuations.TryGetValue(continuationId, out var envelope) ? envelope : null); + return ValueTask.FromResult(_continuations.Get(continuationId)); } } @@ -391,23 +344,20 @@ public ValueTask DeleteContinuationAsync(string continuationId, CancellationToke lock (_lock) { - _continuations.Remove(continuationId); + _continuations.Forget(continuationId); } return default; } - private static DateTimeOffset SortValue(ConversationRecord conversation) => conversation.LastMessageAt ?? conversation.CreatedAt; - - private int RemoveWords(string conversationId) + /// Drops a conversation, its claims, its state, its continuation and its words. Runs under the lock. + private void Forget(string conversationId) { - var going = _rows.Keys.Where(key => key.ConversationId == conversationId).ToList(); - foreach (var key in going) - { - _rows.Remove(key); - } - - return going.Count; + _conversations.Remove(conversationId); + _claims.Forget(conversationId); + _state.Remove(conversationId); + _continuations.Forget(conversationId); + _words.Forget(conversationId); } private ValueTask Amend(string conversationId, Func amend) diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs new file mode 100644 index 00000000..e0a34ade --- /dev/null +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs @@ -0,0 +1,164 @@ +using AgentCore.Application.Ports; +using AgentCore.Application.Transcript; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Conversation.Memory; + +/// +/// The words of every conversation the in-memory store holds, by ordinal, and the next ordinal each +/// conversation will issue. Every member runs under the owning store's lock; nothing here takes one. +/// +internal sealed class InMemoryConversationWords +{ + private readonly Dictionary<(string ConversationId, int Ordinal), ConversationMessage> _rows = []; + + /// The next free ordinal of each conversation. Never rewound, even when its words are. + private readonly Dictionary _nextOrdinal = []; + + /// Reads the ordinal a conversation's next row will take. + /// The conversation to ask about. + /// The next free ordinal, or zero for a conversation that has never spoken. + public int NextOrdinal(string conversationId) => _nextOrdinal.GetValueOrDefault(conversationId); + + /// Numbers and keeps a turn's new rows. + /// The conversation the rows belong to. + /// The rows to keep, oldest first. + /// The turn a draft that names none is filed under. + /// The rows as kept, in the order given. + public IReadOnlyList Append( + string conversationId, IReadOnlyList drafts, int fallbackTurnIndex) + { + var first = NextOrdinal(conversationId); + + var rows = new List(drafts.Count); + for (var index = 0; index < drafts.Count; index++) + { + var draft = drafts[index]; + ConversationMessage row = new( + conversationId, first + index, draft.TurnIndex ?? fallbackTurnIndex, draft.Content, draft.MessageId) + { + CoversUpTo = draft.CoversUpTo, + }; + + rows.Add(row); + _rows.Add((row.ConversationId, row.Ordinal), row); + } + + _nextOrdinal[conversationId] = first + drafts.Count; + + return rows; + } + + /// Replaces one row's content in place, by the name the caller knows it by. + /// The conversation the row belongs to. + /// The row to rewrite. + /// What it now says. + public void Rewrite(string conversationId, string messageId, ChatMessage content) + { + foreach (var pair in _rows) + { + if (pair.Key.ConversationId != conversationId || pair.Value.MessageId != messageId) + { + continue; + } + + _rows[pair.Key] = pair.Value with { Content = content }; + break; + } + } + + private IReadOnlyList Read(string conversationId) + => [.. Said(conversationId).OrderBy(row => row.Ordinal)]; + + /// Reads one conversation as its session opens it: the newest summary, and every row above what it covers. + /// The conversation to read. + /// The rows, oldest ordinal first. + public IReadOnlyList ReadForSession(string conversationId) + { + var summary = Of(conversationId).Where(row => row.CoversUpTo is not null).MaxBy(row => row.Ordinal); + if (summary is not { CoversUpTo: { } covered }) + { + return Read(conversationId); + } + + return [.. Of(conversationId) + .Where(row => row.Ordinal > covered && (row.CoversUpTo is null || row.Ordinal == summary.Ordinal)) + .OrderBy(row => row.Ordinal)]; + } + + /// Reads the newest turns of one conversation before a given one, oldest row first. Summary rows are left out. + /// The conversation to read. + /// Which turns. + /// Every row of those turns. + public IReadOnlyList Read(string conversationId, TranscriptWindow window) + { + var rows = Said(conversationId).Where(row => window.Admits(row.TurnIndex)).ToList(); + + var kept = rows + .Select(row => row.TurnIndex) + .Distinct() + .OrderByDescending(turn => turn) + .Take(window.Turns) + .ToHashSet(); + + return [.. rows.Where(row => kept.Contains(row.TurnIndex)).OrderBy(row => row.Ordinal)]; + } + + /// Finds the ordinal of one row somebody said (). + /// The conversation to search. + /// The row to find. + /// The ordinal, or when no spoken row carries that id. + public int? OrdinalOf(string conversationId, string messageId) + => Said(conversationId).FirstOrDefault(row => string.Equals(row.MessageId, messageId, StringComparison.Ordinal))?.Ordinal; + + /// + /// Removes a conversation's rows from one ordinal onward. A summary row goes only when the cut + /// reaches a row it covers (). + /// + /// The conversation to cut. + /// The first ordinal to remove. It goes too. + /// How many rows went, and the span of turns they belonged to. + public ConversationCut Truncate(string conversationId, int fromOrdinal) + { + var spoken = Said(conversationId).Where(row => row.Ordinal >= fromOrdinal).Select(row => row.TurnIndex).ToList(); + WithdrawnTurns? turns = spoken.Count == 0 ? null : new(spoken.Min(), spoken.Max()); + + var rows = Remove(conversationId, row => row.Ordinal >= fromOrdinal && (row.CoversUpTo is null || row.CoversUpTo >= fromOrdinal)); + + return new(rows, turns); + } + + /// Removes every row of a conversation and keeps its next ordinal. + /// The conversation to quieten. + /// How many rows went. + public int Erase(string conversationId) => Remove(conversationId, static _ => true); + + /// Removes every row of a conversation and forgets its next ordinal. + /// The conversation that is going. + public void Forget(string conversationId) + { + _nextOrdinal.Remove(conversationId); + Erase(conversationId); + } + + private IEnumerable Of(string conversationId) + => _rows.Values.Where(row => string.Equals(row.ConversationId, conversationId, StringComparison.Ordinal)); + + private IEnumerable Said(string conversationId) + => Of(conversationId).Where(static row => row.CoversUpTo is null); + + private int Remove(string conversationId, Func going) + { + var keys = Of(conversationId) + .Where(going) + .Select(row => (row.ConversationId, row.Ordinal)) + .ToList(); + + foreach (var key in keys) + { + _rows.Remove(key); + } + + return keys.Count; + } +} diff --git a/src/AgentCore.Application/Conversation/StoredConversation.cs b/src/AgentCore.Application/Conversation/StoredConversation.cs index 1f976d38..7427e3a4 100644 --- a/src/AgentCore.Application/Conversation/StoredConversation.cs +++ b/src/AgentCore.Application/Conversation/StoredConversation.cs @@ -5,7 +5,7 @@ namespace AgentCore.Application.Conversation; /// One conversation as the stores hold it: ready for a browser, nothing left to join. /// The row. -/// Every stored message, oldest first. +/// The stored messages, oldest first: every one, or one window's worth. /// /// One link per file the messages name and the blob store kept, each name once, in first-seen order. /// The links expire; read them out at once rather than keeping this record around. @@ -13,4 +13,11 @@ namespace AgentCore.Application.Conversation; public sealed record StoredConversation( ConversationRecord Conversation, IReadOnlyList Messages, - IReadOnlyList Files); + IReadOnlyList Files) +{ + /// + /// Gets the turn to read the next older window before, or when + /// reaches the conversation's start — or holds the whole conversation. + /// + public int? OlderBefore { get; init; } +} diff --git a/src/AgentCore.Application/Diagnostics/Log.cs b/src/AgentCore.Application/Diagnostics/Log.cs index 8ac1ab75..e223c501 100644 --- a/src/AgentCore.Application/Diagnostics/Log.cs +++ b/src/AgentCore.Application/Diagnostics/Log.cs @@ -312,4 +312,23 @@ public static partial void KnowledgeScopeComposed( Level = LogLevel.Warning, Message = "The file '{Name}' of conversation {ConversationId} could not be published.")] public static partial void SandboxFileCaptureFailed(ILogger logger, string conversationId, string name, Exception exception); + + /// The compaction strategy threw after a turn committed, so the session keeps the view it had. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that committed. + /// The cause. + [LoggerMessage( + EventId = 26, + Level = LogLevel.Warning, + Message = "The transcript of conversation {ConversationId} could not be compacted before turn {TurnIndex}. " + + "The session keeps the view it had and tries again before the next turn.")] + public static partial void TranscriptCompactionFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); + + [LoggerMessage( + EventId = 27, + Level = LogLevel.Warning, + Message = "The compaction strategy of conversation {ConversationId} produced, before turn {TurnIndex}, a shape one summary row " + + "cannot stand for: not one new message over the oldest rows with the rest kept in order. The session keeps the view it had.")] + public static partial void TranscriptCompactionUnsupported(ILogger logger, string conversationId, int turnIndex); } diff --git a/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs b/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs index 53f7f6fd..af8e0863 100644 --- a/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs +++ b/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs @@ -99,11 +99,8 @@ public IChatClient GetChatClient(ModelReference? model) return _vendor[entry.As]; } - // The vendor client stays one for each 'as' name. Only the conversation settings differ, so the - // wrapper sits above the shared client rather than beside it. ConfigureOptions clones the - // caller's ChatOptions (or starts a new one) and never mutates them, which is the same - // semantic a hand-rolled wrapper used to reimplement. var key = entry.As + "|" + temperature.ToString("R", CultureInfo.InvariantCulture); + return _shaped.GetOrAdd( key, _ => _vendor[entry.As] @@ -136,17 +133,16 @@ public IChatClient GetChatClient(ModelReference? model) return adapter.ResolveHostedTool(marker, entry); } + /// + public int? GetContextWindow(ModelReference? model) + { + ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + + var entry = Resolve(model); + return _adapters.TryGetValue(entry.As, out var adapter) ? adapter.GetContextWindow(entry) : null; + } + /// Releases every client the adapters built. - /// - /// A shaped client is a view over a shared vendor client, not an owner of one: it holds no - /// resource of its own, and its own chains straight through - /// to the vendor client it wraps (that is how and the client - /// ConfigureOptions builds both work). Disposing the shaped clients here as well as the - /// vendor clients would therefore dispose a shared vendor client once for every shaped wrapper - /// built over it, plus once more directly - safe only by accident, and wrong the moment a vendor - /// client's Dispose is not idempotent. Only the vendor client is released; the shaped - /// dictionary is dropped without disposing what it held. - /// public void Dispose() { if (Interlocked.Exchange(ref _disposed, 1) == 1) diff --git a/src/AgentCore.Application/Ports/IChatClientAdapter.cs b/src/AgentCore.Application/Ports/IChatClientAdapter.cs index 21907ecd..a630e126 100644 --- a/src/AgentCore.Application/Ports/IChatClientAdapter.cs +++ b/src/AgentCore.Application/Ports/IChatClientAdapter.cs @@ -23,4 +23,13 @@ ValueTask CreateClientAsync( /// The providers.llm[] entry this adapter serves. /// The tool to hand the model, or when this vendor does not run it. AITool? ResolveHostedTool(AITool marker, LlmProviderConfiguration entry) => null; + + /// Reports the model's context window, in tokens. + /// The providers.llm[] entry this adapter serves. + /// + /// The window in tokens, or when this adapter does not know the model. + /// Compaction is always on, so the compiler refuses an agent whose model answers + /// . + /// + int? GetContextWindow(LlmProviderConfiguration entry) => null; } diff --git a/src/AgentCore.Application/Ports/IChatClientFactory.cs b/src/AgentCore.Application/Ports/IChatClientFactory.cs index f87dbf1e..dda0d7f6 100644 --- a/src/AgentCore.Application/Ports/IChatClientFactory.cs +++ b/src/AgentCore.Application/Ports/IChatClientFactory.cs @@ -21,4 +21,14 @@ public interface IChatClientFactory /// The reference, or for the factory's default entry. /// The tool to hand the model, or when the vendor behind it does not run it. AITool? ResolveHostedTool(AITool marker, ModelReference? model) => null; + + /// Reports the context window of the model one reference names, in tokens. + /// + /// The reference, or for the factory's default entry. + /// + /// + /// The window in tokens, or when the adapter behind that entry does not + /// know the model. + /// + int? GetContextWindow(ModelReference? model); } diff --git a/src/AgentCore.Application/Ports/IConversationStore.cs b/src/AgentCore.Application/Ports/IConversationStore.cs index 033c22ec..5a272a67 100644 --- a/src/AgentCore.Application/Ports/IConversationStore.cs +++ b/src/AgentCore.Application/Ports/IConversationStore.cs @@ -128,20 +128,48 @@ ValueTask RewriteAsync( ChatMessage content, CancellationToken cancellationToken = default); - /// Reads one whole conversation's words, oldest message first. + /// + /// Reads a conversation's words as its session opens them: the newest summary row, and every row + /// above what it covers. The rows a summary stands in for are not read. With no summary, every row. + /// This is the one read that returns a summary row. + /// + /// The conversation to read. + /// Cancels the read. + /// The rows, oldest ordinal first. The summary sits at its own ordinal, above the rows it covers. + ValueTask> ReadForSessionAsync( + string conversationId, + CancellationToken cancellationToken = default); + + /// Reads the newest turns of a conversation before a given one, oldest message first. Summary rows are left out. /// The conversation to read. + /// Which turns: how many, and before which. /// Cancels the read. - /// Every message of the conversation, or an empty list when it holds none. - ValueTask> ReadAsync( + /// Every message of those turns, or an empty list when none fall in the window. + ValueTask> ReadWindowAsync( string conversationId, + TranscriptWindow window, CancellationToken cancellationToken = default); - /// Withdraws the tail of a conversation's words, from one ordinal onward. + /// Finds the ordinal of one message somebody said. Summary rows are not found. + /// The conversation to search. + /// The message to find. + /// Cancels the read. + /// The ordinal, or when the conversation holds no such message. + ValueTask OrdinalOfAsync( + string conversationId, + string messageId, + CancellationToken cancellationToken = default); + + /// + /// Withdraws the tail of a conversation's words, from one ordinal onward. A summary row goes + /// only when the cut reaches a row it covers: written after the rows it stands for, its own + /// ordinal says nothing about where the cut falls. + /// /// The conversation to cut. /// The first ordinal to remove. It goes too. /// Cancels the delete. - /// How many messages went. - ValueTask TruncateAsync( + /// How many rows went, and the span of turns they belonged to. + ValueTask TruncateAsync( string conversationId, int fromOrdinal, CancellationToken cancellationToken = default); diff --git a/src/AgentCore.Application/Ports/IConversations.cs b/src/AgentCore.Application/Ports/IConversations.cs index 288da45d..0931d624 100644 --- a/src/AgentCore.Application/Ports/IConversations.cs +++ b/src/AgentCore.Application/Ports/IConversations.cs @@ -7,8 +7,10 @@ namespace AgentCore.Application.Ports; /// /// The door a host or a consumer reads and writes stored conversations through: rows, words, and the -/// files a conversation published, together. What the turn loop and the sweeper need beyond this stays -/// on , which is the adapter seam and not a consumer surface. +/// files a conversation published, together. Words are read a window of turns at a time and never +/// whole: a consumer that could read a whole conversation would, and a long one is a slow query and a +/// large body every time. What the turn loop and the sweeper need beyond this stays on +/// , which is the adapter seam and not a consumer surface. /// public interface IConversations { @@ -18,11 +20,15 @@ public interface IConversations /// ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default); - /// Reads one conversation whole: its row, its words, and a link to every file it kept. + /// Reads one window of a conversation: its row, the newest turns before a given one, and a link to every file those turns kept. /// The conversation to read. + /// Which turns: how many, and before which. /// Cancels the read. - /// The conversation, or when the store holds none under that id. - ValueTask LoadAsync(string conversationId, CancellationToken cancellationToken = default); + /// + /// The window, with set when an older one may exist, or + /// when the store holds no conversation under that id. + /// + ValueTask LoadWindowAsync(string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default); /// ValueTask ListAsync( @@ -52,9 +58,6 @@ ValueTask ListAsync( /// ValueTask AppendMessageAsync(string conversationId, ChatMessage message, CancellationToken cancellationToken = default); - /// - ValueTask> ReadAsync(string conversationId, CancellationToken cancellationToken = default); - /// ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default); diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 901fd8ff..bc66479b 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -138,7 +138,6 @@ AgentCore.Application.Conversation.Memory.InMemoryConversationStore.GetAsync(str AgentCore.Application.Conversation.Memory.InMemoryConversationStore.GetContinuationAsync(string! continuationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Memory.InMemoryConversationStore.InMemoryConversationStore(System.TimeProvider? timeProvider = null) -> void AgentCore.Application.Conversation.Memory.InMemoryConversationStore.ListAsync(string! principalKey, string? after, int limit, AgentCore.Application.Conversation.ConversationStatus? status = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Conversation.Memory.InMemoryConversationStore.ReadAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Conversation.Memory.InMemoryConversationStore.RenameAsync(string! conversationId, string! title, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Memory.InMemoryConversationStore.RewriteAsync(string! conversationId, string! messageId, Microsoft.Extensions.AI.ChatMessage! content, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Memory.InMemoryConversationStore.SaveContinuationAsync(string! continuationId, System.Text.Json.JsonElement envelope, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask @@ -146,8 +145,6 @@ AgentCore.Application.Conversation.Memory.InMemoryConversationStore.SetCustomAsy AgentCore.Application.Conversation.Memory.InMemoryConversationStore.SetExternalIdAsync(string! conversationId, string? externalId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Memory.InMemoryConversationStore.SetStatusAsync(string! conversationId, AgentCore.Application.Conversation.ConversationStatus status, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Memory.InMemoryConversationStore.SweepAsync(System.TimeSpan retention, int batchSize = 500, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Conversation.Memory.InMemoryConversationStore.TruncateAsync(string! conversationId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Configuration.Compilation.AgentCompaction AgentCore.Application.Configuration.Compilation.AgentCompilationContext AgentCore.Application.Configuration.Compilation.AgentCompilationContext.AgentCompilationContext(AgentCore.Application.Ports.IChatClientFactory! chatClients) -> void AgentCore.Application.Configuration.Compilation.AgentCompilationContext.ConversationStore.get -> AgentCore.Application.Ports.IConversationStore? @@ -208,19 +205,6 @@ AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardFa AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardFacets.init -> void AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardValue.get -> string? AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardValue.init -> void -AgentCore.Application.Configuration.Compilation.ResolvedCompaction -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.$() -> AgentCore.Application.Configuration.Compilation.ResolvedCompaction! -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Deconstruct(out AgentCore.Application.Configuration.Schema.CompactionStrategyKind Strategy, out AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! Trigger, out int Keep, out int FoldResultChars) -> void -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Equals(AgentCore.Application.Configuration.Compilation.ResolvedCompaction? other) -> bool -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.FoldResultChars.get -> int -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.FoldResultChars.init -> void -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Keep.get -> int -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Keep.init -> void -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.ResolvedCompaction(AgentCore.Application.Configuration.Schema.CompactionStrategyKind Strategy, AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! Trigger, int Keep, int FoldResultChars) -> void -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Strategy.get -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Strategy.init -> void -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Trigger.get -> AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! -AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Trigger.init -> void AgentCore.Application.Configuration.Compilation.ResolvedHarness AgentCore.Application.Configuration.Compilation.ResolvedHarness.$() -> AgentCore.Application.Configuration.Compilation.ResolvedHarness! AgentCore.Application.Configuration.Compilation.ResolvedHarness.Deconstruct(out bool Todos, out bool Mode, out bool Clock, out bool BaseInstructions) -> void @@ -313,8 +297,6 @@ AgentCore.Application.Configuration.Schema.AgentConfiguration.Approval.get -> Ag AgentCore.Application.Configuration.Schema.AgentConfiguration.Approval.init -> void AgentCore.Application.Configuration.Schema.AgentConfiguration.Background.get -> System.Collections.Generic.IReadOnlyList! AgentCore.Application.Configuration.Schema.AgentConfiguration.Background.init -> void -AgentCore.Application.Configuration.Schema.AgentConfiguration.Compaction.get -> AgentCore.Application.Configuration.Schema.CompactionConfiguration? -AgentCore.Application.Configuration.Schema.AgentConfiguration.Compaction.init -> void AgentCore.Application.Configuration.Schema.AgentConfiguration.Equals(AgentCore.Application.Configuration.Schema.AgentConfiguration? other) -> bool AgentCore.Application.Configuration.Schema.AgentConfiguration.Files.get -> AgentCore.Application.Configuration.Schema.AgentFilesConfiguration? AgentCore.Application.Configuration.Schema.AgentConfiguration.Files.init -> void @@ -379,8 +361,6 @@ AgentCore.Application.Configuration.Schema.AgentDefaults.$() -> AgentCore AgentCore.Application.Configuration.Schema.AgentDefaults.AgentDefaults() -> void AgentCore.Application.Configuration.Schema.AgentDefaults.Approval.get -> AgentCore.Application.Configuration.Schema.ApprovalConfiguration? AgentCore.Application.Configuration.Schema.AgentDefaults.Approval.init -> void -AgentCore.Application.Configuration.Schema.AgentDefaults.Compaction.get -> AgentCore.Application.Configuration.Schema.CompactionConfiguration? -AgentCore.Application.Configuration.Schema.AgentDefaults.Compaction.init -> void AgentCore.Application.Configuration.Schema.AgentDefaults.Equals(AgentCore.Application.Configuration.Schema.AgentDefaults? other) -> bool AgentCore.Application.Configuration.Schema.AgentDefaults.Instructions.get -> string? AgentCore.Application.Configuration.Schema.AgentDefaults.Instructions.init -> void @@ -446,35 +426,6 @@ AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.Kin AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.Kind.init -> void AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.MaxFrameBytes.get -> int? AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.MaxFrameBytes.init -> void -AgentCore.Application.Configuration.Schema.CompactionConfiguration -AgentCore.Application.Configuration.Schema.CompactionConfiguration.$() -> AgentCore.Application.Configuration.Schema.CompactionConfiguration! -AgentCore.Application.Configuration.Schema.CompactionConfiguration.CompactionConfiguration() -> void -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Equals(AgentCore.Application.Configuration.Schema.CompactionConfiguration? other) -> bool -AgentCore.Application.Configuration.Schema.CompactionConfiguration.FoldResultChars.get -> int? -AgentCore.Application.Configuration.Schema.CompactionConfiguration.FoldResultChars.init -> void -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Keep.get -> int? -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Keep.init -> void -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Strategy.get -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind? -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Strategy.init -> void -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Trigger.get -> AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? -AgentCore.Application.Configuration.Schema.CompactionConfiguration.Trigger.init -> void -AgentCore.Application.Configuration.Schema.CompactionStrategyKind -AgentCore.Application.Configuration.Schema.CompactionStrategyKind.ContextWindow = 3 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind -AgentCore.Application.Configuration.Schema.CompactionStrategyKind.SlidingWindow = 2 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind -AgentCore.Application.Configuration.Schema.CompactionStrategyKind.ToolResult = 0 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind -AgentCore.Application.Configuration.Schema.CompactionStrategyKind.Truncate = 1 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.$() -> AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.CompactionTriggerConfiguration() -> void -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Equals(AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? other) -> bool -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Groups.get -> int? -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Groups.init -> void -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Messages.get -> int? -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Messages.init -> void -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Tokens.get -> int? -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Tokens.init -> void -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Turns.get -> int? -AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Turns.init -> void AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.$() -> AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration! AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.Dimensions.get -> int? @@ -1072,6 +1023,7 @@ AgentCore.Application.Knowledge.SourceLocatorCitationFormatter.SourceLocatorCita AgentCore.Application.Llm.CompositeChatClientFactory AgentCore.Application.Llm.CompositeChatClientFactory.Dispose() -> void AgentCore.Application.Llm.CompositeChatClientFactory.GetChatClient(AgentCore.Application.Configuration.Schema.ModelReference? model) -> Microsoft.Extensions.AI.IChatClient! +AgentCore.Application.Llm.CompositeChatClientFactory.GetContextWindow(AgentCore.Application.Configuration.Schema.ModelReference? model) -> int? AgentCore.Application.Llm.CompositeChatClientFactory.ResolveHostedTool(Microsoft.Extensions.AI.AITool! marker, AgentCore.Application.Configuration.Schema.ModelReference? model) -> Microsoft.Extensions.AI.AITool? AgentCore.Application.Policy.StagePolicy AgentCore.Application.Policy.StagePolicy.Advance(System.Collections.Generic.IReadOnlyDictionary! state) -> string! @@ -1122,7 +1074,6 @@ AgentCore.Application.Ports.IConversationStore.EraseAsync(string! conversationId AgentCore.Application.Ports.IConversationStore.GetAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStore.GetContinuationAsync(string! continuationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStore.ListAsync(string! principalKey, string? after, int limit, AgentCore.Application.Conversation.ConversationStatus? status = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Ports.IConversationStore.ReadAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IConversationStore.RenameAsync(string! conversationId, string! title, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStore.RewriteAsync(string! conversationId, string! messageId, Microsoft.Extensions.AI.ChatMessage! content, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStore.SaveContinuationAsync(string! continuationId, System.Text.Json.JsonElement envelope, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask @@ -1130,7 +1081,6 @@ AgentCore.Application.Ports.IConversationStore.SetCustomAsync(string! conversati AgentCore.Application.Ports.IConversationStore.SetExternalIdAsync(string! conversationId, string? externalId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStore.SetStatusAsync(string! conversationId, AgentCore.Application.Conversation.ConversationStatus status, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStore.SweepAsync(System.TimeSpan retention, int batchSize = 500, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Ports.IConversationStore.TruncateAsync(string! conversationId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationStoreAdapter AgentCore.Application.Ports.IConversationStoreAdapter.OpenAsync(AgentCore.Application.Configuration.Schema.VendorProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversationTitler @@ -1138,9 +1088,11 @@ AgentCore.Application.Ports.IConversationTitler.GenerateAsync(string! conversati AgentCore.Application.Ports.IConversationTitler.GenerateFromAsync(string! conversationId, System.Collections.Generic.IReadOnlyList! messages, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable! AgentCore.Application.Ports.IChatClientAdapter AgentCore.Application.Ports.IChatClientAdapter.CreateClientAsync(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Ports.IChatClientAdapter.GetContextWindow(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry) -> int? AgentCore.Application.Ports.IChatClientAdapter.ResolveHostedTool(Microsoft.Extensions.AI.AITool! marker, AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry) -> Microsoft.Extensions.AI.AITool? AgentCore.Application.Ports.IChatClientFactory AgentCore.Application.Ports.IChatClientFactory.GetChatClient(AgentCore.Application.Configuration.Schema.ModelReference? model) -> Microsoft.Extensions.AI.IChatClient! +AgentCore.Application.Ports.IChatClientFactory.GetContextWindow(AgentCore.Application.Configuration.Schema.ModelReference? model) -> int? AgentCore.Application.Ports.IChatClientFactory.ResolveHostedTool(Microsoft.Extensions.AI.AITool! marker, AgentCore.Application.Configuration.Schema.ModelReference? model) -> Microsoft.Extensions.AI.AITool? AgentCore.Application.Ports.IConversationPort AgentCore.Application.Ports.IConversationPort.ConversationId.get -> string! @@ -1506,9 +1458,6 @@ const AgentCore.Application.Audit.QueuedAuditSink.DefaultBatchSize = 100 -> int const AgentCore.Application.Audit.QueuedAuditSink.DefaultCapacity = 10000 -> int const AgentCore.Application.Conversation.ConversationSessionState.CurrentVersion = 1 -> int const AgentCore.Application.Conversation.ConversationStoreFactory.MemoryKind = "memory" -> string! -const AgentCore.Application.Configuration.Compilation.AgentCompaction.DefaultFoldResultChars = 200 -> int -const AgentCore.Application.Configuration.Compilation.AgentCompaction.DefaultKeep = 4 -> int -const AgentCore.Application.Configuration.Compilation.AgentCompaction.DefaultStrategy = AgentCore.Application.Configuration.Schema.CompactionStrategyKind.ToolResult -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind const AgentCore.Application.Configuration.Compilation.AgentInstructions.Separator = "\n\n" -> string! const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultCitations = false -> bool const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultLimit = 5 -> int @@ -1608,9 +1557,6 @@ override AgentCore.Application.Conversation.ConversationSessionState.ToString() override AgentCore.Application.Configuration.Compilation.ResolvedClarification.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Compilation.ResolvedClarification.GetHashCode() -> int override AgentCore.Application.Configuration.Compilation.ResolvedClarification.ToString() -> string! -override AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Compilation.ResolvedCompaction.GetHashCode() -> int -override AgentCore.Application.Configuration.Compilation.ResolvedCompaction.ToString() -> string! override AgentCore.Application.Configuration.Compilation.ResolvedHarness.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Compilation.ResolvedHarness.GetHashCode() -> int override AgentCore.Application.Configuration.Compilation.ResolvedHarness.ToString() -> string! @@ -1656,12 +1602,6 @@ override AgentCore.Application.Configuration.Schema.ApprovalConfiguration.ToStri override AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.CompactionConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.CompactionConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.CompactionConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.ToString() -> string! override AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.ToString() -> string! @@ -1861,7 +1801,6 @@ static AgentCore.Application.Conversation.ConversationSessionState.operator ==(A static AgentCore.Application.Conversation.ConversationSpeechPairing.Validate(AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration! conversation, AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration! speech, AgentCore.Application.Ports.IConversationAdapter! selectedConversation) -> void static AgentCore.Application.Conversation.ConversationStateJson.Options.get -> System.Text.Json.JsonSerializerOptions! static AgentCore.Application.Conversation.ConversationStoreFactory.OpenAsync(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Collections.Generic.IReadOnlyList! adapters, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -static AgentCore.Application.Configuration.Compilation.AgentCompaction.Compose(AgentCore.Application.Configuration.Schema.AgentDefaults? defaults, AgentCore.Application.Configuration.Schema.AgentConfiguration! agent) -> AgentCore.Application.Configuration.Compilation.ResolvedCompaction? static AgentCore.Application.Configuration.Compilation.AgentHarness.Compose(AgentCore.Application.Configuration.Schema.AgentDefaults? defaults, AgentCore.Application.Configuration.Schema.AgentConfiguration! agent) -> AgentCore.Application.Configuration.Compilation.ResolvedHarness! static AgentCore.Application.Configuration.Compilation.AgentInstructions.Compose(AgentCore.Application.Configuration.Schema.AgentDefaults? defaults, AgentCore.Application.Configuration.Schema.AgentConfiguration! agent) -> string? static AgentCore.Application.Configuration.Compilation.AgentKnowledge.AllScoped(AgentCore.Application.Configuration.Schema.AgentsConfiguration! agents) -> bool @@ -1872,8 +1811,6 @@ static AgentCore.Application.Configuration.Compilation.ConfigurationCompiler.Com static AgentCore.Application.Configuration.Compilation.ResolvedClarification.From(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Compilation.ResolvedClarification! static AgentCore.Application.Configuration.Compilation.ResolvedClarification.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedClarification? left, AgentCore.Application.Configuration.Compilation.ResolvedClarification? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedClarification.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedClarification? left, AgentCore.Application.Configuration.Compilation.ResolvedClarification? right) -> bool -static AgentCore.Application.Configuration.Compilation.ResolvedCompaction.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedCompaction? left, AgentCore.Application.Configuration.Compilation.ResolvedCompaction? right) -> bool -static AgentCore.Application.Configuration.Compilation.ResolvedCompaction.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedCompaction? left, AgentCore.Application.Configuration.Compilation.ResolvedCompaction? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedHarness.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedHarness? left, AgentCore.Application.Configuration.Compilation.ResolvedHarness? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedHarness.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedHarness? left, AgentCore.Application.Configuration.Compilation.ResolvedHarness? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? left, AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? right) -> bool @@ -1918,10 +1855,6 @@ static AgentCore.Application.Configuration.Schema.ApprovalConfiguration.operator static AgentCore.Application.Configuration.Schema.ApprovalConfiguration.operator ==(AgentCore.Application.Configuration.Schema.ApprovalConfiguration? left, AgentCore.Application.Configuration.Schema.ApprovalConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.operator !=(AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration? left, AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration? left, AgentCore.Application.Configuration.Schema.ConversationProviderConfiguration? right) -> bool -static AgentCore.Application.Configuration.Schema.CompactionConfiguration.operator !=(AgentCore.Application.Configuration.Schema.CompactionConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionConfiguration? right) -> bool -static AgentCore.Application.Configuration.Schema.CompactionConfiguration.operator ==(AgentCore.Application.Configuration.Schema.CompactionConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionConfiguration? right) -> bool -static AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.operator !=(AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? right) -> bool -static AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.operator ==(AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.operator !=(AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? left, AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? left, AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.EntryConfiguration.operator !=(AgentCore.Application.Configuration.Schema.EntryConfiguration? left, AgentCore.Application.Configuration.Schema.EntryConfiguration? right) -> bool @@ -2234,7 +2167,6 @@ AgentCore.Application.Conversation.Conversations.GetAsync(string! conversationId AgentCore.Application.Conversation.Conversations.GetContinuationAsync(string! continuationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Conversations.LinkFilesAsync(string! conversationId, System.Collections.Generic.IEnumerable! messages, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! AgentCore.Application.Conversation.Conversations.ListAsync(string! principalKey, string? after, int limit, AgentCore.Application.Conversation.ConversationStatus? status = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Conversation.Conversations.ReadAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Conversation.Conversations.RenameAsync(string! conversationId, string! title, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Conversations.RewriteAsync(string! conversationId, string! messageId, Microsoft.Extensions.AI.ChatMessage! content, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Conversations.SaveContinuationAsync(string! continuationId, System.Text.Json.JsonElement envelope, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask @@ -2242,7 +2174,6 @@ AgentCore.Application.Conversation.Conversations.SetCustomAsync(string! conversa AgentCore.Application.Conversation.Conversations.SetExternalIdAsync(string! conversationId, string? externalId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Conversations.SetStatusAsync(string! conversationId, AgentCore.Application.Conversation.ConversationStatus status, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.Conversations.SweepAsync(System.TimeSpan retention, int batchSize = 500, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Conversation.Conversations.TruncateAsync(string! conversationId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask override AgentCore.Application.Blobs.FileLink.Equals(object? obj) -> bool override AgentCore.Application.Blobs.FileLink.GetHashCode() -> int override AgentCore.Application.Blobs.FileLink.ToString() -> string! @@ -2293,7 +2224,6 @@ AgentCore.Application.Configuration.Schema.ShellConfiguration.MemoryMb.get -> in AgentCore.Application.Configuration.Schema.ShellConfiguration.MemoryMb.init -> void AgentCore.Application.Configuration.Compilation.AgentCompilationContext.Secrets.get -> AgentCore.Application.Secrets.ResolvedSecrets? AgentCore.Application.Configuration.Compilation.AgentCompilationContext.Secrets.init -> void -AgentCore.Application.Conversation.Conversations.LoadAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Conversation.StoredConversation AgentCore.Application.Conversation.StoredConversation.Conversation.get -> AgentCore.Application.Conversation.ConversationRecord! AgentCore.Application.Conversation.StoredConversation.Conversation.init -> void @@ -2311,8 +2241,6 @@ AgentCore.Application.Ports.IConversations.DetachPrincipalAsync(string! conversa AgentCore.Application.Ports.IConversations.EraseAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversations.GetAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversations.ListAsync(string! principalKey, string? after, int limit, AgentCore.Application.Conversation.ConversationStatus? status = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Ports.IConversations.LoadAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Ports.IConversations.ReadAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IConversations.RenameAsync(string! conversationId, string! title, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversations.SetCustomAsync(string! conversationId, System.Text.Json.JsonElement? custom, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IConversations.SetExternalIdAsync(string! conversationId, string? externalId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask @@ -2348,3 +2276,66 @@ AgentCore.Application.Tools.CachedTool AgentCore.Application.Tools.CachedTool.CachedTool(Microsoft.Extensions.AI.AIFunction! inner, Microsoft.Extensions.Caching.Hybrid.HybridCache! cache, System.TimeSpan lifetime) -> void AgentCore.Application.Tools.Registry.ToolSourceContext.Cache.get -> Microsoft.Extensions.Caching.Hybrid.HybridCache? AgentCore.Application.Tools.Registry.ToolSourceContext.Cache.init -> void +~override AgentCore.Application.Transcript.TranscriptWindow.Equals(object obj) -> bool +~override AgentCore.Application.Transcript.TranscriptWindow.ToString() -> string +AgentCore.Application.Conversation.Conversations.LoadWindowAsync(string! conversationId, AgentCore.Application.Transcript.TranscriptWindow window, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Conversation.Conversations.ReadWindowAsync(string! conversationId, AgentCore.Application.Transcript.TranscriptWindow window, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Conversation.Memory.InMemoryConversationStore.ReadWindowAsync(string! conversationId, AgentCore.Application.Transcript.TranscriptWindow window, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Conversation.StoredConversation.OlderBefore.get -> int? +AgentCore.Application.Conversation.StoredConversation.OlderBefore.init -> void +AgentCore.Application.Ports.IConversations.LoadWindowAsync(string! conversationId, AgentCore.Application.Transcript.TranscriptWindow window, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Ports.IConversationStore.ReadWindowAsync(string! conversationId, AgentCore.Application.Transcript.TranscriptWindow window, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Transcript.TranscriptWindow +AgentCore.Application.Transcript.TranscriptWindow.Admits(int turnIndex) -> bool +AgentCore.Application.Transcript.TranscriptWindow.BeforeTurn.get -> int? +AgentCore.Application.Transcript.TranscriptWindow.BeforeTurn.init -> void +AgentCore.Application.Transcript.TranscriptWindow.Deconstruct(out int? BeforeTurn, out int Turns) -> void +AgentCore.Application.Transcript.TranscriptWindow.Equals(AgentCore.Application.Transcript.TranscriptWindow other) -> bool +AgentCore.Application.Transcript.TranscriptWindow.TranscriptWindow() -> void +AgentCore.Application.Transcript.TranscriptWindow.TranscriptWindow(int? BeforeTurn, int Turns) -> void +AgentCore.Application.Transcript.TranscriptWindow.Turns.get -> int +AgentCore.Application.Transcript.TranscriptWindow.Turns.init -> void +override AgentCore.Application.Transcript.TranscriptWindow.GetHashCode() -> int +static AgentCore.Application.Transcript.TranscriptWindow.operator ==(AgentCore.Application.Transcript.TranscriptWindow left, AgentCore.Application.Transcript.TranscriptWindow right) -> bool +static AgentCore.Application.Transcript.TranscriptWindow.operator !=(AgentCore.Application.Transcript.TranscriptWindow left, AgentCore.Application.Transcript.TranscriptWindow right) -> bool +AgentCore.Application.Conversation.Conversations.ReadForSessionAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Conversation.Memory.InMemoryConversationStore.ReadForSessionAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Ports.IConversationStore.ReadForSessionAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Transcript.ConversationMessage.CoversUpTo.get -> int? +AgentCore.Application.Transcript.ConversationMessage.CoversUpTo.init -> void +AgentCore.Application.Transcript.ConversationMessageDraft.CoversUpTo.get -> int? +AgentCore.Application.Transcript.ConversationMessageDraft.CoversUpTo.init -> void +~override AgentCore.Application.Transcript.ConversationCut.Equals(object obj) -> bool +~override AgentCore.Application.Transcript.ConversationCut.ToString() -> string +~override AgentCore.Application.Transcript.WithdrawnTurns.Equals(object obj) -> bool +~override AgentCore.Application.Transcript.WithdrawnTurns.ToString() -> string +AgentCore.Application.Conversation.Conversations.OrdinalOfAsync(string! conversationId, string! messageId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Conversation.Conversations.TruncateAsync(string! conversationId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Conversation.Memory.InMemoryConversationStore.OrdinalOfAsync(string! conversationId, string! messageId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Conversation.Memory.InMemoryConversationStore.TruncateAsync(string! conversationId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Ports.IConversationStore.OrdinalOfAsync(string! conversationId, string! messageId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Ports.IConversationStore.TruncateAsync(string! conversationId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Transcript.ConversationCut +AgentCore.Application.Transcript.ConversationCut.ConversationCut() -> void +AgentCore.Application.Transcript.ConversationCut.ConversationCut(int Rows, AgentCore.Application.Transcript.WithdrawnTurns? Turns) -> void +AgentCore.Application.Transcript.ConversationCut.Deconstruct(out int Rows, out AgentCore.Application.Transcript.WithdrawnTurns? Turns) -> void +AgentCore.Application.Transcript.ConversationCut.Equals(AgentCore.Application.Transcript.ConversationCut other) -> bool +AgentCore.Application.Transcript.ConversationCut.Rows.get -> int +AgentCore.Application.Transcript.ConversationCut.Rows.init -> void +AgentCore.Application.Transcript.ConversationCut.Turns.get -> AgentCore.Application.Transcript.WithdrawnTurns? +AgentCore.Application.Transcript.ConversationCut.Turns.init -> void +AgentCore.Application.Transcript.WithdrawnTurns +AgentCore.Application.Transcript.WithdrawnTurns.Deconstruct(out int First, out int Last) -> void +AgentCore.Application.Transcript.WithdrawnTurns.Equals(AgentCore.Application.Transcript.WithdrawnTurns other) -> bool +AgentCore.Application.Transcript.WithdrawnTurns.First.get -> int +AgentCore.Application.Transcript.WithdrawnTurns.First.init -> void +AgentCore.Application.Transcript.WithdrawnTurns.Last.get -> int +AgentCore.Application.Transcript.WithdrawnTurns.Last.init -> void +AgentCore.Application.Transcript.WithdrawnTurns.WithdrawnTurns() -> void +AgentCore.Application.Transcript.WithdrawnTurns.WithdrawnTurns(int First, int Last) -> void +override AgentCore.Application.Transcript.ConversationCut.GetHashCode() -> int +override AgentCore.Application.Transcript.WithdrawnTurns.GetHashCode() -> int +static AgentCore.Application.Transcript.ConversationCut.operator ==(AgentCore.Application.Transcript.ConversationCut left, AgentCore.Application.Transcript.ConversationCut right) -> bool +static AgentCore.Application.Transcript.ConversationCut.operator !=(AgentCore.Application.Transcript.ConversationCut left, AgentCore.Application.Transcript.ConversationCut right) -> bool +static AgentCore.Application.Transcript.WithdrawnTurns.operator ==(AgentCore.Application.Transcript.WithdrawnTurns left, AgentCore.Application.Transcript.WithdrawnTurns right) -> bool +static AgentCore.Application.Transcript.WithdrawnTurns.operator !=(AgentCore.Application.Transcript.WithdrawnTurns left, AgentCore.Application.Transcript.WithdrawnTurns right) -> bool diff --git a/src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs b/src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs deleted file mode 100644 index b7b863dd..00000000 --- a/src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs +++ /dev/null @@ -1,68 +0,0 @@ -using System.Text; -using Microsoft.Agents.AI.Compaction; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime.Compaction; - -#pragma warning disable MAAI001 // CompactionMessageGroup is the framework's own experimental surface. - -/// -/// Writes a folded tool-call group as the tool's name and the head of its result. -/// -internal static class CappedToolCallFormatter -{ - private const char Cut = '…'; - - /// Builds a formatter that carries at most of each result. - /// Characters of each tool result to keep. Must be positive. - /// The formatter, for ToolResultCompactionStrategy.ToolCallFormatter. - public static Func Create(int maxResultChars) - { - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxResultChars); - - return group => - { - ArgumentNullException.ThrowIfNull(group); - - var calls = group.Messages - .SelectMany(message => message.Contents.OfType()) - .ToList(); - - if (calls.Count == 0) - { - return string.Empty; - } - - // A repeated CallId is a duplicated tool result — a replayed transcript, or a provider - // that reused an id across parallel calls. MAF's own DefaultToolCallFormatter resolves - // that the same way: last one written wins. - var results = new Dictionary(StringComparer.Ordinal); - foreach (var result in group.Messages.SelectMany(message => message.Contents.OfType())) - { - results[result.CallId] = result.Result?.ToString() ?? string.Empty; - } - - StringBuilder written = new("[Tool Calls]"); - foreach (var call in calls) - { - written.Append('\n').Append(call.Name).Append(':'); - - if (!results.TryGetValue(call.CallId, out var result) || result.Length == 0) - { - continue; - } - - written.Append("\n - ").Append(result.AsSpan(0, Math.Min(result.Length, maxResultChars))); - - if (result.Length > maxResultChars) - { - written.Append(Cut); - } - } - - return written.ToString(); - }; - } -} - -#pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs new file mode 100644 index 00000000..b0d1b376 --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs @@ -0,0 +1,17 @@ +namespace AgentCore.Application.Runtime.Compaction; + +/// The fixed constants of the one compaction every agent runs. See D7, D9, D15. +internal static class CompactionDefaults +{ + /// Groups for the summary, turns for the cap. The newest ones a stage never touches. + public const int Keep = 4; + + /// Characters. What a capped tool result keeps. + public const int CapResultChars = 200; + + /// Fraction of the model's context window at which compaction fires. + public const double FireFraction = 0.75; + + /// Fraction of the model's context window the summary stops at. + public const double TargetFraction = 0.5; +} diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs new file mode 100644 index 00000000..6226ea8e --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs @@ -0,0 +1,13 @@ +using Microsoft.Agents.AI.Compaction; + +namespace AgentCore.Application.Runtime.Compaction; + +/// +/// What the two compaction providers of an agent are built from. They run one after the other in +/// the agent's provider chain: the cap first, so the summary reads short results and counts them. +/// +/// Cuts old tool results. No model call. +/// The strategy runs. One model call, its output stored as a row. +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +internal sealed record CompactionStages(ToolResultCapProvider Cap, CompactionStrategy Summary); +#pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs index b391ed16..eb0410fa 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs @@ -1,53 +1,60 @@ -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Transcript; +using Microsoft.Agents.AI; using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; namespace AgentCore.Application.Runtime.Compaction; /// -/// Builds the MAF compaction strategy one agent's resolved compaction: block names. +/// Builds the one fixed compaction every agent runs: cap old tool results, then summarise the +/// rest, sized off the model's own context window (D7, D9). The trigger-taking overload lets a +/// test size the same pair to fire on a handful of fixture messages. /// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. internal static class CompactionStrategyFactory { - /// Builds the strategy. - /// The agent's resolved block. - /// The strategy, ready for a . - public static CompactionStrategy Create(ResolvedCompaction settings) + /// Builds the stages off the window fractions. + /// The chat client the summary stage calls. This is the agent's own reply model. + /// The reply model's context window, in tokens. + /// A and a , on the same trigger. + /// is not positive. + public static CompactionStages Create(IChatClient summariser, int contextWindow) { - ArgumentNullException.ThrowIfNull(settings); + ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(contextWindow, 0); - var trigger = Trigger(settings.Trigger); - - return settings.Strategy switch - { - CompactionStrategyKind.Truncate => new TruncationCompactionStrategy(trigger, settings.Keep), - CompactionStrategyKind.SlidingWindow => new SlidingWindowCompactionStrategy(trigger, settings.Keep), - CompactionStrategyKind.ContextWindow => ContextWindow(settings), - _ => ToolResult(settings, trigger), - }; + return Create( + summariser, + CompactionTriggers.TokensExceed((int)(contextWindow * CompactionDefaults.FireFraction)), + CompactionTriggers.TokensBelow((int)(contextWindow * CompactionDefaults.TargetFraction))); } - private static ToolResultCompactionStrategy ToolResult(ResolvedCompaction settings, CompactionTrigger trigger) - => new(trigger, settings.Keep) - { - ToolCallFormatter = CappedToolCallFormatter.Create(settings.FoldResultChars), - }; + /// Builds the stages off explicit triggers. A test passes Always and Never here. + /// The chat client the summary stage calls. + /// When a stage applies, judged over everything bound for the model. + /// Where the summary stops. Only the summary stage reads this. + /// A and a , on the same trigger. + public static CompactionStages Create(IChatClient summariser, CompactionTrigger fire, CompactionTrigger target) + { + ArgumentNullException.ThrowIfNull(summariser); + ArgumentNullException.ThrowIfNull(fire); + ArgumentNullException.ThrowIfNull(target); - private static PipelineCompactionStrategy ContextWindow(ResolvedCompaction settings) - => new PipelineCompactionStrategy( - ToolResult(settings, Trigger(settings.Trigger)), - new TruncationCompactionStrategy(Trigger(settings.Trigger), settings.Keep)); + return new CompactionStages( + new ToolResultCapProvider(fire, CompactionDefaults.Keep, CompactionDefaults.CapResultChars), + new SummarizationCompactionStrategy(summariser, fire, CompactionDefaults.Keep, target: target)); + } - private static CompactionTrigger Trigger(CompactionTriggerConfiguration trigger) => trigger switch + /// Builds the providers in chain order: the cap always runs, the summary needs history to persist its row. + /// The cap provider and the strategy the summary provider runs. + /// Store 1, or when the session carries no history. + /// The cap, then the summary when there is somewhere to write it. + public static AIContextProvider[] BuildProviders(CompactionStages stages, AgentCoreChatHistoryProvider? history) { - { Tokens: { } tokens } => CompactionTriggers.TokensExceed(tokens), - { Messages: { } messages } => CompactionTriggers.MessagesExceed(messages), - { Turns: { } turns } => CompactionTriggers.TurnsExceed(turns), - { Groups: { } groups } => CompactionTriggers.GroupsExceed(groups), - _ => throw new ArgumentException( - "the trigger names no condition. AgentCompaction.Compose refuses this before it gets here.", - nameof(trigger)), - }; + ArgumentNullException.ThrowIfNull(stages); + + return history is null + ? [stages.Cap] + : [stages.Cap, new SummaryRowProvider(history, stages.Summary)]; + } } #pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs b/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs new file mode 100644 index 00000000..376f0957 --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs @@ -0,0 +1,151 @@ +using AgentCore.Application.Diagnostics; +using AgentCore.Application.Runtime.Turn; +using AgentCore.Application.Transcript; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging.Abstractions; + +namespace AgentCore.Application.Runtime.Compaction; + +/// +/// The persisted half of compaction. Runs in the provider chain after the tool-result cap, over the +/// rows before the newest turn, and hands the model the strategy's output: one summary message, then +/// the rows it kept. The summary lands in the transcript as a row that covers the rows it replaced +/// () before the request goes out, so the next +/// session opens on it and the summariser is never asked about those rows again. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +internal sealed class SummaryRowProvider : AIContextProvider +{ + private readonly AgentCoreChatHistoryProvider _history; + + private readonly CompactionStrategy _summary; + + /// Store 1, which says what a compaction may cover and takes the row. + /// The strategy that replaces the oldest messages with one summary. One model call. + public SummaryRowProvider(AgentCoreChatHistoryProvider history, CompactionStrategy summary) + { + ArgumentNullException.ThrowIfNull(history); + ArgumentNullException.ThrowIfNull(summary); + + _history = history; + _summary = summary; + } + + /// + protected override async ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(context); + + var input = context.AIContext; + if (input.Messages is null || context.Session is not { } session || _history.Floor(session) is not { } floor) + { + return input; + } + + var messages = input.Messages as IReadOnlyList ?? input.Messages.ToList(); + if (!Leads(floor.Messages, messages)) + { + return input; + } + + var turn = TurnRegistry.For(session); + var logger = turn?.Logger ?? NullLogger.Instance; + + // The stages before this one strip and cap by making new instances, so the view the + // strategy runs over is the model-bound prefix, not the floor's own messages; the floor + // lines up with it by index and lends it the ordinals. + var view = messages.Take(floor.Messages.Count).ToList(); + + try + { + var output = (await CompactionProvider.CompactAsync(_summary, view, logger, cancellationToken).ConfigureAwait(false)).ToList(); + + if (output.Count == view.Count && output.Zip(view).All(pair => ReferenceEquals(pair.First, pair.Second))) + { + return input; + } + + if (Kept(view, output) is not { } kept) + { + if (turn is not null) + { + Log.TranscriptCompactionUnsupported(logger, turn.ConversationId, turn.TurnIndex); + } + + return input; + } + + var coversUpTo = floor.Messages[kept - 1].LastOrdinal; + if (coversUpTo <= floor.CoversUpTo || !_history.Compact(session, output[0], coversUpTo, floor.Revision)) + { + return input; + } + + return new AIContext + { + Instructions = input.Instructions, + Messages = [output[0], .. messages.Skip(kept)], + Tools = input.Tools, + }; + } +#pragma warning disable CA1031 // A strategy that throws never ends a conversation: the session keeps the view it had. + catch (Exception exception) when (exception is not OperationCanceledException) +#pragma warning restore CA1031 + { + if (turn is not null) + { + Log.TranscriptCompactionFailed(logger, turn.ConversationId, turn.TurnIndex, exception); + } + + return input; + } + } + + /// Whether the floor's rows lead the model-bound list, id for id. + private static bool Leads(IReadOnlyList floor, IReadOnlyList messages) + { + if (floor.Count > messages.Count) + { + return false; + } + + for (var index = 0; index < floor.Count; index++) + { + if (!string.Equals(floor[index].Message.MessageId, messages[index].MessageId, StringComparison.Ordinal)) + { + return false; + } + } + + return true; + } + + /// + /// Reads the strategy's output as one new message over a prefix of the view, and names where the + /// kept tail starts. The output must be one new message, then the view from that index on, the + /// very instances in order; anything else is not a shape one summary row can stand for. + /// + /// The index of the first kept message, or . The view's count when nothing was kept. + private static int? Kept(List view, List output) + { + if (output.Count == 0 || output.Count > view.Count || view.Any(message => ReferenceEquals(message, output[0]))) + { + return null; + } + + var kept = view.Count - (output.Count - 1); + for (var index = 1; index < output.Count; index++) + { + if (!ReferenceEquals(output[index], view[kept + index - 1])) + { + return null; + } + } + + return kept; + } +} +#pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs b/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs new file mode 100644 index 00000000..960334da --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs @@ -0,0 +1,120 @@ +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime.Compaction; + +/// +/// The cheap half of compaction: once the words bound for the model pass the trigger, every tool +/// result older than the newest turns is cut to a fixed length. One message in, one message out, +/// same id, so the row numbers the summary stage reads survive. Nothing is stored; the cut is +/// re-made from the rows every turn, and it is the same cut every turn, so the prompt prefix the +/// model's cache keys on does not move. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +internal sealed class ToolResultCapProvider : AIContextProvider +{ + private const char Cut = '…'; + + private readonly CompactionTrigger _trigger; + + private readonly int _keepTurns; + + private readonly int _maxResultChars; + + /// When the cap applies, judged over everything bound for the model. + /// Turns. The newest turns whose results stay whole. A turn starts at a user message. + /// Characters. What a capped result keeps. + public ToolResultCapProvider(CompactionTrigger trigger, int keepTurns, int maxResultChars) + { + ArgumentNullException.ThrowIfNull(trigger); + ArgumentOutOfRangeException.ThrowIfNegative(keepTurns); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxResultChars); + + _trigger = trigger; + _keepTurns = keepTurns; + _maxResultChars = maxResultChars; + } + + /// + protected override ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(context); + + var input = context.AIContext; + if (input.Messages is null) + { + return new(input); + } + + var messages = input.Messages as IReadOnlyList ?? input.Messages.ToList(); + if (!_trigger(Measure(messages))) + { + return new(input); + } + + var capped = new List(messages.Count); + var kept = KeptFrom(messages); + for (var index = 0; index < messages.Count; index++) + { + capped.Add(index < kept ? Cap(messages[index]) : messages[index]); + } + + return new(new AIContext + { + Instructions = input.Instructions, + Messages = capped, + Tools = input.Tools, + }); + } + + /// + /// One group holding every message is enough for the token triggers, and it makes this stage + /// and the summary stage count the same way. + /// + private static CompactionMessageIndex Measure(IReadOnlyList messages) + { + CompactionMessageIndex index = new([]); + index.AddGroup(CompactionGroupKind.User, messages); + return index; + } + + /// The index of the first message of the newest kept turn, or the count when none is kept. + private int KeptFrom(IReadOnlyList messages) + { + var turns = 0; + for (var index = messages.Count - 1; index >= 0; index--) + { + if (messages[index].Role == ChatRole.User && ++turns == _keepTurns) + { + return index; + } + } + + return _keepTurns == 0 ? messages.Count : 0; + } + + private ChatMessage Cap(ChatMessage message) + { + if (message.Role != ChatRole.Tool || !message.Contents.OfType().Any(Long)) + { + return message; + } + + return new ChatMessage(message.Role, message.Contents.Select(content => content is FunctionResultContent result && Long(result) ? Cap(result) : content).ToList()) + { + AuthorName = message.AuthorName, + MessageId = message.MessageId, + CreatedAt = message.CreatedAt, + AdditionalProperties = message.AdditionalProperties, + }; + } + + private FunctionResultContent Cap(FunctionResultContent result) + => new(result.CallId, result.Result!.ToString()![.._maxResultChars] + Cut); + + private bool Long(FunctionResultContent result) + => result.Result?.ToString() is { } text && text.Length > _maxResultChars; +} +#pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs index 1f7e60cb..30517917 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs @@ -1,5 +1,5 @@ -using AgentCore.Application.Conversation; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Conversation; using AgentCore.Application.Runtime.Harness; namespace AgentCore.Application.Runtime; @@ -27,10 +27,6 @@ internal void Restore(ConversationSessionState stored) if (_session.Policy is null) { - // An entry with no policy: has no stage machine and no stage to hold, so the only - // stored stage it can honour is no stage at all. An id from a build whose entry still - // declared policy: would otherwise land in the reserved stage slot, where the guards - // and the audit chain read it as though a machine were holding it. if (stored.Stage.Length > 0) { refusedStage = $"the entry declares no policy, so the stage '{stored.Stage}' has nowhere to go."; @@ -43,16 +39,10 @@ internal void Restore(ConversationSessionState stored) if (refusedStage is null) { - // Both, and in this order. The machine is what picks the agent and what the next - // transition fires from; the reserved slot is what the guards and the audit chain read. - // Moving one without the other is worse than moving neither, because the conversation would - // then report a stage it was not actually running in. _session.Policy?.RestoreStage(stored.Stage); + _session.State.Stage = stored.Stage; - // Only on this branch. A stored 'true' was read off a terminal stage, so restoring it - // beside a stage that was refused would bring the conversation back only to have it turn every - // turn away — the one outcome this whole method exists to avoid. _session.IsComplete = stored.IsComplete; } else @@ -60,21 +50,14 @@ internal void Restore(ConversationSessionState stored) Dropped(refusedStage); } - // Before the slots, and unconditionally: the ask budget is per conversation, not per session, so a - // caller who dropped and reconnected must not buy a fresh maxAsks and hear every clarification - // over again. A refused stage does not refuse this — the questions were still asked. _session.Clarifications.RestoreSpent(stored.Clarifications); foreach (var slot in stored.Slots) { if (ReservedStateSlots.Contains(slot.Key)) { - // TryWrite throws on a reserved slot rather than answering false, and an exception - // here would escape OpenSessionAsync and refuse the conversation outright. Snapshot never - // writes one, but this blob is arbitrary JSON out of store 0 and a host hands one - // straight in through DeserializeSessionAsync, so the guard is the caller's and not - // the blob's. Dropped($"the slot '{slot.Key}' is reserved, and a reserved slot is never restored."); + continue; } @@ -83,9 +66,6 @@ internal void Restore(ConversationSessionState stored) continue; } - // TryWrite answers false for two kinds of reason that cost an operator different things - // to fix — a slot the document no longer declares, and a value its type or enum: gate - // now refuses — so the reason says which one happened rather than making them guess. Dropped( _session.State.Configuration.State.ContainsKey(slot.Key) ? $"the slot '{slot.Key}' no longer takes the value it was stored with." @@ -114,11 +94,6 @@ internal ConversationSessionState Snapshot() { if (_session.AgentSession is null && _session.Checkpoint is { } held) { - // Handed back by reference, where the branch below deep-clones through - // WrittenSlots(). Deliberate, and not the asymmetry it looks like: this value is the - // host's own object, arriving from Resume and going straight back out to the only - // caller that can reach this branch — the seam, which serializes it and drops it. A - // clone would defend the host against itself, and cost a copy of the slots to do it. return held; } } @@ -128,17 +103,9 @@ internal ConversationSessionState Snapshot() Stage = _session.State.Stage, IsComplete = _session.IsComplete, Slots = _session.State.WrittenSlots(), - - // The turn index this conversation has reached, which is already the NEXT one by the time the - // commit reads it. NextTurnIndex = _session.State.TurnIndex, - Clarifications = _session.Clarifications.Spent(), - Providers = HarnessSessionState.Capture(_session.AgentSession, _session.Compiled.HarnessStateKeys), - - // Turn-boundary workflow checkpoints on a graph row that reuses its session; every - // other conversation leaves this empty and keeps provider state in Providers above. WorkflowState = _session.GraphBlob, }; } @@ -148,9 +115,6 @@ internal void Resume(ConversationSessionState stored) { ArgumentNullException.ThrowIfNull(stored); - // One lock over the check and the write. The guard exists to catch a late hand-off, and a - // guard that read the session under the lock and then wrote the field outside it would be - // racing the very reader — OpenSessionAsync at the top of this file — that it guards. lock (_session.InterruptLock) { if (_session.AgentSession is not null) diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs index 29b77a92..0a1629ba 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs @@ -7,9 +7,6 @@ namespace AgentCore.Application.Runtime; -// The transcript half of the session (MAF history-provider seam): opening the session once, -// re-syncing it with store 0 before every later turn, draining writes, and naming approval -// answers. Reads and publishes the live session through the owning ConversationSession. internal sealed class ConversationTranscriptLedger { private readonly ConversationSession _session; @@ -42,11 +39,6 @@ internal async ValueTask OpenSessionAsync(CancellationToken cancel checkpoint = _session.Checkpoint; } - // One restore point for both sources, and store 0 outranks the host's checkpoint outright - // rather than merging with it. Store 0's blob is written in the same batch as the turn's - // words, so its state and store 1's words are of one moment and cannot disagree; a - // checkpoint's state beside store 1's words can be of two. So the checkpoint decides only a - // conversation store 0 does not know, or knows without state. var stored = record.State ?? checkpoint; AgentSession session; @@ -61,9 +53,6 @@ internal async ValueTask OpenSessionAsync(CancellationToken cancel { session = new ConversationHistorySession(); - // Rows 1 and 2 restore provider state onto their long-lived session above. A graph - // row instead keeps one workflow session for the whole conversation: MAF restores each - // participant's provider state from its checkpoints whenever a turn runs on it. if (_session.ReusesGraphSession) { _session.GraphSession = stored is { Version: ConversationSessionState.CurrentVersion, WorkflowState: { } blob } @@ -74,7 +63,7 @@ internal async ValueTask OpenSessionAsync(CancellationToken cancel IReadOnlyList spoken = record.LastMessageAt is null ? [] - : await _session.Compiled.ConversationStore.ReadAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); + : await _session.Compiled.ConversationStore.ReadForSessionAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); lock (_session.InterruptLock) { @@ -89,9 +78,6 @@ internal async ValueTask OpenSessionAsync(CancellationToken cancel _session.Events.RaiseDroppedTranscriptWrite, new TranscriptMarks(record.NextOrdinal, stored?.NextTurnIndex ?? 0)); - // After the constructor, never inside it. The const writer has already run by now, - // so a slot a previous session filled lands on top of the const default rather than - // under it — and the record it is read from only exists after an async store read. if (stored is { } s) { _session.States.Restore(s); @@ -114,16 +100,15 @@ private async ValueTask ResyncTranscriptAsync(AgentSession opened, CancellationT try { - var refreshed = await _session.Compiled.ConversationStore.GetAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false) - ?? throw new InvalidOperationException( - $"Store 0 holds no conversation '{_session.ConversationId}' for its own session to resync against."); + var refreshed = await RecordAsync("resync against", cancellationToken).ConfigureAwait(false); if (refreshed.NextOrdinal == _session.History.NextOrdinal(opened)) { return; } - var rows = await _session.Compiled.ConversationStore.ReadAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); + var rows = await _session.Compiled.ConversationStore.ReadForSessionAsync( + _session.ConversationId, cancellationToken).ConfigureAwait(false); _session.History.Resync(opened, rows, refreshed.NextOrdinal); } @@ -136,6 +121,55 @@ private async ValueTask ResyncTranscriptAsync(AgentSession opened, CancellationT } } + /// + /// Cuts an edit that reaches under the summary: the parent is a row the summary stands in for, + /// or the edit takes the whole conversation. The caller asks + /// first and comes here when it says no. + /// + /// The session of this conversation. + /// The message the edit hangs off, or for the whole conversation. + /// Cancels the cut. + /// The turns the cut withdrew, or when nothing went. + internal async ValueTask CutUnderSummaryAsync( + AgentSession opened, string? parentMessageId, CancellationToken cancellationToken) + { + var store = _session.Compiled.ConversationStore; + + await _session.History.DrainAsync(opened).ConfigureAwait(false); + + int from; + if (parentMessageId is null) + { + from = 0; + } + else if (await store.OrdinalOfAsync(_session.ConversationId, parentMessageId, cancellationToken).ConfigureAwait(false) is { } parent) + { + from = parent + 1; + } + else + { + return null; + } + + var cut = await store.TruncateAsync(_session.ConversationId, from, cancellationToken).ConfigureAwait(false); + Log.ConversationTruncated(_session.Logger, _session.ConversationId, from, _session.State.TurnIndex); + + var refreshed = await RecordAsync("edit", cancellationToken).ConfigureAwait(false); + var rows = await store.ReadForSessionAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); + + _session.History.Resync(opened, rows, refreshed.NextOrdinal); + + return cut.Turns; + } + + /// Store 0's record of this conversation, which must exist for a session that already opened it. + /// What the session is about to do with it, for the error. + /// Cancels the read. + private async ValueTask RecordAsync(string purpose, CancellationToken cancellationToken) + => await _session.Compiled.ConversationStore.GetAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false) + ?? throw new InvalidOperationException( + $"Store 0 holds no conversation '{_session.ConversationId}' for its own session to {purpose}."); + /// /// Reads the session of this conversation, or null before its first turn opened one. /// diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs index a1b68b47..ea591603 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs @@ -17,14 +17,15 @@ internal ConversationTurnCommit(ConversationSession session) _session = session; } - // One lock, one moment. A late barge-in reads all four of these together, so a window in - // which LastTurn already names this turn while the span or the ordinal still names the one - // before it would let an amendment rewrite the wrong part of the transcript. - internal TurnResult Publish(ConversationTurn turn, ReplyOutcome outcome, TranscriptEntry addition, TurnResult result, ConversationInterruptionTracker.Interruption? interruption) + internal TurnResult Publish( + ConversationTurn turn, + ReplyOutcome outcome, + TranscriptEntry addition, + TurnResult result, + ConversationInterruptionTracker.Interruption? interruption) { lock (_session.InterruptLock) { - // What the caller said and what the caller heard, written together. if (_session.SessionCarriesHistory) { _session.LastReplyMessageId = _session.History.AppendTurn( @@ -32,58 +33,28 @@ internal TurnResult Publish(ConversationTurn turn, ReplyOutcome outcome, Transcr } else { - // Rows 3 and 4 answer with one reply per node, and the caller hears one of them. - // Store 1 holds the caller-facing turn alone, so the deliberation that produced the - // answer never enters the record and never reaches a later turn. _session.LastReplyMessageId = _session.History.AppendCallerFacingTurn( turn.Session, turn.Spoken, addition.Heard, _session.Snapshot(), turn.MessageId); } - // Only now. The chain stores a hash of the spoken text and store 1 stores the text, so a - // reply.interrupted raised before the append would name a hash of words nothing holds. var completedEventId = _session.Events.WriteTurnEvents(result, outcome.SpokenReply, outcome.ToolFault); - // A turn one barge-in already cut is not amendable again, so it is not published here. _session.AmendableEventId = outcome.InterruptedAfter is null ? completedEventId : null; + _session.LastTurn = result; - // The second read. The first one happened before the extractor await, and that await is - // bounded only by TurnCompletionTimeout, so a barge-in has five whole seconds in which - // to land after this turn already decided it was not interrupted. On a streaming turn it - // finds _runCancellation still set and the run still audible, because EndRun does not - // run until this method has returned, so it takes the in-flight path, cancels a run that - // has already stopped, and answers true — and true, on the contract of Interrupt, means - // the barge-in is recorded. (A turn that never streamed was never audible, so its frame - // already took the amendment path against the turn before this one and never lands - // here.) Nothing recorded the streaming frame. Reading _interruption again here, one - // statement after _amendable and LastTurn were published, hands that frame to the very - // path a frame arriving one instant later would have taken: the tested amendment, which - // writes the TurnCompleted then ReplyInterrupted pair T23 asks for. The _amendableEventId - // guard above already fits: it is published exactly when interruptedAfter is null, which - // is the only state this window can be reached in. if (interruption is null && _session.Interruption is { } late && _session.Interruptions.AmendLastTurn(late) && _session.LastTurn is { } amended) { - // The amendment republished LastTurn, so the turn this method returns and the - // duration the telemetry reads must both come from it and not from the record - // built before the frame landed. result = amended; } - // Consumed, on whichever path recorded it: the in-flight read at the top of the turn - // fed WriteTurnEvents, and the amendment above wrote its own pair. Nothing downstream - // may handle one frame twice. _session.Interruption = null; - // The turn is committed, so the run is no longer what the caller is hearing. This is the - // tail of the same defect the read above fixes: a barge-in landing between this lock and - // EndRun would otherwise still find the run audible, take the in-flight path, and be - // recorded nowhere at all. Cleared here, under the lock that just published LastTurn, it - // reaches AmendLastTurn against this turn instead. EndRun still runs and still owns - // disposing the source; clearing the field twice costs nothing. _session.RunCancellation = null; + _session.Interruptions.RunIsAudible = false; } @@ -94,9 +65,6 @@ internal async Task EndConversationIfOverAsync(DateTimeOffset endedAt, string st { if (_session.IsComplete) { - // The machine reached a terminal stage, so the conversation is over and the chain closes here. - // The stage rides as detail, because the reason a report counts is the same one for - // every terminal stage the document declares. _session.Events.EndConversation(ConversationEndReason.AgentCompleted, endedAt, stageAfter); } @@ -105,18 +73,10 @@ internal async Task EndConversationIfOverAsync(DateTimeOffset endedAt, string st return; } - // Children before shells: a cancelled child may be inside a shell tool the next line - // tears down. await _session.Lifetime.ReleaseBackgroundSessionsAsync().ConfigureAwait(false); - // Shells first: a Docker executor's bind mount is this workspace, and it must not be - // deleted out from under a still-live container. await _session.Lifetime.DisposeShellsAsync().ConfigureAwait(false); - // A tool running mid-turn (a file_memory_write, say) can call EndConversation itself, which - // deletes the workspace and then IsComplete overwrites the flag when the policy also - // reaches a terminal stage. _events.HasEnded survives that overwrite, so the folder a - // tool recreated after the mid-turn delete is still cleaned up here. _session.Lifetime.DeleteWorkspace(); } } diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs index 4c90e2bc..82712cbc 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs @@ -11,9 +11,6 @@ namespace AgentCore.Application.Runtime; -// The prepare half of the turn loop (OpenAI turn_preparation seam): guards, withdrawal, -// request building, and the non-streaming run core. Owns no committed state; everything it -// reads lives on the owning ConversationSession, which keeps the single live-state owner of Phase 1. internal sealed class ConversationTurnRunner { private readonly ConversationSession _session; @@ -64,6 +61,7 @@ internal async Task RunTurnCoreAsync( { var session = await _session.Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); + await AdmitTurnAsync(session, origin, cancellationToken).ConfigureAwait(false); var turn = BeginTurn(userInput, session, origin); var cancellation = _session.Interruptions.StartRun(cancellationToken); @@ -72,7 +70,7 @@ internal async Task RunTurnCoreAsync( { var invocation = TurnInvocationOf(turn); - var runSession = await RunSessionAsync(turn, cancellation.Token).ConfigureAwait(false); + var runSession = await OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); TurnRegistry.Set(runSession, invocation); @@ -81,9 +79,6 @@ internal async Task RunTurnCoreAsync( try { - // Interrupt never cancels this token: the turn is not audible, so a barge-in takes - // the amendment path against the turn that finished last. Only the host's own token - // cancels this run, and that cancellation propagates. response = await turn.Agent .RunAsync( turn.Request, @@ -94,14 +89,10 @@ internal async Task RunTurnCoreAsync( } catch (Exception exception) when (exception is not OperationCanceledException) { - // Section 8.7, sixth row. The run throws, the turn ends, and the conversation lives. toolFault = exception.Message; response = new AgentResponse(); } - // CompleteTurnAsync publishes LastTurn itself, under the same lock that records what a - // late barge-in may still amend. Assigning it a second time here could overwrite an - // amendment that landed in between. return await _session.Completion.CompleteTurnAsync(turn, response, toolFault, ConversationTurnStream.ReadDisposition(response), cancellationToken) .ConfigureAwait(false); } @@ -113,14 +104,13 @@ internal async Task RunTurnCoreAsync( } /// - /// Picks the agent, withdraws whatever this turn replaces, builds the model input, and takes the - /// turn. + /// Admits one turn: refuses a terminal or running conversation, then withdraws whatever the turn + /// replaces. follows, from the same frame. /// - /// What the caller said or answered: words, an approval answer, or both. /// The session of this conversation. /// Where the turn hangs, or null for a caller that does not say. - /// Everything the rest of the turn needs. - internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, ConversationTurnOrigin? origin = null) + /// Cancels the withdrawal. + internal async ValueTask AdmitTurnAsync(AgentSession session, ConversationTurnOrigin? origin, CancellationToken cancellationToken) { if (_session.IsComplete) { @@ -128,49 +118,48 @@ internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, $"The conversation '{_session.ConversationId}' reached the terminal stage '{_session.Stage}', so it runs no further turn."); } - var agent = ResolveAgent(); - - // One session runs one turn at a time. The state document takes no lock, so a second turn - // that overlapped the first would corrupt it rather than fail. if (!_session.Interruptions.TryEnterTurn()) { throw new InvalidOperationException( $"A turn of the conversation '{_session.ConversationId}' is still running. One conversation runs one turn at a time."); } - Activity? activity = null; try { - // After both guards: a turn refused as terminal or already-running must not drop the - // probe latch out from under the turn actually in flight. Runs exactly once here, in - // BeginTurn, and never per streaming step, which would drop the latch several times - // inside one streaming turn. _session.Clarifications.BeginTurn(); - // Behind both guards, because the withdrawal deletes: a turn refused for a terminal conversation or - // for one already running must not have taken the tail of the conversation with it on the way out. - // Ahead of the request below, because the words it withdraws have to be gone from the live - // history this run reads and not only from the store. The turn index is deliberately not - // wound back with them: store 3 keeps its rows for the withdrawn turns, and two turns at one - // index in the chain is worse than a gap in it. - WithdrawSuperseded(session, origin); - - // The reminder rides a request that happens anyway, and it rides exactly one, as a message - // the framework appends for that invocation and stores nowhere. It reads the state document - // and never the transcript. Only an entry with a policy: has a stage that waits on a slot. + await WithdrawSupersededAsync(session, origin, cancellationToken).ConfigureAwait(false); + } + catch + { + _session.Interruptions.ReleaseTurn(); + + throw; + } + } + + /// + /// Picks the agent, builds the model input, and takes the turn admitted. + /// Synchronous on purpose: the turn span it opens must be the ambient activity of the caller's + /// frame, and an async method hands no back. + /// + /// What the caller said or answered: words, an approval answer, or both. + /// The session of this conversation. + /// Where the turn hangs, or null for a caller that does not say. + /// Everything the rest of the turn needs. + internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, ConversationTurnOrigin? origin = null) + { + Activity? activity = null; + try + { + var agent = ResolveAgent(); + var reminder = _session.Policy is null ? null : UnfilledSlotReminder.Build(_session.State, _session.Policy.CurrentStage); + ChatMessage spoken = userInput; - // The framework has never heard of a turn, so the turn loop names this one before the run. _session.History.BeginTurn(session, _session.State.TurnIndex); - // Rows 1 and 2 read the conversation out of the session, so the run carries the new message alone - // and the provider prepends the rest. A graph row that reuses its session reads the same - // way: the resumed conversation already carries what came before. Any other graph row - // takes no provider, so its history rides the request, rendered into the one role a node - // still recognises. Neither shape puts the caller's message in store 1 yet: the turn - // writes what it said and what it heard together, when it commits, so the run that is - // about to read the history does not find its own prompt already in it. List request; if (_session.SessionCarriesHistory || _session.ReusesGraphSession) { @@ -185,9 +174,8 @@ internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, request = [spoken]; } - // One turn is one span. The conversation id rides here, on a span attribute, because T61 refuses it - // on a metric. The span is disposed in the finally of whichever run method opened the turn. activity = AgentCoreTelemetry.StartTurn(_session.ConversationId, _session.State.TurnIndex, _session.State.Stage); + var knowledge = StateKnowledgeScope.Compose( _session.State, _session.Compiled.Configuration.Providers?.Knowledge?.Scope, _session.Scope); @@ -215,33 +203,33 @@ internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, } catch { - // Only the run methods' own finally frees the session and closes the span, and it starts - // after this method returns. A throw while the turn is still being built would otherwise - // leave _running set, so every later turn of the conversation is refused as one already running. activity?.Dispose(); + _session.Interruptions.ReleaseTurn(); + throw; } } /// Takes back everything the conversation said after the message this turn hangs off. - internal void WithdrawSuperseded(AgentSession session, ConversationTurnOrigin? origin) + internal async ValueTask WithdrawSupersededAsync(AgentSession session, ConversationTurnOrigin? origin, CancellationToken cancellationToken) { - if (origin is not { NamesParent: true } - || _session.History.TruncateFrom(session, origin.ParentMessageId) is not { } withdrawn) + if (origin is not { NamesParent: true }) + { + return; + } + + var cut = _session.History.CanTruncateFrom(session, origin.ParentMessageId) + ? _session.History.TruncateFrom(session, origin.ParentMessageId) + : await _session.Ledger.CutUnderSummaryAsync(session, origin.ParentMessageId, cancellationToken).ConfigureAwait(false); + + if (cut is not { } withdrawn) { return; } - // Without this, lastNamed would survive a withdrawal that deleted the very turns it recorded, - // and silence the probe forever about a question the caller edited away. The ask counter is - // deliberately untouched here: what the caller heard, they still heard, and clearing it - // would let the withdrawn segment buy a fresh maxAsks budget. _session.Clarifications.Withdraw(); - // The turn index the event is filed under is the one about to run; the payload is what says - // which turns it replaced. The rows of those turns are already deleted, so nothing else in - // any store can answer that afterwards. _ = _session.Events.Raise( ConversationEventKind.TurnSuperseded, _session.Time.GetUtcNow(), @@ -261,7 +249,6 @@ internal AIAgent ResolveAgent() { if (_session.Policy is null) { - // Row 1, row 3, and row 4 of the compile table. One entry agent answers every turn. return _session.Compiled.TurnAgent; } @@ -281,7 +268,7 @@ internal AIAgent ResolveAgent() /// The turn about to run. /// Cancels the open. /// The conversation's session on rows 1 and 2, the conversation's shared workflow session on a graph row that reuses one, and a fresh workflow session on any other graph row. - internal async ValueTask RunSessionAsync(ConversationTurn turn, CancellationToken cancellationToken) + internal async ValueTask OpenRunAsync(ConversationTurn turn, CancellationToken cancellationToken) { if (_session.SessionCarriesHistory) { @@ -312,6 +299,7 @@ internal TurnInvocation TurnInvocationOf(ConversationTurn turn) Knowledge = turn.Knowledge, Clarifications = _session.Clarifications, CarriesHistory = _session.SessionCarriesHistory, + Logger = _session.Logger, Screen = turn.Renders, Sources = turn.Sources, Renders = turn.Renders, diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs index aee3e3ca..58b750f4 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs @@ -38,6 +38,7 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync { var session = await _session.Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); + await _session.Runner.AdmitTurnAsync(session, origin, cancellationToken).ConfigureAwait(false); var turn = _session.Runner.BeginTurn(userInput, session, origin); // A streaming turn becomes audible only once it hands the host its first piece of content. @@ -49,7 +50,7 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync string? toolFault = null; var invocation = _session.Runner.TurnInvocationOf(turn); - var runSession = await _session.Runner.RunSessionAsync(turn, cancellation.Token).ConfigureAwait(false); + var runSession = await _session.Runner.OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); TurnRegistry.Set(runSession, invocation); @@ -67,8 +68,6 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync { AgentResponseUpdate update; - // The enumeration itself sits in its own try, because a method that yields takes - // no catch clause around the yield. try { if (!await stream.MoveNextAsync().ConfigureAwait(false)) @@ -80,14 +79,12 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync } catch (OperationCanceledException) when (_session.Interruptions.CurrentInterruption() is not null) { - // The caller spoke over the reply, and the relay already reported how much of - // it played. Nothing here estimates that value: see item 6c. break; } catch (Exception exception) when (exception is not OperationCanceledException) { - // Section 8.7, sixth row. toolFault = exception.Message; + break; } @@ -96,12 +93,8 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync var content = update.AsChatResponseUpdate(); if (TurnMessages.CarriesContent(content) && Speaks(update)) { - // Marked before the yield, not after it: an async iterator only resumes past - // a yield once the host comes back for the next update, and by then the host - // has already queued this piece for the caller. _session.Interruptions.RunIsAudible = true; - // The host speaks this, so it leaves the seam as fast as the model produced it. yield return content; } } @@ -111,9 +104,6 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync await stream.DisposeAsync().ConfigureAwait(false); } - // CompleteTurnAsync publishes LastTurn itself. See the same note in RunTurnAsync. The - // disposition comes off the raw updates and never off the folded response: update-level - // properties do not survive streaming coalescing. _ = await _session.Completion.CompleteTurnAsync( turn, updates.ToAgentResponse(), toolFault, ReadDisposition(updates), cancellationToken) .ConfigureAwait(false); diff --git a/src/AgentCore.Application/Runtime/TurnInvocation.cs b/src/AgentCore.Application/Runtime/TurnInvocation.cs index 70446fd3..1b6a2924 100644 --- a/src/AgentCore.Application/Runtime/TurnInvocation.cs +++ b/src/AgentCore.Application/Runtime/TurnInvocation.cs @@ -3,8 +3,9 @@ using AgentCore.Application.Runtime.Turn; using AgentCore.Application.State; using AgentCore.Domain.Knowledge; -using Microsoft.Extensions.AI; using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; namespace AgentCore.Application.Runtime; @@ -48,6 +49,9 @@ internal sealed record TurnInvocation /// Gets whether this row's session carries the caller's own history. public bool CarriesHistory { get; init; } + /// Gets the conversation's logger, or to log nowhere. + public ILogger? Logger { get; init; } + /// Gets the screen this conversation draws on, or when it has none. public IRenderPort? Screen { get; init; } diff --git a/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs b/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs index 77ff9ce0..51e94b9c 100644 --- a/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs +++ b/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs @@ -32,7 +32,6 @@ public AgentCoreChatHistoryProvider(IConversationStore? store = null, ILogger? l _store = store ?? new InMemoryConversationStore(); _logger = logger ?? NullLogger.Instance; - } /// @@ -86,12 +85,9 @@ public int NextOrdinal(AgentSession session) return UnderLock(session, static transcript => transcript.NextOrdinal); } - /// - /// Replaces the conversation's live history with what store 1 now holds, so a later turn sees a row a - /// host appended from outside any turn. - /// + /// Replaces the conversation's live history with what store 1 holds. /// The session this conversation runs on. - /// Every stored message of the conversation, as store 1 now holds it. + /// The rows store 1 read for the session, as takes them. /// The next free ordinal of the conversation, from store 0's own counter. public void Resync(AgentSession session, IReadOnlyList rows, int nextOrdinal) { @@ -107,6 +103,70 @@ public void Resync(AgentSession session, IReadOnlyList rows }); } + /// Reads the summary the session holds in place of its oldest rows, or when every row is live. + /// The session this conversation runs on. + public ChatMessage? Summary(AgentSession session) + { + ArgumentNullException.ThrowIfNull(session); + + return UnderLock(session, static transcript => transcript.Summary?.Message); + } + + /// Names where a compaction of the conversation would reach, and the revision it reads. + /// The session this conversation runs on. + /// The floor, or when the conversation holds nothing to compact. + public TranscriptFloor? Floor(AgentSession session) + { + ArgumentNullException.ThrowIfNull(session); + + return UnderLock(session, static transcript => transcript.Floor()); + } + + /// + /// Puts one summary in place of every row at or below , unless the + /// words moved since was read, and queues the summary's row for store 1 ahead + /// of the turn's own words. + /// + /// The session this conversation runs on. + /// The message that now speaks for those rows. + /// The last ordinal it speaks for. + /// The revision reported. + /// when the summary now stands. + public bool Compact(AgentSession session, ChatMessage summary, int coversUpTo, int revision) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(summary); + + return UnderLock( + session, + (transcript, gate) => + { + if (transcript.Compact(summary, coversUpTo, revision) is not { } row) + { + return false; + } + + ConversationMessageDraft draft = new(row.TurnIndex, row.Content, row.MessageId) { CoversUpTo = row.CoversUpTo }; + gate.Enqueue(() => new ValueTask(_store.AppendAsync( + transcript.ConversationId, [draft], state: null, CancellationToken.None).AsTask())); + + return true; + }); + } + + /// + /// Whether can cut an edit hanging off one message from what the session + /// holds. It cannot when the cut would reach a row the summary stands in for; every row must be read back first. + /// + /// The session this conversation runs on. + /// The message the edit hangs off, or for the whole conversation. + public bool CanTruncateFrom(AgentSession session, string? parentMessageId) + { + ArgumentNullException.ThrowIfNull(session); + + return UnderLock(session, transcript => transcript.CanTruncateFrom(parentMessageId)); + } + /// /// Stamps the turn the next run belongs to. /// @@ -124,7 +184,7 @@ public void BeginTurn(AgentSession session, int turnIndex) } /// - /// Reads the whole conversation, oldest message first. + /// Reads the conversation as the model sees it: the summary first, when one stands, then every live row, oldest first. /// public IReadOnlyList Read(AgentSession session) { @@ -175,11 +235,8 @@ public IReadOnlyList Read(AgentSession session) .Select(row => new ConversationMessageDraft(row.TurnIndex, row.Content, row.MessageId)) .ToArray(); - Enqueue( - gate, - () => new ValueTask(_store.AppendAsync( - transcript.ConversationId, drafts, state, CancellationToken.None).AsTask()), - transcript); + gate.Enqueue(() => new ValueTask(_store.AppendAsync( + transcript.ConversationId, drafts, state, CancellationToken.None).AsTask())); return rows[^1].MessageId; }); } @@ -196,6 +253,10 @@ public IReadOnlyList Read(AgentSession session) /// the conversation holds no message of that name — a caller naming a message this host never stored — /// and the turn then runs as a plain new turn. /// + /// + /// The cut reaches a row the summary stands in for. Ask first, and read every + /// row back when it says no. + /// public WithdrawnTurns? TruncateFrom(AgentSession session, string? parentMessageId) { ArgumentNullException.ThrowIfNull(session); @@ -225,11 +286,8 @@ public IReadOnlyList Read(AgentSession session) Log.ConversationTruncated(_logger, transcript.ConversationId, from, transcript.TurnIndex); - Enqueue( - gate, - () => new ValueTask( - _store.TruncateAsync(transcript.ConversationId, from, CancellationToken.None).AsTask()), - transcript); + gate.Enqueue(() => new ValueTask( + _store.TruncateAsync(transcript.ConversationId, from, CancellationToken.None).AsTask())); return withdrawn; }); @@ -279,10 +337,7 @@ public bool TruncateLastReply(AgentSession session, string heard, TimeSpan playe foreach (var row in rows) { - Enqueue( - gate, - () => _store.RewriteAsync(row.ConversationId, row.MessageId, row.Content, CancellationToken.None), - transcript); + gate.Enqueue(() => _store.RewriteAsync(row.ConversationId, row.MessageId, row.Content, CancellationToken.None)); } return true; @@ -316,33 +371,6 @@ protected override ValueTask> ProvideChatHistoryAsync( protected override ValueTask StoreChatHistoryAsync( InvokedContext context, CancellationToken cancellationToken = default) => default; - /// Queues one store write behind everything this conversation has already queued. - private void Enqueue(ConversationGate gate, Func write, ConversationTranscript transcript) - => gate.Writes = WriteAfterAsync(gate.Writes, gate, write, transcript.ConversationId, transcript.TurnIndex); - - /// Writes to the store, and lets the conversation outlive a store that refuses. - private async Task WriteAfterAsync( - Task previous, ConversationGate gate, Func write, string conversationId, int turnIndex) - { - await previous.ConfigureAwait(false); - - try - { - await write().ConfigureAwait(false); - } -#pragma warning disable CA1031 // A store 1 write failure never ends a conversation, and never breaks the chain behind it. - catch (Exception exception) -#pragma warning restore CA1031 - { - Log.TranscriptWriteFailed(_logger, conversationId, turnIndex, exception); - - // The words are lost and the conversation is not. The report is what turns that into a fact the - // host can count; the contract of TranscriptWriteDropped is that it cannot throw, which - // is what keeps this chain from ever faulting. - gate.Dropped?.Invoke(turnIndex, exception); - } - } - /// Runs one piece of work against the conversation's transcript, alone. private TResult UnderLock(AgentSession session, Func work) { @@ -357,21 +385,5 @@ private TResult UnderLock(AgentSession session, Func(AgentSession session, Func work) => UnderLock(session, (transcript, _) => work(transcript)); - private ConversationGate GateFor(AgentSession session) => _gates.GetValue(session, static _ => new ConversationGate()); - - /// What one conversation holds outside its state bag: its lock, its transcript, and its queue of store writes. - private sealed class ConversationGate - { - /// Gets the lock every read and every change of this conversation's transcript takes. - public Lock Sync { get; } = new(); - - /// Gets the conversation's live transcript. It never enters the state bag, so serializing the bag stays small. - public ConversationTranscript Transcript { get; } = new(); - - /// Gets or sets the tail of this conversation's store writes. It never faults. - public Task Writes { get; set; } = Task.CompletedTask; - - /// Gets or sets where a dropped write of this conversation is reported, if anywhere. - public TranscriptWriteDropped? Dropped { get; set; } - } + private ConversationGate GateFor(AgentSession session) => _gates.GetValue(session, _ => new ConversationGate(_logger)); } diff --git a/src/AgentCore.Application/Transcript/ConversationCut.cs b/src/AgentCore.Application/Transcript/ConversationCut.cs new file mode 100644 index 00000000..eed5783c --- /dev/null +++ b/src/AgentCore.Application/Transcript/ConversationCut.cs @@ -0,0 +1,6 @@ +namespace AgentCore.Application.Transcript; + +/// What one took. +/// How many rows went, a summary row among them. +/// The span of turns whose spoken rows went, or when none did. +public readonly record struct ConversationCut(int Rows, WithdrawnTurns? Turns); diff --git a/src/AgentCore.Application/Transcript/ConversationGate.cs b/src/AgentCore.Application/Transcript/ConversationGate.cs new file mode 100644 index 00000000..aa7b12d2 --- /dev/null +++ b/src/AgentCore.Application/Transcript/ConversationGate.cs @@ -0,0 +1,56 @@ +using AgentCore.Application.Diagnostics; +using Microsoft.Extensions.Logging; + +namespace AgentCore.Application.Transcript; + +/// +/// What one conversation holds outside its state bag: its lock, its transcript, and its queue of +/// store writes, which never faults and lets the conversation outlive a store that refuses. +/// +internal sealed class ConversationGate +{ + private readonly ILogger _logger; + + /// Creates the gate of one conversation. + /// Where a refused write is logged. + public ConversationGate(ILogger logger) => _logger = logger; + + /// Gets the lock every read and every change of this conversation's transcript takes. + public Lock Sync { get; } = new(); + + /// Gets the conversation's live transcript. It never enters the state bag, so serializing the bag stays small. + public ConversationTranscript Transcript { get; } = new(); + + /// Gets the tail of this conversation's store writes. It never faults. + public Task Writes { get; private set; } = Task.CompletedTask; + + /// Gets or sets where a dropped write of this conversation is reported, if anywhere. + public TranscriptWriteDropped? Dropped { get; set; } + + /// Queues one store write behind everything this conversation has already queued. Runs under . + /// The write. + public void Enqueue(Func write) + => Writes = WriteAfterAsync(Writes, write, Transcript.ConversationId, Transcript.TurnIndex); + + /// Writes to the store, and lets the conversation outlive a store that refuses. + private async Task WriteAfterAsync(Task previous, Func write, string conversationId, int turnIndex) + { + await previous.ConfigureAwait(false); + + try + { + await write().ConfigureAwait(false); + } +#pragma warning disable CA1031 // A store 1 write failure never ends a conversation, and never breaks the chain behind it. + catch (Exception exception) +#pragma warning restore CA1031 + { + Log.TranscriptWriteFailed(_logger, conversationId, turnIndex, exception); + + // The words are lost and the conversation is not. The report is what turns that into a fact the + // host can count; the contract of TranscriptWriteDropped is that it cannot throw, which + // is what keeps this chain from ever faulting. + Dropped?.Invoke(turnIndex, exception); + } + } +} diff --git a/src/AgentCore.Application/Transcript/ConversationMessage.cs b/src/AgentCore.Application/Transcript/ConversationMessage.cs index 93734a8f..4a1287f1 100644 --- a/src/AgentCore.Application/Transcript/ConversationMessage.cs +++ b/src/AgentCore.Application/Transcript/ConversationMessage.cs @@ -20,4 +20,12 @@ namespace AgentCore.Application.Transcript; /// /// public sealed record ConversationMessage( - string ConversationId, int Ordinal, int TurnIndex, ChatMessage Content, string MessageId); + string ConversationId, int Ordinal, int TurnIndex, ChatMessage Content, string MessageId) +{ + /// + /// Gets the last ordinal this row stands in for, when it is a summary the session wrote in place + /// of every row at or below it; for a row somebody said. Every consumer + /// read of store 1 leaves summary rows out; only the session's own read returns one. + /// + public int? CoversUpTo { get; init; } +} diff --git a/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs b/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs index 9f6acdee..88173462 100644 --- a/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs +++ b/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs @@ -9,4 +9,8 @@ namespace AgentCore.Application.Transcript; /// /// The message itself. /// What the message is called. Unique within the conversation. Never empty. -public sealed record ConversationMessageDraft(int? TurnIndex, ChatMessage Content, string MessageId); +public sealed record ConversationMessageDraft(int? TurnIndex, ChatMessage Content, string MessageId) +{ + /// + public int? CoversUpTo { get; init; } +} diff --git a/src/AgentCore.Application/Transcript/ConversationTranscript.cs b/src/AgentCore.Application/Transcript/ConversationTranscript.cs index 52891fe5..987cf47a 100644 --- a/src/AgentCore.Application/Transcript/ConversationTranscript.cs +++ b/src/AgentCore.Application/Transcript/ConversationTranscript.cs @@ -23,8 +23,17 @@ internal sealed class ConversationTranscript /// public List Messages { get; set; } = []; + /// Gets the summary that stands in for the oldest rows, or when every row is live. + public StoredMessage? Summary => Messages.Find(static stored => stored.CoversUpTo is not null); + + /// + /// Gets a count that moves on every change to the words. A compaction computed outside the lock + /// names the revision it read, and is refused when the words moved underneath it. + /// + public int Revision { get; private set; } + /// Reads a conversation that already has words back into a transcript that has none. - /// Every stored message of the conversation. Order does not matter. + /// The rows of the conversation the session reads, as takes them. /// How far the conversation had got, from the state stored beside these words. /// The index the next turn of this conversation takes. public int Resume(IReadOnlyList rows, TranscriptMarks marks) @@ -35,10 +44,14 @@ public int Resume(IReadOnlyList rows, TranscriptMarks marks } /// - /// Replaces the live history with what store 1 now holds, without disturbing + /// Replaces the live history with what store 1 holds, without disturbing /// or . /// - /// Every stored message of the conversation, as store 1 now holds it. Order does not matter. + /// + /// The rows store 1 read for the session: every row, or the newest summary and the rows above what + /// it covers. A row a summary stands in for is the caller's mistake, not this method's to catch: + /// it lands in the live history beside the summary that already speaks for it. Order does not matter. + /// /// The next free ordinal of the conversation, from store 0's own counter. public void Resync(IReadOnlyList rows, int nextOrdinal) { @@ -54,9 +67,11 @@ public void Resync(IReadOnlyList rows, int nextOrdinal) TurnIndex = row.TurnIndex, MessageId = row.MessageId, Message = row.Content.WithoutHostContent(), + CoversUpTo = row.CoversUpTo, })]; NextOrdinal = nextOrdinal; + Revision++; // Without this a caller who barges in on the first reply of a resumed session is not heard: // TruncateLastReply finds no ordinal to cut at and returns nothing, and the provider reports @@ -66,7 +81,10 @@ public void Resync(IReadOnlyList rows, int nextOrdinal) /// Finds the ordinal a message sits at, by the name a caller knows it under. /// What the caller calls the message. - /// The ordinal, or when the conversation holds no message of that name. + /// + /// The ordinal, or when the live history holds no message of that name. + /// A message the stands in for is not held, and answers null too. + /// public int? OrdinalOf(string messageId) { ArgumentException.ThrowIfNullOrEmpty(messageId); @@ -75,16 +93,45 @@ public void Resync(IReadOnlyList rows, int nextOrdinal) ?.Ordinal; } - /// Withdraws the tail of the conversation, from one ordinal onward. - /// The first ordinal to drop. It goes too. + /// + /// Whether an edit hanging off one message can be cut from what this transcript holds. It can + /// unless the cut would reach a row the stands in for: the whole + /// conversation, or a parent this transcript does not hold. Such an edit needs every row read + /// back first, because the summary must go and the rows it spoke for must come back. + /// + /// The message the edit hangs off, or for the whole conversation. + public bool CanTruncateFrom(string? parentMessageId) + { + if (Summary is not { CoversUpTo: { } covered }) + { + return true; + } + + return parentMessageId is not null && OrdinalOf(parentMessageId) is { } ordinal && ordinal > covered; + } + + /// + /// Withdraws the tail of the conversation, from one ordinal onward. The + /// stays when the cut lies above what it covers, whatever its own ordinal: it was written after + /// the rows it stands for, so its ordinal says nothing about where the cut falls. + /// + /// The first ordinal to drop. It goes too. It lies above what the covers. /// The turns the withdrawal took, or when nothing went. + /// The cut reaches a row the stands in for. public WithdrawnTurns? TruncateFrom(int fromOrdinal) { + if (Summary is { CoversUpTo: { } covered } && fromOrdinal <= covered) + { + throw new InvalidOperationException( + $"The cut at ordinal {fromOrdinal} reaches under the summary of the conversation '{ConversationId}', " + + $"which covers every row up to {covered}. Read every row back before cutting there."); + } + var first = int.MaxValue; var last = int.MinValue; foreach (var stored in Messages) { - if (stored.Ordinal < fromOrdinal) + if (stored.Ordinal < fromOrdinal || stored.CoversUpTo is not null) { continue; } @@ -98,14 +145,16 @@ public void Resync(IReadOnlyList rows, int nextOrdinal) return null; } - Messages.RemoveAll(stored => stored.Ordinal >= fromOrdinal); + Messages.RemoveAll(stored => stored.Ordinal >= fromOrdinal && stored.CoversUpTo is null); RestoreLastAssistantOrdinal(); + Revision++; return new WithdrawnTurns(first, last); } private void RestoreLastAssistantOrdinal() => LastAssistantOrdinal = Messages - .Where(stored => stored.Message.Role == ChatRole.Assistant + .Where(stored => stored.CoversUpTo is null + && stored.Message.Role == ChatRole.Assistant && !string.IsNullOrWhiteSpace(stored.Message.Text)) .Select(stored => (int?)stored.Ordinal) .LastOrDefault(); @@ -113,8 +162,90 @@ private void RestoreLastAssistantOrdinal() /// Opens a turn, so the rows it appends carry its index. public void BeginTurn(int turnIndex) => TurnIndex = turnIndex; - /// Reads the whole conversation, oldest message first. - public IReadOnlyList Read() => [.. Messages.Select(stored => stored.Message)]; + /// + /// Reads the conversation as the model sees it: the first, then every live + /// row, oldest first. The summary leads whatever its ordinal: it was written after the newest + /// rows it does not cover, and those must follow it, not precede it. + /// + public IReadOnlyList Read() => [.. View(Messages.Count).Select(entry => entry.Message)]; + + /// + /// Names what a compaction of the conversation would cover: everything before the newest live + /// turn. That turn stays live so the edit a caller most often makes — of the last question, which + /// hangs off the reply before it — still finds its parent without a full read. + /// + /// + /// The view the compaction would run over, or when nothing lies before the + /// newest live turn: a conversation of one turn, or a summary with one turn above it — which the + /// summary already covers. + /// + public TranscriptFloor? Floor() + { + var newest = Messages.FindLast(static stored => stored.CoversUpTo is null)?.TurnIndex; + + var last = Messages.FindLastIndex(stored => stored.CoversUpTo is null && stored.TurnIndex < newest); + + if (last < 0) + { + return null; + } + + return new TranscriptFloor(Revision, Summary?.CoversUpTo, [.. View(last + 1)]); + } + + /// The model view of the first rows: the summary first, then each live row at its own ordinal. + private IEnumerable View(int count) + { + if (Summary is { CoversUpTo: { } covered } summary) + { + yield return new ViewMessage(summary.Message, covered); + } + + foreach (var stored in Messages.Take(count).Where(stored => stored.CoversUpTo is null)) + { + yield return new ViewMessage(stored.Message, stored.Ordinal); + } + } + + /// + /// Puts one summary in place of every row at or below and of the + /// summary that stood before it, unless the words moved since was read. + /// + /// The message that now speaks for those rows. + /// The last ordinal it speaks for. Never below what the standing covers. + /// The the compaction read. + /// The row the summary became, for store 1; or when the compaction was stale and dropped. + public ConversationMessage? Compact(ChatMessage summary, int coversUpTo, int revision) + { + ArgumentNullException.ThrowIfNull(summary); + + if (Summary is { CoversUpTo: { } covered }) + { + ArgumentOutOfRangeException.ThrowIfLessThan(coversUpTo, covered); + } + + if (revision != Revision) + { + return null; + } + + Messages.RemoveAll(stored => stored.Ordinal <= coversUpTo || stored.CoversUpTo is not null); + + var ordinal = NextOrdinal++; + var messageId = NewMessageId(); + Messages.Add(new StoredMessage + { + Ordinal = ordinal, + TurnIndex = TurnIndex, + MessageId = messageId, + Message = summary.WithoutHostContent(), + CoversUpTo = coversUpTo, + }); + + RestoreLastAssistantOrdinal(); + Revision++; + return new ConversationMessage(ConversationId, ordinal, TurnIndex, summary, messageId) { CoversUpTo = coversUpTo }; + } /// Adds new messages to the conversation, and returns the rows they became. /// The messages the turn produced, oldest first. @@ -131,16 +262,11 @@ public IReadOnlyList Append( for (var index = 0; index < messages.Count; index++) { var message = messages[index]; + var ordinal = NextOrdinal++; - // Every row gets a name, not just the one the caller named. The parent an edit anchors on - // is usually a reply, and a reply is not something the caller can have named in advance. var messageId = (index == 0 ? firstMessageId : null) ?? NewMessageId(); - // The row is what the store persists, so it keeps the full message, drawing and source - // included. Messages is the live history, serialised into the session state bag every - // turn, so it never sees either: a multi-kilobyte RenderContent, or a SourceContent citing - // a document, has no business growing that bag. rows.Add(new ConversationMessage(ConversationId, ordinal, TurnIndex, message, messageId)); Messages.Add(new StoredMessage @@ -151,14 +277,13 @@ public IReadOnlyList Append( Message = message.WithoutHostContent(), }); - // A tool-calling turn produces two assistant messages and only the second is spoken. - // The textless one is not a reply anybody can be cut off in the middle of. if (message.Role == ChatRole.Assistant && !string.IsNullOrWhiteSpace(message.Text)) { LastAssistantOrdinal = ordinal; } } + Revision++; return rows; } @@ -176,7 +301,7 @@ public IReadOnlyList TruncateLastReply(string heard) List rows = []; foreach (var stored in Messages) { - if (stored.TurnIndex != spoken.TurnIndex || stored.Message.Role != ChatRole.Assistant) + if (stored.TurnIndex != spoken.TurnIndex || stored.Message.Role != ChatRole.Assistant || stored.CoversUpTo is not null) { continue; } @@ -197,6 +322,11 @@ public IReadOnlyList TruncateLastReply(string heard) ConversationId, stored.Ordinal, stored.TurnIndex, corrected, stored.MessageId)); } + if (rows.Count > 0) + { + Revision++; + } + return rows; } @@ -217,5 +347,8 @@ internal sealed class StoredMessage /// Gets or sets the message. A barge-in replaces it with what the caller heard. public ChatMessage Message { get; set; } = new(ChatRole.Assistant, string.Empty); + + /// + public int? CoversUpTo { get; set; } } } diff --git a/src/AgentCore.Application/Transcript/TranscriptFloor.cs b/src/AgentCore.Application/Transcript/TranscriptFloor.cs new file mode 100644 index 00000000..daa3f4c2 --- /dev/null +++ b/src/AgentCore.Application/Transcript/TranscriptFloor.cs @@ -0,0 +1,7 @@ +namespace AgentCore.Application.Transcript; + +/// What a compaction of the conversation would cover, read before the compaction runs. +/// The the words stood at when read. +/// The last ordinal the summary that already stands covers, or when none stands. +/// Every message the compaction covers, as the model sees them, oldest first. A standing summary comes first. +internal readonly record struct TranscriptFloor(int Revision, int? CoversUpTo, IReadOnlyList Messages); diff --git a/src/AgentCore.Application/Transcript/TranscriptWindow.cs b/src/AgentCore.Application/Transcript/TranscriptWindow.cs new file mode 100644 index 00000000..78024125 --- /dev/null +++ b/src/AgentCore.Application/Transcript/TranscriptWindow.cs @@ -0,0 +1,24 @@ +namespace AgentCore.Application.Transcript; + +/// +/// One page of a conversation's words, counted in turns rather than rows. A turn holds a question, +/// the tool calls that answered it, and the reply, and a page boundary never falls inside one, so a +/// reader can draw a page without a reply whose tool calls are on the page before it. +/// +/// +/// Only turns with a smaller index are read, or to read back from the newest. +/// +/// How many turns at most. Positive. +/// is not positive. +public readonly record struct TranscriptWindow(int? BeforeTurn, int Turns) +{ + /// How many turns at most. Positive, except on default, which reads an empty page. + public int Turns { get; init; } = Turns > 0 + ? Turns + : throw new ArgumentOutOfRangeException(nameof(Turns), Turns, "A window holds at least one turn."); + + /// Whether a turn falls before the window's start. + /// The turn to test. + /// when the turn is one the window may hold. + public bool Admits(int turnIndex) => BeforeTurn is not { } before || turnIndex < before; +} diff --git a/src/AgentCore.Application/Transcript/ViewMessage.cs b/src/AgentCore.Application/Transcript/ViewMessage.cs new file mode 100644 index 00000000..ff34fc7c --- /dev/null +++ b/src/AgentCore.Application/Transcript/ViewMessage.cs @@ -0,0 +1,12 @@ +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Transcript; + +/// +/// One message of a compaction view, with the last ordinal it stands for: a live row's own, or +/// what a standing summary covers. This is what lets the strategy's output land back on ordinals +/// instead of positions. +/// +/// The message, as the model would see it. +/// The last ordinal this message stands for, inclusive. +internal readonly record struct ViewMessage(ChatMessage Message, int LastOrdinal); diff --git a/src/AgentCore.Application/Transcript/WithdrawnTurns.cs b/src/AgentCore.Application/Transcript/WithdrawnTurns.cs index 969ae845..e8ce0e74 100644 --- a/src/AgentCore.Application/Transcript/WithdrawnTurns.cs +++ b/src/AgentCore.Application/Transcript/WithdrawnTurns.cs @@ -3,4 +3,4 @@ namespace AgentCore.Application.Transcript; /// The span of turns one withdrawal took, both ends included. /// The lowest turn index withdrawn. /// The highest turn index withdrawn. -internal readonly record struct WithdrawnTurns(int First, int Last); +public readonly record struct WithdrawnTurns(int First, int Last); diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs index edb3fb87..420e9d27 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs @@ -1,4 +1,3 @@ -using System.Diagnostics.CodeAnalysis; using System.Text.Json; using AgentCore.Application.Conversation; using AgentCore.Application.Ports; @@ -16,6 +15,8 @@ internal sealed class PostgresConversationStore : IConversationStore, IAsyncDisp { private readonly NpgsqlDataSource _dataSource; + private readonly PostgresConversationWords _words; + /// Creates the store over a data source it then owns. /// The pool every statement runs on. Disposing the store disposes it. /// The data source is . @@ -23,6 +24,7 @@ public PostgresConversationStore(NpgsqlDataSource dataSource) { ArgumentNullException.ThrowIfNull(dataSource); _dataSource = dataSource; + _words = new PostgresConversationWords(dataSource); } /// @@ -242,153 +244,41 @@ private async ValueTask AmendAsync( } /// - [SuppressMessage( - "csharpsquid", - "S3265", - Justification = "Npgsql documents Array combined with an element type via bit OR, and the enum omits Flags only upstream.")] - public async ValueTask> AppendAsync( + public ValueTask> AppendAsync( string conversationId, IReadOnlyList messages, ConversationSessionState? state = null, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(messages); - - if (messages.Count == 0) - { - return []; - } - - await using var connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); - await using NpgsqlBatch batch = new(connection); - - NpgsqlBatchCommand appendCommand = new(AppendSql); - appendCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.TurnIndex)], - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.Content.Role.Value)], - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - Value = messages.Select(message => Serialise(message.Content)).ToArray(), - NpgsqlDbType = NpgsqlDbType.Array | NpgsqlDbType.Jsonb, - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.MessageId)], - }); - batch.BatchCommands.Add(appendCommand); - - if (state is not null) - { - NpgsqlBatchCommand stateCommand = new(StateSql); - stateCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - stateCommand.Parameters.Add(new NpgsqlParameter - { - Value = JsonSerializer.Serialize(state, ConversationStateJson.Options), - NpgsqlDbType = NpgsqlDbType.Jsonb, - }); - - batch.BatchCommands.Add(stateCommand); - } - - // AppendSql is the only command with a RETURNING clause, so its result set is the only one - // this reads. Matched by message_id and not by row order: PostgreSQL makes no promise that a - // multi-row INSERT ... SELECT returns in the order its source rows arrived. - Dictionary written = []; - - await using (var reader = await batch.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false)) - { - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) - { - written[reader.GetString(2)] = (reader.GetInt32(0), reader.GetInt32(1)); - } - } - - if (written.Count == 0) - { - throw new InvalidOperationException($"Store 0 holds no conversation '{conversationId}' to append words to."); - } - - return [.. messages.Select(draft => - { - var (ordinal, turnIndex) = written[draft.MessageId]; - return new ConversationMessage(conversationId, ordinal, turnIndex, draft.Content, draft.MessageId); - })]; - } + => _words.AppendAsync(conversationId, messages, state, cancellationToken); /// - public async ValueTask RewriteAsync( + public ValueTask RewriteAsync( string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentException.ThrowIfNullOrEmpty(messageId); - ArgumentNullException.ThrowIfNull(content); - - await using var command = _dataSource.CreateCommand(RewriteSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = messageId }); - command.Parameters.Add(new NpgsqlParameter { Value = Serialise(content), NpgsqlDbType = NpgsqlDbType.Jsonb }); - - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + => _words.RewriteAsync(conversationId, messageId, content, cancellationToken); /// - /// The conversation id is . - public async ValueTask> ReadAsync( + public ValueTask> ReadForSessionAsync( string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - - await using var command = _dataSource.CreateCommand(ReadSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + => _words.ReadForSessionAsync(conversationId, cancellationToken); - List rows = []; - - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) - { - rows.Add(new ConversationMessage( - conversationId, - reader.GetInt32(0), - reader.GetInt32(1), - Deserialise(reader.GetString(2)), - reader.GetString(3))); - } + /// + public ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + => _words.ReadWindowAsync(conversationId, window, cancellationToken); - return rows; - } + /// + public ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) + => _words.OrdinalOfAsync(conversationId, messageId, cancellationToken); /// - /// The conversation id is . - public async ValueTask TruncateAsync( + public ValueTask TruncateAsync( string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - - await using var command = _dataSource.CreateCommand(TruncateSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = fromOrdinal }); - - return await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + => _words.TruncateAsync(conversationId, fromOrdinal, cancellationToken); /// - /// The continuation id is . - public async ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - - await using var command = _dataSource.CreateCommand(EraseSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - - return await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + => _words.EraseAsync(conversationId, cancellationToken); /// public async ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs index 585eb842..5c726881 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs @@ -85,7 +85,8 @@ ON CONFLICT (principal_key, conversation_id) DO NOTHING /// ordinals mark reserves, and RETURNING on the UPDATE sees the bumped /// next_ordinal, so subtracting that same count back off it gives the first one this batch /// may use. A null element of $2 (turn_index) takes the conversation's own next turn index instead - /// of naming one, which is what an append from outside any turn asks for. + /// of naming one, which is what an append from outside any turn asks for. $6 is the + /// covers_up_to of each row: null for every row somebody said. /// internal const string AppendSql = $""" WITH mark AS ( @@ -95,23 +96,74 @@ WITH mark AS ( RETURNING next_ordinal - cardinality($5::text[]) AS first, coalesce((state ->> 'nextTurnIndex')::int, 0) AS next_turn_index ) - INSERT INTO {Schema}.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) - SELECT $1, mark.first + d.position - 1, coalesce(d.turn_index, mark.next_turn_index), d.role, d.content, d.message_id - FROM mark, unnest($2::int[], $3::text[], $4::jsonb[], $5::text[]) WITH ORDINALITY - AS d(turn_index, role, content, message_id, position) + INSERT INTO {Schema}.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id, covers_up_to) + SELECT $1, mark.first + d.position - 1, coalesce(d.turn_index, mark.next_turn_index), d.role, d.content, d.message_id, d.covers_up_to + FROM mark, unnest($2::int[], $3::text[], $4::jsonb[], $5::text[], $6::int[]) WITH ORDINALITY + AS d(turn_index, role, content, message_id, covers_up_to, position) RETURNING ordinal, turn_index, message_id """; - /// Reads one whole conversation. - internal const string ReadSql = + /// The columns every row read returns, in the order PostgresConversationWords.ReadRowsAsync reads them. + private const string RowColumns = "ordinal, turn_index, content, message_id, covers_up_to"; + + /// + /// Reads a conversation as its session opens it: the newest summary row, and every row somebody + /// said above what it covers. With no summary, every row. + /// + internal const string ReadForSessionSql = + $""" + WITH summary AS ( + SELECT ordinal, covers_up_to FROM {Schema}.conversation_message + WHERE conversation_id = $1 AND covers_up_to IS NOT NULL + ORDER BY ordinal DESC LIMIT 1 + ) + SELECT {RowColumns} + FROM {Schema}.conversation_message m + WHERE m.conversation_id = $1 + AND m.ordinal > coalesce((SELECT covers_up_to FROM summary), -1) + AND (m.covers_up_to IS NULL OR m.ordinal = (SELECT ordinal FROM summary)) + ORDER BY m.ordinal + """; + + /// + /// Reads the newest turns of a conversation before a given one, whole. $2 is the turn to + /// read before, or null for the newest; $3 is how many turns at most. + /// + internal const string ReadWindowSql = $""" - SELECT ordinal, turn_index, content, message_id - FROM {Schema}.conversation_message WHERE conversation_id = $1 ORDER BY ordinal + SELECT {RowColumns} + FROM {Schema}.conversation_message + WHERE conversation_id = $1 + AND covers_up_to IS NULL + AND turn_index IN ( + SELECT DISTINCT turn_index FROM {Schema}.conversation_message + WHERE conversation_id = $1 AND covers_up_to IS NULL AND ($2::int IS NULL OR turn_index < $2) + ORDER BY turn_index DESC LIMIT $3) + ORDER BY ordinal """; - /// Withdraws the tail of a conversation, from one ordinal onward. + /// + /// Withdraws the tail of a conversation, from one ordinal onward. A summary row goes only when + /// the cut reaches a row it covers. + /// internal const string TruncateSql = - $"DELETE FROM {Schema}.conversation_message WHERE conversation_id = $1 AND ordinal >= $2"; + $""" + WITH gone AS ( + DELETE FROM {Schema}.conversation_message + WHERE conversation_id = $1 AND ordinal >= $2 AND (covers_up_to IS NULL OR covers_up_to >= $2) + RETURNING turn_index, covers_up_to) + SELECT count(*)::int, + min(turn_index) FILTER (WHERE covers_up_to IS NULL), + max(turn_index) FILTER (WHERE covers_up_to IS NULL) + FROM gone + """; + + /// Finds the ordinal of one spoken row by its message id. Summary rows are not found. + internal const string OrdinalOfSql = + $""" + SELECT ordinal FROM {Schema}.conversation_message + WHERE conversation_id = $1 AND message_id = $2 AND covers_up_to IS NULL + """; internal const string RewriteSql = $""" UPDATE {Schema}.conversation_message SET content = $3, updated_at = now() @@ -149,6 +201,7 @@ WITH ORDINALITY AS element(part, position) FROM {{Schema}}.conversation_message WHERE conversation_id = $1 AND role = 'assistant' + AND covers_up_to IS NULL AND content -> 'contents' @> '[{"$type": "text"}]' ORDER BY conversation_id, turn_index, ordinal DESC ), diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs new file mode 100644 index 00000000..3ca4deed --- /dev/null +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs @@ -0,0 +1,219 @@ +using System.Diagnostics.CodeAnalysis; +using System.Text.Json; +using AgentCore.Application.Conversation; +using AgentCore.Application.Ports; +using AgentCore.Application.Transcript; +using Microsoft.Extensions.AI; +using Npgsql; +using NpgsqlTypes; +using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationRows; +using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationStoreSql; + +namespace AgentCore.Infrastructure.Conversation.Postgres; + +/// The words of every conversation, in PostgreSQL: store 1's rows, and what a turn writes beside them. +internal sealed class PostgresConversationWords +{ + private readonly NpgsqlDataSource _dataSource; + + /// Binds the words to the pool every statement runs on. The store owns the pool; this does not. + /// The pool. + public PostgresConversationWords(NpgsqlDataSource dataSource) => _dataSource = dataSource; + + /// + [SuppressMessage( + "csharpsquid", + "S3265", + Justification = "Npgsql documents Array combined with an element type via bit OR, and the enum omits Flags only upstream.")] + public async ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(messages); + + if (messages.Count == 0) + { + return []; + } + + await using var connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); + await using NpgsqlBatch batch = new(connection); + + NpgsqlBatchCommand appendCommand = new(AppendSql); + appendCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.TurnIndex)], + }); + appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.Content.Role.Value)], + }); + appendCommand.Parameters.Add(new NpgsqlParameter + { + Value = messages.Select(message => Serialise(message.Content)).ToArray(), + NpgsqlDbType = NpgsqlDbType.Array | NpgsqlDbType.Jsonb, + }); + appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.MessageId)], + }); + appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.CoversUpTo)], + }); + batch.BatchCommands.Add(appendCommand); + + if (state is not null) + { + NpgsqlBatchCommand stateCommand = new(StateSql); + stateCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + stateCommand.Parameters.Add(new NpgsqlParameter + { + Value = JsonSerializer.Serialize(state, ConversationStateJson.Options), + NpgsqlDbType = NpgsqlDbType.Jsonb, + }); + + batch.BatchCommands.Add(stateCommand); + } + + // AppendSql is the only command with a RETURNING clause, so its result set is the only one + // this reads. Matched by message_id and not by row order: PostgreSQL makes no promise that a + // multi-row INSERT ... SELECT returns in the order its source rows arrived. + Dictionary written = []; + + await using (var reader = await batch.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false)) + { + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + { + written[reader.GetString(2)] = (reader.GetInt32(0), reader.GetInt32(1)); + } + } + + if (written.Count == 0) + { + throw new InvalidOperationException($"Store 0 holds no conversation '{conversationId}' to append words to."); + } + + return [.. messages.Select(draft => + { + var (ordinal, turnIndex) = written[draft.MessageId]; + return new ConversationMessage(conversationId, ordinal, turnIndex, draft.Content, draft.MessageId) { CoversUpTo = draft.CoversUpTo }; + })]; + } + + /// + public async ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); + ArgumentNullException.ThrowIfNull(content); + + await using var command = _dataSource.CreateCommand(RewriteSql); + command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + command.Parameters.Add(new NpgsqlParameter { Value = messageId }); + command.Parameters.Add(new NpgsqlParameter { Value = Serialise(content), NpgsqlDbType = NpgsqlDbType.Jsonb }); + + await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } + + private static async ValueTask> ReadRowsAsync( + string conversationId, NpgsqlCommand command, CancellationToken cancellationToken) + { + List rows = []; + + await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + { + rows.Add(new ConversationMessage( + conversationId, + reader.GetInt32(0), + reader.GetInt32(1), + Deserialise(reader.GetString(2)), + reader.GetString(3)) + { + CoversUpTo = reader.IsDBNull(4) ? null : reader.GetInt32(4), + }); + } + + return rows; + } + + /// + /// The conversation id is . + public async ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + + await using var command = _dataSource.CreateCommand(ReadForSessionSql); + command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + + return await ReadRowsAsync(conversationId, command, cancellationToken).ConfigureAwait(false); + } + + /// + /// The conversation id is . + public async ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + + await using var command = _dataSource.CreateCommand(ReadWindowSql); + command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + command.Parameters.Add(new NpgsqlParameter { TypedValue = window.BeforeTurn, NpgsqlDbType = NpgsqlDbType.Integer }); + command.Parameters.Add(new NpgsqlParameter { Value = window.Turns }); + + return await ReadRowsAsync(conversationId, command, cancellationToken).ConfigureAwait(false); + } + + /// + /// The conversation id is . + /// The message id is or empty. + public async ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); + + await using var command = _dataSource.CreateCommand(OrdinalOfSql); + command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + command.Parameters.Add(new NpgsqlParameter { Value = messageId }); + + return await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false) is int ordinal ? ordinal : null; + } + + /// + /// The conversation id is . + public async ValueTask TruncateAsync( + string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + + await using var command = _dataSource.CreateCommand(TruncateSql); + command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + command.Parameters.Add(new NpgsqlParameter { Value = fromOrdinal }); + + await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + await reader.ReadAsync(cancellationToken).ConfigureAwait(false); + + WithdrawnTurns? turns = reader.IsDBNull(1) ? null : new(reader.GetInt32(1), reader.GetInt32(2)); + return new(reader.GetInt32(0), turns); + } + + /// + /// The conversation id is . + public async ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + + await using var command = _dataSource.CreateCommand(EraseSql); + command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + + return await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } +} diff --git a/src/AgentCore.Infrastructure/Database/Postgres/Migrations/001_agentcore.sql b/src/AgentCore.Infrastructure/Database/Postgres/Migrations/001_agentcore.sql index df870e7c..98d322b7 100644 --- a/src/AgentCore.Infrastructure/Database/Postgres/Migrations/001_agentcore.sql +++ b/src/AgentCore.Infrastructure/Database/Postgres/Migrations/001_agentcore.sql @@ -1,21 +1,3 @@ --- The whole AgentCore schema. One migration, applied to a database that has none of it. --- --- Order inside the file is the order the objects need: the role first, because every grant names it; --- the schema next, because every table below lives in it; conversation before conversation_message, because the --- words are a child of the conversation they belong to; the continuation map beside them, because a resume --- must never find the key without the words; audit_event last, with the triggers that refuse to --- let it change. - - --- The role the running system connects as. Store 0, store 1 and store 3 share it. --- --- NOLOGIN, no password: a deployment owns credentials, not this migration. Make the process's login --- role a member of it: GRANT agentcore_writer TO ; --- --- The handler is not decoration. Roles are cluster-wide but the advisory lock that guards this --- migration is per-database, so two databases of one cluster can migrate at the same moment. That --- race surfaces as either error depending on where it lands: duplicate_object from the existence --- check, unique_violation from pg_authid's index. DO $$ BEGIN CREATE ROLE agentcore_writer NOLOGIN; @@ -26,156 +8,74 @@ EXCEPTION RAISE EXCEPTION 'agentcore_writer does not exist and this role may not create it. Either CREATE ROLE agentcore_writer NOLOGIN as a role that may, or grant CREATEROLE to the migrating role.'; END $$; --- Every AgentCore table lives here, never in whatever schema happens to be first on the migrating --- role's search_path. Nothing in this file or in the application relies on search_path: every --- statement below names the schema explicitly. CREATE SCHEMA IF NOT EXISTS agentcore; --- USAGE on the schema is what lets agentcore_writer see into any table below at all; the per-table --- grants that follow are meaningless without it. GRANT USAGE ON SCHEMA agentcore TO agentcore_writer; --- The running system starts as this role and asks the ledger what is already applied, so it reads --- the ledger and never writes it. Only a privileged first run migrates. GRANT SELECT ON agentcore.schema_migration TO agentcore_writer; - --- Store 0 — what a conversation is, apart from its words. One row per thread in a caller's list. --- --- This table comes first because conversation_message hangs off it. A conversation exists before it has words, and --- deleting it takes the words with it: one statement, one transaction, no ordering to get wrong. --- --- audit_event is deliberately NOT a child. The triggers at the foot of this file refuse every DELETE --- on it, so a cascade could not run even if one were declared. The trail outlives the conversation --- on purpose, and relates to a conversation by conversation_id convention alone. CREATE TABLE agentcore.conversation ( conversation_id text PRIMARY KEY, title text NULL, status text NOT NULL DEFAULT 'regular', external_id text NULL, custom jsonb NULL, - - -- What the SESSION of a conversation holds and nothing else does: the stage, whether the machine - -- finished, the slots the writers filled, and the turn-index mark that says how far the conversation's - -- own session has got. Not the words — those are conversation_message. Written in the same batch as the - -- turn's words, so a crash cannot land one without the other. - -- - -- The ordinal mark is not here. next_ordinal, below, holds it instead: an append can come from - -- the session or from a host outside any turn, so the shared counter needs a column the store - -- itself owns, not a value inside session state that only the session ever writes. - -- - -- The turn-index mark stays here on purpose. An edit deletes the rows it replaces, so the largest - -- turn index still in conversation_message is smaller than the largest ever issued, and a session that - -- recomputed it from the surviving rows would hand the next turn a place a deleted row already - -- stood in. state jsonb NULL, - - -- The conversation's next free message ordinal: a store-owned counter that numbers every appended row, - -- whether the append comes from the session or from a host outside any turn. next_ordinal integer NOT NULL DEFAULT 0, - created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(), CONSTRAINT conversation_status_check CHECK (status IN ('regular', 'archived')) ); --- Who may see a conversation. principal_key is opaque: this schema never joins it to a user table, and the --- consumer's identity model stays the consumer's. A conversation carries as many keys as are attached, so a --- tenant key can be attached when the conversation starts and a person's key when identity is learned. CREATE TABLE agentcore.conversation_principal ( conversation_id text NOT NULL REFERENCES agentcore.conversation(conversation_id) ON DELETE CASCADE, principal_key text NOT NULL, role text NOT NULL, attached_at timestamptz NOT NULL DEFAULT now(), - PRIMARY KEY (principal_key, conversation_id) ); --- The listing filters by principal, so principal leads the primary key. This index serves the other --- direction, which reading and detaching one conversation's claims use. CREATE INDEX conversation_principal_conversation_idx ON agentcore.conversation_principal (conversation_id); --- No index on title. Searching the list is the consumer's, and a consumer who wants substring match --- adds their own GIN index over pg_trgm rather than paying for one nobody asked for. GRANT SELECT, INSERT, UPDATE, DELETE ON agentcore.conversation, agentcore.conversation_principal TO agentcore_writer; - --- Store 1 — the words of a conversation. One row per message, never one JSON blob per conversation. --- --- A child of conversation. The row must exist before a word may be written against it, which is what stops --- a conversation accumulating words no listing can reach. CREATE TABLE agentcore.conversation_message ( conversation_id text NOT NULL REFERENCES agentcore.conversation(conversation_id) ON DELETE CASCADE, ordinal integer NOT NULL, turn_index integer NOT NULL, role text NOT NULL, content jsonb NOT NULL, - - -- The handle an edit names its parent by. A client that edits an earlier message tells the host - -- which message the new one hangs off, and the host turns that name into an ordinal to know - -- where to cut. Position cannot answer it: the browser never learns an ordinal, and an ordinal - -- moves meaning under it the moment anything is deleted. - -- - -- Every row carries one. The client names the message it sent; the host names its own replies, - -- because the message an edit anchors on is usually a reply and no client can have named one - -- before it existed. message_id text NOT NULL, - + covers_up_to integer NULL, created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(), - PRIMARY KEY (conversation_id, ordinal), - - -- What the id -> ordinal lookup an edit does reads, and what stops two rows of one conversation - -- answering to one name. CONSTRAINT conversation_message_message_id_unique UNIQUE (conversation_id, message_id) ); CREATE INDEX conversation_message_updated_at_idx ON agentcore.conversation_message (updated_at); + CREATE INDEX conversation_message_turn_idx ON agentcore.conversation_message (conversation_id, turn_index); + CREATE INDEX conversation_message_retention_idx ON agentcore.conversation_message (conversation_id, updated_at DESC); --- Retention deletes the conversation itself and reaches these rows through the cascade, so it needs no --- privilege of its own here. -GRANT SELECT, INSERT, UPDATE, DELETE ON agentcore.conversation_message TO agentcore_writer; +CREATE INDEX conversation_message_summary_idx ON agentcore.conversation_message (conversation_id, ordinal DESC) WHERE covers_up_to IS NOT NULL; +GRANT SELECT, INSERT, UPDATE, DELETE ON agentcore.conversation_message TO agentcore_writer; --- The Responses continuation map: one serialized agent session per opaque id. --- --- A conversation id or a response id names no conversation and carries no state. This --- table is what it opens: the session envelope an AIAgent wrote, filed under --- the id the protocol handed out. It lives in this database beside the conversations --- rather than anywhere else because the envelope names a conversation whose words live --- in conversation_message: splitting the key from the words across databases would let --- a resume find one without the other. --- --- No foreign key to conversation. A continuation outlives the turns that filed it, and --- a swept conversation must not take the row that proves what its id once opened; an --- unknown id already fails closed at lookup, which is the only integrity this --- table needs. CREATE TABLE agentcore.response_continuation ( store_id text PRIMARY KEY, envelope jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); --- The writer files, reads, replaces, and forgets. Nothing here is append-only: --- a response id is filed once and a conversation id is replaced every turn. REVOKE ALL ON agentcore.response_continuation FROM PUBLIC; + REVOKE ALL ON agentcore.response_continuation FROM agentcore_writer; + GRANT SELECT, INSERT, UPDATE, DELETE ON agentcore.response_continuation TO agentcore_writer; --- Store 3 — the append-only record of what happened on a conversation. --- --- Two numbers, two owners, and the split is the point. event_id is IDENTITY and the CALL allocates --- it: an amendment has to name the event it corrects the instant that event is raised, so waiting --- for a store is not available. sequence is ORDER and the STORE allocates it: a per-conversation counter --- held by a session restarts at zero on the second session of one conversation, which is what a chat page --- reload is, and two app instances have no counter to share at all. --- --- Nothing sorts by event_id. UUID v7 is random within a millisecond and one turn raises three events --- inside one, so id order is not time order. Read the chain by sequence. CREATE TABLE agentcore.audit_event ( write_position bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, conversation_id text NOT NULL, @@ -188,40 +88,26 @@ CREATE TABLE agentcore.audit_event ( payload jsonb NOT NULL DEFAULT '{}'::jsonb, CONSTRAINT audit_event_conversation_sequence_unique UNIQUE (conversation_id, sequence), - - -- What makes a replayed batch a no-op instead of a duplicate. QueuedAuditSink logs and drops a - -- batch today rather than retrying it, so nothing exercises this yet — but the day a retry is - -- added, it must be safe by construction, not by care, and this constraint is what makes it so. CONSTRAINT audit_event_conversation_event_unique UNIQUE (conversation_id, event_id) ); --- No index for reading one conversation's chain is declared here, and that is not an omission: --- audit_event_conversation_sequence_unique is (conversation_id, sequence), so the constraint's own index already --- serves every "this conversation, in order" read. A second index on the same two columns in the same order --- would only cost every insert a second write. - --- Refusals 1, 2 and 3: the writer may only insert and read. --- --- The PUBLIC revoke is required and its absence was a real hole. A privilege held by PUBLIC is not --- removed by revoking from the role: with a GRANT ALL ... TO PUBLIC present, the other two statements --- ran clean and has_table_privilege('agentcore_writer','agentcore.audit_event','UPDATE') still returned true. REVOKE ALL ON agentcore.audit_event FROM PUBLIC; + REVOKE ALL ON agentcore.audit_event FROM agentcore_writer; + GRANT INSERT, SELECT ON agentcore.audit_event TO agentcore_writer; --- Refusals 4, 5 and 6: the table owner is refused as well. --- --- Know what these stop. They stop the writer role and they stop an accident. They do not stop an --- owner who means it: ALTER TABLE ... DISABLE TRIGGER USER leaves no trace, and --- SET session_replication_role = replica bypasses all three in one statement with no DDL. CREATE FUNCTION agentcore.agentcore_audit_refuse() RETURNS trigger LANGUAGE plpgsql AS $$ + BEGIN RAISE EXCEPTION 'audit_event is append-only. A correction is a new event that names the old one.'; END $$; CREATE TRIGGER audit_event_no_update BEFORE UPDATE ON agentcore.audit_event FOR EACH ROW EXECUTE FUNCTION agentcore.agentcore_audit_refuse(); + CREATE TRIGGER audit_event_no_delete BEFORE DELETE ON agentcore.audit_event FOR EACH ROW EXECUTE FUNCTION agentcore.agentcore_audit_refuse(); + CREATE TRIGGER audit_event_no_truncate BEFORE TRUNCATE ON agentcore.audit_event FOR EACH STATEMENT EXECUTE FUNCTION agentcore.agentcore_audit_refuse(); diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs index ff80c9d2..38f57ecc 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs @@ -65,6 +65,14 @@ await secrets }; } + /// + public int? GetContextWindow(LlmProviderConfiguration entry) + { + ArgumentNullException.ThrowIfNull(entry); + + return OpenAiContextWindows.Lookup(entry.Model); + } + /// Puts store, reasoning_effort and prompt_cache_key on every request this client sends. internal static IChatClient WithResponseDefaults(IChatClient client, string? effort) { diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs new file mode 100644 index 00000000..eb5036d4 --- /dev/null +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs @@ -0,0 +1,45 @@ +namespace AgentCore.Infrastructure.Llm.OpenAI; + +/// +/// A built-in table of OpenAI model context windows, keyed by model id prefix. +/// +internal static class OpenAiContextWindows +{ + private static readonly (string Prefix, int Tokens)[] Table = + [ + ("gpt-6-astra", 1_050_000), + ("gpt-5.6-sol", 1_050_000), + ("gpt-5.6-terra", 1_050_000), + ("gpt-5.6-luna", 1_050_000), + ("gpt-5.6-cyber", 400_000), + ("gpt-daybreak-red-latest", 400_000), + ("gpt-daybreak-blue-latest", 1_050_000), + ("gpt-5.4-nano", 400_000), + ("gpt-5.4", 1_050_000), + ("gpt-4.1-mini", 1_047_576), + ("gpt-4.1-nano", 1_047_576), + ("gpt-4.1", 1_047_576), + ]; + + /// Looks up a model id's context window by its longest matching prefix. + /// The providers.llm[].model value, such as gpt-4.1-mini-2025-04-14. + /// The window in tokens, or when no entry's prefix matches. + internal static int? Lookup(string modelId) + { + ArgumentException.ThrowIfNullOrEmpty(modelId); + + var best = -1; + int? tokens = null; + + foreach (var (prefix, value) in Table) + { + if (prefix.Length > best && modelId.StartsWith(prefix, StringComparison.Ordinal)) + { + best = prefix.Length; + tokens = value; + } + } + + return tokens; + } +} diff --git a/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt b/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt index 5a4f965c..2c9018af 100644 --- a/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt @@ -34,6 +34,7 @@ AgentCore.Infrastructure.Knowledge.VectorData.Qdrant.QdrantKnowledgeAdapter.UseA AgentCore.Infrastructure.Knowledge.VectorData.Qdrant.QdrantKnowledgeAdapter.UseMappers(params AgentCore.Application.Knowledge.IKnowledgePointMapper![]! mappers) -> AgentCore.Infrastructure.Knowledge.VectorData.Qdrant.QdrantKnowledgeAdapter! AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.CreateClientAsync(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.GetContextWindow(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry) -> int? AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.Kind.get -> string! AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.OpenAiChatClientAdapter() -> void AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.ResolveHostedTool(Microsoft.Extensions.AI.AITool! marker, AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry) -> Microsoft.Extensions.AI.AITool? From c1b92a2f18cc899e8b9fe3df0c19c07396a1b387 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sun, 20 Sep 2026 17:52:02 -0600 Subject: [PATCH 5/8] refactor: scan and remove unnecessary tests --- .../Configuration/AgentCompactionTests.cs | 87 ------ .../Compilation/AgentToolTests.cs | 10 +- .../Compilation/CompactionCompilationTests.cs | 270 ++---------------- .../Compilation/CompileTableTests.cs | 6 +- .../Compilation/GraphNoMatchTests.cs | 18 +- .../Compilation/GuardedGraphEdgeTests.cs | 18 +- .../Compilation/HostedWebSearchDropTests.cs | 33 +-- .../ConfigurationSchemaValidatorTests.cs | 20 -- .../Configuration/ExampleDocument.cs | 9 - .../ChatConversationTitlerTests.cs | 26 +- .../Conversation/ConversationsTests.cs | 54 +++- .../DelegatingConversationStoreTests.cs | 2 +- ...nMemoryConversationStoreSummaryRowTests.cs | 37 +++ ...nMemoryConversationStoreTranscriptTests.cs | 88 +----- .../InMemoryConversationStoreWindowTests.cs | 74 +++++ .../InMemoryConversationStoreAppendTests.cs | 9 +- .../Fakes/FakeChatClientFactory.cs | 9 +- .../Fakes/RecordingChatClientAdapter.cs | 5 + .../Fakes/RecordingConversationStore.cs | 8 +- .../Fakes/ThrowingConversationStore.cs | 2 +- ...ybridCachingKnowledgeRetrievalPortTests.cs | 4 +- .../Llm/CompositeChatClientFactoryTests.cs | 15 + .../Llm/HostedWebSearchCapabilityTests.cs | 13 +- .../Runtime/CappedToolCallFormatterTests.cs | 82 ------ .../Runtime/CompactionStrategyFactoryTests.cs | 187 ++++++++---- .../Runtime/ToolResultCapProviderTests.cs | 69 +++++ ...entCoreChatHistoryProviderTruncateTests.cs | 5 +- .../Transcript/CapturingChatClient.cs | 66 +++++ .../ConversationSessionCompactionEditTests.cs | 153 ++++++++++ ...nversationSessionCompactionFailureTests.cs | 162 +++++++++++ ...onversationSessionCompactionTestSupport.cs | 94 ++++++ .../ConversationSessionCompactionTests.cs | 192 +++++++++++++ ...ConversationSessionConversationRowTests.cs | 4 +- .../ConversationSessionOutsideAppendTests.cs | 8 +- .../ConversationSessionResumeTests.cs | 8 +- .../ConversationTranscriptCompactionTests.cs | 198 +++++++++++++ .../DependencyInjection/AddAgentCoreTests.cs | 7 - .../Endpoints/FileWireTests.cs | 5 +- .../Fakes/FakeChatClientAdapter.cs | 2 + .../AgentCore.Hosting.Tests.csproj | 1 + .../AgentCoreHostTests.cs | 11 +- .../ConfigurationSecretResolverTests.cs | 8 +- .../PostgresConversationStoreAppendTests.cs | 10 +- ...ostgresConversationStoreSummaryRowTests.cs | 42 +++ .../PostgresConversationStoreTruncateTests.cs | 11 +- .../PostgresConversationStoreWindowTests.cs | 78 +++++ .../PostgresConversationStoreWordsTests.cs | 45 +-- .../Llm/OpenAiContextWindowsTests.cs | 36 +++ .../ToolSeamTests.cs | 13 +- .../ConversationStoreReadAll.cs | 12 + .../ConversationStoreSummaryRowFacts.cs | 145 ++++++++++ .../DelegatingConversationStore.cs | 16 +- .../LambdaChatClientFactory.cs | 31 ++ .../RecordingChatClientFactory.cs | 2 + .../RoutingChatClientFactory.cs | 13 +- 55 files changed, 1761 insertions(+), 772 deletions(-) delete mode 100644 tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs create mode 100644 tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs create mode 100644 tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs delete mode 100644 tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs create mode 100644 tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs create mode 100644 tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs create mode 100644 tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs create mode 100644 tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs create mode 100644 tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs create mode 100644 tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs create mode 100644 tests/AgentCore.TestSupport/ConversationStoreReadAll.cs create mode 100644 tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs create mode 100644 tests/AgentCore.TestSupport/LambdaChatClientFactory.cs diff --git a/tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs b/tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs deleted file mode 100644 index 06262f40..00000000 --- a/tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs +++ /dev/null @@ -1,87 +0,0 @@ -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Schema; -using Xunit; - -namespace AgentCore.Application.Tests.Configuration; - -/// -/// : the key-by-key merge of one agent's compaction: block -/// against agents.defaults.compaction. -/// -public sealed class AgentCompactionTests -{ - [Fact] - public void Compose_NoBlockAnywhere_IsNull() - { - Assert.Null(AgentCompaction.Compose(defaults: null, Agent(compaction: null))); - } - - [Fact] - public void Compose_DefaultsOnly_IsInherited() - { - var resolved = AgentCompaction.Compose( - new AgentDefaults { Compaction = Block(CompactionStrategyKind.Truncate) }, - Agent(compaction: null)); - - Assert.NotNull(resolved); - Assert.Equal(CompactionStrategyKind.Truncate, resolved.Strategy); - } - - [Fact] - public void Compose_AgentOverridesDefaults_TakesTheAgent() - { - var resolved = AgentCompaction.Compose( - new AgentDefaults { Compaction = Block(CompactionStrategyKind.Truncate) }, - Agent(Block(CompactionStrategyKind.ToolResult))); - - Assert.NotNull(resolved); - Assert.Equal(CompactionStrategyKind.ToolResult, resolved.Strategy); - } - - [Fact] - public void Compose_UnsetKeys_TakeTheDocumentedDefaults() - { - var resolved = AgentCompaction.Compose( - defaults: null, - Agent(new CompactionConfiguration - { - Strategy = CompactionStrategyKind.ToolResult, - Trigger = new CompactionTriggerConfiguration { Tokens = 60000 }, - })); - - Assert.NotNull(resolved); - Assert.Equal(AgentCompaction.DefaultKeep, resolved.Keep); - Assert.Equal(AgentCompaction.DefaultFoldResultChars, resolved.FoldResultChars); - } - - [Fact] - public void Compose_NoTrigger_Throws() - { - var exception = Assert.Throws(() => AgentCompaction.Compose( - defaults: null, - Agent(new CompactionConfiguration { Strategy = CompactionStrategyKind.Truncate }))); - - Assert.Contains("exactly one", exception.Message, StringComparison.Ordinal); - } - - [Fact] - public void Compose_TwoTriggers_Throws() - { - Assert.Throws(() => AgentCompaction.Compose( - defaults: null, - Agent(new CompactionConfiguration - { - Strategy = CompactionStrategyKind.Truncate, - Trigger = new CompactionTriggerConfiguration { Tokens = 60000, Messages = 40 }, - }))); - } - - private static CompactionConfiguration Block(CompactionStrategyKind strategy) => new() - { - Strategy = strategy, - Trigger = new CompactionTriggerConfiguration { Tokens = 60000 }, - }; - - private static AgentConfiguration Agent(CompactionConfiguration? compaction) => - new() { Id = "reply", Compaction = compaction }; -} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs index d597aaee..43976a58 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs @@ -272,11 +272,11 @@ public void Rule16_ADelegatingDocument_BuildsTheInnerAgentOnce() var compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(factory))["main"]; - // Three declared agents, so three model resolutions. Two callers share the one specialist, - // and neither of them compiled a second copy of it. A fourth resolution would prove the - // opposite, because every ChatClientAgent this compiler builds asks the factory once. + // Three declared agents, so three model resolutions, each asking the factory twice: once + // for the compaction pipeline's summariser, once for its own ChatClientAgent. Two callers + // share the one specialist, and neither of them compiled a second copy of it. Assert.Equal(3, compiled.Agents.Count); - Assert.Equal(3, factory.Requested.Count); + Assert.Equal(6, factory.Requested.Count); } [Fact] @@ -293,7 +293,7 @@ public void Rule16_ADelegatingDocument_CompilesOnceThroughTheRegistry() Assert.Same(first, second); Assert.Equal(1, registry.CompileCount); - Assert.Equal(3, factory.Requested.Count); + Assert.Equal(6, factory.Requested.Count); } [Fact] diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs index 18911e92..be773889 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs @@ -2,142 +2,48 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Runtime.Harness; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; using AgentCore.Domain.Sources; -using Microsoft.Agents.AI; -using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; using Xunit; namespace AgentCore.Application.Tests.Configuration.Compilation; /// -/// The compaction: block reaching a compiled agent's context providers, and the trimming -/// reaching the model. +/// Compaction reaching a compiled agent's context providers, and the trimming reaching the model. +/// The block itself is D15's ledger: in +/// Runtime covers the stages and the unknown-model compile failure. /// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. public sealed class CompactionCompilationTests { [Fact] - public void Compile_AgentWithCompaction_GetsAProvider() + public void Compile_ADocumentThatStillWritesCompaction_FailsSchemaValidationLikeAnyUnknownKey() { - var providers = Providers(WithCompaction()); - - Assert.Contains(providers, provider => provider is CompactionProvider); - } - - [Fact] - public void Compile_AgentWithoutCompaction_GetsNoProvider() - { - var providers = Providers(WithoutCompaction()); - - Assert.DoesNotContain(providers, provider => provider is CompactionProvider); - } - - [Fact] - public void Compile_BlockOnOneAgentOnly_GivesOnlyThatAgentAProvider() - { - // There is no per-agent opt-out: an omitted block and an explicit null are one value in C#. - // Selective compaction is expressed by declaring the block per agent instead of on defaults. - var (withBlock, withoutBlock) = TwoAgentsOneWithCompaction(); - - Assert.Contains(withBlock, provider => provider is CompactionProvider); - Assert.DoesNotContain(withoutBlock, provider => provider is CompactionProvider); - } - - [Fact] - public void Compile_TriggerNamesTwoConditions_FailsNamingTheAgentAndThePointer() - { - var failure = Assert.Throws(() => CompileOne(TwoTriggerConditions())); - - Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); - Assert.Equal("/agents/items/0/compaction/trigger", Assert.Single(failure.Errors).Pointer); - Assert.Equal(ConfigurationCheck.DocumentSchema, Assert.Single(failure.Errors).Check); - } - - [Fact] - public async Task Compile_CompactionBlock_TrimsWhatTheModelSeesAcrossTurns() - { - // CompactionStrategyFactoryTests.Create_SameWordsTwiceFromEmptyState_Agrees calls the static - // CompactionProvider.CompactAsync directly, from empty state, twice — it never opens a session - // and cannot see the incremental path CompactionProvider actually runs in a compiled agent. This - // one runs a real compiled agent over several turns of one reused session, and reads back what - // the chat client was actually sent. Remove the CompactionProvider from - // AgentContextProviderCompiler.Build and this goes red: the model would then see every message - // the conversation holds, on every turn. - using SequencedChatClient reply = new("hello there."); - - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration - { - Id = "only", - Compaction = new CompactionConfiguration - { - Strategy = CompactionStrategyKind.Truncate, - Trigger = new CompactionTriggerConfiguration { Messages = 4 }, - Keep = 2, - }, - }, - ], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration { Agent = "only" }, - }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - var agent = Assert.Single(compiled.Agents.Values); - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); - - // AgentCoreChatHistoryProvider (this agent's ChatHistoryProvider, because SingleAgentRow sets - // SessionCarriesHistory) reads store 1, which nothing here writes to, so it always hands back an - // empty history and never grows the request on its own. The conversation this test measures is - // instead built by hand and re-sent whole on every turn — exactly the shape a resumed conversation - // replays, which is the case CompactionProvider's incremental path exists for. - List conversation = []; - var sizeBeforeTheLastCompaction = 0; - - const int turns = 6; - for (var turn = 0; turn < turns; turn++) - { - conversation.Add(new ChatMessage(ChatRole.User, $"turn {turn}")); - sizeBeforeTheLastCompaction = conversation.Count; - - var response = await agent.RunAsync(conversation, session, cancellationToken: token); - - conversation.AddRange(response.Messages); - } - - var lastRequestSize = reply.Requests[^1].Count; - - Assert.True( - lastRequestSize < sizeBeforeTheLastCompaction, - $"the model saw {lastRequestSize} messages on the last turn, of a conversation that held " - + $"{sizeBeforeTheLastCompaction} before compaction ran."); + const string document = """ + apiVersion: agentcore/v1 + agents: + defaults: + compaction: { strategy: truncate } + items: + - { id: only, instructions: "ok" } + entries: + main: + agent: only + """; + + var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Contains("compaction", failure.Message, StringComparison.Ordinal); } [Fact] - public async Task Compile_CompactionBlock_KeepsReaderContentOutOfTheStateBag() + public async Task Compile_AnAgent_KeepsReaderContentOutOfTheModelRequest() { - // CompactionProvider copies every message it saw into the session state bag, and the bag - // serialises with MAF's default options, which know none of AgentCore's content types. A - // tool-result message carrying a FileContent, RenderContent or SourceContent therefore made - // the end-of-turn state capture throw NotSupportedException at - // $.MessageGroups.Messages.Contents, and the compaction state for that turn was lost. using SequencedChatClient reply = new("noted."); - var compiled = CompileCompactingAgent(reply); + var compiled = CompileOneAgent(reply); var agent = Assert.Single(compiled.Agents.Values); var token = TestContext.Current.CancellationToken; var session = await agent.CreateSessionAsync(token); @@ -165,36 +71,18 @@ public async Task Compile_CompactionBlock_KeepsReaderContentOutOfTheStateBag() await agent.RunAsync(conversation, session, cancellationToken: token); - // Capture serialises the whole bag before it picks keys, so any non-empty key set walks - // past the compaction state. The harness keys are empty here: no harness: block. - var compactionKey = Assert.Single(Assert.Single(Providers(agent).OfType()).StateKeys); - var captured = HarnessSessionState.Capture(session, new HashSet([compactionKey], StringComparer.Ordinal)); - - Assert.Contains(compactionKey, captured.Keys); Assert.DoesNotContain( reply.Requests[^1].SelectMany(message => message.Contents), content => content is FileContent or RenderContent or SourceContent); } - private static CompiledAgent CompileCompactingAgent(SequencedChatClient reply) => ConfigurationCompiler.CompileAll( + private static CompiledAgent CompileOneAgent(SequencedChatClient reply) => ConfigurationCompiler.CompileAll( new AgentCoreConfiguration { ApiVersion = AgentCoreConfiguration.SupportedApiVersion, Agents = new AgentsConfiguration { - Items = - [ - new AgentConfiguration - { - Id = "only", - Compaction = new CompactionConfiguration - { - Strategy = CompactionStrategyKind.Truncate, - Trigger = new CompactionTriggerConfiguration { Messages = 4 }, - Keep = 2, - }, - }, - ], + Items = [new AgentConfiguration { Id = "only" }], }, Entries = new Dictionary { @@ -202,115 +90,5 @@ private static CompiledAgent CompileCompactingAgent(SequencedChatClient reply) = }, }, new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - private static AgentCoreConfiguration TwoTriggerConditions() => new() - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration - { - Id = "only", - Compaction = new CompactionConfiguration - { - Strategy = CompactionStrategyKind.ToolResult, - Trigger = new CompactionTriggerConfiguration { Tokens = 60000, Messages = 40 }, - }, - }, - ], - }, - }; - - private static AIAgent WithCompaction() => CompileOne(new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration - { - Id = "only", - Compaction = Block(), - }, - ], - }, - }); - - private static AIAgent WithoutCompaction() => CompileOne(new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration - { - Items = [new AgentConfiguration { Id = "only" }], - }, - }); - - private static (IEnumerable WithBlock, IEnumerable WithoutBlock) - TwoAgentsOneWithCompaction() - { - using SequencedChatClient reply = new("hello there."); - - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration { Id = "withBlock", Compaction = Block() }, - new AgentConfiguration { Id = "withoutBlock" }, - ], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration - { - Policy = new PolicyConfiguration - { - Initial = "opening", - Stages = - [ - new StageConfiguration { Id = "opening", Agent = "withBlock" }, - new StageConfiguration { Id = "closing", Agent = "withoutBlock" }, - ], - }, - }, - }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - return (Providers(compiled.Agents["withBlock"]), Providers(compiled.Agents["withoutBlock"])); - } - - private static CompactionConfiguration Block() => new() - { - Strategy = CompactionStrategyKind.ToolResult, - Trigger = new CompactionTriggerConfiguration { Tokens = 60000 }, - }; - - private static AIAgent CompileOne(AgentCoreConfiguration configuration) - { - using SequencedChatClient reply = new("hello there."); - - var compiled = ConfigurationCompiler.CompileAll( - configuration, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - return Assert.Single(compiled.Agents.Values); - } - - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; - } } #pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs index 57bfa28c..875bf17e 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs @@ -399,8 +399,10 @@ public void EveryAgent_TakesTheModelTheDocumentNames() document, new AgentCompilationContext(factory) { Knowledge = new StubKnowledgePort([]) })["phone"]; - // 5 agents on the stage machine, plus analyst and webchat, which policy: never reaches. - Assert.Equal(7, factory.Requested.Count); + // 5 agents on the stage machine, plus analyst and webchat, which policy: never reaches. Each + // asks the factory twice: once for the compaction pipeline's summariser, once for its own + // ChatClientAgent. + Assert.Equal(14, factory.Requested.Count); Assert.All(factory.Requested, model => Assert.Equal("reply", model!.Ref)); } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs index 82a76883..e90d268c 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs @@ -1,3 +1,4 @@ +using AgentCore.TestSupport; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -184,7 +185,7 @@ public Harness() _document = ConfigurationLoader.LoadYaml(NoMatchGraphYaml); GuardEvaluator guards = new(_document.Guards); - RoutingFactory models = new(); + RoutingChatClientFactory models = new(); models.Route("router", _router); models.Route("human", _human); @@ -244,19 +245,4 @@ public void Dispose() } } - /// Hands one offline client to each providers.llm[].as name. - private sealed class RoutingFactory : IChatClientFactory - { - private readonly Dictionary _byName = new(StringComparer.Ordinal); - - /// Binds one client to one model name. - /// The as name of one providers.llm entry. - /// The client that answers for it. - public void Route(string name, IChatClient client) => _byName[name] = client; - - public IChatClient GetChatClient(ModelReference? model) - => model is not null && _byName.TryGetValue(model.Ref, out var client) - ? client - : throw new KeyNotFoundException($"No offline client is routed to the model '{model?.Ref}'."); - } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs index 51615ed8..eb4fbe4a 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs @@ -1,3 +1,4 @@ +using AgentCore.TestSupport; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -289,7 +290,7 @@ public Harness(bool holdEscalatedReply = false) var document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); GuardEvaluator guards = new(document.Guards); - RoutingFactory models = new(); + RoutingChatClientFactory models = new(); models.Route("router", _router); models.Route("human", _human); models.Route("bot", _bot); @@ -323,19 +324,4 @@ public void Dispose() } } - /// Hands one offline client to each providers.llm[].as name. - private sealed class RoutingFactory : IChatClientFactory - { - private readonly Dictionary _byName = new(StringComparer.Ordinal); - - /// Binds one client to one model name. - /// The as name of one providers.llm entry. - /// The client that answers for it. - public void Route(string name, IChatClient client) => _byName[name] = client; - - public IChatClient GetChatClient(ModelReference? model) - => model is not null && _byName.TryGetValue(model.Ref, out var client) - ? client - : throw new KeyNotFoundException($"No offline client is routed to the model '{model?.Ref}'."); - } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs index f4b823d1..3f8e2329 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs @@ -30,7 +30,7 @@ public void Compile_CapableModel_KeepsTheTool() public void Compile_TunedMarker_ReachesTheModel() { HostedWebSearchTool tuned = new(new Dictionary { ["memory_limit"] = "4g" }); - var tools = BuildAgentTools("reply", model: null, new ScreeningChatClientFactory(tuned)); + var tools = BuildAgentTools("reply", model: null, ScreeningChatClientFactory(tuned)); Assert.Same(tuned, Assert.Single(tools.OfType())); } @@ -123,7 +123,7 @@ public async Task Compile_TwoAgentsOnDifferentModels_ThroughTheRealCompiler_Only }, }, }, - new AgentCompilationContext(new RoutingCapabilityChatClientFactory(capableRef, reply)) { Tools = registry })["main"]; + new AgentCompilationContext(RoutingCapabilityChatClientFactory(capableRef, reply)) { Tools = registry })["main"]; var token = TestContext.Current.CancellationToken; await compiled.Agents["capable"].RunAsync("hi", cancellationToken: token); @@ -137,14 +137,14 @@ private static ToolConfiguration SearchTool() => new() { Id = SearchToolId, Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }; private static List Tools(string agent, bool capable) - => BuildAgentTools(agent, model: null, SearchTool(), new ScreeningChatClientFactory(Marker(capable))); + => BuildAgentTools(agent, model: null, SearchTool(), ScreeningChatClientFactory(Marker(capable))); private static HostedWebSearchTool? Marker(bool capable) => capable ? new HostedWebSearchTool() : null; private static (List Tools, List Logs) ToolsAndLogs(string agent, bool capable) { RecordingLoggerFactory loggers = new(); - var tools = BuildAgentTools(agent, model: null, SearchTool(), new ScreeningChatClientFactory(Marker(capable)), loggers); + var tools = BuildAgentTools(agent, model: null, SearchTool(), ScreeningChatClientFactory(Marker(capable)), loggers); return (tools, [.. loggers.Of(18).Select(line => line.Message)]); } @@ -153,7 +153,7 @@ private static (List Capable, List Incapable) TwoAgents() const string capableRef = "vendor-a"; const string incapableRef = "vendor-b"; - var factory = new RoutingCapabilityChatClientFactory(capableRef); + var factory = RoutingCapabilityChatClientFactory(capableRef); var capable = BuildAgentTools("capable", new ModelReference { Ref = capableRef }, factory); var incapable = BuildAgentTools("incapable", new ModelReference { Ref = incapableRef }, factory); @@ -168,7 +168,7 @@ private static List ToolsFromHostSource(bool capable) Dictionary declared = new(StringComparer.Ordinal); var registry = BuildRegistry([new HostSearchToolSource(hostToolId)], []); - AgentCompilationContext context = new(new ScreeningChatClientFactory(Marker(capable))) { Tools = registry }; + AgentCompilationContext context = new(ScreeningChatClientFactory(Marker(capable))) { Tools = registry }; return AgentToolCompiler.Build(item, model: null, declared, context, "/agents/items/0", static _ => null) ?? []; } @@ -217,19 +217,12 @@ public ValueTask> ProvideAsync( [new ToolRegistration(id, "A vendor's own hosted search.", () => new HostedWebSearchTool())]); } - private sealed class RoutingCapabilityChatClientFactory(string capableRef, IChatClient? client = null) : IChatClientFactory - { - public IChatClient GetChatClient(ModelReference? model) => client ?? throw new NotSupportedException(); - - public AITool? ResolveHostedTool(AITool marker, ModelReference? model) => - string.Equals(model?.Ref, capableRef, StringComparison.Ordinal) ? marker : null; - } + /// Admits any hosted tool for only. + private static LambdaChatClientFactory RoutingCapabilityChatClientFactory(string capableRef, IChatClient? client = null) => new( + client is null ? null : _ => client, + (marker, model) => string.Equals(model?.Ref, capableRef, StringComparison.Ordinal) ? marker : null); - private sealed class ScreeningChatClientFactory(AITool? marker) : IChatClientFactory - { - public IChatClient GetChatClient(ModelReference? model) => throw new NotSupportedException(); - - public AITool? ResolveHostedTool(AITool asked, ModelReference? model) => - marker is not null && asked.GetType() == marker.GetType() ? marker : null; - } + /// Admits a hosted tool of 's type, answering with . + private static LambdaChatClientFactory ScreeningChatClientFactory(AITool? marker) => new( + hostedTool: (asked, _) => marker is not null && asked.GetType() == marker.GetType() ? marker : null); } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs index 8677cd48..0fa6dd2e 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs @@ -743,26 +743,6 @@ public void ANonBuiltinToolWithParameters_PassesCheckOne(string kind, string dis Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); } - [Theory] - [InlineData("{}")] - [InlineData("{ tokens: 60000, messages: 40 }")] - public void ACompactionTriggerNotNamingExactlyOneCondition_FailsWithThePointerOfTheTrigger(string trigger) - { - var document = $$""" - apiVersion: agentcore/v1 - agents: - defaults: - compaction: - strategy: truncate - trigger: {{trigger}} - """; - - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/agents/defaults/compaction/trigger"); - } - [Fact] public void AFullAgenticAgent_PassesCheckOne() { diff --git a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs index f9c31f61..b4ecb86c 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs @@ -120,7 +120,6 @@ internal static class ExampleDocument instructions: | knowledge: { mode: prefetch, limit: 5, citations: false } - compaction: { strategy: context_window, trigger: { messages: 40 }, keep: 6, foldResultChars: 300 } items: - { id: greeter, instructions: "", tools: [] } - { id: identifier, instructions: "", tools: [ lookup_order ] } @@ -439,14 +438,6 @@ internal static class ExampleDocument "mode": "prefetch", "limit": 5, "citations": false - }, - "compaction": { - "strategy": "context_window", - "trigger": { - "messages": 40 - }, - "keep": 6, - "foldResultChars": 300 } }, "items": [ diff --git a/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs b/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs index 1e718971..b0012c2a 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs @@ -1,7 +1,6 @@ using System.Runtime.CompilerServices; using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; -using AgentCore.Application.Ports; using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; using Xunit; @@ -61,6 +60,31 @@ public async Task GenerateAsync_StoppedPartWay_LeavesTheTitleAlone() Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); } + [Fact] + public async Task GenerateAsync_OneTurnWritingManyMessages_SendsOnlyTheNewestSix() + { + // Arrange: the store reads whole turns, so one wide turn hands back more than six rows. + // The cut is by message, not by turn. + InMemoryConversationStore conversations = new(); + await conversations.CreateAsync("c1", Token); + await conversations.AppendAsync( + "c1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "early"), "m0"), + .. Enumerable.Range(1, 7).Select(n => new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, $"m{n}"), $"m{n}")), + ], + cancellationToken: Token); + StubChatClient client = new("title"); + ChatConversationTitler titler = new(conversations, client); + + // Act + await CollectAsync(titler.GenerateAsync("c1", Token)); + + // Assert + var transcript = Assert.Single(client.Seen, message => message.Role == ChatRole.User).Text; + Assert.Equal("user: m2\nuser: m3\nuser: m4\nuser: m5\nuser: m6\nuser: m7\n", transcript.ReplaceLineEndings("\n")); + } + [Fact] public async Task GenerateFromAsync_MessagesFromTheCaller_StreamsThePiecesAndStoresTheWhole() { diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs index 9a4fa5d7..6ae4436c 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs @@ -62,7 +62,7 @@ public async Task DeleteAsync_NoBlobStore_DeletesTheRowAlone() } [Fact] - public async Task LoadAsync_ReturnsTheRowTheWordsAndOneLinkPerKeptFile() + public async Task LoadWindowAsync_ReturnsTheRowTheWordsAndOneLinkPerKeptFile() { // Arrange CountingBlobStore blobs = new(); @@ -73,7 +73,7 @@ public async Task LoadAsync_ReturnsTheRowTheWordsAndOneLinkPerKeptFile() await conversations.AppendMessageAsync("conversation-1", ReplyWith(("chart.png", "image/png")), token); // Act - var stored = await conversations.LoadAsync("conversation-1", token); + var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 10), token); // Assert Assert.NotNull(stored); @@ -85,13 +85,59 @@ public async Task LoadAsync_ReturnsTheRowTheWordsAndOneLinkPerKeptFile() } [Fact] - public async Task LoadAsync_AConversationThatWasNeverMade_IsNull() + public async Task LoadWindowAsync_AFullWindow_NamesTheTurnToReadBeforeNext_AndLinksThatWindowsFilesAlone() + { + // Arrange: turn 0 kept a file, turn 1 kept another. The window holds turn 1 only. + CountingBlobStore blobs = new(); + Conversations conversations = new(new InMemoryConversationStore(), blobs); + var token = TestContext.Current.CancellationToken; + await conversations.CreateAsync("conversation-1", token); + await conversations.AppendAsync( + "conversation-1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "chart it"), "m0"), + new ConversationMessageDraft(0, ReplyWith(("chart.png", "image/png")), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "rows too"), "m2"), + new ConversationMessageDraft(1, ReplyWith(("rows.csv", "text/csv")), "m3"), + ], + cancellationToken: token); + + // Act + var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 1), token); + + // Assert + Assert.NotNull(stored); + Assert.Equal(["m2", "m3"], stored.Messages.Select(message => message.MessageId)); + Assert.Equal(1, stored.OlderBefore); + Assert.Equal("rows.csv", Assert.Single(stored.Files).Blob.Name); + } + + [Fact] + public async Task LoadWindowAsync_AShortWindow_ReachedTheStart_AndNamesNoTurn() + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), blobs: null); + var token = TestContext.Current.CancellationToken; + await conversations.CreateAsync("conversation-1", token); + await conversations.AppendMessageAsync("conversation-1", new ChatMessage(ChatRole.User, "hello"), token); + + // Act + var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 5), token); + + // Assert + Assert.NotNull(stored); + Assert.Single(stored.Messages); + Assert.Null(stored.OlderBefore); + } + + [Fact] + public async Task LoadWindowAsync_AConversationThatWasNeverMade_IsNull() { // Arrange Conversations conversations = new(new InMemoryConversationStore(), blobs: null); // Act - var stored = await conversations.LoadAsync("conversation-1", TestContext.Current.CancellationToken); + var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 5), TestContext.Current.CancellationToken); // Assert Assert.Null(stored); diff --git a/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs b/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs index 06333ee0..e03b01c4 100644 --- a/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs @@ -41,7 +41,7 @@ await store.AppendAsync( // Assert Assert.Equal(1, store.Appends); - Assert.Single(await store.ReadAsync("c1", Token)); + Assert.Single(await store.ReadAllAsync("c1", Token)); } [Fact] diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs new file mode 100644 index 00000000..c2d44f85 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs @@ -0,0 +1,37 @@ +using AgentCore.Application.Conversation.Memory; +using AgentCore.TestSupport; +using Xunit; + +namespace AgentCore.Application.Tests.Conversation; + +/// The summary row facts of , against the in-memory store. +public sealed class InMemoryConversationStoreSummaryRowTests +{ + [Fact] + public Task ReadForSession_HandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers() + => ConversationStoreSummaryRowFacts.SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + + [Fact] + public Task ReadForSession_WithNoSummary_HandsBackEveryRow() + => ConversationStoreSummaryRowFacts.SessionReadWithNoSummaryHandsBackEveryRow(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + + [Fact] + public Task ConsumerReads_LeaveEverySummaryOut() + => ConversationStoreSummaryRowFacts.ConsumerReadsLeaveEverySummaryOut(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + + [Fact] + public Task Truncate_UnderWhatTheSummaryCovers_TakesTheSummary() + => ConversationStoreSummaryRowFacts.TruncateUnderWhatTheSummaryCoversTakesTheSummary(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + + [Fact] + public Task Truncate_AboveWhatTheSummaryCovers_KeepsTheSummaryWhateverItsOrdinal() + => ConversationStoreSummaryRowFacts.TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + + [Fact] + public Task Truncate_AboveTheSummary_LeavesEverythingUnderItAlone() + => ConversationStoreSummaryRowFacts.TruncateAboveTheSummaryLeavesEverythingUnderItAlone(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + + [Fact] + public Task OrdinalOf_FindsASpokenRow_AndNotASummary() + => ConversationStoreSummaryRowFacts.OrdinalOfFindsASpokenRowAndNotASummary(new InMemoryConversationStore(), TestContext.Current.CancellationToken); +} diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs index 0ff7a2bc..cd0c3a46 100644 --- a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs @@ -1,5 +1,6 @@ using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Transcript; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; @@ -10,28 +11,6 @@ public sealed class InMemoryConversationStoreTranscriptTests { private static CancellationToken Token => TestContext.Current.CancellationToken; - [Fact] - public async Task ReadAsync_AfterAppend_ReturnsTheRowsOldestFirst() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - - // Act - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "hi"), "m1"), - ], cancellationToken: Token); - - // Assert - var rows = await store.ReadAsync("c1", Token); - Assert.Equal(2, rows.Count); - Assert.Equal(0, rows[0].Ordinal); - Assert.Equal("hello", rows[0].Content.Text); - } - [Fact] public async Task RewriteAsync_AnExistingMessage_ReplacesItsContent() { @@ -47,7 +26,7 @@ await store.AppendAsync( await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.Assistant, "cut"), Token); // Assert - var rows = await store.ReadAsync("c1", Token); + var rows = await store.ReadAllAsync("c1", Token); Assert.Equal("cut", Assert.Single(rows).Content.Text); } @@ -68,8 +47,8 @@ await store.AppendAsync( // Assert Assert.Equal(1, erased); - Assert.Empty(await store.ReadAsync("c1", Token)); - Assert.Single(await store.ReadAsync("c2", Token)); + Assert.Empty(await store.ReadAllAsync("c1", Token)); + Assert.Single(await store.ReadAllAsync("c2", Token)); } [Fact] @@ -89,61 +68,6 @@ await store.AppendAsync( Assert.NotNull(conversation.LastMessageAt); } - [Fact] - public async Task ReadAsync_AConversationWithMessages_ReturnsThemOldestFirst() - { - // Arrange — the store numbers rows in draft order, so this pins the read order against the - // ordinal the store assigned rather than against the order the drafts happened to list. - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "first"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "second"), "m1"), - ], - cancellationToken: Token); - - // Act - var rows = await store.ReadAsync("c1", Token); - - // Assert - Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); - Assert.Equal(["first", "second"], rows.Select(row => row.Content.Text)); - } - - [Fact] - public async Task ReadAsync_AConversationThatHoldsNothing_IsEmpty() - { - // Arrange - InMemoryConversationStore store = new(); - - // Act - var rows = await store.ReadAsync("missing", Token); - - // Assert - Assert.Empty(rows); - } - - [Fact] - public async Task ReadAsync_AnotherConversationsMessages_AreNotReturned() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.CreateAsync("c2", Token); - await store.AppendAsync( - "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "mine"), "m0")], cancellationToken: Token); - await store.AppendAsync( - "c2", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "theirs"), "m0")], cancellationToken: Token); - - // Act - var rows = await store.ReadAsync("c1", Token); - - // Assert - Assert.Single(rows); - } - [Fact] public async Task EraseAsync_AConversation_TakesEveryRowAndReportsHowMany() { @@ -163,7 +87,7 @@ await store.AppendAsync( // Assert Assert.Equal(2, erased); - Assert.Empty(await store.ReadAsync("c1", Token)); + Assert.Empty(await store.ReadAllAsync("c1", Token)); } [Fact] @@ -182,6 +106,6 @@ await store.AppendAsync( await store.EraseAsync("c1", Token); // Assert - Assert.Single(await store.ReadAsync("c2", Token)); + Assert.Single(await store.ReadAllAsync("c2", Token)); } } diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs new file mode 100644 index 00000000..6d64d624 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs @@ -0,0 +1,74 @@ +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Transcript; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Conversation; + +/// Reading store 1 a window of turns at a time, newest turns first, every turn whole. +public sealed class InMemoryConversationStoreWindowTests +{ + private static CancellationToken Token => TestContext.Current.CancellationToken; + + /// Four turns. Turn 2 answers through a tool, so it holds four rows rather than two. + private static async Task FourTurnsAsync() + { + InMemoryConversationStore store = new(); + await store.CreateAsync("c1", Token); + await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q0"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a0"), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q1"), "m2"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a1"), "m3"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2"), "m4"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call", "lookup")]), "m5"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call", "found")]), "m6"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, "a2"), "m7"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.User, "q3"), "m8"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.Assistant, "a3"), "m9"), + ], cancellationToken: Token); + return store; + } + + [Fact] + public async Task ReadWindowAsync_NoStart_ReadsTheNewestTurnsWholeOldestRowFirst() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(null, 2), Token); + + Assert.Equal(["m4", "m5", "m6", "m7", "m8", "m9"], rows.Select(row => row.MessageId)); + } + + [Fact] + public async Task ReadWindowAsync_BeforeATurn_ReadsTheTurnsJustBelowIt() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(2, 2), Token); + + Assert.Equal(["m0", "m1", "m2", "m3"], rows.Select(row => row.MessageId)); + } + + [Fact] + public async Task ReadWindowAsync_PastTheStart_ReadsWhatIsLeft() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(1, 5), Token); + + Assert.Equal(["m0", "m1"], rows.Select(row => row.MessageId)); + } + + [Fact] + public async Task ReadWindowAsync_BeforeTheFirstTurn_ReadsNothing() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(0, 5), Token); + + Assert.Empty(rows); + } +} diff --git a/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs b/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs index b65c97c6..d89b532d 100644 --- a/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs @@ -1,8 +1,9 @@ using System.Text.RegularExpressions; -using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Conversation; using AgentCore.Application.Ports; using AgentCore.Application.Transcript; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; @@ -138,7 +139,7 @@ public async Task RewriteAsync_OneRow_ChangesOnlyThatRowsContent() await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.User, "corrected"), Token); // Assert - var rows = await store.ReadAsync("c1", Token); + var rows = await store.ReadAllAsync("c1", Token); Assert.Equal(["corrected", "second"], rows.Select(row => row.Content.Text)); } @@ -161,7 +162,7 @@ public async Task AppendAsync_AfterATruncate_NeverReusesTheOrdinalsItTook() } [Fact] - public async Task ReadAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() + public async Task AppendAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() { // Arrange IConversationStore store = new InMemoryConversationStore(); @@ -175,7 +176,7 @@ public async Task ReadAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRound await store.AppendMessageAsync("c1", message, Token); // Assert - var rows = await store.ReadAsync("c1", Token); + var rows = await store.ReadAllAsync("c1", Token); Assert.Equal("human", Assert.Single(rows).Content.AdditionalProperties?["speaker"]?.ToString()); } diff --git a/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs b/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs index 59e62913..b4d5c170 100644 --- a/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs +++ b/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs @@ -10,8 +10,13 @@ namespace AgentCore.Application.Tests.Fakes; internal sealed class FakeChatClientFactory : IChatClientFactory { private readonly IChatClient _client; + private readonly int _contextWindow; - public FakeChatClientFactory(IChatClient client) => _client = client; + public FakeChatClientFactory(IChatClient client, int contextWindow = 128_000) + { + _client = client; + _contextWindow = contextWindow; + } /// Gets every model reference this factory was asked for, in call order. public List Requested { get; } = []; @@ -25,4 +30,6 @@ public IChatClient GetChatClient(ModelReference? model) return _client; } + + public int? GetContextWindow(ModelReference? model) => _contextWindow; } diff --git a/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs b/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs index eb31e210..3e056cbb 100644 --- a/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs +++ b/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs @@ -17,6 +17,9 @@ internal sealed class RecordingChatClientAdapter : IChatClientAdapter public string Kind { get; } + /// Gets or sets the value answers, or . + public int? ContextWindow { get; set; } + /// Gets the as names this adapter built a client for, in build order. public IReadOnlyList BuiltNames => _builtNames; @@ -43,6 +46,8 @@ public ValueTask CreateClientAsync( _clients[entry.As] = client; return ValueTask.FromResult(client); } + + public int? GetContextWindow(LlmProviderConfiguration entry) => ContextWindow; } /// diff --git a/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs b/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs index 4146190b..050ed828 100644 --- a/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs +++ b/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs @@ -21,7 +21,7 @@ internal sealed class RecordingConversationStore() : DelegatingConversationStore /// Gets every rewrite the provider asked for, in order. public List Rewrites { get; } = []; - /// Gets how many times a whole conversation was read back. + /// Gets how many times a conversation was read back, by a consumer or by its session. public int Reads { get; private set; } /// Reads one conversation as the store holds it now, oldest message first. @@ -79,8 +79,12 @@ public override async ValueTask RewriteAsync( } /// - public override ValueTask> ReadAsync( + /// The rows are the ones somebody said: nothing here writes a summary row. + public override ValueTask> ReadForSessionAsync( string conversationId, CancellationToken cancellationToken = default) + => Read(conversationId); + + private ValueTask> Read(string conversationId) { lock (_lock) { diff --git a/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs b/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs index e18a2abb..54b88692 100644 --- a/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs +++ b/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs @@ -20,7 +20,7 @@ public override ValueTask RewriteAsync( string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) => throw new InvalidOperationException("the conversation store is down."); - public override ValueTask> ReadAsync( + public override ValueTask> ReadForSessionAsync( string conversationId, CancellationToken cancellationToken = default) => throw new InvalidOperationException("the conversation store is down."); diff --git a/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs b/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs index 852a785f..cf131104 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs @@ -73,9 +73,9 @@ public async Task A_cached_card_reads_back_whole() Assert.Equal("f85-2019", PayloadPath.Read(card.Extras, "model")); Assert.Equal(12L, PayloadPath.Read(card.Extras, "page")); Assert.Equal(1.5, PayloadPath.Read(card.Extras, "weight")); - Assert.Equal(false, PayloadPath.Read(card.Extras, "draft")); + Assert.False(Assert.IsType(PayloadPath.Read(card.Extras, "draft"))); Assert.Equal("owner-manual", PayloadPath.Read(card.Extras, "source.doc")); - Assert.Equal(["belt", "deck"], Assert.IsAssignableFrom>(PayloadPath.Read(card.Extras, "tags"))); + Assert.Equal(["belt", "deck"], Assert.IsType>(PayloadPath.Read(card.Extras, "tags"), exactMatch: false)); } [Fact] diff --git a/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs b/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs index 3a236e54..fa7caf25 100644 --- a/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs @@ -193,6 +193,21 @@ public async Task ADocumentWithNoModel_FailsAReferenceThatNamesNone() Assert.Contains("declares no model", failure.Message, StringComparison.Ordinal); } + // --------------------------------------------------------------------------------------------- + // GetContextWindow: forwards to the adapter of the entry the reference names. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task GetContextWindow_ANamedReference_ForwardsToItsOwnAdapter() + { + RecordingChatClientAdapter openai = new("openai") { ContextWindow = 128_000 }; + RecordingChatClientAdapter anthropic = new("anthropic") { ContextWindow = 200_000 }; + + using var factory = await Create(TwoVendorsYaml, openai, anthropic); + + Assert.Equal(128_000, factory.GetContextWindow(new ModelReference { Ref = "reply" })); + Assert.Equal(200_000, factory.GetContextWindow(new ModelReference { Ref = "fill" })); + } + // --------------------------------------------------------------------------------------------- // The temperature wrapper: the document keeps its setting, the vendor client stays one. // --------------------------------------------------------------------------------------------- diff --git a/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs b/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs index d2671745..adfab483 100644 --- a/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs +++ b/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs @@ -1,3 +1,4 @@ +using AgentCore.TestSupport; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; using Microsoft.Extensions.AI; @@ -25,9 +26,9 @@ public void Factory_UnknownReference_AnswersNull() { // A reference the document does not declare must not throw here. The compiler asks this // question while deciding whether to add a tool, and a missing model is reported elsewhere. - IChatClientFactory factory = new SilentFactory(); - - Assert.Null(factory.ResolveHostedTool(new HostedWebSearchTool(), new ModelReference { Ref = "absent" })); + // The interface default is under test; it is reachable only through the interface type. + Assert.Null(((IChatClientFactory)new RecordingChatClientFactory()) + .ResolveHostedTool(new HostedWebSearchTool(), new ModelReference { Ref = "absent" })); } private static LlmProviderConfiguration Entry(bool? webSearch) => new() @@ -48,10 +49,4 @@ public ValueTask CreateClientAsync( CancellationToken cancellationToken = default) => throw new NotSupportedException(); } - - private sealed class SilentFactory : IChatClientFactory - { - public IChatClient GetChatClient(ModelReference? model) - => throw new NotSupportedException(); - } } diff --git a/tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs b/tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs deleted file mode 100644 index a22b86f3..00000000 --- a/tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs +++ /dev/null @@ -1,82 +0,0 @@ -using AgentCore.Application.Runtime.Compaction; -using Microsoft.Agents.AI.Compaction; -using Microsoft.Extensions.AI; -using Xunit; - -namespace AgentCore.Application.Tests.Runtime; - -/// -/// : what a folded tool-call group carries forward. MAF's own -/// formatter copies the whole result, which grows the conversation it was asked to shrink. -/// -#pragma warning disable MAAI001 // CompactionMessageGroup and CompactionMessageIndex are the framework's own experimental surface. -public sealed class CappedToolCallFormatterTests -{ - [Fact] - public void Create_LongResult_IsCutToTheCap() - { - var written = CappedToolCallFormatter.Create(50)(Group("lookup", new string('x', 4000))); - - Assert.Contains("lookup", written, StringComparison.Ordinal); - Assert.True(written.Length < 200, $"the fold was {written.Length} characters, expected under 200"); - } - - [Fact] - public void Create_LongResult_SaysItWasCut() - { - var written = CappedToolCallFormatter.Create(50)(Group("lookup", new string('x', 4000))); - - Assert.Contains("…", written, StringComparison.Ordinal); - } - - [Fact] - public void Create_ShortResult_IsKeptWhole() - { - var written = CappedToolCallFormatter.Create(50)(Group("lookup", "sunny")); - - Assert.Contains("sunny", written, StringComparison.Ordinal); - Assert.DoesNotContain("…", written, StringComparison.Ordinal); - } - - [Fact] - public void Create_NoToolCalls_IsEmpty() - { - var group = Group(CompactionGroupKind.User, [new ChatMessage(ChatRole.User, "hello")]); - - Assert.Empty(CappedToolCallFormatter.Create(50)(group)); - } - - [Fact] - public void Create_TwoResultsShareOneConversationId_RendersTheLastOneWithoutThrowing() - { - var group = Group( - CompactionGroupKind.ToolCall, - [ - new ChatMessage(ChatRole.Assistant, - [new FunctionCallContent("conversation-1", "lookup", new Dictionary())]), - new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", "first")]), - new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", "last")]), - ]); - - var written = CappedToolCallFormatter.Create(50)(group); - - Assert.Contains("last", written, StringComparison.Ordinal); - Assert.DoesNotContain("first", written, StringComparison.Ordinal); - } - - // CompactionMessageGroup has no public constructor: its only public members are read-only - // properties, so a group has to come from the index that MAF's own strategies build it - // through. Passing a null tokenizer is fine — AddGroup falls back to an estimate, and this - // formatter never reads TokenCount. - private static CompactionMessageGroup Group(CompactionGroupKind kind, IReadOnlyList messages) => - new CompactionMessageIndex([], null!).AddGroup(kind, messages, turnIndex: null); - - private static CompactionMessageGroup Group(string tool, string result) => Group( - CompactionGroupKind.ToolCall, - [ - new ChatMessage(ChatRole.Assistant, - [new FunctionCallContent("conversation-1", tool, new Dictionary())]), - new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", result)]), - ]); -} -#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs index fc6217f7..f2d3cf95 100644 --- a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs @@ -1,6 +1,10 @@ using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using Microsoft.Agents.AI; using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; using Xunit; @@ -8,106 +12,163 @@ namespace AgentCore.Application.Tests.Runtime; /// -/// : resolved settings to a MAF strategy, and the trimming -/// the 2026-09-09 handoff recorded as unproven. +/// : the one fixed Cap -> Summary pair (D7, D9), +/// sized off the model's window, and the compiler's refusal when the window is unknown (D14, D15). /// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. public sealed class CompactionStrategyFactoryTests { [Theory] - [InlineData(CompactionStrategyKind.ToolResult, typeof(ToolResultCompactionStrategy))] - [InlineData(CompactionStrategyKind.Truncate, typeof(TruncationCompactionStrategy))] - [InlineData(CompactionStrategyKind.SlidingWindow, typeof(SlidingWindowCompactionStrategy))] - [InlineData(CompactionStrategyKind.ContextWindow, typeof(PipelineCompactionStrategy))] - public void Create_EachKind_BuildsItsStrategy(CompactionStrategyKind kind, Type expected) + [InlineData(0)] + [InlineData(-1)] + public void Create_AContextWindowThatIsNotPositive_Throws(int window) { - Assert.IsType(expected, CompactionStrategyFactory.Create(Resolved(kind, messages: 6))); + using SequencedChatClient summariser = new("summary."); + + Assert.Throws(() => CompactionStrategyFactory.Create(summariser, window)); } [Fact] - public async Task Create_Truncate_RemovesOldestAndKeepsNewest() + public async Task Create_AViewAt76PercentOfTheWindow_FiresAndLandsAtOrUnderTheTarget() { - var history = History(12); + // window = 1000: fire above 750 (75%), stop at or below 500 (50%). 20 pairs of 76-char + // messages sum to exactly 3040 UTF-8 bytes, which MAF's byte/4 estimator (no tokenizer + // supplied) reads as exactly 760 tokens - over the fire line. + using SequencedChatClient summariser = new("summary."); + var stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); + + var view = Conversation(pairs: 20, charsPerMessage: 76); var compacted = (await CompactionProvider.CompactAsync( - CompactionStrategyFactory.Create(Resolved(CompactionStrategyKind.Truncate, messages: 6)), - history, - cancellationToken: TestContext.Current.CancellationToken)).ToList(); + stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)).ToList(); - Assert.True(compacted.Count < history.Count, $"kept all {history.Count} messages"); - Assert.Equal(history[^1].Text, compacted[^1].Text); + var after = EstimatedTokens(compacted); + Assert.True(after <= 500, $"expected at or under the 500-token target, got {after}."); } [Fact] - public async Task Create_ToolResult_ShrinksTheText() + public async Task Create_AViewAt74PercentOfTheWindow_ComesBackUnchanged() { - var history = HistoryWithToolResults(6, resultChars: 4000); - var before = history.Sum(Size); + // Same shape, one token under the fire line: 20 pairs of 74-char messages are exactly + // 2960 bytes, which the byte/4 estimator reads as 740 tokens - at or under 750, so the + // summary compacts nothing. + using SequencedChatClient summariser = new("summary."); + var stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); - var compacted = (await CompactionProvider.CompactAsync( - CompactionStrategyFactory.Create(Resolved(CompactionStrategyKind.ToolResult, messages: 8)), - history, - cancellationToken: TestContext.Current.CancellationToken)).ToList(); + var view = Conversation(pairs: 20, charsPerMessage: 74); - var after = compacted.Sum(Size); + var compacted = (await CompactionProvider.CompactAsync( + stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)).ToList(); - // MAF's own formatter grows this number. The capping formatter is what makes it fall. - Assert.True(after < before / 2, $"the fold did not cap: {before} -> {after}"); + Assert.Equal(view.Count, compacted.Count); + for (var index = 0; index < view.Count; index++) + { + Assert.Same(view[index], compacted[index]); + } } [Fact] - public async Task Create_SameWordsTwiceFromEmptyState_Agrees() + public void Compile_AnUnknownModel_FailsNamingTheAgentAtThePointerEndingInModel() { - // The claim the resume design rests on: a resumed conversation builds a new session, so the provider - // starts empty and re-derives. If two passes disagreed, a resumed conversation would not match the - // call it resumed, and compaction state would have to be persisted. - var history = HistoryWithToolResults(6, resultChars: 4000); - var settings = Resolved(CompactionStrategyKind.ToolResult, messages: 8); - - var first = (await CompactionProvider.CompactAsync( - CompactionStrategyFactory.Create(settings), history, cancellationToken: TestContext.Current.CancellationToken)).ToList(); - var second = (await CompactionProvider.CompactAsync( - CompactionStrategyFactory.Create(settings), history, cancellationToken: TestContext.Current.CancellationToken)).ToList(); - - Assert.Equal(first.Count, second.Count); - Assert.Equal(first.Select(message => message.Text), second.Select(message => message.Text)); + using SequencedChatClient reply = new("hello there."); + + var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only" }], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "only" }, + }, + }, + new AgentCompilationContext(new NullWindowChatClientFactory(reply)))); + + Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); + Assert.EndsWith("/model", Assert.Single(failure.Errors).Pointer, StringComparison.Ordinal); } - private static int Size(ChatMessage message) => message.Text.Length - + message.Contents.OfType().Sum(c => c.Result?.ToString()?.Length ?? 0); + [Fact] + public void Compile_EveryAgentOfATwoAgentDocument_HasBothCompactionProviders() + { + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration { Id = "first" }, + new AgentConfiguration { Id = "second" }, + ], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration + { + Policy = new PolicyConfiguration + { + Initial = "opening", + Stages = + [ + new StageConfiguration { Id = "opening", Agent = "first" }, + new StageConfiguration { Id = "closing", Agent = "second" }, + ], + }, + }, + }, + }, + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + + Assert.All( + compiled.Agents.Values, + agent => + { + var providers = Providers(agent).ToList(); + var cap = Assert.Single(providers, provider => provider is ToolResultCapProvider); + var summary = Assert.Single(providers, provider => provider is SummaryRowProvider); + Assert.True(providers.IndexOf(cap) < providers.IndexOf(summary), "the cap runs before the summary."); + }); + } - private static ResolvedCompaction Resolved(CompactionStrategyKind kind, int messages) => new( - kind, - new CompactionTriggerConfiguration { Messages = messages }, - Keep: 2, - FoldResultChars: 200); + private static int EstimatedTokens(IReadOnlyList messages) + => messages.Sum(message => System.Text.Encoding.UTF8.GetByteCount(message.Text)) / 4; - private static List History(int count) + private static List Conversation(int pairs, int charsPerMessage) { List messages = []; - for (var index = 0; index < count / 2; index++) + for (var index = 0; index < pairs; index++) { - messages.Add(new ChatMessage(ChatRole.User, $"question {index}")); - messages.Add(new ChatMessage(ChatRole.Assistant, $"answer {index}")); + messages.Add(new ChatMessage(ChatRole.User, new string('x', charsPerMessage))); + messages.Add(new ChatMessage(ChatRole.Assistant, new string('x', charsPerMessage))); } return messages; } - private static List HistoryWithToolResults(int turns, int resultChars) + private static IEnumerable Providers(AIAgent agent) { - List messages = []; - for (var index = 0; index < turns; index++) - { - messages.Add(new ChatMessage(ChatRole.User, $"question {index}")); - messages.Add(new ChatMessage(ChatRole.Assistant, - [new FunctionCallContent($"conversation-{index}", "lookup", new Dictionary())])); - messages.Add(new ChatMessage(ChatRole.Tool, - [new FunctionResultContent($"conversation-{index}", new string('x', resultChars))])); - messages.Add(new ChatMessage(ChatRole.Assistant, $"answer {index}")); - } + var inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } - return messages; + /// Answers no window, as an adapter would for a model id its table does not carry. + private sealed class NullWindowChatClientFactory : IChatClientFactory + { + private readonly IChatClient _client; + + public NullWindowChatClientFactory(IChatClient client) => _client = client; + + public IChatClient GetChatClient(ModelReference? model) => _client; + + public int? GetContextWindow(ModelReference? model) => null; } } #pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs b/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs new file mode 100644 index 00000000..cd2ebabd --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs @@ -0,0 +1,69 @@ +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Transcript; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// : once the trigger fires, every tool result older than the +/// kept turns is cut to the cap, one message for one, with its id; nothing else moves. +/// +#pragma warning disable MAAI001 // The context constructors and triggers are the framework's own experimental surface. +public sealed class ToolResultCapProviderTests +{ + [Fact] + public async Task UnderTheTrigger_TheListComesBackAsItWas() + { + var provider = new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 3); + var input = new AIContext { Messages = Turns(2) }; + + var output = await provider.InvokingAsync(Context(input), TestContext.Current.CancellationToken); + + Assert.Same(input, output); + } + + [Fact] + public async Task OverTheTrigger_OldResultsAreCutInPlaceWithTheirIds_TheKeptTurnsAreNot() + { + var provider = new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 1, maxResultChars: 3); + var messages = Turns(3); + var input = new AIContext { Messages = messages }; + + var output = (await provider.InvokingAsync(Context(input), TestContext.Current.CancellationToken)).Messages!.ToList(); + + Assert.Equal(["res…", "res…", "result-2"], output.Where(message => message.Role == ChatRole.Tool).Select(Result)); + Assert.Equal(messages.Select(message => message.MessageId), output.Select(message => message.MessageId)); + for (var index = 0; index < messages.Count; index++) + { + if (messages[index].Role != ChatRole.Tool) + { + Assert.Same(messages[index], output[index]); + } + } + } + + private static string Result(ChatMessage message) + => Assert.Single(message.Contents.OfType()).Result!.ToString()!; + + /// Turns of a question, a call, its result result-N, and a reply; four messages each. + private static List Turns(int count) + { + List messages = []; + for (var turn = 0; turn < count; turn++) + { + messages.Add(new ChatMessage(ChatRole.User, $"q{turn}") { MessageId = $"m-{turn}-q" }); + messages.Add(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent($"call-{turn}", "tool")]) { MessageId = $"m-{turn}-call" }); + messages.Add(new ChatMessage(ChatRole.Tool, [new FunctionResultContent($"call-{turn}", $"result-{turn}")]) { MessageId = $"m-{turn}-result" }); + messages.Add(new ChatMessage(ChatRole.Assistant, $"a{turn}") { MessageId = $"m-{turn}-a" }); + } + + return messages; + } + + private static AIContextProvider.InvokingContext Context(AIContext input) + => new(StubAgent.Instance, new StubSession(), input); +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs index 7ba177ef..7a0dc07f 100644 --- a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs @@ -1,5 +1,6 @@ using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Transcript; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; using static AgentCore.Application.Tests.Transcript.AgentCoreChatHistoryProviderTestSupport; @@ -77,7 +78,7 @@ public async Task TruncateLastReply_WhileTheAppendIsStillWriting_ReachesTheStore Assert.True(cut); Assert.Equal( ["hello", "hi there", "order 41?", "it ships"], - (await store.ReadAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + (await store.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); } /// @@ -176,6 +177,6 @@ public async Task InMemoryStore_AfterTurnAndBargeIn_HoldsTheHeardTextInOrder() await provider.DrainAsync(session); Assert.Equal( ["order 41?", "it ships"], - (await store.ReadAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + (await store.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); } } diff --git a/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs b/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs new file mode 100644 index 00000000..67774023 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs @@ -0,0 +1,66 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Conversation; +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Transcript; +using AgentCore.TestSupport; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Xunit; + +namespace AgentCore.Application.Tests.Transcript; + +/// Answers each request in turn, keeps what it was asked, and runs a hook before answering. +/// Buffered path only, like . +internal sealed class CapturingChatClient : IChatClient +{ + private readonly Func _beforeReply; + + private readonly string[] _replies; + + private int _calls; + + public CapturingChatClient(Func beforeReply, params string[] replies) + { + _beforeReply = beforeReply; + _replies = replies; + } + + /// Gets every request this client answered, one role-prefixed line per message: its text, or its tool results. + public List> Requests { get; } = []; + + public async Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + var callIndex = _calls++; + Requests.Add([.. messages.Select(message => $"{message.Role}:{Words(message)}")]); + + await _beforeReply(callIndex).ConfigureAwait(false); + + return new ChatResponse(new ChatMessage(ChatRole.Assistant, _replies[callIndex])); + } + + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + => throw new NotSupportedException("These facts drive the buffered path only."); + + private static string Words(ChatMessage message) + => message.Text.Length > 0 + ? message.Text + : string.Join("|", message.Contents.OfType().Select(result => result.Result?.ToString())); + + public object? GetService(Type serviceType, object? serviceKey = null) => null; + + public void Dispose() + { + } +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs new file mode 100644 index 00000000..5bf01529 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs @@ -0,0 +1,153 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Conversation; +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Transcript; +using AgentCore.Domain.Audit; +using AgentCore.TestSupport; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Xunit; +using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; + +namespace AgentCore.Application.Tests.Transcript; + +/// +/// An edit against a conversation that carries a summary: cut above what the summary covers, +/// or reach under it and take the summary with the tail. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +public sealed class ConversationSessionCompactionEditTests +{ + [Fact] + public async Task ATurn_EditingAMessageUnderTheSummary_CutsTheStoreFirst_AndReadsBackOnlyWhatSurvived() + { + var store = new CountingReads(new InMemoryConversationStore()); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a0, rewritten reply"); + RecordingObserver observer = new(); + var session = CreateSession( + reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), observer: observer); + + await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // Turns 0 and 1 (q0/a0, q1/a1) are under the summary (D11: turn 2 stayed live as the newest + // existing turn). "m-0-a" — turn 0's reply — sits inside that span. + Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo == 3); + store.RowsRead.Clear(); + + await session.RunTurnAtOriginAsync( + "q0, rewritten", + new ConversationTurnOrigin("caller-2", "m-0-a") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The session's view is the raw rows again: the cut row's parent and the rewritten turn, + // nothing from the dropped summary and nothing that was cut. + var view = session.Compiled.History.Read(session.AgentSession!).Select(message => message.Text).ToList(); + Assert.Equal(["q0", "a0", "q0, rewritten", "a0, rewritten reply"], view); + Assert.Equal(view, (await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + Assert.Null(session.Compiled.History.Summary(session.AgentSession!)); + + // The store handed the session the two rows the cut kept, not the eight it held before the + // cut; the last read is this test's own. + Assert.Equal([2, 4], store.RowsRead); + + // Turns 1 through 3 (q1/a1, q2/a2, q3/a3) went, and the trail says so even though the session + // never held turn 1's rows. + var superseded = Assert.Single(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); + Assert.Equal("1", superseded.Payload![AuditPayloadKeys.WithdrewFromTurnIndex]); + Assert.Equal("3", superseded.Payload[AuditPayloadKeys.WithdrewThroughTurnIndex]); + } + + [Fact] + public async Task ATurn_EditingAMessageTheStoreDoesNotHold_CutsNothing_AndKeepsTheSummary() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a4"); + RecordingObserver observer = new(); + var session = CreateSession( + reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), observer: observer); + + await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + await session.RunTurnAtOriginAsync( + "q4", + new ConversationTurnOrigin("caller-2", "nobody") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // Nothing went: the summary stands, and the turn compacts again over it (D11: q3/a3 was the + // newest existing turn, so it stays live and the summary now covers everything before it). + Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q3", "assistant:a3", "user:q4"], reply.Requests[1]); + Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo == 5); + Assert.Equal(10, (await store.ReadAllAsync("c1", TestContext.Current.CancellationToken)).Count); + Assert.DoesNotContain(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); + } + + [Fact] + public async Task ATurn_EditingAMessageAboveTheSummary_CutsTheTailAndKeepsTheSummary() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a3, rewritten reply"); + var session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0)); + + await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The edit hangs off a2 (ordinal 5), above what the summary covers (3) and below the summary's + // own ordinal (6). The cut takes q3/a3 (7, 8) and leaves the summary standing. + await session.RunTurnAtOriginAsync( + "q3, rewritten", + new ConversationTurnOrigin("caller-2", "m-2-a") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal( + ["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3, rewritten"], + reply.Requests[1]); + var forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); + Assert.Single(forSession, row => row.CoversUpTo == 3); + Assert.Equal([4, 5, 6, 9, 10], forSession.Select(row => row.Ordinal)); + } + + /// Notes how many rows each read handed back. + private sealed class CountingReads(IConversationStore inner) : DelegatingConversationStore(inner) + { + public List RowsRead { get; } = []; + + public override async ValueTask> ReadForSessionAsync(string conversationId, CancellationToken cancellationToken = default) + => Note(await base.ReadForSessionAsync(conversationId, cancellationToken)); + + private IReadOnlyList Note(IReadOnlyList rows) + { + RowsRead.Add(rows.Count); + return rows; + } + } +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs new file mode 100644 index 00000000..d1ff04c5 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs @@ -0,0 +1,162 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Conversation; +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Transcript; +using AgentCore.TestSupport; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Xunit; +using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; + +namespace AgentCore.Application.Tests.Transcript; + +/// +/// Compaction that goes wrong costs the conversation nothing: a strategy that throws, one whose +/// output is not one summary, a refused row write, and words that move under the summariser. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +public sealed class ConversationSessionCompactionFailureTests +{ + [Fact] + public async Task CompactAsync_AStrategyThatThrows_LeavesTheTurnAndTheStoreUntouched_AndLogsEvent26() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + + var loggerFactory = new RecordingLoggerFactory(); + var session = CreateSession( + new ScriptedChatClient("a2"), store, conversationId: "c1", logger: loggerFactory.CreateLogger("test"), + compaction: SummaryOnly(new ThrowingCompactionStrategy())); + + var result = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Null(result.Failure); + Assert.Equal("a2", result.ReplyText); + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Single(loggerFactory.Of(26)); + } + + [Fact] + public async Task CompactAsync_AStrategyWhoseOutputIsNotOneSummary_KeepsTheView_AndLogsEvent27() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + + var loggerFactory = new RecordingLoggerFactory(); + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a2"); + var session = CreateSession( + reply, store, conversationId: "c1", logger: loggerFactory.CreateLogger("test"), + compaction: SummaryOnly(new TruncatingCompactionStrategy())); + + await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal(["user:q0", "assistant:a0", "user:q1", "assistant:a1", "user:q2"], Assert.Single(reply.Requests)); + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Single(loggerFactory.Of(27)); + } + + [Fact] + public async Task CompactAsync_TheRowWriteFails_IsReportedAsADroppedWriteAndTheTurnStands() + { + var store = new RefusingSummaryWrite(new InMemoryConversationStore()); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + RecordingObserver observer = new(); + var session = CreateSession( + new ScriptedChatClient("a3"), store, conversationId: "c1", + compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), + observer: observer); + + var result = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal("a3", result.ReplyText); + var dropped = Assert.Single(observer.Events, conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptWriteFailed); + Assert.Null(dropped.EventId); + Assert.Contains("summary row refused", dropped.Payload![ConversationEventPayloadKeys.Reason], StringComparison.Ordinal); + + // The words landed; only the summary did not. + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Equal(8, (await store.ReadAllAsync("c1", TestContext.Current.CancellationToken)).Count); + } + + [Fact] + public async Task CompactAsync_WordsMoveWhileTheSummariserRuns_TheSummaryIsRefused() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + ConversationSession? session = null; + var strategy = new BargingCompactionStrategy( + new SummarizationCompactionStrategy(new ScriptedChatClient("the gist of it"), CompactionTriggers.Always, minimumPreservedGroups: 0), + () => session!.Compiled.History.AppendTurn(session.AgentSession!, [new ChatMessage(ChatRole.User, "barged in")])); + session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: SummaryOnly(strategy)); + + var result = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal("a3", result.ReplyText); + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Null(session.Compiled.History.Summary(session.AgentSession!)); + Assert.Contains(await store.ReadAllAsync("c1", TestContext.Current.CancellationToken), row => row.Content.Text == "barged in"); + } + + /// A store that refuses to write a summary row and takes every other row. + private sealed class RefusingSummaryWrite(IConversationStore inner) : DelegatingConversationStore(inner) + { + public override ValueTask> AppendAsync( + string conversationId, IReadOnlyList messages, ConversationSessionState? state = null, CancellationToken cancellationToken = default) + => messages.Any(draft => draft.CoversUpTo is not null) + ? throw new InvalidOperationException("summary row refused") + : base.AppendAsync(conversationId, messages, state, cancellationToken); + } + + /// A strategy that always fires and always throws, to prove a failed compaction costs the turn nothing. + private sealed class ThrowingCompactionStrategy() : CompactionStrategy(CompactionTriggers.Always) + { + protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + => throw new InvalidOperationException("the summariser is down"); + } + + /// Drops the oldest group and inserts nothing: a shape no summary row can stand for. + private sealed class TruncatingCompactionStrategy() : CompactionStrategy(CompactionTriggers.Always) + { + protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + { + index.Groups[0].IsExcluded = true; + return new(true); + } + } + + /// Moves the words before forwarding to , as a writer racing the compaction would. + private sealed class BargingCompactionStrategy(CompactionStrategy inner, Action bargeIn) : CompactionStrategy(CompactionTriggers.Always) + { + protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + { + bargeIn(); + return inner.CompactAsync(index, logger, cancellationToken); + } + } +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs new file mode 100644 index 00000000..0cd8e023 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs @@ -0,0 +1,94 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Conversation; +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Transcript; +using AgentCore.TestSupport; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Xunit; + +namespace AgentCore.Application.Tests.Transcript; + +/// Builds the session and seeds the store the compaction facts run against. +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +internal static class ConversationSessionCompactionTestSupport +{ + /// + /// The stages the agent runs in place of the window-derived ones: sized to fire on a handful of + /// fixture messages. + /// + /// The reply model's window, in tokens. The fixed stages fire at 75% of it (D7). + internal static ConversationSession CreateSession( + IChatClient reply, IConversationStore store, string? conversationId = null, ILogger? logger = null, CompactionStages? compaction = null, int contextWindow = 128_000, IConversationObserver? observer = null) + { + var document = ConfigurationLoader.LoadYaml(ConversationSessionResumeTestSupport.OneAgentYaml); + var chatClients = new FakeChatClientFactory(reply, contextWindow); + var compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + ConversationStore = store, + Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), + Compaction = compaction, + })["main"]; + + var factory = new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null, + logger: logger, + observers: observer is null ? [] : [observer]); + + return factory.Create(conversationId); + } + + /// Stages whose cap never fires and whose summary always does. + internal static CompactionStages Summary(IChatClient summariser, int minimumPreservedGroups) + => SummaryOnly(new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups)); + + /// Stages whose cap never fires. + internal static CompactionStages SummaryOnly(CompactionStrategy summary) + => new(new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 1), summary); + + /// Seeds one turn of a plain question and reply, two rows. + internal static async Task SeedPlainTurnAsync(IConversationStore store, int turnIndex, string question, string reply) + { + await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, question), $"m-{turnIndex}-q"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, reply), $"m-{turnIndex}-a"), + ], + new ConversationSessionState { NextTurnIndex = turnIndex + 1 }, + TestContext.Current.CancellationToken); + } + + /// Seeds one turn of a question, a tool call and its result, and a reply — four rows. + internal static async Task SeedToolTurnAsync( + InMemoryConversationStore store, int turnIndex, string question, string toolName, string callId, string result, string reply) + { + await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, question), $"m-{turnIndex}-q"), + new ConversationMessageDraft( + turnIndex, + new ChatMessage(ChatRole.Assistant, [new FunctionCallContent(callId, toolName, new Dictionary(StringComparer.Ordinal))]), + $"m-{turnIndex}-call"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Tool, [new FunctionResultContent(callId, result)]), $"m-{turnIndex}-result"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, reply), $"m-{turnIndex}-a"), + ], + new ConversationSessionState { NextTurnIndex = turnIndex + 1 }, + TestContext.Current.CancellationToken); + } +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs new file mode 100644 index 00000000..3e23e1a5 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs @@ -0,0 +1,192 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Conversation; +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Transcript; +using AgentCore.TestSupport; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Xunit; +using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; + +namespace AgentCore.Application.Tests.Transcript; + +/// +/// Compaction driven end to end through a real session: the summary a real MAF strategy produces +/// lands as one row before the firing turn's own model call, is read back by the next session, +/// survives a barge-in, and a strategy that throws costs the conversation nothing. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. +public sealed class ConversationSessionCompactionTests +{ + [Fact] + public async Task TheFiringTurn_CallsTheSummariserOnce_AndSendsTheSummaryInItsOwnRequest() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + var summariser = new CapturingChatClient(_ => Task.CompletedTask, "the gist of it"); + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3"); + var session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(summariser, minimumPreservedGroups: 0)); + + await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Single(summariser.Requests); + + // Turn 2 (q2/a2) is the newest existing turn and stays live (D11); turns 0 and 1 go under the summary. + Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3"], Assert.Single(reply.Requests)); + + var forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); + var summary = Assert.Single(forSession, row => row.CoversUpTo is not null); + Assert.Equal((6, 3, 3), (summary.Ordinal, summary.CoversUpTo, summary.TurnIndex)); + Assert.Equal([4, 5, 6, 7, 8], forSession.Select(row => row.Ordinal)); + } + + [Fact] + public async Task ASecondSummary_FoldsTheFirstIntoItself_AndOneRowStands() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + var summariser = new CapturingChatClient(_ => Task.CompletedTask, "SUMMARY-ONE", "SUMMARY-TWO"); + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a4"); + var session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(summariser, minimumPreservedGroups: 0)); + + await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.RunTurnAsync("q4", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The second summariser call read the first summary, and the rows above it that came under the floor. + Assert.Equal(2, summariser.Requests.Count); + Assert.Equal(["assistant:[Summary]\nSUMMARY-ONE", "user:q2", "assistant:a2"], summariser.Requests[1].Skip(1)); + Assert.Equal(["assistant:[Summary]\nSUMMARY-TWO", "user:q3", "assistant:a3", "user:q4"], reply.Requests[1]); + + var forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); + var summary = Assert.Single(forSession, row => row.CoversUpTo is not null); + Assert.Equal((9, 5), (summary.Ordinal, summary.CoversUpTo)); + Assert.Contains("SUMMARY-TWO", summary.Content.Text, StringComparison.Ordinal); + Assert.DoesNotContain(forSession, row => row.Content.Text.Contains("SUMMARY-ONE", StringComparison.Ordinal)); + } + + [Fact] + public async Task TheSummary_ReadsTheCappedResults_AndCoversTheirRows() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedToolTurnAsync(store, turnIndex: 0, "q0", "toolA", "call-0", "result-A", "a0"); + await SeedToolTurnAsync(store, turnIndex: 1, "q1", "toolB", "call-1", "result-B", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + // Cap every result to 3 characters; summarise all but the newest four groups, which are + // q1 (call-1 + result-1) a1: the summary takes q0, its tool group and a0, rows 0-3. + var summariser = new CapturingChatClient(_ => Task.CompletedTask, "the gist of it"); + var stages = new CompactionStages( + new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), + new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups: 3)); + var session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: stages); + + await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + var request = Assert.Single(summariser.Requests); + Assert.Contains("tool:res…", request); + Assert.DoesNotContain("tool:result-A", request); + + var summary = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Equal(3, summary.CoversUpTo); + } + + [Fact] + public async Task ACapOnlyStage_WritesNoRow_AndTheRequestCarriesTheCappedResults() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedToolTurnAsync(store, turnIndex: 0, "q0", "toolA", "call-0", "result-A", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a2"); + var stages = new CompactionStages( + new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), + new SummarizationCompactionStrategy(new ScriptedChatClient("never"), CompactionTriggers.Never)); + var session = CreateSession(reply, store, conversationId: "c1", compaction: stages); + + await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + var request = Assert.Single(reply.Requests); + Assert.Contains("tool:res…", request); + Assert.DoesNotContain("tool:result-A", request); + + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + var stored = await store.ReadAllAsync("c1", TestContext.Current.CancellationToken); + Assert.Equal(8, stored.Count); + Assert.Contains(stored, row => row.Content.Contents.OfType().Any(result => result.Result?.ToString() == "result-A")); + } + + [Fact] + public async Task ATurn_WhoseViewCrossesThreeQuartersOfTheWindow_FiresTheRealPipeline() + { + // A 400-token window fires at 300 and stops at 200 (D7). One short turn stays well under; + // twelve turns of ~80 characters each land well over. + const int Window = 400; + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + + var quiet = CreateSession(new ScriptedChatClient("a1"), store, conversationId: "c1", contextWindow: Window); + await quiet.RunTurnAsync("q1", TestContext.Current.CancellationToken); + await quiet.FlushTranscriptAsync(); + + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + + var padding = new string('w', 80); + for (var turn = 2; turn < 14; turn++) + { + await SeedPlainTurnAsync(store, turn, $"q{turn} {padding}", $"a{turn} {padding}"); + } + + var loud = CreateSession(new ScriptedChatClient("the gist of it"), store, conversationId: "c1", contextWindow: Window); + await loud.RunTurnAsync("q14", TestContext.Current.CancellationToken); + await loud.FlushTranscriptAsync(); + + var summary = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Contains("the gist of it", summary.Content.Text, StringComparison.Ordinal); + Assert.DoesNotContain(await store.ReadAllAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + } + + [Fact] + public async Task ANewSession_OfAConversationWithASummary_OpensOnTheSummarisedView() + { + var store = new InMemoryConversationStore(); + await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + var first = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0)); + await first.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await first.FlushTranscriptAsync(); + + var reply = new CapturingChatClient(_ => Task.CompletedTask, "a4"); + var resumed = CreateSession(reply, store, conversationId: "c1"); + await resumed.RunTurnAsync("q4", TestContext.Current.CancellationToken); + + Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3", "assistant:a3", "user:q4"], Assert.Single(reply.Requests)); + Assert.NotNull(resumed.Compiled.History.Summary(resumed.AgentSession!)); + } +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs index e5ca914e..acefdf62 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs @@ -48,7 +48,7 @@ public async Task ATurn_CreatesTheConversationRow_BeforeItWritesAnyWord() // Assert await session.FlushTranscriptAsync(); Assert.NotNull(await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken)); - Assert.NotEmpty(await store.ReadAsync(session.ConversationId, TestContext.Current.CancellationToken)); + Assert.NotEmpty(await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken)); } [Fact] @@ -66,7 +66,7 @@ public async Task ATurn_WhenStoreZeroRefusesTheRow_FailsAndWritesNoWords() // Assert Assert.Equal("store 0 is down.", fault.Message); - Assert.Empty(await inner.ReadAsync(session.ConversationId, TestContext.Current.CancellationToken)); + Assert.Empty(await inner.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken)); } private static ConversationSession CreateSession(string yaml, IChatClient reply, IConversationStore store) diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs index 17cfc847..7a9ba43c 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs @@ -3,7 +3,7 @@ using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Runtime; -using AgentCore.Application.Transcript; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionResumeTestSupport; @@ -42,7 +42,7 @@ public async Task AfterTheSecondTurn_TheStoresOrdinalsAreDenseAndUnique() IConversationStore store = new InMemoryConversationStore(); var (session, _) = await RunTwoTurnsWithAnOutsideHandoffAsync(store); - var rows = await store.ReadAsync(session.ConversationId, TestContext.Current.CancellationToken); + var rows = await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken); var ordinals = rows.Select(row => row.Ordinal).ToArray(); for (var index = 1; index < ordinals.Length; index++) @@ -85,7 +85,7 @@ await store.AppendMessageAsync( ["my name is Dana", "hi Dana", "Dana joined", "still there?"], clientB.Requests[0].Select(message => message.Text)); - var rows = await store.ReadAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); + var rows = await store.ReadAllAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); Assert.Equal([0, 1, 2, 3, 4], rows.Select(row => row.Ordinal)); var record = await store.GetAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); @@ -121,7 +121,7 @@ await session.RunTurnAtOriginAsync( TestContext.Current.CancellationToken); await session.FlushTranscriptAsync(); - var rows = await store.ReadAsync(session.ConversationId, TestContext.Current.CancellationToken); + var rows = await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken); Assert.Equal(3, rows.Count); Assert.Equal("m1", rows[0].MessageId); diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs index 5638daab..c7ba917d 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs @@ -40,7 +40,7 @@ public async Task ASecondSessionOfOneConversation_KeepsEveryWordTheFirstOneWrote await SecondTurnAsync(store, conversationId, "what is my name?", "Dana"); - var rows = await store.ReadAsync(conversationId, TestContext.Current.CancellationToken); + var rows = await store.ReadAllAsync(conversationId, TestContext.Current.CancellationToken); // Two turns, each writing what the caller said and what it heard. A resumed session that // restarted its ordinals would overwrite the first pair rather than follow them. @@ -56,7 +56,7 @@ public async Task ASecondSessionOfOneConversation_CountsItsTurnAsTheNextOne() await SecondTurnAsync(store, conversationId, "what is my name?", "Dana"); - var rows = await store.ReadAsync(conversationId, TestContext.Current.CancellationToken); + var rows = await store.ReadAllAsync(conversationId, TestContext.Current.CancellationToken); // The turn index is the join to the audit chain, so a second turn numbered 0 would claim the // first turn's events as its own. @@ -71,7 +71,7 @@ public async Task ASessionOfAConversationWithNoWords_StartsAtTheBeginning() await SecondTurnAsync(store, "empty-conversation", "hello", "hi there"); - var rows = await store.ReadAsync("empty-conversation", TestContext.Current.CancellationToken); + var rows = await store.ReadAllAsync("empty-conversation", TestContext.Current.CancellationToken); Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); Assert.Equal([0, 0], rows.Select(row => row.TurnIndex)); @@ -96,7 +96,7 @@ await Assert.ThrowsAsync( /// A store 1 that takes words and will not give them back. private sealed class UnreadableConversationStore(IConversationStore inner) : DelegatingConversationStore(inner) { - public override ValueTask> ReadAsync( + public override ValueTask> ReadForSessionAsync( string conversationId, CancellationToken cancellationToken = default) => throw new InvalidOperationException("store 1 will not answer a read."); } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs new file mode 100644 index 00000000..86ae3984 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs @@ -0,0 +1,198 @@ +using AgentCore.Application.Transcript; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Transcript; + +/// +/// The summary row inside one transcript: the view it and the live rows build together, what a +/// compaction may cover, when one is refused, and which cuts must not reach under it. +/// +public sealed class ConversationTranscriptCompactionTests +{ + [Fact] + public void Read_WithASummary_EmitsItFirstThenTheLiveRowsAboveWhatItCovers() + { + var transcript = FiveTurns(); + + var row = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + Assert.NotNull(row); + Assert.Equal(10, row.Ordinal); + Assert.Equal(3, row.CoversUpTo); + Assert.Equal(["past", "q2", "a2", "q3", "a3", "q4", "a4"], transcript.Read().Select(message => message.Text)); + } + + [Fact] + public void Compact_ASecondSummary_ReplacesTheFirstAndCoversMore() + { + var transcript = FiveTurns(); + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + var row = transcript.Compact(Assistant("more past"), coversUpTo: 5, transcript.Revision); + + Assert.NotNull(row); + Assert.Equal(11, row.Ordinal); + Assert.Equal(["more past", "q3", "a3", "q4", "a4"], transcript.Read().Select(message => message.Text)); + Assert.Single(transcript.Messages, stored => stored.CoversUpTo is not null); + } + + [Fact] + public void Compact_ASummaryThatCoversLessThanTheStandingOne_Throws() + { + var transcript = FiveTurns(); + transcript.Compact(Assistant("past"), coversUpTo: 5, transcript.Revision); + + Assert.Throws(() => transcript.Compact(Assistant("less"), coversUpTo: 3, transcript.Revision)); + } + + [Fact] + public void Compact_RefusesACompactionReadBeforeTheWordsMoved() + { + var transcript = FiveTurns(); + var revision = transcript.Revision; + transcript.BeginTurn(5); + transcript.Append([User("q5")]); + + Assert.Null(transcript.Compact(Assistant("past"), coversUpTo: 3, revision)); + Assert.Null(transcript.Summary); + } + + [Fact] + public void Floor_ALiveRowReportsItsOwnOrdinal_AndTheSummaryReportsWhatItCovers() + { + var transcript = FiveTurns(); + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + var floor = transcript.Floor(); + + Assert.NotNull(floor); + Assert.Equal(3, floor.Value.CoversUpTo); + Assert.Equal( + [("past", 3), ("q2", 4), ("a2", 5), ("q3", 6), ("a3", 7)], + floor.Value.Messages.Select(view => (view.Message.Text, view.LastOrdinal))); + } + + [Fact] + public void Floor_IsNothing_WhenOneTurnIsAllThatIsLive() + { + var transcript = new ConversationTranscript { ConversationId = "c1" }; + transcript.BeginTurn(0); + transcript.Append([User("q0"), Assistant("a0")]); + + Assert.Null(transcript.Floor()); + + // A summary that covers everything but the newest turn: nothing lies before that turn either. + var five = FiveTurns(); + five.Compact(Assistant("past"), coversUpTo: 7, five.Revision); + Assert.Null(five.Floor()); + } + + [Fact] + public void Floor_LeavesTheSummaryOutOfTheNewestTurn_WhenTheTurnThatWroteItNeverLanded() + { + // The summary carries turn 5, but turn 5's own rows never landed. Turn 4 is still the newest + // live turn, so it stays out of the floor. + var transcript = FiveTurns(); + transcript.BeginTurn(5); + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + var floor = transcript.Floor(); + + Assert.NotNull(floor); + Assert.Equal(["past", "q2", "a2", "q3", "a3"], floor.Value.Messages.Select(view => view.Message.Text)); + } + + [Fact] + public void CanTruncateFrom_UnderASummary_OnlyARowAboveWhatItCoversWillDo() + { + var transcript = FiveTurns(); + Assert.True(transcript.CanTruncateFrom(null)); + Assert.True(transcript.CanTruncateFrom("nobody")); + + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + Assert.False(transcript.CanTruncateFrom(null)); + Assert.False(transcript.CanTruncateFrom("nobody")); + Assert.True(transcript.CanTruncateFrom(transcript.Messages.Single(stored => stored.Ordinal == 4).MessageId)); + } + + [Fact] + public void TruncateFrom_UnderWhatTheSummaryCovers_Refuses() + { + var transcript = FiveTurns(); + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + Assert.Throws(() => transcript.TruncateFrom(3)); + } + + [Fact] + public void TruncateFrom_AboveWhatTheSummaryCovers_CutsTheLiveRowsAndKeepsTheSummary() + { + // The summary sits at ordinal 10, above the cut, and stays: it was written after the rows it + // does not cover, so its ordinal says nothing about where the cut falls. + var transcript = FiveTurns(); + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + + var withdrawn = transcript.TruncateFrom(6); + + Assert.Equal(new WithdrawnTurns(3, 4), withdrawn); + Assert.Equal(["past", "q2", "a2"], transcript.Read().Select(message => message.Text)); + Assert.NotNull(transcript.Summary); + Assert.Equal(5, transcript.LastAssistantOrdinal); + } + + [Fact] + public void Resync_WithTheSummaryAndTheRowsAboveIt_BuildsTheSameView() + { + var transcript = new ConversationTranscript { ConversationId = "c1" }; + + transcript.Resync( + [Row(4, 2, "q2", "m4"), Row(5, 2, "a2", "m5"), Summary(6, 3, "past", coversUpTo: 3), Row(7, 3, "q3", "m7")], + nextOrdinal: 8); + + Assert.Equal(["past", "q2", "a2", "q3"], transcript.Read().Select(message => message.Text)); + Assert.Equal(3, transcript.Summary?.CoversUpTo); + Assert.Equal(5, transcript.LastAssistantOrdinal); + } + + [Fact] + public void TruncateLastReply_NeverRewritesTheSummary() + { + // The summary is an assistant message with text, in the same turn as the reply. A barge-in + // must cut the reply and leave the summary whole. + var transcript = FiveTurns(); + transcript.BeginTurn(5); + transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + transcript.Append([User("q5"), Assistant("a5 in full")]); + + var rows = transcript.TruncateLastReply("a5"); + + Assert.Equal("a5", Assert.Single(rows).Content.Text); + Assert.Equal("past", transcript.Summary?.Message.Text); + } + + /// Turns 0-4, ordinals 0-9: q0/a0 .. q4/a4. + private static ConversationTranscript FiveTurns() + { + var transcript = new ConversationTranscript { ConversationId = "c1" }; + for (var turn = 0; turn < 5; turn++) + { + transcript.BeginTurn(turn); + transcript.Append([User($"q{turn}"), Assistant($"a{turn}")]); + } + + return transcript; + } + + /// A row whose role follows its text: a question is the user's, anything else the assistant's. + private static ConversationMessage Row(int ordinal, int turnIndex, string text, string messageId) + => new("c1", ordinal, turnIndex, new ChatMessage(text.StartsWith('q') ? ChatRole.User : ChatRole.Assistant, text), messageId); + + private static ConversationMessage Summary(int ordinal, int turnIndex, string text, int coversUpTo) + => new("c1", ordinal, turnIndex, Assistant(text), $"s{ordinal}") { CoversUpTo = coversUpTo }; + + private static ChatMessage User(string text) => new(ChatRole.User, text); + + private static ChatMessage Assistant(string text) => new(ChatRole.Assistant, text); +} diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs index 4876502a..c952c0ed 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs @@ -1431,13 +1431,6 @@ public override ValueTask RewriteAsync( string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) => ValueTask.CompletedTask; - public override ValueTask> ReadAsync( - string conversationId, CancellationToken cancellationToken = default) - { - IReadOnlyList rows = []; - return ValueTask.FromResult(rows); - } - public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) => ValueTask.FromResult(0); diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs index 9cf66f4f..37769cdc 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs @@ -1,8 +1,9 @@ using System.Runtime.CompilerServices; using System.Text.Json; -using AgentCore.Application.Conversation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Conversation; using AgentCore.AspNetCore.Tests.Fakes; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; using Xunit; @@ -98,7 +99,7 @@ public async Task AToolThatPublishes_ReachesTheBrowserAsAFilePartAndTheTranscrip // And a later read of the transcript links the same file again. var conversations = host.Services.GetRequiredService(); - var stored = await conversations.ReadAsync(ConversationId, TestContext.Current.CancellationToken); + var stored = await conversations.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken); var links = await conversations.LinkFilesAsync(ConversationId, stored.Select(row => row.Content), TestContext.Current.CancellationToken); var link = Assert.Single(links); diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs index cce7cd17..407a9c4f 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs @@ -24,4 +24,6 @@ public ValueTask CreateClientAsync( ISecretResolverPort? secrets, CancellationToken cancellationToken = default) => ValueTask.FromResult(_client()); + + public int? GetContextWindow(LlmProviderConfiguration entry) => 128_000; } diff --git a/tests/AgentCore.Hosting.Tests/AgentCore.Hosting.Tests.csproj b/tests/AgentCore.Hosting.Tests/AgentCore.Hosting.Tests.csproj index 71895a5a..9f31a865 100644 --- a/tests/AgentCore.Hosting.Tests/AgentCore.Hosting.Tests.csproj +++ b/tests/AgentCore.Hosting.Tests/AgentCore.Hosting.Tests.csproj @@ -7,6 +7,7 @@ + diff --git a/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs b/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs index ef1b4653..6f7aa992 100644 --- a/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs +++ b/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs @@ -1,3 +1,4 @@ +using AgentCore.TestSupport; using System.Text.Json.Nodes; using AgentCore.Application.Audit; using AgentCore.Application.Audit.Memory; @@ -65,12 +66,6 @@ public void Dispose() } } - /// The factory behind every model reference in these tests. - private sealed class FakeChatClientFactory : IChatClientFactory - { - public IChatClient GetChatClient(ModelReference? model) => new FakeChatClient(); - } - // --------------------------------------------------------------------------------------------- // Who wins. The host does, on every seam, because its callback runs last. // --------------------------------------------------------------------------------------------- @@ -239,7 +234,7 @@ public async Task AnMcpServerThatCannotBeReachedFailsTheStartNamingTheServer() builder.AddAgentCoreHost(options => { options.Configuration = ConfigurationLoader.LoadYaml(McpDocument); - options.UseChatClients(_ => new FakeChatClientFactory()); + options.UseChatClients(_ => new RecordingChatClientFactory(new FakeChatClient())); }); await using var app = builder.Build(); @@ -477,7 +472,7 @@ private static async Task BuildAsync( builder.AddAgentCoreHost(options => { options.Configuration = ConfigurationLoader.LoadYaml(document); - options.UseChatClients(_ => new FakeChatClientFactory()); + options.UseChatClients(_ => new RecordingChatClientFactory(new FakeChatClient())); configure?.Invoke(options); }); diff --git a/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs b/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs index e2ab91aa..1f82b179 100644 --- a/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs +++ b/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs @@ -1,3 +1,4 @@ +using AgentCore.TestSupport; using AgentCore.Application.Ports; using AgentCore.Application.Configuration.Parsing; using AgentCore.AspNetCore.DependencyInjection; @@ -151,18 +152,13 @@ private static async Task BuildAsync( builder.AddAgentCoreHost(options => { options.Configuration = ConfigurationLoader.LoadYaml(Document); - options.UseChatClients(_ => new FakeSecretChainChatClientFactory()); + options.UseChatClients(_ => new RecordingChatClientFactory(new FakeSecretChainChatClient())); configure(options); }); return builder.Build(); } - private sealed class FakeSecretChainChatClientFactory : IChatClientFactory - { - public IChatClient GetChatClient(ModelReference? model) => new FakeSecretChainChatClient(); - } - private sealed class FakeSecretChainChatClient : IChatClient { public Task GetResponseAsync( diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs index 139b7276..edb60682 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs @@ -1,9 +1,11 @@ +using System.Text.Json; using System.Text.RegularExpressions; using AgentCore.Application.Conversation; using AgentCore.Application.Ports; using AgentCore.Application.Transcript; using AgentCore.Infrastructure.Conversation.Postgres; using AgentCore.Infrastructure.Tests.Database.Postgres; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; @@ -134,7 +136,7 @@ async Task WriteFiftyAsync(string label) await Task.WhenAll(WriteFiftyAsync("a"), WriteFiftyAsync("b")); // Assert - var rows = await store.ReadAsync("c1", Token); + var rows = await store.ReadAllAsync("c1", Token); Assert.Equal(100, rows.Count); Assert.Equal(Enumerable.Range(0, 100), rows.Select(row => row.Ordinal).Order()); } @@ -167,7 +169,7 @@ public async Task RewriteAsync_OneRow_ChangesOnlyThatRowsContent() await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.User, "corrected"), Token); // Assert - var rows = await store.ReadAsync("c1", Token); + var rows = await store.ReadAllAsync("c1", Token); Assert.Equal(["corrected", "second"], rows.Select(row => row.Content.Text)); } @@ -190,7 +192,7 @@ public async Task AppendAsync_AfterATruncate_NeverReusesTheOrdinalsItTook() } [PostgresFact] - public async Task ReadAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() + public async Task AppendAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() { // Arrange IConversationStore store = new PostgresConversationStore(DataSource); @@ -204,7 +206,7 @@ public async Task ReadAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRound await store.AppendMessageAsync("c1", message, Token); // Assert - var rows = await store.ReadAsync("c1", Token); + var rows = await store.ReadAllAsync("c1", Token); Assert.Equal("human", Assert.Single(rows).Content.AdditionalProperties?["speaker"]?.ToString()); } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs new file mode 100644 index 00000000..45f8d673 --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs @@ -0,0 +1,42 @@ +using AgentCore.Application.Ports; +using AgentCore.Infrastructure.Conversation.Postgres; +using AgentCore.Infrastructure.Tests.Database.Postgres; +using AgentCore.TestSupport; + +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; + +/// The summary row facts of , against PostgreSQL. +public sealed class PostgresConversationStoreSummaryRowTests : PostgresDatabaseTest +{ + protected override bool Migrated => true; + + private IConversationStore Store => new PostgresConversationStore(DataSource); + + [PostgresFact] + public Task ReadForSession_HandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers() + => ConversationStoreSummaryRowFacts.SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(Store, Token); + + [PostgresFact] + public Task ReadForSession_WithNoSummary_HandsBackEveryRow() + => ConversationStoreSummaryRowFacts.SessionReadWithNoSummaryHandsBackEveryRow(Store, Token); + + [PostgresFact] + public Task ConsumerReads_LeaveEverySummaryOut() + => ConversationStoreSummaryRowFacts.ConsumerReadsLeaveEverySummaryOut(Store, Token); + + [PostgresFact] + public Task Truncate_UnderWhatTheSummaryCovers_TakesTheSummary() + => ConversationStoreSummaryRowFacts.TruncateUnderWhatTheSummaryCoversTakesTheSummary(Store, Token); + + [PostgresFact] + public Task Truncate_AboveWhatTheSummaryCovers_KeepsTheSummaryWhateverItsOrdinal() + => ConversationStoreSummaryRowFacts.TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(Store, Token); + + [PostgresFact] + public Task Truncate_AboveTheSummary_LeavesEverythingUnderItAlone() + => ConversationStoreSummaryRowFacts.TruncateAboveTheSummaryLeavesEverythingUnderItAlone(Store, Token); + + [PostgresFact] + public Task OrdinalOf_FindsASpokenRow_AndNotASummary() + => ConversationStoreSummaryRowFacts.OrdinalOfFindsASpokenRowAndNotASummary(Store, Token); +} diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs index 58cc2e00..61cad129 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs @@ -2,6 +2,7 @@ using AgentCore.Application.Transcript; using AgentCore.Infrastructure.Conversation.Postgres; using AgentCore.Infrastructure.Tests.Database.Postgres; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Npgsql; using Xunit; @@ -41,8 +42,8 @@ await store.AppendAsync( var went = await store.TruncateAsync("C1", 2, Token); - Assert.Equal(2, went); - var rows = await store.ReadAsync("C1", Token); + Assert.Equal(new ConversationCut(2, new WithdrawnTurns(1, 1)), went); + var rows = await store.ReadAllAsync("C1", Token); Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); } @@ -70,7 +71,7 @@ await store.AppendAsync( state: null, Token); - var rows = await store.ReadAsync("C1", Token); + var rows = await store.ReadAllAsync("C1", Token); Assert.Equal([0, 1, 3], rows.Select(row => row.Ordinal)); Assert.Equal([0, 0, 2], rows.Select(row => row.TurnIndex)); } @@ -85,7 +86,7 @@ await store.AppendAsync( state: null, Token); - Assert.Equal("m0", (await store.ReadAsync("C1", Token))[0].MessageId); + Assert.Equal("m0", (await store.ReadAllAsync("C1", Token))[0].MessageId); var clash = await Record.ExceptionAsync( () => store.AppendAsync( @@ -115,6 +116,6 @@ await store.AppendAsync( Assert.Equal("collecting", record?.State?.Stage); Assert.Equal(1, record?.NextOrdinal); Assert.Equal(1, record?.State?.NextTurnIndex); - Assert.Empty(await store.ReadAsync("C1", Token)); + Assert.Empty(await store.ReadAllAsync("C1", Token)); } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs new file mode 100644 index 00000000..ed4f7fce --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs @@ -0,0 +1,78 @@ +using AgentCore.Application.Transcript; +using AgentCore.Infrastructure.Conversation.Postgres; +using AgentCore.Infrastructure.Tests.Database.Postgres; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; + +/// Reading store 1 in PostgreSQL a window of turns at a time: newest turns first, every turn whole. +public sealed class PostgresConversationStoreWindowTests : PostgresDatabaseTest +{ + /// + protected override bool Migrated => true; + + /// Four turns. Turn 2 answers through a tool, so it holds four rows rather than two. + private async Task FourTurnsAsync() + { + PostgresConversationStore store = new(DataSource); + await store.CreateAsync("C1", Token); + await store.AppendAsync( + "C1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q0"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a0"), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q1"), "m2"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a1"), "m3"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2"), "m4"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call", "lookup")]), "m5"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call", "found")]), "m6"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, "a2"), "m7"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.User, "q3"), "m8"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.Assistant, "a3"), "m9"), + ], + state: null, + Token); + return store; + } + + [PostgresFact] + public async Task ReadWindow_NoStart_ReadsTheNewestTurnsWholeOldestRowFirst() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(null, 2), Token); + + Assert.Equal(["m4", "m5", "m6", "m7", "m8", "m9"], rows.Select(row => row.MessageId)); + } + + [PostgresFact] + public async Task ReadWindow_BeforeATurn_ReadsTheTurnsJustBelowIt() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(2, 2), Token); + + Assert.Equal(["m0", "m1", "m2", "m3"], rows.Select(row => row.MessageId)); + } + + [PostgresFact] + public async Task ReadWindow_PastTheStart_ReadsWhatIsLeft() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(1, 5), Token); + + Assert.Equal(["m0", "m1"], rows.Select(row => row.MessageId)); + } + + [PostgresFact] + public async Task ReadWindow_BeforeTheFirstTurn_ReadsNothing() + { + var store = await FourTurnsAsync(); + + var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(0, 5), Token); + + Assert.Empty(rows); + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs index a073182f..54e2d556 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs @@ -5,8 +5,9 @@ using AgentCore.Application.Transcript; using AgentCore.Domain.Audit; using AgentCore.Infrastructure.Audit.Postgres; -using AgentCore.Infrastructure.Tests.Database.Postgres; using AgentCore.Infrastructure.Conversation.Postgres; +using AgentCore.Infrastructure.Tests.Database.Postgres; +using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; @@ -83,7 +84,7 @@ await store.AppendAsync( cancellationToken: Token); // Assert - var rows = await store.ReadAsync("C1", Token); + var rows = await store.ReadAllAsync("C1", Token); Assert.Equal( ["Let me check that.", "lookup", "id1"], [ @@ -202,7 +203,7 @@ await store.AppendAsync( var record = await store.GetAsync("C1", Token); Assert.Equal("a", record?.State?.Stage); - var rows = await store.ReadAsync("C1", Token); + var rows = await store.ReadAllAsync("C1", Token); Assert.Single(rows); Assert.Equal("m0", rows[0].MessageId); } @@ -226,38 +227,6 @@ public async Task AStateBlobThatWillNotParse_ReadsAsNoBlobRatherThanClosingTheCo Assert.Null(record.State); } - // --------------------------------------------------------------------------------------------- - // Read. It runs at conversation start, on a resume, and nowhere else. - // --------------------------------------------------------------------------------------------- - [PostgresFact] - public async Task ReadAsync_AWrittenConversation_ReturnsEveryRowInOrdinalOrder() - { - // Arrange - var store = await OpenAsync(); - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - await store.AppendAsync("C1", Turn(turnIndex: 1, idSeed: 2), cancellationToken: Token); - - // Act - var rows = await store.ReadAsync("C1", Token); - - // Assert - Assert.Equal([0, 1, 2, 3], rows.Select(row => row.Ordinal).ToArray()); - } - - [PostgresFact] - public async Task ReadAsync_AnotherConversation_ReturnsNothing() - { - // Arrange - var store = await OpenAsync(); - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - - // Act - var rows = await store.ReadAsync("C2", Token); - - // Assert - Assert.Empty(rows); - } - // --------------------------------------------------------------------------------------------- // Rewrite. R4: the record holds the words the caller heard. // --------------------------------------------------------------------------------------------- @@ -272,7 +241,7 @@ public async Task RewriteAsync_ARow_ReplacesTheWordsOfThatRowOnly() await store.RewriteAsync("C1", "m1", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); // Assert - var rows = await store.ReadAsync("C1", Token); + var rows = await store.ReadAllAsync("C1", Token); Assert.Equal(["what about order 41", "Order 41 sh"], rows.Select(row => row.Content.Text).ToArray()); } @@ -324,8 +293,8 @@ public async Task EraseAsync_OneConversation_DeletesItsRowsAndLeavesTheOthers() // Assert Assert.Equal(2, erased); - Assert.Empty(await store.ReadAsync("C1", Token)); - Assert.Equal(2, (await store.ReadAsync("C2", Token)).Count); + Assert.Empty(await store.ReadAllAsync("C1", Token)); + Assert.Equal(2, (await store.ReadAllAsync("C2", Token)).Count); } diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs new file mode 100644 index 00000000..135df4be --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs @@ -0,0 +1,36 @@ +using AgentCore.Infrastructure.Llm.OpenAI; +using Xunit; + +namespace AgentCore.Infrastructure.Tests.Llm; + +/// The built-in OpenAI context window table. +public sealed class OpenAiContextWindowsTests +{ + [Fact] + public void Lookup_ExactId_ReturnsItsValue() + { + Assert.Equal(1_050_000, OpenAiContextWindows.Lookup("gpt-6-astra")); + } + + [Fact] + public void Lookup_DatedSnapshotId_ResolvesThroughTheBaseId() + { + Assert.Equal(1_047_576, OpenAiContextWindows.Lookup("gpt-4.1-mini-2025-04-14")); + } + + [Fact] + public void Lookup_LongerPrefixWins_OverAShorterPrefixThatAlsoMatches() + { + // "gpt-5.4" and "gpt-5.4-nano" are both entries, and both match "gpt-5.4-nano-2026-03-17". + // The two have different windows, so this proves the longer prefix wins rather than the + // first or shortest one. + Assert.NotEqual(OpenAiContextWindows.Lookup("gpt-5.4"), OpenAiContextWindows.Lookup("gpt-5.4-nano")); + Assert.Equal(400_000, OpenAiContextWindows.Lookup("gpt-5.4-nano-2026-03-17")); + } + + [Fact] + public void Lookup_UnknownId_ReturnsNull() + { + Assert.Null(OpenAiContextWindows.Lookup("gpt-does-not-exist")); + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs b/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs index 054c5535..362f69a3 100644 --- a/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs @@ -1,3 +1,4 @@ +using AgentCore.TestSupport; using AgentCore.Application.Tools.Binding; using AgentCore.Application.Tools.Registry; using System.Net; @@ -102,7 +103,7 @@ public async Task TheWorkedExample_CompilesWithEveryToolBound() using OneReplyChatClient model = new("done"); var compiled = ConfigurationCompiler.CompileAll( document, - new AgentCompilationContext(new OneClientFactory(model)) { Tools = registry })["main"]; + new AgentCompilationContext(new RecordingChatClientFactory(model)) { Tools = registry })["main"]; Assert.Equal(3, compiled.Agents.Count); @@ -119,16 +120,6 @@ public async Task TheWorkedExample_CompilesWithEveryToolBound() handler.Requests[0].Headers.GetValues("Authorization").Single()); } - /// Hands the same offline client to every model reference. - private sealed class OneClientFactory : IChatClientFactory - { - private readonly IChatClient _client; - - public OneClientFactory(IChatClient client) => _client = client; - - public IChatClient GetChatClient(ModelReference? model) => _client; - } - /// An offline model that answers one line and calls no tool. private sealed class OneReplyChatClient : IChatClient { diff --git a/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs b/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs new file mode 100644 index 00000000..f270ea35 --- /dev/null +++ b/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs @@ -0,0 +1,12 @@ +using AgentCore.Application.Ports; +using AgentCore.Application.Transcript; + +namespace AgentCore.TestSupport; + +/// The oracle read a test wants: every row somebody said, oldest first. +public static class ConversationStoreReadAll +{ + public static ValueTask> ReadAllAsync( + this IConversationStore store, string conversationId, CancellationToken cancellationToken = default) + => store.ReadWindowAsync(conversationId, new TranscriptWindow(null, int.MaxValue), cancellationToken); +} diff --git a/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs b/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs new file mode 100644 index 00000000..6c8898dc --- /dev/null +++ b/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs @@ -0,0 +1,145 @@ +using AgentCore.Application.Ports; +using AgentCore.Application.Transcript; +using Microsoft.Extensions.AI; + +namespace AgentCore.TestSupport; + +/// +/// What every store 1 must do with a summary row: hand it to the session's read alone, leave it out +/// of every consumer read, and take it on a truncate only when the cut reaches a row it covers. +/// Each store's test class runs these against its own instance. This project carries no test +/// framework, so a fact that fails throws naming what it saw. +/// +public static class ConversationStoreSummaryRowFacts +{ + /// + /// Seeds three plain turns (ordinals 0-5), a summary over 0-3 at ordinal 6, a fourth turn + /// (7-8), a second summary over 0-5 at ordinal 9, and a fifth turn (10-11). + /// + public static async Task SeedAsync(IConversationStore store, CancellationToken cancellationToken) + { + await store.CreateAsync("c1", cancellationToken); + await TurnAsync(store, 0, cancellationToken); + await TurnAsync(store, 1, cancellationToken); + await TurnAsync(store, 2, cancellationToken); + await SummaryAsync(store, turnIndex: 3, "first summary", coversUpTo: 3, cancellationToken); + await TurnAsync(store, 3, cancellationToken); + await SummaryAsync(store, turnIndex: 4, "second summary", coversUpTo: 5, cancellationToken); + await TurnAsync(store, 4, cancellationToken); + } + + public static async Task SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); + + var rows = await store.ReadForSessionAsync("c1", cancellationToken); + + ExpectOrdinals([7, 8, 9, 10, 11], rows, "the session read"); + var summary = rows.Single(row => row.CoversUpTo is not null); + Expect("9/5/second summary", $"{summary.Ordinal}/{summary.CoversUpTo}/{summary.Content.Text}", "the summary the session read"); + } + + public static async Task SessionReadWithNoSummaryHandsBackEveryRow(IConversationStore store, CancellationToken cancellationToken) + { + await store.CreateAsync("c1", cancellationToken); + await TurnAsync(store, 0, cancellationToken); + await TurnAsync(store, 1, cancellationToken); + + ExpectOrdinals([0, 1, 2, 3], await store.ReadForSessionAsync("c1", cancellationToken), "the session read"); + } + + public static async Task ConsumerReadsLeaveEverySummaryOut(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); + + ExpectOrdinals([0, 1, 2, 3, 4, 5, 7, 8, 10, 11], await store.ReadAllAsync("c1", cancellationToken), "ReadAsync"); + ExpectOrdinals([7, 8, 10, 11], await store.ReadWindowAsync("c1", new TranscriptWindow(null, 2), cancellationToken), "ReadWindowAsync(2 turns)"); + } + + public static async Task TruncateUnderWhatTheSummaryCoversTakesTheSummary(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); + + // Cut at 4: rows 4-5 go, and so does the second summary (covers 5 >= 4). The first summary + // (covers 3 < 4) stays, and the session read falls back to it. + var went = await store.TruncateAsync("c1", 4, cancellationToken); + + Expect("7", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 4 took"); + Expect("2-4", Turns(went), "turns the cut at 4 took"); + var rows = await store.ReadForSessionAsync("c1", cancellationToken); + ExpectOrdinals([6], rows, "the session read after the cut at 4"); + Expect("3", rows[0].CoversUpTo?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "what the standing summary covers"); + } + + public static async Task TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); + + // Cut at 7: rows 7-8 and 10-11 go. Both summaries sit at ordinals >= 7 but cover rows < 7, so both stay. + var went = await store.TruncateAsync("c1", 7, cancellationToken); + + Expect("4", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 7 took"); + Expect("3-4", Turns(went), "turns the cut at 7 took"); + ExpectOrdinals([9], await store.ReadForSessionAsync("c1", cancellationToken), "the session read after the cut at 7"); + ExpectOrdinals([0, 1, 2, 3, 4, 5], await store.ReadAllAsync("c1", cancellationToken), "ReadAsync after the cut at 7"); + } + + public static async Task TruncateAboveTheSummaryLeavesEverythingUnderItAlone(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); + + var went = await store.TruncateAsync("c1", 10, cancellationToken); + + Expect("2", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 10 took"); + Expect("4-4", Turns(went), "turns the cut at 10 took"); + ExpectOrdinals([7, 8, 9], await store.ReadForSessionAsync("c1", cancellationToken), "the session read after the cut at 10"); + + // Nothing left above 10: a second cut there takes no row and names no turn. + var again = await store.TruncateAsync("c1", 10, cancellationToken); + Expect("0/none", $"{again.Rows}/{Turns(again)}", "a cut with nothing above it"); + } + + public static async Task OrdinalOfFindsASpokenRowAndNotASummary(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); + + Expect("5", (await store.OrdinalOfAsync("c1", "m-2-a", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of turn 2's reply"); + Expect("null", (await store.OrdinalOfAsync("c1", "s-5", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of a summary row"); + Expect("null", (await store.OrdinalOfAsync("c1", "nobody", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of a message nobody said"); + } + + private static string Turns(ConversationCut cut) + => cut.Turns is { } turns ? $"{turns.First}-{turns.Last}" : "none"; + + private static void ExpectOrdinals(int[] expected, IReadOnlyList rows, string what) + => Expect(string.Join(",", expected), string.Join(",", rows.Select(row => row.Ordinal)), what); + + private static void Expect(string expected, string actual, string what) + { + if (!string.Equals(expected, actual, StringComparison.Ordinal)) + { + throw new InvalidOperationException($"{what}: expected [{expected}], got [{actual}]."); + } + } + + private static async Task TurnAsync(IConversationStore store, int turnIndex, CancellationToken cancellationToken) + { + await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, $"q{turnIndex}"), $"m-{turnIndex}-q"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, $"a{turnIndex}"), $"m-{turnIndex}-a"), + ], + state: null, + cancellationToken); + } + + private static async Task SummaryAsync(IConversationStore store, int turnIndex, string text, int coversUpTo, CancellationToken cancellationToken) + { + await store.AppendAsync( + "c1", + [new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, text), $"s-{coversUpTo}") { CoversUpTo = coversUpTo }], + state: null, + cancellationToken); + } +} diff --git a/tests/AgentCore.TestSupport/DelegatingConversationStore.cs b/tests/AgentCore.TestSupport/DelegatingConversationStore.cs index aa83e20d..5e753fb1 100644 --- a/tests/AgentCore.TestSupport/DelegatingConversationStore.cs +++ b/tests/AgentCore.TestSupport/DelegatingConversationStore.cs @@ -72,12 +72,22 @@ public virtual ValueTask RewriteAsync( => Inner.RewriteAsync(conversationId, messageId, content, cancellationToken); /// - public virtual ValueTask> ReadAsync( + public virtual ValueTask> ReadForSessionAsync( string conversationId, CancellationToken cancellationToken = default) - => Inner.ReadAsync(conversationId, cancellationToken); + => Inner.ReadForSessionAsync(conversationId, cancellationToken); /// - public virtual ValueTask TruncateAsync( + public virtual ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + => Inner.ReadWindowAsync(conversationId, window, cancellationToken); + + /// + public virtual ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) + => Inner.OrdinalOfAsync(conversationId, messageId, cancellationToken); + + /// + public virtual ValueTask TruncateAsync( string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) => Inner.TruncateAsync(conversationId, fromOrdinal, cancellationToken); diff --git a/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs b/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs new file mode 100644 index 00000000..f8e980f1 --- /dev/null +++ b/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs @@ -0,0 +1,31 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; +using Microsoft.Extensions.AI; + +namespace AgentCore.TestSupport; + +/// +/// A factory whose two seams are lambdas, for a test that needs one odd answer — a factory that +/// throws, or one that admits a hosted tool for one model only — without a class of its own. +/// +public sealed class LambdaChatClientFactory : IChatClientFactory +{ + private readonly Func _client; + private readonly Func _hostedTool; + + /// Answers . Omitted, every call throws. + /// Answers . Omitted, no model admits a hosted tool. + public LambdaChatClientFactory( + Func? client = null, + Func? hostedTool = null) + { + _client = client ?? (_ => throw new NotSupportedException()); + _hostedTool = hostedTool ?? ((_, _) => null); + } + + public IChatClient GetChatClient(ModelReference? model) => _client(model); + + public AITool? ResolveHostedTool(AITool marker, ModelReference? model) => _hostedTool(marker, model); + + public int? GetContextWindow(ModelReference? model) => 128_000; +} diff --git a/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs b/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs index b02bef35..39eb7009 100644 --- a/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs +++ b/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs @@ -27,6 +27,8 @@ public IChatClient GetChatClient(ModelReference? model) return _client; } + public int? GetContextWindow(ModelReference? model) => 128_000; + private sealed class StubChatClient : IChatClient { public IAsyncEnumerable GetStreamingResponseAsync( diff --git a/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs b/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs index 619ac431..8691bd80 100644 --- a/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs +++ b/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs @@ -15,9 +15,12 @@ namespace AgentCore.TestSupport; public sealed class RoutingChatClientFactory : IChatClientFactory { private readonly Dictionary _byName = new(StringComparer.Ordinal); - private readonly IChatClient _fallback; + private readonly IChatClient? _fallback; - public RoutingChatClientFactory(IChatClient fallback) => _fallback = fallback; + /// + /// The client for a reference with no route, or to throw on one. + /// + public RoutingChatClientFactory(IChatClient? fallback = null) => _fallback = fallback; /// Binds one client to one as name. public RoutingChatClientFactory Route(string name, IChatClient client) @@ -27,5 +30,9 @@ public RoutingChatClientFactory Route(string name, IChatClient client) } public IChatClient GetChatClient(ModelReference? model) - => model is not null && _byName.TryGetValue(model.Ref, out var client) ? client : _fallback; + => model is not null && _byName.TryGetValue(model.Ref, out var client) + ? client + : _fallback ?? throw new KeyNotFoundException($"No offline client is routed to the model '{model?.Ref}'."); + + public int? GetContextWindow(ModelReference? model) => 128_000; } \ No newline at end of file From 8cce2ce24441d23dfb8f484ca96485870dc435db Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sun, 20 Sep 2026 19:10:58 -0600 Subject: [PATCH 6/8] chore: apply diagnotic suggested changes --- .editorconfig | 22 + .../Audit/AuditConversationObserver.cs | 89 +- .../Audit/AuditSinkFactory.cs | 85 +- .../Audit/Memory/InMemoryAuditSink.cs | 77 +- .../Audit/QueuedAuditSink.cs | 393 +- src/AgentCore.Application/Blobs/BlobLink.cs | 45 +- .../Blobs/BlobMediaTypes.cs | 69 +- src/AgentCore.Application/Blobs/BlobName.cs | 40 +- src/AgentCore.Application/Blobs/BlobPolicy.cs | 101 +- src/AgentCore.Application/Blobs/BlobRead.cs | 28 +- src/AgentCore.Application/Blobs/BlobRef.cs | 25 +- .../Blobs/BlobStoreFactory.cs | 65 +- src/AgentCore.Application/Blobs/BlobWrite.cs | 29 +- src/AgentCore.Application/Blobs/FileLink.cs | 13 +- .../Cache/PassThroughHybridCache.cs | 79 +- .../Compilation/AgentApproval.cs | 145 +- .../Compilation/AgentBackgroundCompiler.cs | 97 +- .../Compilation/AgentCompilationContext.cs | 137 +- .../AgentContextProviderCompiler.cs | 167 +- .../Compilation/AgentDelegationTool.cs | 190 +- .../Configuration/Compilation/AgentHarness.cs | 53 +- .../Compilation/AgentHarnessProviders.cs | 470 ++- .../Compilation/AgentInstructions.cs | 121 +- .../Compilation/AgentKnowledge.cs | 192 +- .../Compilation/AgentShellOptionsCompiler.cs | 193 +- .../Compilation/AgentToolCompiler.cs | 190 +- .../Configuration/Compilation/AgentsWalk.cs | 25 +- .../Compilation/CompileTableRow.cs | 81 +- .../Compilation/CompiledAgent.cs | 240 +- .../Compilation/CompiledAgentBuilder.cs | 57 +- .../Compilation/CompiledAgentRegistry.cs | 161 +- .../Compilation/CompiledAgentSet.cs | 21 +- .../Compilation/CompiledAgentShape.cs | 29 +- .../Compilation/CompiledDocument.cs | 21 +- .../Compilation/ConfigurationCompiler.cs | 417 +- .../Configuration/Compilation/EntryBuild.cs | 13 +- .../Compilation/ExplicitGraphRow.cs | 306 +- .../Compilation/GraphGuardGate.cs | 73 +- .../Compilation/GraphStateCarrier.cs | 63 +- .../Compilation/GraphStateEntry.cs | 56 +- .../Compilation/PatternGraphRow.cs | 136 +- .../Configuration/Compilation/PolicyRow.cs | 104 +- .../Compilation/ResolvedClarification.cs | 163 +- .../Compilation/SingleAgentRow.cs | 62 +- .../Configuration/Compilation/TurnLayers.cs | 41 +- .../Parsing/ConfigurationBinder.cs | 277 +- .../Parsing/ConfigurationCheck.cs | 63 +- .../Parsing/ConfigurationError.cs | 95 +- .../Parsing/ConfigurationJson.cs | 257 +- .../Parsing/ConfigurationLoadException.cs | 139 +- .../Parsing/ConfigurationLoader.cs | 229 +- .../Parsing/ConfigurationSchemaValidator.cs | 186 +- .../Parsing/McpAllowEntryConverter.cs | 120 +- .../Parsing/SchemaFailureWording.cs | 386 +- .../Configuration/Parsing/ScopeTemplate.cs | 91 +- .../Configuration/Parsing/SecretReference.cs | 40 +- .../Configuration/Parsing/SecretTemplate.cs | 146 +- .../Configuration/Parsing/YamlToJson.cs | 380 +- .../Schema/AgentCoreConfiguration.cs | 135 +- .../Schema/AgentLoopConfiguration.cs | 47 +- .../Schema/AgentMemoryConfiguration.cs | 59 +- .../Schema/AgentShellConfiguration.cs | 109 +- .../Schema/AgentsConfiguration.cs | 213 +- .../Schema/ApprovalConfiguration.cs | 23 +- .../Schema/BlobProviderConfiguration.cs | 39 +- .../ConversationProviderConfiguration.cs | 29 +- .../Schema/EmbeddingProviderConfiguration.cs | 31 +- .../Schema/EntryConfiguration.cs | 33 +- .../Schema/EvaluationConfiguration.cs | 69 +- .../Schema/ExtractorConfiguration.cs | 59 +- .../Schema/GraphConfiguration.cs | 139 +- .../Configuration/Schema/GuardReference.cs | 105 +- .../Schema/LlmProviderConfiguration.cs | 45 +- .../Schema/McpServerConfiguration.cs | 161 +- .../Schema/PolicyConfiguration.cs | 109 +- .../Schema/ProvidersConfiguration.cs | 619 +-- .../Schema/ReservedStateSlots.cs | 51 +- .../Schema/SpeechProviderConfiguration.cs | 21 +- .../Schema/StateSlotConfiguration.cs | 133 +- .../Schema/TitlerConfiguration.cs | 17 +- .../Configuration/Schema/ToolConfiguration.cs | 119 +- .../Schema/ToolResultReference.cs | 64 +- .../Schema/VendorProviderConfiguration.cs | 17 +- .../Validation/AmbiguityCheck.cs | 153 +- .../ConfigurationValidationResult.cs | 46 +- .../Validation/ConfigurationValidator.cs | 257 +- .../Configuration/Validation/DeclaredNames.cs | 61 +- .../Validation/DelegationCycleCheck.cs | 161 +- .../Validation/EntryShapeCheck.cs | 121 +- .../Validation/ExitExclusivityCheck.cs | 177 +- .../Configuration/Validation/GraphReach.cs | 69 +- .../Validation/GraphWellFormednessCheck.cs | 95 +- .../Validation/GuardEvaluator.cs | 429 ++- .../Validation/GuardExclusivityCheck.cs | 165 +- .../Validation/GuardOperators.cs | 178 +- .../Validation/GuardRuleCheck.cs | 117 +- .../Validation/GuardRuleFacts.cs | 344 +- .../Validation/IGuardEvaluator.cs | 87 +- .../Validation/KnowledgeFilterValidator.cs | 209 +- .../Validation/KnowledgeScopeCheck.cs | 229 +- .../Configuration/Validation/McpCheck.cs | 103 +- .../Validation/ReachabilityCheck.cs | 97 +- .../Validation/ReasoningTemperatureCheck.cs | 197 +- .../Validation/ReferenceCheck.cs | 235 +- .../Validation/ServedReferenceCheck.cs | 207 +- .../Configuration/Validation/SiblingGroup.cs | 25 +- .../Validation/SlotWriterCheck.cs | 113 +- .../Configuration/Validation/StateDomain.cs | 482 +-- .../Validation/ValidationErrors.cs | 121 +- .../Validation/ValidationPointer.cs | 152 +- .../Conversation/ChatConversationTitler.cs | 207 +- .../Conversation/ConversationChannel.cs | 131 +- .../ConversationChannelContext.cs | 21 +- .../ConversationClarificationState.cs | 23 +- .../Conversation/ConversationCursor.cs | 107 +- .../Conversation/ConversationInput.cs | 83 +- .../Conversation/ConversationPage.cs | 19 +- .../Conversation/ConversationRecord.cs | 67 +- .../Conversation/ConversationSessionState.cs | 109 +- .../Conversation/ConversationSpeechPairing.cs | 157 +- .../Conversation/ConversationStateJson.cs | 25 +- .../Conversation/ConversationStatus.cs | 17 +- .../Conversation/ConversationStoreFactory.cs | 73 +- .../Conversation/Conversations.cs | 387 +- .../Memory/InMemoryConversationClaims.cs | 58 +- .../InMemoryConversationContinuations.cs | 49 +- .../Memory/InMemoryConversationListing.cs | 65 +- .../Memory/InMemoryConversationStore.cs | 542 ++- .../Memory/InMemoryConversationWords.cs | 264 +- .../Conversation/StoredConversation.cs | 37 +- .../Diagnostics/AgentCoreTelemetry.cs | 219 +- src/AgentCore.Application/Diagnostics/Log.cs | 605 +-- .../LoggingConversationObserver.cs | 212 +- .../TelemetryConversationObserver.cs | 120 +- .../Diagnostics/TelemetrySessionFactory.cs | 103 +- .../CompositeEmbeddingGeneratorFactory.cs | 69 +- .../HybridCachingEmbeddingGenerator.cs | 107 +- .../Evaluation/DocumentRecallEvaluator.cs | 164 +- .../Evaluation/EvaluationSampler.cs | 128 +- .../Evaluation/EvaluationScore.cs | 27 +- .../Evaluation/EvaluatorRegistry.cs | 118 +- .../Evaluation/FaultCodeContext.cs | 79 +- .../Evaluation/FaultCodeEvaluator.cs | 249 +- .../InMemoryEvaluationScorePublisher.cs | 73 +- .../Evaluation/ModerationEvaluatorFactory.cs | 99 +- .../Evaluation/ModerationVerdict.cs | 191 +- .../Evaluation/PromptModerator.cs | 185 +- .../Evaluation/RetrievedDocumentsContext.cs | 75 +- .../Knowledge/ClaimedProbe.cs | 15 +- .../CompositeKnowledgeStoreFactory.cs | 221 +- .../Knowledge/FacetFilterProvider.cs | 103 +- .../Knowledge/FacetFilterReader.cs | 111 +- .../Knowledge/FacetFilterSchema.cs | 161 +- .../Knowledge/FacetFilteredSearch.cs | 138 +- .../HybridCachingKnowledgeRetrievalPort.cs | 169 +- .../Knowledge/IKnowledgeCitationFormatter.cs | 35 +- .../Knowledge/IKnowledgePointMapper.cs | 23 +- .../Knowledge/IKnowledgeQueryAnalyzer.cs | 21 +- .../Knowledge/KnowledgeAuditRecord.cs | 273 +- .../Knowledge/KnowledgeBinding.cs | 29 +- .../Knowledge/KnowledgeCancellation.cs | 65 +- .../Knowledge/KnowledgeCardCodec.cs | 90 +- .../Knowledge/KnowledgeCardMapper.cs | 59 +- .../KnowledgeCitationFormatterFactory.cs | 73 +- .../Knowledge/KnowledgeNotices.cs | 57 +- .../Knowledge/KnowledgePoint.cs | 21 +- .../Knowledge/KnowledgePrefetchProvider.cs | 98 +- .../Knowledge/KnowledgeProbe.cs | 502 +-- .../Knowledge/KnowledgeProviderFactory.cs | 116 +- .../KnowledgeRetrievalPortExtensions.cs | 31 +- .../Knowledge/KnowledgeSearch.cs | 279 +- .../Knowledge/KnowledgeSearchRecord.cs | 65 +- .../Knowledge/KnowledgeSourceMapper.cs | 58 +- .../Knowledge/NoQueryAnalyzer.cs | 29 +- .../Knowledge/ProbeWiring.cs | 55 +- .../SourceLocatorCitationFormatter.cs | 61 +- .../Knowledge/StateKnowledgeScope.cs | 129 +- .../Knowledge/ToolFacetOverlay.cs | 73 +- .../Llm/ChatRequestProperties.cs | 25 +- .../Llm/CompositeChatClientFactory.cs | 300 +- .../Llm/ConversationRequestStamp.cs | 27 +- .../Policy/StagePolicy.cs | 211 +- .../Ports/IAuditSinkAdapter.cs | 38 +- .../Ports/IAuditSinkPort.cs | 63 +- src/AgentCore.Application/Ports/IBlobStore.cs | 67 +- .../Ports/IBlobStoreAdapter.cs | 29 +- .../Ports/IChatClientAdapter.cs | 63 +- .../Ports/IChatClientFactory.cs | 58 +- .../Ports/IConversationAdapter.cs | 63 +- .../Ports/IConversationChannelFactory.cs | 19 +- .../Ports/IConversationInputPort.cs | 103 +- .../Ports/IConversationObserver.cs | 87 +- .../Ports/IConversationOutputPort.cs | 75 +- .../Ports/IConversationPort.cs | 173 +- .../Ports/IConversationSessionFactory.cs | 17 +- .../Ports/IConversationSessionRegistry.cs | 27 +- .../Ports/IConversationSessions.cs | 79 +- .../Ports/IConversationStore.cs | 477 +-- .../Ports/IConversationStoreAdapter.cs | 29 +- .../Ports/IConversationTitler.cs | 37 +- .../Ports/IConversations.cs | 101 +- .../Ports/IEmbeddingGeneratorAdapter.cs | 29 +- .../Ports/IEvaluationScorePublisher.cs | 65 +- .../Ports/IKnowledgeFacetReadPort.cs | 49 +- .../Ports/IKnowledgeRetrievalPort.cs | 69 +- .../Ports/IKnowledgeStoreAdapter.cs | 71 +- .../Ports/IModerationAdapter.cs | 87 +- .../Ports/IRenderPort.cs | 17 +- .../Ports/ISecretResolverPort.cs | 57 +- .../Ports/ISourcePort.cs | 19 +- .../Ports/ISpeechAdapter.cs | 95 +- .../Ports/ITelemetryAdapter.cs | 79 +- .../Ports/ITelemetrySession.cs | 17 +- .../Ports/IToolSource.cs | 25 +- .../Ports/IVendorAdapter.cs | 45 +- .../Providers/VendorAdapterSelector.cs | 169 +- .../Providers/VendorSeam.cs | 69 +- .../PublicAPI.Unshipped.txt | 2 +- .../Runtime/AgentCoreAgent.cs | 579 +-- .../AuditingFunctionInvokingChatClient.cs | 328 +- .../Runtime/ClarificationText.cs | 97 +- .../Runtime/Clarifications.cs | 492 +-- .../Runtime/Compaction/CompactionDefaults.cs | 25 +- .../Runtime/Compaction/CompactionStages.cs | 19 +- .../Compaction/CompactionStrategyFactory.cs | 93 +- .../Compaction/ReaderContentFilterProvider.cs | 40 +- .../Runtime/Compaction/SummaryRowProvider.cs | 203 +- .../Compaction/ToolResultCapProvider.cs | 182 +- .../Runtime/ConversationEvent.cs | 67 +- .../Runtime/ConversationEventChain.cs | 431 ++- .../Runtime/ConversationEventKind.cs | 75 +- .../Runtime/ConversationEventKinds.cs | 85 +- .../Runtime/ConversationEventPayloadKeys.cs | 19 +- .../ConversationInterruptionTracker.cs | 179 + .../Runtime/ConversationObserverDispatcher.cs | 337 +- .../Runtime/ConversationObservers.cs | 145 +- .../Runtime/ConversationSession.cs | 721 ++-- .../ConversationInterruptionTracker.cs | 172 - .../ConversationSessionLifetime.cs | 79 - .../ConversationSessionStateStore.cs | 132 - .../ConversationTranscriptLedger.cs | 215 -- .../ConversationSession/ConversationTurn.cs | 28 - .../ConversationTurnCommit.cs | 82 - .../ConversationTurnCompletion.cs | 332 -- .../ConversationTurnRunner.cs | 313 -- .../ConversationTurnStream.cs | 152 - .../ConversationTurnWriters.cs | 78 - .../ConversationSession/ReplyOutcome.cs | 18 - .../ConversationSession/TranscriptEntry.cs | 8 - .../Runtime/ConversationSessionFactory.cs | 131 +- .../Runtime/ConversationSessionLifetime.cs | 86 + .../Runtime/ConversationSessionSeams.cs | 29 +- .../Runtime/ConversationSessionStateStore.cs | 137 + .../Runtime/ConversationTranscriptLedger.cs | 219 ++ .../Runtime/ConversationTurn.cs | 29 + .../Runtime/ConversationTurnCommit.cs | 78 + .../Runtime/ConversationTurnCompletion.cs | 336 ++ .../Runtime/ConversationTurnOrigin.cs | 29 +- .../Runtime/ConversationTurnRunner.cs | 318 ++ .../Runtime/ConversationTurnStream.cs | 157 + .../Runtime/ConversationTurnWriters.cs | 79 + .../Runtime/ConversationWorkspace.cs | 138 +- .../Runtime/DelegatedAgentRun.cs | 103 +- .../Runtime/FallbackAgent.cs | 338 +- .../Runtime/GraphStateAgent.cs | 93 +- .../Runtime/Harness/BackgroundChildAgent.cs | 101 +- .../Harness/BackgroundSessionRelease.cs | 83 +- .../Runtime/Harness/BlobOwnerKey.cs | 33 +- .../Runtime/Harness/CallerTimeZone.cs | 91 +- .../Runtime/Harness/ClockContextProvider.cs | 81 +- .../Harness/ConversationFilesProvider.cs | 126 +- .../ConversationShellEnvironmentProvider.cs | 55 +- .../Harness/ConversationShellOptions.cs | 55 +- .../Harness/ConversationShellProvider.cs | 53 +- .../Runtime/Harness/ConversationShells.cs | 401 +- .../Runtime/Harness/HarnessSessionState.cs | 93 +- .../Runtime/Harness/PendingApprovalQueue.cs | 181 +- .../Runtime/ModelFacingChatClient.cs | 86 +- .../Runtime/ModerationAgent.cs | 279 +- .../Runtime/ReplyOutcome.cs | 19 + .../Runtime/RequireOutputAgent.cs | 111 +- .../Runtime/SpokenReply.cs | 95 +- .../Runtime/ToolCallScopes.cs | 35 +- .../Runtime/TranscriptEntry.cs | 9 + .../Runtime/Turn/ITurnAttachments.cs | 39 +- .../Runtime/Turn/OuterCall.cs | 38 +- .../Runtime/Turn/TurnAttachments.cs | 154 +- .../Runtime/Turn/TurnContextProvider.cs | 35 +- .../Runtime/Turn/TurnFiles.cs | 29 +- .../Runtime/Turn/TurnMessages.cs | 169 +- .../Runtime/Turn/TurnRegistry.cs | 53 +- .../Runtime/Turn/TurnRenders.cs | 33 +- .../Runtime/Turn/TurnResults.cs | 249 +- .../Runtime/Turn/TurnSources.cs | 31 +- .../Runtime/TurnDisposition.cs | 111 +- .../Runtime/TurnInvocation.cs | 207 +- .../Scripting/ScriptRequest.cs | 35 +- .../Scripting/ScriptResult.cs | 39 +- .../Secrets/KnownSecrets.cs | 105 +- .../Secrets/ResolvedSecrets.cs | 258 +- .../Secrets/SecretName.cs | 90 +- .../Secrets/SecretResolutionException.cs | 105 +- .../Secrets/SecretResolverExtensions.cs | 207 +- .../Memory/InMemoryConversationSessions.cs | 253 +- .../Skills/PinnedSkillsProvider.cs | 167 +- .../Skills/ReadOnlySkillsProvider.cs | 65 +- .../Skills/SkillCatalog.cs | 41 +- .../Skills/SkillsProviderFactory.cs | 89 +- .../State/ConstStateWriter.cs | 53 +- .../State/CounterStateWriter.cs | 87 +- .../State/StateDocument.cs | 254 +- .../State/StateExtractionResult.cs | 52 +- .../State/StateExtractor.cs | 461 +-- .../State/StateValueCoercion.cs | 225 +- .../State/ToolResultPath.cs | 117 +- .../State/ToolStateWriter.cs | 67 +- .../State/UnfilledSlotReminder.cs | 209 +- .../Tools/Binding/BindingToolSource.cs | 128 +- .../Tools/Binding/ToolBindingRegistry.cs | 182 +- .../Tools/Binding/ToolParameterBindings.cs | 47 +- .../Tools/Binding/TypedBindingTool.cs | 51 +- .../Tools/Builtin/BuiltinToolNames.cs | 17 +- .../Tools/Builtin/BuiltinToolOptions.cs | 36 +- .../Tools/Builtin/BuiltinToolSource.cs | 152 +- .../Tools/Builtin/FilePublishTool.cs | 293 +- .../Builtin/FilePublishToolDefinition.cs | 56 +- .../Tools/Builtin/IBuiltinToolDefinition.cs | 63 +- .../Tools/Builtin/WebSearchToolDefinition.cs | 30 +- src/AgentCore.Application/Tools/CachedTool.cs | 106 +- .../Tools/DeclaredTool.cs | 159 +- .../Tools/Registry/ToolRegistration.cs | 41 +- .../Tools/Registry/ToolRegistry.cs | 60 +- .../Tools/Registry/ToolRegistryBuilder.cs | 194 +- .../Tools/Registry/ToolSourceContext.cs | 33 +- .../Tools/Registry/ToolSourceError.cs | 43 +- .../Tools/TimeLimitedTool.cs | 73 +- .../Tools/ToolArgumentJson.cs | 70 +- .../Tools/ToolCallNames.cs | 53 +- .../Tools/ToolCallScope.cs | 17 +- .../Tools/ToolErrorResult.cs | 97 +- .../Tools/ToolResultJson.cs | 92 +- .../AgentCoreChatHistoryProvider.cs | 647 ++-- .../Transcript/ChatMessageExtensions.cs | 53 +- .../Transcript/ConversationCut.cs | 13 +- .../Transcript/ConversationGate.cs | 79 +- .../Transcript/ConversationMessage.cs | 55 +- .../Transcript/ConversationMessageDraft.cs | 25 +- .../Transcript/ConversationMessageIds.cs | 16 +- .../Transcript/ConversationTranscript.cs | 550 +-- .../Transcript/FileContent.cs | 39 +- .../Transcript/ReaderContent.cs | 99 +- .../Transcript/RenderContent.cs | 25 +- .../Transcript/SourceContent.cs | 21 +- .../Transcript/TranscriptFloor.cs | 15 +- .../Transcript/TranscriptJson.cs | 39 +- .../Transcript/TranscriptMarks.cs | 13 +- .../Transcript/TranscriptWindow.cs | 46 +- .../Transcript/ViewMessage.cs | 21 +- .../Transcript/WithdrawnTurns.cs | 13 +- .../Conversation/ConnectionTaskObserver.cs | 306 +- ...versationEndpointRouteBuilderExtensions.cs | 167 +- .../Conversation/ConversationRouteLog.cs | 57 +- .../Conversation/ConversationSeams.cs | 15 +- .../Conversation/ConversationTurnArbiter.cs | 711 ++-- .../Conversation/FrameOutcome.cs | 15 +- .../Conversation/FrameParser.cs | 13 +- .../IConversationTransportAdapter.cs | 29 +- .../Conversation/JsonWebSocketPump.cs | 667 ++-- .../Conversation/JsonWebSocketPumpOptions.cs | 57 +- .../DependencyInjection/AgentCoreBoot.cs | 576 +-- .../AgentCoreBootService.cs | 66 +- .../AgentCoreHttpClients.cs | 293 +- .../DependencyInjection/AgentCoreOptions.cs | 667 ++-- .../AgentCoreServiceCollectionExtensions.cs | 213 +- .../DependencyInjection/AgentCoreStartup.cs | 45 +- .../Startup/BlobStartup.cs | 39 +- .../Startup/ChatClientStartup.cs | 51 +- .../Startup/CompilationStartup.cs | 61 +- .../Startup/ConfigurationStartup.cs | 98 +- .../Startup/ConversationSeamStartup.cs | 190 +- .../Startup/ConversationSessionStartup.cs | 147 +- .../Startup/ConversationStartup.cs | 55 +- .../Startup/EmbeddingStartup.cs | 43 +- .../Startup/EntryRegistry.cs | 132 +- .../Startup/EvaluationStartup.cs | 47 +- .../Startup/KnowledgeStartup.cs | 123 +- .../Startup/SecretsStartup.cs | 67 +- .../Startup/SkillsStartup.cs | 381 +- .../Startup/TelemetryStartup.cs | 51 +- .../Startup/ToolRegistryStartup.cs | 147 +- .../DependencyInjection/StartupLog.cs | 51 +- .../Endpoints/ResponsesContracts.cs | 358 +- .../Endpoints/ResponsesEndpoints.cs | 508 +-- .../Endpoints/ResponsesRequestReader.cs | 260 +- .../Endpoints/ResponsesRunInput.cs | 27 +- .../Endpoints/ResponsesSessionFiling.cs | 33 +- .../Endpoints/ResponsesTurn.cs | 49 +- .../Endpoints/ResponsesTurnReply.cs | 65 +- .../Endpoints/ResponsesTurnStream.cs | 185 +- .../Endpoints/TurnStreamFiles.cs | 76 +- .../Endpoints/TurnStreamParts.cs | 229 +- .../Sessions/AgentCoreAgentSessionStore.cs | 115 +- .../Sessions/ConversationSessionSweeper.cs | 100 +- .../TelnyxRelay/TelnyxRelayConnection.cs | 1661 ++++---- .../TelnyxRelay/TelnyxRelayContracts.cs | 163 +- .../TelnyxRelayConversationAdapter.cs | 211 +- .../TelnyxRelayConversationChannelFactory.cs | 77 +- .../TelnyxRelay/TelnyxRelayEndpoints.cs | 152 +- .../TelnyxRelay/TelnyxRelayFrameReader.cs | 183 +- .../Vendors/TelnyxRelay/TelnyxRelayJson.cs | 31 +- .../Vendors/TelnyxRelay/TelnyxRelayLog.cs | 597 +-- .../Vendors/TelnyxRelay/TelnyxRelayOptions.cs | 77 +- .../TelnyxRelay/TelnyxRelaySpeechAdapter.cs | 55 +- src/AgentCore.Domain/Audit/AuditEvent.cs | 79 +- src/AgentCore.Domain/Audit/AuditEventKind.cs | 41 +- src/AgentCore.Domain/Audit/AuditEventKinds.cs | 74 +- .../Audit/AuditEventVocabulary.cs | 239 +- src/AgentCore.Domain/Audit/AuditHash.cs | 151 +- .../Audit/AuditPayloadKeys.cs | 121 +- .../Audit/ConversationEndReason.cs | 115 +- .../Audit/ConversationEndReasons.cs | 100 +- src/AgentCore.Domain/Audit/ToolFailureKind.cs | 95 +- .../Audit/ToolFailureKinds.cs | 90 +- .../Knowledge/KnowledgeCard.cs | 57 +- .../Knowledge/KnowledgeScope.cs | 53 +- src/AgentCore.Domain/Knowledge/PayloadPath.cs | 59 +- src/AgentCore.Domain/PendingApproval.cs | 21 +- src/AgentCore.Domain/Sources/SourceKind.cs | 17 +- .../Sources/SourceReference.cs | 41 +- src/AgentCore.Domain/TurnResult.cs | 153 +- .../AgentCoreHostBuilderExtensions.cs | 317 +- .../AgentCoreHostEndpointExtensions.cs | 71 +- .../Secrets/ConfigurationSecretResolver.cs | 70 +- .../Audit/Postgres/PostgresAuditSink.cs | 246 +- .../Postgres/PostgresAuditSinkAdapter.cs | 51 +- .../Blobs/S3/S3BlobStore.cs | 284 +- .../Blobs/S3/S3BlobStoreAdapter.cs | 121 +- .../Postgres/PostgresConversationRows.cs | 108 +- .../Postgres/PostgresConversationStore.cs | 535 +-- .../PostgresConversationStoreAdapter.cs | 51 +- .../Postgres/PostgresConversationStoreSql.cs | 187 +- .../PostgresConversationVerification.cs | 67 +- .../Postgres/PostgresConversationWords.cs | 328 +- .../Postgres/PostgresDataSourceFactory.cs | 83 +- .../Database/Postgres/PostgresSchema.cs | 257 +- .../OpenAI/OpenAiEmbeddingGeneratorAdapter.cs | 77 +- .../OpenAiModerationAdapter.cs | 57 +- .../OpenAiModerationEvaluator.cs | 622 +-- .../VectorData/Qdrant/FieldsPointMapper.cs | 83 +- .../VectorData/Qdrant/IQdrantSearchChannel.cs | 71 +- .../Qdrant/QdrantCollectionProof.cs | 432 ++- .../Qdrant/QdrantKnowledgeAdapter.cs | 453 +-- .../VectorData/Qdrant/QdrantKnowledgeStore.cs | 535 +-- .../Qdrant/QdrantKnowledgeStoreOptions.cs | 79 +- .../VectorData/Qdrant/QdrantPayload.cs | 55 +- .../VectorData/Qdrant/QdrantPointConverter.cs | 56 +- .../VectorData/Qdrant/QdrantScopeMatcher.cs | 159 +- .../VectorData/Qdrant/QdrantSearchChannel.cs | 140 +- .../VectorData/Qdrant/Uuid5PointId.cs | 101 +- .../Llm/OpenAI/OpenAiChatClientAdapter.cs | 199 +- .../Llm/OpenAI/OpenAiContextWindows.cs | 73 +- .../Secrets/ChainedSecretResolver.cs | 107 +- .../Secrets/EnvironmentSecretResolver.cs | 118 +- .../Secrets/FileSecretResolver.cs | 129 +- .../Grafana/GrafanaOtlpTelemetryAdapter.cs | 340 +- .../Telemetry/Grafana/OtlpTelemetrySession.cs | 132 +- .../Tools/HttpToolSource.cs | 265 +- .../Tools/Mcp/McpConnectionFactory.cs | 155 +- .../Tools/Mcp/McpLog.cs | 155 +- .../Tools/Mcp/McpServerSession.cs | 704 ++-- .../Tools/Mcp/McpTool.cs | 212 +- .../Tools/Mcp/McpToolDescriptor.cs | 29 +- .../Tools/McpToolSource.cs | 389 +- .../Audit/AuditConversationObserverTests.cs | 441 ++- .../Audit/AuditSinkFactoryTests.cs | 371 +- .../Audit/ConversationSessionAuditTests.cs | 1025 ++--- .../ConversationSessionModerationTests.cs | 543 +-- .../Audit/QueuedAuditSinkTests.cs | 347 +- .../Blobs/BlobLinkTests.cs | 61 +- .../Blobs/BlobNameTests.cs | 101 +- .../Blobs/BlobPolicyTests.cs | 203 +- .../Blobs/BlobStoreFactoryTests.cs | 225 +- .../Configuration/AgentHarnessTests.cs | 159 +- .../Configuration/AgentKnowledgeTests.cs | 357 +- .../Configuration/AgenticKeySchemaTests.cs | 127 +- .../Compilation/AgentToolTests.cs | 562 +-- .../Compilation/ApprovalCompilationTests.cs | 281 +- .../Compilation/BackgroundCompilationTests.cs | 288 +- .../ClarificationWiringBindingTests.cs | 312 +- .../Compilation/CompactionCompilationTests.cs | 125 +- .../Compilation/CompileTableTests.cs | 509 +-- .../CompiledAgentConcurrencyTests.cs | 172 +- .../Compilation/CompiledAgentRunTests.cs | 209 +- ...igurationCompilerConversationStampTests.cs | 117 +- .../ConfigurationCompilerModelFacingTests.cs | 107 +- .../DiscoveredToolReferenceTests.cs | 120 +- .../Compilation/FilesCompilationTests.cs | 539 ++- .../Compilation/GraphNoMatchTests.cs | 416 +- .../Compilation/GuardedGraphEdgeTests.cs | 555 +-- .../Compilation/HarnessCompilationTests.cs | 399 +- .../Compilation/HostedWebSearchDropTests.cs | 364 +- .../KnowledgeProviderBindingTests.cs | 225 +- .../KnowledgeProviderSchemaTests.cs | 172 +- .../Compilation/LoopCompilationTests.cs | 246 +- .../Compilation/MemoryCompilationTests.cs | 611 ++- .../Compilation/ShellOptionsCompilerTests.cs | 108 +- .../Compilation/SkillsProviderBindingTests.cs | 101 +- .../Configuration/ConfigurationBinderTests.cs | 439 +-- .../Configuration/ConfigurationLoaderTests.cs | 825 ++-- .../ConfigurationRoundTripTests.cs | 357 +- .../ConfigurationSchemaValidatorTests.cs | 905 ++--- .../Configuration/ConversationSchemaTests.cs | 221 +- .../Configuration/ExampleDocument.cs | 78 +- .../Configuration/ExampleDocumentTests.cs | 75 +- .../Configuration/FacetResolveSchemaTests.cs | 49 +- .../Configuration/McpConfigurationTests.cs | 279 +- .../McpServerConfigurationTests.cs | 254 +- .../Validation/ConfigurationValidatorTests.cs | 1932 +++++----- .../Validation/GuardEvaluatorTests.cs | 521 +-- .../KnowledgeFilterValidatorTests.cs | 180 +- .../ReasoningTemperatureCheckTests.cs | 147 +- .../Validation/StateDomainTests.cs | 58 +- .../ChatConversationTitlerTests.cs | 431 ++- .../Conversation/ConversationChannelTests.cs | 113 +- .../Conversation/ConversationCursorTests.cs | 91 +- .../ConversationSessionStateTests.cs | 142 +- .../ConversationSpeechPairingTests.cs | 213 +- .../ConversationStoreFactoryTests.cs | 263 +- .../Conversation/ConversationsTests.cs | 419 +- .../DelegatingConversationStoreTests.cs | 79 +- ...nMemoryConversationStoreSummaryRowTests.cs | 77 +- .../InMemoryConversationStoreTests.cs | 478 +-- ...nMemoryConversationStoreTranscriptTests.cs | 204 +- .../InMemoryConversationStoreWindowTests.cs | 107 +- .../InMemoryConversationStoreAppendTests.cs | 325 +- .../Diagnostics/DiagnosticsFakes.cs | 183 +- .../Diagnostics/LibraryOpenTelemetryTests.cs | 755 ++-- .../LoggingConversationObserverTests.cs | 381 +- .../TelemetryConversationObserverTests.cs | 251 +- .../Diagnostics/TelemetrySeamTests.cs | 386 +- .../Diagnostics/TurnObservabilityTests.cs | 687 ++-- ...CompositeEmbeddingGeneratorFactoryTests.cs | 224 +- .../Fakes/CountingEmbeddingGenerator.cs | 49 +- .../RecordingEmbeddingGeneratorAdapter.cs | 89 +- .../HybridCachingEmbeddingGeneratorTests.cs | 115 +- .../DocumentRecallEvaluatorTests.cs | 279 +- .../Evaluation/EvaluationSamplerTests.cs | 129 +- .../Evaluation/EvaluatorRegistryTests.cs | 125 +- .../Evaluation/Fakes/RecordingEvaluator.cs | 53 +- .../Fakes/ScriptedModerationEvaluator.cs | 183 +- .../Evaluation/FaultCodeEvaluatorTests.cs | 406 +- .../Evaluation/PromptModeratorTests.cs | 211 +- .../Evaluation/ScorePublishingTests.cs | 179 +- .../Fakes/FakeChatClientFactory.cs | 42 +- .../Fakes/RecordingBlobStore.cs | 69 +- .../Fakes/RecordingChatClientAdapter.cs | 170 +- .../Fakes/RecordingConversationStore.cs | 150 +- .../Fakes/RequestRecordingChatClient.cs | 82 +- .../Fakes/ScriptedChatClient.cs | 124 +- .../Fakes/ShellScriptedClient.cs | 139 +- .../Fakes/TestGuardEvaluator.cs | 105 +- .../Fakes/ThrowingConversationStore.cs | 45 +- .../Fakes/ToolCallingChatClient.cs | 199 +- .../CompositeKnowledgeStoreFactoryTests.cs | 434 ++- .../Knowledge/FacetFilterTests.cs | 560 +-- .../Fakes/RecordingKnowledgeStoreAdapter.cs | 102 +- .../Knowledge/Fakes/StubKnowledgePort.cs | 221 +- ...ybridCachingKnowledgeRetrievalPortTests.cs | 271 +- .../Knowledge/KnowledgeAuditRecordTests.cs | 320 +- .../Knowledge/KnowledgeCardMapperTests.cs | 224 +- .../KnowledgeCitationFormatterFactoryTests.cs | 162 +- .../Knowledge/KnowledgeProbeTests.cs | 1950 +++++----- .../KnowledgeProviderFactoryTests.cs | 1440 +++---- .../Knowledge/KnowledgeQueryAnalyzerTests.cs | 32 +- .../Knowledge/KnowledgeSourceMapperTests.cs | 104 +- .../Knowledge/StateKnowledgeScopeTests.cs | 167 +- .../Knowledge/ToolFacetOverlayTests.cs | 163 +- .../Llm/CompositeChatClientFactoryTests.cs | 493 +-- .../Llm/HostedWebSearchCapabilityTests.cs | 80 +- .../Policy/ConversationPolicyGoldenSet.cs | 350 +- .../Policy/GoldenConversationReplayTests.cs | 129 +- .../Policy/StagePolicyTests.cs | 163 +- .../Ports/VendorAdapterTests.cs | 48 +- .../Providers/VendorAdapterSelectorTests.cs | 253 +- .../Runtime/AgentCoreAgentSessionTests.cs | 574 +-- .../Runtime/AgentCoreAgentTestSupport.cs | 80 +- .../Runtime/AgentCoreAgentTests.cs | 234 +- .../Runtime/AgentSessionAcrossAgentsTests.cs | 188 +- ...nctionInvokingChatClientCallRecordTests.cs | 83 +- ...ctionInvokingChatClientErrorPolicyTests.cs | 480 ++- ...ingFunctionInvokingChatClientStripTests.cs | 289 +- .../Runtime/ClarificationTextTests.cs | 94 +- .../Runtime/ClarificationsTests.cs | 482 +-- .../Runtime/CompactionStrategyFactoryTests.cs | 259 +- .../Runtime/ConversationEventKindsTests.cs | 127 +- .../ConversationObserverDispatcherTests.cs | 553 +-- .../Runtime/ConversationObserversTests.cs | 135 +- .../ConversationSessionApprovalTests.cs | 268 +- .../Runtime/ConversationSessionEditTests.cs | 328 +- ...versationSessionFactoryModelFacingTests.cs | 72 +- .../ConversationSessionGraphReplyTests.cs | 329 +- .../ConversationSessionInterruptionTests.cs | 1767 ++++----- .../Runtime/ConversationSessionProbeTests.cs | 251 +- .../Runtime/ConversationSessionTests.cs | 1670 ++++---- .../ConversationSessionWorkspaceTests.cs | 243 +- .../Runtime/ConversationWorkspaceTests.cs | 141 +- .../Runtime/DelegatedToolsTests.cs | 245 +- .../Harness/BackgroundChildAgentTests.cs | 189 +- .../Runtime/Harness/CallerTimeZoneTests.cs | 51 +- .../Harness/ClockContextProviderTests.cs | 45 +- .../Harness/ConversationFilesProviderTests.cs | 197 +- .../ConversationSessionBackgroundTests.cs | 274 +- .../ConversationSessionGraphStateTests.cs | 265 +- .../ConversationSessionProviderStateTests.cs | 368 +- .../Harness/ConversationSessionShellTests.cs | 490 +-- .../Harness/ConversationShellsTests.cs | 347 +- .../Harness/HarnessSessionStateTests.cs | 102 +- .../Runtime/Harness/ProcHelpers.cs | 45 +- ...dgeScopeThroughConversationSessionTests.cs | 437 +-- .../Runtime/ModelFacingChatClientTests.cs | 181 +- .../Runtime/RuntimeFakes.cs | 1063 +++-- .../Runtime/ToolResultCapProviderTests.cs | 95 +- .../Runtime/Turn/TurnContextProviderTests.cs | 407 +- .../Runtime/Turn/TurnFilesTests.cs | 107 +- .../Runtime/Turn/TurnResultsTests.cs | 221 +- .../Runtime/Turn/TurnSourcesTests.cs | 172 +- .../Runtime/TurnPipelineTests.cs | 603 +-- .../Runtime/TurnScreenTests.cs | 251 +- .../Secrets/ResolvedSecretsTests.cs | 294 +- .../Secrets/SecretOptionalReadTests.cs | 325 +- .../Secrets/SecretResolverExtensionsTests.cs | 493 +-- .../Sessions/ConversationSessionsTests.cs | 319 +- .../Skills/PinnedSkillsProviderTests.cs | 153 +- .../Skills/ReadOnlySkillsProviderTests.cs | 97 +- .../Skills/SkillCatalogTests.cs | 51 +- .../Skills/SkillsProviderFactoryTests.cs | 127 +- .../State/StateDocumentTests.cs | 250 +- .../State/StateExtractorTests.cs | 370 +- .../State/StateWriterTests.cs | 245 +- .../State/ToolResultPathTests.cs | 341 +- .../State/UnfilledSlotReminderTests.cs | 295 +- .../Tools/BindingToolTests.cs | 461 +-- .../Tools/BuiltinToolTests.cs | 155 +- .../Tools/CachedToolTests.cs | 362 +- .../Tools/DeclaredToolTests.cs | 243 +- .../Tools/FilePublishBackgroundChildTests.cs | 105 +- .../Tools/FilePublishToolDefinitionTests.cs | 307 +- .../Tools/TimeLimitedToolTests.cs | 251 +- .../Tools/ToolCallScopeTests.cs | 251 +- .../Tools/ToolRegistryTests.cs | 224 +- .../Tools/TypedBindingToolTests.cs | 493 +-- .../Tools/WebSearchToolDefinitionTests.cs | 49 +- ...AgentCoreChatHistoryProviderTestSupport.cs | 237 +- .../AgentCoreChatHistoryProviderTests.cs | 464 +-- ...entCoreChatHistoryProviderTruncateTests.cs | 339 +- .../Transcript/CapturingChatClient.cs | 87 +- .../CompiledHistoryProviderTests.cs | 705 ++-- .../ConversationSessionCompactionEditTests.cs | 261 +- ...nversationSessionCompactionFailureTests.cs | 268 +- ...onversationSessionCompactionTestSupport.cs | 140 +- .../ConversationSessionCompactionTests.cs | 324 +- ...ConversationSessionConversationRowTests.cs | 119 +- ...ConversationSessionGraphTranscriptTests.cs | 492 +-- .../ConversationSessionOutsideAppendTests.cs | 353 +- .../ConversationSessionResumeTestSupport.cs | 183 +- .../ConversationSessionResumeTests.cs | 185 +- .../ConversationSessionStateRestoreTests.cs | 625 +-- .../ConversationSessionStoreFailureTests.cs | 366 +- .../ConversationSessionTranscriptTests.cs | 678 ++-- .../ConversationTranscriptCompactionTests.cs | 315 +- .../ConversationTranscriptEditTests.cs | 257 +- .../Transcript/ConversationTranscriptTests.cs | 348 +- .../Transcript/FileContentTests.cs | 48 +- .../Transcript/InnerAgentTranscriptTests.cs | 78 +- .../Transcript/ReaderContentTests.cs | 49 +- .../Transcript/SourceContentTests.cs | 93 +- .../Transcript/TranscriptJsonTests.cs | 115 +- .../ConversationChannelShapeTests.cs | 69 +- .../ConversationInputPortTests.cs | 103 +- .../ConversationOptionsFromDocumentTests.cs | 173 +- .../ConversationRegistrationTests.cs | 345 +- .../ConversationRouteSelectionTests.cs | 327 +- .../ConversationTurnArbiterTests.cs | 506 +-- ...nyxRelayThroughTheConversationSeamTests.cs | 81 +- .../DependencyInjection/AddAgentCoreTests.cs | 3429 +++++++++-------- .../AgentCoreHttpClientsTests.cs | 265 +- .../AmbiguityStartupTests.cs | 186 +- .../KnowledgeLoggingThroughBootTests.cs | 167 +- .../KnowledgeScopeArgumentOrderTests.cs | 267 +- .../KnowledgeStartupTests.cs | 366 +- .../DependencyInjection/SkillsStartupTests.cs | 580 +-- .../DependencyInjection/StartedHost.cs | 29 +- .../DependencyInjection/StartedHostFixture.cs | 121 +- .../ToolRegistryStartupTests.cs | 302 +- .../WorkspaceStartupTests.cs | 191 +- .../OpenAiEmbeddingGeneratorAdapterTests.cs | 167 +- .../Endpoints/ApprovalWireTests.cs | 449 +-- .../Endpoints/FileWireTests.cs | 303 +- .../Endpoints/ResponsesTests.cs | 1014 ++--- .../Endpoints/SourceWireTests.cs | 477 +-- .../Endpoints/TimeZoneHeaderTests.cs | 79 +- .../Endpoints/ToolWireTests.cs | 548 +-- .../Endpoints/TurnStreamFilesTests.cs | 173 +- .../Fakes/EventObservedLoggerProvider.cs | 122 +- .../Fakes/FakeBlobStoreAdapter.cs | 95 +- .../Fakes/FakeChatClientAdapter.cs | 38 +- .../Fakes/FakeConversationInput.cs | 104 +- .../Fakes/FakeConversationOutput.cs | 77 +- .../Fakes/FakeRelayClient.cs | 458 +-- .../Fakes/FakeWebSocket.cs | 687 ++-- .../Fakes/HostFakes.cs | 542 ++- .../Fakes/RelayFrames.cs | 67 +- .../Fakes/ResponsesHost.cs | 233 +- .../Fakes/ScriptedHttpMessageHandler.cs | 59 +- .../Fakes/TelnyxRelayHost.cs | 529 +-- .../OpenAI/OpenAiChatClientAdapterTests.cs | 185 +- .../ConversationSessionsRelayTests.cs | 119 +- .../TelnyxRelay/TelnyxRelayBargeInTests.cs | 1323 +++---- .../TelnyxRelayConversationEndTests.cs | 1283 +++--- .../TelnyxRelay/TelnyxRelayEndpointTests.cs | 428 +- .../TelnyxRelay/TelnyxRelayFrameCostTests.cs | 461 +-- .../TelnyxRelayFrameReaderTests.cs | 423 +- .../TelnyxRelay/TelnyxRelayTurnTests.cs | 693 ++-- .../TelnyxRelay/TelnyxRelayWriteLoopTests.cs | 324 +- .../Audit/AuditEventVocabularyTests.cs | 767 ++-- .../Audit/AuditHashTests.cs | 55 +- .../Knowledge/KnowledgeScopeTests.cs | 25 +- .../AgentCore.Domain.Tests/TurnResultTests.cs | 91 +- tests/AgentCore.Evals/BaselineGateTests.cs | 173 +- tests/AgentCore.Evals/DatasetFixture.cs | 47 +- tests/AgentCore.Evals/DatasetHarness.cs | 196 +- tests/AgentCore.Evals/EvalGateCollection.cs | 47 +- tests/AgentCore.Evals/EvalHarness.cs | 153 +- tests/AgentCore.Evals/EvalHarnessTests.cs | 161 +- tests/AgentCore.Evals/EvalStoreCollection.cs | 61 +- tests/AgentCore.Evals/FixtureEvalTests.cs | 43 +- .../GateLastCollectionOrderer.cs | 91 +- tests/AgentCore.Evals/GoldenRow.cs | 72 +- tests/AgentCore.Evals/GoldenSet.cs | 146 +- tests/AgentCore.Evals/GoldenSetEvalTests.cs | 126 +- tests/AgentCore.Evals/ScoreBaseline.cs | 206 +- .../AgentCoreHostTests.cs | 1065 ++--- .../ConfigurationSecretResolverTests.cs | 262 +- .../Postgres/PostgresAuditSinkAdapterTests.cs | 156 +- .../Audit/Postgres/PostgresAuditSinkTests.cs | 577 +-- .../Blobs/S3/S3BlobStoreAdapterTests.cs | 47 +- .../Blobs/S3/S3BlobStoreLinkTests.cs | 150 +- .../Blobs/S3/S3BlobStoreTests.cs | 277 +- .../Blobs/S3/S3Bucket.cs | 43 +- .../Blobs/S3/S3FactAttribute.cs | 29 +- .../Postgres/ContinuationStoreTests.cs | 95 +- .../Postgres/ConversationThreadSchemaTests.cs | 201 +- .../Postgres/PostgresConversationListTests.cs | 369 +- .../PostgresConversationPrincipalTests.cs | 195 +- .../PostgresConversationStoreAppendTests.cs | 356 +- ...ostgresConversationStoreSummaryRowTests.cs | 85 +- .../PostgresConversationStoreSweepTests.cs | 213 +- .../PostgresConversationStoreTests.cs | 436 +-- .../PostgresConversationStoreTruncateTests.cs | 211 +- .../PostgresConversationStoreWindowTests.cs | 113 +- .../PostgresConversationStoreWordsTests.cs | 801 ++-- .../Database/Postgres/PostgresCluster.cs | 25 +- .../Database/Postgres/PostgresDatabaseTest.cs | 99 +- .../Postgres/PostgresFactAttribute.cs | 39 +- .../Database/Postgres/PostgresSchemaTests.cs | 508 +-- .../Database/Postgres/PostgresTestDatabase.cs | 127 +- .../Postgres/PostgresTheoryAttribute.cs | 31 +- .../OpenAiModerationEvaluatorTests.cs | 884 ++--- .../Fakes/FakeEmbeddingGenerator.cs | 70 +- .../Fakes/StubHandlerFactory.cs | 39 +- .../Qdrant/AmbiguityIntegrationTests.cs | 1058 ++--- .../Qdrant/DirectLinkLookupTests.cs | 114 +- .../VectorData/Qdrant/FacetReadTests.cs | 175 +- .../Qdrant/Fakes/CapturingSearchChannel.cs | 119 +- .../Qdrant/Fakes/FacetScrollChannel.cs | 67 +- .../Qdrant/Fakes/HangingSearchChannel.cs | 45 +- .../Qdrant/Fakes/RecordingSearchChannel.cs | 59 +- .../Qdrant/FieldsPointMapperTests.cs | 232 +- .../VectorData/Qdrant/ForeignCorpus.cs | 152 +- .../VectorData/Qdrant/ForeignSchemaTests.cs | 410 +- .../VectorData/Qdrant/HostileCorpus.cs | 151 +- .../VectorData/Qdrant/HostileSchemaTests.cs | 284 +- .../VectorData/Qdrant/KbShapedCorpus.cs | 524 +-- .../VectorData/Qdrant/KbShapedCorpusTests.cs | 292 +- .../VectorData/Qdrant/QdrantFactAttribute.cs | 31 +- .../Qdrant/QdrantKnowledgeAdapterTests.cs | 1666 ++++---- .../Qdrant/QdrantKnowledgeStoreTests.cs | 1023 ++--- .../Qdrant/QdrantPointConverterTests.cs | 76 +- .../Qdrant/QdrantSearchChannelTests.cs | 122 +- .../VectorData/Qdrant/QdrantServer.cs | 57 +- .../Qdrant/QdrantServerCollection.cs | 33 +- .../Qdrant/QdrantTheoryAttribute.cs | 31 +- .../Qdrant/QdrantWildcardScopeTests.cs | 236 +- .../Qdrant/ScoreFloorOnPrefetchTests.cs | 189 +- .../Qdrant/StoreNamingNeutralityTests.cs | 390 +- .../Knowledge/VectorData/Qdrant/TestScopes.cs | 18 +- .../VectorData/Qdrant/Uuid5PointIdTests.cs | 159 +- .../Qdrant/WildcardScopeIntegrationTests.cs | 281 +- .../Llm/CapturingChatClient.cs | 55 +- .../Llm/OpenAiContextWindowsTests.cs | 53 +- .../Llm/OpenAiPromptCacheKeyTests.cs | 97 +- .../Llm/OpenAiReasoningEffortTests.cs | 300 +- .../Secrets/SecretResolverTests.cs | 290 +- .../GrafanaOtlpTelemetryAdapterTests.cs | 145 +- .../ToolSeamTests.cs | 193 +- .../Tools/Fakes/ControllableMcpServer.cs | 334 +- .../Tools/Fakes/InProcessMcpServer.cs | 153 +- .../Tools/HttpToolSourceTests.cs | 480 +-- .../Tools/McpConnectionFactoryTests.cs | 364 +- .../Tools/McpServerSessionTests.cs | 663 ++-- .../Tools/McpToolSourceTests.cs | 542 +-- .../Tools/StubHttpMessageHandler.cs | 63 +- .../AssertionMethodAttribute.cs | 9 + .../ConversationStoreReadAll.cs | 17 +- .../ConversationStoreSummaryRowFacts.cs | 230 +- .../DelegatingConversationStore.cs | 283 +- .../AgentCore.TestSupport/FakeTimeProvider.cs | 211 +- .../LambdaChatClientFactory.cs | 40 +- .../MapSecretResolver.cs | 41 +- .../ParkingConversationStore.cs | 69 +- .../RecordingChatClientFactory.cs | 114 +- .../RecordingLoggerFactory.cs | 155 +- .../RequestCapturingChatClient.cs | 75 +- .../RoutingChatClientFactory.cs | 57 +- tests/AgentCore.TestSupport/SkillFolder.cs | 219 +- .../AgentCore.TestSupport/TestToolRegistry.cs | 87 +- 826 files changed, 85882 insertions(+), 83037 deletions(-) create mode 100644 .editorconfig create mode 100644 src/AgentCore.Application/Runtime/ConversationInterruptionTracker.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationInterruptionTracker.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionLifetime.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTurn.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCompletion.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnWriters.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/ReplyOutcome.cs delete mode 100644 src/AgentCore.Application/Runtime/ConversationSession/TranscriptEntry.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationSessionLifetime.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationSessionStateStore.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTranscriptLedger.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTurn.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTurnCommit.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTurnCompletion.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTurnRunner.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTurnStream.cs create mode 100644 src/AgentCore.Application/Runtime/ConversationTurnWriters.cs create mode 100644 src/AgentCore.Application/Runtime/ReplyOutcome.cs create mode 100644 src/AgentCore.Application/Runtime/TranscriptEntry.cs create mode 100644 tests/AgentCore.TestSupport/AssertionMethodAttribute.cs diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..6b6210aa --- /dev/null +++ b/.editorconfig @@ -0,0 +1,22 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 4 + +[*.{csproj,props,targets,json,xml,yaml,yml,md}] +indent_size = 2 + +[*.cs] +# Every IDE style rule at the Roslyn default preference, raised from hidden to suggestion so that +# dotnet format applies it and SonarQube reports whatever is left. +dotnet_analyzer_diagnostic.category-Style.severity = suggestion + +# Off because it folds every guard before a return into a ternary, and a second guard then nests +# one ternary inside another, which SonarQube S3358 forbids. Sonar wins. +dotnet_style_prefer_conditional_expression_over_return = false +dotnet_style_prefer_conditional_expression_over_assignment = false diff --git a/src/AgentCore.Application/Audit/AuditConversationObserver.cs b/src/AgentCore.Application/Audit/AuditConversationObserver.cs index 89cc0bff..ec9dc335 100644 --- a/src/AgentCore.Application/Audit/AuditConversationObserver.cs +++ b/src/AgentCore.Application/Audit/AuditConversationObserver.cs @@ -2,57 +2,58 @@ using AgentCore.Application.Runtime; using AgentCore.Domain.Audit; -namespace AgentCore.Application.Audit; - -/// -/// Turns the durable facts of a call into the append-only chain of D23. -/// -internal sealed class AuditConversationObserver : IConversationObserver +namespace AgentCore.Application.Audit { - private readonly IAuditSinkPort _sink; - - /// Creates the observer that writes the chain. - /// Where the rows go. - /// is . - public AuditConversationObserver(IAuditSinkPort sink) + /// + /// Turns the durable facts of a call into the append-only chain of D23. + /// + internal sealed class AuditConversationObserver : IConversationObserver { - ArgumentNullException.ThrowIfNull(sink); + private readonly IAuditSinkPort _sink; - _sink = sink; - } - - /// - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(conversationEvent); - - // A diagnostic-only fact took no identity, so there is no row to write and nothing to report. - if (conversationEvent.EventId is not { } eventId) + /// Creates the observer that writes the chain. + /// Where the rows go. + /// is . + public AuditConversationObserver(IAuditSinkPort sink) { - return ValueTask.CompletedTask; - } + ArgumentNullException.ThrowIfNull(sink); - // The two enums are not interchangeable, and a value outside the closed set is dropped rather - // than thrown over: the turn loop pairs an identity with a stored kind, so this is unreachable - // for any event the session raises, and audit is a record of the conversation and never a part of it. - if (!ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind kind)) - { - return ValueTask.CompletedTask; + _sink = sink; } - AuditEvent auditEvent = new() + /// + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - ConversationId = conversationEvent.ConversationId, - EventId = eventId, - Kind = kind, - OccurredAt = conversationEvent.OccurredAt, - TurnIndex = conversationEvent.TurnIndex, - AmendsEventId = conversationEvent.AmendsEventId, - Payload = conversationEvent.Payload, - }; - - // The token of the run belongs to the dispatcher, which passes CancellationToken.None: the - // enqueue belongs to the record of the conversation, not to a turn the caller may have cancelled. - return _sink.AppendAsync(auditEvent, cancellationToken); + ArgumentNullException.ThrowIfNull(conversationEvent); + + // A diagnostic-only fact took no identity, so there is no row to write and nothing to report. + if (conversationEvent.EventId is not { } eventId) + { + return ValueTask.CompletedTask; + } + + // The two enums are not interchangeable, and a value outside the closed set is dropped rather + // than thrown over: the turn loop pairs an identity with a stored kind, so this is unreachable + // for any event the session raises, and audit is a record of the conversation and never a part of it. + if (!ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind kind)) + { + return ValueTask.CompletedTask; + } + + AuditEvent auditEvent = new() + { + ConversationId = conversationEvent.ConversationId, + EventId = eventId, + Kind = kind, + OccurredAt = conversationEvent.OccurredAt, + TurnIndex = conversationEvent.TurnIndex, + AmendsEventId = conversationEvent.AmendsEventId, + Payload = conversationEvent.Payload, + }; + + // The token of the run belongs to the dispatcher, which passes CancellationToken.None: the + // enqueue belongs to the record of the conversation, not to a turn the caller may have cancelled. + return _sink.AppendAsync(auditEvent, cancellationToken); + } } } diff --git a/src/AgentCore.Application/Audit/AuditSinkFactory.cs b/src/AgentCore.Application/Audit/AuditSinkFactory.cs index 553bf8a1..1db78ea4 100644 --- a/src/AgentCore.Application/Audit/AuditSinkFactory.cs +++ b/src/AgentCore.Application/Audit/AuditSinkFactory.cs @@ -4,52 +4,53 @@ using AgentCore.Application.Ports; using AgentCore.Application.Providers; -namespace AgentCore.Application.Audit; - -/// -/// Opens the audit sink the document names, from the adapters the host registered. -/// -public static class AuditSinkFactory +namespace AgentCore.Application.Audit { - /// The built-in kind, and the one a document that names no provider gets. - public const string MemoryKind = "memory"; - - /// What this seam conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam Seam = - new("providers.audit", "/providers/audit/kind", "options.UseAuditSinks(...)", "sinks"); - - /// Opens the sink providers.audit names, or the built-in one. - /// The loaded document. - /// The chain a credential resolves through, or . - /// The vendors this host supports. - /// Cancels the open. - /// - /// The store, which is never . It is the raw store and not a queue: the - /// caller wraps it in , which is what keeps the append off the turn. - /// - /// The configuration or the adapters are . - /// - /// The document names a kind no adapter serves, or a kind two adapters answer to. - /// - public static ValueTask OpenAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) + /// + /// Opens the audit sink the document names, from the adapters the host registered. + /// + public static class AuditSinkFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + /// The built-in kind, and the one a document that names no provider gets. + public const string MemoryKind = "memory"; + + /// What this seam conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam Seam = + new("providers.audit", "/providers/audit/kind", "options.UseAuditSinks(...)", "sinks"); - // The document named nothing, or it named the built-in kind, and the two mean the same - // thing: an absent block is read as kind: memory. Both are answered before the selector - // runs, so neither needs a registered adapter and neither can be taken over by one. - if (configuration.Providers?.Audit is not { } entry - || string.Equals(entry.Kind, MemoryKind, StringComparison.OrdinalIgnoreCase)) + /// Opens the sink providers.audit names, or the built-in one. + /// The loaded document. + /// The chain a credential resolves through, or . + /// The vendors this host supports. + /// Cancels the open. + /// + /// The store, which is never . It is the raw store and not a queue: the + /// caller wraps it in , which is what keeps the append off the turn. + /// + /// The configuration or the adapters are . + /// + /// The document names a kind no adapter serves, or a kind two adapters answer to. + /// + public static ValueTask OpenAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - return ValueTask.FromResult(new InMemoryAuditSink()); - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); + + // The document named nothing, or it named the built-in kind, and the two mean the same + // thing: an absent block is read as kind: memory. Both are answered before the selector + // runs, so neither needs a registered adapter and neither can be taken over by one. + if (configuration.Providers?.Audit is not { } entry + || string.Equals(entry.Kind, MemoryKind, StringComparison.OrdinalIgnoreCase)) + { + return ValueTask.FromResult(new InMemoryAuditSink()); + } - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); - return adapter.OpenAsync(entry, secrets, cancellationToken); + IAuditSinkAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); + return adapter.OpenAsync(entry, secrets, cancellationToken); + } } } diff --git a/src/AgentCore.Application/Audit/Memory/InMemoryAuditSink.cs b/src/AgentCore.Application/Audit/Memory/InMemoryAuditSink.cs index b14b2def..1d754a74 100644 --- a/src/AgentCore.Application/Audit/Memory/InMemoryAuditSink.cs +++ b/src/AgentCore.Application/Audit/Memory/InMemoryAuditSink.cs @@ -1,56 +1,57 @@ using AgentCore.Application.Ports; using AgentCore.Domain.Audit; -namespace AgentCore.Application.Audit.Memory; - -/// -/// The sink that keeps every event in a list. -/// -public sealed class InMemoryAuditSink : IAuditSinkPort +namespace AgentCore.Application.Audit.Memory { - private readonly Lock _gate = new(); + /// + /// The sink that keeps every event in a list. + /// + public sealed class InMemoryAuditSink : IAuditSinkPort + { + private readonly Lock _gate = new(); - private readonly List _events = []; + private readonly List _events = []; - /// Gets the events this sink accepted, in the order they arrived. - public IReadOnlyList Events - { - get + /// Gets the events this sink accepted, in the order they arrived. + public IReadOnlyList Events { - lock (_gate) + get { - return [.. _events]; + lock (_gate) + { + return [.. _events]; + } } } - } - - /// - /// Reads back the events of one conversation, oldest first. - /// - /// The id of the conversation. - /// The events of that conversation, in the order they arrived. - /// is . - public IReadOnlyList EventsOf(string conversationId) - { - ArgumentNullException.ThrowIfNull(conversationId); - lock (_gate) + /// + /// Reads back the events of one conversation, oldest first. + /// + /// The id of the conversation. + /// The events of that conversation, in the order they arrived. + /// is . + public IReadOnlyList EventsOf(string conversationId) { - return [.. _events.Where(item => string.Equals(item.ConversationId, conversationId, StringComparison.Ordinal))]; - } - } + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(auditEvent); - AuditEventVocabulary.Validate(auditEvent); + lock (_gate) + { + return [.. _events.Where(item => string.Equals(item.ConversationId, conversationId, StringComparison.Ordinal))]; + } + } - lock (_gate) + /// + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { - _events.Add(auditEvent); - } + ArgumentNullException.ThrowIfNull(auditEvent); + AuditEventVocabulary.Validate(auditEvent); + + lock (_gate) + { + _events.Add(auditEvent); + } - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } } diff --git a/src/AgentCore.Application/Audit/QueuedAuditSink.cs b/src/AgentCore.Application/Audit/QueuedAuditSink.cs index ea5c8cc2..9590cbcd 100644 --- a/src/AgentCore.Application/Audit/QueuedAuditSink.cs +++ b/src/AgentCore.Application/Audit/QueuedAuditSink.cs @@ -5,250 +5,251 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Audit; - -/// -/// Puts a bounded queue and a batching background writer in front of any other audit sink. -/// -public sealed class QueuedAuditSink : IAuditSinkPort, IAsyncDisposable, IDisposable +namespace AgentCore.Application.Audit { - /// The number of events the queue holds before it starts dropping. - public const int DefaultCapacity = 10_000; - - /// The most events the writer hands the store in one conversation. - public const int DefaultBatchSize = 100; - - /// How long waits for the drain before it gives up. - private static readonly TimeSpan DisposeTimeout = TimeSpan.FromSeconds(5); - - private readonly IAuditSinkPort _inner; - - private readonly ILogger _logger; - - private readonly Channel _queue; - - private readonly CancellationTokenSource _stopping = new(); - - private readonly Task _writer; - - private readonly int _batchSize; - - /// The events accepted and not yet handed to the store. reads it. - private int _pending; - - /// Gets the store this queue writes into. - public IAuditSinkPort Store => _inner; + /// + /// Puts a bounded queue and a batching background writer in front of any other audit sink. + /// + public sealed class QueuedAuditSink : IAuditSinkPort, IAsyncDisposable, IDisposable + { + /// The number of events the queue holds before it starts dropping. + public const int DefaultCapacity = 10_000; + + /// The most events the writer hands the store in one conversation. + public const int DefaultBatchSize = 100; + + /// How long waits for the drain before it gives up. + private static readonly TimeSpan DisposeTimeout = TimeSpan.FromSeconds(5); + private readonly ILogger _logger; + + private readonly Channel _queue; + + private readonly CancellationTokenSource _stopping = new(); + + private readonly Task _writer; + + private readonly int _batchSize; + + /// The events accepted and not yet handed to the store. reads it. + private int _pending; + + /// Gets the store this queue writes into. + public IAuditSinkPort Store { get; } + + private int _closed; + + /// Puts a queue in front of one sink. + /// The store the writer hands each batch to. It may block and it may be slow. + /// + /// The logger a drop and a refused batch are reported to, or for + /// . The library never throws for want of one. + /// + /// + /// The number of events the queue holds before it drops, or . + /// + /// + /// The most events one call to the store carries, or . + /// + /// is . + /// + /// or is less than one. + /// + public QueuedAuditSink( + IAuditSinkPort inner, + ILogger? logger = null, + int capacity = DefaultCapacity, + int batchSize = DefaultBatchSize) + { + ArgumentNullException.ThrowIfNull(inner); + ArgumentOutOfRangeException.ThrowIfLessThan(capacity, 1); + ArgumentOutOfRangeException.ThrowIfLessThan(batchSize, 1); - private int _closed; + Store = inner; - /// Puts a queue in front of one sink. - /// The store the writer hands each batch to. It may block and it may be slow. - /// - /// The logger a drop and a refused batch are reported to, or for - /// . The library never throws for want of one. - /// - /// - /// The number of events the queue holds before it drops, or . - /// - /// - /// The most events one call to the store carries, or . - /// - /// is . - /// - /// or is less than one. - /// - public QueuedAuditSink( - IAuditSinkPort inner, - ILogger? logger = null, - int capacity = DefaultCapacity, - int batchSize = DefaultBatchSize) - { - ArgumentNullException.ThrowIfNull(inner); - ArgumentOutOfRangeException.ThrowIfLessThan(capacity, 1); - ArgumentOutOfRangeException.ThrowIfLessThan(batchSize, 1); + _logger = logger ?? NullLogger.Instance; - _inner = inner; + _batchSize = batchSize; - _logger = logger ?? NullLogger.Instance; + _queue = Channel.CreateBounded(new BoundedChannelOptions(capacity) + { + FullMode = BoundedChannelFullMode.Wait, + SingleReader = true, + SingleWriter = false, + }); - _batchSize = batchSize; + _writer = Task.Run(WriteAsync, CancellationToken.None); + } - _queue = Channel.CreateBounded(new BoundedChannelOptions(capacity) + /// + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { - FullMode = BoundedChannelFullMode.Wait, - SingleReader = true, - SingleWriter = false, - }); + ArgumentNullException.ThrowIfNull(auditEvent); - _writer = Task.Run(WriteAsync, CancellationToken.None); - } + // Counted before the write, so FlushAsync never reads zero while an event is in the channel. + _ = Interlocked.Increment(ref _pending); - /// - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(auditEvent); + if (_queue.Writer.TryWrite(auditEvent)) + { + return ValueTask.CompletedTask; + } - // Counted before the write, so FlushAsync never reads zero while an event is in the channel. - Interlocked.Increment(ref _pending); + // Either the queue is full or the sink is disposed. Both are a drop, and both are reported: + // the caller is a turn loop, and a turn is never told that its record was lost. + _ = Interlocked.Decrement(ref _pending); + + Report(auditEvent); - if (_queue.Writer.TryWrite(auditEvent)) - { return ValueTask.CompletedTask; } - // Either the queue is full or the sink is disposed. Both are a drop, and both are reported: - // the caller is a turn loop, and a turn is never told that its record was lost. - Interlocked.Decrement(ref _pending); - - Report(auditEvent); - - return ValueTask.CompletedTask; - } - - /// Waits until every accepted event has been handed to the store. - /// Stops waiting. It cancels no write. - /// A task that completes when nothing is left in the queue. - public async ValueTask FlushAsync(CancellationToken cancellationToken = default) - { - while (Volatile.Read(ref _pending) > 0) + /// Waits until every accepted event has been handed to the store. + /// Stops waiting. It cancels no write. + /// A task that completes when nothing is left in the queue. + public async ValueTask FlushAsync(CancellationToken cancellationToken = default) { - cancellationToken.ThrowIfCancellationRequested(); - await Task.Delay(TimeSpan.FromMilliseconds(1), cancellationToken).ConfigureAwait(false); + while (Volatile.Read(ref _pending) > 0) + { + cancellationToken.ThrowIfCancellationRequested(); + await Task.Delay(TimeSpan.FromMilliseconds(1), cancellationToken).ConfigureAwait(false); + } } - } - /// Stops taking events and writes what is queued. - /// A task that completes when the drain is done. - public async ValueTask DisposeAsync() - { - // A container captures this once per service type it is registered under, and it answers to - // two. Without this guard the second close cancels a CancellationTokenSource the first one - // already disposed. - if (Interlocked.Exchange(ref _closed, 1) != 0) + /// Stops taking events and writes what is queued. + /// A task that completes when the drain is done. + public async ValueTask DisposeAsync() { - return; - } - - // Completing the writer is what ends the drain loop, and it is also what makes every later - // TryWrite return false. The queue keeps whatever is already in it, so the drain is honest. - _queue.Writer.TryComplete(); + // A container captures this once per service type it is registered under, and it answers to + // two. Without this guard the second close cancels a CancellationTokenSource the first one + // already disposed. + if (Interlocked.Exchange(ref _closed, 1) != 0) + { + return; + } - // Bounded on purpose. A host that stops is never held by a store that will not answer, and a - // store that does answer gets the whole window to write what it already accepted. - if (!await DrainedAsync().ConfigureAwait(false)) - { - await _stopping.CancelAsync().ConfigureAwait(false); - await DrainedAsync().ConfigureAwait(false); - } + // Completing the writer is what ends the drain loop, and it is also what makes every later + // TryWrite return false. The queue keeps whatever is already in it, so the drain is honest. + _ = _queue.Writer.TryComplete(); - _stopping.Dispose(); - } + // Bounded on purpose. A host that stops is never held by a store that will not answer, and a + // store that does answer gets the whole window to write what it already accepted. + if (!await DrainedAsync().ConfigureAwait(false)) + { + await _stopping.CancelAsync().ConfigureAwait(false); + _ = await DrainedAsync().ConfigureAwait(false); + } - /// Stops taking events and writes what is queued, blocking until it is done. - public void Dispose() => DisposeAsync().AsTask().GetAwaiter().GetResult(); + _stopping.Dispose(); + } - /// Waits out the drain, and reports whether it finished rather than throwing. - /// when the writer loop ended inside . - private async Task DrainedAsync() - { - try + /// Stops taking events and writes what is queued, blocking until it is done. + public void Dispose() { - await _writer.WaitAsync(DisposeTimeout, CancellationToken.None).ConfigureAwait(false); - return true; + DisposeAsync().AsTask().GetAwaiter().GetResult(); } + + /// Waits out the drain, and reports whether it finished rather than throwing. + /// when the writer loop ended inside . + private async Task DrainedAsync() + { + try + { + await _writer.WaitAsync(DisposeTimeout, CancellationToken.None).ConfigureAwait(false); + return true; + } #pragma warning disable CA1031 // A drain that failed has already reported itself, and disposal never throws. - catch (Exception) + catch (Exception) #pragma warning restore CA1031 - { - // WriteAsync swallows everything the store raises, so a fault here is the timeout. - return false; + { + // WriteAsync swallows everything the store raises, so a fault here is the timeout. + return false; + } } - } - /// Drains the queue into the store, in batches, until the queue is complete. - /// A task that always completes, and never faults. - private async Task WriteAsync() - { - List batch = new(_batchSize); - - while (await _queue.Reader.WaitToReadAsync(CancellationToken.None).ConfigureAwait(false)) + /// Drains the queue into the store, in batches, until the queue is complete. + /// A task that always completes, and never faults. + private async Task WriteAsync() { - // Everything waiting goes in one batch, so the store pays one round trip for a burst - // rather than one for each event of it. - while (batch.Count < _batchSize && _queue.Reader.TryRead(out AuditEvent? auditEvent)) - { - batch.Add(auditEvent); - } + List batch = new(_batchSize); - if (batch.Count == 0) + while (await _queue.Reader.WaitToReadAsync(CancellationToken.None).ConfigureAwait(false)) { - continue; + // Everything waiting goes in one batch, so the store pays one round trip for a burst + // rather than one for each event of it. + while (batch.Count < _batchSize && _queue.Reader.TryRead(out AuditEvent? auditEvent)) + { + batch.Add(auditEvent); + } + + if (batch.Count == 0) + { + continue; + } + + await AppendBatchAsync(batch).ConfigureAwait(false); + batch.Clear(); } - - await AppendBatchAsync(batch).ConfigureAwait(false); - batch.Clear(); } - } - /// Hands one batch to the store, and reports whatever it refuses. - /// The events to write, in the order they were accepted. - /// A task that always completes, and never faults. - private async Task AppendBatchAsync(List batch) - { - try + /// Hands one batch to the store, and reports whatever it refuses. + /// The events to write, in the order they were accepted. + /// A task that always completes, and never faults. + private async Task AppendBatchAsync(List batch) { - await _inner.AppendManyAsync([.. batch], _stopping.Token).ConfigureAwait(false); - } + try + { + await Store.AppendManyAsync([.. batch], _stopping.Token).ConfigureAwait(false); + } #pragma warning disable CA1031 // The store is a record of the conversation and never a part of it. - catch (Exception exception) + catch (Exception exception) #pragma warning restore CA1031 - { - Report(batch, exception); - } - finally - { - // Counted down whatever happened. A batch the store refused is not pending any more: it - // is lost, and FlushAsync must not wait for a row that will never be written. - Interlocked.Add(ref _pending, -batch.Count); + { + Report(batch, exception); + } + finally + { + // Counted down whatever happened. A batch the store refused is not pending any more: it + // is lost, and FlushAsync must not wait for a row that will never be written. + _ = Interlocked.Add(ref _pending, -batch.Count); + } } - } - /// Writes the one line a dropped event is worth, and never throws. - /// The event the queue had no room for. - private void Report(AuditEvent auditEvent) - { - try + /// Writes the one line a dropped event is worth, and never throws. + /// The event the queue had no room for. + private void Report(AuditEvent auditEvent) { - Log.AuditQueueFull(_logger, auditEvent.ConversationId, auditEvent.EventId); - } + try + { + Log.AuditQueueFull(_logger, auditEvent.ConversationId, auditEvent.EventId); + } #pragma warning disable CA1031 // A logger that refuses the report is still not a part of the conversation. - catch (Exception) + catch (Exception) #pragma warning restore CA1031 - { - // The report itself failed, and there is nowhere left to report that. + { + // The report itself failed, and there is nowhere left to report that. + } } - } - /// Writes the one line a refused batch is worth, and never throws. - /// The events the store did not take. - /// The cause. - private void Report(List batch, Exception exception) - { - try + /// Writes the one line a refused batch is worth, and never throws. + /// The events the store did not take. + /// The cause. + private void Report(List batch, Exception exception) { - // One line for the batch and not one for each event. The store refused the conversation, so the - // fault is one fault, and the first event names the conversation an operator goes looking at. - Log.AuditAppendFailed( - _logger, - batch[0].ConversationId, - AuditEventKinds.ToToken(batch[0].Kind), - exception); - } + try + { + // One line for the batch and not one for each event. The store refused the conversation, so the + // fault is one fault, and the first event names the conversation an operator goes looking at. + Log.AuditAppendFailed( + _logger, + batch[0].ConversationId, + AuditEventKinds.ToToken(batch[0].Kind), + exception); + } #pragma warning disable CA1031 // A logger that refuses the report is still not a part of the conversation. - catch (Exception) + catch (Exception) #pragma warning restore CA1031 - { - // The report itself failed, and there is nowhere left to report that. + { + // The report itself failed, and there is nowhere left to report that. + } } } } diff --git a/src/AgentCore.Application/Blobs/BlobLink.cs b/src/AgentCore.Application/Blobs/BlobLink.cs index 80c8492b..a2d5237d 100644 --- a/src/AgentCore.Application/Blobs/BlobLink.cs +++ b/src/AgentCore.Application/Blobs/BlobLink.cs @@ -1,28 +1,29 @@ -namespace AgentCore.Application.Blobs; - -/// What every store agrees on when it hands a browser a link to a blob. -public static class BlobLink +namespace AgentCore.Application.Blobs { - /// How long a link works. - public static TimeSpan Lifetime { get; } = TimeSpan.FromMinutes(15); - - /// - /// The Content-Disposition a link serves the blob with: inline for what a browser - /// draws safely, attachment for everything else. SVG and HTML are never inline: both run - /// script under the store's origin. - /// - /// The blob's IANA media type. - /// The file name the browser saves it under. - /// The header value. - public static string DispositionOf(string mediaType, string name) + /// What every store agrees on when it hands a browser a link to a blob. + public static class BlobLink { - ArgumentNullException.ThrowIfNull(mediaType); - ArgumentNullException.ThrowIfNull(name); + /// How long a link works. + public static TimeSpan Lifetime { get; } = TimeSpan.FromMinutes(15); + + /// + /// The Content-Disposition a link serves the blob with: inline for what a browser + /// draws safely, attachment for everything else. SVG and HTML are never inline: both run + /// script under the store's origin. + /// + /// The blob's IANA media type. + /// The file name the browser saves it under. + /// The header value. + public static string DispositionOf(string mediaType, string name) + { + ArgumentNullException.ThrowIfNull(mediaType); + ArgumentNullException.ThrowIfNull(name); - var inline = mediaType.Equals("application/pdf", StringComparison.OrdinalIgnoreCase) - || (mediaType.StartsWith("image/", StringComparison.OrdinalIgnoreCase) - && !mediaType.Contains("svg", StringComparison.OrdinalIgnoreCase)); + bool inline = mediaType.Equals("application/pdf", StringComparison.OrdinalIgnoreCase) + || (mediaType.StartsWith("image/", StringComparison.OrdinalIgnoreCase) + && !mediaType.Contains("svg", StringComparison.OrdinalIgnoreCase)); - return (inline ? "inline" : "attachment") + "; filename*=UTF-8''" + Uri.EscapeDataString(name); + return (inline ? "inline" : "attachment") + "; filename*=UTF-8''" + Uri.EscapeDataString(name); + } } } diff --git a/src/AgentCore.Application/Blobs/BlobMediaTypes.cs b/src/AgentCore.Application/Blobs/BlobMediaTypes.cs index f77bf70f..74ba8a7a 100644 --- a/src/AgentCore.Application/Blobs/BlobMediaTypes.cs +++ b/src/AgentCore.Application/Blobs/BlobMediaTypes.cs @@ -1,41 +1,42 @@ -namespace AgentCore.Application.Blobs; - -/// The media type a file name implies, one entry per . -internal static class BlobMediaTypes +namespace AgentCore.Application.Blobs { - /// The type for a name whose extension is not listed. A browser saves it rather than showing it. - public const string Fallback = "application/octet-stream"; - - private static readonly Dictionary ByExtension = new(StringComparer.OrdinalIgnoreCase) + /// The media type a file name implies, one entry per . + internal static class BlobMediaTypes { - ["png"] = "image/png", - ["jpg"] = "image/jpeg", - ["jpeg"] = "image/jpeg", - ["gif"] = "image/gif", - ["webp"] = "image/webp", - ["pdf"] = "application/pdf", - ["csv"] = "text/csv", - ["tsv"] = "text/tab-separated-values", - ["txt"] = "text/plain", - ["md"] = "text/markdown", - ["json"] = "application/json", - ["zip"] = "application/zip", - ["xlsx"] = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", - ["docx"] = "application/vnd.openxmlformats-officedocument.wordprocessingml.document", - ["pptx"] = "application/vnd.openxmlformats-officedocument.presentationml.presentation", - }; + /// The type for a name whose extension is not listed. A browser saves it rather than showing it. + public const string Fallback = "application/octet-stream"; - /// Reads the media type off a file name's extension. - /// The file name. - /// The IANA media type, or when the extension is not listed. - public static string Of(string name) - { - ArgumentNullException.ThrowIfNull(name); + private static readonly Dictionary ByExtension = new(StringComparer.OrdinalIgnoreCase) + { + ["png"] = "image/png", + ["jpg"] = "image/jpeg", + ["jpeg"] = "image/jpeg", + ["gif"] = "image/gif", + ["webp"] = "image/webp", + ["pdf"] = "application/pdf", + ["csv"] = "text/csv", + ["tsv"] = "text/tab-separated-values", + ["txt"] = "text/plain", + ["md"] = "text/markdown", + ["json"] = "application/json", + ["zip"] = "application/zip", + ["xlsx"] = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", + ["docx"] = "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + ["pptx"] = "application/vnd.openxmlformats-officedocument.presentationml.presentation", + }; + + /// Reads the media type off a file name's extension. + /// The file name. + /// The IANA media type, or when the extension is not listed. + public static string Of(string name) + { + ArgumentNullException.ThrowIfNull(name); - var extension = Path.GetExtension(name).TrimStart('.'); + string extension = Path.GetExtension(name).TrimStart('.'); - return extension.Length > 0 && ByExtension.TryGetValue(extension, out var mediaType) - ? mediaType - : Fallback; + return extension.Length > 0 && ByExtension.TryGetValue(extension, out string? mediaType) + ? mediaType + : Fallback; + } } } diff --git a/src/AgentCore.Application/Blobs/BlobName.cs b/src/AgentCore.Application/Blobs/BlobName.cs index e59daa38..4cb465c0 100644 --- a/src/AgentCore.Application/Blobs/BlobName.cs +++ b/src/AgentCore.Application/Blobs/BlobName.cs @@ -1,36 +1,22 @@ using System.Text; -namespace AgentCore.Application.Blobs; - -/// -/// The one shape a blob name may take. A name is a key, never a path. -/// -public static class BlobName +namespace AgentCore.Application.Blobs { - /// The longest name, in UTF-8 bytes, that every backing store accepts. - public const int MaxBytes = 255; - - /// Says whether a name is safe to use as a key. - /// What the model or the caller wrote. - /// when the name is not empty, holds no path separator, no .., - /// no control character, and fits in . - public static bool IsSafe(string? name) + /// + /// The one shape a blob name may take. A name is a key, never a path. + /// + public static class BlobName { - if (string.IsNullOrWhiteSpace(name)) - { - return false; - } + /// The longest name, in UTF-8 bytes, that every backing store accepts. + public const int MaxBytes = 255; - if (name.Contains("..", StringComparison.Ordinal)) + /// Says whether a name is safe to use as a key. + /// What the model or the caller wrote. + /// when the name is not empty, holds no path separator, no .., + /// no control character, and fits in . + public static bool IsSafe(string? name) { - return false; + return !string.IsNullOrWhiteSpace(name) && !name.Contains("..", StringComparison.Ordinal) && !name.Any(c => c is '/' or '\\' || char.IsControl(c)) && Encoding.UTF8.GetByteCount(name) <= MaxBytes; } - - if (name.Any(c => c is '/' or '\\' || char.IsControl(c))) - { - return false; - } - - return Encoding.UTF8.GetByteCount(name) <= MaxBytes; } } diff --git a/src/AgentCore.Application/Blobs/BlobPolicy.cs b/src/AgentCore.Application/Blobs/BlobPolicy.cs index c3bde263..a6ae90a1 100644 --- a/src/AgentCore.Application/Blobs/BlobPolicy.cs +++ b/src/AgentCore.Application/Blobs/BlobPolicy.cs @@ -1,68 +1,69 @@ -namespace AgentCore.Application.Blobs; - -/// -/// What a captured sandbox file must satisfy before it is stored. -/// -public sealed class BlobPolicy +namespace AgentCore.Application.Blobs { - /// The cap a sandbox file must fit under. 10 MB. - public const long DefaultMaxBytes = 10L * 1024 * 1024; - /// - /// The extensions stored by default: images, PDF, plain data and Office files. Never - /// html, svg or xml: a presigned link serves those as a live page from - /// the bucket, so a model-written file could pose as one of the operator's own. + /// What a captured sandbox file must satisfy before it is stored. /// - public static readonly IReadOnlySet DefaultExtensions = new HashSet(StringComparer.OrdinalIgnoreCase) + public sealed class BlobPolicy { - "png", "jpg", "jpeg", "gif", "webp", "pdf", "csv", "tsv", "txt", "md", "json", "zip", "xlsx", "docx", "pptx", - }; + /// The cap a sandbox file must fit under. 10 MB. + public const long DefaultMaxBytes = 10L * 1024 * 1024; - /// The policy the harness uses when the document names none. - public static BlobPolicy Default { get; } = new(DefaultMaxBytes, DefaultExtensions); + /// + /// The extensions stored by default: images, PDF, plain data and Office files. Never + /// html, svg or xml: a presigned link serves those as a live page from + /// the bucket, so a model-written file could pose as one of the operator's own. + /// + public static readonly IReadOnlySet DefaultExtensions = new HashSet(StringComparer.OrdinalIgnoreCase) + { + "png", "jpg", "jpeg", "gif", "webp", "pdf", "csv", "tsv", "txt", "md", "json", "zip", "xlsx", "docx", "pptx", + }; - /// Makes a policy. - /// The largest file stored. Must be positive. - /// Extensions stored, without the dot. Case does not matter. - public BlobPolicy(long maxBytes, IEnumerable allowedExtensions) - { - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxBytes); - ArgumentNullException.ThrowIfNull(allowedExtensions); + /// The policy the harness uses when the document names none. + public static BlobPolicy Default { get; } = new(DefaultMaxBytes, DefaultExtensions); - MaxBytes = maxBytes; - AllowedExtensions = new HashSet(allowedExtensions, StringComparer.OrdinalIgnoreCase); - } + /// Makes a policy. + /// The largest file stored. Must be positive. + /// Extensions stored, without the dot. Case does not matter. + public BlobPolicy(long maxBytes, IEnumerable allowedExtensions) + { + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxBytes); + ArgumentNullException.ThrowIfNull(allowedExtensions); - /// Gets the largest file stored, in bytes. - public long MaxBytes { get; } + MaxBytes = maxBytes; + AllowedExtensions = new HashSet(allowedExtensions, StringComparer.OrdinalIgnoreCase); + } - /// Gets the extensions stored, without the dot. - public IReadOnlySet AllowedExtensions { get; } + /// Gets the largest file stored, in bytes. + public long MaxBytes { get; } - /// Says why a file is refused, or that it is not. - /// The file's name, already normalised by . - /// The file's size in bytes. - /// A short reason fit for a log line, or when the file may be stored. - public string? WhyRefused(string name, long length) - { - ArgumentNullException.ThrowIfNull(name); + /// Gets the extensions stored, without the dot. + public IReadOnlySet AllowedExtensions { get; } - if (length < 0 || length > MaxBytes) + /// Says why a file is refused, or that it is not. + /// The file's name, already normalised by . + /// The file's size in bytes. + /// A short reason fit for a log line, or when the file may be stored. + public string? WhyRefused(string name, long length) { - return $"size {length} is outside 0..{MaxBytes} bytes"; - } + ArgumentNullException.ThrowIfNull(name); - var dot = name.LastIndexOf('.'); + if (length < 0 || length > MaxBytes) + { + return $"size {length} is outside 0..{MaxBytes} bytes"; + } - if (dot < 0 || dot == name.Length - 1) - { - return "no extension"; - } + int dot = name.LastIndexOf('.'); + + if (dot < 0 || dot == name.Length - 1) + { + return "no extension"; + } - var extension = name[(dot + 1)..]; + string extension = name[(dot + 1)..]; - return AllowedExtensions.Contains(extension) - ? null - : $"extension '{extension}' is not allowed"; + return AllowedExtensions.Contains(extension) + ? null + : $"extension '{extension}' is not allowed"; + } } } diff --git a/src/AgentCore.Application/Blobs/BlobRead.cs b/src/AgentCore.Application/Blobs/BlobRead.cs index 5b5741f1..3368cb7d 100644 --- a/src/AgentCore.Application/Blobs/BlobRead.cs +++ b/src/AgentCore.Application/Blobs/BlobRead.cs @@ -1,14 +1,18 @@ -namespace AgentCore.Application.Blobs; - -/// One stored blob, opened for reading. Dispose it to release the stream. -/// The IANA media type, such as image/png. -/// How many bytes holds. -/// The bytes, positioned at the start. -public sealed record BlobRead( - string MediaType, - long Length, - Stream Content) : IAsyncDisposable +namespace AgentCore.Application.Blobs { - /// - public ValueTask DisposeAsync() => Content.DisposeAsync(); + /// One stored blob, opened for reading. Dispose it to release the stream. + /// The IANA media type, such as image/png. + /// How many bytes holds. + /// The bytes, positioned at the start. + public sealed record BlobRead( + string MediaType, + long Length, + Stream Content) : IAsyncDisposable + { + /// + public ValueTask DisposeAsync() + { + return Content.DisposeAsync(); + } + } } diff --git a/src/AgentCore.Application/Blobs/BlobRef.cs b/src/AgentCore.Application/Blobs/BlobRef.cs index e6a114ab..8e346395 100644 --- a/src/AgentCore.Application/Blobs/BlobRef.cs +++ b/src/AgentCore.Application/Blobs/BlobRef.cs @@ -1,12 +1,13 @@ -namespace AgentCore.Application.Blobs; - -/// One stored blob, apart from its bytes. -/// Who wrote it. -/// The name it is stored under. -/// The IANA media type, such as image/png. -/// How many bytes it holds. -public sealed record BlobRef( - string OwnerId, - string Name, - string MediaType, - long Length); +namespace AgentCore.Application.Blobs +{ + /// One stored blob, apart from its bytes. + /// Who wrote it. + /// The name it is stored under. + /// The IANA media type, such as image/png. + /// How many bytes it holds. + public sealed record BlobRef( + string OwnerId, + string Name, + string MediaType, + long Length); +} diff --git a/src/AgentCore.Application/Blobs/BlobStoreFactory.cs b/src/AgentCore.Application/Blobs/BlobStoreFactory.cs index a8dc9283..f2fee186 100644 --- a/src/AgentCore.Application/Blobs/BlobStoreFactory.cs +++ b/src/AgentCore.Application/Blobs/BlobStoreFactory.cs @@ -3,43 +3,44 @@ using AgentCore.Application.Ports; using AgentCore.Application.Providers; -namespace AgentCore.Application.Blobs; - -/// -/// Opens the blob store the document names, from the adapters the host registered. -/// -public static class BlobStoreFactory +namespace AgentCore.Application.Blobs { - /// What this seam conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam Seam = - new("providers.blobs", "/providers/blobs/kind", "options.UseBlobStores(...)", "stores"); - - /// Opens the store providers.blobs names, or nothing. - /// The loaded document. - /// The chain a credential resolves through, or . - /// The vendors this host supports. - /// Cancels the open. - /// The store, or when the document names none. - /// The configuration or the adapters are . - /// - /// The document names a kind no adapter serves, or a kind two adapters answer to. - /// - public static async ValueTask OpenAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) + /// + /// Opens the blob store the document names, from the adapters the host registered. + /// + public static class BlobStoreFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + /// What this seam conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam Seam = + new("providers.blobs", "/providers/blobs/kind", "options.UseBlobStores(...)", "stores"); - if (configuration.Providers?.Blobs is not { } entry) + /// Opens the store providers.blobs names, or nothing. + /// The loaded document. + /// The chain a credential resolves through, or . + /// The vendors this host supports. + /// Cancels the open. + /// The store, or when the document names none. + /// The configuration or the adapters are . + /// + /// The document names a kind no adapter serves, or a kind two adapters answer to. + /// + public static async ValueTask OpenAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - return null; - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); + if (configuration.Providers?.Blobs is not { } entry) + { + return null; + } - return await adapter.OpenAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + IBlobStoreAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); + + return await adapter.OpenAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.Application/Blobs/BlobWrite.cs b/src/AgentCore.Application/Blobs/BlobWrite.cs index ca8f03d9..4cef91bd 100644 --- a/src/AgentCore.Application/Blobs/BlobWrite.cs +++ b/src/AgentCore.Application/Blobs/BlobWrite.cs @@ -1,14 +1,15 @@ -namespace AgentCore.Application.Blobs; - -/// One blob to store. -/// Who writes it. The conversation id today. -/// The name it is stored under. Must pass . -/// The IANA media type, such as image/png. -/// The bytes. Read once, from its current position. The caller disposes it. -/// How many bytes holds. -public sealed record BlobWrite( - string OwnerId, - string Name, - string MediaType, - Stream Content, - long Length); +namespace AgentCore.Application.Blobs +{ + /// One blob to store. + /// Who writes it. The conversation id today. + /// The name it is stored under. Must pass . + /// The IANA media type, such as image/png. + /// The bytes. Read once, from its current position. The caller disposes it. + /// How many bytes holds. + public sealed record BlobWrite( + string OwnerId, + string Name, + string MediaType, + Stream Content, + long Length); +} diff --git a/src/AgentCore.Application/Blobs/FileLink.cs b/src/AgentCore.Application/Blobs/FileLink.cs index 519e529e..ef831b6c 100644 --- a/src/AgentCore.Application/Blobs/FileLink.cs +++ b/src/AgentCore.Application/Blobs/FileLink.cs @@ -1,6 +1,7 @@ -namespace AgentCore.Application.Blobs; - -/// One file a conversation's sandbox wrote and the store kept. -/// The file's facts. -/// Where a browser fetches it from, or when the store has no web door. -public sealed record FileLink(BlobRef Blob, Uri? Url); +namespace AgentCore.Application.Blobs +{ + /// One file a conversation's sandbox wrote and the store kept. + /// The file's facts. + /// Where a browser fetches it from, or when the store has no web door. + public sealed record FileLink(BlobRef Blob, Uri? Url); +} diff --git a/src/AgentCore.Application/Cache/PassThroughHybridCache.cs b/src/AgentCore.Application/Cache/PassThroughHybridCache.cs index a4be9864..909885c9 100644 --- a/src/AgentCore.Application/Cache/PassThroughHybridCache.cs +++ b/src/AgentCore.Application/Cache/PassThroughHybridCache.cs @@ -1,44 +1,53 @@ using Microsoft.Extensions.Caching.Hybrid; -namespace AgentCore.Application.Cache; - -/// -/// The cache a container runs on when the host set none: it stores nothing, so every read runs -/// its factory and every write and removal is a no-op. -/// -public sealed class PassThroughHybridCache : HybridCache +namespace AgentCore.Application.Cache { - /// Gets the one instance; it holds no state, so one is enough. - public static PassThroughHybridCache Instance { get; } = new(); - - private PassThroughHybridCache() + /// + /// The cache a container runs on when the host set none: it stores nothing, so every read runs + /// its factory and every write and removal is a no-op. + /// + public sealed class PassThroughHybridCache : HybridCache { - } + /// Gets the one instance; it holds no state, so one is enough. + public static PassThroughHybridCache Instance { get; } = new(); - /// - public override ValueTask GetOrCreateAsync( - string key, - TState state, - Func> factory, - HybridCacheEntryOptions? options = null, - IEnumerable? tags = null, - CancellationToken cancellationToken = default) - => factory(state, cancellationToken); + private PassThroughHybridCache() + { + } - /// - public override ValueTask SetAsync( - string key, - T value, - HybridCacheEntryOptions? options = null, - IEnumerable? tags = null, - CancellationToken cancellationToken = default) - => default; + /// + public override ValueTask GetOrCreateAsync( + string key, + TState state, + Func> factory, + HybridCacheEntryOptions? options = null, + IEnumerable? tags = null, + CancellationToken cancellationToken = default) + { + return factory(state, cancellationToken); + } - /// - public override ValueTask RemoveAsync(string key, CancellationToken cancellationToken = default) - => default; + /// + public override ValueTask SetAsync( + string key, + T value, + HybridCacheEntryOptions? options = null, + IEnumerable? tags = null, + CancellationToken cancellationToken = default) + { + return default; + } - /// - public override ValueTask RemoveByTagAsync(string tag, CancellationToken cancellationToken = default) - => default; + /// + public override ValueTask RemoveAsync(string key, CancellationToken cancellationToken = default) + { + return default; + } + + /// + public override ValueTask RemoveByTagAsync(string tag, CancellationToken cancellationToken = default) + { + return default; + } + } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentApproval.cs b/src/AgentCore.Application/Configuration/Compilation/AgentApproval.cs index e7503505..b3e31849 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentApproval.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentApproval.cs @@ -3,92 +3,89 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// One agent's approval: block: the standing rules that answer an approval request before -/// it surfaces. Everything a rule does not name still asks. -/// -internal static class AgentApproval +namespace AgentCore.Application.Configuration.Compilation { - /// Composes one agent's auto-approval patterns. - /// The agents.defaults section, or . - /// The agent to resolve. - /// - /// The agent's own auto: when it declares one, else the defaults', else empty. One key, - /// so key-by-key inheritance is a single fallback, the same as knowledge: and - /// compaction:. - /// - public static IReadOnlyList Compose(AgentDefaults? defaults, AgentConfiguration agent) + /// + /// One agent's approval: block: the standing rules that answer an approval request before + /// it surfaces. Everything a rule does not name still asks. + /// + internal static class AgentApproval { - ArgumentNullException.ThrowIfNull(agent); - - return agent.Approval?.Auto ?? defaults?.Approval?.Auto ?? []; - } + /// Composes one agent's auto-approval patterns. + /// The agents.defaults section, or . + /// The agent to resolve. + /// + /// The agent's own auto: when it declares one, else the defaults', else empty. One key, + /// so key-by-key inheritance is a single fallback, the same as knowledge: and + /// compaction:. + /// + public static IReadOnlyList Compose(AgentDefaults? defaults, AgentConfiguration agent) + { + ArgumentNullException.ThrowIfNull(agent); - /// Whether auto-approves . - /// One auto: entry: a tool name, or a prefix with a trailing *. - /// The called tool's name. - /// - /// An ordinal prefix match for a trailing-* pattern, else an ordinal exact match. A - /// * anywhere else is literal, so it matches nothing a document can conversation. - /// - public static bool Matches(string pattern, string toolName) - { - ArgumentNullException.ThrowIfNull(pattern); - ArgumentNullException.ThrowIfNull(toolName); + return agent.Approval?.Auto ?? defaults?.Approval?.Auto ?? []; + } - return pattern.EndsWith('*') - ? toolName.StartsWith(pattern[..^1], StringComparison.Ordinal) - : toolName == pattern; - } + /// Whether auto-approves . + /// One auto: entry: a tool name, or a prefix with a trailing *. + /// The called tool's name. + /// + /// An ordinal prefix match for a trailing-* pattern, else an ordinal exact match. A + /// * anywhere else is literal, so it matches nothing a document can conversation. + /// + public static bool Matches(string pattern, string toolName) + { + ArgumentNullException.ThrowIfNull(pattern); + ArgumentNullException.ThrowIfNull(toolName); - /// Reads the state keys an agent's approval surface needs persisted across resume. - /// The agents.defaults section, or . - /// The agent being compiled. - /// The tools the agent offers the model, if any. - /// - /// The pending queue and the standing-rule keys when the agent may surface an approval — - /// through auto:, which adds the approval layer, or through an approval-required tool — - /// else empty. An absent key is never kept, so both ride together. - /// - public static IReadOnlyList StateKeysFor( - AgentDefaults? defaults, AgentConfiguration item, IEnumerable? tools) - { - ArgumentNullException.ThrowIfNull(item); + return pattern.EndsWith('*') + ? toolName.StartsWith(pattern[..^1], StringComparison.Ordinal) + : toolName == pattern; + } - if (Compose(defaults, item).Count == 0 - && tools?.OfType().Any() != true) + /// Reads the state keys an agent's approval surface needs persisted across resume. + /// The agents.defaults section, or . + /// The agent being compiled. + /// The tools the agent offers the model, if any. + /// + /// The pending queue and the standing-rule keys when the agent may surface an approval — + /// through auto:, which adds the approval layer, or through an approval-required tool — + /// else empty. An absent key is never kept, so both ride together. + /// + public static IReadOnlyList StateKeysFor( + AgentDefaults? defaults, AgentConfiguration item, IEnumerable? tools) { - return []; + ArgumentNullException.ThrowIfNull(item); + + return Compose(defaults, item).Count == 0 + && tools?.OfType().Any() != true + ? [] + : [PendingApprovalQueue.PendingStateKey, PendingApprovalQueue.StandingStateKey]; } - return [PendingApprovalQueue.PendingStateKey, PendingApprovalQueue.StandingStateKey]; - } + /// + /// Bakes one agent's auto: into its pipeline as UseToolApproval rules. No + /// patterns, no layer — the document pays nothing for approval it never declares. + /// + /// The compiled agent. + /// The agents.defaults section, or . + /// The agent being compiled. + /// The approval-wrapped agent, or unchanged. + public static AIAgent Apply(AIAgent agent, AgentDefaults? defaults, AgentConfiguration item) + { + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(item); - /// - /// Bakes one agent's auto: into its pipeline as UseToolApproval rules. No - /// patterns, no layer — the document pays nothing for approval it never declares. - /// - /// The compiled agent. - /// The agents.defaults section, or . - /// The agent being compiled. - /// The approval-wrapped agent, or unchanged. - public static AIAgent Apply(AIAgent agent, AgentDefaults? defaults, AgentConfiguration item) - { - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(item); + return Compose(defaults, item) is not { Count: > 0 } auto + ? agent + : new AIAgentBuilder(agent) + .UseToolApproval(new ToolApprovalAgentOptions { AutoApprovalRules = [.. auto.Select(ToRule)] }) + .Build(); + } - if (Compose(defaults, item) is not { Count: > 0 } auto) + private static Func> ToRule(string pattern) { - return agent; + return context => ValueTask.FromResult(Matches(pattern, context.FunctionCallContent.Name)); } - - return new AIAgentBuilder(agent) - .UseToolApproval(new ToolApprovalAgentOptions { AutoApprovalRules = auto.Select(ToRule).ToList() }) - .Build(); } - - private static Func> ToRule(string pattern) - => context => ValueTask.FromResult(Matches(pattern, context.FunctionCallContent.Name)); } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentBackgroundCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentBackgroundCompiler.cs index e705035d..6fc3f8ab 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentBackgroundCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentBackgroundCompiler.cs @@ -3,63 +3,64 @@ using AgentCore.Application.Runtime.Harness; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - +namespace AgentCore.Application.Configuration.Compilation +{ #pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. -/// -/// The provider behind one agent's background: list: its children, each wrapped so a child -/// session knows which conversation started it. -/// -internal static class AgentBackgroundCompiler -{ - /// Builds the provider that starts this agent's background children. - /// The agent being compiled. - /// This agent's JSON pointer, for a background: failure. - /// Resolves an agents.items id to its compiled agent, or when undeclared. - public static BackgroundAgentsProvider Build( - AgentConfiguration item, - string pointer, - Func resolve) + /// + /// The provider behind one agent's background: list: its children, each wrapped so a child + /// session knows which conversation started it. + /// + internal static class AgentBackgroundCompiler { - if (item.Background.Contains(item.Id, StringComparer.Ordinal)) + /// Builds the provider that starts this agent's background children. + /// The agent being compiled. + /// This agent's JSON pointer, for a background: failure. + /// Resolves an agents.items id to its compiled agent, or when undeclared. + public static BackgroundAgentsProvider Build( + AgentConfiguration item, + string pointer, + Func resolve) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "background"), - $"the agent '{item.Id}' names itself in background:, so it would start itself as its own child. " - + "Remove it from the list, or point at another agent."); - } + if (item.Background.Contains(item.Id, StringComparer.Ordinal)) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "background"), + $"the agent '{item.Id}' names itself in background:, so it would start itself as its own child. " + + "Remove it from the list, or point at another agent."); + } - List children = new(item.Background.Count); - for (var index = 0; index < item.Background.Count; index++) - { - var childPointer = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(pointer, "background"), index); + List children = new(item.Background.Count); + for (int index = 0; index < item.Background.Count; index++) + { + string childPointer = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(pointer, "background"), index); - var childId = item.Background[index]; + string childId = item.Background[index]; - var child = resolve(childId) - ?? throw ConfigurationCompiler.Fail( - childPointer, - $"the agent '{childId}' is not declared in agents.items"); + AIAgent child = resolve(childId) + ?? throw ConfigurationCompiler.Fail( + childPointer, + $"the agent '{childId}' is not declared in agents.items"); - children.Add(new BackgroundChildAgent(child)); - } + children.Add(new BackgroundChildAgent(child)); + } - try - { - // Children run with their own compiled tools, which carry no approval-required tool - // today — every harness tool runs with approval off — so a child never stalls waiting - // for an approval the parent would only see as a completed task with empty output. - return new BackgroundAgentsProvider(children); - } - catch (ArgumentException exception) - { - // The provider keys children by name case-insensitively, so two ids that differ only - // by case collide here rather than at either declaration. - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "background"), - $"the agent '{item.Id}' declares background: children whose names collide: {exception.Message}"); + try + { + // Children run with their own compiled tools, which carry no approval-required tool + // today — every harness tool runs with approval off — so a child never stalls waiting + // for an approval the parent would only see as a completed task with empty output. + return new BackgroundAgentsProvider(children); + } + catch (ArgumentException exception) + { + // The provider keys children by name case-insensitively, so two ids that differ only + // by case collide here rather than at either declaration. + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "background"), + $"the agent '{item.Id}' declares background: children whose names collide: {exception.Message}"); + } } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs b/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs index 00d9a9f2..162c068c 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentCompilationContext.cs @@ -8,89 +8,90 @@ using AgentCore.Application.Tools.Registry; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Everything the compile table needs that the document does not hold. -/// -public sealed class AgentCompilationContext +namespace AgentCore.Application.Configuration.Compilation { /// - /// Creates the context. + /// Everything the compile table needs that the document does not hold. /// - /// The seam that resolves a model reference. - public AgentCompilationContext(IChatClientFactory chatClients) + public sealed class AgentCompilationContext { - ArgumentNullException.ThrowIfNull(chatClients); - ChatClients = chatClients; - } + /// + /// Creates the context. + /// + /// The seam that resolves a model reference. + public AgentCompilationContext(IChatClientFactory chatClients) + { + ArgumentNullException.ThrowIfNull(chatClients); + ChatClients = chatClients; + } - /// - /// Gets the seam that resolves a model reference. - /// - public IChatClientFactory ChatClients { get; } + /// + /// Gets the seam that resolves a model reference. + /// + public IChatClientFactory ChatClients { get; } - /// - /// Gets or sets the seam that builds a tool. An agent advertises no tool when this is null. - /// - public ToolRegistry? Tools { get; init; } + /// + /// Gets or sets the seam that builds a tool. An agent advertises no tool when this is null. + /// + public ToolRegistry? Tools { get; init; } - /// - /// Gets or sets the evaluator a guarded graph edge conversations. - /// - public IGuardEvaluator? Guards { get; init; } + /// + /// Gets or sets the evaluator a guarded graph edge conversations. + /// + public IGuardEvaluator? Guards { get; init; } - /// - /// Gets or sets the moderator that reads what the caller said before the model runs. - /// - public PromptModerator? Moderation { get; init; } + /// + /// Gets or sets the moderator that reads what the caller said before the model runs. + /// + public PromptModerator? Moderation { get; init; } - /// - /// Gets or sets the backing store of store 1, or for memory. - /// - public IConversationStore? ConversationStore { get; init; } + /// + /// Gets or sets the backing store of store 1, or for memory. + /// + public IConversationStore? ConversationStore { get; init; } - /// - /// Gets or sets the store every agent's knowledge: block reads through. - /// - public IKnowledgeRetrievalPort? Knowledge { get; init; } + /// + /// Gets or sets the store every agent's knowledge: block reads through. + /// + public IKnowledgeRetrievalPort? Knowledge { get; init; } - /// - /// Gets or sets the skills every agent's skills: list is drawn from, or - /// when the host bound no skills folder. - /// - public SkillCatalog? Skills { get; init; } + /// + /// Gets or sets the skills every agent's skills: list is drawn from, or + /// when the host bound no skills folder. + /// + public SkillCatalog? Skills { get; init; } - /// - /// Gets or sets the wording each card's source label is written in. - /// - public IKnowledgeCitationFormatter? Citations { get; init; } + /// + /// Gets or sets the wording each card's source label is written in. + /// + public IKnowledgeCitationFormatter? Citations { get; init; } - /// - /// Gets or sets where the compiled agents write their own diagnostics, or . - /// - public ILoggerFactory? Loggers { get; init; } + /// + /// Gets or sets where the compiled agents write their own diagnostics, or . + /// + public ILoggerFactory? Loggers { get; init; } - /// - /// Gets or sets the clock a clock: agent reads the date from, or - /// for . - /// - public TimeProvider? Clock { get; init; } + /// + /// Gets or sets the clock a clock: agent reads the date from, or + /// for . + /// + public TimeProvider? Clock { get; init; } - /// - /// Gets or sets the root a memory: block's files are kept under, or - /// when the host bound no workspace root. - /// - public string? WorkspaceRoot { get; init; } + /// + /// Gets or sets the root a memory: block's files are kept under, or + /// when the host bound no workspace root. + /// + public string? WorkspaceRoot { get; init; } - /// - /// Gets or sets the set a shell: block's env: resolves its ${secret:name} - /// references against, or to treat every such reference as unresolved. - /// - public ResolvedSecrets? Secrets { get; init; } + /// + /// Gets or sets the set a shell: block's env: resolves its ${secret:name} + /// references against, or to treat every such reference as unresolved. + /// + public ResolvedSecrets? Secrets { get; init; } - /// - /// Gets or sets the compaction stages every agent runs. - /// - internal CompactionStages? Compaction { get; init; } + /// + /// Gets or sets the compaction stages every agent runs. + /// + internal CompactionStages? Compaction { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs index fef13a5a..ba029331 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs @@ -8,97 +8,98 @@ using AgentCore.Application.Transcript; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -internal static class AgentContextProviderCompiler +namespace AgentCore.Application.Configuration.Compilation { - /// - /// The formatter an agent cites through when the host bound none. Stateless, so every agent in - /// every document reads the one instance. - /// - private static readonly SourceLocatorCitationFormatter DefaultCitations = new(); - - /// Builds the context providers of one agent. - /// What every agent of this walk shares. - /// The agent being compiled. - /// The compile-time seams. - /// This agent's JSON pointer. - /// Resolves an agents.items id to its compiled agent, or when undeclared. - /// Store 1, or on a row whose session carries no history and so has nothing to summarise. - public static List Build( - AgentsWalk walk, - AgentConfiguration item, - AgentCompilationContext context, - string pointer, - Func resolve, - AgentCoreChatHistoryProvider? history) + internal static class AgentContextProviderCompiler { - var defaults = walk.Defaults; - List providers = []; - - if (item.Pinned.Count > 0) + /// + /// The formatter an agent cites through when the host bound none. Stateless, so every agent in + /// every document reads the one instance. + /// + private static readonly SourceLocatorCitationFormatter DefaultCitations = new(); + + /// Builds the context providers of one agent. + /// What every agent of this walk shares. + /// The agent being compiled. + /// The compile-time seams. + /// This agent's JSON pointer. + /// Resolves an agents.items id to its compiled agent, or when undeclared. + /// Store 1, or on a row whose session carries no history and so has nothing to summarise. + public static List Build( + AgentsWalk walk, + AgentConfiguration item, + AgentCompilationContext context, + string pointer, + Func resolve, + AgentCoreChatHistoryProvider? history) { - providers.Add(new PinnedSkillsProvider(RequireCatalog(item, context, pointer, "pinned"), item.Pinned)); - } - - providers.Add(new TurnContextProvider()); - - if (item.Skills.Count > 0) - { - providers.Add(SkillsProviderFactory.Create(RequireCatalog(item, context, pointer, "skills"), item.Skills, context.Loggers)); - } - - var model = item.Model ?? defaults?.Model; - if (context.ChatClients.GetContextWindow(model) is not { } contextWindow) - { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "model"), - $"the agent '{item.Id}' uses the model '{model?.Ref ?? "default"}' and its adapter " - + "reports no context window, so compaction cannot size itself. Add the model to the " - + "adapter's table."); - } + AgentDefaults? defaults = walk.Defaults; + List providers = []; + + if (item.Pinned.Count > 0) + { + providers.Add(new PinnedSkillsProvider(RequireCatalog(item, context, pointer, "pinned"), item.Pinned)); + } + + providers.Add(new TurnContextProvider()); + + if (item.Skills.Count > 0) + { + providers.Add(SkillsProviderFactory.Create(RequireCatalog(item, context, pointer, "skills"), item.Skills, context.Loggers)); + } + + ModelReference? model = item.Model ?? defaults?.Model; + if (context.ChatClients.GetContextWindow(model) is not { } contextWindow) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "model"), + $"the agent '{item.Id}' uses the model '{model?.Ref ?? "default"}' and its adapter " + + "reports no context window, so compaction cannot size itself. Add the model to the " + + "adapter's table."); + } + + providers.Add(new ReaderContentFilterProvider()); + + CompactionStages stages = context.Compaction ?? CompactionStrategyFactory.Create(context.ChatClients.GetChatClient(model), contextWindow); + providers.AddRange(CompactionStrategyFactory.BuildProviders(stages, history)); + + AgentHarnessProviders.Add(providers, defaults, item, context, pointer, resolve, walk.Background); + + if (AgentKnowledge.Compose(defaults, item) is not { } composed) + { + return providers; + } + + if (context.Knowledge is not { } port) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "knowledge"), + $"the agent '{item.Id}' declares a knowledge: block and this host registered no " + + "knowledge vendor, so there is no store to read. Conversation " + + "options.UseKnowledgeStores(...) with an adapter that serves " + + $"{nameof(IKnowledgeRetrievalPort)}, or remove the knowledge: block."); + } + + ResolvedKnowledge knowledge = composed with { Clarification = walk.Clarification }; + + providers.Add(KnowledgeProviderFactory.Create( + port, + knowledge, + item.Id, + context.Citations ?? DefaultCitations, + context.Loggers, + walk.Scope)); - providers.Add(new ReaderContentFilterProvider()); - - var stages = context.Compaction ?? CompactionStrategyFactory.Create(context.ChatClients.GetChatClient(model), contextWindow); - providers.AddRange(CompactionStrategyFactory.BuildProviders(stages, history)); - - AgentHarnessProviders.Add(providers, defaults, item, context, pointer, resolve, walk.Background); - - if (AgentKnowledge.Compose(defaults, item) is not { } composed) - { return providers; } - if (context.Knowledge is not { } port) + private static SkillCatalog RequireCatalog(AgentConfiguration item, AgentCompilationContext context, string pointer, string key) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "knowledge"), - $"the agent '{item.Id}' declares a knowledge: block and this host registered no " - + "knowledge vendor, so there is no store to read. Conversation " - + "options.UseKnowledgeStores(...) with an adapter that serves " - + $"{nameof(IKnowledgeRetrievalPort)}, or remove the knowledge: block."); + return context.Skills ?? throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, key), + $"the agent '{item.Id}' declares a {key}: list and this host bound no skills " + + "folder, so there is nothing to load. Call options.UseSkills(...) with the " + + $"folder that holds the SKILL.md directories, or remove the {key}: list."); } - - var knowledge = composed with { Clarification = walk.Clarification }; - - providers.Add(KnowledgeProviderFactory.Create( - port, - knowledge, - item.Id, - context.Citations ?? DefaultCitations, - context.Loggers, - walk.Scope)); - - return providers; - } - - private static SkillCatalog RequireCatalog(AgentConfiguration item, AgentCompilationContext context, string pointer, string key) - { - return context.Skills ?? throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, key), - $"the agent '{item.Id}' declares a {key}: list and this host bound no skills " - + "folder, so there is nothing to load. Call options.UseSkills(...) with the " - + $"folder that holds the SKILL.md directories, or remove the {key}: list."); } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentDelegationTool.cs b/src/AgentCore.Application/Configuration/Compilation/AgentDelegationTool.cs index a6140b1f..3dd7c33a 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentDelegationTool.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentDelegationTool.cs @@ -6,126 +6,126 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Turns one declaration into the function the outer agent conversations. -/// -internal static class AgentDelegationTool +namespace AgentCore.Application.Configuration.Compilation { - /// The argument name AsAIFunction() generates when the document declares no schema. - private const string DefaultArgument = "query"; - - /// Builds the function that runs one declared agent. - /// The kind: agent declaration. - /// The already compiled inner agent. - /// The function the outer agent advertises. - internal static AIFunction Create(ToolConfiguration tool, AIAgent inner) - { - // The document names the function and describes it, because the calling model reads both to - // decide when to delegate. Without a description it falls back to the inner agent's own. - // AsAIFunction is the schema donor only — the wrapper below runs the agent directly, so - // its name, description and parameters stay exactly what the model was built against. - var function = inner.AsAIFunction(new AIFunctionFactoryOptions - { - Name = tool.Id, - Description = tool.Description ?? inner.Description, - }); - - return new DeclaredSchemaFunction(function, tool.Parameters, tool.Id, inner); - } - /// - /// Advertises the parameters: the document declares, over a function that takes one - /// string — or the inner function as-is when the document declares none — and runs the - /// inner agent directly instead of the framework's delegation machinery, so the nested run - /// carries the turn on its own options like every other run. + /// Turns one declaration into the function the outer agent conversations. /// - private sealed class DeclaredSchemaFunction : DelegatingAIFunction + internal static class AgentDelegationTool { - private readonly JsonElement _schema; + /// The argument name AsAIFunction() generates when the document declares no schema. + private const string DefaultArgument = "query"; + + /// Builds the function that runs one declared agent. + /// The kind: agent declaration. + /// The already compiled inner agent. + /// The function the outer agent advertises. + internal static AIFunction Create(ToolConfiguration tool, AIAgent inner) + { + // The document names the function and describes it, because the calling model reads both to + // decide when to delegate. Without a description it falls back to the inner agent's own. + // AsAIFunction is the schema donor only — the wrapper below runs the agent directly, so + // its name, description and parameters stay exactly what the model was built against. + AIFunction function = inner.AsAIFunction(new AIFunctionFactoryOptions + { + Name = tool.Id, + Description = tool.Description ?? inner.Description, + }); - private readonly string? _argument; + return new DeclaredSchemaFunction(function, tool.Parameters, tool.Id, inner); + } - private readonly string _toolId; + /// + /// Advertises the parameters: the document declares, over a function that takes one + /// string — or the inner function as-is when the document declares none — and runs the + /// inner agent directly instead of the framework's delegation machinery, so the nested run + /// carries the turn on its own options like every other run. + /// + private sealed class DeclaredSchemaFunction : DelegatingAIFunction + { + private readonly JsonElement _schema; - private readonly AIAgent _inner; + private readonly string? _argument; - internal DeclaredSchemaFunction(AIFunction inner, JsonNode? parameters, string toolId, AIAgent innerAgent) - : base(inner) - { - ArgumentNullException.ThrowIfNull(toolId); + private readonly string _toolId; - _toolId = toolId; - _inner = innerAgent ?? throw new ArgumentNullException(nameof(innerAgent)); + private readonly AIAgent _inner; - if (parameters is null) + internal DeclaredSchemaFunction(AIFunction inner, JsonNode? parameters, string toolId, AIAgent innerAgent) + : base(inner) { - _schema = inner.JsonSchema; - _argument = null; + ArgumentNullException.ThrowIfNull(toolId); + + _toolId = toolId; + _inner = innerAgent ?? throw new ArgumentNullException(nameof(innerAgent)); + + if (parameters is null) + { + _schema = inner.JsonSchema; + _argument = null; + } + else + { + using JsonDocument document = JsonDocument.Parse(parameters.ToJsonString()); + + _schema = document.RootElement.Clone(); + _argument = FirstProperty(inner.JsonSchema) ?? DefaultArgument; + } } - else - { - using var document = JsonDocument.Parse(parameters.ToJsonString()); - - _schema = document.RootElement.Clone(); - _argument = FirstProperty(inner.JsonSchema) ?? DefaultArgument; - } - } - public override JsonElement JsonSchema - => _schema; + public override JsonElement JsonSchema + => _schema; - protected override ValueTask InvokeCoreAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(arguments); + protected override ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(arguments); - var parent = TurnInvocation.FiledIn(arguments); + TurnInvocation? parent = TurnInvocation.FiledIn(arguments); - // Schemaless the donor advertises one query string; declared, the payload the - // document shaped. Either way the nested agent reads words, not arguments. - string query = _argument is null - && arguments.TryGetValue(DefaultArgument, out var bare) - && BareText(bare) is { } text - ? text - : ToolArgumentJson.ToJsonObject(arguments).ToJsonString(); + // Schemaless the donor advertises one query string; declared, the payload the + // document shaped. Either way the nested agent reads words, not arguments. + string query = _argument is null + && arguments.TryGetValue(DefaultArgument, out object? bare) + && BareText(bare) is { } text + ? text + : ToolArgumentJson.ToJsonObject(arguments).ToJsonString(); - // Decided here where the parent turn is in hand: the nested run neither latches - // the holder (K42) nor records, and only the run under this tool is offered its - // tools. Without a turn the nested run is bare, as before. - var nested = parent is not null - ? parent with { Clarifications = null, Nested = true } - : null; + // Decided here where the parent turn is in hand: the nested run neither latches + // the holder (K42) nor records, and only the run under this tool is offered its + // tools. Without a turn the nested run is bare, as before. + TurnInvocation? nested = parent is not null + ? parent with { Clarifications = null, Nested = true } + : null; - var offered = parent?.ToolsFor == _toolId ? parent?.Tools : null; + IReadOnlyList? offered = parent?.ToolsFor == _toolId ? parent?.Tools : null; - return DelegatedAgentRun.RunAsync(_inner, query, nested, offered, cancellationToken); - } + return DelegatedAgentRun.RunAsync(_inner, query, nested, offered, cancellationToken); + } - private static string? BareText(object? value) - => value switch + private static string? BareText(object? value) { - string text => text, - JsonElement { ValueKind: JsonValueKind.String } element => element.GetString(), - _ => null, - }; + return value switch + { + string text => text, + JsonElement { ValueKind: JsonValueKind.String } element => element.GetString(), + _ => null, + }; + } - /// - /// Reads the name of the first declared property of one JSON Schema object. - /// - private static string? FirstProperty(JsonElement schema) - { - if (schema.ValueKind is not JsonValueKind.Object - || !schema.TryGetProperty("properties", out var properties) - || properties.ValueKind is not JsonValueKind.Object) + /// + /// Reads the name of the first declared property of one JSON Schema object. + /// + private static string? FirstProperty(JsonElement schema) { - return null; + return schema.ValueKind is not JsonValueKind.Object + || !schema.TryGetProperty("properties", out JsonElement properties) + || properties.ValueKind is not JsonValueKind.Object + ? null + : properties.EnumerateObject().Select(property => property.Name).FirstOrDefault(); } - return properties.EnumerateObject().Select(property => property.Name).FirstOrDefault(); } - } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentHarness.cs b/src/AgentCore.Application/Configuration/Compilation/AgentHarness.cs index cba1ae08..b94df2e9 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentHarness.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentHarness.cs @@ -1,33 +1,34 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Compilation; - -/// One agent's harness switches, fully resolved. -/// Whether the agent gets the todo tools. -/// Whether the agent gets the mode tools. -/// Whether the agent is told the current date and time each turn. -/// Whether the framework's base instructions sit above the document's own. -public sealed record ResolvedHarness(bool Todos, bool Mode, bool Clock, bool BaseInstructions); - -/// -/// Composes one agent's harness switches (todos:, mode:, clock:, -/// baseInstructions:) from agents.defaults and the agent's own keys, key by key. -/// The tool switches are off until named; the two posture switches are on until named, so an -/// agent has to opt out of knowing the date or of the base instructions rather than opt in. -/// -public static class AgentHarness +namespace AgentCore.Application.Configuration.Compilation { - /// Composes one agent's resolved harness switches. - /// The agents.defaults section, or . - /// The agent to resolve. - public static ResolvedHarness Compose(AgentDefaults? defaults, AgentConfiguration agent) + /// One agent's harness switches, fully resolved. + /// Whether the agent gets the todo tools. + /// Whether the agent gets the mode tools. + /// Whether the agent is told the current date and time each turn. + /// Whether the framework's base instructions sit above the document's own. + public sealed record ResolvedHarness(bool Todos, bool Mode, bool Clock, bool BaseInstructions); + + /// + /// Composes one agent's harness switches (todos:, mode:, clock:, + /// baseInstructions:) from agents.defaults and the agent's own keys, key by key. + /// The tool switches are off until named; the two posture switches are on until named, so an + /// agent has to opt out of knowing the date or of the base instructions rather than opt in. + /// + public static class AgentHarness { - ArgumentNullException.ThrowIfNull(agent); + /// Composes one agent's resolved harness switches. + /// The agents.defaults section, or . + /// The agent to resolve. + public static ResolvedHarness Compose(AgentDefaults? defaults, AgentConfiguration agent) + { + ArgumentNullException.ThrowIfNull(agent); - return new ResolvedHarness( - agent.Todos ?? defaults?.Todos ?? false, - agent.Mode ?? defaults?.Mode ?? false, - agent.Clock ?? defaults?.Clock ?? true, - agent.BaseInstructions ?? defaults?.BaseInstructions ?? true); + return new ResolvedHarness( + agent.Todos ?? defaults?.Todos ?? false, + agent.Mode ?? defaults?.Mode ?? false, + agent.Clock ?? defaults?.Clock ?? true, + agent.BaseInstructions ?? defaults?.BaseInstructions ?? true); + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentHarnessProviders.cs b/src/AgentCore.Application/Configuration/Compilation/AgentHarnessProviders.cs index 580dffdc..34f89702 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentHarnessProviders.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentHarnessProviders.cs @@ -3,308 +3,302 @@ using AgentCore.Application.Runtime.Harness; using AgentCore.Application.Runtime.Turn; using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// The context providers behind one agent's harness switches (todos:, mode:, -/// clock:, memory:, files:, shell:, background:), added into the provider list -/// builds. -/// -internal static class AgentHarnessProviders +namespace AgentCore.Application.Configuration.Compilation { /// - /// MAF's default , with its persistence claim - /// replaced: the default tells the model these files "persist beyond the current conversation", - /// which is false here — FileMemoryProvider's working folder is the conversation's workspace, - /// deleted at EndConversation. Every other sentence, including how to use the tools, is unchanged. - /// - private const string MemoryInstructions = - "## File Based Memory\n" - + "You have access to a file-based memory system via the `file_memory_*` tools for storing and retrieving information across interactions.\n" - + "These files act as your working memory for this conversation: they live in this conversation's workspace and are deleted when the conversation ends,\n" - + "so anything you write now stays available for the rest of this conversation, but not after it ends.\n" - + "Use these tools to store plans, memories, processing results, or downloaded data.\n\n" - + "- Use descriptive file names (e.g., \"projectarchitecture.md\", \"userpreferences.md\").\n" - + "- Include a description when writing a file to help with future discovery.\n" - + "- Before starting new tasks, use file_memory_ls and file_memory_grep to check for relevant existing memories to avoid duplicate work.\n" - + "- Keep memories up-to-date by overwriting files when information changes, or by using file_memory_replace and file_memory_replace_lines to make small edits.\n" - + "- When you receive large amounts of data (e.g., downloaded web pages, API responses, research results),\n" - + " write them to files if they will be required later, so that they are not lost when older context is compacted or truncated.\n" - + " This ensures important data remains accessible across long-running sessions."; - - /// - /// MAF's default , with its persistence claim - /// replaced: the default tells the model these files "persist beyond the current session" and - /// "may be shared across sessions or agents", which is false here — ConversationFilesProvider - /// resolves to the conversation's workspace, deleted at EndConversation. Every other sentence, including - /// how to use the tools, is unchanged. + /// The context providers behind one agent's harness switches (todos:, mode:, + /// clock:, memory:, files:, shell:, background:), added into the provider list + /// builds. /// - private const string FilesInstructions = - "## File Access\n" - + "You have access to a shared file storage area via the `file_access_*` tools for reading, writing, and managing files.\n" - + "These files live in this conversation's workspace: they exist only for the duration of this conversation and are deleted when the conversation ends.\n" - + "Use these tools to read input data provided by the user, write output artifacts, and manage any files the user has asked you to work with.\n\n" - + "- Never delete or overwrite existing files unless the user has explicitly asked you to do so.\n" - + "- Files may be organized into subdirectories. Use `file_access_ls` to explore the tree level by level,\n" - + " or `file_access_grep` to search file contents recursively across the whole store.\n" - + "- To make small edits to an existing file, prefer `file_access_replace` (substring replacement) or\n" - + " `file_access_replace_lines` (whole-line replacement) over rewriting the whole file.\n" - + "- To change part of a file, find the line numbers with `file_access_grep`, read the range around them\n" - + " with `file_access_read_lines`, then edit with `file_access_replace_lines`. Reading the whole file\n" - + " first is rarely necessary."; + internal static class AgentHarnessProviders + { + /// + /// MAF's default , with its persistence claim + /// replaced: the default tells the model these files "persist beyond the current conversation", + /// which is false here — FileMemoryProvider's working folder is the conversation's workspace, + /// deleted at EndConversation. Every other sentence, including how to use the tools, is unchanged. + /// + private const string MemoryInstructions = + "## File Based Memory\n" + + "You have access to a file-based memory system via the `file_memory_*` tools for storing and retrieving information across interactions.\n" + + "These files act as your working memory for this conversation: they live in this conversation's workspace and are deleted when the conversation ends,\n" + + "so anything you write now stays available for the rest of this conversation, but not after it ends.\n" + + "Use these tools to store plans, memories, processing results, or downloaded data.\n\n" + + "- Use descriptive file names (e.g., \"projectarchitecture.md\", \"userpreferences.md\").\n" + + "- Include a description when writing a file to help with future discovery.\n" + + "- Before starting new tasks, use file_memory_ls and file_memory_grep to check for relevant existing memories to avoid duplicate work.\n" + + "- Keep memories up-to-date by overwriting files when information changes, or by using file_memory_replace and file_memory_replace_lines to make small edits.\n" + + "- When you receive large amounts of data (e.g., downloaded web pages, API responses, research results),\n" + + " write them to files if they will be required later, so that they are not lost when older context is compacted or truncated.\n" + + " This ensures important data remains accessible across long-running sessions."; + + /// + /// MAF's default , with its persistence claim + /// replaced: the default tells the model these files "persist beyond the current session" and + /// "may be shared across sessions or agents", which is false here — ConversationFilesProvider + /// resolves to the conversation's workspace, deleted at EndConversation. Every other sentence, including + /// how to use the tools, is unchanged. + /// + private const string FilesInstructions = + "## File Access\n" + + "You have access to a shared file storage area via the `file_access_*` tools for reading, writing, and managing files.\n" + + "These files live in this conversation's workspace: they exist only for the duration of this conversation and are deleted when the conversation ends.\n" + + "Use these tools to read input data provided by the user, write output artifacts, and manage any files the user has asked you to work with.\n\n" + + "- Never delete or overwrite existing files unless the user has explicitly asked you to do so.\n" + + "- Files may be organized into subdirectories. Use `file_access_ls` to explore the tree level by level,\n" + + " or `file_access_grep` to search file contents recursively across the whole store.\n" + + "- To make small edits to an existing file, prefer `file_access_replace` (substring replacement) or\n" + + " `file_access_replace_lines` (whole-line replacement) over rewriting the whole file.\n" + + "- To change part of a file, find the line numbers with `file_access_grep`, read the range around them\n" + + " with `file_access_read_lines`, then edit with `file_access_replace_lines`. Reading the whole file\n" + + " first is rarely necessary."; #pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. - /// Adds this agent's harness providers, in declaration order: todos, mode, clock, memory, files, shell, background. - /// The provider list under construction. - /// The agents.defaults section, or . - /// The agent being compiled. - /// The compile-time seams, including the bound workspace root. - /// This agent's JSON pointer, for a memory:, files:, shell:, or background: failure. - /// Resolves an agents.items id to its compiled agent, or when undeclared. - /// Collects the built background providers, so the conversation can release their sessions when it ends. - public static void Add( - List providers, - AgentDefaults? defaults, - AgentConfiguration item, - AgentCompilationContext context, - string pointer, - Func resolve, - ICollection? background = null) - { - var harness = AgentHarness.Compose(defaults, item); - - if (harness.Todos) + /// Adds this agent's harness providers, in declaration order: todos, mode, clock, memory, files, shell, background. + /// The provider list under construction. + /// The agents.defaults section, or . + /// The agent being compiled. + /// The compile-time seams, including the bound workspace root. + /// This agent's JSON pointer, for a memory:, files:, shell:, or background: failure. + /// Resolves an agents.items id to its compiled agent, or when undeclared. + /// Collects the built background providers, so the conversation can release their sessions when it ends. + public static void Add( + List providers, + AgentDefaults? defaults, + AgentConfiguration item, + AgentCompilationContext context, + string pointer, + Func resolve, + ICollection? background = null) { - providers.Add(new TodoProvider()); - } + ResolvedHarness harness = AgentHarness.Compose(defaults, item); - if (harness.Mode) - { - providers.Add(new AgentModeProvider()); - } + if (harness.Todos) + { + providers.Add(new TodoProvider()); + } - if (harness.Clock) - { - providers.Add(new ClockContextProvider(context.Clock ?? TimeProvider.System)); - } + if (harness.Mode) + { + providers.Add(new AgentModeProvider()); + } - if (item.Memory is { Store: AgentFileStoreKind.Workspace }) - { - providers.Add(BuildMemoryProvider(item, context, pointer)); - } + if (harness.Clock) + { + providers.Add(new ClockContextProvider(context.Clock ?? TimeProvider.System)); + } - if (item.Files is { Store: AgentFileStoreKind.Workspace } files) - { - providers.Add(BuildFilesProvider(item, files, context, pointer)); - } + if (item.Memory is { Store: AgentFileStoreKind.Workspace }) + { + providers.Add(BuildMemoryProvider(item, context, pointer)); + } - if (item.Shell is { } shell) - { - var options = AgentShellOptionsCompiler.Build(item, shell, context, pointer); - providers.Add(new ConversationShellProvider(options)); - providers.Add(new ConversationShellEnvironmentProvider(options)); - } + if (item.Files is { Store: AgentFileStoreKind.Workspace } files) + { + providers.Add(BuildFilesProvider(item, files, context, pointer)); + } - if (item.Background.Count > 0) - { - var provider = AgentBackgroundCompiler.Build(item, pointer, resolve); - providers.Add(provider); - background?.Add(provider); + if (item.Shell is { } shell) + { + ConversationShellOptions options = AgentShellOptionsCompiler.Build(item, shell, context, pointer); + providers.Add(new ConversationShellProvider(options)); + providers.Add(new ConversationShellEnvironmentProvider(options)); + } + + if (item.Background.Count > 0) + { + BackgroundAgentsProvider provider = AgentBackgroundCompiler.Build(item, pointer, resolve); + providers.Add(provider); + background?.Add(provider); + } } - } #pragma warning restore MAAI001 #pragma warning disable MAAI001 // The loop family is evaluation-only in Microsoft.Agents.AI 1.21.0. - /// - /// Wraps one compiled agent in its loop: block: a over the - /// until: evaluators in document order, capped at maxRounds:. No block, no wrap. - /// - /// The compiled agent. - /// The agents.defaults section, or . - /// The agent being compiled. - /// This agent's JSON pointer, for a loop: failure. - /// The loop-wrapped agent, or unchanged. - public static AIAgent ApplyLoop(AIAgent agent, AgentDefaults? defaults, AgentConfiguration item, string pointer) - { - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(item); - - if (item.Loop is not { } loop) + /// + /// Wraps one compiled agent in its loop: block: a over the + /// until: evaluators in document order, capped at maxRounds:. No block, no wrap. + /// + /// The compiled agent. + /// The agents.defaults section, or . + /// The agent being compiled. + /// This agent's JSON pointer, for a loop: failure. + /// The loop-wrapped agent, or unchanged. + public static AIAgent ApplyLoop(AIAgent agent, AgentDefaults? defaults, AgentConfiguration item, string pointer) { - return agent; - } + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(item); - if (loop.Until is not { Count: > 0 }) - { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "loop"), - $"the agent '{item.Id}' declares a loop: block with no until: entries, so the loop would " - + "run exactly once and maxRounds: would never apply. Name what ends the loop, or remove " - + "the loop: block."); - } - - var harness = AgentHarness.Compose(defaults, item); - List evaluators = new(loop.Until.Count); + if (item.Loop is not { } loop) + { + return agent; + } - for (var index = 0; index < loop.Until.Count; index++) - { - var untilPointer = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "loop"), "until"), index); + if (loop.Until is not { Count: > 0 }) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "loop"), + $"the agent '{item.Id}' declares a loop: block with no until: entries, so the loop would " + + "run exactly once and maxRounds: would never apply. Name what ends the loop, or remove " + + "the loop: block."); + } - var until = loop.Until[index]; + ResolvedHarness harness = AgentHarness.Compose(defaults, item); + List evaluators = new(loop.Until.Count); - if (until.Todos is not null) + for (int index = 0; index < loop.Until.Count; index++) { - if (!harness.Todos) - { - throw ConfigurationCompiler.Fail( - untilPointer, - $"the agent '{item.Id}' declares loop: until: todos: and no todos: switch, so the " - + "evaluator would fault every turn resolving its provider. Set todos: true, or " - + "remove the entry."); - } + string untilPointer = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "loop"), "until"), index); - evaluators.Add(new TodoCompletionLoopEvaluator(new TodoCompletionLoopEvaluatorOptions())); - } + LoopUntilConfiguration until = loop.Until[index]; - if (until.Background is not null) - { - if (item.Background.Count == 0) + if (until.Todos is not null) { - throw ConfigurationCompiler.Fail( - untilPointer, - $"the agent '{item.Id}' declares loop: until: background: and no background: children, " - + "so the evaluator would fault every turn resolving its provider. Name the children, " - + "or remove the entry."); + if (!harness.Todos) + { + throw ConfigurationCompiler.Fail( + untilPointer, + $"the agent '{item.Id}' declares loop: until: todos: and no todos: switch, so the " + + "evaluator would fault every turn resolving its provider. Set todos: true, or " + + "remove the entry."); + } + + evaluators.Add(new TodoCompletionLoopEvaluator(new TodoCompletionLoopEvaluatorOptions())); } - evaluators.Add(new BackgroundTaskCompletionLoopEvaluator(new BackgroundTaskCompletionLoopEvaluatorOptions())); + if (until.Background is not null) + { + if (item.Background.Count == 0) + { + throw ConfigurationCompiler.Fail( + untilPointer, + $"the agent '{item.Id}' declares loop: until: background: and no background: children, " + + "so the evaluator would fault every turn resolving its provider. Name the children, " + + "or remove the entry."); + } + + evaluators.Add(new BackgroundTaskCompletionLoopEvaluator(new BackgroundTaskCompletionLoopEvaluatorOptions())); + } } - } - // Every iteration's text reaches the stream; there are no per-iteration entries (decision 14). - return new LoopAgent(agent, evaluators, new LoopAgentOptions { MaxIterations = loop.MaxRounds }); - } + // Every iteration's text reaches the stream; there are no per-iteration entries (decision 14). + return new LoopAgent(agent, evaluators, new LoopAgentOptions { MaxIterations = loop.MaxRounds }); + } #pragma warning restore MAAI001 #pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - /// - /// The state keys of the harness providers among — never the - /// history provider's key, which is the transcript and belongs to store 1. - /// - internal static IReadOnlySet StateKeysOf(IEnumerable providers) - { - HashSet keys = new(StringComparer.Ordinal); - - foreach (var provider in providers) + /// + /// The state keys of the harness providers among — never the + /// history provider's key, which is the transcript and belongs to store 1. + /// + internal static IReadOnlySet StateKeysOf(IEnumerable providers) { - if (provider is not (TodoProvider or AgentModeProvider or FileMemoryProvider or FileAccessProvider or BackgroundAgentsProvider)) - { - continue; - } + HashSet keys = new(StringComparer.Ordinal); - foreach (var key in provider.StateKeys) + foreach (AIContextProvider provider in providers) { - keys.Add(key); + if (provider is not (TodoProvider or AgentModeProvider or FileMemoryProvider or FileAccessProvider or BackgroundAgentsProvider)) + { + continue; + } + + foreach (string key in provider.StateKeys) + { + _ = keys.Add(key); + } } - } - return keys; - } + return keys; + } #pragma warning restore MAAI001 - private static FileMemoryProvider BuildMemoryProvider( - AgentConfiguration item, AgentCompilationContext context, string pointer) - { - if (context.WorkspaceRoot is not { } root) + private static FileMemoryProvider BuildMemoryProvider( + AgentConfiguration item, AgentCompilationContext context, string pointer) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "memory"), - $"the agent '{item.Id}' declares a memory: block and this host bound no workspace " - + "root, so there is nowhere to keep the files. Call options.UseWorkspace(...) with " - + "the folder, or remove the memory: block."); - } + if (context.WorkspaceRoot is not { } root) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "memory"), + $"the agent '{item.Id}' declares a memory: block and this host bound no workspace " + + "root, so there is nowhere to keep the files. Call options.UseWorkspace(...) with " + + "the folder, or remove the memory: block."); + } - try - { + try + { #pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - return new FileMemoryProvider( - new FileSystemAgentFileStore(root), - InitializeWorkingFolder, - new FileMemoryProviderOptions { Instructions = MemoryInstructions }); + return new FileMemoryProvider( + new FileSystemAgentFileStore(root), + InitializeWorkingFolder, + new FileMemoryProviderOptions { Instructions = MemoryInstructions }); #pragma warning restore MAAI001 + } + catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) + { + // FileSystemAgentFileStore's constructor creates the root eagerly, and this compiles + // before ConversationSessionStartup's own guarded create — so a bad root fails here first, and + // must fail with the same named cause an operator gets from that later guard. + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "memory"), + $"the agent '{item.Id}' declares a memory: block and the workspace root '{root}' " + + $"could not be created: {exception.Message} Check the path passed to " + + "options.UseWorkspace(...), and that the process has permission to create it."); + } } - catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) - { - // FileSystemAgentFileStore's constructor creates the root eagerly, and this compiles - // before ConversationSessionStartup's own guarded create — so a bad root fails here first, and - // must fail with the same named cause an operator gets from that later guard. - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "memory"), - $"the agent '{item.Id}' declares a memory: block and the workspace root '{root}' " - + $"could not be created: {exception.Message} Check the path passed to " - + "options.UseWorkspace(...), and that the process has permission to create it."); - } - } #pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - private static ConversationFilesProvider BuildFilesProvider( - AgentConfiguration item, - AgentFilesConfiguration files, - AgentCompilationContext context, - string pointer) - { - if (context.WorkspaceRoot is null) + private static ConversationFilesProvider BuildFilesProvider( + AgentConfiguration item, + AgentFilesConfiguration files, + AgentCompilationContext context, + string pointer) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "files"), - $"the agent '{item.Id}' declares a files: block and this host bound no workspace " - + "root, so there is nowhere to keep the files. Call options.UseWorkspace(...) with " - + "the folder, or remove the files: block."); + return context.WorkspaceRoot is null + ? throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "files"), + $"the agent '{item.Id}' declares a files: block and this host bound no workspace " + + "root, so there is nowhere to keep the files. Call options.UseWorkspace(...) with " + + "the folder, or remove the files: block.") + : new ConversationFilesProvider( + context.WorkspaceRoot, + new FileAccessProviderOptions + { + DisableWriteTools = !files.Write, + DisableReadOnlyToolApproval = true, + DisableWriteToolApproval = true, + Instructions = FilesInstructions, + }); } - return new ConversationFilesProvider( - context.WorkspaceRoot, - new FileAccessProviderOptions - { - DisableWriteTools = !files.Write, - DisableReadOnlyToolApproval = true, - DisableWriteToolApproval = true, - Instructions = FilesInstructions, - }); - } - #pragma warning restore MAAI001 #pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - /// - /// Builds the state a new session starts with: its working - /// folder set to the id of the conversation running the turn, so it reads and writes under - /// <root>/<conversationId>/ — the folder the host creates and deletes with the conversation. - /// - private static FileMemoryState InitializeWorkingFolder(AgentSession? session) - { - if (TurnRegistry.For(session)?.ConversationId is not { } conversationId) + /// + /// Builds the state a new session starts with: its working + /// folder set to the id of the conversation running the turn, so it reads and writes under + /// <root>/<conversationId>/ — the folder the host creates and deletes with the conversation. + /// + private static FileMemoryState InitializeWorkingFolder(AgentSession? session) { - throw new InvalidOperationException( - "A memory: block's FileMemoryProvider needs the running conversation's id, and no turn is " - + "filed for this session. The provider's working folder is bound only while " - + "a turn runs through a ConversationSession. Run the agent through a ConversationSession."); + return TurnRegistry.For(session)?.ConversationId is not { } conversationId + ? throw new InvalidOperationException( + "A memory: block's FileMemoryProvider needs the running conversation's id, and no turn is " + + "filed for this session. The provider's working folder is bound only while " + + "a turn runs through a ConversationSession. Run the agent through a ConversationSession.") + : new FileMemoryState { WorkingFolder = conversationId }; } - return new FileMemoryState { WorkingFolder = conversationId }; - } - #pragma warning restore MAAI001 + } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentInstructions.cs b/src/AgentCore.Application/Configuration/Compilation/AgentInstructions.cs index 92d0610b..156e4670 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentInstructions.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentInstructions.cs @@ -1,77 +1,78 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Composes the instructions of one agent from the framework's base, the shared prefix, and the -/// stage delta. -/// -public static class AgentInstructions +namespace AgentCore.Application.Configuration.Compilation { - /// The separator between the base, the cached prefix, and the stage delta. - public const string Separator = "\n\n"; - /// - /// The posture every agent starts from. + /// Composes the instructions of one agent from the framework's base, the shared prefix, and the + /// stage delta. /// - public static string Base { get; } = - "You are a helpful AI assistant that uses tools to complete tasks.\n" - + "\n" - + "## General guidelines\n" - + "\n" - + "- Think through the task before acting. Break complex work into clear steps.\n" - + "- Use the tools available to you to gather information, perform actions, and verify results.\n" - + "- Explain your reasoning and thought process as you work through tasks.\n" - + "- Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.\n" - + "- Avoid making more than 4 tool calls in a row without explaining what you are doing.\n" - + "- If a tool call fails or returns unexpected results, adapt your approach rather than repeating the same conversation.\n" - + "- When you have completed the task, present a clear and concise summary of what you did and what you found.\n" - + "\n" - + "Resolve what you can from what you know and what you are given. Ask only for what you " - + "cannot resolve, and ask for one thing at a time.\n" - + "If the request needs something you cannot do, say so in one sentence and offer the " - + "nearest thing you can do.\n" - + "Never invent a fact, a value, or a source.\n" - + "Finish the task. Do not stop at the easy part.\n" - + "The instructions below take priority over these."; - - /// Puts the base and the shared prefix above the delta of one agent. - /// The agents.defaults section, or . - /// The agent whose delta goes below the prefix. - /// The composed instructions, or when no part exists. - public static string? Compose(AgentDefaults? defaults, AgentConfiguration agent) + public static class AgentInstructions { - ArgumentNullException.ThrowIfNull(agent); + /// The separator between the base, the cached prefix, and the stage delta. + public const string Separator = "\n\n"; - var parts = new List(3); + /// + /// The posture every agent starts from. + /// + public static string Base { get; } = + "You are a helpful AI assistant that uses tools to complete tasks.\n" + + "\n" + + "## General guidelines\n" + + "\n" + + "- Think through the task before acting. Break complex work into clear steps.\n" + + "- Use the tools available to you to gather information, perform actions, and verify results.\n" + + "- Explain your reasoning and thought process as you work through tasks.\n" + + "- Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.\n" + + "- Avoid making more than 4 tool calls in a row without explaining what you are doing.\n" + + "- If a tool call fails or returns unexpected results, adapt your approach rather than repeating the same conversation.\n" + + "- When you have completed the task, present a clear and concise summary of what you did and what you found.\n" + + "\n" + + "Resolve what you can from what you know and what you are given. Ask only for what you " + + "cannot resolve, and ask for one thing at a time.\n" + + "If the request needs something you cannot do, say so in one sentence and offer the " + + "nearest thing you can do.\n" + + "Never invent a fact, a value, or a source.\n" + + "Finish the task. Do not stop at the easy part.\n" + + "The instructions below take priority over these."; - if (AgentHarness.Compose(defaults, agent).BaseInstructions) + /// Puts the base and the shared prefix above the delta of one agent. + /// The agents.defaults section, or . + /// The agent whose delta goes below the prefix. + /// The composed instructions, or when no part exists. + public static string? Compose(AgentDefaults? defaults, AgentConfiguration agent) { - parts.Add(Base); - } + ArgumentNullException.ThrowIfNull(agent); - // The prefix always comes before the delta. Nothing per-turn inside either. - if (Trim(defaults?.Instructions) is { } prefix) - { - parts.Add(prefix); - } + List parts = new(3); - if (Trim(agent.Instructions) is { } delta) - { - parts.Add(delta); - } + if (AgentHarness.Compose(defaults, agent).BaseInstructions) + { + parts.Add(Base); + } - return parts.Count == 0 ? null : string.Join(Separator, parts); - } + // The prefix always comes before the delta. Nothing per-turn inside either. + if (Trim(defaults?.Instructions) is { } prefix) + { + parts.Add(prefix); + } - private static string? Trim(string? text) - { - if (text is null) - { - return null; + if (Trim(agent.Instructions) is { } delta) + { + parts.Add(delta); + } + + return parts.Count == 0 ? null : string.Join(Separator, parts); } - var trimmed = text.Trim('\n', '\r'); - return trimmed.Length == 0 ? null : trimmed; + private static string? Trim(string? text) + { + if (text is null) + { + return null; + } + + string trimmed = text.Trim('\n', '\r'); + return trimmed.Length == 0 ? null : trimmed; + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs b/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs index 433fd672..51a32dda 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs @@ -1,116 +1,114 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// One agent's knowledge: block, fully resolved: every field inherited or defaulted, so -/// nothing downstream has to ask whether a value came from the agent, the defaults, or nowhere. -/// -/// How this agent reaches the knowledge base. -/// How many cards to retrieve. -/// Whether the model sees the source label. -/// Whether this agent's searches are confined to a scope. -public sealed record ResolvedKnowledge(KnowledgeMode Mode, int Limit, bool Citations, bool Scoped) -{ - /// - /// Gets the document-level ambiguity wiring the search side reads, or - /// where the document configures none. - /// - public ResolvedClarification Clarification { get; init; } = ResolvedClarification.None; -} - -/// -/// Composes one agent's knowledge: block from agents.defaults.knowledge and the -/// agent's own block, key by key. -/// -public static class AgentKnowledge +namespace AgentCore.Application.Configuration.Compilation { - /// The mode used when neither the agent nor the defaults name one. - public const KnowledgeMode DefaultMode = KnowledgeMode.Prefetch; - - /// The limit used when neither the agent nor the defaults name one. - public const int DefaultLimit = 5; - /// - /// The citations flag used when neither the agent nor the defaults name one. + /// One agent's knowledge: block, fully resolved: every field inherited or defaulted, so + /// nothing downstream has to ask whether a value came from the agent, the defaults, or nowhere. /// - public const bool DefaultCitations = false; + /// How this agent reaches the knowledge base. + /// How many cards to retrieve. + /// Whether the model sees the source label. + /// Whether this agent's searches are confined to a scope. + public sealed record ResolvedKnowledge(KnowledgeMode Mode, int Limit, bool Citations, bool Scoped) + { + /// + /// Gets the document-level ambiguity wiring the search side reads, or + /// where the document configures none. + /// + public ResolvedClarification Clarification { get; init; } = ResolvedClarification.None; + } /// - /// The scoped flag used when neither the agent nor the defaults name one. + /// Composes one agent's knowledge: block from agents.defaults.knowledge and the + /// agent's own block, key by key. /// - public const bool DefaultScoped = true; - - /// Composes one agent's resolved knowledge settings. - /// The agents.defaults section, or . - /// The agent to resolve. - /// - /// The resolved settings, or when neither the defaults nor the agent - /// declares a knowledge: block — that agent has nothing to do with the knowledge base, - /// and pays nothing for it. - /// - public static ResolvedKnowledge? Compose(AgentDefaults? defaults, AgentConfiguration agent) + public static class AgentKnowledge { - ArgumentNullException.ThrowIfNull(agent); - - var own = agent.Knowledge; - var shared = defaults?.Knowledge; - - if (own is null && shared is null) + /// The mode used when neither the agent nor the defaults name one. + public const KnowledgeMode DefaultMode = KnowledgeMode.Prefetch; + + /// The limit used when neither the agent nor the defaults name one. + public const int DefaultLimit = 5; + + /// + /// The citations flag used when neither the agent nor the defaults name one. + /// + public const bool DefaultCitations = false; + + /// + /// The scoped flag used when neither the agent nor the defaults name one. + /// + public const bool DefaultScoped = true; + + /// Composes one agent's resolved knowledge settings. + /// The agents.defaults section, or . + /// The agent to resolve. + /// + /// The resolved settings, or when neither the defaults nor the agent + /// declares a knowledge: block — that agent has nothing to do with the knowledge base, + /// and pays nothing for it. + /// + public static ResolvedKnowledge? Compose(AgentDefaults? defaults, AgentConfiguration agent) { - return null; + ArgumentNullException.ThrowIfNull(agent); + + AgentKnowledgeConfiguration? own = agent.Knowledge; + AgentKnowledgeConfiguration? shared = defaults?.Knowledge; + + return own is null && shared is null + ? null + : new ResolvedKnowledge( + own?.Mode ?? shared?.Mode ?? DefaultMode, + own?.Limit ?? shared?.Limit ?? DefaultLimit, + own?.Citations ?? shared?.Citations ?? DefaultCitations, + own?.Scoped ?? shared?.Scoped ?? DefaultScoped); } - return new ResolvedKnowledge( - own?.Mode ?? shared?.Mode ?? DefaultMode, - own?.Limit ?? shared?.Limit ?? DefaultLimit, - own?.Citations ?? shared?.Citations ?? DefaultCitations, - own?.Scoped ?? shared?.Scoped ?? DefaultScoped); - } - - /// - /// Whether ANY agent in the document composes to a knowledge block at all. - /// - /// The agents: section. - public static bool AnyDeclared(AgentsConfiguration agents) - { - ArgumentNullException.ThrowIfNull(agents); + /// + /// Whether ANY agent in the document composes to a knowledge block at all. + /// + /// The agents: section. + public static bool AnyDeclared(AgentsConfiguration agents) + { + ArgumentNullException.ThrowIfNull(agents); - return agents.Items.Any(agent => Compose(agents.Defaults, agent) is not null); - } + return agents.Items.Any(agent => Compose(agents.Defaults, agent) is not null); + } - /// - /// Whether ANY agent in the document composes to a scoped search. - /// - /// The agents: section. - /// - /// when at least one agent's composed knowledge is scoped. An agent with - /// no composed knowledge at all declares nothing about scoping, so it cannot make this true — - /// vacuously false over an empty set of participants, the same convention Enumerable.Any - /// uses. - /// - public static bool AnyScoped(AgentsConfiguration agents) - { - ArgumentNullException.ThrowIfNull(agents); + /// + /// Whether ANY agent in the document composes to a scoped search. + /// + /// The agents: section. + /// + /// when at least one agent's composed knowledge is scoped. An agent with + /// no composed knowledge at all declares nothing about scoping, so it cannot make this true — + /// vacuously false over an empty set of participants, the same convention Enumerable.Any + /// uses. + /// + public static bool AnyScoped(AgentsConfiguration agents) + { + ArgumentNullException.ThrowIfNull(agents); - return agents.Items.Any(agent => Compose(agents.Defaults, agent) is { Scoped: true }); - } + return agents.Items.Any(agent => Compose(agents.Defaults, agent) is { Scoped: true }); + } - /// - /// Whether EVERY agent in the document that composes to a knowledge block composes to a scoped - /// one. - /// - /// The agents: section. - /// - /// when no agent with composed knowledge is unscoped. An agent with no - /// composed knowledge never reads the store, so it does not count against this either way — - /// vacuously true over an empty set of participants, the same convention Enumerable.All - /// uses, and the safe direction besides: a store nobody reads is never asked to enforce anything. - /// - public static bool AllScoped(AgentsConfiguration agents) - { - ArgumentNullException.ThrowIfNull(agents); + /// + /// Whether EVERY agent in the document that composes to a knowledge block composes to a scoped + /// one. + /// + /// The agents: section. + /// + /// when no agent with composed knowledge is unscoped. An agent with no + /// composed knowledge never reads the store, so it does not count against this either way — + /// vacuously true over an empty set of participants, the same convention Enumerable.All + /// uses, and the safe direction besides: a store nobody reads is never asked to enforce anything. + /// + public static bool AllScoped(AgentsConfiguration agents) + { + ArgumentNullException.ThrowIfNull(agents); - return agents.Items.All(agent => Compose(agents.Defaults, agent) is not { Scoped: false }); + return agents.Items.All(agent => Compose(agents.Defaults, agent) is not { Scoped: false }); + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentShellOptionsCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentShellOptionsCompiler.cs index 7edb3cf2..ea2e62b3 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentShellOptionsCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentShellOptionsCompiler.cs @@ -5,122 +5,123 @@ using AgentCore.Application.Secrets; using Microsoft.Agents.AI.Tools.Shell; -namespace AgentCore.Application.Configuration.Compilation; - -/// Compiles one agent's shell: block into . -internal static class AgentShellOptionsCompiler +namespace AgentCore.Application.Configuration.Compilation { - /// Builds this agent's shell options from its declared shell: block. - /// The agent being compiled. - /// The declared block. - /// The compile-time seams, including the bound workspace root and resolved secrets. - /// This agent's JSON pointer. - /// - /// The block names no workspace root, a Docker-only key under kind: local, or a policy - /// pattern that is not a valid regex. - /// - internal static ConversationShellOptions Build( - AgentConfiguration item, - ShellConfiguration shell, - AgentCompilationContext context, - string pointer) + /// Compiles one agent's shell: block into . + internal static class AgentShellOptionsCompiler { - if (context.WorkspaceRoot is null) + /// Builds this agent's shell options from its declared shell: block. + /// The agent being compiled. + /// The declared block. + /// The compile-time seams, including the bound workspace root and resolved secrets. + /// This agent's JSON pointer. + /// + /// The block names no workspace root, a Docker-only key under kind: local, or a policy + /// pattern that is not a valid regex. + /// + internal static ConversationShellOptions Build( + AgentConfiguration item, + ShellConfiguration shell, + AgentCompilationContext context, + string pointer) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "shell"), - $"the agent '{item.Id}' declares a shell: block and this host bound no workspace " - + "root, so the shell has no working directory. Call options.UseWorkspace(...) with " - + "the folder, or remove the shell: block."); - } + if (context.WorkspaceRoot is null) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "shell"), + $"the agent '{item.Id}' declares a shell: block and this host bound no workspace " + + "root, so the shell has no working directory. Call options.UseWorkspace(...) with " + + "the folder, or remove the shell: block."); + } - if (shell.Kind == ShellKind.Local) - { - RejectDockerOnlyKey(item, pointer, "image", shell.Image is not null); - RejectDockerOnlyKey(item, pointer, "network", shell.Network is not null); - RejectDockerOnlyKey(item, pointer, "memoryMb", shell.MemoryMb is not null); - } + if (shell.Kind == ShellKind.Local) + { + RejectDockerOnlyKey(item, pointer, "image", shell.Image is not null); + RejectDockerOnlyKey(item, pointer, "network", shell.Network is not null); + RejectDockerOnlyKey(item, pointer, "memoryMb", shell.MemoryMb is not null); + } - var policy = shell.Policy is { } declared ? BuildPolicy(item, declared, pointer) : null; + ShellPolicy? policy = shell.Policy is { } declared ? BuildPolicy(item, declared, pointer) : null; - var timeout = shell.TimeoutSeconds is { } seconds ? TimeSpan.FromSeconds(seconds) : (TimeSpan?)null; + TimeSpan? timeout = shell.TimeoutSeconds is { } seconds ? TimeSpan.FromSeconds(seconds) : (TimeSpan?)null; - var secrets = context.Secrets ?? ResolvedSecrets.Empty; - var env = shell.Env.Count == 0 - ? null - : shell.Env.ToDictionary( - static entry => entry.Key, - entry => secrets.Format(entry.Value), - StringComparer.Ordinal); + ResolvedSecrets secrets = context.Secrets ?? ResolvedSecrets.Empty; + Dictionary? env = shell.Env.Count == 0 + ? null + : shell.Env.ToDictionary( + static entry => entry.Key, + entry => secrets.Format(entry.Value), + StringComparer.Ordinal); - var maxOutputBytes = shell.MaxOutputKb is { } maxOutputKb ? maxOutputKb * 1024 : (int?)null; + int? maxOutputBytes = shell.MaxOutputKb is { } maxOutputKb ? maxOutputKb * 1024 : (int?)null; - var memoryBytes = shell.MemoryMb is { } memoryMb ? (long)memoryMb * 1024 * 1024 : (long?)null; + long? memoryBytes = shell.MemoryMb is { } memoryMb ? (long)memoryMb * 1024 * 1024 : (long?)null; - return new ConversationShellOptions( - shell.Kind, - policy, - timeout, - env, - maxOutputBytes, - shell.Image, - shell.Network, - memoryBytes); - } - - /// Fails compilation when a Docker-only shell: key appears under kind: local. - private static void RejectDockerOnlyKey(AgentConfiguration item, string pointer, string key, bool present) - { - if (!present) - { - return; + return new ConversationShellOptions( + shell.Kind, + policy, + timeout, + env, + maxOutputBytes, + shell.Image, + shell.Network, + memoryBytes); } - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "shell"), - $"the agent '{item.Id}' declares a shell: {key}: and kind: local, but {key}: only applies to " - + "kind: docker. Remove it, or set kind: docker."); - } - - private static ShellPolicy BuildPolicy( - AgentConfiguration item, - ShellPolicyConfiguration policy, - string pointer) - { - // ShellPolicy treats a supplied-but-empty allow list as deny-all (it denies any command that - // matches none of the allow patterns, and an empty list matches nothing), so an agent that - // declares no allow: must reach the executor with allowList: null, not an empty collection. - var allow = policy.Allow.Count == 0 ? null : policy.Allow; - - try + /// Fails compilation when a Docker-only shell: key appears under kind: local. + private static void RejectDockerOnlyKey(AgentConfiguration item, string pointer, string key, bool present) { - return new ShellPolicy(denyList: policy.Deny, allowList: allow); - } - catch (ArgumentException exception) - { - // ShellPolicy compiles every pattern into a Regex eagerly in its own constructor, so a - // bad pattern in either list throws here, at compile time, rather than at the model's - // first command. - var bad = policy.Deny.Concat(allow ?? []) - .FirstOrDefault(pattern => !IsValidRegex(pattern)); + if (!present) + { + return; + } throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "shell"), "policy"), - $"the agent '{item.Id}' declares a shell: policy whose pattern '{bad}' is not a " - + $"valid regex: {exception.Message}"); + ConfigurationError.AppendPointer(pointer, "shell"), + $"the agent '{item.Id}' declares a shell: {key}: and kind: local, but {key}: only applies to " + + "kind: docker. Remove it, or set kind: docker."); } - } - private static bool IsValidRegex(string pattern) - { - try + private static ShellPolicy BuildPolicy( + AgentConfiguration item, + ShellPolicyConfiguration policy, + string pointer) { - _ = new Regex(pattern, RegexOptions.None, TimeSpan.FromSeconds(1)); - return true; + // ShellPolicy treats a supplied-but-empty allow list as deny-all (it denies any command that + // matches none of the allow patterns, and an empty list matches nothing), so an agent that + // declares no allow: must reach the executor with allowList: null, not an empty collection. + IReadOnlyList? allow = policy.Allow.Count == 0 ? null : policy.Allow; + + try + { + return new ShellPolicy(denyList: policy.Deny, allowList: allow); + } + catch (ArgumentException exception) + { + // ShellPolicy compiles every pattern into a Regex eagerly in its own constructor, so a + // bad pattern in either list throws here, at compile time, rather than at the model's + // first command. + string? bad = policy.Deny.Concat(allow ?? []) + .FirstOrDefault(pattern => !IsValidRegex(pattern)); + + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "shell"), "policy"), + $"the agent '{item.Id}' declares a shell: policy whose pattern '{bad}' is not a " + + $"valid regex: {exception.Message}"); + } } - catch (ArgumentException) + + private static bool IsValidRegex(string pattern) { - return false; + try + { + _ = new Regex(pattern, RegexOptions.None, TimeSpan.FromSeconds(1)); + return true; + } + catch (ArgumentException) + { + return false; + } } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs index 64b172f8..c93fe5dd 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs @@ -6,131 +6,127 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Configuration.Compilation; - -internal static class AgentToolCompiler +namespace AgentCore.Application.Configuration.Compilation { - public static List? Build( - AgentConfiguration item, - ModelReference? model, - Dictionary declared, - AgentCompilationContext context, - string pointer, - Func resolveAgent) + internal static class AgentToolCompiler { - if (item.Tools.Count == 0) + public static List? Build( + AgentConfiguration item, + ModelReference? model, + Dictionary declared, + AgentCompilationContext context, + string pointer, + Func resolveAgent) { - return null; + if (item.Tools.Count == 0) + { + return null; + } + + List tools = []; + for (int index = 0; index < item.Tools.Count; index++) + { + string id = item.Tools[index]; + string toolPointer = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(pointer, "tools"), index); + + if (Resolve(id, declared, context.Tools, resolveAgent, toolPointer) is { } tool) + { + Add(tools, tool, item.Id, id, model, context); + } + } + + return tools.Count == 0 ? null : tools; } - List tools = []; - for (var index = 0; index < item.Tools.Count; index++) + /// Finds the tool one id names, or when no source can build it. + private static AITool? Resolve( + string id, + Dictionary declared, + ToolRegistry? registry, + Func resolveAgent, + string pointer) { - var id = item.Tools[index]; - var toolPointer = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(pointer, "tools"), index); - - if (Resolve(id, declared, context.Tools, resolveAgent, toolPointer) is { } tool) + if (!declared.TryGetValue(id, out ToolConfiguration? tool)) { - Add(tools, tool, item.Id, id, model, context); + return Undeclared(id, registry, pointer); } - } - return tools.Count == 0 ? null : tools; - } + if (tool.Kind == ToolKind.Agent) + { + // A kind: agent tool needs no tool factory. Section 7 says section 8 adds no port, + // and this kind adds none either: the inner agent is already in the document. + return AgentDelegationTool.Create(tool, ResolveInner(tool, resolveAgent, pointer)); + } - /// Finds the tool one id names, or when no source can build it. - private static AITool? Resolve( - string id, - Dictionary declared, - ToolRegistry? registry, - Func resolveAgent, - string pointer) - { - if (!declared.TryGetValue(id, out var tool)) - { - return Undeclared(id, registry, pointer); + return Declared(id, registry, pointer); } - if (tool.Kind == ToolKind.Agent) + /// An id that tools: does not declare. Only a registry that serves it can build it. + private static AITool? Undeclared(string id, ToolRegistry? registry, string pointer) { - // A kind: agent tool needs no tool factory. Section 7 says section 8 adds no port, - // and this kind adds none either: the inner agent is already in the document. - return AgentDelegationTool.Create(tool, ResolveInner(tool, resolveAgent, pointer)); - } - - return Declared(id, registry, pointer); - } + if (registry is null) + { + // No factory, so nothing could have been built anyway. + return null; + } - /// An id that tools: does not declare. Only a registry that serves it can build it. - private static AITool? Undeclared(string id, ToolRegistry? registry, string pointer) - { - if (registry is null) - { - // No factory, so nothing could have been built anyway. - return null; + return registry.Contains(id) + ? registry.Resolve(id) + : throw ConfigurationCompiler.Fail(pointer, $"the tool id '{id}' is not declared in tools:, and no tool source serves it."); } - return registry.Contains(id) - ? registry.Resolve(id) - : throw ConfigurationCompiler.Fail(pointer, $"the tool id '{id}' is not declared in tools:, and no tool source serves it."); - } - - /// An id that tools: declares. The registry, when there is one, has to serve it. - private static AITool? Declared(string id, ToolRegistry? registry, string pointer) - { - if (registry is null) + /// An id that tools: declares. The registry, when there is one, has to serve it. + private static AITool? Declared(string id, ToolRegistry? registry, string pointer) { - return null; + return registry switch + { + null => null, + _ when registry.Contains(id) => registry.Resolve(id), + _ => throw ConfigurationCompiler.Fail(pointer, $"the tool id '{id}' is declared, and no tool source serves it."), + }; } - return registry.Contains(id) - ? registry.Resolve(id) - : throw ConfigurationCompiler.Fail(pointer, $"the tool id '{id}' is declared, and no tool source serves it."); - } - - /// Adds one tool, unless it is a hosted marker its agent's model cannot run. - /// - /// Tested by type and not by the builtin name, so a hosted marker a host supplies through - /// its own IToolSource is covered by the same rule. - /// - private static void Add( - List tools, - AITool tool, - string agentId, - string toolId, - ModelReference? model, - AgentCompilationContext context) - { - if (tool is HostedWebSearchTool) + /// Adds one tool, unless it is a hosted marker its agent's model cannot run. + /// + /// Tested by type and not by the builtin name, so a hosted marker a host supplies through + /// its own IToolSource is covered by the same rule. + /// + private static void Add( + List tools, + AITool tool, + string agentId, + string toolId, + ModelReference? model, + AgentCompilationContext context) { - if (context.ChatClients.ResolveHostedTool(tool, model) is not { } resolved) + if (tool is HostedWebSearchTool) { - var logger = context.Loggers?.CreateLogger(typeof(AgentToolCompiler)) ?? NullLogger.Instance; - var modelDescription = model is { Ref.Length: > 0 } ? $"the model '{model.Ref}'" : "this agent's default model"; + if (context.ChatClients.ResolveHostedTool(tool, model) is not { } resolved) + { + ILogger logger = context.Loggers?.CreateLogger(typeof(AgentToolCompiler)) ?? NullLogger.Instance; + string modelDescription = model is { Ref.Length: > 0 } ? $"the model '{model.Ref}'" : "this agent's default model"; + + Log.HostedToolDropped(logger, agentId, toolId, tool.GetType().Name, modelDescription); + + return; + } - Log.HostedToolDropped(logger, agentId, toolId, tool.GetType().Name, modelDescription); - + tools.Add(resolved); return; } - tools.Add(resolved); - return; + tools.Add(tool); } - tools.Add(tool); - } - - private static AIAgent ResolveInner(ToolConfiguration tool, Func resolveAgent, string pointer) - { - if (tool.Agent is not { Length: > 0 } id) + private static AIAgent ResolveInner(ToolConfiguration tool, Func resolveAgent, string pointer) { - throw ConfigurationCompiler.Fail(pointer, $"the tool '{tool.Id}' is kind: agent and names no agent:."); + return tool.Agent is not { Length: > 0 } id + ? throw ConfigurationCompiler.Fail(pointer, $"the tool '{tool.Id}' is kind: agent and names no agent:.") + : resolveAgent(id) + ?? throw ConfigurationCompiler.Fail( + pointer, + $"the tool '{tool.Id}' delegates to the agent '{id}', which agents.items does not declare."); } - - return resolveAgent(id) - ?? throw ConfigurationCompiler.Fail( - pointer, - $"the tool '{tool.Id}' delegates to the agent '{id}', which agents.items does not declare."); } } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentsWalk.cs b/src/AgentCore.Application/Configuration/Compilation/AgentsWalk.cs index cf2b78c1..c6018469 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentsWalk.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentsWalk.cs @@ -1,17 +1,18 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - +namespace AgentCore.Application.Configuration.Compilation +{ #pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. -/// What one walk over agents.items shares between every agent it compiles. -/// The agents.defaults section, or . -/// The document's ambiguity wiring (§8), built once rather than re-derived per agent. -/// The providers.knowledge.scope block, or . -/// Collects the built background providers, so the conversation can release their sessions when it ends. -internal sealed record AgentsWalk( - AgentDefaults? Defaults, - ResolvedClarification Clarification, - KnowledgeScopeConfiguration? Scope, - ICollection Background); + /// What one walk over agents.items shares between every agent it compiles. + /// The agents.defaults section, or . + /// The document's ambiguity wiring (§8), built once rather than re-derived per agent. + /// The providers.knowledge.scope block, or . + /// Collects the built background providers, so the conversation can release their sessions when it ends. + internal sealed record AgentsWalk( + AgentDefaults? Defaults, + ResolvedClarification Clarification, + KnowledgeScopeConfiguration? Scope, + ICollection Background); #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Configuration/Compilation/CompileTableRow.cs b/src/AgentCore.Application/Configuration/Compilation/CompileTableRow.cs index 5f6186b4..444b4d18 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompileTableRow.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompileTableRow.cs @@ -2,46 +2,53 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// One row of the section 8.2 compile table. The row owns everything the compiler decides per -/// shape, so adding a shape is one new row and nothing else. -/// -internal abstract class CompileTableRow +namespace AgentCore.Application.Configuration.Compilation { - /// Gets the this row compiles. - internal abstract CompiledAgentShape Shape { get; } + /// + /// One row of the section 8.2 compile table. The row owns everything the compiler decides per + /// shape, so adding a shape is one new row and nothing else. + /// + internal abstract class CompileTableRow + { + /// Gets the this row compiles. + internal abstract CompiledAgentShape Shape { get; } - /// Gets whether the row answers its runs out of store 1 on its own session. - /// Rows 1 and 2 ride the session. A graph run rides the request messages. - internal virtual bool SessionCarriesHistory => false; + /// Gets whether the row answers its runs out of store 1 on its own session. + /// Rows 1 and 2 ride the session. A graph run rides the request messages. + internal virtual bool SessionCarriesHistory => false; - /// Builds the entry agent of one entry, and the stage table when the row has one. - /// The loaded document. - /// The entry key. Graph rows build workflows under it. - /// The entry being compiled. It already selected this row. - /// The JSON Pointer to the entry, /entries/<name>. - /// The compiled agents.items entries, keyed by id. - /// The seams the document names. - /// The agent a turn runs, and the agent id each policy.stages entry names. - /// The entry does not compile through this row. - internal abstract EntryBuild BuildEntry( - AgentCoreConfiguration configuration, - string entryName, - EntryConfiguration entry, - string entryPointer, - Dictionary agents, - AgentCompilationContext context); + /// Builds the entry agent of one entry, and the stage table when the row has one. + /// The loaded document. + /// The entry key. Graph rows build workflows under it. + /// The entry being compiled. It already selected this row. + /// The JSON Pointer to the entry, /entries/<name>. + /// The compiled agents.items entries, keyed by id. + /// The seams the document names. + /// The agent a turn runs, and the agent id each policy.stages entry names. + /// The entry does not compile through this row. + internal abstract EntryBuild BuildEntry( + AgentCoreConfiguration configuration, + string entryName, + EntryConfiguration entry, + string entryPointer, + Dictionary agents, + AgentCompilationContext context); - /// Names the agents whose reply the caller actually hears. - /// The loaded document. - /// The entry being compiled. - /// - /// The agents.items ids that answer the caller, or when the last - /// thing the run produced is the answer. - /// - internal virtual HashSet? SpokenAuthors(AgentCoreConfiguration configuration, EntryConfiguration entry) => null; + /// Names the agents whose reply the caller actually hears. + /// The loaded document. + /// The entry being compiled. + /// + /// The agents.items ids that answer the caller, or when the last + /// thing the run produced is the answer. + /// + internal virtual HashSet? SpokenAuthors(AgentCoreConfiguration configuration, EntryConfiguration entry) + { + return null; + } - private protected static Dictionary NoStages() => new(StringComparer.Ordinal); + private protected static Dictionary NoStages() + { + return new(StringComparer.Ordinal); + } + } } diff --git a/src/AgentCore.Application/Configuration/Compilation/CompiledAgent.cs b/src/AgentCore.Application/Configuration/Compilation/CompiledAgent.cs index dfd5e469..a6638381 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompiledAgent.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompiledAgent.cs @@ -5,159 +5,157 @@ using AgentCore.Application.Transcript; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// One entry, compiled to the row that it selected. -/// -public sealed class CompiledAgent +namespace AgentCore.Application.Configuration.Compilation { - private readonly CompiledDocument _document; + /// + /// One entry, compiled to the row that it selected. + /// + public sealed class CompiledAgent + { + private readonly CompiledDocument _document; - private readonly CompileTableRow _row; + private readonly CompileTableRow _row; - private readonly EntryBuild _build; + private readonly EntryBuild _build; - private readonly CompiledAgentSet _agents; + private readonly CompiledAgentSet _agents; - private readonly TurnLayers _layers; + private readonly TurnLayers _layers; - private readonly Dictionary _turnByAgentId; + private readonly Dictionary _turnByAgentId; - /// Compiles one entry: its row's build, with the turn layers on every agent a turn runs. - /// Every part of the entry, complete. - internal CompiledAgent(CompiledAgentBuilder builder) - { - _document = builder.Document; - EntryName = builder.EntryName; - Policy = builder.Policy; - _row = builder.Row; - _build = builder.Entry; - _agents = builder.Agents; - _layers = builder.Layers; - - TurnAgent = _layers.Apply(_build.Agent); - _turnByAgentId = new Dictionary(StringComparer.Ordinal); - - foreach (var (id, agent) in _agents.Agents) + /// Compiles one entry: its row's build, with the turn layers on every agent a turn runs. + /// Every part of the entry, complete. + internal CompiledAgent(CompiledAgentBuilder builder) { - _turnByAgentId[id] = _layers.Apply(agent); + _document = builder.Document; + EntryName = builder.EntryName; + Policy = builder.Policy; + _row = builder.Row; + _build = builder.Entry; + _agents = builder.Agents; + _layers = builder.Layers; + + TurnAgent = _layers.Apply(_build.Agent); + _turnByAgentId = new Dictionary(StringComparer.Ordinal); + + foreach ((string? id, AIAgent? agent) in _agents.Agents) + { + _turnByAgentId[id] = _layers.Apply(agent); + } } - } - /// - /// Gets whether the row answers its runs out of store 1 on its own session, rather than the - /// request messages. - /// - internal bool SessionCarriesHistory => _row.SessionCarriesHistory; + /// + /// Gets whether the row answers its runs out of store 1 on its own session, rather than the + /// request messages. + /// + internal bool SessionCarriesHistory => _row.SessionCarriesHistory; - /// Gets the document this agent was compiled from. - public AgentCoreConfiguration Configuration => _document.Configuration; + /// Gets the document this agent was compiled from. + public AgentCoreConfiguration Configuration => _document.Configuration; - /// Gets the entry key this agent was compiled from. It is the agent's name. - internal string EntryName { get; } + /// Gets the entry key this agent was compiled from. It is the agent's name. + internal string EntryName { get; } - /// Gets this entry's stage machine, or when the entry holds none. - public PolicyConfiguration? Policy { get; } + /// Gets this entry's stage machine, or when the entry holds none. + public PolicyConfiguration? Policy { get; } - /// Gets the resolved line the caller hears when a turn fails. - public string FallbackReply => _layers.FallbackReply; + /// Gets the resolved line the caller hears when a turn fails. + public string FallbackReply => _layers.FallbackReply; - /// Gets the resolved line the caller hears when the agent refuses to answer. - internal string RefusalReply => _layers.RefusalReply; + /// Gets the resolved line the caller hears when the agent refuses to answer. + internal string RefusalReply => _layers.RefusalReply; - /// Gets the row of the compile table this entry selected. - internal CompiledAgentShape Shape => _row.Shape; + /// Gets the row of the compile table this entry selected. + internal CompiledAgentShape Shape => _row.Shape; - /// Gets the name of the entry. - public string Name => EntryName; + /// Gets the name of the entry. + public string Name => EntryName; - /// - /// Gets the agent a turn runs. - /// - public AIAgent Agent => _build.Agent; + /// + /// Gets the agent a turn runs. + /// + public AIAgent Agent => _build.Agent; - /// - /// Gets the agents whose reply the caller hears, or for all of them. - /// - internal IReadOnlySet? SpokenBy => _layers.SpokenBy; + /// + /// Gets the agents whose reply the caller hears, or for all of them. + /// + internal IReadOnlySet? SpokenBy => _layers.SpokenBy; - /// - /// Gets store 1 of every conversation this agent answers. - /// - internal AgentCoreChatHistoryProvider History => _document.History; + /// + /// Gets store 1 of every conversation this agent answers. + /// + internal AgentCoreChatHistoryProvider History => _document.History; - /// Gets the store this agent's conversations and every word of them are kept in. - internal IConversationStore ConversationStore => _document.Conversations; - - /// - /// Gets the union of every harness provider's state keys, over every agent this document - /// compiled — never the history provider's key. Empty when the document names no harness - /// switch. This is what a conversation's Providers keeps beside its stage and its slots. - /// - internal IReadOnlySet HarnessStateKeys => _agents.HarnessStateKeys; + /// Gets the store this agent's conversations and every word of them are kept in. + internal IConversationStore ConversationStore => _document.Conversations; + + /// + /// Gets the union of every harness provider's state keys, over every agent this document + /// compiled — never the history provider's key. Empty when the document names no harness + /// switch. This is what a conversation's Providers keeps beside its stage and its slots. + /// + internal IReadOnlySet HarnessStateKeys => _agents.HarnessStateKeys; #pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. - /// - /// Gets every background provider this document compiled, over every agent. The conversation releases - /// each one's session when it ends, so children still running cannot outlive it. - /// - internal IReadOnlyList BackgroundProviders => _agents.BackgroundProviders; + /// + /// Gets every background provider this document compiled, over every agent. The conversation releases + /// each one's session when it ends, so children still running cannot outlive it. + /// + internal IReadOnlyList BackgroundProviders => _agents.BackgroundProviders; #pragma warning restore MAAI001 - /// - /// Gets the agent a turn runs, with the turn-disposition layers on it. - /// - internal AIAgent TurnAgent { get; } - - /// - /// Gets every compiled agent, keyed by the agents.items id. - /// - public IReadOnlyDictionary Agents => _agents.Agents; - - /// Gets the agent one stage names. - /// The stage id. - /// The agent, or when the stage names none. - /// The stage is not declared. - public AIAgent? ForStage(string stageId) - { - ArgumentNullException.ThrowIfNull(stageId); - - if (!_build.Stages.TryGetValue(stageId, out var agentId)) + /// + /// Gets the agent a turn runs, with the turn-disposition layers on it. + /// + internal AIAgent TurnAgent { get; } + + /// + /// Gets every compiled agent, keyed by the agents.items id. + /// + public IReadOnlyDictionary Agents => _agents.Agents; + + /// Gets the agent one stage names. + /// The stage id. + /// The agent, or when the stage names none. + /// The stage is not declared. + public AIAgent? ForStage(string stageId) { - throw new KeyNotFoundException($"The stage '{stageId}' is not declared in policy.stages."); + ArgumentNullException.ThrowIfNull(stageId); + + return _build.Stages.GetValueOrDefault(stageId) switch + { + null => throw new KeyNotFoundException($"The stage '{stageId}' is not declared in policy.stages."), + "" => null, + string agentId => _agents.Agents[agentId], + }; } - return agentId.Length == 0 ? null : _agents.Agents[agentId]; - } - - /// Gets the agent one stage names, with the turn-disposition layers on it. - /// The stage id. - /// The agent, or when the stage names none. - /// The stage is not declared. - internal AIAgent? TurnAgentForStage(string stageId) - { - ArgumentNullException.ThrowIfNull(stageId); - - if (!_build.Stages.TryGetValue(stageId, out var agentId)) + /// Gets the agent one stage names, with the turn-disposition layers on it. + /// The stage id. + /// The agent, or when the stage names none. + /// The stage is not declared. + internal AIAgent? TurnAgentForStage(string stageId) { - throw new KeyNotFoundException($"The stage '{stageId}' is not declared in policy.stages."); + ArgumentNullException.ThrowIfNull(stageId); + + return _build.Stages.GetValueOrDefault(stageId) switch + { + null => throw new KeyNotFoundException($"The stage '{stageId}' is not declared in policy.stages."), + "" => null, + string agentId => _turnByAgentId[agentId], + }; } - return agentId.Length == 0 ? null : _turnByAgentId[agentId]; - } - - /// Builds one stage machine for one conversation. - /// The evaluator that runs each exit guard. - /// The machine, in the initial stage. - public StagePolicy CreatePolicy(IGuardEvaluator guards) - { - if (Policy is not { } policy) + /// Builds one stage machine for one conversation. + /// The evaluator that runs each exit guard. + /// The machine, in the initial stage. + public StagePolicy CreatePolicy(IGuardEvaluator guards) { - throw new InvalidOperationException( - $"The entry '{EntryName}' declares no policy, so it has no stage machine."); + return Policy is not { } policy + ? throw new InvalidOperationException( + $"The entry '{EntryName}' declares no policy, so it has no stage machine.") + : new StagePolicy(policy, guards); } - - return new StagePolicy(policy, guards); } } diff --git a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentBuilder.cs b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentBuilder.cs index cc64474b..b885b0e5 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentBuilder.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentBuilder.cs @@ -1,41 +1,42 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Collects what one entry compiles from, then builds the once every -/// part is present. required makes the compiler enforce completeness, so a new part is one -/// property here and one on the record that owns it; the constructor never grows. -/// -internal sealed class CompiledAgentBuilder +namespace AgentCore.Application.Configuration.Compilation { - /// Gets what every entry of the document shares. - public required CompiledDocument Document { get; init; } + /// + /// Collects what one entry compiles from, then builds the once every + /// part is present. required makes the compiler enforce completeness, so a new part is one + /// property here and one on the record that owns it; the constructor never grows. + /// + internal sealed class CompiledAgentBuilder + { + /// Gets what every entry of the document shares. + public required CompiledDocument Document { get; init; } - /// Gets the entry key. It is the agent's name. - public required string EntryName { get; init; } + /// Gets the entry key. It is the agent's name. + public required string EntryName { get; init; } - /// Gets the entry's stage machine, or when it holds none. - public PolicyConfiguration? Policy { get; init; } + /// Gets the entry's stage machine, or when it holds none. + public PolicyConfiguration? Policy { get; init; } - /// Gets the row of the compile table the entry selected. - public required CompileTableRow Row { get; init; } + /// Gets the row of the compile table the entry selected. + public required CompileTableRow Row { get; init; } - /// Gets what the row built for the entry. - public required EntryBuild Entry { get; init; } + /// Gets what the row built for the entry. + public required EntryBuild Entry { get; init; } - /// Gets the agents.items entries the row built on. - public required CompiledAgentSet Agents { get; init; } + /// Gets the agents.items entries the row built on. + public required CompiledAgentSet Agents { get; init; } - /// Gets the turn layers of the entry. - public required TurnLayers Layers { get; init; } + /// Gets the turn layers of the entry. + public required TurnLayers Layers { get; init; } - /// Builds the agent, putting the turn layers on every agent a turn runs. - /// The compiled entry. - public CompiledAgent Build() - { - ArgumentException.ThrowIfNullOrEmpty(EntryName); + /// Builds the agent, putting the turn layers on every agent a turn runs. + /// The compiled entry. + public CompiledAgent Build() + { + ArgumentException.ThrowIfNullOrEmpty(EntryName); - return new CompiledAgent(this); + return new CompiledAgent(this); + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentRegistry.cs b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentRegistry.cs index 9a45a6af..304e96c1 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentRegistry.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentRegistry.cs @@ -1,114 +1,115 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Holds each compiled entry for the life of the process. -/// -public sealed class CompiledAgentRegistry +namespace AgentCore.Application.Configuration.Compilation { - internal readonly record struct EntryKey(AgentCoreConfiguration Configuration, string Entry); + /// + /// Holds each compiled entry for the life of the process. + /// + public sealed class CompiledAgentRegistry + { + internal readonly record struct EntryKey(AgentCoreConfiguration Configuration, string Entry); - private readonly Dictionary _compiled = []; + private readonly Dictionary _compiled = []; - private readonly Lock _gate = new(); - - private int _compileCount; + private readonly Lock _gate = new(); - /// Gets how many entries this registry has compiled. - public int CompileCount - { - get + private int _compileCount; + + /// Gets how many entries this registry has compiled. + public int CompileCount { - lock (_gate) + get { - return _compileCount; + lock (_gate) + { + return _compileCount; + } } } - } - - /// Gets the compiled agent for one entry, compiling it the first time only. - /// The loaded document. - /// The entry key. - /// The seams the document names. It is read on the first call only. - /// The one compiled agent for that entry. - /// The entry name is not declared. - public CompiledAgent GetOrCompile( - AgentCoreConfiguration configuration, - string entryName, - AgentCompilationContext context) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(entryName); - ArgumentNullException.ThrowIfNull(context); - lock (_gate) + /// Gets the compiled agent for one entry, compiling it the first time only. + /// The loaded document. + /// The entry key. + /// The seams the document names. It is read on the first call only. + /// The one compiled agent for that entry. + /// The entry name is not declared. + public CompiledAgent GetOrCompile( + AgentCoreConfiguration configuration, + string entryName, + AgentCompilationContext context) { - ThrowWhenUnknownEntry(configuration, entryName); + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(entryName); + ArgumentNullException.ThrowIfNull(context); - var key = new EntryKey(configuration, entryName); - if (_compiled.TryGetValue(key, out var existing)) + lock (_gate) { - return existing; - } + ThrowWhenUnknownEntry(configuration, entryName); - // The compile runs inside the lock, so 26 simultaneous callers still compile once. - CacheAllLocked(configuration, context); - return _compiled[key]; - } - } + EntryKey key = new(configuration, entryName); + if (_compiled.TryGetValue(key, out CompiledAgent? existing)) + { + return existing; + } - /// Compiles every entry of one document, so boot fails fast on a bad entry. - /// The loaded document. - /// The seams the document names. It is read on the first call only. - /// The compiled agents, keyed by entry name. - public IReadOnlyDictionary EnsureAll( - AgentCoreConfiguration configuration, - AgentCompilationContext context) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(context); + // The compile runs inside the lock, so 26 simultaneous callers still compile once. + CacheAllLocked(configuration, context); + return _compiled[key]; + } + } - lock (_gate) + /// Compiles every entry of one document, so boot fails fast on a bad entry. + /// The loaded document. + /// The seams the document names. It is read on the first call only. + /// The compiled agents, keyed by entry name. + public IReadOnlyDictionary EnsureAll( + AgentCoreConfiguration configuration, + AgentCompilationContext context) { - CacheAllLocked(configuration, context); + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(context); - Dictionary compiled = new(StringComparer.Ordinal); - foreach (var name in configuration.Entries.Keys) + lock (_gate) { - compiled[name] = _compiled[new EntryKey(configuration, name)]; - } + CacheAllLocked(configuration, context); - return compiled; - } - } + Dictionary compiled = new(StringComparer.Ordinal); + foreach (string name in configuration.Entries.Keys) + { + compiled[name] = _compiled[new EntryKey(configuration, name)]; + } - private void CacheAllLocked(AgentCoreConfiguration configuration, AgentCompilationContext context) - { - var missing = configuration.Entries.Keys.Any(name => !_compiled.ContainsKey(new EntryKey(configuration, name))); - if (!missing) - { - return; + return compiled; + } } - var compiled = ConfigurationCompiler.CompileAll(configuration, context); - foreach (var (name, agent) in compiled) + private void CacheAllLocked(AgentCoreConfiguration configuration, AgentCompilationContext context) { - if (_compiled.TryAdd(new EntryKey(configuration, name), agent)) + bool missing = configuration.Entries.Keys.Any(name => !_compiled.ContainsKey(new EntryKey(configuration, name))); + if (!missing) { - _compileCount++; + return; + } + + IReadOnlyDictionary compiled = ConfigurationCompiler.CompileAll(configuration, context); + foreach ((string? name, CompiledAgent? agent) in compiled) + { + if (_compiled.TryAdd(new EntryKey(configuration, name), agent)) + { + _compileCount++; + } } } - } - private static void ThrowWhenUnknownEntry(AgentCoreConfiguration configuration, string entryName) - { - if (!configuration.Entries.ContainsKey(entryName)) + private static void ThrowWhenUnknownEntry(AgentCoreConfiguration configuration, string entryName) { - throw ConfigurationCompiler.Fail( - "/entries", - $"the entry '{entryName}' is not declared. Valid entries: {string.Join(", ", configuration.Entries.Keys)}."); + if (!configuration.Entries.ContainsKey(entryName)) + { + throw ConfigurationCompiler.Fail( + "/entries", + $"the entry '{entryName}' is not declared. Valid entries: {string.Join(", ", configuration.Entries.Keys)}."); + } } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentSet.cs b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentSet.cs index 0c108f2c..0c5e4287 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentSet.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentSet.cs @@ -1,14 +1,15 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - +namespace AgentCore.Application.Configuration.Compilation +{ #pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. -/// The agents.items entries one build produced, and what every one of them declared. -/// The compiled agents, keyed by id. -/// The union of every harness provider's state keys. Never the history provider's key. -/// Every background provider, for the conversation-end release. -internal sealed record CompiledAgentSet( - Dictionary Agents, - IReadOnlySet HarnessStateKeys, - IReadOnlyList BackgroundProviders); + /// The agents.items entries one build produced, and what every one of them declared. + /// The compiled agents, keyed by id. + /// The union of every harness provider's state keys. Never the history provider's key. + /// Every background provider, for the conversation-end release. + internal sealed record CompiledAgentSet( + Dictionary Agents, + IReadOnlySet HarnessStateKeys, + IReadOnlyList BackgroundProviders); #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentShape.cs b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentShape.cs index 1383a1ed..32eee655 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompiledAgentShape.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompiledAgentShape.cs @@ -1,19 +1,20 @@ -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// The row of the compile table in section 8.2 that one entry selects. -/// -public enum CompiledAgentShape +namespace AgentCore.Application.Configuration.Compilation { - /// The entry holds agent:. It builds a ChatClientAgent. - SingleAgent, + /// + /// The row of the compile table in section 8.2 that one entry selects. + /// + public enum CompiledAgentShape + { + /// The entry holds agent:. It builds a ChatClientAgent. + SingleAgent, - /// The entry holds policy:. The machine picks a stage each turn, and the stage names one agent. - Policy, + /// The entry holds policy:. The machine picks a stage each turn, and the stage names one agent. + Policy, - /// The entry holds graph: with pattern:. It builds one of the four AgentWorkflowBuilder shapes. - PatternGraph, + /// The entry holds graph: with pattern:. It builds one of the four AgentWorkflowBuilder shapes. + PatternGraph, - /// The entry holds graph: with nodes: and edges:. It builds a WorkflowBuilder graph. - ExplicitGraph, + /// The entry holds graph: with nodes: and edges:. It builds a WorkflowBuilder graph. + ExplicitGraph, + } } diff --git a/src/AgentCore.Application/Configuration/Compilation/CompiledDocument.cs b/src/AgentCore.Application/Configuration/Compilation/CompiledDocument.cs index 87fb4370..2f6144e6 100644 --- a/src/AgentCore.Application/Configuration/Compilation/CompiledDocument.cs +++ b/src/AgentCore.Application/Configuration/Compilation/CompiledDocument.cs @@ -2,13 +2,14 @@ using AgentCore.Application.Ports; using AgentCore.Application.Transcript; -namespace AgentCore.Application.Configuration.Compilation; - -/// What every entry of one document shares once compiled. -/// The loaded document. -/// The store every conversation and every word of it is kept in. -/// Store 1, over . -internal sealed record CompiledDocument( - AgentCoreConfiguration Configuration, - IConversationStore Conversations, - AgentCoreChatHistoryProvider History); +namespace AgentCore.Application.Configuration.Compilation +{ + /// What every entry of one document shares once compiled. + /// The loaded document. + /// The store every conversation and every word of it is kept in. + /// Store 1, over . + internal sealed record CompiledDocument( + AgentCoreConfiguration Configuration, + IConversationStore Conversations, + AgentCoreChatHistoryProvider History); +} diff --git a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs index ea0b1fa2..54b04bc5 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs @@ -7,277 +7,260 @@ using AgentCore.Application.Transcript; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// The compile table of section 8.2. It is a table, not a heuristic. -/// -public static class ConfigurationCompiler +namespace AgentCore.Application.Configuration.Compilation { - /// Picks the row of the compile table one entry selects. - /// The entry being compiled. - /// The JSON Pointer to the entry, /entries/<name>. - /// The row. - /// The entry selects no row, or selects two. - internal static CompileTableRow SelectEntryRow(EntryConfiguration entry, string entryPointer) + /// + /// The compile table of section 8.2. It is a table, not a heuristic. + /// + public static class ConfigurationCompiler { - ArgumentNullException.ThrowIfNull(entry); - ArgumentException.ThrowIfNullOrEmpty(entryPointer); - - var hasAgent = entry.Agent is not null; - var hasPolicy = entry.Policy is not null; - var hasGraph = entry.Graph is not null; - var selected = (hasAgent ? 1 : 0) + (hasPolicy ? 1 : 0) + (hasGraph ? 1 : 0); - - if (selected > 1) + /// Picks the row of the compile table one entry selects. + /// The entry being compiled. + /// The JSON Pointer to the entry, /entries/<name>. + /// The row. + /// The entry selects no row, or selects two. + internal static CompileTableRow SelectEntryRow(EntryConfiguration entry, string entryPointer) { - throw Fail( - entryPointer, - "the entry holds two of agent:, policy:, and graph:. The section 8.2 compile table " - + "takes exactly one: agent: for one agent answering directly, policy: for a conversation that " - + "walks stages, and graph: for a run that needs checkpointing, a request port, or a " - + "parallel fan-out with a join."); - } + ArgumentNullException.ThrowIfNull(entry); + ArgumentException.ThrowIfNullOrEmpty(entryPointer); - if (hasGraph) - { - return SelectGraphRow(entry.Graph!, ConfigurationError.AppendPointer(entryPointer, "graph")); - } + bool hasAgent = entry.Agent is not null; + bool hasPolicy = entry.Policy is not null; + bool hasGraph = entry.Graph is not null; + int selected = (hasAgent ? 1 : 0) + (hasPolicy ? 1 : 0) + (hasGraph ? 1 : 0); - if (hasPolicy) - { - return PolicyRow.Instance; - } + if (selected > 1) + { + throw Fail( + entryPointer, + "the entry holds two of agent:, policy:, and graph:. The section 8.2 compile table " + + "takes exactly one: agent: for one agent answering directly, policy: for a conversation that " + + "walks stages, and graph: for a run that needs checkpointing, a request port, or a " + + "parallel fan-out with a join."); + } - if (hasAgent) - { - return SelectSingleAgentRow(entry.Agent!, ConfigurationError.AppendPointer(entryPointer, "agent")); + return (hasGraph, hasPolicy, hasAgent) switch + { + (true, _, _) => SelectGraphRow(entry.Graph!, ConfigurationError.AppendPointer(entryPointer, "graph")), + (_, true, _) => PolicyRow.Instance, + (_, _, true) => SelectSingleAgentRow(entry.Agent!, ConfigurationError.AppendPointer(entryPointer, "agent")), + _ => throw Fail( + entryPointer, + "the entry holds none of agent:, policy:, and graph:, so it compiles to nothing."), + }; } - throw Fail( - entryPointer, - "the entry holds none of agent:, policy:, and graph:, so it compiles to nothing."); - } - - /// Picks the graph row: pattern: or nodes: and edges:, never both, never neither. - private static CompileTableRow SelectGraphRow(GraphConfiguration graph, string graphPointer) - { - var hasPattern = graph.Pattern is not null; - var hasNodes = graph.Nodes.Count > 0 || graph.Edges.Count > 0; - - if (hasPattern && hasNodes) + /// Picks the graph row: pattern: or nodes: and edges:, never both, never neither. + private static CompileTableRow SelectGraphRow(GraphConfiguration graph, string graphPointer) { - throw Fail(graphPointer, "the graph holds both pattern: and nodes:. It holds one or the other."); - } + bool hasPattern = graph.Pattern is not null; + bool hasNodes = graph.Nodes.Count > 0 || graph.Edges.Count > 0; - if (hasPattern) - { - return PatternGraphRow.Instance; + return (hasPattern, hasNodes) switch + { + (true, true) => throw Fail(graphPointer, "the graph holds both pattern: and nodes:. It holds one or the other."), + (true, false) => PatternGraphRow.Instance, + (false, true) => ExplicitGraphRow.Instance, + (false, false) => throw Fail(graphPointer, "the graph declares neither pattern: nor nodes: and edges:."), + }; } - if (hasNodes) + /// Picks the single-agent row, once agent: names an id. + private static SingleAgentRow SelectSingleAgentRow(string agentId, string agentPointer) { - return ExplicitGraphRow.Instance; + return agentId.Length == 0 + ? throw Fail(agentPointer, "the entry holds an empty agent:. It names one agents.items id.") + : SingleAgentRow.Instance; } - throw Fail(graphPointer, "the graph declares neither pattern: nor nodes: and edges:."); - } - - /// Picks the single-agent row, once agent: names an id. - private static SingleAgentRow SelectSingleAgentRow(string agentId, string agentPointer) - { - if (agentId.Length == 0) + /// Compiles one document into one agent per entry. + /// The loaded document. + /// The seams the document names. + /// The compiled agents, keyed by entry name. Each is a process singleton: see T44. + /// An entry does not compile. + public static IReadOnlyDictionary CompileAll( + AgentCoreConfiguration configuration, + AgentCompilationContext context) { - throw Fail(agentPointer, "the entry holds an empty agent:. It names one agents.items id."); - } - - return SingleAgentRow.Instance; - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(context); - /// Compiles one document into one agent per entry. - /// The loaded document. - /// The seams the document names. - /// The compiled agents, keyed by entry name. Each is a process singleton: see T44. - /// An entry does not compile. - public static IReadOnlyDictionary CompileAll( - AgentCoreConfiguration configuration, - AgentCompilationContext context) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(context); + IConversationStore conversations = context.ConversationStore ?? new InMemoryConversationStore(); + CompiledDocument document = new(configuration, conversations, new AgentCoreChatHistoryProvider(conversations)); - IConversationStore conversations = context.ConversationStore ?? new InMemoryConversationStore(); - CompiledDocument document = new(configuration, conversations, new AgentCoreChatHistoryProvider(conversations)); + Dictionary built = new(StringComparer.Ordinal); + Dictionary compiled = new(StringComparer.Ordinal); - Dictionary built = new(StringComparer.Ordinal); - Dictionary compiled = new(StringComparer.Ordinal); - - foreach (var (entryName, entry) in configuration.Entries) - { - var entryPointer = ConfigurationError.AppendPointer("/entries", entryName); - var row = SelectEntryRow(entry, entryPointer); - - var shape = row.Shape; - var key = shape == CompiledAgentShape.SingleAgent || shape == CompiledAgentShape.Policy ? "session" : shape.ToString(); - if (!built.TryGetValue(key, out var shared)) + foreach ((string? entryName, EntryConfiguration? entry) in configuration.Entries) { - shared = BuildAgents(configuration, context, row.SessionCarriesHistory ? document.History : null); - built[key] = shared; - } + string entryPointer = ConfigurationError.AppendPointer("/entries", entryName); + CompileTableRow row = SelectEntryRow(entry, entryPointer); - var build = row.BuildEntry(configuration, entryName, entry, entryPointer, shared.Agents, context); - - TurnLayers layers = new( - entry.FallbackReply ?? configuration.FallbackReply, - entry.RefusalReply ?? configuration.RefusalReply, - context.Moderation, - row.SpokenAuthors(configuration, entry)); + CompiledAgentShape shape = row.Shape; + string key = shape is CompiledAgentShape.SingleAgent or CompiledAgentShape.Policy ? "session" : shape.ToString(); + if (!built.TryGetValue(key, out CompiledAgentSet? shared)) + { + shared = BuildAgents(configuration, context, row.SessionCarriesHistory ? document.History : null); + built[key] = shared; + } - compiled[entryName] = new CompiledAgentBuilder - { - Document = document, - EntryName = entryName, - Policy = entry.Policy, - Row = row, - Entry = build, - Agents = shared, - Layers = layers, - }.Build(); - } + EntryBuild build = row.BuildEntry(configuration, entryName, entry, entryPointer, shared.Agents, context); - return compiled; - } + TurnLayers layers = new( + entry.FallbackReply ?? configuration.FallbackReply, + entry.RefusalReply ?? configuration.RefusalReply, + context.Moderation, + row.SpokenAuthors(configuration, entry)); -#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. - /// Builds one ChatClientAgent for each agents.items entry. - /// The loaded document. - /// The seams the document names. - /// Store 1, or to leave the framework default in place. - /// The agents keyed by id, with what every one of them declared. - private static CompiledAgentSet BuildAgents( - AgentCoreConfiguration configuration, - AgentCompilationContext context, - AgentCoreChatHistoryProvider? history) - { - Dictionary agents = new(StringComparer.Ordinal); - HashSet harnessStateKeys = new(StringComparer.Ordinal); - List backgroundProviders = []; - if (configuration.Agents is not { } section) - { - return new CompiledAgentSet(agents, harnessStateKeys, backgroundProviders); - } + compiled[entryName] = new CompiledAgentBuilder + { + Document = document, + EntryName = entryName, + Policy = entry.Policy, + Row = row, + Entry = build, + Agents = shared, + Layers = layers, + }.Build(); + } - Dictionary tools = new(StringComparer.Ordinal); - foreach (var tool in configuration.Tools) - { - tools[tool.Id] = tool; + return compiled; } - Dictionary declaredAt = new(StringComparer.Ordinal); - for (var index = 0; index < section.Items.Count; index++) +#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. + /// Builds one ChatClientAgent for each agents.items entry. + /// The loaded document. + /// The seams the document names. + /// Store 1, or to leave the framework default in place. + /// The agents keyed by id, with what every one of them declared. + private static CompiledAgentSet BuildAgents( + AgentCoreConfiguration configuration, + AgentCompilationContext context, + AgentCoreChatHistoryProvider? history) { - if (!declaredAt.TryAdd(section.Items[index].Id, index)) + Dictionary agents = new(StringComparer.Ordinal); + HashSet harnessStateKeys = new(StringComparer.Ordinal); + List backgroundProviders = []; + if (configuration.Agents is not { } section) { - throw Fail( - ConfigurationError.AppendPointer(ConfigurationError.AppendPointer("/agents/items", index), "id"), - $"the agent id '{section.Items[index].Id}' is declared twice."); + return new CompiledAgentSet(agents, harnessStateKeys, backgroundProviders); } - } - - List path = []; - - AgentsWalk walk = new( - section.Defaults, - ResolvedClarification.From(configuration), - configuration.Providers?.Knowledge?.Scope, - backgroundProviders); - - foreach (var item in section.Items) - { - Resolve(item.Id); - } - - return new CompiledAgentSet(agents, harnessStateKeys, backgroundProviders); - AIAgent? Resolve(string id) - { - if (agents.TryGetValue(id, out var existing)) + Dictionary tools = new(StringComparer.Ordinal); + foreach (ToolConfiguration tool in configuration.Tools) { - return existing; + tools[tool.Id] = tool; } - if (!declaredAt.TryGetValue(id, out var index)) + Dictionary declaredAt = new(StringComparer.Ordinal); + for (int index = 0; index < section.Items.Count; index++) { - return null; + if (!declaredAt.TryAdd(section.Items[index].Id, index)) + { + throw Fail( + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer("/agents/items", index), "id"), + $"the agent id '{section.Items[index].Id}' is declared twice."); + } } - var item = section.Items[index]; - var pointer = ConfigurationError.AppendPointer("/agents/items", index); + List path = []; + + AgentsWalk walk = new( + section.Defaults, + ResolvedClarification.From(configuration), + configuration.Providers?.Knowledge?.Scope, + backgroundProviders); - if (path.Contains(id, StringComparer.Ordinal)) + foreach (AgentConfiguration item in section.Items) { - throw Fail( - pointer, - $"the agent '{id}' delegates back to itself through a kind: agent tool: " - + $"{string.Join(" -> ", path)} -> {id}. Check 8 of section 8.5 rejects a delegation " - + "cycle, because the conversation would never return."); + _ = Resolve(item.Id); } - path.Add(id); + return new CompiledAgentSet(agents, harnessStateKeys, backgroundProviders); - var compiledTools = AgentToolCompiler.Build( - item, item.Model ?? section.Defaults?.Model, tools, context, pointer, Resolve); + AIAgent? Resolve(string id) + { + if (agents.TryGetValue(id, out AIAgent? existing)) + { + return existing; + } - var providers = AgentContextProviderCompiler.Build(walk, item, context, pointer, Resolve, history); - harnessStateKeys.UnionWith(AgentHarnessProviders.StateKeysOf(providers)); + if (!declaredAt.TryGetValue(id, out int index)) + { + return null; + } - harnessStateKeys.UnionWith(AgentApproval.StateKeysFor(section.Defaults, item, compiledTools)); + AgentConfiguration item = section.Items[index]; + string pointer = ConfigurationError.AppendPointer("/agents/items", index); - var built = new ChatClientAgent( - WithToolFailureAuditing(context.ChatClients.GetChatClient(item.Model ?? section.Defaults?.Model)), - new ChatClientAgentOptions + if (path.Contains(id, StringComparer.Ordinal)) { - Name = item.Id, - Description = item.Description, - ChatOptions = new ChatOptions - { - Instructions = AgentInstructions.Compose(section.Defaults, item), - Tools = compiledTools, - }, - ChatHistoryProvider = history, - AIContextProviders = providers, - }); + throw Fail( + pointer, + $"the agent '{id}' delegates back to itself through a kind: agent tool: " + + $"{string.Join(" -> ", path)} -> {id}. Check 8 of section 8.5 rejects a delegation " + + "cycle, because the conversation would never return."); + } - path.RemoveAt(path.Count - 1); + path.Add(id); - var instrumented = new AIAgentBuilder(built) - .UseOpenTelemetry(configure: static agent => agent.EnableSensitiveData = false) - .Build(); + List providers = AgentContextProviderCompiler.Build(walk, item, context, pointer, Resolve, history); + harnessStateKeys.UnionWith(AgentHarnessProviders.StateKeysOf(providers)); - var approved = AgentApproval.Apply(instrumented, section.Defaults, item); - var looped = AgentHarnessProviders.ApplyLoop(approved, section.Defaults, item, pointer); + List? compiledTools = AgentToolCompiler.Build( + item, item.Model ?? section.Defaults?.Model, tools, context, pointer, Resolve); + harnessStateKeys.UnionWith(AgentApproval.StateKeysFor(section.Defaults, item, compiledTools)); - agents[id] = looped; - return looped; + ChatClientAgent built = new( + WithToolFailureAuditing(context.ChatClients.GetChatClient(item.Model ?? section.Defaults?.Model)), + new ChatClientAgentOptions + { + Name = item.Id, + Description = item.Description, + ChatOptions = new ChatOptions + { + Instructions = AgentInstructions.Compose(section.Defaults, item), + Tools = compiledTools, + }, + ChatHistoryProvider = history, + AIContextProviders = providers, + }); + + path.RemoveAt(path.Count - 1); + + AIAgent instrumented = new AIAgentBuilder(built) + .UseOpenTelemetry(configure: static agent => agent.EnableSensitiveData = false) + .Build(); + + AIAgent approved = AgentApproval.Apply(instrumented, section.Defaults, item); + AIAgent looped = AgentHarnessProviders.ApplyLoop(approved, section.Defaults, item, pointer); + + agents[id] = looped; + return looped; + } } - } #pragma warning restore MAAI001 - /// Puts the auditing function-invocation loop into the pipeline of one agent. - private static AuditingFunctionInvokingChatClient WithToolFailureAuditing(IChatClient model) - => new(model.AsBuilder() - .UseOpenTelemetry(configure: static client => client.EnableSensitiveData = false) - .ConfigureOptions(ConversationRequestStamp.Apply) - .Use(static innerClient => new ModelFacingChatClient(innerClient)) - .Build()); + /// Puts the auditing function-invocation loop into the pipeline of one agent. + private static AuditingFunctionInvokingChatClient WithToolFailureAuditing(IChatClient model) + { + return new(model.AsBuilder() + .UseOpenTelemetry(configure: static client => client.EnableSensitiveData = false) + .ConfigureOptions(ConversationRequestStamp.Apply) + .Use(static innerClient => new ModelFacingChatClient(innerClient)) + .Build()); + } - internal static ConfigurationLoadException Fail(string pointer, string message) - => new(new ConfigurationError + internal static ConfigurationLoadException Fail(string pointer, string message) { - Pointer = pointer, - Message = message, + return new(new ConfigurationError + { + Pointer = pointer, + Message = message, - // The compile table is a shape rule over the whole document, like check 1. - Check = ConfigurationCheck.DocumentSchema, - }); + // The compile table is a shape rule over the whole document, like check 1. + Check = ConfigurationCheck.DocumentSchema, + }); + } + } } diff --git a/src/AgentCore.Application/Configuration/Compilation/EntryBuild.cs b/src/AgentCore.Application/Configuration/Compilation/EntryBuild.cs index 6a8187db..280fd601 100644 --- a/src/AgentCore.Application/Configuration/Compilation/EntryBuild.cs +++ b/src/AgentCore.Application/Configuration/Compilation/EntryBuild.cs @@ -1,8 +1,9 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// What one compile-table row built for one entry. -/// The agent a turn runs. -/// The agent id each policy.stages entry names. Empty for a row with no stages. -internal sealed record EntryBuild(AIAgent Agent, Dictionary Stages); +namespace AgentCore.Application.Configuration.Compilation +{ + /// What one compile-table row built for one entry. + /// The agent a turn runs. + /// The agent id each policy.stages entry names. Empty for a row with no stages. + internal sealed record EntryBuild(AIAgent Agent, Dictionary Stages); +} diff --git a/src/AgentCore.Application/Configuration/Compilation/ExplicitGraphRow.cs b/src/AgentCore.Application/Configuration/Compilation/ExplicitGraphRow.cs index bc951a19..95c72655 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ExplicitGraphRow.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ExplicitGraphRow.cs @@ -5,191 +5,195 @@ using Microsoft.Agents.AI; using Microsoft.Agents.AI.Workflows; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Row 4: the entry holds graph: with nodes: and edges:. It builds a -/// WorkflowBuilder, binds the agents as executors, then AsAIAgent(). -/// -internal sealed class ExplicitGraphRow : CompileTableRow +namespace AgentCore.Application.Configuration.Compilation { - internal static readonly ExplicitGraphRow Instance = new(); - - internal override CompiledAgentShape Shape => CompiledAgentShape.ExplicitGraph; - - internal override EntryBuild BuildEntry( - AgentCoreConfiguration configuration, - string entryName, - EntryConfiguration entry, - string entryPointer, - Dictionary agents, - AgentCompilationContext context) + /// + /// Row 4: the entry holds graph: with nodes: and edges:. It builds a + /// WorkflowBuilder, binds the agents as executors, then AsAIAgent(). + /// + internal sealed class ExplicitGraphRow : CompileTableRow { - var graph = entry.Graph!; - var graphPointer = ConfigurationError.AppendPointer(entryPointer, "graph"); - var (nodes, start, outputs) = BindNodes(graph, ConfigurationError.AppendPointer(graphPointer, "nodes"), agents); - - var stateEntry = ExecutorBindingExtensions.BindExecutor(new GraphStateEntry()); + internal static readonly ExplicitGraphRow Instance = new(); - WorkflowBuilder builder = new(stateEntry); - builder = builder.AddEdge(stateEntry, nodes[start]); - var (built, guarded) = AddEdges(builder, graph, ConfigurationError.AppendPointer(graphPointer, "edges"), nodes, context); + internal override CompiledAgentShape Shape => CompiledAgentShape.ExplicitGraph; - if (outputs.Count > 0) + internal override EntryBuild BuildEntry( + AgentCoreConfiguration configuration, + string entryName, + EntryConfiguration entry, + string entryPointer, + Dictionary agents, + AgentCompilationContext context) { - built = built.WithOutputFrom([.. outputs]); - } - - var compiled = built.WithName(entryName) - .Build() - .AsAIAgent(name: entryName); - - AIAgent withOutputCheck = new RequireOutputAgent(compiled, entryName); - - return new EntryBuild( - guarded ? new GraphStateAgent(withOutputCheck, entryName) : withOutputCheck, - NoStages()); - } + GraphConfiguration graph = entry.Graph!; + string graphPointer = ConfigurationError.AppendPointer(entryPointer, "graph"); + (Dictionary? nodes, string? start, List? outputs) = BindNodes(graph, ConfigurationError.AppendPointer(graphPointer, "nodes"), agents); - /// Binds every node to its agent, and finds the one start node. - private static (Dictionary Nodes, string Start, List Outputs) BindNodes( - GraphConfiguration graph, - string nodesPointer, - Dictionary agents) - { - Dictionary nodes = new(StringComparer.Ordinal); - List starts = []; - List outputs = []; + ExecutorBinding stateEntry = ExecutorBindingExtensions.BindExecutor(new GraphStateEntry()); - for (var index = 0; index < graph.Nodes.Count; index++) - { - var node = graph.Nodes[index]; - var binding = BindNode(node, ConfigurationError.AppendPointer(nodesPointer, index), agents, nodes); - nodes[node.Id] = binding; + WorkflowBuilder builder = new(stateEntry); + builder = builder.AddEdge(stateEntry, nodes[start]); + (WorkflowBuilder? built, bool guarded) = AddEdges(builder, graph, ConfigurationError.AppendPointer(graphPointer, "edges"), nodes, context); - if (node.Start) + if (outputs.Count > 0) { - starts.Add(node.Id); + built = built.WithOutputFrom([.. outputs]); } - if (node.Output) - { - outputs.Add(binding); - } + AIAgent compiled = built.WithName(entryName) + .Build() + .AsAIAgent(name: entryName); + + AIAgent withOutputCheck = new RequireOutputAgent(compiled, entryName); + + return new EntryBuild( + guarded ? new GraphStateAgent(withOutputCheck, entryName) : withOutputCheck, + NoStages()); } - if (starts.Count != 1) + /// Binds every node to its agent, and finds the one start node. + private static (Dictionary Nodes, string Start, List Outputs) BindNodes( + GraphConfiguration graph, + string nodesPointer, + Dictionary agents) { - throw ConfigurationCompiler.Fail( - nodesPointer, - $"the graph declares {starts.Count} start nodes. Check 7 of section 8.5 needs exactly one."); - } + Dictionary nodes = new(StringComparer.Ordinal); + List starts = []; + List outputs = []; - return (nodes, starts[0], outputs); - } + for (int index = 0; index < graph.Nodes.Count; index++) + { + GraphNodeConfiguration node = graph.Nodes[index]; + AIAgentBinding binding = BindNode(node, ConfigurationError.AppendPointer(nodesPointer, index), agents, nodes); + nodes[node.Id] = binding; + + if (node.Start) + { + starts.Add(node.Id); + } + + if (node.Output) + { + outputs.Add(binding); + } + } - private static AIAgentBinding BindNode( - GraphNodeConfiguration node, - string pointer, - Dictionary agents, - Dictionary nodes) - { - if (node.Agent is not { } agentId || !agents.TryGetValue(agentId, out var agent)) - { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "agent"), - $"the node '{node.Id}' names no declared agent, so nothing binds as its executor."); + return starts.Count != 1 + ? throw ConfigurationCompiler.Fail( + nodesPointer, + $"the graph declares {starts.Count} start nodes. Check 7 of section 8.5 needs exactly one.") + : ((Dictionary Nodes, string Start, List Outputs))(nodes, starts[0], outputs); } - if (nodes.ContainsKey(node.Id)) + private static AIAgentBinding BindNode( + GraphNodeConfiguration node, + string pointer, + Dictionary agents, + Dictionary nodes) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "id"), - $"the node id '{node.Id}' is declared twice."); - } + if (node.Agent is not { } agentId || !agents.TryGetValue(agentId, out AIAgent? agent)) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "agent"), + $"the node '{node.Id}' names no declared agent, so nothing binds as its executor."); + } - // The measured shape: an agent binds as an executor, and the host emits update events so - // the wrapper can stream. Section 8.6. - return new AIAgentBinding(agent, new AIAgentHostOptions { EmitAgentUpdateEvents = true }); - } + if (nodes.ContainsKey(node.Id)) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "id"), + $"the node id '{node.Id}' is declared twice."); + } - /// Adds every edge, with a gate in front of each guarded one. - /// The builder, and whether any edge carries a guard. - private static (WorkflowBuilder Builder, bool Guarded) AddEdges( - WorkflowBuilder builder, - GraphConfiguration graph, - string edgesPointer, - Dictionary nodes, - AgentCompilationContext context) - { - var guarded = false; + // The measured shape: an agent binds as an executor, and the host emits update events so + // the wrapper can stream. Section 8.6. + return new AIAgentBinding(agent, new AIAgentHostOptions { EmitAgentUpdateEvents = true }); + } - for (var index = 0; index < graph.Edges.Count; index++) + /// Adds every edge, with a gate in front of each guarded one. + /// The builder, and whether any edge carries a guard. + private static (WorkflowBuilder Builder, bool Guarded) AddEdges( + WorkflowBuilder builder, + GraphConfiguration graph, + string edgesPointer, + Dictionary nodes, + AgentCompilationContext context) { - var edge = graph.Edges[index]; - var pointer = ConfigurationError.AppendPointer(edgesPointer, index); - var from = Endpoint(nodes, edge.From, pointer, "from"); - var to = Endpoint(nodes, edge.To, pointer, "to"); + bool guarded = false; - if (edge.When is not { } guard) + for (int index = 0; index < graph.Edges.Count; index++) { - builder = builder.AddEdge(from, to); - continue; + GraphEdgeConfiguration edge = graph.Edges[index]; + string pointer = ConfigurationError.AppendPointer(edgesPointer, index); + ExecutorBinding from = Endpoint(nodes, edge.From, pointer, "from"); + ExecutorBinding to = Endpoint(nodes, edge.To, pointer, "to"); + + if (edge.When is not { } guard) + { + builder = builder.AddEdge(from, to); + continue; + } + + FunctionExecutor gate = Gate(index, guard, Evaluator(context, pointer)); + builder = builder.AddEdge(from, gate); + builder = builder.AddEdge(gate, to); + guarded = true; } - var gate = Gate(index, guard, Evaluator(context, pointer)); - builder = builder.AddEdge(from, gate); - builder = builder.AddEdge(gate, to); - guarded = true; + return (builder, guarded); } - return (builder, guarded); - } + private static ExecutorBinding Endpoint(Dictionary nodes, string id, string pointer, string key) + { + return nodes.TryGetValue(id, out ExecutorBinding? node) + ? node + : throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, key), + $"the node '{id}' is not declared."); + } - private static ExecutorBinding Endpoint(Dictionary nodes, string id, string pointer, string key) - => nodes.TryGetValue(id, out var node) - ? node - : throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, key), - $"the node '{id}' is not declared."); - - private static IGuardEvaluator Evaluator(AgentCompilationContext context, string pointer) - => context.Guards ?? throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(pointer, "when"), - "the edge carries a guard, and the compilation context binds no guard evaluator. Bind " - + "AgentCompilationContext.Guards, which runs the rule. AddAgentCore binds it to " - + "GuardEvaluator. A guarded edge that silently became unconditional is exactly " - + "the silent graph failure section 8.2 refuses to ship."); + private static IGuardEvaluator Evaluator(AgentCompilationContext context, string pointer) + { + return context.Guards ?? throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "when"), + "the edge carries a guard, and the compilation context binds no guard evaluator. Bind " + + "AgentCompilationContext.Guards, which runs the rule. AddAgentCore binds it to " + + "GuardEvaluator. A guarded edge that silently became unconditional is exactly " + + "the silent graph failure section 8.2 refuses to ship."); + } - /// - /// One gate per guarded edge, holding the run until its guard is true. The gate is a - /// workflow executor rather than an edge predicate because the predicate only ever sees - /// the edge message: per-call state reaches the gate through the run, filed by the - /// graph-state entry. object, not List<ChatMessage>: the guard reads state, so every - /// message on the edge takes the same answer and the turn token is not filtered out. - /// - private static FunctionExecutor Gate(int index, GuardReference guard, IGuardEvaluator evaluator) - => new( - $"agentcore-gate-{index}", - (message, gateContext, gateToken) => GraphGuardGate.RouteAsync( - message, gateContext, guard, evaluator, gateToken), - null, - [typeof(object)], - null, - true); - - /// An explicit graph answers from its output: true nodes. - internal override HashSet? SpokenAuthors(AgentCoreConfiguration configuration, EntryConfiguration entry) - { - HashSet outputs = new(StringComparer.Ordinal); - foreach (var node in entry.Graph!.Nodes) + /// + /// One gate per guarded edge, holding the run until its guard is true. The gate is a + /// workflow executor rather than an edge predicate because the predicate only ever sees + /// the edge message: per-call state reaches the gate through the run, filed by the + /// graph-state entry. object, not List<ChatMessage>: the guard reads state, so every + /// message on the edge takes the same answer and the turn token is not filtered out. + /// + private static FunctionExecutor Gate(int index, GuardReference guard, IGuardEvaluator evaluator) { - if (node.Output && node.Agent is { } agentId) + return new( + $"agentcore-gate-{index}", + (message, gateContext, gateToken) => GraphGuardGate.RouteAsync( + message, gateContext, guard, evaluator, gateToken), + null, + [typeof(object)], + null, + true); + } + + /// An explicit graph answers from its output: true nodes. + internal override HashSet? SpokenAuthors(AgentCoreConfiguration configuration, EntryConfiguration entry) + { + HashSet outputs = new(StringComparer.Ordinal); + foreach (GraphNodeConfiguration node in entry.Graph!.Nodes) { - outputs.Add(agentId); + if (node.Output && node.Agent is { } agentId) + { + _ = outputs.Add(agentId); + } } - } - return outputs.Count == 0 ? null : outputs; + return outputs.Count == 0 ? null : outputs; + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/GraphGuardGate.cs b/src/AgentCore.Application/Configuration/Compilation/GraphGuardGate.cs index f58b1f7a..dbed024c 100644 --- a/src/AgentCore.Application/Configuration/Compilation/GraphGuardGate.cs +++ b/src/AgentCore.Application/Configuration/Compilation/GraphGuardGate.cs @@ -3,50 +3,45 @@ using AgentCore.Application.Configuration.Validation; using Microsoft.Agents.AI.Workflows; -namespace AgentCore.Application.Configuration.Compilation; - -internal static class GraphGuardGate +namespace AgentCore.Application.Configuration.Compilation { - /// The reason a gate reports when the run carries no state. - internal const string NoStateMessage = - "A guarded graph edge asked for the state of the running conversation, and the run carries none. " - + "Row 4 of the section 8.2 compile table reads the state of one conversation, and the graph-state " - + "wrapper files it from the turn before the run starts. Run the graph through a ConversationSession, " - + "which files the turn on the run's session. This throws and does not answer false, because " - + "a guarded edge that quietly became unconditional is the silent graph failure section 8.2 " - + "refuses to ship."; - - /// Forwards one edge message past a guarded edge, or holds it when the guard is false. - /// The message that reached the edge, forwarded unchanged. - /// The run the edge belongs to, carrying the filed snapshot. - /// The edge's when: guard. - /// The shared evaluator that runs the rule. - /// Cancels the read. - /// The run carries no state. - internal static async ValueTask RouteAsync( - object? message, - IWorkflowContext context, - GuardReference guard, - IGuardEvaluator evaluator, - CancellationToken cancellationToken) + internal static class GraphGuardGate { - ArgumentNullException.ThrowIfNull(context); - ArgumentNullException.ThrowIfNull(guard); - ArgumentNullException.ThrowIfNull(evaluator); - - var snapshot = await context - .ReadStateAsync>( - GraphStateEntry.SlotsKey, GraphStateEntry.StateScope, cancellationToken) - .ConfigureAwait(false); + /// The reason a gate reports when the run carries no state. + internal const string NoStateMessage = + "A guarded graph edge asked for the state of the running conversation, and the run carries none. " + + "Row 4 of the section 8.2 compile table reads the state of one conversation, and the graph-state " + + "wrapper files it from the turn before the run starts. Run the graph through a ConversationSession, " + + "which files the turn on the run's session. This throws and does not answer false, because " + + "a guarded edge that quietly became unconditional is the silent graph failure section 8.2 " + + "refuses to ship."; - if (snapshot is null) + /// Forwards one edge message past a guarded edge, or holds it when the guard is false. + /// The message that reached the edge, forwarded unchanged. + /// The run the edge belongs to, carrying the filed snapshot. + /// The edge's when: guard. + /// The shared evaluator that runs the rule. + /// Cancels the read. + /// The run carries no state. + internal static async ValueTask RouteAsync( + object? message, + IWorkflowContext context, + GuardReference guard, + IGuardEvaluator evaluator, + CancellationToken cancellationToken) { - throw new InvalidOperationException(NoStateMessage); - } + ArgumentNullException.ThrowIfNull(context); + ArgumentNullException.ThrowIfNull(guard); + ArgumentNullException.ThrowIfNull(evaluator); - if (evaluator.Evaluate(guard, snapshot)) - { - await context.SendMessageAsync(message!, cancellationToken: cancellationToken).ConfigureAwait(false); + IReadOnlyDictionary? snapshot = await context + .ReadStateAsync>( + GraphStateEntry.SlotsKey, GraphStateEntry.StateScope, cancellationToken) + .ConfigureAwait(false) ?? throw new InvalidOperationException(NoStateMessage); + if (evaluator.Evaluate(guard, snapshot)) + { + await context.SendMessageAsync(message!, cancellationToken: cancellationToken).ConfigureAwait(false); + } } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/GraphStateCarrier.cs b/src/AgentCore.Application/Configuration/Compilation/GraphStateCarrier.cs index 72dc7fd8..def8b692 100644 --- a/src/AgentCore.Application/Configuration/Compilation/GraphStateCarrier.cs +++ b/src/AgentCore.Application/Configuration/Compilation/GraphStateCarrier.cs @@ -1,44 +1,45 @@ using System.Text.Json.Nodes; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Configuration.Compilation; - -internal static class GraphStateCarrier +namespace AgentCore.Application.Configuration.Compilation { - /// The message key the snapshot rides under. - internal const string ArgumentsKey = "urn:agentcore:graph-state"; - - /// Builds the carrier heading one run's request messages. - /// Every declared slot and the three reserved slots, read at run start. - /// A content-free message only the graph-state entry reads. - internal static ChatMessage Build(IReadOnlyDictionary snapshot) + internal static class GraphStateCarrier { - ArgumentNullException.ThrowIfNull(snapshot); + /// The message key the snapshot rides under. + internal const string ArgumentsKey = "urn:agentcore:graph-state"; - return new ChatMessage(ChatRole.System, string.Empty) + /// Builds the carrier heading one run's request messages. + /// Every declared slot and the three reserved slots, read at run start. + /// A content-free message only the graph-state entry reads. + internal static ChatMessage Build(IReadOnlyDictionary snapshot) { - AdditionalProperties = new AdditionalPropertiesDictionary { [ArgumentsKey] = snapshot }, - }; - } + ArgumentNullException.ThrowIfNull(snapshot); - /// Takes the snapshot off the head of one run's request, when it carries one. - /// The run's accumulated messages, oldest first. - /// The snapshot, without the carrier around it. - /// Whether a carrier headed the messages. The carrier is removed either way it answers. - internal static bool TryTake(List messages, out IReadOnlyDictionary? snapshot) - { - ArgumentNullException.ThrowIfNull(messages); + return new ChatMessage(ChatRole.System, string.Empty) + { + AdditionalProperties = new AdditionalPropertiesDictionary { [ArgumentsKey] = snapshot }, + }; + } - snapshot = null; - if (messages.Count == 0 - || messages[0].AdditionalProperties?.TryGetValue(ArgumentsKey, out var filed) != true - || filed is not IReadOnlyDictionary carried) + /// Takes the snapshot off the head of one run's request, when it carries one. + /// The run's accumulated messages, oldest first. + /// The snapshot, without the carrier around it. + /// Whether a carrier headed the messages. The carrier is removed either way it answers. + internal static bool TryTake(List messages, out IReadOnlyDictionary? snapshot) { - return false; - } + ArgumentNullException.ThrowIfNull(messages); - messages.RemoveAt(0); - snapshot = carried; - return true; + snapshot = null; + if (messages.Count == 0 + || messages[0].AdditionalProperties?.TryGetValue(ArgumentsKey, out object? filed) != true + || filed is not IReadOnlyDictionary carried) + { + return false; + } + + messages.RemoveAt(0); + snapshot = carried; + return true; + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/GraphStateEntry.cs b/src/AgentCore.Application/Configuration/Compilation/GraphStateEntry.cs index 012b528d..c64f30e4 100644 --- a/src/AgentCore.Application/Configuration/Compilation/GraphStateEntry.cs +++ b/src/AgentCore.Application/Configuration/Compilation/GraphStateEntry.cs @@ -1,39 +1,41 @@ +using System.Text.Json.Nodes; using Microsoft.Agents.AI.Workflows; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Configuration.Compilation; - -internal sealed class GraphStateEntry : ChatProtocolExecutor +namespace AgentCore.Application.Configuration.Compilation { - /// The workflow scope the snapshot is filed under. Named, because the default - /// scope belongs to each executor alone and a gate would read its own empty one. - internal const string StateScope = "graph-state"; - - /// The workflow state key the snapshot is filed under. - internal const string SlotsKey = "slots"; - - /// Creates the entry of one compiled graph. - internal GraphStateEntry() - : base("agentcore-graph-entry", new ChatProtocolExecutorOptions { AutoSendTurnToken = true }, true) + internal sealed class GraphStateEntry : ChatProtocolExecutor { - } + /// The workflow scope the snapshot is filed under. Named, because the default + /// scope belongs to each executor alone and a gate would read its own empty one. + internal const string StateScope = "graph-state"; - /// - protected override async ValueTask TakeTurnAsync( - List messages, - IWorkflowContext context, - bool? emitEvents, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - ArgumentNullException.ThrowIfNull(context); + /// The workflow state key the snapshot is filed under. + internal const string SlotsKey = "slots"; - if (GraphStateCarrier.TryTake(messages, out var snapshot) && snapshot is not null) + /// Creates the entry of one compiled graph. + internal GraphStateEntry() + : base("agentcore-graph-entry", new ChatProtocolExecutorOptions { AutoSendTurnToken = true }, true) { - await context.QueueStateUpdateAsync(SlotsKey, snapshot, StateScope, cancellationToken) - .ConfigureAwait(false); } - await context.SendMessageAsync(messages, cancellationToken: cancellationToken).ConfigureAwait(false); + /// + protected override async ValueTask TakeTurnAsync( + List messages, + IWorkflowContext context, + bool? emitEvents, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + ArgumentNullException.ThrowIfNull(context); + + if (GraphStateCarrier.TryTake(messages, out IReadOnlyDictionary? snapshot) && snapshot is not null) + { + await context.QueueStateUpdateAsync(SlotsKey, snapshot, StateScope, cancellationToken) + .ConfigureAwait(false); + } + + await context.SendMessageAsync(messages, cancellationToken: cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/PatternGraphRow.cs b/src/AgentCore.Application/Configuration/Compilation/PatternGraphRow.cs index 41bb2735..dea68cf7 100644 --- a/src/AgentCore.Application/Configuration/Compilation/PatternGraphRow.cs +++ b/src/AgentCore.Application/Configuration/Compilation/PatternGraphRow.cs @@ -3,88 +3,94 @@ using Microsoft.Agents.AI; using Microsoft.Agents.AI.Workflows; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Row 3: the entry holds graph: with pattern:. It builds -/// AgentWorkflowBuilder.BuildSequential, BuildConcurrent, -/// CreateHandoffBuilderWith, or CreateGroupChatBuilderWith. -/// -internal sealed class PatternGraphRow : CompileTableRow +namespace AgentCore.Application.Configuration.Compilation { - internal static readonly PatternGraphRow Instance = new(); - - internal override CompiledAgentShape Shape => CompiledAgentShape.PatternGraph; - - internal override EntryBuild BuildEntry( - AgentCoreConfiguration configuration, - string entryName, - EntryConfiguration entry, - string entryPointer, - Dictionary agents, - AgentCompilationContext context) + /// + /// Row 3: the entry holds graph: with pattern:. It builds + /// AgentWorkflowBuilder.BuildSequential, BuildConcurrent, + /// CreateHandoffBuilderWith, or CreateGroupChatBuilderWith. + /// + internal sealed class PatternGraphRow : CompileTableRow { - var graph = entry.Graph!; - var graphPointer = ConfigurationError.AppendPointer(entryPointer, "graph"); - var agentsPointer = ConfigurationError.AppendPointer(graphPointer, "agents"); - List participants = []; + internal static readonly PatternGraphRow Instance = new(); - for (var index = 0; index < graph.Agents.Count; index++) + internal override CompiledAgentShape Shape => CompiledAgentShape.PatternGraph; + + internal override EntryBuild BuildEntry( + AgentCoreConfiguration configuration, + string entryName, + EntryConfiguration entry, + string entryPointer, + Dictionary agents, + AgentCompilationContext context) { - var id = graph.Agents[index]; - if (!agents.TryGetValue(id, out var agent)) + GraphConfiguration graph = entry.Graph!; + string graphPointer = ConfigurationError.AppendPointer(entryPointer, "graph"); + string agentsPointer = ConfigurationError.AppendPointer(graphPointer, "agents"); + List participants = []; + + for (int index = 0; index < graph.Agents.Count; index++) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(agentsPointer, index), - $"the graph names the agent '{id}', which agents.items does not declare."); + string id = graph.Agents[index]; + if (!agents.TryGetValue(id, out AIAgent? agent)) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(agentsPointer, index), + $"the graph names the agent '{id}', which agents.items does not declare."); + } + + participants.Add(agent); } - participants.Add(agent); + if (participants.Count == 0) + { + throw ConfigurationCompiler.Fail(agentsPointer, "a pattern graph names no agent."); + } + + Workflow workflow = graph.Pattern switch + { + GraphPattern.Sequential => AgentWorkflowBuilder.BuildSequential(entryName, participants), + GraphPattern.Concurrent => AgentWorkflowBuilder.BuildConcurrent(entryName, participants, aggregator: null), + GraphPattern.Handoff => BuildHandoff(entryName, participants), + GraphPattern.GroupChat => BuildGroupChat(entryName, participants), + _ => throw new ArgumentOutOfRangeException(nameof(entry), graph.Pattern, "The graph pattern vocabulary is closed, and this value is not in it."), + }; + + return new EntryBuild(workflow.AsAIAgent(name: entryName), NoStages()); } - if (participants.Count == 0) + /// + /// A sequential graph answers from its last participant. Concurrent aggregates every + /// participant, and handoff and group chat both end wherever the conversation took them, so on + /// those patterns any participant may legitimately speak last and no filter applies. + /// + internal override HashSet? SpokenAuthors(AgentCoreConfiguration configuration, EntryConfiguration entry) { - throw ConfigurationCompiler.Fail(agentsPointer, "a pattern graph names no agent."); + return entry.Graph is { Pattern: GraphPattern.Sequential, Agents.Count: > 0 } graph + ? new HashSet(StringComparer.Ordinal) { graph.Agents[^1] } + : null; } - var workflow = graph.Pattern switch + private static Workflow BuildHandoff(string name, List participants) { - GraphPattern.Sequential => AgentWorkflowBuilder.BuildSequential(entryName, participants), - GraphPattern.Concurrent => AgentWorkflowBuilder.BuildConcurrent(entryName, participants, aggregator: null), - GraphPattern.Handoff => BuildHandoff(entryName, participants), - _ => BuildGroupChat(entryName, participants), - }; - - return new EntryBuild(workflow.AsAIAgent(name: entryName), NoStages()); - } + AIAgent start = participants[0]; + HandoffWorkflowBuilder builder = AgentWorkflowBuilder.CreateHandoffBuilderWith(start).WithName(name); - /// - /// A sequential graph answers from its last participant. Concurrent aggregates every - /// participant, and handoff and group chat both end wherever the conversation took them, so on - /// those patterns any participant may legitimately speak last and no filter applies. - /// - internal override HashSet? SpokenAuthors(AgentCoreConfiguration configuration, EntryConfiguration entry) - => entry.Graph is { Pattern: GraphPattern.Sequential, Agents.Count: > 0 } graph - ? new HashSet(StringComparer.Ordinal) { graph.Agents[^1] } - : null; + if (participants.Count > 1) + { + builder = builder.WithHandoffs(start, participants.Skip(1)); + } - private static Workflow BuildHandoff(string name, List participants) - { - var start = participants[0]; - var builder = AgentWorkflowBuilder.CreateHandoffBuilderWith(start).WithName(name); + return builder.Build(); + } - if (participants.Count > 1) + private static Workflow BuildGroupChat(string name, List participants) { - builder = builder.WithHandoffs(start, participants.Skip(1)); + return AgentWorkflowBuilder + .CreateGroupChatBuilderWith(members => new RoundRobinGroupChatManager(members)) + .AddParticipants(participants) + .WithName(name) + .Build(); } - - return builder.Build(); } - - private static Workflow BuildGroupChat(string name, List participants) - => AgentWorkflowBuilder - .CreateGroupChatBuilderWith(members => new RoundRobinGroupChatManager(members)) - .AddParticipants(participants) - .WithName(name) - .Build(); } diff --git a/src/AgentCore.Application/Configuration/Compilation/PolicyRow.cs b/src/AgentCore.Application/Configuration/Compilation/PolicyRow.cs index 422d6932..6b02680d 100644 --- a/src/AgentCore.Application/Configuration/Compilation/PolicyRow.cs +++ b/src/AgentCore.Application/Configuration/Compilation/PolicyRow.cs @@ -2,71 +2,67 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Row 2: the entry holds policy:. The machine picks a stage each turn, the stage names -/// one agent, and that agent's run answers the caller. Runtime is Stateless. -/// -internal sealed class PolicyRow : CompileTableRow +namespace AgentCore.Application.Configuration.Compilation { - internal static readonly PolicyRow Instance = new(); - - /// A stage that names no agent. CompiledAgent.ForStage reads the same sentinel. - private const string NoAgentId = ""; + /// + /// Row 2: the entry holds policy:. The machine picks a stage each turn, the stage names + /// one agent, and that agent's run answers the caller. Runtime is Stateless. + /// + internal sealed class PolicyRow : CompileTableRow + { + internal static readonly PolicyRow Instance = new(); - internal override CompiledAgentShape Shape => CompiledAgentShape.Policy; + /// A stage that names no agent. CompiledAgent.ForStage reads the same sentinel. + private const string NoAgentId = ""; - internal override bool SessionCarriesHistory => true; + internal override CompiledAgentShape Shape => CompiledAgentShape.Policy; - internal override EntryBuild BuildEntry( - AgentCoreConfiguration configuration, - string entryName, - EntryConfiguration entry, - string entryPointer, - Dictionary agents, - AgentCompilationContext context) - { - var policy = entry.Policy!; - var policyPointer = ConfigurationError.AppendPointer(entryPointer, "policy"); - var initialPointer = ConfigurationError.AppendPointer(policyPointer, "initial"); - Dictionary stages = new(StringComparer.Ordinal); + internal override bool SessionCarriesHistory => true; - for (var index = 0; index < policy.Stages.Count; index++) + internal override EntryBuild BuildEntry( + AgentCoreConfiguration configuration, + string entryName, + EntryConfiguration entry, + string entryPointer, + Dictionary agents, + AgentCompilationContext context) { - var stage = policy.Stages[index]; - var stagePointer = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(policyPointer, "stages"), index); - if (stage.Agent is not { } agentId) - { - stages[stage.Id] = NoAgentId; - continue; - } + PolicyConfiguration policy = entry.Policy!; + string policyPointer = ConfigurationError.AppendPointer(entryPointer, "policy"); + string initialPointer = ConfigurationError.AppendPointer(policyPointer, "initial"); + Dictionary stages = new(StringComparer.Ordinal); - if (!agents.ContainsKey(agentId)) + for (int index = 0; index < policy.Stages.Count; index++) { - throw ConfigurationCompiler.Fail( - ConfigurationError.AppendPointer(stagePointer, "agent"), - $"the stage '{stage.Id}' names the agent '{agentId}', which agents.items does not declare."); - } + StageConfiguration stage = policy.Stages[index]; + string stagePointer = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(policyPointer, "stages"), index); + if (stage.Agent is not { } agentId) + { + stages[stage.Id] = NoAgentId; + continue; + } - stages[stage.Id] = agentId; - } + if (!agents.ContainsKey(agentId)) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(stagePointer, "agent"), + $"the stage '{stage.Id}' names the agent '{agentId}', which agents.items does not declare."); + } - if (!stages.TryGetValue(policy.Initial, out var initialAgent)) - { - throw ConfigurationCompiler.Fail( - initialPointer, - $"the initial stage '{policy.Initial}' is not declared in policy.stages."); - } + stages[stage.Id] = agentId; + } - if (initialAgent.Length == 0) - { - throw ConfigurationCompiler.Fail( - initialPointer, - $"the initial stage '{policy.Initial}' names no agent, so no turn can run."); + return stages.GetValueOrDefault(policy.Initial) switch + { + null => throw ConfigurationCompiler.Fail( + initialPointer, + $"the initial stage '{policy.Initial}' is not declared in policy.stages."), + "" => throw ConfigurationCompiler.Fail( + initialPointer, + $"the initial stage '{policy.Initial}' names no agent, so no turn can run."), + string initialAgent => new EntryBuild(agents[initialAgent], stages), + }; } - - return new EntryBuild(agents[initialAgent], stages); } } diff --git a/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs b/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs index 68e7ceed..bc3cdc58 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs @@ -2,100 +2,101 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// The document-level ambiguity wiring the knowledge probe needs (§8), read once from -/// providers.knowledge and the declared state: slots. -/// -/// -/// The same for every agent, so builds it once rather than -/// letting each agent re-derive it. -/// -public sealed record ResolvedClarification +namespace AgentCore.Application.Configuration.Compilation { - /// The wiring of a document that configures no ambiguity: nothing to probe, nothing to ask. - public static readonly ResolvedClarification None = new(); - /// - /// Gets how the knowledge search asks the caller which value they meant, or - /// when providers.knowledge.ambiguity is absent — neither the probe nor the clarification - /// ever runs. - /// - public KnowledgeAmbiguityConfiguration? Ambiguity { get; init; } - - /// - /// Gets the providers.knowledge.scope.fromState slots, in declaration order, or empty when - /// the document names none. - /// - public IReadOnlyList FromState { get; init; } = []; - - /// - /// Gets each slot's description, keyed by slot name. + /// The document-level ambiguity wiring the knowledge probe needs (§8), read once from + /// providers.knowledge and the declared state: slots. /// /// - /// Every slot has a key here. The value is both - /// where state: declares that slot without a description and where it declares no - /// such slot at all; readers fall back to the slot name for either. + /// The same for every agent, so builds it once rather than + /// letting each agent re-derive it. /// - public IReadOnlyDictionary SlotDescriptions { get; init; } = - ReadOnlyDictionary.Empty; + public sealed record ResolvedClarification + { + /// The wiring of a document that configures no ambiguity: nothing to probe, nothing to ask. + public static readonly ResolvedClarification None = new(); - /// - /// Gets the payload value that satisfies any scope on a wildcard facet, or - /// when providers.knowledge.scope.wildcard is absent. - /// - public string? WildcardValue { get; init; } + /// + /// Gets how the knowledge search asks the caller which value they meant, or + /// when providers.knowledge.ambiguity is absent — neither the probe nor the clarification + /// ever runs. + /// + public KnowledgeAmbiguityConfiguration? Ambiguity { get; init; } - /// - /// Gets the facet keys widens, or empty when - /// providers.knowledge.scope.wildcard is absent. - /// - public IReadOnlyList WildcardFacets { get; init; } = []; + /// + /// Gets the providers.knowledge.scope.fromState slots, in declaration order, or empty when + /// the document names none. + /// + public IReadOnlyList FromState { get; init; } = []; - /// - /// Gets the payload path each facet key becomes, or when - /// providers.knowledge.scope.template is absent. - /// - /// - /// The probe walks the resolved path to read a dropped facet's value off a returned card's - /// Extras (§8 step 5). Boot and the store resolve their own paths from the same document - /// value through , which owns the one resolution rule. - /// - public ScopeTemplate? Template { get; init; } + /// + /// Gets each slot's description, keyed by slot name. + /// + /// + /// Every slot has a key here. The value is both + /// where state: declares that slot without a description and where it declares no + /// such slot at all; readers fall back to the slot name for either. + /// + public IReadOnlyDictionary SlotDescriptions { get; init; } = + ReadOnlyDictionary.Empty; - /// Reads the wiring out of one bound document. - /// The bound document. - /// The wiring, or when the document configures no knowledge scope. - /// is . - public static ResolvedClarification From(AgentCoreConfiguration configuration) - { - ArgumentNullException.ThrowIfNull(configuration); + /// + /// Gets the payload value that satisfies any scope on a wildcard facet, or + /// when providers.knowledge.scope.wildcard is absent. + /// + public string? WildcardValue { get; init; } - var knowledge = configuration.Providers?.Knowledge; - if (knowledge is null) - { - return None; - } + /// + /// Gets the facet keys widens, or empty when + /// providers.knowledge.scope.wildcard is absent. + /// + public IReadOnlyList WildcardFacets { get; init; } = []; - var fromState = knowledge.Scope.FromState; + /// + /// Gets the payload path each facet key becomes, or when + /// providers.knowledge.scope.template is absent. + /// + /// + /// The probe walks the resolved path to read a dropped facet's value off a returned card's + /// Extras (§8 step 5). Boot and the store resolve their own paths from the same document + /// value through , which owns the one resolution rule. + /// + public ScopeTemplate? Template { get; init; } - Dictionary descriptions = new(StringComparer.Ordinal); - foreach (var slot in fromState) + /// Reads the wiring out of one bound document. + /// The bound document. + /// The wiring, or when the document configures no knowledge scope. + /// is . + public static ResolvedClarification From(AgentCoreConfiguration configuration) { - descriptions[slot] = configuration.State.TryGetValue(slot, out var declared) - ? declared.Description - : null; - } + ArgumentNullException.ThrowIfNull(configuration); - return new ResolvedClarification - { - Ambiguity = knowledge.Ambiguity, - FromState = fromState, - SlotDescriptions = descriptions, - WildcardValue = knowledge.Scope.Wildcard?.Value, - WildcardFacets = knowledge.Scope.Wildcard?.Facets ?? [], - Template = ScopeTemplate.Parse(knowledge.Scope.Template), - }; + KnowledgeProviderConfiguration? knowledge = configuration.Providers?.Knowledge; + if (knowledge is null) + { + return None; + } + + IReadOnlyList fromState = knowledge.Scope.FromState; + + Dictionary descriptions = new(StringComparer.Ordinal); + foreach (string slot in fromState) + { + descriptions[slot] = configuration.State.TryGetValue(slot, out StateSlotConfiguration? declared) + ? declared.Description + : null; + } + + return new ResolvedClarification + { + Ambiguity = knowledge.Ambiguity, + FromState = fromState, + SlotDescriptions = descriptions, + WildcardValue = knowledge.Scope.Wildcard?.Value, + WildcardFacets = knowledge.Scope.Wildcard?.Facets ?? [], + Template = ScopeTemplate.Parse(knowledge.Scope.Template), + }; + } } } diff --git a/src/AgentCore.Application/Configuration/Compilation/SingleAgentRow.cs b/src/AgentCore.Application/Configuration/Compilation/SingleAgentRow.cs index da1b7041..3fdcf3a2 100644 --- a/src/AgentCore.Application/Configuration/Compilation/SingleAgentRow.cs +++ b/src/AgentCore.Application/Configuration/Compilation/SingleAgentRow.cs @@ -2,44 +2,40 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// -/// Row 1: the entry holds agent:. The named agents.items entry is the -/// entry, and its run's own last message is the reply. -/// -internal sealed class SingleAgentRow : CompileTableRow +namespace AgentCore.Application.Configuration.Compilation { - internal static readonly SingleAgentRow Instance = new(); - - internal override CompiledAgentShape Shape => CompiledAgentShape.SingleAgent; - - internal override bool SessionCarriesHistory => true; - - internal override EntryBuild BuildEntry( - AgentCoreConfiguration configuration, - string entryName, - EntryConfiguration entry, - string entryPointer, - Dictionary agents, - AgentCompilationContext context) + /// + /// Row 1: the entry holds agent:. The named agents.items entry is the + /// entry, and its run's own last message is the reply. + /// + internal sealed class SingleAgentRow : CompileTableRow { - var agentPointer = ConfigurationError.AppendPointer(entryPointer, "agent"); + internal static readonly SingleAgentRow Instance = new(); - if (entry.Agent is not { Length: > 0 } agentId) - { - throw ConfigurationCompiler.Fail( - agentPointer, - $"the entry '{entryName}' names no agent, so nothing runs."); - } + internal override CompiledAgentShape Shape => CompiledAgentShape.SingleAgent; - if (!agents.TryGetValue(agentId, out var agent)) + internal override bool SessionCarriesHistory => true; + + internal override EntryBuild BuildEntry( + AgentCoreConfiguration configuration, + string entryName, + EntryConfiguration entry, + string entryPointer, + Dictionary agents, + AgentCompilationContext context) { - throw ConfigurationCompiler.Fail( - agentPointer, - $"the entry '{entryName}' names the agent '{agentId}', which agents.items does not declare."); + string agentPointer = ConfigurationError.AppendPointer(entryPointer, "agent"); + + return entry.Agent switch + { + not { Length: > 0 } => throw ConfigurationCompiler.Fail( + agentPointer, + $"the entry '{entryName}' names no agent, so nothing runs."), + string agentId when agents.TryGetValue(agentId, out AIAgent? agent) => new EntryBuild(agent, NoStages()), + string agentId => throw ConfigurationCompiler.Fail( + agentPointer, + $"the entry '{entryName}' names the agent '{agentId}', which agents.items does not declare."), + }; } - - return new EntryBuild(agent, NoStages()); } } diff --git a/src/AgentCore.Application/Configuration/Compilation/TurnLayers.cs b/src/AgentCore.Application/Configuration/Compilation/TurnLayers.cs index d844953e..1cc232b2 100644 --- a/src/AgentCore.Application/Configuration/Compilation/TurnLayers.cs +++ b/src/AgentCore.Application/Configuration/Compilation/TurnLayers.cs @@ -2,28 +2,29 @@ using AgentCore.Application.Runtime; using Microsoft.Agents.AI; -namespace AgentCore.Application.Configuration.Compilation; - -/// The two turn-disposition layers one entry puts on every agent a turn runs. -/// The resolved line the caller hears when a turn fails. -/// The resolved line the caller hears when the agent refuses to answer. -/// The endpoint seam, or to moderate nothing. -/// The agents whose reply the caller hears, or for all. -internal sealed record TurnLayers( - string FallbackReply, - string RefusalReply, - PromptModerator? Moderation, - IReadOnlySet? SpokenBy) +namespace AgentCore.Application.Configuration.Compilation { - /// Puts the layers on one agent. - /// The compiled agent of one entry, or of one policy: stage. - /// The agent the turn loop runs. - public AIAgent Apply(AIAgent agent) + /// The two turn-disposition layers one entry puts on every agent a turn runs. + /// The resolved line the caller hears when a turn fails. + /// The resolved line the caller hears when the agent refuses to answer. + /// The endpoint seam, or to moderate nothing. + /// The agents whose reply the caller hears, or for all. + internal sealed record TurnLayers( + string FallbackReply, + string RefusalReply, + PromptModerator? Moderation, + IReadOnlySet? SpokenBy) { - AIAgent layered = new FallbackAgent(agent, FallbackReply, SpokenBy); + /// Puts the layers on one agent. + /// The compiled agent of one entry, or of one policy: stage. + /// The agent the turn loop runs. + public AIAgent Apply(AIAgent agent) + { + AIAgent layered = new FallbackAgent(agent, FallbackReply, SpokenBy); - return Moderation is null - ? layered - : new ModerationAgent(layered, Moderation, RefusalReply, ModerationAgent.DefaultTimeout); + return Moderation is null + ? layered + : new ModerationAgent(layered, Moderation, RefusalReply, ModerationAgent.DefaultTimeout); + } } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationBinder.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationBinder.cs index fb75fa29..595adfde 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationBinder.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationBinder.cs @@ -5,166 +5,171 @@ using System.Text.RegularExpressions; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// The second stage of the pipeline in section 6: to records. -/// -/// -/// -/// Check 1 runs before this, so the shape is already known good and this stage only moves values -/// across. does the moving, against the settings in -/// . What is left here is turning a reader failure back into the -/// section 8.7 form: one error carrying a JSON Pointer into the document. -/// -/// -/// Every failure still carries a pointer, because a hand-built node tree may reach the binder -/// without the check. For a document that came through these -/// branches are unreachable: check 1 rejects the same inputs first, and says more about them. -/// -/// -internal static partial class ConfigurationBinder +namespace AgentCore.Application.Configuration.Parsing { - internal static AgentCoreConfiguration Bind(JsonNode document) + /// + /// The second stage of the pipeline in section 6: to records. + /// + /// + /// + /// Check 1 runs before this, so the shape is already known good and this stage only moves values + /// across. does the moving, against the settings in + /// . What is left here is turning a reader failure back into the + /// section 8.7 form: one error carrying a JSON Pointer into the document. + /// + /// + /// Every failure still carries a pointer, because a hand-built node tree may reach the binder + /// without the check. For a document that came through these + /// branches are unreachable: check 1 rejects the same inputs first, and says more about them. + /// + /// + internal static partial class ConfigurationBinder { - ArgumentNullException.ThrowIfNull(document); - - try - { - return document.Deserialize(ConfigurationJson.Options) - ?? throw Error(ConfigurationError.RootPointer, "the document is empty"); - } - catch (JsonException exception) + internal static AgentCoreConfiguration Bind(JsonNode document) { - throw Error(Pointer(exception.Path), Explain(exception.Message), exception); - } - } + ArgumentNullException.ThrowIfNull(document); - /// Turns the reader's $.a.b[0] path into the RFC 6901 pointer /a/b/0. - /// The path the reader reported, or when it reported none. - /// The pointer to the part of the document that failed. - internal static string Pointer(string? path) - { - if (string.IsNullOrEmpty(path) || path[0] != '$') - { - return ConfigurationError.RootPointer; + try + { + return document.Deserialize(ConfigurationJson.Options) + ?? throw Error(ConfigurationError.RootPointer, "the document is empty"); + } + catch (JsonException exception) + { + throw Error(Pointer(exception.Path), Explain(exception.Message), exception); + } } - var pointer = new StringBuilder(); - var index = 1; - while (index < path.Length) + /// Turns the reader's $.a.b[0] path into the RFC 6901 pointer /a/b/0. + /// The path the reader reported, or when it reported none. + /// The pointer to the part of the document that failed. + internal static string Pointer(string? path) { - switch (path[index]) + if (string.IsNullOrEmpty(path) || path[0] != '$') { - case '.': - // A plain property: everything up to the next separator. - index++; - var stop = path.AsSpan(index).IndexOfAny('.', '['); - var end = stop < 0 ? path.Length : index + stop; - Append(pointer, path[index..end]); - index = end; - break; - - case '[' when index + 1 < path.Length && path[index + 1] == '\'': - // A property the reader had to quote, because it holds a separator of its own. - var close = path.IndexOf("']", index + 2, StringComparison.Ordinal); - if (close < 0) - { - return pointer.ToString(); - } - - Append(pointer, path[(index + 2)..close]); - index = close + 2; - break; + return ConfigurationError.RootPointer; + } - case '[': - // An array index. - var bracket = path.IndexOf(']', index + 1); - if (bracket < 0) - { + StringBuilder pointer = new(); + int index = 1; + while (index < path.Length) + { + switch (path[index]) + { + case '.': + // A plain property: everything up to the next separator. + index++; + int stop = path.AsSpan(index).IndexOfAny('.', '['); + int end = stop < 0 ? path.Length : index + stop; + Append(pointer, path[index..end]); + index = end; + break; + + case '[' when index + 1 < path.Length && path[index + 1] == '\'': + // A property the reader had to quote, because it holds a separator of its own. + int close = path.IndexOf("']", index + 2, StringComparison.Ordinal); + if (close < 0) + { + return pointer.ToString(); + } + + Append(pointer, path[(index + 2)..close]); + index = close + 2; + break; + + case '[': + // An array index. + int bracket = path.IndexOf(']', index + 1); + if (bracket < 0) + { + return pointer.ToString(); + } + + Append(pointer, path[(index + 1)..bracket]); + index = bracket + 1; + break; + + default: return pointer.ToString(); - } + } + } - Append(pointer, path[(index + 1)..bracket]); - index = bracket + 1; - break; + return pointer.ToString(); - default: - return pointer.ToString(); + static void Append(StringBuilder pointer, string segment) + { + _ = pointer.Append(ConfigurationError.AppendPointer(string.Empty, segment)); } } - return pointer.ToString(); + /// Rewrites the reader's message as one the author of a document can act on. + /// The message the reader wrote. + /// The message the error carries. + /// + /// The reader names CLR types and repeats the path it already reported through + /// . Both are noise to whoever wrote the document, so the tail is + /// cut and the four kinds of value a configuration document can hold are named the way the + /// schema names them. A message this does not recognise is passed through, so nothing is lost. + /// + internal static string Explain(string message) + { + // The reader appends " Path: $.a.b | LineNumber: 0 | BytePositionInLine: 12." to its own + // messages and to any a converter throws. The pointer already says where. + int tail = message.IndexOf(" Path: $", StringComparison.Ordinal); + if (tail >= 0) + { + message = message[..tail]; + } - static void Append(StringBuilder pointer, string segment) - => pointer.Append(ConfigurationError.AppendPointer(string.Empty, segment)); - } + if (MissingPropertiesPattern().Match(message) is { Success: true } missing) + { + string[] names = missing.Groups[1].Value + .Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries); - /// Rewrites the reader's message as one the author of a document can act on. - /// The message the reader wrote. - /// The message the error carries. - /// - /// The reader names CLR types and repeats the path it already reported through - /// . Both are noise to whoever wrote the document, so the tail is - /// cut and the four kinds of value a configuration document can hold are named the way the - /// schema names them. A message this does not recognise is passed through, so nothing is lost. - /// - internal static string Explain(string message) - { - // The reader appends " Path: $.a.b | LineNumber: 0 | BytePositionInLine: 12." to its own - // messages and to any a converter throws. The pointer already says where. - var tail = message.IndexOf(" Path: $", StringComparison.Ordinal); - if (tail >= 0) - { - message = message[..tail]; - } + return names.Length == 1 + ? $"the required property {names[0]} is missing" + : $"the required properties {string.Join(", ", names)} are missing"; + } - if (MissingPropertiesPattern().Match(message) is { Success: true } missing) - { - var names = missing.Groups[1].Value - .Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries); + if (WrongTypePattern().Match(message) is { Success: true } wrong) + { + // An optional key is a Nullable, and the author of the document only cares about T. + string type = NullableTypePattern().Match(wrong.Groups[1].Value) is { Success: true } wrapped + ? wrapped.Groups[1].Value + : wrong.Groups[1].Value; + + return type switch + { + "System.String" => "a string is expected", + "System.Boolean" => "a boolean is expected", + "System.Int32" or "System.Int64" => "a whole number is expected", + "System.Double" or "System.Decimal" or "System.Single" => "a number is expected", + _ => string.Create(CultureInfo.InvariantCulture, $"the value does not fit a '{type}'"), + }; + } - return names.Length == 1 - ? $"the required property {names[0]} is missing" - : $"the required properties {string.Join(", ", names)} are missing"; + return message; } - if (WrongTypePattern().Match(message) is { Success: true } wrong) + private static ConfigurationLoadException Error(string pointer, string message, Exception? cause = null) { - // An optional key is a Nullable, and the author of the document only cares about T. - var type = NullableTypePattern().Match(wrong.Groups[1].Value) is { Success: true } wrapped - ? wrapped.Groups[1].Value - : wrong.Groups[1].Value; - - return type switch - { - "System.String" => "a string is expected", - "System.Boolean" => "a boolean is expected", - "System.Int32" or "System.Int64" => "a whole number is expected", - "System.Double" or "System.Decimal" or "System.Single" => "a number is expected", - _ => string.Create(CultureInfo.InvariantCulture, $"the value does not fit a '{type}'"), - }; + return new( + new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.DocumentSchema, + }, + cause); } - return message; - } - - private static ConfigurationLoadException Error(string pointer, string message, Exception? cause = null) - => new( - new ConfigurationError - { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.DocumentSchema, - }, - cause); + [GeneratedRegex(@"was missing required properties,? including: (.+?)\.?$")] + private static partial Regex MissingPropertiesPattern(); - [GeneratedRegex(@"was missing required properties,? including: (.+?)\.?$")] - private static partial Regex MissingPropertiesPattern(); + [GeneratedRegex(@"^The JSON value could not be converted to (.+?)\.?$")] + private static partial Regex WrongTypePattern(); - [GeneratedRegex(@"^The JSON value could not be converted to (.+?)\.?$")] - private static partial Regex WrongTypePattern(); - - [GeneratedRegex(@"^System\.Nullable`1\[(.+)\]$")] - private static partial Regex NullableTypePattern(); + [GeneratedRegex(@"^System\.Nullable`1\[(.+)\]$")] + private static partial Regex NullableTypePattern(); + } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs index 8d269b71..61dc124f 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs @@ -1,42 +1,43 @@ -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// The load-time check that rejected a document. The numbers are the rows of the table in section 8.5, -/// except , which that table has no row for. -/// -public enum ConfigurationCheck +namespace AgentCore.Application.Configuration.Parsing { - /// The document is not well-formed YAML or JSON. This runs before check 1. - Syntax = 0, + /// + /// The load-time check that rejected a document. The numbers are the rows of the table in section 8.5, + /// except , which that table has no row for. + /// + public enum ConfigurationCheck + { + /// The document is not well-formed YAML or JSON. This runs before check 1. + Syntax = 0, - /// Check 1: JSON Schema over the document. It fails on any shape error. - DocumentSchema = 1, + /// Check 1: JSON Schema over the document. It fails on any shape error. + DocumentSchema = 1, - /// Check 2: reference resolution. It fails on an unknown agent, tool, guard, stage, or state slot. - ReferenceResolution = 2, + /// Check 2: reference resolution. It fails on an unknown agent, tool, guard, stage, or state slot. + ReferenceResolution = 2, - /// Check 3: one writer for each slot. It fails on zero writers, or two. - SlotWriters = 3, + /// Check 3: one writer for each slot. It fails on zero writers, or two. + SlotWriters = 3, - /// Check 4: guard operators and variables. - GuardOperators = 4, + /// Check 4: guard operators and variables. + GuardOperators = 4, - /// Check 5: exclusivity and coverage by evaluation. - GuardExclusivity = 5, + /// Check 5: exclusivity and coverage by evaluation. + GuardExclusivity = 5, - /// Check 6: reachability of every stage and node. - Reachability = 6, + /// Check 6: reachability of every stage and node. + Reachability = 6, - /// Check 7: graph well-formedness. - GraphWellFormedness = 7, + /// Check 7: graph well-formedness. + GraphWellFormedness = 7, - /// Check 8: delegation cycles through an agent-as-tool loop. - DelegationCycles = 8, + /// Check 8: delegation cycles through an agent-as-tool loop. + DelegationCycles = 8, - /// - /// Check 9: a configured count or interval outside the range the runtime accepts. It exists so a - /// value that a timer or a cancellation source would throw on is refused at load, where the error - /// still carries a pointer into the document. - /// - ValueRange = 9, + /// + /// Check 9: a configured count or interval outside the range the runtime accepts. It exists so a + /// value that a timer or a cancellation source would throw on is refused at load, where the error + /// still carries a pointer into the document. + /// + ValueRange = 9, + } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationError.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationError.cs index fadc3c93..693814bd 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationError.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationError.cs @@ -1,50 +1,53 @@ -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// One reason a configuration document did not load. -/// -/// -/// Section 8.7: loading fails fast, and every message carries a JSON Pointer into the document. -/// All eight checks of section 8.5 report through this record. -/// -public sealed record ConfigurationError +namespace AgentCore.Application.Configuration.Parsing { - /// The JSON Pointer to the whole document. - public const string RootPointer = ""; - - /// Gets the RFC 6901 JSON Pointer to the part of the document that failed. - public required string Pointer { get; init; } - - /// Gets the message a human reads. It does not repeat the pointer. - public required string Message { get; init; } - - /// Gets the check that produced the error. - public required ConfigurationCheck Check { get; init; } - - /// Writes the pointer and the message on one line. - /// The text the exception message holds. - public override string ToString() - => $"{(Pointer.Length == 0 ? "/" : Pointer)}: {Message} (check {(int)Check})"; - - /// Escapes one JSON Pointer segment, then appends it to a pointer. - /// The pointer to extend. - /// The raw property name or array index. - /// The extended pointer. - public static string AppendPointer(string pointer, string segment) - { - ArgumentNullException.ThrowIfNull(pointer); - ArgumentNullException.ThrowIfNull(segment); - - return pointer + "/" + segment.Replace("~", "~0", StringComparison.Ordinal).Replace("/", "~1", StringComparison.Ordinal); - } - - /// Appends an array index to a pointer. - /// The pointer to extend. - /// The zero-based index. - /// The extended pointer. - public static string AppendPointer(string pointer, int index) + /// + /// One reason a configuration document did not load. + /// + /// + /// Section 8.7: loading fails fast, and every message carries a JSON Pointer into the document. + /// All eight checks of section 8.5 report through this record. + /// + public sealed record ConfigurationError { - ArgumentNullException.ThrowIfNull(pointer); - return pointer + "/" + index.ToString(System.Globalization.CultureInfo.InvariantCulture); + /// The JSON Pointer to the whole document. + public const string RootPointer = ""; + + /// Gets the RFC 6901 JSON Pointer to the part of the document that failed. + public required string Pointer { get; init; } + + /// Gets the message a human reads. It does not repeat the pointer. + public required string Message { get; init; } + + /// Gets the check that produced the error. + public required ConfigurationCheck Check { get; init; } + + /// Writes the pointer and the message on one line. + /// The text the exception message holds. + public override string ToString() + { + return $"{(Pointer.Length == 0 ? "/" : Pointer)}: {Message} (check {(int)Check})"; + } + + /// Escapes one JSON Pointer segment, then appends it to a pointer. + /// The pointer to extend. + /// The raw property name or array index. + /// The extended pointer. + public static string AppendPointer(string pointer, string segment) + { + ArgumentNullException.ThrowIfNull(pointer); + ArgumentNullException.ThrowIfNull(segment); + + return pointer + "/" + segment.Replace("~", "~0", StringComparison.Ordinal).Replace("/", "~1", StringComparison.Ordinal); + } + + /// Appends an array index to a pointer. + /// The pointer to extend. + /// The zero-based index. + /// The extended pointer. + public static string AppendPointer(string pointer, int index) + { + ArgumentNullException.ThrowIfNull(pointer); + return pointer + "/" + index.ToString(System.Globalization.CultureInfo.InvariantCulture); + } } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationJson.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationJson.cs index ac0e8b41..81c096ae 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationJson.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationJson.cs @@ -3,153 +3,156 @@ using System.Text.Json.Serialization; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// The reader settings that turn a checked document into the records of section 6. -/// -/// -/// -/// Check 1 of section 8.5 runs immediately before this and rejects every shape error, so the reader -/// is asked only to move values across, never to validate them. The converters below exist because -/// document values are written as strings, or as one of two interchangeable shapes, and modelled as -/// something richer: a tool result path, a secret template, a guard reference, and an MCP -/// allow: entry. -/// -/// -/// The settings are deliberately strict where a default would be lax. Property names match -/// case-sensitively, because apiversion: is not a key the schema accepts and silently binding -/// it would let a document pass check 1 by one spelling and bind by another. Numbers are not read -/// from strings, because "0.5" is a string in both YAML and JSON and the schema types the key -/// as a number. Unknown keys are skipped rather than refused, which matches the binder this -/// replaced: check 1's additionalProperties: false is what rejects them, and it has already -/// run. -/// -/// -internal static class ConfigurationJson +namespace AgentCore.Application.Configuration.Parsing { - /// Gets the settings the binder reads a document with. - internal static JsonSerializerOptions Options { get; } = new() + /// + /// The reader settings that turn a checked document into the records of section 6. + /// + /// + /// + /// Check 1 of section 8.5 runs immediately before this and rejects every shape error, so the reader + /// is asked only to move values across, never to validate them. The converters below exist because + /// document values are written as strings, or as one of two interchangeable shapes, and modelled as + /// something richer: a tool result path, a secret template, a guard reference, and an MCP + /// allow: entry. + /// + /// + /// The settings are deliberately strict where a default would be lax. Property names match + /// case-sensitively, because apiversion: is not a key the schema accepts and silently binding + /// it would let a document pass check 1 by one spelling and bind by another. Numbers are not read + /// from strings, because "0.5" is a string in both YAML and JSON and the schema types the key + /// as a number. Unknown keys are skipped rather than refused, which matches the binder this + /// replaced: check 1's additionalProperties: false is what rejects them, and it has already + /// run. + /// + /// + internal static class ConfigurationJson { - // Every key in agentcore/v1 is camelCase, and every record property is the PascalCase of it. - // The two exceptions carry a [JsonPropertyName]: state slot `enum` and telemetry - // `exportIntervalMs`. - PropertyNamingPolicy = JsonNamingPolicy.CamelCase, - PropertyNameCaseInsensitive = false, - NumberHandling = JsonNumberHandling.Strict, - UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip, - Converters = + /// Gets the settings the binder reads a document with. + internal static JsonSerializerOptions Options { get; } = new() { - // Every enum in the document is written snake_case: `after_reply`, `group_chat`, and the - // single-word ones such as `builtin`. Integers are refused, because no document may - // write an enum as its ordinal. - new JsonStringEnumConverter(JsonNamingPolicy.SnakeCaseLower, allowIntegerValues: false), - new ToolResultReferenceConverter(), - new SecretTemplateConverter(), - new GuardReferenceConverter(), - new McpAllowEntryConverter(), - }, - }; -} + // Every key in agentcore/v1 is camelCase, and every record property is the PascalCase of it. + // The two exceptions carry a [JsonPropertyName]: state slot `enum` and telemetry + // `exportIntervalMs`. + PropertyNamingPolicy = JsonNamingPolicy.CamelCase, + PropertyNameCaseInsensitive = false, + NumberHandling = JsonNumberHandling.Strict, + UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip, + Converters = + { + // Every enum in the document is written snake_case: `after_reply`, `group_chat`, and the + // single-word ones such as `builtin`. Integers are refused, because no document may + // write an enum as its ordinal. + new JsonStringEnumConverter(JsonNamingPolicy.SnakeCaseLower, allowIntegerValues: false), + new ToolResultReferenceConverter(), + new SecretTemplateConverter(), + new GuardReferenceConverter(), + new McpAllowEntryConverter(), + }, + }; + } -/// -/// Reads a from: value, as in lookup_order.status. -/// -/// -/// Check 1 already holds the value to the pattern ^[^.\s]+\.[^\s]+$, which is stricter than -/// . The failure branch is kept for a hand-built tree that -/// reached the binder without the check. -/// -internal sealed class ToolResultReferenceConverter : JsonConverter -{ - /// - public override ToolResultReference Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) + /// + /// Reads a from: value, as in lookup_order.status. + /// + /// + /// Check 1 already holds the value to the pattern ^[^.\s]+\.[^\s]+$, which is stricter than + /// . The failure branch is kept for a hand-built tree that + /// reached the binder without the check. + /// + internal sealed class ToolResultReferenceConverter : JsonConverter { - if (reader.TokenType != JsonTokenType.String) + /// + public override ToolResultReference Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { - throw new JsonException("a string is expected"); + if (reader.TokenType != JsonTokenType.String) + { + throw new JsonException("a string is expected"); + } + + string? text = reader.GetString(); + return ToolResultReference.TryParse(text, out ToolResultReference? reference) + ? reference + : throw new JsonException($"'{text}' is not a tool result path. The form is toolId.path."); } - var text = reader.GetString(); - return ToolResultReference.TryParse(text, out var reference) - ? reference - : throw new JsonException($"'{text}' is not a tool result path. The form is toolId.path."); + /// + public override void Write(Utf8JsonWriter writer, ToolResultReference value, JsonSerializerOptions options) + { + ArgumentNullException.ThrowIfNull(writer); + ArgumentNullException.ThrowIfNull(value); + writer.WriteStringValue(value.ToString()); + } } - /// - public override void Write(Utf8JsonWriter writer, ToolResultReference value, JsonSerializerOptions options) + /// + /// Reads a configuration string that may hold ${secret:name} references. + /// + /// + /// resolves nothing and rejects nothing: text with no reference + /// in it is a template with no reference in it. So this converter has one failure of its own, a + /// value that is not a string at all. + /// + internal sealed class SecretTemplateConverter : JsonConverter { - ArgumentNullException.ThrowIfNull(writer); - ArgumentNullException.ThrowIfNull(value); - writer.WriteStringValue(value.ToString()); - } -} - -/// -/// Reads a configuration string that may hold ${secret:name} references. -/// -/// -/// resolves nothing and rejects nothing: text with no reference -/// in it is a template with no reference in it. So this converter has one failure of its own, a -/// value that is not a string at all. -/// -internal sealed class SecretTemplateConverter : JsonConverter -{ - /// - public override SecretTemplate Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) - => reader.TokenType == JsonTokenType.String - ? SecretTemplate.Parse(reader.GetString()!) - : throw new JsonException("a string is expected"); + /// + public override SecretTemplate Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) + { + return reader.TokenType == JsonTokenType.String + ? SecretTemplate.Parse(reader.GetString()!) + : throw new JsonException("a string is expected"); + } - /// - public override void Write(Utf8JsonWriter writer, SecretTemplate value, JsonSerializerOptions options) - { - ArgumentNullException.ThrowIfNull(writer); - ArgumentNullException.ThrowIfNull(value); - writer.WriteStringValue(value.Raw); + /// + public override void Write(Utf8JsonWriter writer, SecretTemplate value, JsonSerializerOptions options) + { + ArgumentNullException.ThrowIfNull(writer); + ArgumentNullException.ThrowIfNull(value); + writer.WriteStringValue(value.Raw); + } } -} -/// -/// Reads a when: value: a guard name, or an inline JSONLogic rule. -/// -/// -/// Section 8.4 prefers the name. A string is read as a name and anything else as a rule, which is -/// the rule the document schema types as #/$defs/rule. An empty string is neither: it names -/// no guard, and check 2 would report it as an unknown guard called nothing at all, so it is refused -/// here with a message that says what happened. -/// -internal sealed class GuardReferenceConverter : JsonConverter -{ - /// - public override GuardReference Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) + /// + /// Reads a when: value: a guard name, or an inline JSONLogic rule. + /// + /// + /// Section 8.4 prefers the name. A string is read as a name and anything else as a rule, which is + /// the rule the document schema types as #/$defs/rule. An empty string is neither: it names + /// no guard, and check 2 would report it as an unknown guard called nothing at all, so it is refused + /// here with a message that says what happened. + /// + internal sealed class GuardReferenceConverter : JsonConverter { - if (reader.TokenType == JsonTokenType.String) + /// + public override GuardReference Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { - var name = reader.GetString(); - return string.IsNullOrEmpty(name) - ? throw new JsonException("the guard name holds no text. Write the name of a guard, or an inline rule.") - : GuardReference.FromName(name); - } + if (reader.TokenType == JsonTokenType.String) + { + string? name = reader.GetString(); + return string.IsNullOrEmpty(name) + ? throw new JsonException("the guard name holds no text. Write the name of a guard, or an inline rule.") + : GuardReference.FromName(name); + } - var rule = JsonSerializer.Deserialize(ref reader, options) - ?? throw new JsonException("a guard name or an inline rule is expected, and the document holds null"); + JsonNode rule = JsonSerializer.Deserialize(ref reader, options) + ?? throw new JsonException("a guard name or an inline rule is expected, and the document holds null"); - return GuardReference.FromRule(rule); - } - - /// - public override void Write(Utf8JsonWriter writer, GuardReference value, JsonSerializerOptions options) - { - ArgumentNullException.ThrowIfNull(writer); - ArgumentNullException.ThrowIfNull(value); + return GuardReference.FromRule(rule); + } - if (value.Name is { } name) + /// + public override void Write(Utf8JsonWriter writer, GuardReference value, JsonSerializerOptions options) { - writer.WriteStringValue(name); - return; - } + ArgumentNullException.ThrowIfNull(writer); + ArgumentNullException.ThrowIfNull(value); + + if (value.Name is { } name) + { + writer.WriteStringValue(name); + return; + } - JsonSerializer.Serialize(writer, value.Rule, options); + JsonSerializer.Serialize(writer, value.Rule, options); + } } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoadException.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoadException.cs index 64c5f970..bea62d8d 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoadException.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoadException.cs @@ -1,78 +1,91 @@ -namespace AgentCore.Application.Configuration.Parsing; -/// -/// The one exception every load failure uses. -/// -/// -/// Section 8.7: loading fails fast, and every message carries a JSON Pointer into the document. The -/// exception carries one error for each reason, so a check that finds several may report them all. -/// -public sealed class ConfigurationLoadException : Exception +namespace AgentCore.Application.Configuration.Parsing { - /// Creates an exception with no error detail. - public ConfigurationLoadException() - : base("The configuration document did not load.") => Errors = []; - - /// Creates an exception with a plain message and no error detail. - /// The message a human reads. - public ConfigurationLoadException(string message) - : base(message) => Errors = []; + /// + /// The one exception every load failure uses. + /// + /// + /// Section 8.7: loading fails fast, and every message carries a JSON Pointer into the document. The + /// exception carries one error for each reason, so a check that finds several may report them all. + /// + public sealed class ConfigurationLoadException : Exception + { + /// Creates an exception with no error detail. + public ConfigurationLoadException() + : base("The configuration document did not load.") + { + Errors = []; + } - /// Creates an exception with a plain message and an inner cause. - /// The message a human reads. - /// The cause. - public ConfigurationLoadException(string message, Exception? innerException) - : base(message, innerException) => Errors = []; + /// Creates an exception with a plain message and no error detail. + /// The message a human reads. + public ConfigurationLoadException(string message) + : base(message) + { + Errors = []; + } - /// Creates an exception for one error. - /// The reason the document did not load. - public ConfigurationLoadException(ConfigurationError error) - : this([error], null) - { - } + /// Creates an exception with a plain message and an inner cause. + /// The message a human reads. + /// The cause. + public ConfigurationLoadException(string message, Exception? innerException) + : base(message, innerException) + { + Errors = []; + } - /// Creates an exception for one error, with the cause that produced it. - /// The reason the document did not load. - /// The cause, when one exists. - public ConfigurationLoadException(ConfigurationError error, Exception? innerException) - : this([error], innerException) - { - } + /// Creates an exception for one error. + /// The reason the document did not load. + public ConfigurationLoadException(ConfigurationError error) + : this([error], null) + { + } - /// Creates an exception for several errors. - /// The reasons the document did not load. At least one is expected. - public ConfigurationLoadException(IEnumerable errors) - : this(errors, null) - { - } + /// Creates an exception for one error, with the cause that produced it. + /// The reason the document did not load. + /// The cause, when one exists. + public ConfigurationLoadException(ConfigurationError error, Exception? innerException) + : this([error], innerException) + { + } - /// Creates an exception for several errors, with the cause that produced them. - /// The reasons the document did not load. At least one is expected. - /// The cause, when one exists. - public ConfigurationLoadException(IEnumerable errors, Exception? innerException) - : base(BuildMessage(errors), innerException) - => Errors = [.. errors]; + /// Creates an exception for several errors. + /// The reasons the document did not load. At least one is expected. + public ConfigurationLoadException(IEnumerable errors) + : this(errors, null) + { + } - /// Gets every reason the document did not load, in the order the check found them. - public IReadOnlyList Errors { get; } + /// Creates an exception for several errors, with the cause that produced them. + /// The reasons the document did not load. At least one is expected. + /// The cause, when one exists. + public ConfigurationLoadException(IEnumerable errors, Exception? innerException) + : base(BuildMessage(errors), innerException) + { + Errors = [.. errors]; + } - /// Gets the JSON Pointer of the first error, or the root pointer when there is none. - public string Pointer => Errors.Count > 0 ? Errors[0].Pointer : ConfigurationError.RootPointer; + /// Gets every reason the document did not load, in the order the check found them. + public IReadOnlyList Errors { get; } - /// Gets the check that produced the first error. - public ConfigurationCheck Check => Errors.Count > 0 ? Errors[0].Check : ConfigurationCheck.Syntax; + /// Gets the JSON Pointer of the first error, or the root pointer when there is none. + public string Pointer => Errors.Count > 0 ? Errors[0].Pointer : ConfigurationError.RootPointer; - private static string BuildMessage(IEnumerable errors) - { - ArgumentNullException.ThrowIfNull(errors); + /// Gets the check that produced the first error. + public ConfigurationCheck Check => Errors.Count > 0 ? Errors[0].Check : ConfigurationCheck.Syntax; - var lines = errors.Select(error => error.ToString()).ToList(); - return lines.Count switch + private static string BuildMessage(IEnumerable errors) { - 0 => "The configuration document did not load.", - 1 => "The configuration document did not load. " + lines[0], - _ => "The configuration document did not load. " + lines.Count.ToString(System.Globalization.CultureInfo.InvariantCulture) - + " errors:" + Environment.NewLine + string.Join(Environment.NewLine, lines), - }; + ArgumentNullException.ThrowIfNull(errors); + + List lines = [.. errors.Select(error => error.ToString())]; + return lines.Count switch + { + 0 => "The configuration document did not load.", + 1 => "The configuration document did not load. " + lines[0], + _ => "The configuration document did not load. " + lines.Count.ToString(System.Globalization.CultureInfo.InvariantCulture) + + " errors:" + Environment.NewLine + string.Join(Environment.NewLine, lines), + }; + } } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoader.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoader.cs index 78bb683c..2eb25b38 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoader.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationLoader.cs @@ -2,133 +2,144 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Parsing; - -/// The two forms one configuration document may take. -public enum ConfigurationFormat +namespace AgentCore.Application.Configuration.Parsing { - /// YAML, read through YamlDotNet. - Yaml, + /// The two forms one configuration document may take. + public enum ConfigurationFormat + { + /// YAML, read through YamlDotNet. + Yaml, - /// JSON, read through . - Json, -} + /// JSON, read through . + Json, + } -/// -/// The whole load pipeline of section 6: YamlDotNet to to records. -/// -/// -/// The loader runs check 1 of section 8.5 and nothing else. Checks 2 to 8 run on the records it -/// returns. Loading fails fast, and every message carries a JSON Pointer into the document. -/// Rule 17 of section 11 holds here: the same document loads identically as YAML and as JSON. -/// -public static class ConfigurationLoader -{ - private static readonly JsonDocumentOptions JsonOptions = new() + /// + /// The whole load pipeline of section 6: YamlDotNet to to records. + /// + /// + /// The loader runs check 1 of section 8.5 and nothing else. Checks 2 to 8 run on the records it + /// returns. Loading fails fast, and every message carries a JSON Pointer into the document. + /// Rule 17 of section 11 holds here: the same document loads identically as YAML and as JSON. + /// + public static class ConfigurationLoader { - CommentHandling = JsonCommentHandling.Skip, - AllowTrailingCommas = true, - - // A repeated key is a mistake in both formats, and the YAML reader rejects it too. - AllowDuplicateProperties = false, - }; - - /// Loads a YAML document. - /// The YAML text. - /// The bound configuration. - /// The document is malformed or fails check 1. - public static AgentCoreConfiguration LoadYaml(string yaml) => Load(yaml, ConfigurationFormat.Yaml); - - /// Loads a JSON document. - /// The JSON text. - /// The bound configuration. - /// The document is malformed or fails check 1. - public static AgentCoreConfiguration LoadJson(string json) => Load(json, ConfigurationFormat.Json); - - /// Loads a document in the given format. - /// The document text. - /// The format of the text. - /// The bound configuration. - /// The document is malformed or fails check 1. - public static AgentCoreConfiguration Load(string text, ConfigurationFormat format) - => LoadDocument(ReadDocument(text, format)); - - /// Loads a document from a file. The extension picks the format. - /// The path of a .yaml, .yml, or .json file. - /// The bound configuration. - /// The extension is unknown, or the document fails to load. - public static AgentCoreConfiguration LoadFile(string path) - { - ArgumentException.ThrowIfNullOrEmpty(path); - - var extension = Path.GetExtension(path); - var format = extension.ToUpperInvariant() switch + private static readonly JsonDocumentOptions JsonOptions = new() { - ".YAML" or ".YML" => ConfigurationFormat.Yaml, - ".JSON" => ConfigurationFormat.Json, - _ => throw Syntax($"the file extension '{extension}' is unknown. Use .yaml, .yml, or .json."), + CommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true, + + // A repeated key is a mistake in both formats, and the YAML reader rejects it too. + AllowDuplicateProperties = false, }; - return Load(File.ReadAllText(path), format); - } + /// Loads a YAML document. + /// The YAML text. + /// The bound configuration. + /// The document is malformed or fails check 1. + public static AgentCoreConfiguration LoadYaml(string yaml) + { + return Load(yaml, ConfigurationFormat.Yaml); + } - /// Runs check 1 over a node tree, then binds it. - /// The document as a node tree. - /// The bound configuration. - /// The document fails check 1. - public static AgentCoreConfiguration LoadDocument(JsonNode document) - { - ArgumentNullException.ThrowIfNull(document); + /// Loads a JSON document. + /// The JSON text. + /// The bound configuration. + /// The document is malformed or fails check 1. + public static AgentCoreConfiguration LoadJson(string json) + { + return Load(json, ConfigurationFormat.Json); + } - ConfigurationSchemaValidator.Validate(document); - return ConfigurationBinder.Bind(document); - } + /// Loads a document in the given format. + /// The document text. + /// The format of the text. + /// The bound configuration. + /// The document is malformed or fails check 1. + public static AgentCoreConfiguration Load(string text, ConfigurationFormat format) + { + return LoadDocument(ReadDocument(text, format)); + } - /// Reads a document into a node tree, and binds nothing. - /// The document text. - /// The format of the text. - /// The node tree. Both formats produce the same tree for the same document. - /// The text is malformed. - public static JsonNode ReadDocument(string text, ConfigurationFormat format) - { - ArgumentNullException.ThrowIfNull(text); + /// Loads a document from a file. The extension picks the format. + /// The path of a .yaml, .yml, or .json file. + /// The bound configuration. + /// The extension is unknown, or the document fails to load. + public static AgentCoreConfiguration LoadFile(string path) + { + ArgumentException.ThrowIfNullOrEmpty(path); - var node = format switch + string extension = Path.GetExtension(path); + ConfigurationFormat format = extension.ToUpperInvariant() switch + { + ".YAML" or ".YML" => ConfigurationFormat.Yaml, + ".JSON" => ConfigurationFormat.Json, + _ => throw Syntax($"the file extension '{extension}' is unknown. Use .yaml, .yml, or .json."), + }; + + return Load(File.ReadAllText(path), format); + } + + /// Runs check 1 over a node tree, then binds it. + /// The document as a node tree. + /// The bound configuration. + /// The document fails check 1. + public static AgentCoreConfiguration LoadDocument(JsonNode document) { - ConfigurationFormat.Yaml => YamlToJson.Parse(text), - ConfigurationFormat.Json => ReadJson(text), - _ => throw Syntax($"the format '{format}' is unknown"), - }; + ArgumentNullException.ThrowIfNull(document); - // Both paths end in the same node backing, so two trees of the same document compare equal. - // JsonOptions travels with this reparse too: ReadJson already enforces it on the JSON path, - // and on the YAML path YamlDotNet rejects a repeated node key while it builds the mapping and - // YamlToJson.ConvertMapping rejects the rest (two keys that differ as YAML and agree as JSON), - // so this is belt-and-braces rather than a live gap. - return JsonNode.Parse(node.ToJsonString(), documentOptions: JsonOptions) - ?? throw Syntax("the document is empty"); - } + ConfigurationSchemaValidator.Validate(document); + return ConfigurationBinder.Bind(document); + } - private static JsonNode ReadJson(string json) - { - try + /// Reads a document into a node tree, and binds nothing. + /// The document text. + /// The format of the text. + /// The node tree. Both formats produce the same tree for the same document. + /// The text is malformed. + public static JsonNode ReadDocument(string text, ConfigurationFormat format) { - return JsonNode.Parse(json, documentOptions: JsonOptions) + ArgumentNullException.ThrowIfNull(text); + + JsonNode node = format switch + { + ConfigurationFormat.Yaml => YamlToJson.Parse(text), + ConfigurationFormat.Json => ReadJson(text), + _ => throw Syntax($"the format '{format}' is unknown"), + }; + + // Both paths end in the same node backing, so two trees of the same document compare equal. + // JsonOptions travels with this reparse too: ReadJson already enforces it on the JSON path, + // and on the YAML path YamlDotNet rejects a repeated node key while it builds the mapping and + // YamlToJson.ConvertMapping rejects the rest (two keys that differ as YAML and agree as JSON), + // so this is belt-and-braces rather than a live gap. + return JsonNode.Parse(node.ToJsonString(), documentOptions: JsonOptions) ?? throw Syntax("the document is empty"); } - catch (JsonException exception) + + private static JsonNode ReadJson(string json) { - throw Syntax($"the document is not well-formed JSON: {exception.Message}", exception); + try + { + return JsonNode.Parse(json, documentOptions: JsonOptions) + ?? throw Syntax("the document is empty"); + } + catch (JsonException exception) + { + throw Syntax($"the document is not well-formed JSON: {exception.Message}", exception); + } } - } - private static ConfigurationLoadException Syntax(string message, Exception? cause = null) - => new( - new ConfigurationError - { - Pointer = ConfigurationError.RootPointer, - Message = message, - Check = ConfigurationCheck.Syntax, - }, - cause); + private static ConfigurationLoadException Syntax(string message, Exception? cause = null) + { + return new( + new ConfigurationError + { + Pointer = ConfigurationError.RootPointer, + Message = message, + Check = ConfigurationCheck.Syntax, + }, + cause); + } + } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ConfigurationSchemaValidator.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationSchemaValidator.cs index 1094c861..887241c1 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationSchemaValidator.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationSchemaValidator.cs @@ -1,137 +1,139 @@ using System.Reflection; using System.Text.Json; using System.Text.Json.Nodes; +using Json.Pointer; using Json.Schema; -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// Check 1 of section 8.5: the JSON Schema over the document. It fails on any shape error. -/// -/// -/// The schema ships as an embedded resource of this assembly. Checks 2 to 8 run after this one, on -/// the bound records. -/// -public static class ConfigurationSchemaValidator +namespace AgentCore.Application.Configuration.Parsing { - private const string ResourceName = "AgentCore.Application.Configuration.Schema.agentcore-v1.schema.json"; - - private static readonly Lazy LazySchemaJson = new(ReadResource); - - private static readonly Lazy LazySchema = new(() => JsonSchema.FromText(LazySchemaJson.Value)); - - private static readonly EvaluationOptions Options = new() - { - OutputFormat = OutputFormat.List, - }; - /// - /// The schema keywords whose subschemas are asked a question rather than imposed as a rule. + /// Check 1 of section 8.5: the JSON Schema over the document. It fails on any shape error. /// - private static readonly HashSet SpeculativeKeywords = new(StringComparer.Ordinal) + /// + /// The schema ships as an embedded resource of this assembly. Checks 2 to 8 run after this one, on + /// the bound records. + /// + public static class ConfigurationSchemaValidator { - "if", "not", "oneOf", "anyOf", "propertyNames", - }; + private const string ResourceName = "AgentCore.Application.Configuration.Schema.agentcore-v1.schema.json"; - /// Gets the text of the embedded agentcore-v1 JSON Schema. - public static string SchemaJson => LazySchemaJson.Value; + private static readonly Lazy LazySchemaJson = new(ReadResource); - /// Evaluates a document against the schema and returns every shape error. - /// The document, already read from YAML or JSON. - /// The errors, ordered by their JSON Pointer. An empty list means the document passes. - public static IReadOnlyList Evaluate(JsonNode document) - { - ArgumentNullException.ThrowIfNull(document); + private static readonly Lazy LazySchema = new(() => JsonSchema.FromText(LazySchemaJson.Value)); - using var element = JsonDocument.Parse(document.ToJsonString()); - var results = LazySchema.Value.Evaluate(element.RootElement, Options); - if (results.IsValid) + private static readonly EvaluationOptions Options = new() { - return []; - } + OutputFormat = OutputFormat.List, + }; - var errors = new List(); - var seen = new HashSet(StringComparer.Ordinal); + /// + /// The schema keywords whose subschemas are asked a question rather than imposed as a rule. + /// + private static readonly HashSet SpeculativeKeywords = new(StringComparer.Ordinal) + { + "if", "not", "oneOf", "anyOf", "propertyNames", + }; - foreach (var node in results.Details ?? []) + /// Gets the text of the embedded agentcore-v1 JSON Schema. + public static string SchemaJson => LazySchemaJson.Value; + + /// Evaluates a document against the schema and returns every shape error. + /// The document, already read from YAML or JSON. + /// The errors, ordered by their JSON Pointer. An empty list means the document passes. + public static IReadOnlyList Evaluate(JsonNode document) { - if (node.IsValid || node.Errors is not { Count: > 0 } || Speculative(node)) + ArgumentNullException.ThrowIfNull(document); + + using JsonDocument element = JsonDocument.Parse(document.ToJsonString()); + EvaluationResults results = LazySchema.Value.Evaluate(element.RootElement, Options); + if (results.IsValid) { - continue; + return []; } - var pointer = node.InstanceLocation.ToString(); - foreach (var error in node.Errors) + List errors = []; + HashSet seen = new(StringComparer.Ordinal); + + foreach (EvaluationResults node in results.Details ?? []) { - if (SchemaFailureWording.Describe(node, error.Key, error.Value) is not { } message) + if (node.IsValid || node.Errors is not { Count: > 0 } || Speculative(node)) { continue; } - if (seen.Add(pointer + "\0" + message)) + string pointer = node.InstanceLocation.ToString(); + foreach (KeyValuePair error in node.Errors) { - errors.Add(new ConfigurationError + if (SchemaFailureWording.Describe(node, error.Key, error.Value) is not { } message) + { + continue; + } + + if (seen.Add(pointer + "\0" + message)) { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.DocumentSchema, - }); + errors.Add(new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.DocumentSchema, + }); + } } } - } - if (errors.Count == 0) - { - errors.Add(new ConfigurationError + if (errors.Count == 0) { - Pointer = ConfigurationError.RootPointer, - Message = "the document does not match the agentcore/v1 schema", - Check = ConfigurationCheck.DocumentSchema, - }); - } + errors.Add(new ConfigurationError + { + Pointer = ConfigurationError.RootPointer, + Message = "the document does not match the agentcore/v1 schema", + Check = ConfigurationCheck.DocumentSchema, + }); + } - errors.Sort(static (left, right) => string.CompareOrdinal(left.Pointer, right.Pointer)); - return errors; - } + errors.Sort(static (left, right) => string.CompareOrdinal(left.Pointer, right.Pointer)); + return errors; + } - /// Evaluates a document and throws when it holds any shape error. - /// The document, already read from YAML or JSON. - /// The document does not match the schema. - public static void Validate(JsonNode document) - { - var errors = Evaluate(document); - if (errors.Count > 0) + /// Evaluates a document and throws when it holds any shape error. + /// The document, already read from YAML or JSON. + /// The document does not match the schema. + public static void Validate(JsonNode document) { - throw new ConfigurationLoadException(errors); + IReadOnlyList errors = Evaluate(document); + if (errors.Count > 0) + { + throw new ConfigurationLoadException(errors); + } } - } - /// Reports whether a failure came from inside a subschema the keyword only asked about. - /// The evaluation node. - /// when the failure is the keyword working, not a document mistake. - private static bool Speculative(EvaluationResults node) - { - var path = node.EvaluationPath; - for (var index = 0; index < path.SegmentCount; index++) + /// Reports whether a failure came from inside a subschema the keyword only asked about. + /// The evaluation node. + /// when the failure is the keyword working, not a document mistake. + private static bool Speculative(EvaluationResults node) { - if (SpeculativeKeywords.Contains(path[index].ToString())) + JsonPointer path = node.EvaluationPath; + for (int index = 0; index < path.SegmentCount; index++) { - return true; + if (SpeculativeKeywords.Contains(path[index].ToString())) + { + return true; + } } - } - return false; - } + return false; + } - private static string ReadResource() - { - var assembly = typeof(ConfigurationSchemaValidator).GetTypeInfo().Assembly; + private static string ReadResource() + { + Assembly assembly = typeof(ConfigurationSchemaValidator).GetTypeInfo().Assembly; - using var stream = assembly.GetManifestResourceStream(ResourceName) - ?? throw new InvalidOperationException($"The embedded resource '{ResourceName}' is missing from the assembly."); + using Stream stream = assembly.GetManifestResourceStream(ResourceName) + ?? throw new InvalidOperationException($"The embedded resource '{ResourceName}' is missing from the assembly."); - using var reader = new StreamReader(stream); + using StreamReader reader = new(stream); - return reader.ReadToEnd(); + return reader.ReadToEnd(); + } } } diff --git a/src/AgentCore.Application/Configuration/Parsing/McpAllowEntryConverter.cs b/src/AgentCore.Application/Configuration/Parsing/McpAllowEntryConverter.cs index c1833ea9..42400bb5 100644 --- a/src/AgentCore.Application/Configuration/Parsing/McpAllowEntryConverter.cs +++ b/src/AgentCore.Application/Configuration/Parsing/McpAllowEntryConverter.cs @@ -3,81 +3,81 @@ using System.Text.Json.Serialization; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// Reads one allow: entry: a tool name, or a single-key object aliasing it. -/// -/// -/// Check 1 already holds an entry to one of the two shapes below. The failure branches here are kept -/// for a hand-built tree that reached without the check. -/// -internal sealed class McpAllowEntryConverter : JsonConverter +namespace AgentCore.Application.Configuration.Parsing { /// - /// Gets a value indicating that must run for a JSON null too. + /// Reads one allow: entry: a tool name, or a single-key object aliasing it. /// /// - /// The default is for a reference type, and null would then bind - /// straight into the list without ever reaching — the one input that would - /// silently produce a wrong entry instead of the loud failure every other shape gets here. + /// Check 1 already holds an entry to one of the two shapes below. The failure branches here are kept + /// for a hand-built tree that reached without the check. /// - public override bool HandleNull => true; - - /// - public override McpAllowEntry Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) + internal sealed class McpAllowEntryConverter : JsonConverter { - if (reader.TokenType == JsonTokenType.String) - { - return new McpAllowEntry { Name = reader.GetString()! }; - } + /// + /// Gets a value indicating that must run for a JSON null too. + /// + /// + /// The default is for a reference type, and null would then bind + /// straight into the list without ever reaching — the one input that would + /// silently produce a wrong entry instead of the loud failure every other shape gets here. + /// + public override bool HandleNull => true; - var node = JsonSerializer.Deserialize(ref reader, options); - if (node is not JsonObject entry || entry.Count != 1) + /// + public override McpAllowEntry Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { - throw new JsonException( - $"an allow entry must be a string or a single-key object, and this is a {Describe(node)}"); + if (reader.TokenType == JsonTokenType.String) + { + return new McpAllowEntry { Name = reader.GetString()! }; + } + + JsonNode? node = JsonSerializer.Deserialize(ref reader, options); + if (node is not JsonObject entry || entry.Count != 1) + { + throw new JsonException( + $"an allow entry must be a string or a single-key object, and this is a {Describe(node)}"); + } + + (string? name, JsonNode? aliasNode) = entry.Single(); + return aliasNode is not JsonObject alias + || alias.Count != 1 + || alias["as"] is not JsonValue asValue + || asValue.GetValueKind() != JsonValueKind.String + ? throw new JsonException($"'{name}' must map to an object holding only 'as', and this does not") + : new McpAllowEntry { Name = name, As = asValue.GetValue() }; } - var (name, aliasNode) = entry.Single(); - if (aliasNode is not JsonObject alias - || alias.Count != 1 - || alias["as"] is not JsonValue asValue - || asValue.GetValueKind() != JsonValueKind.String) + /// + public override void Write(Utf8JsonWriter writer, McpAllowEntry value, JsonSerializerOptions options) { - throw new JsonException($"'{name}' must map to an object holding only 'as', and this does not"); - } + ArgumentNullException.ThrowIfNull(writer); + ArgumentNullException.ThrowIfNull(value); - return new McpAllowEntry { Name = name, As = asValue.GetValue() }; - } + if (value.As is null) + { + writer.WriteStringValue(value.Name); + return; + } - /// - public override void Write(Utf8JsonWriter writer, McpAllowEntry value, JsonSerializerOptions options) - { - ArgumentNullException.ThrowIfNull(writer); - ArgumentNullException.ThrowIfNull(value); + writer.WriteStartObject(); + writer.WritePropertyName(value.Name); + writer.WriteStartObject(); + writer.WriteString("as", value.As); + writer.WriteEndObject(); + writer.WriteEndObject(); + } - if (value.As is null) + private static string Describe(JsonNode? node) { - writer.WriteStringValue(value.Name); - return; + return node switch + { + null => "null", + JsonObject obj => $"object with {obj.Count} properties", + JsonArray => "array", + JsonValue value => value.GetValueKind().ToString(), + _ => node.GetType().Name, + }; } - - writer.WriteStartObject(); - writer.WritePropertyName(value.Name); - writer.WriteStartObject(); - writer.WriteString("as", value.As); - writer.WriteEndObject(); - writer.WriteEndObject(); } - - private static string Describe(JsonNode? node) - => node switch - { - null => "null", - JsonObject obj => $"object with {obj.Count} properties", - JsonArray => "array", - JsonValue value => value.GetValueKind().ToString(), - _ => node.GetType().Name, - }; } diff --git a/src/AgentCore.Application/Configuration/Parsing/SchemaFailureWording.cs b/src/AgentCore.Application/Configuration/Parsing/SchemaFailureWording.cs index a43201e8..fcc4604a 100644 --- a/src/AgentCore.Application/Configuration/Parsing/SchemaFailureWording.cs +++ b/src/AgentCore.Application/Configuration/Parsing/SchemaFailureWording.cs @@ -5,224 +5,252 @@ using Json.Pointer; using Json.Schema; -namespace AgentCore.Application.Configuration.Parsing; - -/// Writes one schema failure as a sentence about the document. -internal static partial class SchemaFailureWording +namespace AgentCore.Application.Configuration.Parsing { - private static readonly Lazy LazySchemaTree = new(() => JsonNode.Parse(ConfigurationSchemaValidator.SchemaJson)!); - - /// - /// The keywords that only relay a child failure upwards. - /// - private static readonly HashSet RelayKeywords = new(StringComparer.Ordinal) - { - "properties", "patternProperties", "items", "prefixItems", "contains", - "allOf", "then", "else", "dependentSchemas", "dependentRequired", - }; - - /// Writes one failure as a sentence about the document, or drops it. - /// The evaluation node the failure came from. - /// The schema keyword that failed, or the empty string for a false schema. - /// The text the library wrote. - /// The message the author reads, or to drop the failure. - public static string? Describe(EvaluationResults node, string keyword, string message) + /// Writes one schema failure as a sentence about the document. + internal static partial class SchemaFailureWording { - if (RelayKeywords.Contains(keyword)) + private static readonly Lazy LazySchemaTree = new(() => JsonNode.Parse(ConfigurationSchemaValidator.SchemaJson)!); + + /// + /// The keywords that only relay a child failure upwards. + /// + private static readonly HashSet RelayKeywords = new(StringComparer.Ordinal) { - return null; + "properties", "patternProperties", "items", "prefixItems", "contains", + "allOf", "then", "else", "dependentSchemas", "dependentRequired", + }; + + /// Writes one failure as a sentence about the document, or drops it. + /// The evaluation node the failure came from. + /// The schema keyword that failed, or the empty string for a false schema. + /// The text the library wrote. + /// The message the author reads, or to drop the failure. + public static string? Describe(EvaluationResults node, string keyword, string message) + { + return RelayKeywords.Contains(keyword) + ? null + : keyword switch + { + "" => FalseSchema(node), + "required" => Required(message), + "additionalProperties" => AdditionalProperties(node, message), + "type" => WrongType(message), + "enum" => Enumerated(node), + "const" => Constant(node), + "pattern" => Pattern(node), + "minLength" or "maxLength" => Length(message, "text", "characters"), + "minItems" or "maxItems" => Length(message, "list", "entries"), + "uniqueItems" => "the list repeats a value, and every entry here must differ", + + "minimum" or "exclusiveMinimum" or "maximum" or "exclusiveMaximum" or "multipleOf" + => $"the number is outside the range this key accepts: {message}", + + "oneOf" => OneOf(node), + + // The rule this states is written on the schema node itself, because no keyword can say it. + "not" or "dependentRequired" => Documentation(node) ?? message, + + "propertyNames" => $"these key names are not names the schema accepts: {Quote(Names(message))}", + + // Anything the schema grows later still reports, with the keyword named. + _ => string.Create(CultureInfo.InvariantCulture, $"{message} [{keyword}]"), + }; } - return keyword switch + /// A false schema. The instance pointer ends in the key that is not allowed to be there. + private static string FalseSchema(EvaluationResults node) { - "" => FalseSchema(node), - "required" => Required(message), - "additionalProperties" => AdditionalProperties(node, message), - "type" => WrongType(message), - "enum" => Enumerated(node), - "const" => Constant(node), - "pattern" => Pattern(node), - "minLength" or "maxLength" => Length(message, "text", "characters"), - "minItems" or "maxItems" => Length(message, "list", "entries"), - "uniqueItems" => "the list repeats a value, and every entry here must differ", + return Name(node) is { Length: > 0 } name + ? $"the key '{name}' is not allowed here" + : "the schema allows nothing here"; + } - "minimum" or "exclusiveMinimum" or "maximum" or "exclusiveMaximum" or "multipleOf" - => $"the number is outside the range this key accepts: {message}", + private static string Required(string message) + { + return Names(message) is { Count: 1 } one + ? $"the required property '{one[0]}' is missing" + : $"the required properties {Quote(Names(message))} are missing"; + } - "oneOf" => OneOf(node), + /// Writes an additionalProperties failure, or drops it. + /// The evaluation node. + /// The text the library wrote. + /// The message the author reads, or to drop the failure. + private static string? AdditionalProperties(EvaluationResults node, string message) + { + return Keyword(node, "additionalProperties") is JsonValue value && value.GetValueKind() == JsonValueKind.False + ? $"the schema does not know these keys here: {Quote(Names(message))}" + : null; + } - // The rule this states is written on the schema node itself, because no keyword can say it. - "not" or "dependentRequired" => Documentation(node) ?? message, + private static string WrongType(string message) + { + return WrongTypePattern().Match(message) is { Success: true } wrong + ? $"the value is {wrong.Groups[1].Value}, and this key takes {wrong.Groups[2].Value}" + : $"the value has the wrong type. {message}"; + } - "propertyNames" => $"these key names are not names the schema accepts: {Quote(Names(message))}", + private static string Enumerated(EvaluationResults node) + { + return Accepted(node, "enum") is { Count: > 0 } members + ? $"this key accepts only: {string.Join(", ", members)}" + : "the value is not one this key accepts"; + } - // Anything the schema grows later still reports, with the keyword named. - _ => string.Create(CultureInfo.InvariantCulture, $"{message} [{keyword}]"), - }; - } + private static string Constant(EvaluationResults node) + { + return Accepted(node, "const") is { Count: 1 } only + ? $"this key is written exactly '{only[0]}', and nothing else" + : "the value is not the one this key holds"; + } - /// A false schema. The instance pointer ends in the key that is not allowed to be there. - private static string FalseSchema(EvaluationResults node) - => Name(node) is { Length: > 0 } name - ? $"the key '{name}' is not allowed here" - : "the schema allows nothing here"; - - private static string Required(string message) - => Names(message) is { Count: 1 } one - ? $"the required property '{one[0]}' is missing" - : $"the required properties {Quote(Names(message))} are missing"; - - /// Writes an additionalProperties failure, or drops it. - /// The evaluation node. - /// The text the library wrote. - /// The message the author reads, or to drop the failure. - private static string? AdditionalProperties(EvaluationResults node, string message) - => Keyword(node, "additionalProperties") is JsonValue value && value.GetValueKind() == JsonValueKind.False - ? $"the schema does not know these keys here: {Quote(Names(message))}" - : null; - - private static string WrongType(string message) - => WrongTypePattern().Match(message) is { Success: true } wrong - ? $"the value is {wrong.Groups[1].Value}, and this key takes {wrong.Groups[2].Value}" - : $"the value has the wrong type. {message}"; - - private static string Enumerated(EvaluationResults node) - => Accepted(node, "enum") is { Count: > 0 } members - ? $"this key accepts only: {string.Join(", ", members)}" - : "the value is not one this key accepts"; - - private static string Constant(EvaluationResults node) - => Accepted(node, "const") is { Count: 1 } only - ? $"this key is written exactly '{only[0]}', and nothing else" - : "the value is not the one this key holds"; - - private static string Pattern(EvaluationResults node) - => Keyword(node, "pattern")?.GetValue() switch - { - null => "the value is not written in the form this key requires", - @"\S" => "the text holds no words, and this key needs some", - var form => $"the text is not written in the form this key requires: {form}", - }; + private static string Pattern(EvaluationResults node) + { + return Keyword(node, "pattern")?.GetValue() switch + { + null => "the value is not written in the form this key requires", + @"\S" => "the text holds no words, and this key needs some", + var form => $"the text is not written in the form this key requires: {form}", + }; + } - /// Writes a length failure over , counted in . - private static string Length(string message, string what, string unit) - => Bound(message) is { } bound - ? $"the {what} holds too {bound.Way} {unit}, and this key takes at {bound.Limit}" - : $"the {what} is the wrong length. {message}"; + /// Writes a length failure over , counted in . + private static string Length(string message, string what, string unit) + { + return Bound(message) is { } bound + ? $"the {what} holds too {bound.Way} {unit}, and this key takes at {bound.Limit}" + : $"the {what} is the wrong length. {message}"; + } - /// A composite the document has to satisfy exactly one way. The schema documents each way. - private static string OneOf(EvaluationResults node) - => Alternatives(node) is { Count: > 0 } shapes - ? $"this block matches none of the shapes allowed here: {string.Join("; ", shapes)}" - : "this block matches none of the shapes allowed here"; + /// A composite the document has to satisfy exactly one way. The schema documents each way. + private static string OneOf(EvaluationResults node) + { + return Alternatives(node) is { Count: > 0 } shapes + ? $"this block matches none of the shapes allowed here: {string.Join("; ", shapes)}" + : "this block matches none of the shapes allowed here"; + } - /// Reads the last segment of the instance pointer, unescaped. - private static string Name(EvaluationResults node) - { - var location = node.InstanceLocation; - return location.SegmentCount == 0 ? string.Empty : location[location.SegmentCount - 1].ToString(); - } + /// Reads the last segment of the instance pointer, unescaped. + private static string Name(EvaluationResults node) + { + JsonPointer location = node.InstanceLocation; + return location.SegmentCount == 0 ? string.Empty : location[location.SegmentCount - 1].ToString(); + } - /// Reads the JSON array of names out of a library message. - private static List Names(string message) - { - var open = message.IndexOf('[', StringComparison.Ordinal); - var close = message.LastIndexOf(']'); - if (open < 0 || close <= open) + /// Reads the JSON array of names out of a library message. + private static List Names(string message) { - return []; + int open = message.IndexOf('[', StringComparison.Ordinal); + int close = message.LastIndexOf(']'); + if (open < 0 || close <= open) + { + return []; + } + + try + { + return JsonNode.Parse(message[open..(close + 1)]) is JsonArray array + ? [.. array.Select(item => item?.GetValue() ?? string.Empty)] + : []; + } + catch (JsonException) + { + return []; + } } - try + private static string Quote(List names) { - return JsonNode.Parse(message[open..(close + 1)]) is JsonArray array - ? [.. array.Select(item => item?.GetValue() ?? string.Empty)] - : []; + return names.Count == 0 ? "(none)" : string.Join(", ", names.Select(name => $"'{name}'")); } - catch (JsonException) + + /// Reads one keyword off the schema node the failure came from. + /// The evaluation node. + /// The keyword to read. + /// The keyword's value, or when the node cannot be resolved. + private static JsonNode? Keyword(EvaluationResults node, string keyword) { - return []; + return Schema(node) is JsonObject schema && schema.TryGetPropertyValue(keyword, out JsonNode? value) ? value : null; } - } - private static string Quote(List names) - => names.Count == 0 ? "(none)" : string.Join(", ", names.Select(name => $"'{name}'")); + private static JsonObject? Schema(EvaluationResults node) + { + string fragment = node.SchemaLocation.Fragment; + if (fragment.Length == 0 || fragment[0] != '#' || !JsonPointer.TryParse(fragment[1..], out JsonPointer pointer)) + { + return null; + } - /// Reads one keyword off the schema node the failure came from. - /// The evaluation node. - /// The keyword to read. - /// The keyword's value, or when the node cannot be resolved. - private static JsonNode? Keyword(EvaluationResults node, string keyword) - => Schema(node) is JsonObject schema && schema.TryGetPropertyValue(keyword, out var value) ? value : null; + // The library indexes some keywords under a name of its own, so the location it reports may + // hold a segment the schema document does not. Walking up finds the nearest node that does + // exist; a walk that lands somewhere unhelpful simply holds no keyword to read, and the + // caller falls back to a sentence that needs no lookup. + for (int levels = 0; levels <= pointer.SegmentCount; levels++) + { + JsonPointer? candidate = levels == 0 ? pointer : pointer.GetParent(levels); + if (candidate is { } at && at.TryEvaluate(LazySchemaTree.Value, out JsonNode? found) && found is JsonObject schema) + { + return schema; + } + } - private static JsonObject? Schema(EvaluationResults node) - { - var fragment = node.SchemaLocation.Fragment; - if (fragment.Length == 0 || fragment[0] != '#' || !JsonPointer.TryParse(fragment[1..], out var pointer)) - { return null; } - // The library indexes some keywords under a name of its own, so the location it reports may - // hold a segment the schema document does not. Walking up finds the nearest node that does - // exist; a walk that lands somewhere unhelpful simply holds no keyword to read, and the - // caller falls back to a sentence that needs no lookup. - for (var levels = 0; levels <= pointer.SegmentCount; levels++) + /// Lists the values one key accepts, as the schema wrote them. + private static List Accepted(EvaluationResults node, string keyword) { - var candidate = levels == 0 ? pointer : pointer.GetParent(levels); - if (candidate is { } at && at.TryEvaluate(LazySchemaTree.Value, out var found) && found is JsonObject schema) + return Keyword(node, keyword) switch { - return schema; - } + JsonArray array => [.. array.Select(Written)], + { } single => [Written(single)], + _ => [], + }; } - return null; - } + private static string Written(JsonNode? value) + { + return value is JsonValue text && text.GetValueKind() == JsonValueKind.String + ? text.GetValue() + : value?.ToJsonString() ?? "null"; + } - /// Lists the values one key accepts, as the schema wrote them. - private static List Accepted(EvaluationResults node, string keyword) - => Keyword(node, keyword) switch + /// Lists what each branch of a oneOf says about itself. + private static List Alternatives(EvaluationResults node) { - JsonArray array => [.. array.Select(Written)], - { } single => [Written(single)], - _ => [], - }; + return Keyword(node, "oneOf") is JsonArray branches + ? [.. branches + .Select(branch => (branch as JsonObject)?["description"]?.GetValue()) + .Where(description => !string.IsNullOrEmpty(description)) + .Select(description => description!)] + : []; + } - private static string Written(JsonNode? value) - => value is JsonValue text && text.GetValueKind() == JsonValueKind.String - ? text.GetValue() - : value?.ToJsonString() ?? "null"; - - /// Lists what each branch of a oneOf says about itself. - private static List Alternatives(EvaluationResults node) - => Keyword(node, "oneOf") is JsonArray branches - ? [.. branches - .Select(branch => (branch as JsonObject)?["description"]?.GetValue()) - .Where(description => !string.IsNullOrEmpty(description)) - .Select(description => description!)] - : []; - - /// Reads what the schema says about the rule this node carries. - private static string? Documentation(EvaluationResults node) - => Keyword(node, "description")?.GetValue() ?? Keyword(node, "$comment")?.GetValue(); - - /// Reads "at least 1 items" or "at most 3 items" out of a library message. - /// The text the library wrote. - /// Which way the bound runs and what it is, or when the message does not carry one. - private static (string Way, string Limit)? Bound(string message) - { - if (BoundPattern().Match(message) is not { Success: true } bound) + /// Reads what the schema says about the rule this node carries. + private static string? Documentation(EvaluationResults node) { - return null; + return Keyword(node, "description")?.GetValue() ?? Keyword(node, "$comment")?.GetValue(); } - var way = bound.Groups[1].Value == "least" ? "few" : "many"; - return (way, $"{bound.Groups[1].Value} {bound.Groups[2].Value}"); - } + /// Reads "at least 1 items" or "at most 3 items" out of a library message. + /// The text the library wrote. + /// Which way the bound runs and what it is, or when the message does not carry one. + private static (string Way, string Limit)? Bound(string message) + { + if (BoundPattern().Match(message) is not { Success: true } bound) + { + return null; + } + + string way = bound.Groups[1].Value == "least" ? "few" : "many"; + return (way, $"{bound.Groups[1].Value} {bound.Groups[2].Value}"); + } - [GeneratedRegex(@"^Value is ""([^""]+)"" but should be ""([^""]+)""$")] - private static partial Regex WrongTypePattern(); + [GeneratedRegex(@"^Value is ""([^""]+)"" but should be ""([^""]+)""$")] + private static partial Regex WrongTypePattern(); - [GeneratedRegex(@"at (least|most) (\d+)")] - private static partial Regex BoundPattern(); + [GeneratedRegex(@"at (least|most) (\d+)")] + private static partial Regex BoundPattern(); + } } diff --git a/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs b/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs index 25ac9ab9..e6e4f4a4 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs @@ -1,45 +1,54 @@ -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// A providers.knowledge.scope.template: the payload path one facet key becomes. -/// -/// -/// There is no default template, because a template is a claim about where one particular collection -/// keeps its facets. Boot, the probe (§8 step 5) and the store's own filter all resolve a key the -/// same way, so they resolve it through this one type rather than each holding the raw string. -/// -public sealed record ScopeTemplate +namespace AgentCore.Application.Configuration.Parsing { - /// The placeholder a template writes where the facet key goes. - public const string KeyPlaceholder = "{key}"; - - /// The advice every refusal over a missing template ends with. - public const string WriteOneAdvice = - "There is no default: write scope.template as the payload path one facet key becomes, such " - + "as '{key}' for flat facets or 'facets.{key}' for facets nested under one struct."; - - private ScopeTemplate(string raw) => Raw = raw; - - /// Gets the text exactly as the document wrote it. - public string Raw { get; } - - /// Reads a template out of what the document wrote. - /// The raw scope.template value. - /// The template, or when the document names none. - public static ScopeTemplate? Parse(string? text) - => text is { Length: > 0 } ? new ScopeTemplate(text) : null; - - /// Turns one facet key into the payload path this template names for it. - /// The facet key: a slot name, or a wildcard.facets member. - /// The resolved path. - /// is . - public string Resolve(string key) + /// + /// A providers.knowledge.scope.template: the payload path one facet key becomes. + /// + /// + /// There is no default template, because a template is a claim about where one particular collection + /// keeps its facets. Boot, the probe (§8 step 5) and the store's own filter all resolve a key the + /// same way, so they resolve it through this one type rather than each holding the raw string. + /// + public sealed record ScopeTemplate { - ArgumentNullException.ThrowIfNull(key); - - return Raw.Replace(KeyPlaceholder, key, StringComparison.Ordinal); + /// The placeholder a template writes where the facet key goes. + public const string KeyPlaceholder = "{key}"; + + /// The advice every refusal over a missing template ends with. + public const string WriteOneAdvice = + "There is no default: write scope.template as the payload path one facet key becomes, such " + + "as '{key}' for flat facets or 'facets.{key}' for facets nested under one struct."; + + private ScopeTemplate(string raw) + { + Raw = raw; + } + + /// Gets the text exactly as the document wrote it. + public string Raw { get; } + + /// Reads a template out of what the document wrote. + /// The raw scope.template value. + /// The template, or when the document names none. + public static ScopeTemplate? Parse(string? text) + { + return text is { Length: > 0 } ? new ScopeTemplate(text) : null; + } + + /// Turns one facet key into the payload path this template names for it. + /// The facet key: a slot name, or a wildcard.facets member. + /// The resolved path. + /// is . + public string Resolve(string key) + { + ArgumentNullException.ThrowIfNull(key); + + return Raw.Replace(KeyPlaceholder, key, StringComparison.Ordinal); + } + + /// + public override string ToString() + { + return Raw; + } } - - /// - public override string ToString() => Raw; } diff --git a/src/AgentCore.Application/Configuration/Parsing/SecretReference.cs b/src/AgentCore.Application/Configuration/Parsing/SecretReference.cs index 01923c60..888640a5 100644 --- a/src/AgentCore.Application/Configuration/Parsing/SecretReference.cs +++ b/src/AgentCore.Application/Configuration/Parsing/SecretReference.cs @@ -1,21 +1,25 @@ -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// One ${secret:name} reference inside a configuration string. -/// -/// -/// The parser reads the reference and never resolves it. ISecretResolverPort resolves it at -/// startup, through the four-step chain in D22. -/// -/// The secret name between the colon and the closing brace. -/// The position of the $ inside the source string. -/// The number of characters the whole reference spans. -public sealed record SecretReference(string Name, int Start, int Length) +namespace AgentCore.Application.Configuration.Parsing { - /// The text that opens a reference. - public const string Prefix = "${secret:"; + /// + /// One ${secret:name} reference inside a configuration string. + /// + /// + /// The parser reads the reference and never resolves it. ISecretResolverPort resolves it at + /// startup, through the four-step chain in D22. + /// + /// The secret name between the colon and the closing brace. + /// The position of the $ inside the source string. + /// The number of characters the whole reference spans. + public sealed record SecretReference(string Name, int Start, int Length) + { + /// The text that opens a reference. + public const string Prefix = "${secret:"; - /// Writes the reference back in its source form. - /// The text ${secret:name}. - public override string ToString() => Prefix + Name + "}"; + /// Writes the reference back in its source form. + /// The text ${secret:name}. + public override string ToString() + { + return Prefix + Name + "}"; + } + } } diff --git a/src/AgentCore.Application/Configuration/Parsing/SecretTemplate.cs b/src/AgentCore.Application/Configuration/Parsing/SecretTemplate.cs index 17dc19a7..7913d367 100644 --- a/src/AgentCore.Application/Configuration/Parsing/SecretTemplate.cs +++ b/src/AgentCore.Application/Configuration/Parsing/SecretTemplate.cs @@ -1,96 +1,100 @@ using System.Text; -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// A configuration string that may hold ${secret:name} references. -/// -/// -/// Section 8.1 shows one in tools[].request.headers. The template keeps the raw text and the -/// references it found. It resolves nothing: ISecretResolverPort does that at startup. -/// -public sealed record SecretTemplate +namespace AgentCore.Application.Configuration.Parsing { - private SecretTemplate(string raw, IReadOnlyList references) + /// + /// A configuration string that may hold ${secret:name} references. + /// + /// + /// Section 8.1 shows one in tools[].request.headers. The template keeps the raw text and the + /// references it found. It resolves nothing: ISecretResolverPort does that at startup. + /// + public sealed record SecretTemplate { - Raw = raw; - References = references; - } - - /// Gets the text exactly as the document wrote it. - public string Raw { get; } + private SecretTemplate(string raw, IReadOnlyList references) + { + Raw = raw; + References = references; + } - /// Gets the references the text holds, in the order they appear. - public IReadOnlyList References { get; } + /// Gets the text exactly as the document wrote it. + public string Raw { get; } - /// Reports whether the text holds at least one reference. - public bool HasSecretReferences => References.Count > 0; + /// Gets the references the text holds, in the order they appear. + public IReadOnlyList References { get; } - /// Reads a string and finds every reference it holds. - /// The raw configuration string. - /// The template. - public static SecretTemplate Parse(string text) - { - ArgumentNullException.ThrowIfNull(text); + /// Reports whether the text holds at least one reference. + public bool HasSecretReferences => References.Count > 0; - List? references = null; - var index = 0; - while (true) + /// Reads a string and finds every reference it holds. + /// The raw configuration string. + /// The template. + public static SecretTemplate Parse(string text) { - var start = text.IndexOf(SecretReference.Prefix, index, StringComparison.Ordinal); - if (start < 0) + ArgumentNullException.ThrowIfNull(text); + + List? references = null; + int index = 0; + while (true) { - break; + int start = text.IndexOf(SecretReference.Prefix, index, StringComparison.Ordinal); + if (start < 0) + { + break; + } + + int nameStart = start + SecretReference.Prefix.Length; + int end = text.IndexOf('}', nameStart); + if (end < 0) + { + break; + } + + string name = text[nameStart..end]; + if (name.Length > 0) + { + references ??= []; + references.Add(new SecretReference(name, start, end - start + 1)); + } + + index = end + 1; } - var nameStart = start + SecretReference.Prefix.Length; - var end = text.IndexOf('}', nameStart); - if (end < 0) + return new SecretTemplate( + text, + references is null ? [] : references.ToArray()); + } + + /// Rebuilds the text with every reference replaced by its resolved value. + /// A function from a secret name to its value. + /// The text with no reference left in it. + public string Format(Func resolve) + { + ArgumentNullException.ThrowIfNull(resolve); + + if (References.Count == 0) { - break; + return Raw; } - var name = text[nameStart..end]; - if (name.Length > 0) + StringBuilder builder = new(Raw.Length); + int cursor = 0; + foreach (SecretReference reference in References) { - references ??= []; - references.Add(new SecretReference(name, start, end - start + 1)); + _ = builder.Append(Raw, cursor, reference.Start - cursor); + _ = builder.Append(resolve(reference.Name)); + cursor = reference.Start + reference.Length; } - index = end + 1; + _ = builder.Append(Raw, cursor, Raw.Length - cursor); + return builder.ToString(); } - return new SecretTemplate( - text, - references is null ? [] : references.ToArray()); - } - - /// Rebuilds the text with every reference replaced by its resolved value. - /// A function from a secret name to its value. - /// The text with no reference left in it. - public string Format(Func resolve) - { - ArgumentNullException.ThrowIfNull(resolve); - - if (References.Count == 0) + /// Writes the raw text. + /// The raw text. + public override string ToString() { return Raw; } - - var builder = new StringBuilder(Raw.Length); - var cursor = 0; - foreach (var reference in References) - { - builder.Append(Raw, cursor, reference.Start - cursor); - builder.Append(resolve(reference.Name)); - cursor = reference.Start + reference.Length; - } - - builder.Append(Raw, cursor, Raw.Length - cursor); - return builder.ToString(); } - - /// Writes the raw text. - /// The raw text. - public override string ToString() => Raw; } diff --git a/src/AgentCore.Application/Configuration/Parsing/YamlToJson.cs b/src/AgentCore.Application/Configuration/Parsing/YamlToJson.cs index e180d405..4e6fbd49 100644 --- a/src/AgentCore.Application/Configuration/Parsing/YamlToJson.cs +++ b/src/AgentCore.Application/Configuration/Parsing/YamlToJson.cs @@ -4,251 +4,239 @@ using YamlDotNet.Core; using YamlDotNet.RepresentationModel; -namespace AgentCore.Application.Configuration.Parsing; - -/// -/// The first stage of the pipeline in section 6: YamlDotNet to . This is D20. -/// -/// -/// -/// A plain scalar takes its type from the YAML 1.2 core schema, so 3 and 0x10 become -/// numbers, true becomes a boolean, and gpt-4.1-mini, yes and 2024-01-01 -/// stay strings. A quoted, literal, or folded scalar always stays a string, and an explicit -/// !!str tag forces one. This is what makes rule 17 of section 11 hold: the same document -/// produces the same node tree as YAML and as JSON. -/// -/// -/// Yaml2JsonNode, by the maintainer of the JsonSchema.Net and JsonLogic packages this -/// assembly already carries, was measured against this file and does not resolve the core schema. -/// It reads a plain scalar with decimal.TryParse(NumberStyles.Any) and ignores the tag, so -/// 0x10 becomes the string "0x10", !!str 1 becomes the number 1, and — the reason it -/// was not adopted — 1,000 becomes the number 1000 and (5) becomes the number -5, -/// which turns a typo in a customer document into a value that passes check 1. See the Task 5 row -/// of docs/handoff/library-first-cleanup.md. -/// -/// -public static partial class YamlToJson +namespace AgentCore.Application.Configuration.Parsing { - private const string YamlTagPrefix = "tag:yaml.org,2002:"; - - /// Reads a YAML document and returns it as a JSON node tree. - /// The YAML text of exactly one document. - /// The node tree. - /// The text is not one well-formed YAML document. - public static JsonNode Parse(string yaml) + /// + /// The first stage of the pipeline in section 6: YamlDotNet to . This is D20. + /// + /// + /// + /// A plain scalar takes its type from the YAML 1.2 core schema, so 3 and 0x10 become + /// numbers, true becomes a boolean, and gpt-4.1-mini, yes and 2024-01-01 + /// stay strings. A quoted, literal, or folded scalar always stays a string, and an explicit + /// !!str tag forces one. This is what makes rule 17 of section 11 hold: the same document + /// produces the same node tree as YAML and as JSON. + /// + /// + /// Yaml2JsonNode, by the maintainer of the JsonSchema.Net and JsonLogic packages this + /// assembly already carries, was measured against this file and does not resolve the core schema. + /// It reads a plain scalar with decimal.TryParse(NumberStyles.Any) and ignores the tag, so + /// 0x10 becomes the string "0x10", !!str 1 becomes the number 1, and — the reason it + /// was not adopted — 1,000 becomes the number 1000 and (5) becomes the number -5, + /// which turns a typo in a customer document into a value that passes check 1. See the Task 5 row + /// of docs/handoff/library-first-cleanup.md. + /// + /// + public static partial class YamlToJson { - ArgumentNullException.ThrowIfNull(yaml); - - var stream = new YamlStream(); - try - { - stream.Load(new StringReader(yaml)); - } - catch (YamlException exception) - { - throw Syntax( - ConfigurationError.RootPointer, - $"the document is not well-formed YAML at line {exception.Start.Line}, column {exception.Start.Column}: {exception.Message}", - exception); - } - catch (Exception exception) when (exception is InvalidOperationException or ArgumentException or FormatException) - { - // The scanner reports a few malformed inputs through a plain framework exception. - throw Syntax( - ConfigurationError.RootPointer, - $"the document is not well-formed YAML: {exception.Message}", - exception); - } + private const string YamlTagPrefix = "tag:yaml.org,2002:"; - if (stream.Documents.Count != 1) + /// Reads a YAML document and returns it as a JSON node tree. + /// The YAML text of exactly one document. + /// The node tree. + /// The text is not one well-formed YAML document. + public static JsonNode Parse(string yaml) { - throw Syntax( - ConfigurationError.RootPointer, - $"the text holds {stream.Documents.Count} YAML documents, and exactly one is expected"); - } - - return Convert(stream.Documents[0].RootNode, ConfigurationError.RootPointer) - ?? throw Syntax(ConfigurationError.RootPointer, "the document is empty"); - } - - private static JsonNode? Convert(YamlNode node, string pointer) => node switch - { - YamlMappingNode mapping => ConvertMapping(mapping, pointer), - YamlSequenceNode sequence => ConvertSequence(sequence, pointer), - YamlScalarNode scalar => ConvertScalar(scalar, pointer), - _ => throw Syntax(pointer, "the node kind is not supported here"), - }; + ArgumentNullException.ThrowIfNull(yaml); - private static JsonObject ConvertMapping(YamlMappingNode mapping, string pointer) - { - var result = new JsonObject(); - foreach (var pair in mapping.Children) - { - if (pair.Key is not YamlScalarNode key || key.Value is null) + YamlStream stream = []; + try { - throw Syntax(pointer, "a mapping key must be a scalar"); + stream.Load(new StringReader(yaml)); } - - var childPointer = ConfigurationError.AppendPointer(pointer, key.Value); - - // YamlDotNet rejects two keys that are the same YAML node, so this looks redundant. It is - // not: two keys that differ as YAML nodes can still be the same JSON key. `!!str 1:` and - // `1:` carry different tags, so the YAML reader keeps both, and both name the property - // "1" here. Without this the second would silently overwrite the first. - if (result.ContainsKey(key.Value)) + catch (YamlException exception) + { + throw Syntax( + ConfigurationError.RootPointer, + $"the document is not well-formed YAML at line {exception.Start.Line}, column {exception.Start.Column}: {exception.Message}", + exception); + } + catch (Exception exception) when (exception is InvalidOperationException or ArgumentException or FormatException) { - throw Syntax(childPointer, $"the key '{key.Value}' appears twice in the same mapping"); + // The scanner reports a few malformed inputs through a plain framework exception. + throw Syntax( + ConfigurationError.RootPointer, + $"the document is not well-formed YAML: {exception.Message}", + exception); } - result[key.Value] = Convert(pair.Value, childPointer); + return stream.Documents.Count != 1 + ? throw Syntax( + ConfigurationError.RootPointer, + $"the text holds {stream.Documents.Count} YAML documents, and exactly one is expected") + : Convert(stream.Documents[0].RootNode, ConfigurationError.RootPointer) + ?? throw Syntax(ConfigurationError.RootPointer, "the document is empty"); } - return result; - } - - private static JsonArray ConvertSequence(YamlSequenceNode sequence, string pointer) - { - var result = new JsonArray(); - var index = 0; - foreach (var child in sequence.Children) + private static JsonNode? Convert(YamlNode node, string pointer) { - result.Add(Convert(child, ConfigurationError.AppendPointer(pointer, index))); - index++; + return node switch + { + YamlMappingNode mapping => ConvertMapping(mapping, pointer), + YamlSequenceNode sequence => ConvertSequence(sequence, pointer), + YamlScalarNode scalar => ConvertScalar(scalar, pointer), + _ => throw Syntax(pointer, "the node kind is not supported here"), + }; } - return result; - } + private static JsonObject ConvertMapping(YamlMappingNode mapping, string pointer) + { + JsonObject result = []; + foreach (KeyValuePair pair in mapping.Children) + { + if (pair.Key is not YamlScalarNode key || key.Value is null) + { + throw Syntax(pointer, "a mapping key must be a scalar"); + } + + string childPointer = ConfigurationError.AppendPointer(pointer, key.Value); + + // YamlDotNet rejects two keys that are the same YAML node, so this looks redundant. It is + // not: two keys that differ as YAML nodes can still be the same JSON key. `!!str 1:` and + // `1:` carry different tags, so the YAML reader keeps both, and both name the property + // "1" here. Without this the second would silently overwrite the first. + if (result.ContainsKey(key.Value)) + { + throw Syntax(childPointer, $"the key '{key.Value}' appears twice in the same mapping"); + } + + result[key.Value] = Convert(pair.Value, childPointer); + } - private static JsonValue? ConvertScalar(YamlScalarNode scalar, string pointer) - { - var text = scalar.Value ?? string.Empty; - var tag = scalar.Tag.IsEmpty ? null : scalar.Tag.Value; + return result; + } - if (tag is not null && tag.StartsWith(YamlTagPrefix, StringComparison.Ordinal)) + private static JsonArray ConvertSequence(YamlSequenceNode sequence, string pointer) { - return ConvertTagged(tag, text, pointer); + JsonArray result = []; + int index = 0; + foreach (YamlNode child in sequence.Children) + { + result.Add(Convert(child, ConfigurationError.AppendPointer(pointer, index))); + index++; + } + + return result; } - if (tag is not null || scalar.Style is not ScalarStyle.Plain and not ScalarStyle.Any and not ScalarStyle.ForcePlain) + private static JsonValue? ConvertScalar(YamlScalarNode scalar, string pointer) { - // A quoted, literal, folded, or custom-tagged scalar is always a string. - return JsonValue.Create(text); - } + string text = scalar.Value ?? string.Empty; + string? tag = scalar.Tag.IsEmpty ? null : scalar.Tag.Value; - return ConvertPlain(text, pointer); - } + if (tag is not null && tag.StartsWith(YamlTagPrefix, StringComparison.Ordinal)) + { + return ConvertTagged(tag, text, pointer); + } - private static JsonValue? ConvertTagged(string tag, string text, string pointer) => tag switch - { - YamlTagPrefix + "str" => JsonValue.Create(text), - YamlTagPrefix + "bool" => JsonValue.Create(ParseBool(text, pointer)), - YamlTagPrefix + "int" => ParseInteger(text) ?? throw Syntax(pointer, $"'{text}' is not an integer"), - YamlTagPrefix + "float" => ParseFloat(text, pointer) ?? throw Syntax(pointer, $"'{text}' is not a number"), - YamlTagPrefix + "null" => null, - _ => throw Syntax(pointer, $"the tag '{tag}' is not supported"), - }; - - private static JsonValue? ConvertPlain(string text, string pointer) - { - if (NullPattern().IsMatch(text)) - { - return null; + if (tag is not null || scalar.Style is not ScalarStyle.Plain and not ScalarStyle.Any and not ScalarStyle.ForcePlain) + { + // A quoted, literal, folded, or custom-tagged scalar is always a string. + return JsonValue.Create(text); + } + + return ConvertPlain(text, pointer); } - if (TruePattern().IsMatch(text)) + private static JsonValue? ConvertTagged(string tag, string text, string pointer) { - return JsonValue.Create(true); + return tag switch + { + YamlTagPrefix + "str" => JsonValue.Create(text), + YamlTagPrefix + "bool" => JsonValue.Create(ParseBool(text, pointer)), + YamlTagPrefix + "int" => ParseInteger(text) ?? throw Syntax(pointer, $"'{text}' is not an integer"), + YamlTagPrefix + "float" => ParseFloat(text, pointer) ?? throw Syntax(pointer, $"'{text}' is not a number"), + YamlTagPrefix + "null" => null, + _ => throw Syntax(pointer, $"the tag '{tag}' is not supported"), + }; } - if (FalsePattern().IsMatch(text)) + private static JsonValue? ConvertPlain(string text, string pointer) { - return JsonValue.Create(false); + return text switch + { + _ when NullPattern().IsMatch(text) => null, + _ when TruePattern().IsMatch(text) => JsonValue.Create(true), + _ when FalsePattern().IsMatch(text) => JsonValue.Create(false), + _ => ParseInteger(text) ?? ParseFloat(text, pointer) ?? JsonValue.Create(text), + }; } - return ParseInteger(text) ?? ParseFloat(text, pointer) ?? JsonValue.Create(text); - } - - private static bool ParseBool(string text, string pointer) - { - if (TruePattern().IsMatch(text)) + private static bool ParseBool(string text, string pointer) { - return true; + return text switch + { + _ when TruePattern().IsMatch(text) => true, + _ when FalsePattern().IsMatch(text) => false, + _ => throw Syntax(pointer, $"'{text}' is not a boolean"), + }; } - if (FalsePattern().IsMatch(text)) + private static JsonValue? ParseInteger(string text) { - return false; + return text switch + { + _ when DecimalIntegerPattern().IsMatch(text) + && long.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out long value) => JsonValue.Create(value), + _ when HexIntegerPattern().IsMatch(text) + && long.TryParse(text.AsSpan(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out long hex) => JsonValue.Create(hex), + _ => null, + }; } - throw Syntax(pointer, $"'{text}' is not a boolean"); - } - - private static JsonValue? ParseInteger(string text) - { - if (DecimalIntegerPattern().IsMatch(text) - && long.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out var value)) + /// Reads a plain scalar that looks like a YAML 1.2 float. + /// The scalar text. + /// The pointer to the scalar, for the error. + /// The number, or when the text is not a float and stays a string. + /// + /// A number too large for a parses to an infinity, and JSON has no way to + /// write one. Left alone it would reach JsonValue.Create and come back out of the loader + /// as a raw , past the + /// every caller of section 8.7 is told to catch. It is a defect in the document, so it is + /// reported as one. + /// + private static JsonValue? ParseFloat(string text, string pointer) { - return JsonValue.Create(value); + return FloatPattern().IsMatch(text) && double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out double value) + ? Finite(value, text, pointer) + : null; } - if (HexIntegerPattern().IsMatch(text) - && long.TryParse(text.AsSpan(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out var hex)) + private static JsonValue Finite(double value, string text, string pointer) { - return JsonValue.Create(hex); + return double.IsFinite(value) + ? JsonValue.Create(value) + : throw Syntax(pointer, $"'{text}' is larger than a number can hold"); } - return null; - } - - /// Reads a plain scalar that looks like a YAML 1.2 float. - /// The scalar text. - /// The pointer to the scalar, for the error. - /// The number, or when the text is not a float and stays a string. - /// - /// A number too large for a parses to an infinity, and JSON has no way to - /// write one. Left alone it would reach JsonValue.Create and come back out of the loader - /// as a raw , past the - /// every caller of section 8.7 is told to catch. It is a defect in the document, so it is - /// reported as one. - /// - private static JsonValue? ParseFloat(string text, string pointer) - { - if (!FloatPattern().IsMatch(text) - || !double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out var value)) + private static ConfigurationLoadException Syntax(string pointer, string message, Exception? cause = null) { - return null; + return new( + new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.Syntax, + }, + cause); } - return double.IsFinite(value) - ? JsonValue.Create(value) - : throw Syntax(pointer, $"'{text}' is larger than a number can hold"); - } - - private static ConfigurationLoadException Syntax(string pointer, string message, Exception? cause = null) - => new( - new ConfigurationError - { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.Syntax, - }, - cause); - - [GeneratedRegex(@"^(null|Null|NULL|~)?$")] - private static partial Regex NullPattern(); + [GeneratedRegex(@"^(null|Null|NULL|~)?$")] + private static partial Regex NullPattern(); - [GeneratedRegex("^(true|True|TRUE)$")] - private static partial Regex TruePattern(); + [GeneratedRegex("^(true|True|TRUE)$")] + private static partial Regex TruePattern(); - [GeneratedRegex("^(false|False|FALSE)$")] - private static partial Regex FalsePattern(); + [GeneratedRegex("^(false|False|FALSE)$")] + private static partial Regex FalsePattern(); - [GeneratedRegex("^[-+]?[0-9]+$")] - private static partial Regex DecimalIntegerPattern(); + [GeneratedRegex("^[-+]?[0-9]+$")] + private static partial Regex DecimalIntegerPattern(); - [GeneratedRegex("^0[xX][0-9a-fA-F]+$")] - private static partial Regex HexIntegerPattern(); + [GeneratedRegex("^0[xX][0-9a-fA-F]+$")] + private static partial Regex HexIntegerPattern(); - [GeneratedRegex(@"^[-+]?(\.[0-9]+|[0-9]+(\.[0-9]*)?)([eE][-+]?[0-9]+)?$")] - private static partial Regex FloatPattern(); + [GeneratedRegex(@"^[-+]?(\.[0-9]+|[0-9]+(\.[0-9]*)?)([eE][-+]?[0-9]+)?$")] + private static partial Regex FloatPattern(); + } } diff --git a/src/AgentCore.Application/Configuration/Schema/AgentCoreConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentCoreConfiguration.cs index 42779493..03f767e6 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentCoreConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentCoreConfiguration.cs @@ -1,72 +1,73 @@ using System.Collections.ObjectModel; using System.Text.Json.Nodes; -namespace AgentCore.Application.Configuration.Schema; - -/// -/// One apiVersion: agentcore/v1 configuration document, bound to records. -/// -/// -/// -/// The parser produces this after check 1 of section 8.5 passes. Checks 2 to 8 read it, and the -/// compile table in section 8.2 turns it into an agent. -/// -/// -/// Do not compare two of these for equality. The collection properties are BCL interfaces, -/// so the compiler-written record equality compares them by reference and two loads of the same -/// document are never equal. Nothing in AgentCore compares two configurations, and rule 17 of -/// section 11 — the same document loads identically as YAML and as JSON — is proved where it is -/// stronger: on the raw document trees, through , -/// which also catches keys these records do not model. See ConfigurationRoundTripTests. -/// -/// -public sealed record AgentCoreConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// The only apiVersion value this release accepts. - public const string SupportedApiVersion = "agentcore/v1"; - - /// The spoken fallback used when the document names none. - public const string DefaultFallbackReply = "I am sorry. I could not finish that. Please say it again."; - - /// The spoken refusal used when the document names none. - public const string DefaultRefusalReply = "I am sorry. I cannot help with that request."; - - /// Gets the document version. It is always . - public required string ApiVersion { get; init; } - - /// Gets the line the caller hears when a turn fails. - public string FallbackReply { get; init; } = DefaultFallbackReply; - - /// Gets the line the caller hears when the agent refuses to answer. - public string RefusalReply { get; init; } = DefaultRefusalReply; - - /// Gets the declared state slots, keyed by slot name. - public IReadOnlyDictionary State { get; init; } = ReadOnlyDictionary.Empty; - - /// Gets the extractor settings, or when the document declares none. - public ExtractorConfiguration? Extractor { get; init; } - - /// Gets the named guards, keyed by guard name. Each value is a raw JSONLogic rule. - public IReadOnlyDictionary Guards { get; init; } = ReadOnlyDictionary.Empty; - - /// Gets the declared tools, in document order. - public IReadOnlyList Tools { get; init; } = []; - - /// Gets the declared MCP servers, in document order. - public IReadOnlyList Mcp { get; init; } = []; - - /// Gets the shared agent pool. - public required AgentsConfiguration Agents { get; init; } - - /// Gets the named entries, keyed by entry name. The key is the agent name. - public required IReadOnlyDictionary Entries { get; init; } - - /// Gets the adapter settings, or when the document declares none. - public ProvidersConfiguration? Providers { get; init; } - - /// Gets the evaluation settings, or when the document declares none. - public EvaluationConfiguration? Evaluation { get; init; } - - /// Gets the titler settings, or when the document declares none. - public TitlerConfiguration? Titler { get; init; } + /// + /// One apiVersion: agentcore/v1 configuration document, bound to records. + /// + /// + /// + /// The parser produces this after check 1 of section 8.5 passes. Checks 2 to 8 read it, and the + /// compile table in section 8.2 turns it into an agent. + /// + /// + /// Do not compare two of these for equality. The collection properties are BCL interfaces, + /// so the compiler-written record equality compares them by reference and two loads of the same + /// document are never equal. Nothing in AgentCore compares two configurations, and rule 17 of + /// section 11 — the same document loads identically as YAML and as JSON — is proved where it is + /// stronger: on the raw document trees, through , + /// which also catches keys these records do not model. See ConfigurationRoundTripTests. + /// + /// + public sealed record AgentCoreConfiguration + { + /// The only apiVersion value this release accepts. + public const string SupportedApiVersion = "agentcore/v1"; + + /// The spoken fallback used when the document names none. + public const string DefaultFallbackReply = "I am sorry. I could not finish that. Please say it again."; + + /// The spoken refusal used when the document names none. + public const string DefaultRefusalReply = "I am sorry. I cannot help with that request."; + + /// Gets the document version. It is always . + public required string ApiVersion { get; init; } + + /// Gets the line the caller hears when a turn fails. + public string FallbackReply { get; init; } = DefaultFallbackReply; + + /// Gets the line the caller hears when the agent refuses to answer. + public string RefusalReply { get; init; } = DefaultRefusalReply; + + /// Gets the declared state slots, keyed by slot name. + public IReadOnlyDictionary State { get; init; } = ReadOnlyDictionary.Empty; + + /// Gets the extractor settings, or when the document declares none. + public ExtractorConfiguration? Extractor { get; init; } + + /// Gets the named guards, keyed by guard name. Each value is a raw JSONLogic rule. + public IReadOnlyDictionary Guards { get; init; } = ReadOnlyDictionary.Empty; + + /// Gets the declared tools, in document order. + public IReadOnlyList Tools { get; init; } = []; + + /// Gets the declared MCP servers, in document order. + public IReadOnlyList Mcp { get; init; } = []; + + /// Gets the shared agent pool. + public required AgentsConfiguration Agents { get; init; } + + /// Gets the named entries, keyed by entry name. The key is the agent name. + public required IReadOnlyDictionary Entries { get; init; } + + /// Gets the adapter settings, or when the document declares none. + public ProvidersConfiguration? Providers { get; init; } + + /// Gets the evaluation settings, or when the document declares none. + public EvaluationConfiguration? Evaluation { get; init; } + + /// Gets the titler settings, or when the document declares none. + public TitlerConfiguration? Titler { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/AgentLoopConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentLoopConfiguration.cs index 6e1716ad..b3f0eca0 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentLoopConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentLoopConfiguration.cs @@ -1,27 +1,28 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The options one loop.until: entry carries. Empty today: the entry names the condition by -/// its key. A condition that ever takes options adds members here. -/// -public sealed record LoopConditionOptions { } - -/// One loop.until: entry. Exactly one member is set. -public sealed record LoopUntilConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the condition that the todo list drains to empty. Set, or . - public LoopConditionOptions? Todos { get; init; } + /// + /// The options one loop.until: entry carries. Empty today: the entry names the condition by + /// its key. A condition that ever takes options adds members here. + /// + public sealed record LoopConditionOptions { } - /// Gets the condition that every background task finishes. Set, or . - public LoopConditionOptions? Background { get; init; } -} + /// One loop.until: entry. Exactly one member is set. + public sealed record LoopUntilConfiguration + { + /// Gets the condition that the todo list drains to empty. Set, or . + public LoopConditionOptions? Todos { get; init; } -/// One agent's loop: block: how many model rounds the agent owns may run, and when none stays. -public sealed record LoopConfiguration -{ - /// Gets the most rounds the loop may run, or for the framework default. - public int? MaxRounds { get; init; } + /// Gets the condition that every background task finishes. Set, or . + public LoopConditionOptions? Background { get; init; } + } + + /// One agent's loop: block: how many model rounds the agent owns may run, and when none stays. + public sealed record LoopConfiguration + { + /// Gets the most rounds the loop may run, or for the framework default. + public int? MaxRounds { get; init; } - /// Gets the conditions that end the loop early, in document order, or for none. - public IReadOnlyList? Until { get; init; } -} \ No newline at end of file + /// Gets the conditions that end the loop early, in document order, or for none. + public IReadOnlyList? Until { get; init; } + } +} diff --git a/src/AgentCore.Application/Configuration/Schema/AgentMemoryConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentMemoryConfiguration.cs index cb50f4d5..fa84d2bb 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentMemoryConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentMemoryConfiguration.cs @@ -1,34 +1,35 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// The stores an agentic file block may name. -public enum AgentFileStoreKind +namespace AgentCore.Application.Configuration.Schema { + /// The stores an agentic file block may name. + public enum AgentFileStoreKind + { + /// + /// The host-created per-conversation directory: AgentCoreOptions.WorkspaceRoot/<conversationId>/, + /// created with the conversation and deleted with it. The one store no process decides for a caller. + /// + Workspace, + } + /// - /// The host-created per-conversation directory: AgentCoreOptions.WorkspaceRoot/<conversationId>/, - /// created with the conversation and deleted with it. The one store no process decides for a caller. + /// One agent's memory: block: the file_memory_* tools over a store. The provider + /// keeps its working folder in the session state (§3.5), so a resumed conversation reads the same files. /// - Workspace, -} - -/// -/// One agent's memory: block: the file_memory_* tools over a store. The provider -/// keeps its working folder in the session state (§3.5), so a resumed conversation reads the same files. -/// -public sealed record AgentMemoryConfiguration -{ - /// Gets the store the file-memory tools reach. - public required AgentFileStoreKind Store { get; init; } -} + public sealed record AgentMemoryConfiguration + { + /// Gets the store the file-memory tools reach. + public required AgentFileStoreKind Store { get; init; } + } -/// -/// One agent's files: block: the file_access_* tools over a store. Today every -/// file_access_* tool is approval-required by default, reads included (§3.6). -/// -public sealed record AgentFilesConfiguration -{ - /// Gets the store the file-access tools reach. - public required AgentFileStoreKind Store { get; init; } + /// + /// One agent's files: block: the file_access_* tools over a store. Today every + /// file_access_* tool is approval-required by default, reads included (§3.6). + /// + public sealed record AgentFilesConfiguration + { + /// Gets the store the file-access tools reach. + public required AgentFileStoreKind Store { get; init; } - /// Gets whether the write tools are enabled. write: false leaves read, read_lines, ls, grep. - public bool Write { get; init; } = true; -} \ No newline at end of file + /// Gets whether the write tools are enabled. write: false leaves read, read_lines, ls, grep. + public bool Write { get; init; } = true; + } +} diff --git a/src/AgentCore.Application/Configuration/Schema/AgentShellConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentShellConfiguration.cs index 289d6be1..6a6602ed 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentShellConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentShellConfiguration.cs @@ -1,62 +1,63 @@ using System.Collections.ObjectModel; using AgentCore.Application.Configuration.Parsing; -namespace AgentCore.Application.Configuration.Schema; - -/// The executors a shell: block may name. -public enum ShellKind +namespace AgentCore.Application.Configuration.Schema { - /// A throwaway container: network "none", read-only root, nobody user (§3.6). - Docker, + /// The executors a shell: block may name. + public enum ShellKind + { + /// A throwaway container: network "none", read-only root, nobody user (§3.6). + Docker, - /// The process's own executable environment, confined to the workspace directory. - Local, -} + /// The process's own executable environment, confined to the workspace directory. + Local, + } -/// -/// One agent's shell policy: the regexes that refuse a command before it dispatches. A guardrail -/// for the model, not a security boundary — the executor confinement is the boundary. -/// -public sealed record ShellPolicyConfiguration -{ - /// Gets the patterns whose match refuses a command. - public IReadOnlyList Deny { get; init; } = []; - - /// Gets the patterns an allowed command must match. - public IReadOnlyList Allow { get; init; } = []; -} - -/// One agent's shell: block: one executor per conversation, removed with it (§4.4). -public sealed record ShellConfiguration -{ /// - /// Gets the executor kind. Deliberately required: where a shell runs is the consumer's conversation, so - /// no default exists here (§4.5.1). + /// One agent's shell policy: the regexes that refuse a command before it dispatches. A guardrail + /// for the model, not a security boundary — the executor confinement is the boundary. /// - public required ShellKind Kind { get; init; } - - /// Gets the command policy, or for none. - public ShellPolicyConfiguration? Policy { get; init; } - - /// Gets how long one command may run, or for the executor default. - public int? TimeoutSeconds { get; init; } - - /// - /// Gets the environment passed to the executor, on top of the one the executor kind already - /// supplies. A value may hold ${secret:name} references. - /// - public IReadOnlyDictionary Env { get; init; } - = ReadOnlyDictionary.Empty; - - /// Gets the per-stream output cap, in KiB, or for the executor default. - public int? MaxOutputKb { get; init; } - - /// Gets the container image. only. - public string? Image { get; init; } - - /// Gets the Docker network mode. only. - public string? Network { get; init; } - - /// Gets the container memory limit, in MB. only. - public int? MemoryMb { get; init; } -} \ No newline at end of file + public sealed record ShellPolicyConfiguration + { + /// Gets the patterns whose match refuses a command. + public IReadOnlyList Deny { get; init; } = []; + + /// Gets the patterns an allowed command must match. + public IReadOnlyList Allow { get; init; } = []; + } + + /// One agent's shell: block: one executor per conversation, removed with it (§4.4). + public sealed record ShellConfiguration + { + /// + /// Gets the executor kind. Deliberately required: where a shell runs is the consumer's conversation, so + /// no default exists here (§4.5.1). + /// + public required ShellKind Kind { get; init; } + + /// Gets the command policy, or for none. + public ShellPolicyConfiguration? Policy { get; init; } + + /// Gets how long one command may run, or for the executor default. + public int? TimeoutSeconds { get; init; } + + /// + /// Gets the environment passed to the executor, on top of the one the executor kind already + /// supplies. A value may hold ${secret:name} references. + /// + public IReadOnlyDictionary Env { get; init; } + = ReadOnlyDictionary.Empty; + + /// Gets the per-stream output cap, in KiB, or for the executor default. + public int? MaxOutputKb { get; init; } + + /// Gets the container image. only. + public string? Image { get; init; } + + /// Gets the Docker network mode. only. + public string? Network { get; init; } + + /// Gets the container memory limit, in MB. only. + public int? MemoryMb { get; init; } + } +} diff --git a/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs index 02dd5654..7ebc5236 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs @@ -1,145 +1,146 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// How an agent reaches the knowledge base. -public enum KnowledgeMode +namespace AgentCore.Application.Configuration.Schema { - /// Retrieve before the model is called, and inject the cards. One model round trip. - Prefetch, + /// How an agent reaches the knowledge base. + public enum KnowledgeMode + { + /// Retrieve before the model is called, and inject the cards. One model round trip. + Prefetch, - /// Give the model a search tool and let it decide. - Tool, -} + /// Give the model a search tool and let it decide. + Tool, + } -/// -/// One agent's knowledge: block. Every field is optional, so an unset field is distinct -/// from one set to its default and can inherit key by key. -/// -public sealed record AgentKnowledgeConfiguration -{ /// - /// The largest value may carry. + /// One agent's knowledge: block. Every field is optional, so an unset field is distinct + /// from one set to its default and can inherit key by key. /// - public const int MaximumLimit = 20; + public sealed record AgentKnowledgeConfiguration + { + /// + /// The largest value may carry. + /// + public const int MaximumLimit = 20; - /// Gets the mode, or to inherit. - public KnowledgeMode? Mode { get; init; } + /// Gets the mode, or to inherit. + public KnowledgeMode? Mode { get; init; } - /// Gets how many cards to retrieve, or to inherit. - public int? Limit { get; init; } + /// Gets how many cards to retrieve, or to inherit. + public int? Limit { get; init; } - /// Gets whether the model sees the source label, or to inherit. - public bool? Citations { get; init; } + /// Gets whether the model sees the source label, or to inherit. + public bool? Citations { get; init; } - /// Gets whether this agent's searches are confined to a scope, or to inherit. - public bool? Scoped { get; init; } -} + /// Gets whether this agent's searches are confined to a scope, or to inherit. + public bool? Scoped { get; init; } + } -/// -/// The settings every agent inherits. -/// -public sealed record AgentDefaults -{ - /// Gets the model every agent uses unless it names its own. - public ModelReference? Model { get; init; } - - /// Gets the shared instruction prefix, or . - public string? Instructions { get; init; } + /// + /// The settings every agent inherits. + /// + public sealed record AgentDefaults + { + /// Gets the model every agent uses unless it names its own. + public ModelReference? Model { get; init; } - /// Gets the shared knowledge: block, or when the document declares none. - public AgentKnowledgeConfiguration? Knowledge { get; init; } + /// Gets the shared instruction prefix, or . + public string? Instructions { get; init; } - /// Gets whether agents inherit the todo tools, or to name nothing. - public bool? Todos { get; init; } + /// Gets the shared knowledge: block, or when the document declares none. + public AgentKnowledgeConfiguration? Knowledge { get; init; } - /// Gets whether agents inherit the mode tools, or to name nothing. - public bool? Mode { get; init; } + /// Gets whether agents inherit the todo tools, or to name nothing. + public bool? Todos { get; init; } - /// Gets whether agents are told the current date and time each turn, or to name nothing. - public bool? Clock { get; init; } + /// Gets whether agents inherit the mode tools, or to name nothing. + public bool? Mode { get; init; } - /// Gets whether the framework's base instructions sit above , or to name nothing. - public bool? BaseInstructions { get; init; } + /// Gets whether agents are told the current date and time each turn, or to name nothing. + public bool? Clock { get; init; } - /// Gets the shared approval: block, or when the document declares none. - public ApprovalConfiguration? Approval { get; init; } -} + /// Gets whether the framework's base instructions sit above , or to name nothing. + public bool? BaseInstructions { get; init; } -/// -/// One declared agent. -/// -public sealed record AgentConfiguration -{ - /// Gets the agent id. A stage or a graph node names this id. - public required string Id { get; init; } + /// Gets the shared approval: block, or when the document declares none. + public ApprovalConfiguration? Approval { get; init; } + } /// - /// Gets the one-line summary a parent sees when this agent is listed as a background child, - /// or to list the id alone. + /// One declared agent. /// - public string? Description { get; init; } + public sealed record AgentConfiguration + { + /// Gets the agent id. A stage or a graph node names this id. + public required string Id { get; init; } - /// Gets the instruction delta this agent appends below the shared prefix. - public string? Instructions { get; init; } + /// + /// Gets the one-line summary a parent sees when this agent is listed as a background child, + /// or to list the id alone. + /// + public string? Description { get; init; } - /// Gets the model of this agent, or to inherit the default. - public ModelReference? Model { get; init; } + /// Gets the instruction delta this agent appends below the shared prefix. + public string? Instructions { get; init; } - /// Gets the ids of the tools this agent may conversation. - public IReadOnlyList Tools { get; init; } = []; + /// Gets the model of this agent, or to inherit the default. + public ModelReference? Model { get; init; } - /// Gets the names of the skills this agent may load. - public IReadOnlyList Skills { get; init; } = []; + /// Gets the ids of the tools this agent may conversation. + public IReadOnlyList Tools { get; init; } = []; - /// - /// Gets the names of the skills whose body sits in this agent's system prompt on every turn, - /// - public IReadOnlyList Pinned { get; init; } = []; + /// Gets the names of the skills this agent may load. + public IReadOnlyList Skills { get; init; } = []; - /// Gets this agent's knowledge: block, or to inherit key by key. - public AgentKnowledgeConfiguration? Knowledge { get; init; } + /// + /// Gets the names of the skills whose body sits in this agent's system prompt on every turn, + /// + public IReadOnlyList Pinned { get; init; } = []; - /// Gets whether this agent gets the todo tools, or to inherit. - public bool? Todos { get; init; } + /// Gets this agent's knowledge: block, or to inherit key by key. + public AgentKnowledgeConfiguration? Knowledge { get; init; } - /// Gets whether this agent gets the mode tools, or to inherit. - public bool? Mode { get; init; } + /// Gets whether this agent gets the todo tools, or to inherit. + public bool? Todos { get; init; } - /// Gets whether this agent is told the current date and time each turn, or to inherit. - public bool? Clock { get; init; } + /// Gets whether this agent gets the mode tools, or to inherit. + public bool? Mode { get; init; } - /// Gets whether the framework's base instructions sit above this agent's, or to inherit. - public bool? BaseInstructions { get; init; } + /// Gets whether this agent is told the current date and time each turn, or to inherit. + public bool? Clock { get; init; } - /// Gets this agent's memory: block, or for none. - public AgentMemoryConfiguration? Memory { get; init; } + /// Gets whether the framework's base instructions sit above this agent's, or to inherit. + public bool? BaseInstructions { get; init; } - /// Gets this agent's files: block, or for none. - public AgentFilesConfiguration? Files { get; init; } + /// Gets this agent's memory: block, or for none. + public AgentMemoryConfiguration? Memory { get; init; } - /// - /// Gets this agent's shell: block, or for none. One executor per - /// conversation, never a process singleton. - /// - public ShellConfiguration? Shell { get; init; } + /// Gets this agent's files: block, or for none. + public AgentFilesConfiguration? Files { get; init; } - /// Gets this agent's approval: block, or to inherit key by key. - public ApprovalConfiguration? Approval { get; init; } + /// + /// Gets this agent's shell: block, or for none. One executor per + /// conversation, never a process singleton. + /// + public ShellConfiguration? Shell { get; init; } - /// Gets the ids of the background children this agent may start. Same list as agents.items. - public IReadOnlyList Background { get; init; } = []; + /// Gets this agent's approval: block, or to inherit key by key. + public ApprovalConfiguration? Approval { get; init; } - /// Gets this agent's loop: block, or for none. - public LoopConfiguration? Loop { get; init; } -} + /// Gets the ids of the background children this agent may start. Same list as agents.items. + public IReadOnlyList Background { get; init; } = []; -/// -/// The agents: section. -/// -public sealed record AgentsConfiguration -{ - /// Gets the shared settings, or when the document declares none. - public AgentDefaults? Defaults { get; init; } + /// Gets this agent's loop: block, or for none. + public LoopConfiguration? Loop { get; init; } + } - /// Gets the declared agents, in document order. - public required IReadOnlyList Items { get; init; } + /// + /// The agents: section. + /// + public sealed record AgentsConfiguration + { + /// Gets the shared settings, or when the document declares none. + public AgentDefaults? Defaults { get; init; } + + /// Gets the declared agents, in document order. + public required IReadOnlyList Items { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ApprovalConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ApprovalConfiguration.cs index beae44bf..fc1551ab 100644 --- a/src/AgentCore.Application/Configuration/Schema/ApprovalConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ApprovalConfiguration.cs @@ -1,14 +1,15 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// One agent's approval: block: the standing rules that answer an approval request before it -/// surfaces. Everything a rule does not name still asks. -/// -public sealed record ApprovalConfiguration +namespace AgentCore.Application.Configuration.Schema { /// - /// Gets the tool-name patterns a request never surfaces for. A pattern names one tool exactly, - /// or a prefix with a trailing *. + /// One agent's approval: block: the standing rules that answer an approval request before it + /// surfaces. Everything a rule does not name still asks. /// - public IReadOnlyList Auto { get; init; } = []; -} \ No newline at end of file + public sealed record ApprovalConfiguration + { + /// + /// Gets the tool-name patterns a request never surfaces for. A pattern names one tool exactly, + /// or a prefix with a trailing *. + /// + public IReadOnlyList Auto { get; init; } = []; + } +} diff --git a/src/AgentCore.Application/Configuration/Schema/BlobProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/BlobProviderConfiguration.cs index b44e9845..9cd03621 100644 --- a/src/AgentCore.Application/Configuration/Schema/BlobProviderConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/BlobProviderConfiguration.cs @@ -1,25 +1,26 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The blob provider: the store that keeps what a vendor's sandbox produced, and where it is. -/// -public sealed record BlobProviderConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the vendor, such as s3. - public required string Kind { get; init; } - /// - /// Gets the service URL. - /// when the vendor needs none. + /// The blob provider: the store that keeps what a vendor's sandbox produced, and where it is. /// - public string? Endpoint { get; init; } + public sealed record BlobProviderConfiguration + { + /// Gets the vendor, such as s3. + public required string Kind { get; init; } - /// Gets the bucket every blob is written into, or when the vendor needs none. - public string? Bucket { get; init; } + /// + /// Gets the service URL. + /// when the vendor needs none. + /// + public string? Endpoint { get; init; } - /// - /// Gets the region the request signature names, or to read it off the - /// endpoint host. - /// - public string? Region { get; init; } + /// Gets the bucket every blob is written into, or when the vendor needs none. + public string? Bucket { get; init; } + + /// + /// Gets the region the request signature names, or to read it off the + /// endpoint host. + /// + public string? Region { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ConversationProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ConversationProviderConfiguration.cs index e22d06e4..e681189b 100644 --- a/src/AgentCore.Application/Configuration/Schema/ConversationProviderConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ConversationProviderConfiguration.cs @@ -1,19 +1,20 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The vendor that carries the conversation, and the limits of the socket it opens. -/// -public sealed record ConversationProviderConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the vendor that carries the conversation, such as telnyx-relay. - public required string Kind { get; init; } + /// + /// The vendor that carries the conversation, and the limits of the socket it opens. + /// + public sealed record ConversationProviderConfiguration + { + /// Gets the vendor that carries the conversation, such as telnyx-relay. + public required string Kind { get; init; } - /// Gets how long the socket waits with no inbound frame before ending the conversation, or null for the adapter's default. - public int? IdleTimeoutSeconds { get; init; } + /// Gets how long the socket waits with no inbound frame before ending the conversation, or null for the adapter's default. + public int? IdleTimeoutSeconds { get; init; } - /// Gets how long teardown gives a stuck task before moving on, or null for the adapter's default. - public int? CloseTimeoutSeconds { get; init; } + /// Gets how long teardown gives a stuck task before moving on, or null for the adapter's default. + public int? CloseTimeoutSeconds { get; init; } - /// Gets the largest inbound frame the socket accepts, in bytes, or null for the adapter's default. - public int? MaxFrameBytes { get; init; } + /// Gets the largest inbound frame the socket accepts, in bytes, or null for the adapter's default. + public int? MaxFrameBytes { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs index 5cc3c7a3..8212bb69 100644 --- a/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs @@ -1,19 +1,20 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The embedding provider: the vendor that turns a query into a vector, and the model it uses. -/// -public sealed record EmbeddingProviderConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the vendor, such as openai. - public required string Kind { get; init; } - - /// Gets the model name the vendor knows, such as text-embedding-3-small. - public required string Model { get; init; } - /// - /// Gets the vector width to ask the vendor for, or for the model's own. - /// It must match the width the knowledge collection was built with. + /// The embedding provider: the vendor that turns a query into a vector, and the model it uses. /// - public int? Dimensions { get; init; } + public sealed record EmbeddingProviderConfiguration + { + /// Gets the vendor, such as openai. + public required string Kind { get; init; } + + /// Gets the model name the vendor knows, such as text-embedding-3-small. + public required string Model { get; init; } + + /// + /// Gets the vector width to ask the vendor for, or for the model's own. + /// It must match the width the knowledge collection was built with. + /// + public int? Dimensions { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/EntryConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/EntryConfiguration.cs index 695fc198..bee51cfe 100644 --- a/src/AgentCore.Application/Configuration/Schema/EntryConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/EntryConfiguration.cs @@ -1,22 +1,23 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// One named entry. The entry key is the agent name. -/// -public sealed record EntryConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the id of the agent in the shared pool, or . - public string? Agent { get; init; } + /// + /// One named entry. The entry key is the agent name. + /// + public sealed record EntryConfiguration + { + /// Gets the id of the agent in the shared pool, or . + public string? Agent { get; init; } - /// Gets the stage machine, or when the entry declares none. - public PolicyConfiguration? Policy { get; init; } + /// Gets the stage machine, or when the entry declares none. + public PolicyConfiguration? Policy { get; init; } - /// Gets the workflow graph, or when the entry declares none. - public GraphConfiguration? Graph { get; init; } + /// Gets the workflow graph, or when the entry declares none. + public GraphConfiguration? Graph { get; init; } - /// Gets the entry override for the spoken fallback, or to inherit the root line. - public string? FallbackReply { get; init; } + /// Gets the entry override for the spoken fallback, or to inherit the root line. + public string? FallbackReply { get; init; } - /// Gets the entry override for the spoken refusal, or to inherit the root line. - public string? RefusalReply { get; init; } + /// Gets the entry override for the spoken refusal, or to inherit the root line. + public string? RefusalReply { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/EvaluationConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/EvaluationConfiguration.cs index eb9fb495..ea8bcefc 100644 --- a/src/AgentCore.Application/Configuration/Schema/EvaluationConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/EvaluationConfiguration.cs @@ -1,40 +1,41 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The evaluation: section. It sets the share of finished turns a judge scores. -/// -/// -/// Triage row T18 defers online sampled evaluation and says the sample rate comes from -/// configuration, so this section holds it. Decision D9 keeps the judge off the turn: the rate -/// selects a finished turn and never delays one. The section is optional, and a document that omits -/// it takes . -/// -public sealed record EvaluationConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// The sample rate used when the document sets none. It evaluates no turn. + /// + /// The evaluation: section. It sets the share of finished turns a judge scores. + /// /// - /// T18 defers the online path until the offline gate proves the evaluators, so the seam is - /// reachable and costs nothing until a document raises the rate. + /// Triage row T18 defers online sampled evaluation and says the sample rate comes from + /// configuration, so this section holds it. Decision D9 keeps the judge off the turn: the rate + /// selects a finished turn and never delays one. The section is optional, and a document that omits + /// it takes . /// - public const double DefaultSampleRate = 0; + public sealed record EvaluationConfiguration + { + /// The sample rate used when the document sets none. It evaluates no turn. + /// + /// T18 defers the online path until the offline gate proves the evaluators, so the seam is + /// reachable and costs nothing until a document raises the rate. + /// + public const double DefaultSampleRate = 0; - /// Gets the share of finished turns to evaluate, from 0 through 1. - public double SampleRate { get; init; } = DefaultSampleRate; + /// Gets the share of finished turns to evaluate, from 0 through 1. + public double SampleRate { get; init; } = DefaultSampleRate; - /// Gets the model that scores a turn, or when the document names none. - /// - /// - /// One key serves both evaluation paths. The online path of T18 scores the sampled turn with this - /// model, and the offline golden set of D13 scores a recorded row with it, so a deployment tunes - /// one entry and both paths follow. D9 still holds: the judge reads a turn that already ended and - /// never delays one. - /// - /// - /// The key is optional. A document that names no judge still runs every evaluator that calls no - /// model, and an evaluator that needs a judge returns a metric with no value instead of a score. - /// A judge reads with temperature: 0 in practice, because a score gate cannot use a number - /// that moves for the same input. - /// - /// - public ModelReference? Judge { get; init; } + /// Gets the model that scores a turn, or when the document names none. + /// + /// + /// One key serves both evaluation paths. The online path of T18 scores the sampled turn with this + /// model, and the offline golden set of D13 scores a recorded row with it, so a deployment tunes + /// one entry and both paths follow. D9 still holds: the judge reads a turn that already ended and + /// never delays one. + /// + /// + /// The key is optional. A document that names no judge still runs every evaluator that calls no + /// model, and an evaluator that needs a judge returns a metric with no value instead of a score. + /// A judge reads with temperature: 0 in practice, because a score gate cannot use a number + /// that moves for the same input. + /// + /// + public ModelReference? Judge { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ExtractorConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ExtractorConfiguration.cs index 9c14e609..d9e75dc2 100644 --- a/src/AgentCore.Application/Configuration/Schema/ExtractorConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ExtractorConfiguration.cs @@ -1,35 +1,36 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// When the extractor runs. Section 8.3 defines one value. -public enum ExtractorTrigger +namespace AgentCore.Application.Configuration.Schema { - /// The extractor runs against the finished turn, while the caller speaks. This is D21. - AfterReply, -} + /// When the extractor runs. Section 8.3 defines one value. + public enum ExtractorTrigger + { + /// The extractor runs against the finished turn, while the caller speaks. This is D21. + AfterReply, + } -/// -/// A pointer to one entry of providers.llm, with the conversation settings that go with it. -/// -public sealed record ModelReference -{ - /// Gets the as name of the provider entry, such as reply or fill. - public required string Ref { get; init; } + /// + /// A pointer to one entry of providers.llm, with the conversation settings that go with it. + /// + public sealed record ModelReference + { + /// Gets the as name of the provider entry, such as reply or fill. + public required string Ref { get; init; } - /// Gets the sampling temperature, or when the document sets none. - public double? Temperature { get; init; } -} + /// Gets the sampling temperature, or when the document sets none. + public double? Temperature { get; init; } + } -/// -/// The state extractor. It is the bridge from prose to typed state. -/// -/// -/// The extractor never speaks, holds no tools, and decides nothing. The guards decide. -/// -public sealed record ExtractorConfiguration -{ - /// Gets the model the extractor calls. - public required ModelReference Model { get; init; } + /// + /// The state extractor. It is the bridge from prose to typed state. + /// + /// + /// The extractor never speaks, holds no tools, and decides nothing. The guards decide. + /// + public sealed record ExtractorConfiguration + { + /// Gets the model the extractor calls. + public required ModelReference Model { get; init; } - /// Gets when the extractor runs. It defaults to . - public ExtractorTrigger When { get; init; } = ExtractorTrigger.AfterReply; + /// Gets when the extractor runs. It defaults to . + public ExtractorTrigger When { get; init; } = ExtractorTrigger.AfterReply; + } } diff --git a/src/AgentCore.Application/Configuration/Schema/GraphConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/GraphConfiguration.cs index 12f03c61..272f17ad 100644 --- a/src/AgentCore.Application/Configuration/Schema/GraphConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/GraphConfiguration.cs @@ -1,85 +1,86 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The built-in workflow shapes of row 3 of the compile table in section 8.2. -/// -public enum GraphPattern +namespace AgentCore.Application.Configuration.Schema { - /// AgentWorkflowBuilder.BuildSequential. - Sequential, + /// + /// The built-in workflow shapes of row 3 of the compile table in section 8.2. + /// + public enum GraphPattern + { + /// AgentWorkflowBuilder.BuildSequential. + Sequential, - /// AgentWorkflowBuilder.BuildConcurrent. - Concurrent, + /// AgentWorkflowBuilder.BuildConcurrent. + Concurrent, - /// AgentWorkflowBuilder.CreateHandoffBuilderWith. - /// - /// The first agent in graph.agents starts the handoff, and every other agent is a target it - /// hands to. That is fixed, and no document key moves it. D15 makes a new public key a permanent - /// obligation, so the order of graph.agents carries the decision instead. - /// - Handoff, + /// AgentWorkflowBuilder.CreateHandoffBuilderWith. + /// + /// The first agent in graph.agents starts the handoff, and every other agent is a target it + /// hands to. That is fixed, and no document key moves it. D15 makes a new public key a permanent + /// obligation, so the order of graph.agents carries the decision instead. + /// + Handoff, - /// AgentWorkflowBuilder.CreateGroupChatBuilderWith. - /// - /// The group chat is round-robin, through RoundRobinGroupChatManager. That is fixed, and no - /// document key selects another manager. D15 makes a new public key a permanent obligation, so a - /// document that needs another turn order builds an explicit graph of row 4 instead. - /// - GroupChat, -} + /// AgentWorkflowBuilder.CreateGroupChatBuilderWith. + /// + /// The group chat is round-robin, through RoundRobinGroupChatManager. That is fixed, and no + /// document key selects another manager. D15 makes a new public key a permanent obligation, so a + /// document that needs another turn order builds an explicit graph of row 4 instead. + /// + GroupChat, + } -/// -/// One node of an explicit graph. An agent binds to it as an executor. -/// -public sealed record GraphNodeConfiguration -{ - /// Gets the node id. - public required string Id { get; init; } + /// + /// One node of an explicit graph. An agent binds to it as an executor. + /// + public sealed record GraphNodeConfiguration + { + /// Gets the node id. + public required string Id { get; init; } - /// Gets the id of the agent bound to this node, or . - public string? Agent { get; init; } + /// Gets the id of the agent bound to this node, or . + public string? Agent { get; init; } - /// Gets whether the run starts here. Check 7 needs exactly one start node. - public bool Start { get; init; } + /// Gets whether the run starts here. Check 7 needs exactly one start node. + public bool Start { get; init; } - /// Gets whether the node yields an output. Check 7 needs every path to reach one. - public bool Output { get; init; } -} + /// Gets whether the node yields an output. Check 7 needs every path to reach one. + public bool Output { get; init; } + } -/// -/// One edge of an explicit graph. -/// -public sealed record GraphEdgeConfiguration -{ - /// Gets the id of the node the edge leaves. - public required string From { get; init; } + /// + /// One edge of an explicit graph. + /// + public sealed record GraphEdgeConfiguration + { + /// Gets the id of the node the edge leaves. + public required string From { get; init; } - /// Gets the id of the node the edge reaches. - public required string To { get; init; } + /// Gets the id of the node the edge reaches. + public required string To { get; init; } - /// Gets the guard on the edge, or when the edge is unconditional. - public GuardReference? When { get; init; } -} + /// Gets the guard on the edge, or when the edge is unconditional. + public GuardReference? When { get; init; } + } -/// -/// An entry's graph: block. It holds either a pattern or a node and edge list, never both. -/// -/// -/// Section 8.2 compiles the first form through AgentWorkflowBuilder and the second through -/// WorkflowBuilder and AsAIAgent(). An entry that holds more than one of -/// agent:, policy:, and graph: is a load-time error. -/// -public sealed record GraphConfiguration -{ - /// Gets the built-in shape, or when the graph lists nodes and edges. - public GraphPattern? Pattern { get; init; } + /// + /// An entry's graph: block. It holds either a pattern or a node and edge list, never both. + /// + /// + /// Section 8.2 compiles the first form through AgentWorkflowBuilder and the second through + /// WorkflowBuilder and AsAIAgent(). An entry that holds more than one of + /// agent:, policy:, and graph: is a load-time error. + /// + public sealed record GraphConfiguration + { + /// Gets the built-in shape, or when the graph lists nodes and edges. + public GraphPattern? Pattern { get; init; } - /// Gets the participants of a pattern graph, in order. It is empty for a node and edge graph. - public IReadOnlyList Agents { get; init; } = []; + /// Gets the participants of a pattern graph, in order. It is empty for a node and edge graph. + public IReadOnlyList Agents { get; init; } = []; - /// Gets the nodes. It is empty for a pattern graph. - public IReadOnlyList Nodes { get; init; } = []; + /// Gets the nodes. It is empty for a pattern graph. + public IReadOnlyList Nodes { get; init; } = []; - /// Gets the edges. It is empty for a pattern graph. - public IReadOnlyList Edges { get; init; } = []; + /// Gets the edges. It is empty for a pattern graph. + public IReadOnlyList Edges { get; init; } = []; + } } diff --git a/src/AgentCore.Application/Configuration/Schema/GuardReference.cs b/src/AgentCore.Application/Configuration/Schema/GuardReference.cs index c12d4f3f..49d67e33 100644 --- a/src/AgentCore.Application/Configuration/Schema/GuardReference.cs +++ b/src/AgentCore.Application/Configuration/Schema/GuardReference.cs @@ -1,61 +1,70 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The value of a when: field. It is a guard name or an inline JSONLogic rule. -/// -/// -/// Section 8.4 prefers a name, because the live mermaid render prints the name next to the edge and -/// an inline rule renders as an unreadable blob. Both forms are legal, so both are modelled. -/// -public sealed record GuardReference +namespace AgentCore.Application.Configuration.Schema { - private GuardReference(string? name, JsonNode? rule) + /// + /// The value of a when: field. It is a guard name or an inline JSONLogic rule. + /// + /// + /// Section 8.4 prefers a name, because the live mermaid render prints the name next to the edge and + /// an inline rule renders as an unreadable blob. Both forms are legal, so both are modelled. + /// + public sealed record GuardReference { - Name = name; - Rule = rule; - } + private GuardReference(string? name, JsonNode? rule) + { + Name = name; + Rule = rule; + } - /// Gets the name of a guard in guards:, or when the reference is inline. - public string? Name { get; } + /// Gets the name of a guard in guards:, or when the reference is inline. + public string? Name { get; } - /// Gets the raw inline JSONLogic rule, or when the reference is a name. - public JsonNode? Rule { get; } + /// Gets the raw inline JSONLogic rule, or when the reference is a name. + public JsonNode? Rule { get; } - /// Reports whether the reference names a guard in guards:. - public bool IsNamed => Name is not null; + /// Reports whether the reference names a guard in guards:. + public bool IsNamed => Name is not null; - /// Builds a reference to a named guard. - /// The guard name. - /// The reference. - public static GuardReference FromName(string name) - { - ArgumentException.ThrowIfNullOrEmpty(name); - return new GuardReference(name, null); - } + /// Builds a reference to a named guard. + /// The guard name. + /// The reference. + public static GuardReference FromName(string name) + { + ArgumentException.ThrowIfNullOrEmpty(name); + return new GuardReference(name, null); + } - /// Builds a reference that carries an inline rule. - /// The raw JSONLogic rule. - /// The reference. - public static GuardReference FromRule(JsonNode rule) - { - ArgumentNullException.ThrowIfNull(rule); - return new GuardReference(null, rule); - } + /// Builds a reference that carries an inline rule. + /// The raw JSONLogic rule. + /// The reference. + public static GuardReference FromRule(JsonNode rule) + { + ArgumentNullException.ThrowIfNull(rule); + return new GuardReference(null, rule); + } - /// Compares this reference with another reference. An inline rule compares by its JSON content. - /// The other reference. - /// when both references are equal. - public bool Equals(GuardReference? other) - => other is not null - && string.Equals(Name, other.Name, StringComparison.Ordinal) - && JsonNode.DeepEquals(Rule, other.Rule); + /// Compares this reference with another reference. An inline rule compares by its JSON content. + /// The other reference. + /// when both references are equal. + public bool Equals(GuardReference? other) + { + return other is not null + && string.Equals(Name, other.Name, StringComparison.Ordinal) + && JsonNode.DeepEquals(Rule, other.Rule); + } - /// - public override int GetHashCode() => Name is null ? 0 : StringComparer.Ordinal.GetHashCode(Name); + /// + public override int GetHashCode() + { + return Name is null ? 0 : StringComparer.Ordinal.GetHashCode(Name); + } - /// Writes the guard name, or the inline rule as JSON text. - /// A readable form of the reference. - public override string ToString() => Name ?? Rule?.ToJsonString() ?? string.Empty; + /// Writes the guard name, or the inline rule as JSON text. + /// A readable form of the reference. + public override string ToString() + { + return Name ?? Rule?.ToJsonString() ?? string.Empty; + } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs index 46e4da97..414ce5e8 100644 --- a/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs @@ -1,28 +1,29 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// One large language model, and the name a points at. -/// -public sealed record LlmProviderConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the vendor, such as openai. - public required string Kind { get; init; } + /// + /// One large language model, and the name a points at. + /// + public sealed record LlmProviderConfiguration + { + /// Gets the vendor, such as openai. + public required string Kind { get; init; } - /// Gets the model name the vendor knows. - public required string Model { get; init; } + /// Gets the model name the vendor knows. + public required string Model { get; init; } - /// Gets the name this entry answers to, such as reply or fill. - public required string As { get; init; } + /// Gets the name this entry answers to, such as reply or fill. + public required string As { get; init; } - /// - /// Gets how hard a reasoning model thinks before it answers, or to send - /// nothing and let the vendor decide. - /// - public string? ReasoningEffort { get; init; } + /// + /// Gets how hard a reasoning model thinks before it answers, or to send + /// nothing and let the vendor decide. + /// + public string? ReasoningEffort { get; init; } - /// - /// Gets whether this entry may run a hosted web search, or to let the - /// vendor's adapter decide. - /// - public bool? WebSearch { get; init; } + /// + /// Gets whether this entry may run a hosted web search, or to let the + /// vendor's adapter decide. + /// + public bool? WebSearch { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/McpServerConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/McpServerConfiguration.cs index 1a159eff..6a5149ea 100644 --- a/src/AgentCore.Application/Configuration/Schema/McpServerConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/McpServerConfiguration.cs @@ -1,96 +1,97 @@ using System.Collections.ObjectModel; using AgentCore.Application.Configuration.Parsing; -namespace AgentCore.Application.Configuration.Schema; - -/// How AgentCore talks to a declared MCP server. -public enum McpTransport +namespace AgentCore.Application.Configuration.Schema { - /// The server is a child process, spoken to over its standard streams. command: launches it. - Stdio, - - /// The server is reached over HTTP. url: names it. - Http, -} - -/// -/// One tool a server is allowed to serve. -/// -public sealed record McpAllowEntry -{ - /// Gets the tool name the server offers, or "*" to allow every tool it offers. - public required string Name { get; init; } - - /// - /// Gets the id this tool is served under, or to take the default. - /// - public string? As { get; init; } -} - -/// -/// One declared MCP server. -/// -public sealed record McpServerConfiguration -{ - /// Gets the server id. Decision 10 builds every served tool id from it. - public required string Id { get; init; } - - /// Gets how AgentCore connects to the server. - public required McpTransport Transport { get; init; } - - /// - /// Gets the executable and its arguments. Set when is . - /// - public IReadOnlyList Command { get; init; } = []; + /// How AgentCore talks to a declared MCP server. + public enum McpTransport + { + /// The server is a child process, spoken to over its standard streams. command: launches it. + Stdio, - /// Gets the server URL. Set when is . - public string? Url { get; init; } - - /// Gets the tools this server is pinned to offer. - public IReadOnlyList Allow { get; init; } = []; + /// The server is reached over HTTP. url: names it. + Http, + } /// - /// Gets the headers sent on every request. Set when is - /// . A value may hold ${secret:name} references. + /// One tool a server is allowed to serve. /// - public IReadOnlyDictionary Headers { get; init; } - = ReadOnlyDictionary.Empty; + public sealed record McpAllowEntry + { + /// Gets the tool name the server offers, or "*" to allow every tool it offers. + public required string Name { get; init; } - /// - /// Gets the environment the child process is launched with. Set when is - /// . A value may hold ${secret:name} references. - /// - public IReadOnlyDictionary Env { get; init; } - = ReadOnlyDictionary.Empty; + /// + /// Gets the id this tool is served under, or to take the default. + /// + public string? As { get; init; } + } /// - /// Gets whether the child process also inherits this process's own environment. + /// One declared MCP server. /// - public bool InheritEnv { get; init; } + public sealed record McpServerConfiguration + { + /// Gets the server id. Decision 10 builds every served tool id from it. + public required string Id { get; init; } + + /// Gets how AgentCore connects to the server. + public required McpTransport Transport { get; init; } + + /// + /// Gets the executable and its arguments. Set when is . + /// + public IReadOnlyList Command { get; init; } = []; + + /// Gets the server URL. Set when is . + public string? Url { get; init; } + + /// Gets the tools this server is pinned to offer. + public IReadOnlyList Allow { get; init; } = []; + + /// + /// Gets the headers sent on every request. Set when is + /// . A value may hold ${secret:name} references. + /// + public IReadOnlyDictionary Headers { get; init; } + = ReadOnlyDictionary.Empty; + + /// + /// Gets the environment the child process is launched with. Set when is + /// . A value may hold ${secret:name} references. + /// + public IReadOnlyDictionary Env { get; init; } + = ReadOnlyDictionary.Empty; + + /// + /// Gets whether the child process also inherits this process's own environment. + /// + public bool InheritEnv { get; init; } + + /// + /// Gets how long one connection attempt may take, in seconds, or for the + /// default. It is applied on every attempt. + /// + public int? ConnectTimeoutSeconds { get; init; } + + /// + /// Gets how long one tool call may take, in seconds, or for the default. + /// + public int? CallTimeoutSeconds { get; init; } + + /// Gets what happens when a connection attempt fails, or for the default. + public McpRetryConfiguration? Retry { get; init; } + } /// - /// Gets how long one connection attempt may take, in seconds, or for the - /// default. It is applied on every attempt. + /// What happens when a connection attempt to one MCP server fails. /// - public int? ConnectTimeoutSeconds { get; init; } - - /// - /// Gets how long one tool call may take, in seconds, or for the default. - /// - public int? CallTimeoutSeconds { get; init; } - - /// Gets what happens when a connection attempt fails, or for the default. - public McpRetryConfiguration? Retry { get; init; } -} - -/// -/// What happens when a connection attempt to one MCP server fails. -/// -public sealed record McpRetryConfiguration -{ - /// Gets the number of attempts, including the first, or for the default. - public int? Attempts { get; init; } - - /// Gets the wait before the second attempt, in milliseconds. Each later one waits twice the last. - public int? BackoffMs { get; init; } + public sealed record McpRetryConfiguration + { + /// Gets the number of attempts, including the first, or for the default. + public int? Attempts { get; init; } + + /// Gets the wait before the second attempt, in milliseconds. Each later one waits twice the last. + public int? BackoffMs { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/PolicyConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/PolicyConfiguration.cs index dd9bbbd3..7d06010b 100644 --- a/src/AgentCore.Application/Configuration/Schema/PolicyConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/PolicyConfiguration.cs @@ -1,56 +1,57 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// What a stage does when no exit guard is true. -public enum StageNoMatch -{ - /// The stage stays where it is. This matches OnUnhandledTrigger and is the normal case. - Stay, - - /// The turn fails. A stage sets this to reject the zero-guards-true case. - Error, -} - -/// -/// One exit of a stage. -/// -public sealed record StageTransition -{ - /// Gets the id of the stage this exit leads to. - public required string Stage { get; init; } - - /// Gets the guard on the exit, or when the exit is unconditional. - public GuardReference? When { get; init; } -} - -/// -/// One stage of the machine. The stage names one agent, and the machine picks a stage each turn. -/// -public sealed record StageConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the stage id. - public required string Id { get; init; } - - /// Gets the id of the agent that speaks in this stage, or . - public string? Agent { get; init; } - - /// Gets whether the stage ends the conversation. A terminal stage needs no exit. - public bool Terminal { get; init; } - - /// Gets what the stage does when no exit guard is true. - public StageNoMatch OnNoMatch { get; init; } = StageNoMatch.Stay; - - /// Gets the exits of the stage, in document order. Check 5 evaluates them as siblings. - public IReadOnlyList To { get; init; } = []; -} - -/// -/// An entry's policy: block: a stage machine over string stages, run by Stateless. -/// -public sealed record PolicyConfiguration -{ - /// Gets the id of the stage the conversation starts in. - public required string Initial { get; init; } - - /// Gets the declared stages, in document order. - public required IReadOnlyList Stages { get; init; } + /// What a stage does when no exit guard is true. + public enum StageNoMatch + { + /// The stage stays where it is. This matches OnUnhandledTrigger and is the normal case. + Stay, + + /// The turn fails. A stage sets this to reject the zero-guards-true case. + Error, + } + + /// + /// One exit of a stage. + /// + public sealed record StageTransition + { + /// Gets the id of the stage this exit leads to. + public required string Stage { get; init; } + + /// Gets the guard on the exit, or when the exit is unconditional. + public GuardReference? When { get; init; } + } + + /// + /// One stage of the machine. The stage names one agent, and the machine picks a stage each turn. + /// + public sealed record StageConfiguration + { + /// Gets the stage id. + public required string Id { get; init; } + + /// Gets the id of the agent that speaks in this stage, or . + public string? Agent { get; init; } + + /// Gets whether the stage ends the conversation. A terminal stage needs no exit. + public bool Terminal { get; init; } + + /// Gets what the stage does when no exit guard is true. + public StageNoMatch OnNoMatch { get; init; } = StageNoMatch.Stay; + + /// Gets the exits of the stage, in document order. Check 5 evaluates them as siblings. + public IReadOnlyList To { get; init; } = []; + } + + /// + /// An entry's policy: block: a stage machine over string stages, run by Stateless. + /// + public sealed record PolicyConfiguration + { + /// Gets the id of the stage the conversation starts in. + public required string Initial { get; init; } + + /// Gets the declared stages, in document order. + public required IReadOnlyList Stages { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs index 2de0cfc6..07d318d8 100644 --- a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs @@ -1,376 +1,377 @@ using System.Text.Json.Serialization; using AgentCore.Application.Knowledge; -namespace AgentCore.Application.Configuration.Schema; - -/// -/// How a card's payload is named in the collection this deployment reads. -/// -/// -/// AgentCore ships no field names. Every role starts unmapped, and stays unmapped until this -/// document names the payload path that fills it. A collection built by any ingester is therefore -/// expressible here, and no ingester's naming is privileged. An unmapped role is simply absent from -/// the card: it is never guessed, and never silently read off a name AgentCore chose. -/// -public sealed record KnowledgeFieldsConfiguration +namespace AgentCore.Application.Configuration.Schema { /// - /// Gets the field holding what the model reads, or when this document - /// names none. Required whenever providers.knowledge.mapper is absent, because the - /// built-in mapping has nothing to put in the card without it. + /// How a card's payload is named in the collection this deployment reads. /// - public string? Body { get; init; } + /// + /// AgentCore ships no field names. Every role starts unmapped, and stays unmapped until this + /// document names the payload path that fills it. A collection built by any ingester is therefore + /// expressible here, and no ingester's naming is privileged. An unmapped role is simply absent from + /// the card: it is never guessed, and never silently read off a name AgentCore chose. + /// + public sealed record KnowledgeFieldsConfiguration + { + /// + /// Gets the field holding what the model reads, or when this document + /// names none. Required whenever providers.knowledge.mapper is absent, because the + /// built-in mapping has nothing to put in the card without it. + /// + public string? Body { get; init; } - /// Gets the field holding the card id, or null when the collection carries none. - /// The point's own key stands in for an unmapped id. - public string? Id { get; init; } + /// Gets the field holding the card id, or null when the collection carries none. + /// The point's own key stands in for an unmapped id. + public string? Id { get; init; } - /// Gets the full-text-indexed field the required-term leg matches on. - /// Unmapped, the search ranks by vector alone and the analyzer is never consulted. - public string? Lexical { get; init; } + /// Gets the full-text-indexed field the required-term leg matches on. + /// Unmapped, the search ranks by vector alone and the analyzer is never consulted. + public string? Lexical { get; init; } - /// Gets the field holding the citation's source label. - public string? Source { get; init; } + /// Gets the field holding the citation's source label. + public string? Source { get; init; } - /// Gets the field holding where in that source the card sits. - public string? Locator { get; init; } + /// Gets the field holding where in that source the card sits. + public string? Locator { get; init; } - /// Gets the field holding the trust rank. Read by the audit record only. - public string? Authority { get; init; } -} + /// Gets the field holding the trust rank. Read by the audit record only. + public string? Authority { get; init; } + } -/// How an open KnowledgeScope's facet keys become payload paths. -/// -/// There is no default template, because a template is a claim about where one particular -/// collection keeps its facets. A deployment whose agents never scope needs none; one whose agents -/// do must say where to look. -/// -public sealed record KnowledgeScopeConfiguration -{ - /// - /// Gets the payload path each facet key becomes, with {key} standing for the key, or - /// when this document names none. Required whenever any agent declares - /// knowledge: { scoped: true }. - /// - public string? Template { get; init; } + /// How an open KnowledgeScope's facet keys become payload paths. + /// + /// There is no default template, because a template is a claim about where one particular + /// collection keeps its facets. A deployment whose agents never scope needs none; one whose agents + /// do must say where to look. + /// + public sealed record KnowledgeScopeConfiguration + { + /// + /// Gets the payload path each facet key becomes, with {key} standing for the key, or + /// when this document names none. Required whenever any agent declares + /// knowledge: { scoped: true }. + /// + public string? Template { get; init; } - /// Gets how a card marks itself reachable from every scope, or for exact match only. - public KnowledgeWildcardConfiguration? Wildcard { get; init; } + /// Gets how a card marks itself reachable from every scope, or for exact match only. + public KnowledgeWildcardConfiguration? Wildcard { get; init; } - /// Gets the state slots the turn's scope is built from. Each name becomes one facet key. - public IReadOnlyList FromState { get; init; } = []; + /// Gets the state slots the turn's scope is built from. Each name becomes one facet key. + public IReadOnlyList FromState { get; init; } = []; - /// Gets the facets a tool-mode agent may narrow its own search by. Empty offers none. - public IReadOnlyList Filterable { get; init; } = []; -} + /// Gets the facets a tool-mode agent may narrow its own search by. Empty offers none. + public IReadOnlyList Filterable { get; init; } = []; + } -/// One facet the model may name in the search tool's filters argument. -public sealed record KnowledgeFilterableFacetConfiguration -{ - /// Gets the facet key, which scope.template turns into the payload path. - public required string Key { get; init; } + /// One facet the model may name in the search tool's filters argument. + public sealed record KnowledgeFilterableFacetConfiguration + { + /// Gets the facet key, which scope.template turns into the payload path. + public required string Key { get; init; } + + /// Gets what this facet means, in the words the model reads before it picks a value. + public required string Description { get; init; } - /// Gets what this facet means, in the words the model reads before it picks a value. - public required string Description { get; init; } + /// + /// Gets how the model finds an exact value for this facet, or when the + /// description alone is enough to pick one. + /// + public KnowledgeFacetResolveConfiguration? Resolve { get; init; } + } /// - /// Gets how the model finds an exact value for this facet, or when the - /// description alone is enough to pick one. + /// The lookup that turns what the person said into the one value a facet is stored under. /// - public KnowledgeFacetResolveConfiguration? Resolve { get; init; } -} - -/// -/// The lookup that turns what the person said into the one value a facet is stored under. -/// -/// -/// A vocabulary of thousands cannot sit in a prompt. The model instead searches a small index — the -/// cards under one other facet — and copies the value off the card it finds. This block is printed -/// on the search tool, not run by the host: the model does the lookup itself. -/// -public sealed record KnowledgeFacetResolveConfiguration -{ - /// Gets the facet and value that narrow the lookup search to the index cards. - public required KnowledgeFacetValueConfiguration Via { get; init; } - - /// Gets what the model searches for, with placeholders in angle brackets for what the person said. - public required string Query { get; init; } - - /// Gets where on the card the value is, in the words the model reads. - public required string Read { get; init; } -} - -/// One facet key and the value it must carry. -public sealed record KnowledgeFacetValueConfiguration -{ - /// Gets the facet key. - public required string Key { get; init; } - - /// Gets the value the cards must carry. - public required string Value { get; init; } -} - -/// Which facets a card may opt out of, and the value it opts out with. -/// -/// Named per facet, never global. A wildcard reaching an isolation facet such as a customer id -/// would serve one mis-tagged card to every caller, which is the failure the scope exists to stop. -/// -public sealed record KnowledgeWildcardConfiguration -{ - /// Gets the payload value that satisfies any scope on a named facet. - public required string Value { get; init; } - - /// Gets the facet keys the wildcard widens. Every other facet stays exact match. - public required IReadOnlyList Facets { get; init; } -} - -/// How a card id becomes something Qdrant can fetch. -public enum KnowledgeLinkLookup -{ - /// The point key is uuid5(namespace, prefix + id). One fetch by key. - Uuid5, - - /// The point key is the card id itself. One fetch by key. - Direct, - - /// The point key is unrelated to the id. One scroll, matching on the id field. - Filter, -} - -/// How a card's links to other cards are read and followed. -/// -/// The whole block is opt-in: a document without links: never expands. On a configured -/// block, a collection carrying nothing at is still inert. -/// -public sealed record KnowledgeLinksConfiguration -{ - /// The uuid5 namespace used when the document names none. /// - /// This is RFC 4122's own URL namespace, not any ingester's choice. uuid5 is undefined - /// without a namespace, so unlike a field name it cannot be left unset. + /// A vocabulary of thousands cannot sit in a prompt. The model instead searches a small index — the + /// cards under one other facet — and copies the value off the card it finds. This block is printed + /// on the search tool, not run by the host: the model does the lookup itself. /// - public const string DefaultNamespace = "url"; - - /// - /// Gets the payload field holding the ids of the cards this card links to, or - /// when this document names none. Required inside a links: block. - /// - public string? Field { get; init; } - - /// Gets how a linked id becomes a point to fetch. filter works on any collection. - public KnowledgeLinkLookup Lookup { get; init; } = KnowledgeLinkLookup.Filter; + public sealed record KnowledgeFacetResolveConfiguration + { + /// Gets the facet and value that narrow the lookup search to the index cards. + public required KnowledgeFacetValueConfiguration Via { get; init; } - /// Gets the uuid5 namespace: url, dns, oid, x500, or a GUID. - public string Namespace { get; init; } = DefaultNamespace; + /// Gets what the model searches for, with placeholders in angle brackets for what the person said. + public required string Query { get; init; } - /// Gets what the ingester puts in front of the id before hashing. Empty by default. - public string Prefix { get; init; } = string.Empty; -} - -/// -/// The knowledge provider: the adapter that answers IKnowledgeRetrievalPort, and what it reads. -/// -public sealed record KnowledgeProviderConfiguration -{ - /// The analyzer used when the document names none: one that requires nothing. - public const string DefaultAnalyzer = NoQueryAnalyzer.AnalyzerName; + /// Gets where on the card the value is, in the words the model reads. + public required string Read { get; init; } + } - /// The citation wording used when the document names none. - public const string DefaultCitation = SourceLocatorCitationFormatter.FormatterName; + /// One facet key and the value it must carry. + public sealed record KnowledgeFacetValueConfiguration + { + /// Gets the facet key. + public required string Key { get; init; } - /// - /// The score floor used when the document sets none: a cosine similarity, applied on the dense - /// prefetch. On text-embedding-3-small, 0.25 let twelve of twenty cards through for a question - /// the corpus did not answer; 0.35 let none through and kept every answered question's cards. - /// 0 disables the floor. - /// - public const double DefaultScoreFloor = 0.35; + /// Gets the value the cards must carry. + public required string Value { get; init; } + } - /// Gets the adapter that answers IKnowledgeRetrievalPort, such as qdrant. - public required string Kind { get; init; } + /// Which facets a card may opt out of, and the value it opts out with. + /// + /// Named per facet, never global. A wildcard reaching an isolation facet such as a customer id + /// would serve one mis-tagged card to every caller, which is the failure the scope exists to stop. + /// + public sealed record KnowledgeWildcardConfiguration + { + /// Gets the payload value that satisfies any scope on a named facet. + public required string Value { get; init; } - /// Gets the Qdrant endpoint, such as https://qdrant.example.com:6334. - public string? Endpoint { get; init; } + /// Gets the facet keys the wildcard widens. Every other facet stays exact match. + public required IReadOnlyList Facets { get; init; } + } - /// Gets the collection to read. - public required string Collection { get; init; } + /// How a card id becomes something Qdrant can fetch. + public enum KnowledgeLinkLookup + { + /// The point key is uuid5(namespace, prefix + id). One fetch by key. + Uuid5, - /// - /// Gets the named vector every query searches, or for the collection's - /// single anonymous vector — the default shape most Qdrant tooling creates. - /// - public string? Vector { get; init; } + /// The point key is the card id itself. One fetch by key. + Direct, - /// - /// Gets how a card's payload is named, or when this document names - /// nothing. Required whenever is absent. - /// - public KnowledgeFieldsConfiguration? Fields { get; init; } + /// The point key is unrelated to the id. One scroll, matching on the id field. + Filter, + } - /// Gets how facet keys become payload paths. - public KnowledgeScopeConfiguration Scope { get; init; } = new(); + /// How a card's links to other cards are read and followed. + /// + /// The whole block is opt-in: a document without links: never expands. On a configured + /// block, a collection carrying nothing at is still inert. + /// + public sealed record KnowledgeLinksConfiguration + { + /// The uuid5 namespace used when the document names none. + /// + /// This is RFC 4122's own URL namespace, not any ingester's choice. uuid5 is undefined + /// without a namespace, so unlike a field name it cannot be left unset. + /// + public const string DefaultNamespace = "url"; - /// - /// Gets how the knowledge search asks the caller which machine they meant, or - /// when this document names none. Absent means neither the probe nor the - /// clarification ever runs. - /// - public KnowledgeAmbiguityConfiguration? Ambiguity { get; init; } + /// + /// Gets the payload field holding the ids of the cards this card links to, or + /// when this document names none. Required inside a links: block. + /// + public string? Field { get; init; } - /// Gets how links between cards are read and followed, or for no link expansion. - public KnowledgeLinksConfiguration? Links { get; init; } + /// Gets how a linked id becomes a point to fetch. filter works on any collection. + public KnowledgeLinkLookup Lookup { get; init; } = KnowledgeLinkLookup.Filter; - /// Gets the IKnowledgeQueryAnalyzer name that picks required terms. - public string Analyzer { get; init; } = DefaultAnalyzer; + /// Gets the uuid5 namespace: url, dns, oid, x500, or a GUID. + public string Namespace { get; init; } = DefaultNamespace; - /// - /// Gets the IKnowledgeCitationFormatter name that writes each card's source label. - /// - /// Read only by agents that declare knowledge: { citations: true }. - public string Citation { get; init; } = DefaultCitation; + /// Gets what the ingester puts in front of the id before hashing. Empty by default. + public string Prefix { get; init; } = string.Empty; + } /// - /// Gets the IKnowledgePointMapper name that turns a point into a card, or - /// for the fields: mapping above. + /// The knowledge provider: the adapter that answers IKnowledgeRetrievalPort, and what it reads. /// - - public string? Mapper { get; init; } + public sealed record KnowledgeProviderConfiguration + { + /// The analyzer used when the document names none: one that requires nothing. + public const string DefaultAnalyzer = NoQueryAnalyzer.AnalyzerName; + + /// The citation wording used when the document names none. + public const string DefaultCitation = SourceLocatorCitationFormatter.FormatterName; + + /// + /// The score floor used when the document sets none: a cosine similarity, applied on the dense + /// prefetch. On text-embedding-3-small, 0.25 let twelve of twenty cards through for a question + /// the corpus did not answer; 0.35 let none through and kept every answered question's cards. + /// 0 disables the floor. + /// + public const double DefaultScoreFloor = 0.35; + + /// Gets the adapter that answers IKnowledgeRetrievalPort, such as qdrant. + public required string Kind { get; init; } + + /// Gets the Qdrant endpoint, such as https://qdrant.example.com:6334. + public string? Endpoint { get; init; } + + /// Gets the collection to read. + public required string Collection { get; init; } + + /// + /// Gets the named vector every query searches, or for the collection's + /// single anonymous vector — the default shape most Qdrant tooling creates. + /// + public string? Vector { get; init; } + + /// + /// Gets how a card's payload is named, or when this document names + /// nothing. Required whenever is absent. + /// + public KnowledgeFieldsConfiguration? Fields { get; init; } + + /// Gets how facet keys become payload paths. + public KnowledgeScopeConfiguration Scope { get; init; } = new(); + + /// + /// Gets how the knowledge search asks the caller which machine they meant, or + /// when this document names none. Absent means neither the probe nor the + /// clarification ever runs. + /// + public KnowledgeAmbiguityConfiguration? Ambiguity { get; init; } + + /// Gets how links between cards are read and followed, or for no link expansion. + public KnowledgeLinksConfiguration? Links { get; init; } + + /// Gets the IKnowledgeQueryAnalyzer name that picks required terms. + public string Analyzer { get; init; } = DefaultAnalyzer; + + /// + /// Gets the IKnowledgeCitationFormatter name that writes each card's source label. + /// + /// Read only by agents that declare knowledge: { citations: true }. + public string Citation { get; init; } = DefaultCitation; + + /// + /// Gets the IKnowledgePointMapper name that turns a point into a card, or + /// for the fields: mapping above. + /// + + public string? Mapper { get; init; } + + /// + /// Gets the cosine similarity a card must score strictly above, in the range 0 to 1. The store + /// applies it on the dense prefetch, before any fusion; Qdrant drops a card scoring exactly it. + /// 0 disables the floor. + /// + public double ScoreFloor { get; init; } = DefaultScoreFloor; + } /// - /// Gets the cosine similarity a card must score strictly above, in the range 0 to 1. The store - /// applies it on the dense prefetch, before any fusion; Qdrant drops a card scoring exactly it. - /// 0 disables the floor. + /// How the knowledge search asks the caller which machine they meant, when the scope narrows to more + /// than one and the search itself came back empty. See section 4 of the ambiguity design. /// - public double ScoreFloor { get; init; } = DefaultScoreFloor; -} + public sealed record KnowledgeAmbiguityConfiguration + { + /// The candidate cap used when the document sets none. + public const int DefaultMaxCandidates = 6; -/// -/// How the knowledge search asks the caller which machine they meant, when the scope narrows to more -/// than one and the search itself came back empty. See section 4 of the ambiguity design. -/// -public sealed record KnowledgeAmbiguityConfiguration -{ - /// The candidate cap used when the document sets none. - public const int DefaultMaxCandidates = 6; + /// The per-slot ask cap used when the document sets none. + public const int DefaultMaxAsks = 2; - /// The per-slot ask cap used when the document sets none. - public const int DefaultMaxAsks = 2; + /// The probe's own budget used when the document sets none, in seconds. + public const int DefaultProbeDeadlineSeconds = 5; - /// The probe's own budget used when the document sets none, in seconds. - public const int DefaultProbeDeadlineSeconds = 5; + /// The loser's extra wait used when the document sets none, in seconds. + public const int DefaultProbeWaitMarginSeconds = 1; - /// The loser's extra wait used when the document sets none, in seconds. - public const int DefaultProbeWaitMarginSeconds = 1; + /// Gets how many distinct values the ask may name. Above this, the ask names none of them. + public int MaxCandidates { get; init; } = DefaultMaxCandidates; - /// Gets how many distinct values the ask may name. Above this, the ask names none of them. - public int MaxCandidates { get; init; } = DefaultMaxCandidates; + /// + /// Gets the cap on a slot's probe ask counter. 0 means never ask: the gate still works. + /// + public int MaxAsks { get; init; } = DefaultMaxAsks; - /// - /// Gets the cap on a slot's probe ask counter. 0 means never ask: the gate still works. - /// - public int MaxAsks { get; init; } = DefaultMaxAsks; + /// Gets the probe's own budget, in seconds. The main search keeps the store's own deadline. + public int ProbeDeadlineSeconds { get; init; } = DefaultProbeDeadlineSeconds; - /// Gets the probe's own budget, in seconds. The main search keeps the store's own deadline. - public int ProbeDeadlineSeconds { get; init; } = DefaultProbeDeadlineSeconds; + /// + /// Gets how much longer than the probe, in seconds, a concurrent loser waits for the winner's + /// payload. + /// + public int ProbeWaitMarginSeconds { get; init; } = DefaultProbeWaitMarginSeconds; + } /// - /// Gets how much longer than the probe, in seconds, a concurrent loser waits for the winner's - /// payload. + /// The telemetry provider: where the signals go, and what is listened to on the way. /// - public int ProbeWaitMarginSeconds { get; init; } = DefaultProbeWaitMarginSeconds; -} - -/// -/// The telemetry provider: where the signals go, and what is listened to on the way. -/// -public sealed record TelemetryProviderConfiguration -{ - /// The service name used when the document sets none. - public const string DefaultServiceName = "agentcore"; + public sealed record TelemetryProviderConfiguration + { + /// The service name used when the document sets none. + public const string DefaultServiceName = "agentcore"; + + /// + /// The metric export interval used when the document sets none, in milliseconds. + /// + public const int DefaultExportIntervalMilliseconds = 60_000; + + /// The lowest interval T61 allows, in milliseconds. + public const int MinimumExportIntervalMilliseconds = 60_000; + + /// The extra ActivitySource names listened to when the document lists none. + public static readonly IReadOnlyList DefaultSources = + ["Microsoft.AspNetCore", "System.Net.Http", "Experimental.Microsoft.Extensions.AI", "Experimental.Microsoft.Agents.AI"]; + + /// The extra Meter names listened to when the document lists none. + public static readonly IReadOnlyList DefaultMeters = + [ + "Microsoft.AspNetCore.Hosting", + "Microsoft.AspNetCore.Server.Kestrel", + "System.Net.Http", + "Experimental.Microsoft.Extensions.AI", + "Experimental.Microsoft.Agents.AI", + ]; + + /// Gets the vendor, such as grafana. + public required string Kind { get; init; } + + /// Gets the collector URL, or to read it from the environment. + public string? Endpoint { get; init; } + + /// Gets the service.name every exported signal carries. + public string ServiceName { get; init; } = DefaultServiceName; + + /// Gets how often metrics are sent, in milliseconds, never below the T61 floor. + [JsonPropertyName("exportIntervalMs")] + public int ExportIntervalMilliseconds + { + get; + init => field = Math.Max(value, MinimumExportIntervalMilliseconds); + } = DefaultExportIntervalMilliseconds; + + /// Gets the extra ActivitySource names listened to, beside the one AgentCore owns. + public IReadOnlyList Sources { get; init; } = DefaultSources; + + /// Gets the extra Meter names listened to, beside the one AgentCore owns. + public IReadOnlyList Meters { get; init; } = DefaultMeters; + } /// - /// The metric export interval used when the document sets none, in milliseconds. + /// The providers: section. It configures adapters and never changes agent shape. /// - public const int DefaultExportIntervalMilliseconds = 60_000; - - /// The lowest interval T61 allows, in milliseconds. - public const int MinimumExportIntervalMilliseconds = 60_000; - - /// The extra ActivitySource names listened to when the document lists none. - public static readonly IReadOnlyList DefaultSources = - ["Microsoft.AspNetCore", "System.Net.Http", "Experimental.Microsoft.Extensions.AI", "Experimental.Microsoft.Agents.AI"]; - - /// The extra Meter names listened to when the document lists none. - public static readonly IReadOnlyList DefaultMeters = - [ - "Microsoft.AspNetCore.Hosting", - "Microsoft.AspNetCore.Server.Kestrel", - "System.Net.Http", - "Experimental.Microsoft.Extensions.AI", - "Experimental.Microsoft.Agents.AI", - ]; - - /// Gets the vendor, such as grafana. - public required string Kind { get; init; } - - /// Gets the collector URL, or to read it from the environment. - public string? Endpoint { get; init; } - - /// Gets the service.name every exported signal carries. - public string ServiceName { get; init; } = DefaultServiceName; - - /// Gets how often metrics are sent, in milliseconds, never below the T61 floor. - [JsonPropertyName("exportIntervalMs")] - public int ExportIntervalMilliseconds + public sealed record ProvidersConfiguration { - get => field; - init => field = Math.Max(value, MinimumExportIntervalMilliseconds); - } = DefaultExportIntervalMilliseconds; - - /// Gets the extra ActivitySource names listened to, beside the one AgentCore owns. - public IReadOnlyList Sources { get; init; } = DefaultSources; - - /// Gets the extra Meter names listened to, beside the one AgentCore owns. - public IReadOnlyList Meters { get; init; } = DefaultMeters; -} - -/// -/// The providers: section. It configures adapters and never changes agent shape. -/// -public sealed record ProvidersConfiguration -{ - /// Gets the language models, in document order. - public IReadOnlyList Llm { get; init; } = []; + /// Gets the language models, in document order. + public IReadOnlyList Llm { get; init; } = []; - /// Gets the vendor that carries the conversation and owns its inbound route, or . - public ConversationProviderConfiguration? Conversation { get; init; } + /// Gets the vendor that carries the conversation and owns its inbound route, or . + public ConversationProviderConfiguration? Conversation { get; init; } - /// Gets the two speech roles, or . - public SpeechProviderConfiguration? Speech { get; init; } + /// Gets the two speech roles, or . + public SpeechProviderConfiguration? Speech { get; init; } - /// Gets the telephony provider, or . - public VendorProviderConfiguration? Telephony { get; init; } + /// Gets the telephony provider, or . + public VendorProviderConfiguration? Telephony { get; init; } - /// Gets the moderation provider, or . - public VendorProviderConfiguration? Moderation { get; init; } + /// Gets the moderation provider, or . + public VendorProviderConfiguration? Moderation { get; init; } - /// Gets the embedding provider, or . - public EmbeddingProviderConfiguration? Embeddings { get; init; } + /// Gets the embedding provider, or . + public EmbeddingProviderConfiguration? Embeddings { get; init; } - /// Gets the knowledge provider, or . - public KnowledgeProviderConfiguration? Knowledge { get; init; } + /// Gets the knowledge provider, or . + public KnowledgeProviderConfiguration? Knowledge { get; init; } - /// Gets the telemetry provider, or . - public TelemetryProviderConfiguration? Telemetry { get; init; } + /// Gets the telemetry provider, or . + public TelemetryProviderConfiguration? Telemetry { get; init; } - /// Gets the audit sink provider, or for the in-process default. - public VendorProviderConfiguration? Audit { get; init; } + /// Gets the audit sink provider, or for the in-process default. + public VendorProviderConfiguration? Audit { get; init; } - /// Gets the conversation store provider, or for the in-process default. - public VendorProviderConfiguration? Conversations { get; init; } + /// Gets the conversation store provider, or for the in-process default. + public VendorProviderConfiguration? Conversations { get; init; } - /// - /// Gets the blob store provider, or when a sandbox file is never kept. - /// - public BlobProviderConfiguration? Blobs { get; init; } + /// + /// Gets the blob store provider, or when a sandbox file is never kept. + /// + public BlobProviderConfiguration? Blobs { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ReservedStateSlots.cs b/src/AgentCore.Application/Configuration/Schema/ReservedStateSlots.cs index 06b88ce4..7554ead2 100644 --- a/src/AgentCore.Application/Configuration/Schema/ReservedStateSlots.cs +++ b/src/AgentCore.Application/Configuration/Schema/ReservedStateSlots.cs @@ -1,30 +1,33 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The three read-only slots that are always present. -/// -/// -/// Section 8.3: a configuration may read them in a rule, and may not declare or write them. -/// -public static class ReservedStateSlots +namespace AgentCore.Application.Configuration.Schema { - /// The id of the stage the machine holds. - public const string Stage = "stage"; + /// + /// The three read-only slots that are always present. + /// + /// + /// Section 8.3: a configuration may read them in a rule, and may not declare or write them. + /// + public static class ReservedStateSlots + { + /// The id of the stage the machine holds. + public const string Stage = "stage"; - /// The zero-based index of the current turn. - public const string TurnIndex = "turnIndex"; + /// The zero-based index of the current turn. + public const string TurnIndex = "turnIndex"; - /// The seconds the conversation has run. - public const string ConversationDurationSeconds = "conversationDurationSeconds"; + /// The seconds the conversation has run. + public const string ConversationDurationSeconds = "conversationDurationSeconds"; - /// Gets every reserved slot name. - public static IReadOnlyList All { get; } = [Stage, TurnIndex, ConversationDurationSeconds]; + /// Gets every reserved slot name. + public static IReadOnlyList All { get; } = [Stage, TurnIndex, ConversationDurationSeconds]; - /// Reports whether a name is reserved. - /// The slot name to test. - /// when the name is reserved. - public static bool Contains(string name) - => string.Equals(name, Stage, StringComparison.Ordinal) - || string.Equals(name, TurnIndex, StringComparison.Ordinal) - || string.Equals(name, ConversationDurationSeconds, StringComparison.Ordinal); + /// Reports whether a name is reserved. + /// The slot name to test. + /// when the name is reserved. + public static bool Contains(string name) + { + return string.Equals(name, Stage, StringComparison.Ordinal) + || string.Equals(name, TurnIndex, StringComparison.Ordinal) + || string.Equals(name, ConversationDurationSeconds, StringComparison.Ordinal); + } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs index 9260b05e..f72b234e 100644 --- a/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs @@ -1,13 +1,14 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The two speech roles: who turns sound into text, and who turns text back into sound. -/// -public sealed record SpeechProviderConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the recognition vendor: what the caller said, turned into text. - public required VendorProviderConfiguration Stt { get; init; } + /// + /// The two speech roles: who turns sound into text, and who turns text back into sound. + /// + public sealed record SpeechProviderConfiguration + { + /// Gets the recognition vendor: what the caller said, turned into text. + public required VendorProviderConfiguration Stt { get; init; } - /// Gets the synthesis vendor: text, turned into what the caller hears. - public required VendorProviderConfiguration Tts { get; init; } + /// Gets the synthesis vendor: text, turned into what the caller hears. + public required VendorProviderConfiguration Tts { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs index c7117ae9..87a001cf 100644 --- a/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs @@ -1,71 +1,72 @@ using System.Text.Json.Nodes; using System.Text.Json.Serialization; -namespace AgentCore.Application.Configuration.Schema; - -/// The declared type of one state slot. -public enum StateSlotType -{ - /// type: boolean. Check 5 enumerates two points. - Boolean, - - /// type: integer. - Integer, - - /// type: number. - Number, - - /// type: string. - String, -} - -/// The one owner that fills a state slot. See the table in section 8.3. -public enum StateWriter -{ - /// A model call against a schema AgentCore builds from every extractor slot. - Extractor, - - /// A named field of a named tool result. - Tool, - - /// An integer that increments whenever its rule is true. - Counter, - - /// A fixed value. - Const, -} - -/// -/// One declared state slot. Every slot has exactly one writer. -/// -public sealed record StateSlotConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the declared type. It is authoritative: AgentCore coerces the written value to it. - public required StateSlotType Type { get; init; } - - /// Gets the one writer that owns the slot. - public required StateWriter Writer { get; init; } - - /// Gets the value the slot holds before any writer fills it. - public JsonNode? Default { get; init; } - - /// Gets the prose description of the slot, or . - public string? Description { get; init; } - - /// Gets the members check 5 enumerates, or when the slot is not an enumeration. - /// - /// The document key is enum, which is a C# keyword, so the property carries the name it - /// binds by rather than taking it from the naming policy. - /// - [JsonPropertyName("enum")] - public IReadOnlyList? EnumValues { get; init; } - - /// Gets the tool result the slot reads. It is set when, and only when, the writer is . - public ToolResultReference? From { get; init; } - - /// Gets the raw JSONLogic rule that increments the slot. It is set when the writer is . - public JsonNode? Increment { get; init; } - - /// Gets the fixed value of the slot. It is set when the writer is . - public JsonNode? Value { get; init; } + /// The declared type of one state slot. + public enum StateSlotType + { + /// type: boolean. Check 5 enumerates two points. + Boolean, + + /// type: integer. + Integer, + + /// type: number. + Number, + + /// type: string. + String, + } + + /// The one owner that fills a state slot. See the table in section 8.3. + public enum StateWriter + { + /// A model call against a schema AgentCore builds from every extractor slot. + Extractor, + + /// A named field of a named tool result. + Tool, + + /// An integer that increments whenever its rule is true. + Counter, + + /// A fixed value. + Const, + } + + /// + /// One declared state slot. Every slot has exactly one writer. + /// + public sealed record StateSlotConfiguration + { + /// Gets the declared type. It is authoritative: AgentCore coerces the written value to it. + public required StateSlotType Type { get; init; } + + /// Gets the one writer that owns the slot. + public required StateWriter Writer { get; init; } + + /// Gets the value the slot holds before any writer fills it. + public JsonNode? Default { get; init; } + + /// Gets the prose description of the slot, or . + public string? Description { get; init; } + + /// Gets the members check 5 enumerates, or when the slot is not an enumeration. + /// + /// The document key is enum, which is a C# keyword, so the property carries the name it + /// binds by rather than taking it from the naming policy. + /// + [JsonPropertyName("enum")] + public IReadOnlyList? EnumValues { get; init; } + + /// Gets the tool result the slot reads. It is set when, and only when, the writer is . + public ToolResultReference? From { get; init; } + + /// Gets the raw JSONLogic rule that increments the slot. It is set when the writer is . + public JsonNode? Increment { get; init; } + + /// Gets the fixed value of the slot. It is set when the writer is . + public JsonNode? Value { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs index 264e569f..f4bd4411 100644 --- a/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/TitlerConfiguration.cs @@ -1,10 +1,11 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// The conversation titler. It names a conversation from the newest messages of the conversation itself. -/// -public sealed record TitlerConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the model the titler conversations. - public required ModelReference Model { get; init; } + /// + /// The conversation titler. It names a conversation from the newest messages of the conversation itself. + /// + public sealed record TitlerConfiguration + { + /// Gets the model the titler conversations. + public required ModelReference Model { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs index f89738dc..96604ecd 100644 --- a/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ToolConfiguration.cs @@ -2,82 +2,83 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Parsing; -namespace AgentCore.Application.Configuration.Schema; - -/// The kind of one declared tool. -public enum ToolKind +namespace AgentCore.Application.Configuration.Schema { - /// A tool AgentCore ships. uses: names it. - Builtin, + /// The kind of one declared tool. + public enum ToolKind + { + /// A tool AgentCore ships. uses: names it. + Builtin, + + /// A tool that calls one HTTP endpoint. request: describes it. + Http, - /// A tool that calls one HTTP endpoint. request: describes it. - Http, + /// A tool that calls a host delegate. binds: names it. + Binding, - /// A tool that calls a host delegate. binds: names it. - Binding, + /// + /// A tool that runs another declared agent and returns its reply. agent: names it. + /// + Agent, + } /// - /// A tool that runs another declared agent and returns its reply. agent: names it. + /// The single HTTP call that a tool makes. /// - Agent, -} + public sealed record HttpRequestConfiguration + { + /// Gets the HTTP method, in upper case. + public required string Method { get; init; } -/// -/// The single HTTP call that a tool makes. -/// -public sealed record HttpRequestConfiguration -{ - /// Gets the HTTP method, in upper case. - public required string Method { get; init; } + /// Gets the URL. It may hold {argument} placeholders that the tool arguments fill. + public required string Url { get; init; } - /// Gets the URL. It may hold {argument} placeholders that the tool arguments fill. - public required string Url { get; init; } + /// Gets the request headers. A value may hold ${secret:name} references. + public IReadOnlyDictionary Headers { get; init; } = ReadOnlyDictionary.Empty; + } - /// Gets the request headers. A value may hold ${secret:name} references. - public IReadOnlyDictionary Headers { get; init; } = ReadOnlyDictionary.Empty; -} - -/// -/// One declared tool. -/// -public sealed record ToolConfiguration -{ - /// Gets the tool id. An agent lists this id in its tools:. - public required string Id { get; init; } + /// + /// One declared tool. + /// + public sealed record ToolConfiguration + { + /// Gets the tool id. An agent lists this id in its tools:. + public required string Id { get; init; } - /// Gets the kind of the tool. - public required ToolKind Kind { get; init; } + /// Gets the kind of the tool. + public required ToolKind Kind { get; init; } - /// Gets the description the model reads, or . - public string? Description { get; init; } + /// Gets the description the model reads, or . + public string? Description { get; init; } - /// Gets the built-in the tool calls. It is set when the kind is . - public string? Uses { get; init; } + /// Gets the built-in the tool calls. It is set when the kind is . + public string? Uses { get; init; } - /// Gets the host delegate the tool calls. It is set when the kind is . - public string? Binds { get; init; } + /// Gets the host delegate the tool calls. It is set when the kind is . + public string? Binds { get; init; } - /// - /// Gets the id of the agent this tool runs. It is set when the kind is . - /// - public string? Agent { get; init; } + /// + /// Gets the id of the agent this tool runs. It is set when the kind is . + /// + public string? Agent { get; init; } - /// Gets the raw JSON Schema of the tool arguments, or when the tool takes none. - public JsonNode? Parameters { get; init; } + /// Gets the raw JSON Schema of the tool arguments, or when the tool takes none. + public JsonNode? Parameters { get; init; } - /// Gets the HTTP call. It is set when the kind is . - public HttpRequestConfiguration? Request { get; init; } + /// Gets the HTTP call. It is set when the kind is . + public HttpRequestConfiguration? Request { get; init; } - /// - /// Gets how long one answer is served again for the same arguments, in seconds, or - /// when every call reaches the tool. Only a - /// or tool may set it. - /// - public int? CacheSeconds { get; init; } + /// + /// Gets how long one answer is served again for the same arguments, in seconds, or + /// when every call reaches the tool. Only a + /// or tool may set it. + /// + public int? CacheSeconds { get; init; } - /// Reserved. No kind: builtin tool reads it; setting it fails the load. - public ModelReference? Model { get; init; } + /// Reserved. No kind: builtin tool reads it; setting it fails the load. + public ModelReference? Model { get; init; } - /// Reserved. No kind: builtin tool reads it; setting it fails the load. - public int? MaxRounds { get; init; } + /// Reserved. No kind: builtin tool reads it; setting it fails the load. + public int? MaxRounds { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Schema/ToolResultReference.cs b/src/AgentCore.Application/Configuration/Schema/ToolResultReference.cs index 428c3c80..87f1d64a 100644 --- a/src/AgentCore.Application/Configuration/Schema/ToolResultReference.cs +++ b/src/AgentCore.Application/Configuration/Schema/ToolResultReference.cs @@ -1,41 +1,45 @@ using System.Diagnostics.CodeAnalysis; -namespace AgentCore.Application.Configuration.Schema; - -/// -/// A writer: tool path, as in lookup_order.status. -/// -/// -/// A tool result has no declared shape, so check 2 verifies only that exists, -/// and check 4 cannot type the slot from . See section 8.3. -/// -/// The id of the tool whose result the slot reads. -/// The path into that result. The text after the first dot. -public sealed record ToolResultReference(string ToolId, string Path) +namespace AgentCore.Application.Configuration.Schema { - /// Reads a from: value. - /// The raw value, such as lookup_order.status. - /// The parsed reference, when the text holds a dot. - /// when the text parses. - public static bool TryParse(string? text, [NotNullWhen(true)] out ToolResultReference? reference) + /// + /// A writer: tool path, as in lookup_order.status. + /// + /// + /// A tool result has no declared shape, so check 2 verifies only that exists, + /// and check 4 cannot type the slot from . See section 8.3. + /// + /// The id of the tool whose result the slot reads. + /// The path into that result. The text after the first dot. + public sealed record ToolResultReference(string ToolId, string Path) { - reference = null; - if (string.IsNullOrEmpty(text)) + /// Reads a from: value. + /// The raw value, such as lookup_order.status. + /// The parsed reference, when the text holds a dot. + /// when the text parses. + public static bool TryParse(string? text, [NotNullWhen(true)] out ToolResultReference? reference) { - return false; + reference = null; + if (string.IsNullOrEmpty(text)) + { + return false; + } + + int dot = text.IndexOf('.'); + if (dot <= 0 || dot == text.Length - 1) + { + return false; + } + + reference = new ToolResultReference(text[..dot], text[(dot + 1)..]); + return true; } - var dot = text.IndexOf('.'); - if (dot <= 0 || dot == text.Length - 1) + /// Writes the reference back in its source form. + /// The text toolId.path. + public override string ToString() { - return false; + return ToolId + "." + Path; } - - reference = new ToolResultReference(text[..dot], text[(dot + 1)..]); - return true; } - - /// Writes the reference back in its source form. - /// The text toolId.path. - public override string ToString() => ToolId + "." + Path; } diff --git a/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs index 39f4dd58..aed0475b 100644 --- a/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs @@ -1,10 +1,11 @@ -namespace AgentCore.Application.Configuration.Schema; - -/// -/// A provider that names one vendor and nothing else, such as speech or telephony. -/// -public sealed record VendorProviderConfiguration +namespace AgentCore.Application.Configuration.Schema { - /// Gets the vendor, such as telnyx-relay. - public required string Kind { get; init; } + /// + /// A provider that names one vendor and nothing else, such as speech or telephony. + /// + public sealed record VendorProviderConfiguration + { + /// Gets the vendor, such as telnyx-relay. + public required string Kind { get; init; } + } } diff --git a/src/AgentCore.Application/Configuration/Validation/AmbiguityCheck.cs b/src/AgentCore.Application/Configuration/Validation/AmbiguityCheck.cs index 383fd3be..71394f22 100644 --- a/src/AgentCore.Application/Configuration/Validation/AmbiguityCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/AmbiguityCheck.cs @@ -2,93 +2,94 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 2, ambiguity: section 10 of the ambiguity design. -internal static class AmbiguityCheck +namespace AgentCore.Application.Configuration.Validation { - /// Refuses an ambiguity: block that could not do what it declares. - public static void Run(AgentCoreConfiguration configuration, List errors, List warnings) + /// Check 2, ambiguity: section 10 of the ambiguity design. + internal static class AmbiguityCheck { - var knowledge = configuration.Providers?.Knowledge; - - if (knowledge?.Ambiguity is not { } ambiguity) + /// Refuses an ambiguity: block that could not do what it declares. + public static void Run(AgentCoreConfiguration configuration, List errors, List warnings) { - return; - } + KnowledgeProviderConfiguration? knowledge = configuration.Providers?.Knowledge; - if (knowledge.Mapper is not null) - { - errors.Add(Reference( - ValidationPointer.Mapper, - "providers.knowledge.ambiguity is declared, and providers.knowledge.mapper names a " - + "custom mapper. The probe reads each card's facet values out of Extras, which only " - + "the built-in field mapper fills, so every probe would find no values and the " - + "channel would stay silent.")); - } + if (knowledge?.Ambiguity is not { } ambiguity) + { + return; + } - if (knowledge.Scope.Wildcard is null) - { - errors.Add(Reference( - ValidationPointer.Ambiguity, - "providers.knowledge.ambiguity is declared and providers.knowledge.scope.wildcard is " - + "absent. The probe drops a facet the wildcard filled, so with no wildcard it has " - + "nothing to drop and the channel can never fire.")); - } + if (knowledge.Mapper is not null) + { + errors.Add(Reference( + ValidationPointer.Mapper, + "providers.knowledge.ambiguity is declared, and providers.knowledge.mapper names a " + + "custom mapper. The probe reads each card's facet values out of Extras, which only " + + "the built-in field mapper fills, so every probe would find no values and the " + + "channel would stay silent.")); + } - CheckRanges(ambiguity, errors); + if (knowledge.Scope.Wildcard is null) + { + errors.Add(Reference( + ValidationPointer.Ambiguity, + "providers.knowledge.ambiguity is declared and providers.knowledge.scope.wildcard is " + + "absent. The probe drops a facet the wildcard filled, so with no wildcard it has " + + "nothing to drop and the channel can never fire.")); + } - // A probe drops one of the scope's own facets, so it needs a second one left to search by. - // Zero is as unreachable as one, and reaches this line whenever the host supplies every facet. - if ((knowledge.Scope.FromState ?? []).Count <= 1) - { - warnings.Add(Reference( - ValidationPointer.Ambiguity, - "providers.knowledge.ambiguity is declared and scope.fromState names at most one " - + "facet. That deployment has no droppable facet other than its only one, so the probe " - + "is unreachable unless the host sets one too.")); + CheckRanges(ambiguity, errors); + + // A probe drops one of the scope's own facets, so it needs a second one left to search by. + // Zero is as unreachable as one, and reaches this line whenever the host supplies every facet. + if ((knowledge.Scope.FromState ?? []).Count <= 1) + { + warnings.Add(Reference( + ValidationPointer.Ambiguity, + "providers.knowledge.ambiguity is declared and scope.fromState names at most one " + + "facet. That deployment has no droppable facet other than its only one, so the probe " + + "is unreachable unless the host sets one too.")); + } } - } - private static void CheckRanges(KnowledgeAmbiguityConfiguration ambiguity, List errors) - { - CheckRange( - ambiguity.MaxCandidates, - 2, - int.MaxValue, - ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "maxCandidates"), - "ambiguity.maxCandidates", - "Below 2, the ask could never name a spread of candidates.", - errors); + private static void CheckRanges(KnowledgeAmbiguityConfiguration ambiguity, List errors) + { + CheckRange( + ambiguity.MaxCandidates, + 2, + int.MaxValue, + ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "maxCandidates"), + "ambiguity.maxCandidates", + "Below 2, the ask could never name a spread of candidates.", + errors); - CheckRange( - ambiguity.MaxAsks, - 0, - int.MaxValue, - ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "maxAsks"), - "ambiguity.maxAsks", - "0 is legal and means gate only; a negative count is not.", - errors); + CheckRange( + ambiguity.MaxAsks, + 0, + int.MaxValue, + ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "maxAsks"), + "ambiguity.maxAsks", + "0 is legal and means gate only; a negative count is not.", + errors); - CheckRange( - ambiguity.ProbeDeadlineSeconds, - 1, - MaxIntervalSeconds, - ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "probeDeadlineSeconds"), - "ambiguity.probeDeadlineSeconds", - "A budget below one second leaves the probe unable to complete even the fastest real " - + "search, and one above the range throws out of the CancelAfter that arms it.", - errors); + CheckRange( + ambiguity.ProbeDeadlineSeconds, + 1, + MaxIntervalSeconds, + ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "probeDeadlineSeconds"), + "ambiguity.probeDeadlineSeconds", + "A budget below one second leaves the probe unable to complete even the fastest real " + + "search, and one above the range throws out of the CancelAfter that arms it.", + errors); - CheckRange( - ambiguity.ProbeWaitMarginSeconds, - 1, - MaxIntervalSeconds, - ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "probeWaitMarginSeconds"), - "ambiguity.probeWaitMarginSeconds", - "A margin of 0 reinstates the race it exists to close: the loser's wait would end as the " - + "winner's own search does, leaving a margin equal to the arrival spread. Above the " - + "range, the deadline this is added to no longer fits the wait it arms.", - errors); + CheckRange( + ambiguity.ProbeWaitMarginSeconds, + 1, + MaxIntervalSeconds, + ConfigurationError.AppendPointer(ValidationPointer.Ambiguity, "probeWaitMarginSeconds"), + "ambiguity.probeWaitMarginSeconds", + "A margin of 0 reinstates the race it exists to close: the loser's wait would end as the " + + "winner's own search does, leaving a margin equal to the arrival spread. Above the " + + "range, the deadline this is added to no longer fits the wait it arms.", + errors); + } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidationResult.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidationResult.cs index 4dbc124f..ddaef928 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidationResult.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidationResult.cs @@ -1,31 +1,31 @@ using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// What checks 2 to 8 of section 8.5 found in one bound document. -/// -/// -/// Section 8.7 fails the load fast, so stops the document. A warning does not: -/// check 5 raises one when the state domain passes 65,536 points and it samples instead of walking -/// the whole product, which makes its coverage partial rather than complete. -/// -public sealed record ConfigurationValidationResult +namespace AgentCore.Application.Configuration.Validation { - /// Gets the result with nothing to report. - public static ConfigurationValidationResult Clean { get; } = new() + /// + /// What checks 2 to 8 of section 8.5 found in one bound document. + /// + /// + /// Section 8.7 fails the load fast, so stops the document. A warning does not: + /// check 5 raises one when the state domain passes 65,536 points and it samples instead of walking + /// the whole product, which makes its coverage partial rather than complete. + /// + public sealed record ConfigurationValidationResult { - Errors = [], - Warnings = [], - }; + /// Gets the result with nothing to report. + public static ConfigurationValidationResult Clean { get; } = new() + { + Errors = [], + Warnings = [], + }; - /// Gets every reason the document fails, in check order. - public required IReadOnlyList Errors { get; init; } + /// Gets every reason the document fails, in check order. + public required IReadOnlyList Errors { get; init; } - /// Gets every partial-coverage warning, in check order. A warning does not fail the load. - public required IReadOnlyList Warnings { get; init; } + /// Gets every partial-coverage warning, in check order. A warning does not fail the load. + public required IReadOnlyList Warnings { get; init; } - /// Reports whether the document passes checks 2 to 8. - public bool IsValid => Errors.Count == 0; + /// Reports whether the document passes checks 2 to 8. + public bool IsValid => Errors.Count == 0; + } } diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index 7a21dab1..c9f76c12 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs @@ -1,157 +1,156 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Checks 2 to 8 of section 8.5, over one bound document. Each check lives in its own -/// *Check class in this folder; this type only orders them and shapes the result. -/// -public static class ConfigurationValidator +namespace AgentCore.Application.Configuration.Validation { - /// Runs checks 2 to 8 and returns everything they find. - /// The bound document. - /// Every error and every partial-coverage warning. - public static ConfigurationValidationResult Evaluate(AgentCoreConfiguration configuration) + /// + /// Checks 2 to 8 of section 8.5, over one bound document. Each check lives in its own + /// *Check class in this folder; this type only orders them and shapes the result. + /// + public static class ConfigurationValidator { - var structural = EvaluateStructure(configuration); + /// Runs checks 2 to 8 and returns everything they find. + /// The bound document. + /// Every error and every partial-coverage warning. + public static ConfigurationValidationResult Evaluate(AgentCoreConfiguration configuration) + { + ConfigurationValidationResult structural = EvaluateStructure(configuration); - var declaredToolIds = configuration.Tools.Select(static tool => tool.Id).ToHashSet(StringComparer.Ordinal); - var toolErrors = new List(); + HashSet declaredToolIds = configuration.Tools.Select(static tool => tool.Id).ToHashSet(StringComparer.Ordinal); + List toolErrors = []; - ServedReferenceCheck.Tools(configuration, declaredToolIds, toolErrors); + ServedReferenceCheck.Tools(configuration, declaredToolIds, toolErrors); - if (toolErrors.Count == 0) - { - return structural; + return toolErrors.Count == 0 + ? structural + : new ConfigurationValidationResult + { + Errors = [.. structural.Errors, .. toolErrors], + Warnings = structural.Warnings, + }; } - return new ConfigurationValidationResult + /// Runs checks 2 to 8 and throws when any of them fails. + /// The bound document. + /// The result, so a caller can read the partial-coverage warnings of check 5. + /// The document fails one or more checks. + public static ConfigurationValidationResult Validate(AgentCoreConfiguration configuration) { - Errors = [.. structural.Errors, .. toolErrors], - Warnings = structural.Warnings, - }; - } - - /// Runs checks 2 to 8 and throws when any of them fails. - /// The bound document. - /// The result, so a caller can read the partial-coverage warnings of check 5. - /// The document fails one or more checks. - public static ConfigurationValidationResult Validate(AgentCoreConfiguration configuration) - => ThrowOnErrors(Evaluate(configuration)); + return ThrowOnErrors(Evaluate(configuration)); + } - /// - /// Runs every check of section 8.5 except tool-reference resolution, and returns everything they - /// find. - /// - /// The bound document. - /// Every error and every partial-coverage warning. - public static ConfigurationValidationResult EvaluateStructure(AgentCoreConfiguration configuration) - { - ArgumentNullException.ThrowIfNull(configuration); - - var errors = new List(); - var warnings = new List(); - var names = DeclaredNames.From(configuration); - - EntryShapeCheck.Run(configuration, names, errors); - ReferenceCheck.Run(configuration, names, errors); - ReasoningTemperatureCheck.Run(configuration, errors); - SlotWriterCheck.Run(configuration, errors); - KnowledgeScopeCheck.Run(configuration, errors); - AmbiguityCheck.Run(configuration, errors, warnings); - GuardRuleCheck.Run(configuration, errors); - ExitExclusivityCheck.Run(configuration, errors, warnings); - ReachabilityCheck.Run(configuration, errors); - GraphWellFormednessCheck.Run(configuration, errors); - DelegationCycleCheck.Run(configuration, errors); - McpCheck.ServerIds(configuration, errors); - McpCheck.SecretPlacement(configuration, errors); - - if (errors.Count == 0 && warnings.Count == 0) + /// + /// Runs every check of section 8.5 except tool-reference resolution, and returns everything they + /// find. + /// + /// The bound document. + /// Every error and every partial-coverage warning. + public static ConfigurationValidationResult EvaluateStructure(AgentCoreConfiguration configuration) { - return ConfigurationValidationResult.Clean; + ArgumentNullException.ThrowIfNull(configuration); + + List errors = []; + List warnings = []; + DeclaredNames names = DeclaredNames.From(configuration); + + EntryShapeCheck.Run(configuration, names, errors); + ReferenceCheck.Run(configuration, names, errors); + ReasoningTemperatureCheck.Run(configuration, errors); + SlotWriterCheck.Run(configuration, errors); + KnowledgeScopeCheck.Run(configuration, errors); + AmbiguityCheck.Run(configuration, errors, warnings); + GuardRuleCheck.Run(configuration, errors); + ExitExclusivityCheck.Run(configuration, errors, warnings); + ReachabilityCheck.Run(configuration, errors); + GraphWellFormednessCheck.Run(configuration, errors); + DelegationCycleCheck.Run(configuration, errors); + McpCheck.ServerIds(configuration, errors); + McpCheck.SecretPlacement(configuration, errors); + + return errors.Count == 0 && warnings.Count == 0 + ? ConfigurationValidationResult.Clean + : new ConfigurationValidationResult + { + Errors = errors, + Warnings = warnings, + }; } - return new ConfigurationValidationResult + /// + /// Runs every check of section 8.5 except tool-reference resolution, and throws when any of them + /// fails. + /// + /// The bound document. + /// The result, so a caller can read the partial-coverage warnings of check 5. + /// The document fails one or more checks. + public static ConfigurationValidationResult ValidateStructure(AgentCoreConfiguration configuration) { - Errors = errors, - Warnings = warnings, - }; - } - - /// - /// Runs every check of section 8.5 except tool-reference resolution, and throws when any of them - /// fails. - /// - /// The bound document. - /// The result, so a caller can read the partial-coverage warnings of check 5. - /// The document fails one or more checks. - public static ConfigurationValidationResult ValidateStructure(AgentCoreConfiguration configuration) - => ThrowOnErrors(EvaluateStructure(configuration)); + return ThrowOnErrors(EvaluateStructure(configuration)); + } - /// - /// Resolves every tool reference in the document against the ids the tool registry actually - /// serves, and throws when one names an id nothing serves. - /// - /// The bound document. - /// Every tool id the registry serves, declared and MCP-discovered alike. - /// A reference names a tool id nothing serves. - public static void ValidateToolReferences(AgentCoreConfiguration configuration, IReadOnlySet servedToolIds) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(servedToolIds); + /// + /// Resolves every tool reference in the document against the ids the tool registry actually + /// serves, and throws when one names an id nothing serves. + /// + /// The bound document. + /// Every tool id the registry serves, declared and MCP-discovered alike. + /// A reference names a tool id nothing serves. + public static void ValidateToolReferences(AgentCoreConfiguration configuration, IReadOnlySet servedToolIds) + { + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(servedToolIds); - var errors = new List(); - ServedReferenceCheck.Tools(configuration, servedToolIds, errors); - ThrowOnErrors(errors); - } + List errors = []; + ServedReferenceCheck.Tools(configuration, servedToolIds, errors); + ThrowOnErrors(errors); + } - /// - /// Resolves every skills: and pinned: entry against the names the bound skills - /// folder serves. - /// - /// The bound document. - /// Every skill name the bound folder serves. - /// A reference names a skill nothing serves, or a skill is both pinned and loadable. - public static void ValidateSkillReferences(AgentCoreConfiguration configuration, IReadOnlySet servedSkillNames) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(servedSkillNames); + /// + /// Resolves every skills: and pinned: entry against the names the bound skills + /// folder serves. + /// + /// The bound document. + /// Every skill name the bound folder serves. + /// A reference names a skill nothing serves, or a skill is both pinned and loadable. + public static void ValidateSkillReferences(AgentCoreConfiguration configuration, IReadOnlySet servedSkillNames) + { + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(servedSkillNames); - var errors = new List(); - ServedReferenceCheck.Skills(configuration, servedSkillNames, errors); - ServedReferenceCheck.PinnedSkills(configuration, errors); - ThrowOnErrors(errors); - } + List errors = []; + ServedReferenceCheck.Skills(configuration, servedSkillNames, errors); + ServedReferenceCheck.PinnedSkills(configuration, errors); + ThrowOnErrors(errors); + } - /// - /// Refuses a declared tool id that the skills provider also registers. The provider's tools are - /// added per agent and never pass through the tool registry, so a collision is invisible until - /// the model receives two tools of one name. - /// - /// The bound document. - /// A tool id collides with a skills tool name. - public static void ValidateSkillToolNames(AgentCoreConfiguration configuration) - { - ArgumentNullException.ThrowIfNull(configuration); + /// + /// Refuses a declared tool id that the skills provider also registers. The provider's tools are + /// added per agent and never pass through the tool registry, so a collision is invisible until + /// the model receives two tools of one name. + /// + /// The bound document. + /// A tool id collides with a skills tool name. + public static void ValidateSkillToolNames(AgentCoreConfiguration configuration) + { + ArgumentNullException.ThrowIfNull(configuration); - var errors = new List(); - ServedReferenceCheck.SkillToolNames(configuration, errors); - ThrowOnErrors(errors); - } + List errors = []; + ServedReferenceCheck.SkillToolNames(configuration, errors); + ThrowOnErrors(errors); + } - private static ConfigurationValidationResult ThrowOnErrors(ConfigurationValidationResult result) - { - ThrowOnErrors(result.Errors); - return result; - } + private static ConfigurationValidationResult ThrowOnErrors(ConfigurationValidationResult result) + { + ThrowOnErrors(result.Errors); + return result; + } - private static void ThrowOnErrors(IReadOnlyList errors) - { - if (errors.Count > 0) + private static void ThrowOnErrors(IReadOnlyList errors) { - throw new ConfigurationLoadException(errors); + if (errors.Count > 0) + { + throw new ConfigurationLoadException(errors); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/DeclaredNames.cs b/src/AgentCore.Application/Configuration/Validation/DeclaredNames.cs index dd0363e5..02f29730 100644 --- a/src/AgentCore.Application/Configuration/Validation/DeclaredNames.cs +++ b/src/AgentCore.Application/Configuration/Validation/DeclaredNames.cs @@ -1,39 +1,42 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// Every name the document declares, indexed once so each reference check resolves in O(1). -internal sealed class DeclaredNames +namespace AgentCore.Application.Configuration.Validation { - public required HashSet Agents { get; init; } + /// Every name the document declares, indexed once so each reference check resolves in O(1). + internal sealed class DeclaredNames + { + public required HashSet Agents { get; init; } - public required HashSet Guards { get; init; } + public required HashSet Guards { get; init; } - public required HashSet Models { get; init; } + public required HashSet Models { get; init; } - /// Stage ids of each entry's policy, keyed by entry name. - public required Dictionary> Stages { get; init; } + /// Stage ids of each entry's policy, keyed by entry name. + public required Dictionary> Stages { get; init; } - /// Node ids of each entry's graph, keyed by entry name. - public required Dictionary> Nodes { get; init; } + /// Node ids of each entry's graph, keyed by entry name. + public required Dictionary> Nodes { get; init; } - public static DeclaredNames From(AgentCoreConfiguration configuration) - => new() + public static DeclaredNames From(AgentCoreConfiguration configuration) { - Agents = configuration.Agents.Items - .Select(static agent => agent.Id).ToHashSet(StringComparer.Ordinal), - Guards = configuration.Guards.Keys.ToHashSet(StringComparer.Ordinal), - Stages = configuration.Entries.ToDictionary( - static entry => entry.Key, - entry => (entry.Value.Policy?.Stages ?? []) - .Select(static stage => stage.Id).ToHashSet(StringComparer.Ordinal), - StringComparer.Ordinal), - Nodes = configuration.Entries.ToDictionary( - static entry => entry.Key, - entry => (entry.Value.Graph?.Nodes ?? []) - .Select(static node => node.Id).ToHashSet(StringComparer.Ordinal), - StringComparer.Ordinal), - Models = (configuration.Providers?.Llm ?? []) - .Select(static provider => provider.As).ToHashSet(StringComparer.Ordinal), - }; + return new() + { + Agents = configuration.Agents.Items + .Select(static agent => agent.Id).ToHashSet(StringComparer.Ordinal), + Guards = configuration.Guards.Keys.ToHashSet(StringComparer.Ordinal), + Stages = configuration.Entries.ToDictionary( + static entry => entry.Key, + entry => (entry.Value.Policy?.Stages ?? []) + .Select(static stage => stage.Id).ToHashSet(StringComparer.Ordinal), + StringComparer.Ordinal), + Nodes = configuration.Entries.ToDictionary( + static entry => entry.Key, + entry => (entry.Value.Graph?.Nodes ?? []) + .Select(static node => node.Id).ToHashSet(StringComparer.Ordinal), + StringComparer.Ordinal), + Models = (configuration.Providers?.Llm ?? []) + .Select(static provider => provider.As).ToHashSet(StringComparer.Ordinal), + }; + } + } } diff --git a/src/AgentCore.Application/Configuration/Validation/DelegationCycleCheck.cs b/src/AgentCore.Application/Configuration/Validation/DelegationCycleCheck.cs index 5652ef19..e460dbce 100644 --- a/src/AgentCore.Application/Configuration/Validation/DelegationCycleCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/DelegationCycleCheck.cs @@ -1,108 +1,111 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 8: no agent reaches itself through a chain of kind: agent tools. -internal static class DelegationCycleCheck +namespace AgentCore.Application.Configuration.Validation { - private sealed record Edge(string Target, int Agent, int Slot); - - public static void Run(AgentCoreConfiguration configuration, List errors) + /// Check 8: no agent reaches itself through a chain of kind: agent tools. + internal static class DelegationCycleCheck { - var items = configuration.Agents.Items; - if (items.Count == 0) + private sealed record Edge(string Target, int Agent, int Slot); + + public static void Run(AgentCoreConfiguration configuration, List errors) { - return; - } + IReadOnlyList items = configuration.Agents.Items; + if (items.Count == 0) + { + return; + } - var edges = BuildEdges(configuration); - var state = new Dictionary(StringComparer.Ordinal); - var path = new List(); - var reported = new HashSet(StringComparer.Ordinal); + Dictionary> edges = BuildEdges(configuration); + Dictionary state = new(StringComparer.Ordinal); + List path = []; + HashSet reported = new(StringComparer.Ordinal); - foreach (var agent in items) - { - Visit(agent.Id, edges, state, path, reported, errors); + foreach (AgentConfiguration agent in items) + { + Visit(agent.Id, edges, state, path, reported, errors); + } } - } - - // One edge for each agent-as-tool: the agent lists a tool, and that tool declares kind: agent. - // The 'agent:' field is the one explicit delegation edge in the document. 'uses:' names a - // built-in and 'binds:' names a host delegate, so neither ever names an agent, and a tool id - // that matches an agent id is a coincidence. - private static Dictionary> BuildEdges(AgentCoreConfiguration configuration) - { - var tools = configuration.Tools.ToDictionary(static tool => tool.Id, static tool => tool, StringComparer.Ordinal); - var edges = new Dictionary>(StringComparer.Ordinal); - var items = configuration.Agents.Items; - for (var index = 0; index < items.Count; index++) + // One edge for each agent-as-tool: the agent lists a tool, and that tool declares kind: agent. + // The 'agent:' field is the one explicit delegation edge in the document. 'uses:' names a + // built-in and 'binds:' names a host delegate, so neither ever names an agent, and a tool id + // that matches an agent id is a coincidence. + private static Dictionary> BuildEdges(AgentCoreConfiguration configuration) { - var agent = items[index]; - var outgoing = new List(); + Dictionary tools = configuration.Tools.ToDictionary(static tool => tool.Id, static tool => tool, StringComparer.Ordinal); + Dictionary> edges = new(StringComparer.Ordinal); + IReadOnlyList items = configuration.Agents.Items; - for (var slot = 0; slot < agent.Tools.Count; slot++) + for (int index = 0; index < items.Count; index++) { - if (tools.TryGetValue(agent.Tools[slot], out var tool) - && tool.Kind == ToolKind.Agent - && tool.Agent is { } target) + AgentConfiguration agent = items[index]; + List outgoing = []; + + for (int slot = 0; slot < agent.Tools.Count; slot++) { - outgoing.Add(new Edge(target, index, slot)); + if (tools.TryGetValue(agent.Tools[slot], out ToolConfiguration? tool) + && tool.Kind == ToolKind.Agent + && tool.Agent is { } target) + { + outgoing.Add(new Edge(target, index, slot)); + } } - } - - edges[agent.Id] = outgoing; - } - return edges; - } + edges[agent.Id] = outgoing; + } - private static void Visit( - string agent, - Dictionary> edges, - Dictionary state, - List path, - HashSet reported, - List errors) - { - if (state.TryGetValue(agent, out var mark) && mark != 0) - { - return; + return edges; } - state[agent] = 1; - path.Add(agent); - - var outgoing = edges.TryGetValue(agent, out var found) ? found : []; - foreach (var edge in outgoing) + private static void Visit( + string agent, + Dictionary> edges, + Dictionary state, + List path, + HashSet reported, + List errors) { - var start = path.IndexOf(edge.Target); - if (start < 0) + if (state.TryGetValue(agent, out int mark) && mark != 0) { - Visit(edge.Target, edges, state, path, reported, errors); - continue; + return; } - var cycle = string.Join(" -> ", path.Skip(start).Append(edge.Target)); - if (reported.Add(cycle)) + state[agent] = 1; + path.Add(agent); + + List outgoing = edges.TryGetValue(agent, out List? found) ? found : []; + foreach (Edge edge in outgoing) { - errors.Add(CycleError(edge, cycle)); + int start = path.IndexOf(edge.Target); + if (start < 0) + { + Visit(edge.Target, edges, state, path, reported, errors); + continue; + } + + string cycle = string.Join(" -> ", path.Skip(start).Append(edge.Target)); + if (reported.Add(cycle)) + { + errors.Add(CycleError(edge, cycle)); + } } - } - path.RemoveAt(path.Count - 1); - state[agent] = 2; - } + path.RemoveAt(path.Count - 1); + state[agent] = 2; + } - private static ConfigurationError CycleError(Edge edge, string cycle) - => new() + private static ConfigurationError CycleError(Edge edge, string cycle) { - Pointer = ValidationPointer.AgentTool(edge.Agent, edge.Slot), - // The compiler prints the same chain in the same 'first -> second -> first' form, and - // gives the same reason. The two messages agree rather than compete. - Message = $"this tool runs the agent '{edge.Target}', and that closes the delegation cycle " - + $"{cycle}. The conversation would never return.", - Check = ConfigurationCheck.DelegationCycles, - }; + return new() + { + Pointer = ValidationPointer.AgentTool(edge.Agent, edge.Slot), + // The compiler prints the same chain in the same 'first -> second -> first' form, and + // gives the same reason. The two messages agree rather than compete. + Message = $"this tool runs the agent '{edge.Target}', and that closes the delegation cycle " + + $"{cycle}. The conversation would never return.", + Check = ConfigurationCheck.DelegationCycles, + }; + } + } } diff --git a/src/AgentCore.Application/Configuration/Validation/EntryShapeCheck.cs b/src/AgentCore.Application/Configuration/Validation/EntryShapeCheck.cs index 824341c7..d88b0014 100644 --- a/src/AgentCore.Application/Configuration/Validation/EntryShapeCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/EntryShapeCheck.cs @@ -2,83 +2,84 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 2, entry shapes: each entry holds exactly one of agent:, policy:, or graph:. -internal static class EntryShapeCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, DeclaredNames names, List errors) + /// Check 2, entry shapes: each entry holds exactly one of agent:, policy:, or graph:. + internal static class EntryShapeCheck { - if (configuration.Agents.Items.Count == 0) + public static void Run(AgentCoreConfiguration configuration, DeclaredNames names, List errors) { - errors.Add(Reference( - "/agents/items", - "the document declares no agents:, so no entry can resolve an agent.")); - } + if (configuration.Agents.Items.Count == 0) + { + errors.Add(Reference( + "/agents/items", + "the document declares no agents:, so no entry can resolve an agent.")); + } - if (configuration.Entries.Count == 0) - { - errors.Add(Reference( - "/entries", - "the document declares no entries:, so it compiles to nothing.")); - return; - } + if (configuration.Entries.Count == 0) + { + errors.Add(Reference( + "/entries", + "the document declares no entries:, so it compiles to nothing.")); + return; + } - foreach (var (name, entry) in configuration.Entries) - { - var pointer = ValidationPointer.Entry(name); + foreach ((string? name, EntryConfiguration? entry) in configuration.Entries) + { + string pointer = ValidationPointer.Entry(name); - CheckShapeCount(name, entry, pointer, errors); - CheckAgent(name, entry.Agent, pointer, names, errors); - CheckReply(name, entry.FallbackReply, "fallbackReply", "a failed turn", pointer, errors); - CheckReply(name, entry.RefusalReply, "refusalReply", "a refused turn", pointer, errors); + CheckShapeCount(name, entry, pointer, errors); + CheckAgent(name, entry.Agent, pointer, names, errors); + CheckReply(name, entry.FallbackReply, "fallbackReply", "a failed turn", pointer, errors); + CheckReply(name, entry.RefusalReply, "refusalReply", "a refused turn", pointer, errors); + } } - } - - private static void CheckShapeCount(string name, EntryConfiguration entry, string pointer, List errors) - { - var shapes = (entry.Agent is null ? 0 : 1) + (entry.Policy is null ? 0 : 1) + (entry.Graph is null ? 0 : 1); - if (shapes == 0) - { - errors.Add(Reference( - pointer, - $"the entry '{name}' declares none of agent:, policy:, or graph:. It holds exactly one.")); - } - else if (shapes > 1) + private static void CheckShapeCount(string name, EntryConfiguration entry, string pointer, List errors) { - errors.Add(Reference( - pointer, - $"the entry '{name}' declares more than one of agent:, policy:, and graph:. It holds exactly one.")); + int shapes = (entry.Agent is null ? 0 : 1) + (entry.Policy is null ? 0 : 1) + (entry.Graph is null ? 0 : 1); + + if (shapes == 0) + { + errors.Add(Reference( + pointer, + $"the entry '{name}' declares none of agent:, policy:, or graph:. It holds exactly one.")); + } + else if (shapes > 1) + { + errors.Add(Reference( + pointer, + $"the entry '{name}' declares more than one of agent:, policy:, and graph:. It holds exactly one.")); + } } - } - private static void CheckAgent(string name, string? agentId, string pointer, DeclaredNames names, List errors) - { - if (agentId is null) + private static void CheckAgent(string name, string? agentId, string pointer, DeclaredNames names, List errors) { - return; - } + if (agentId is null) + { + return; + } - var field = ConfigurationError.AppendPointer(pointer, ValidationPointer.AgentField); + string field = ConfigurationError.AppendPointer(pointer, ValidationPointer.AgentField); - if (string.IsNullOrWhiteSpace(agentId)) - { - errors.Add(Reference(field, $"the entry '{name}' names an empty agent:. It names one id from agents.items.")); + if (string.IsNullOrWhiteSpace(agentId)) + { + errors.Add(Reference(field, $"the entry '{name}' names an empty agent:. It names one id from agents.items.")); + } + else if (!names.Agents.Contains(agentId)) + { + errors.Add(Reference(field, $"the agent '{agentId}' is not declared in agents.items")); + } } - else if (!names.Agents.Contains(agentId)) - { - errors.Add(Reference(field, $"the agent '{agentId}' is not declared in agents.items")); - } - } - private static void CheckReply(string name, string? reply, string field, string turn, string pointer, List errors) - { - if (reply is not null && string.IsNullOrWhiteSpace(reply)) + private static void CheckReply(string name, string? reply, string field, string turn, string pointer, List errors) { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, field), - $"the entry '{name}' sets a blank {field}, so {turn} would speak nothing.")); + if (reply is not null && string.IsNullOrWhiteSpace(reply)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, field), + $"the entry '{name}' sets a blank {field}, so {turn} would speak nothing.")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ExitExclusivityCheck.cs b/src/AgentCore.Application/Configuration/Validation/ExitExclusivityCheck.cs index 06ff8545..828f82a6 100644 --- a/src/AgentCore.Application/Configuration/Validation/ExitExclusivityCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/ExitExclusivityCheck.cs @@ -2,111 +2,114 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Check 5: exclusivity and coverage by evaluation. Gathers the sibling exits of each stage and -/// each graph node, then hands each set to . -/// -internal static class ExitExclusivityCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, List errors, List warnings) + /// + /// Check 5: exclusivity and coverage by evaluation. Gathers the sibling exits of each stage and + /// each graph node, then hands each set to . + /// + internal static class ExitExclusivityCheck { - var evaluator = new GuardEvaluator(configuration.Guards); - - foreach (var (name, entry) in configuration.Entries) + public static void Run(AgentCoreConfiguration configuration, List errors, List warnings) { - if (entry.Policy is { } policy) - { - CheckStages(configuration, name, policy, evaluator, errors, warnings); - } + GuardEvaluator evaluator = new(configuration.Guards); - if (entry.Graph is { } graph && graph.Edges.Count > 0) + foreach ((string? name, EntryConfiguration? entry) in configuration.Entries) { - CheckNodes(configuration, name, graph, evaluator, errors, warnings); + if (entry.Policy is { } policy) + { + CheckStages(configuration, name, policy, evaluator, errors, warnings); + } + + if (entry.Graph is { } graph && graph.Edges.Count > 0) + { + CheckNodes(configuration, name, graph, evaluator, errors, warnings); + } } } - } - private static void CheckStages( - AgentCoreConfiguration configuration, - string name, - PolicyConfiguration policy, - GuardEvaluator evaluator, - List errors, - List warnings) - { - for (var index = 0; index < policy.Stages.Count; index++) + private static void CheckStages( + AgentCoreConfiguration configuration, + string name, + PolicyConfiguration policy, + GuardEvaluator evaluator, + List errors, + List warnings) { - var stage = policy.Stages[index]; - var exits = new List(stage.To.Count); - - for (var exit = 0; exit < stage.To.Count; exit++) + for (int index = 0; index < policy.Stages.Count; index++) { - var transition = stage.To[exit]; - exits.Add(Exit(transition.When, "exit", transition.Stage, ValidationPointer.Transition(name, index, exit))); - } + StageConfiguration stage = policy.Stages[index]; + List exits = new(stage.To.Count); - var pinned = new Dictionary(StringComparer.Ordinal) - { - [ReservedStateSlots.Stage] = JsonValue.Create(stage.Id), - }; + for (int exit = 0; exit < stage.To.Count; exit++) + { + StageTransition transition = stage.To[exit]; + exits.Add(Exit(transition.When, "exit", transition.Stage, ValidationPointer.Transition(name, index, exit))); + } - GuardExclusivityCheck.Run( - new SiblingGroup( - exits, - ConfigurationError.AppendPointer(ValidationPointer.Stage(name, index), "to"), - $"the stage '{stage.Id}'", - pinned), - evaluator, - configuration.State, - errors, - warnings); - } - } + Dictionary pinned = new(StringComparer.Ordinal) + { + [ReservedStateSlots.Stage] = JsonValue.Create(stage.Id), + }; - private static void CheckNodes( - AgentCoreConfiguration configuration, - string name, - GraphConfiguration graph, - GuardEvaluator evaluator, - List errors, - List warnings) - { - var byFrom = graph.Edges - .Select(static (edge, index) => (edge, index)) - .GroupBy(static pair => pair.edge.From, StringComparer.Ordinal); + GuardExclusivityCheck.Run( + new SiblingGroup( + exits, + ConfigurationError.AppendPointer(ValidationPointer.Stage(name, index), "to"), + $"the stage '{stage.Id}'", + pinned), + evaluator, + configuration.State, + errors, + warnings); + } + } - foreach (var group in byFrom) + private static void CheckNodes( + AgentCoreConfiguration configuration, + string name, + GraphConfiguration graph, + GuardEvaluator evaluator, + List errors, + List warnings) { - var exits = group - .Select(pair => Exit(pair.edge.When, "edge", pair.edge.To, ValidationPointer.Edge(name, pair.index))) - .ToList(); + IEnumerable> byFrom = graph.Edges + .Select(static (edge, index) => (edge, index)) + .GroupBy(static pair => pair.edge.From, StringComparer.Ordinal); - GuardExclusivityCheck.Run( - new SiblingGroup( - exits, - ValidationPointer.GraphEdges(name), - $"the node '{group.Key}'", - new Dictionary(StringComparer.Ordinal)), - evaluator, - configuration.State, - errors, - warnings); + foreach (IGrouping group in byFrom) + { + List exits = [.. group.Select(pair => Exit(pair.edge.When, "edge", pair.edge.To, ValidationPointer.Edge(name, pair.index)))]; + + GuardExclusivityCheck.Run( + new SiblingGroup( + exits, + ValidationPointer.GraphEdges(name), + $"the node '{group.Key}'", + new Dictionary(StringComparer.Ordinal)), + evaluator, + configuration.State, + errors, + warnings); + } } - } - private static SiblingExit Exit(GuardReference? guard, string kind, string target, string pointer) - => new( - DescribeExit(guard, kind, target), - guard is null ? pointer : ConfigurationError.AppendPointer(pointer, "when"), - guard); + private static SiblingExit Exit(GuardReference? guard, string kind, string target, string pointer) + { + return new( + DescribeExit(guard, kind, target), + guard is null ? pointer : ConfigurationError.AppendPointer(pointer, "when"), + guard); + } - private static string DescribeExit(GuardReference? guard, string kind, string target) - => guard switch + private static string DescribeExit(GuardReference? guard, string kind, string target) { - null => $"the unconditional {kind} to '{target}'", - { Name: { } name } => $"the guard '{name}'", - _ => $"the inline rule on the {kind} to '{target}'", - }; + return guard switch + { + null => $"the unconditional {kind} to '{target}'", + { Name: { } name } => $"the guard '{name}'", + _ => $"the inline rule on the {kind} to '{target}'", + }; + } + } } diff --git a/src/AgentCore.Application/Configuration/Validation/GraphReach.cs b/src/AgentCore.Application/Configuration/Validation/GraphReach.cs index dd291a98..3c74af37 100644 --- a/src/AgentCore.Application/Configuration/Validation/GraphReach.cs +++ b/src/AgentCore.Application/Configuration/Validation/GraphReach.cs @@ -1,51 +1,52 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// Forward adjacency and reachability over a policy or a graph, shared by checks 6 and 7. -internal static class GraphReach +namespace AgentCore.Application.Configuration.Validation { - public static Dictionary> BuildAdjacency(GraphConfiguration graph) + /// Forward adjacency and reachability over a policy or a graph, shared by checks 6 and 7. + internal static class GraphReach { - var forward = new Dictionary>(StringComparer.Ordinal); - foreach (var node in graph.Nodes) - { - forward[node.Id] = []; - } - - foreach (var edge in graph.Edges) + public static Dictionary> BuildAdjacency(GraphConfiguration graph) { - if (forward.TryGetValue(edge.From, out var targets)) + Dictionary> forward = new(StringComparer.Ordinal); + foreach (GraphNodeConfiguration node in graph.Nodes) { - targets.Add(edge.To); + forward[node.Id] = []; } - } - return forward; - } + foreach (GraphEdgeConfiguration edge in graph.Edges) + { + if (forward.TryGetValue(edge.From, out List? targets)) + { + targets.Add(edge.To); + } + } - /// Every id reachable from , including the root itself. - public static HashSet Reach(string root, Dictionary> edges) - { - var seen = new HashSet(StringComparer.Ordinal) { root }; - var pending = new Stack(); - pending.Push(root); + return forward; + } - while (pending.Count > 0) + /// Every id reachable from , including the root itself. + public static HashSet Reach(string root, Dictionary> edges) { - var current = pending.Pop(); - if (!edges.TryGetValue(current, out var targets)) - { - continue; - } + HashSet seen = new(StringComparer.Ordinal) { root }; + Stack pending = new(); + pending.Push(root); - foreach (var target in targets.Where(target => !seen.Contains(target))) + while (pending.Count > 0) { - seen.Add(target); - pending.Push(target); + string current = pending.Pop(); + if (!edges.TryGetValue(current, out List? targets)) + { + continue; + } + + foreach (string? target in targets.Where(target => !seen.Contains(target))) + { + _ = seen.Add(target); + pending.Push(target); + } } - } - return seen; + return seen; + } } } diff --git a/src/AgentCore.Application/Configuration/Validation/GraphWellFormednessCheck.cs b/src/AgentCore.Application/Configuration/Validation/GraphWellFormednessCheck.cs index 379829ea..6fc3587b 100644 --- a/src/AgentCore.Application/Configuration/Validation/GraphWellFormednessCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/GraphWellFormednessCheck.cs @@ -3,71 +3,72 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 7: one start node, no orphan, and a path from every node to an output. -internal static class GraphWellFormednessCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, List errors) + /// Check 7: one start node, no orphan, and a path from every node to an output. + internal static class GraphWellFormednessCheck { - foreach (var (name, entry) in configuration.Entries) + public static void Run(AgentCoreConfiguration configuration, List errors) { - if (entry.Graph is { } graph && graph.Nodes.Count > 0) + foreach ((string? name, EntryConfiguration? entry) in configuration.Entries) { - CheckGraph(name, graph, errors); + if (entry.Graph is { } graph && graph.Nodes.Count > 0) + { + CheckGraph(name, graph, errors); + } } } - } - private static void CheckGraph(string name, GraphConfiguration graph, List errors) - { - var starts = graph.Nodes.Count(static node => node.Start); - if (starts != 1) + private static void CheckGraph(string name, GraphConfiguration graph, List errors) { - errors.Add(WellFormedness( - ValidationPointer.GraphNodes(name), - string.Create(CultureInfo.InvariantCulture, $"the graph in entry '{name}' declares {starts} start nodes, and check 7 needs exactly one"))); - } + int starts = graph.Nodes.Count(static node => node.Start); + if (starts != 1) + { + errors.Add(WellFormedness( + ValidationPointer.GraphNodes(name), + string.Create(CultureInfo.InvariantCulture, $"the graph in entry '{name}' declares {starts} start nodes, and check 7 needs exactly one"))); + } - CheckOrphans(name, graph, errors); + CheckOrphans(name, graph, errors); - var outputs = graph.Nodes.Where(static node => node.Output).Select(static node => node.Id).ToHashSet(StringComparer.Ordinal); - if (outputs.Count == 0) - { - errors.Add(WellFormedness(ValidationPointer.GraphNodes(name), "the graph declares no output node, so no path reaches an output")); - return; - } + HashSet outputs = graph.Nodes.Where(static node => node.Output).Select(static node => node.Id).ToHashSet(StringComparer.Ordinal); + if (outputs.Count == 0) + { + errors.Add(WellFormedness(ValidationPointer.GraphNodes(name), "the graph declares no output node, so no path reaches an output")); + return; + } - var forward = GraphReach.BuildAdjacency(graph); - for (var index = 0; index < graph.Nodes.Count; index++) - { - var node = graph.Nodes[index]; - if (!GraphReach.Reach(node.Id, forward).Overlaps(outputs)) + Dictionary> forward = GraphReach.BuildAdjacency(graph); + for (int index = 0; index < graph.Nodes.Count; index++) { - errors.Add(WellFormedness( - ValidationPointer.Node(name, index), - $"no path from the node '{node.Id}' reaches an output node")); + GraphNodeConfiguration node = graph.Nodes[index]; + if (!GraphReach.Reach(node.Id, forward).Overlaps(outputs)) + { + errors.Add(WellFormedness( + ValidationPointer.Node(name, index), + $"no path from the node '{node.Id}' reaches an output node")); + } } } - } - private static void CheckOrphans(string name, GraphConfiguration graph, List errors) - { - var connected = new HashSet(StringComparer.Ordinal); - foreach (var edge in graph.Edges) + private static void CheckOrphans(string name, GraphConfiguration graph, List errors) { - connected.Add(edge.From); - connected.Add(edge.To); - } + HashSet connected = new(StringComparer.Ordinal); + foreach (GraphEdgeConfiguration edge in graph.Edges) + { + _ = connected.Add(edge.From); + _ = connected.Add(edge.To); + } - for (var index = 0; index < graph.Nodes.Count; index++) - { - var node = graph.Nodes[index]; - if (!connected.Contains(node.Id)) + for (int index = 0; index < graph.Nodes.Count; index++) { - errors.Add(WellFormedness( - ValidationPointer.Node(name, index), - $"the node '{node.Id}' is an orphan: no edge reaches it and no edge leaves it")); + GraphNodeConfiguration node = graph.Nodes[index]; + if (!connected.Contains(node.Id)) + { + errors.Add(WellFormedness( + ValidationPointer.Node(name, index), + $"the node '{node.Id}' is an orphan: no edge reaches it and no edge leaves it")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/GuardEvaluator.cs b/src/AgentCore.Application/Configuration/Validation/GuardEvaluator.cs index 865adb5d..fa97cf4e 100644 --- a/src/AgentCore.Application/Configuration/Validation/GuardEvaluator.cs +++ b/src/AgentCore.Application/Configuration/Validation/GuardEvaluator.cs @@ -5,280 +5,281 @@ using Json.Logic; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// The one of this release. It runs a rule through JsonLogic. -/// -/// -/// -/// Check 5 of section 8.5 uses this type at load time, and the stage machine uses it on every turn. -/// Both paths read the same guards: table, so a guard cannot mean one thing at load time and -/// another at run time. -/// -/// -/// The evaluator runs the Rule object model of JsonLogic, and not the newer -/// JsonLogic.Apply(JsonNode, JsonNode) entry point. Measured on package version 6.1.0, the -/// newer engine returns for min and for max as soon as one -/// operand is a var read, so a guard built on either operator is false at every state. The -/// Rule model applies each argument before it compares, and it answers all twenty operators of -/// the section 8.4 allow-list correctly. -/// -/// -/// A guard is static configuration, so each rule of the guards: table deserializes exactly -/// once, when this type is constructed. A rule that arrives inline deserializes once for each node, -/// and the result is held by node identity. That removes the per-turn parse, which matters because a -/// guard runs on every turn of every conversation. -/// -/// -/// Section 8.7 fixes the failure behaviour: JsonLogic throws when a value cannot convert, and -/// check 4 cannot see every such case. This type catches the failure, reports it once for each guard, -/// treats the guard as false, and continues. It never propagates, because a failed guard must not -/// drop a conversation. A rule that fails to deserialize follows the same path: the constructor holds the -/// cause, names the guard, and reports it once, so a malformed rule never kills the process at -/// startup and never hides which guard is at fault. -/// -/// -public sealed class GuardEvaluator : IGuardEvaluator +namespace AgentCore.Application.Configuration.Validation { - private static readonly JsonNode TrueRule = JsonValue.Create(true); - - private readonly IReadOnlyDictionary _guards; - private readonly Dictionary _named; - private readonly Dictionary _inline = new(ReferenceEqualityComparer.Instance); - private readonly Action? _onFailure; - private readonly HashSet _reported = new(StringComparer.Ordinal); - private readonly Lock _gate = new(); - - /// Creates an evaluator over a guards: table. - /// The named guards, keyed by guard name. Each value is a raw JSONLogic rule. + /// + /// The one of this release. It runs a rule through JsonLogic. + /// /// - /// The cast picks the handler overload. An overload sits beside it, and a - /// bare would not choose between the two. + /// + /// Check 5 of section 8.5 uses this type at load time, and the stage machine uses it on every turn. + /// Both paths read the same guards: table, so a guard cannot mean one thing at load time and + /// another at run time. + /// + /// + /// The evaluator runs the Rule object model of JsonLogic, and not the newer + /// JsonLogic.Apply(JsonNode, JsonNode) entry point. Measured on package version 6.1.0, the + /// newer engine returns for min and for max as soon as one + /// operand is a var read, so a guard built on either operator is false at every state. The + /// Rule model applies each argument before it compares, and it answers all twenty operators of + /// the section 8.4 allow-list correctly. + /// + /// + /// A guard is static configuration, so each rule of the guards: table deserializes exactly + /// once, when this type is constructed. A rule that arrives inline deserializes once for each node, + /// and the result is held by node identity. That removes the per-turn parse, which matters because a + /// guard runs on every turn of every conversation. + /// + /// + /// Section 8.7 fixes the failure behaviour: JsonLogic throws when a value cannot convert, and + /// check 4 cannot see every such case. This type catches the failure, reports it once for each guard, + /// treats the guard as false, and continues. It never propagates, because a failed guard must not + /// drop a conversation. A rule that fails to deserialize follows the same path: the constructor holds the + /// cause, names the guard, and reports it once, so a malformed rule never kills the process at + /// startup and never hides which guard is at fault. + /// /// - public GuardEvaluator(IReadOnlyDictionary guards) - : this(guards, (Action?)null) + public sealed class GuardEvaluator : IGuardEvaluator { - } + private static readonly JsonNode TrueRule = JsonValue.Create(true); + + private readonly IReadOnlyDictionary _guards; + private readonly Dictionary _named; + private readonly Dictionary _inline = new(ReferenceEqualityComparer.Instance); + private readonly Action? _onFailure; + private readonly HashSet _reported = new(StringComparer.Ordinal); + private readonly Lock _gate = new(); + + /// Creates an evaluator over a guards: table. + /// The named guards, keyed by guard name. Each value is a raw JSONLogic rule. + /// + /// The cast picks the handler overload. An overload sits beside it, and a + /// bare would not choose between the two. + /// + public GuardEvaluator(IReadOnlyDictionary guards) + : this(guards, (Action?)null) + { + } - /// Creates an evaluator over a guards: table that reports each failure to a logger. - /// The named guards, keyed by guard name. Each value is a raw JSONLogic rule. - /// The logger the failure of each distinct guard is written to. - /// - /// This is the binding section 8.7 asks for: a guard that throws is logged once, treated as - /// false, and the conversation continues. The composition root uses it, so the report reaches a host - /// without the host writing the handler. - /// - /// is . - public GuardEvaluator(IReadOnlyDictionary guards, ILogger logger) - : this(guards, BindLogger(logger)) - { - } + /// Creates an evaluator over a guards: table that reports each failure to a logger. + /// The named guards, keyed by guard name. Each value is a raw JSONLogic rule. + /// The logger the failure of each distinct guard is written to. + /// + /// This is the binding section 8.7 asks for: a guard that throws is logged once, treated as + /// false, and the conversation continues. The composition root uses it, so the report reaches a host + /// without the host writing the handler. + /// + /// is . + public GuardEvaluator(IReadOnlyDictionary guards, ILogger logger) + : this(guards, BindLogger(logger)) + { + } - /// Creates an evaluator over a guards: table, with a failure handler. - /// The named guards, keyed by guard name. Each value is a raw JSONLogic rule. - /// - /// Receives the guard text and the cause the first time that guard fails. Section 8.7 logs once, - /// so this handler runs once for each distinct guard and never for a repeat of the same guard. A - /// guard whose rule does not deserialize reports here under its name, while the constructor runs. - /// - public GuardEvaluator(IReadOnlyDictionary guards, Action? onFailure) - { - ArgumentNullException.ThrowIfNull(guards); + /// Creates an evaluator over a guards: table, with a failure handler. + /// The named guards, keyed by guard name. Each value is a raw JSONLogic rule. + /// + /// Receives the guard text and the cause the first time that guard fails. Section 8.7 logs once, + /// so this handler runs once for each distinct guard and never for a repeat of the same guard. A + /// guard whose rule does not deserialize reports here under its name, while the constructor runs. + /// + public GuardEvaluator(IReadOnlyDictionary guards, Action? onFailure) + { + ArgumentNullException.ThrowIfNull(guards); - _guards = guards; - _onFailure = onFailure; - _named = new Dictionary(guards.Count, StringComparer.Ordinal); + _guards = guards; + _onFailure = onFailure; + _named = new Dictionary(guards.Count, StringComparer.Ordinal); - // The unconditional exit is a rule too, and check 5 resolves it as one. Compile it here so - // the hot loop of check 5 never parses it. - _inline[TrueRule] = Compile(TrueRule); + // The unconditional exit is a rule too, and check 5 resolves it as one. Compile it here so + // the hot loop of check 5 never parses it. + _inline[TrueRule] = Compile(TrueRule); - foreach (var entry in guards) - { - var compiled = Compile(entry.Value); - _named[entry.Key] = compiled; + foreach (KeyValuePair entry in guards) + { + CompiledGuard compiled = Compile(entry.Value); + _named[entry.Key] = compiled; - // Check 5 resolves a name to its node and then evaluates that node, so the same node - // reaches the inline path. Share the one compiled rule rather than parse it twice. - _inline[entry.Value] = compiled; + // Check 5 resolves a name to its node and then evaluates that node, so the same node + // reaches the inline path. Share the one compiled rule rather than parse it twice. + _inline[entry.Value] = compiled; - if (compiled.Failure is { } failure) - { - ReportOnce(entry.Key, failure); + if (compiled.Failure is { } failure) + { + ReportOnce(entry.Key, failure); + } } } - } - /// Gets the rule of a named guard. - /// The guard name. - /// The raw rule, when the table holds the name. - /// when the table holds the name. - public bool TryGetGuard(string name, out JsonNode? rule) - { - ArgumentNullException.ThrowIfNull(name); - - if (_guards.TryGetValue(name, out var found)) + /// Gets the rule of a named guard. + /// The guard name. + /// The raw rule, when the table holds the name. + /// when the table holds the name. + public bool TryGetGuard(string name, out JsonNode? rule) { - rule = found; - return true; - } - - rule = null; - return false; - } + ArgumentNullException.ThrowIfNull(name); - /// - public bool Evaluate(GuardReference guard, IReadOnlyDictionary state) - { - ArgumentNullException.ThrowIfNull(guard); - ArgumentNullException.ThrowIfNull(state); + if (_guards.TryGetValue(name, out JsonNode? found)) + { + rule = found; + return true; + } - var compiled = ResolveCompiled(guard); - if (compiled is null) - { - // A name the table does not hold is a check 2 failure at load time. At run time it is false. + rule = null; return false; } - return Apply(compiled, state, guard.ToString()); - } + /// + public bool Evaluate(GuardReference guard, IReadOnlyDictionary state) + { + ArgumentNullException.ThrowIfNull(guard); + ArgumentNullException.ThrowIfNull(state); - /// - public bool Evaluate(JsonNode rule, IReadOnlyDictionary state) - { - ArgumentNullException.ThrowIfNull(rule); - ArgumentNullException.ThrowIfNull(state); + CompiledGuard? compiled = ResolveCompiled(guard); + if (compiled is null) + { + // A name the table does not hold is a check 2 failure at load time. At run time it is false. + return false; + } - return Apply(CompileInline(rule), state, rule.ToJsonString()); - } + return Apply(compiled, state, guard.ToString()); + } - /// Resolves a reference to the rule it stands for. - /// The reference. A reference is the unconditional exit. - /// The raw rule, or when a name does not resolve. - public JsonNode? Resolve(GuardReference? guard) - { - if (guard is null) + /// + public bool Evaluate(JsonNode rule, IReadOnlyDictionary state) { - // Section 8.5 evaluates an unconditional exit as a sibling that is always true. - return TrueRule; + ArgumentNullException.ThrowIfNull(rule); + ArgumentNullException.ThrowIfNull(state); + + return Apply(CompileInline(rule), state, rule.ToJsonString()); } - if (guard.Name is null) + /// Resolves a reference to the rule it stands for. + /// The reference. A reference is the unconditional exit. + /// The raw rule, or when a name does not resolve. + public JsonNode? Resolve(GuardReference? guard) { - return guard.Rule; - } + if (guard is null) + { + // Section 8.5 evaluates an unconditional exit as a sibling that is always true. + return TrueRule; + } - return _guards.TryGetValue(guard.Name, out var rule) ? rule : null; - } + if (guard.Name is null) + { + return guard.Rule; + } - /// Builds the data document one rule reads. - /// The slot values, keyed by slot name. - /// A fresh object. Every value is cloned, so no node keeps a second parent. - public static JsonObject BuildData(IReadOnlyDictionary state) - { - ArgumentNullException.ThrowIfNull(state); + return _guards.TryGetValue(guard.Name, out JsonNode? rule) ? rule : null; + } - var data = new JsonObject(); - foreach (var entry in state) + /// Builds the data document one rule reads. + /// The slot values, keyed by slot name. + /// A fresh object. Every value is cloned, so no node keeps a second parent. + public static JsonObject BuildData(IReadOnlyDictionary state) { - data[entry.Key] = entry.Value?.DeepClone(); - } + ArgumentNullException.ThrowIfNull(state); - return data; - } + JsonObject data = []; + foreach (KeyValuePair entry in state) + { + data[entry.Key] = entry.Value?.DeepClone(); + } - /// Turns one logger into the handler the failure path conversations. - /// The logger. - /// The handler. - /// is . - private static Action BindLogger(ILogger logger) - { - ArgumentNullException.ThrowIfNull(logger); - return (guard, cause) => Log.GuardFailed(logger, guard, cause); - } + return data; + } - private CompiledGuard? ResolveCompiled(GuardReference guard) - { - if (guard.Name is { } name) + /// Turns one logger into the handler the failure path conversations. + /// The logger. + /// The handler. + /// is . + private static Action BindLogger(ILogger logger) { - return _named.TryGetValue(name, out var found) ? found : null; + ArgumentNullException.ThrowIfNull(logger); + return (guard, cause) => Log.GuardFailed(logger, guard, cause); } - return guard.Rule is { } rule ? CompileInline(rule) : null; - } - - private CompiledGuard CompileInline(JsonNode rule) - { - lock (_gate) + private CompiledGuard? ResolveCompiled(GuardReference guard) { - if (_inline.TryGetValue(rule, out var found)) + if (guard.Name is { } name) { - return found; + return _named.TryGetValue(name, out CompiledGuard? found) ? found : null; } - var compiled = Compile(rule); - _inline[rule] = compiled; - return compiled; + return guard.Rule is { } rule ? CompileInline(rule) : null; } - } - private static CompiledGuard Compile(JsonNode? rule) - { - try + private CompiledGuard CompileInline(JsonNode rule) { - return new CompiledGuard(JsonSerializer.Deserialize(rule), null); + lock (_gate) + { + if (_inline.TryGetValue(rule, out CompiledGuard? found)) + { + return found; + } + + CompiledGuard compiled = Compile(rule); + _inline[rule] = compiled; + return compiled; + } } + + private static CompiledGuard Compile(JsonNode? rule) + { + try + { + return new CompiledGuard(JsonSerializer.Deserialize(rule), null); + } #pragma warning disable CA1031 // Section 8.7: a rule that will not parse is false, and the conversation continues. - catch (Exception exception) + catch (Exception exception) #pragma warning restore CA1031 - { - return new CompiledGuard(null, exception); + { + return new CompiledGuard(null, exception); + } } - } - private bool Apply(CompiledGuard compiled, IReadOnlyDictionary state, string description) - { - if (compiled.Failure is { } failure) + private bool Apply(CompiledGuard compiled, IReadOnlyDictionary state, string description) { - ReportOnce(description, failure); - return false; - } + if (compiled.Failure is { } failure) + { + ReportOnce(description, failure); + return false; + } - try - { - var result = compiled.Parsed?.Apply(BuildData(state)); - return result is not null && result.IsTruthy(); - } + try + { + JsonNode? result = compiled.Parsed?.Apply(BuildData(state)); + return result is not null && result.IsTruthy(); + } #pragma warning disable CA1031 // Section 8.7: a guard that throws is not a defect. It is false, and the conversation continues. - catch (Exception exception) + catch (Exception exception) #pragma warning restore CA1031 - { - ReportOnce(description, exception); - return false; - } - } - - private void ReportOnce(string description, Exception exception) - { - if (_onFailure is null) - { - return; + { + ReportOnce(description, exception); + return false; + } } - lock (_gate) + private void ReportOnce(string description, Exception exception) { - if (!_reported.Add(description)) + if (_onFailure is null) { return; } + + lock (_gate) + { + if (!_reported.Add(description)) + { + return; + } + } + + _onFailure(description, exception); } - _onFailure(description, exception); + /// One rule of the table, parsed once, or the cause that stopped it parsing. + /// The parsed rule, or when the rule did not parse. + /// The cause, or when the rule parsed. + private sealed record CompiledGuard(Rule? Parsed, Exception? Failure); } - - /// One rule of the table, parsed once, or the cause that stopped it parsing. - /// The parsed rule, or when the rule did not parse. - /// The cause, or when the rule parsed. - private sealed record CompiledGuard(Rule? Parsed, Exception? Failure); } diff --git a/src/AgentCore.Application/Configuration/Validation/GuardExclusivityCheck.cs b/src/AgentCore.Application/Configuration/Validation/GuardExclusivityCheck.cs index 1c0c614d..f7ede7e7 100644 --- a/src/AgentCore.Application/Configuration/Validation/GuardExclusivityCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/GuardExclusivityCheck.cs @@ -3,101 +3,102 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// One exit of a stage or one edge of a graph, as check 5 reads it. -/// How the message names this exit. -/// The JSON Pointer to the exit. -/// The guard reference, or for an unconditional exit. -internal sealed record SiblingExit(string Description, string Pointer, GuardReference? Reference); - -/// -/// Check 5 of section 8.5: exclusivity and coverage by evaluation. -/// -/// -/// The validator enumerates the state domain and evaluates every sibling guard at every point. Two -/// true at one point is an error, and the message prints the state that triggers it. Zero true is -/// the normal case and means the stage stays where it is. This covers a stage exit and a graph edge, -/// because section 8.2 records that both silent MAF failures happen on both. -/// -internal static class GuardExclusivityCheck +namespace AgentCore.Application.Configuration.Validation { - /// Runs check 5 over one group of siblings. - /// The siblings, and what the group already fixes. - /// The evaluator that resolves and runs a rule. - /// The declared state slots. - /// Receives an overlap error. - /// Receives a partial-coverage warning. - public static void Run( - SiblingGroup group, - GuardEvaluator evaluator, - IReadOnlyDictionary slots, - List errors, - List warnings) + /// One exit of a stage or one edge of a graph, as check 5 reads it. + /// How the message names this exit. + /// The JSON Pointer to the exit. + /// The guard reference, or for an unconditional exit. + internal sealed record SiblingExit(string Description, string Pointer, GuardReference? Reference); + + /// + /// Check 5 of section 8.5: exclusivity and coverage by evaluation. + /// + /// + /// The validator enumerates the state domain and evaluates every sibling guard at every point. Two + /// true at one point is an error, and the message prints the state that triggers it. Zero true is + /// the normal case and means the stage stays where it is. This covers a stage exit and a graph edge, + /// because section 8.2 records that both silent MAF failures happen on both. + /// + internal static class GuardExclusivityCheck { - var exits = group.Exits; - if (exits.Count < 2) + /// Runs check 5 over one group of siblings. + /// The siblings, and what the group already fixes. + /// The evaluator that resolves and runs a rule. + /// The declared state slots. + /// Receives an overlap error. + /// Receives a partial-coverage warning. + public static void Run( + SiblingGroup group, + GuardEvaluator evaluator, + IReadOnlyDictionary slots, + List errors, + List warnings) { - // One exit cannot overlap a sibling, and no exit is check 6's concern. - return; - } + IReadOnlyList exits = group.Exits; + if (exits.Count < 2) + { + // One exit cannot overlap a sibling, and no exit is check 6's concern. + return; + } - var rules = new JsonNode?[exits.Count]; - var facts = new GuardRuleFacts(); - for (var index = 0; index < exits.Count; index++) - { - rules[index] = evaluator.Resolve(exits[index].Reference); - facts.Collect(rules[index]); - } + JsonNode?[] rules = new JsonNode?[exits.Count]; + GuardRuleFacts facts = new(); + for (int index = 0; index < exits.Count; index++) + { + rules[index] = evaluator.Resolve(exits[index].Reference); + facts.Collect(rules[index]); + } - var domains = StateDomain.Build(facts, slots, group.Pinned); - var total = StateDomain.CountPoints(domains); + List domains = StateDomain.Build(facts, slots, group.Pinned); + long total = StateDomain.CountPoints(domains); - IEnumerable> points; - if (total > StateDomain.MaximumPoints) - { - points = StateDomain.Sample(domains, StateDomain.MaximumPoints); - warnings.Add(new ConfigurationError + IEnumerable> points; + if (total > StateDomain.MaximumPoints) { - Pointer = group.Pointer, - Message = string.Create( - CultureInfo.InvariantCulture, - $"the state domain of {group.Description} passes {StateDomain.MaximumPoints} points, so check 5 sampled {StateDomain.MaximumPoints} points at random and its coverage is partial"), - Check = ConfigurationCheck.GuardExclusivity, - }); - } - else - { - points = StateDomain.Enumerate(domains); - } + points = StateDomain.Sample(domains, StateDomain.MaximumPoints); + warnings.Add(new ConfigurationError + { + Pointer = group.Pointer, + Message = string.Create( + CultureInfo.InvariantCulture, + $"the state domain of {group.Description} passes {StateDomain.MaximumPoints} points, so check 5 sampled {StateDomain.MaximumPoints} points at random and its coverage is partial"), + Check = ConfigurationCheck.GuardExclusivity, + }); + } + else + { + points = StateDomain.Enumerate(domains); + } - foreach (var state in points) - { - var first = -1; - for (var index = 0; index < rules.Length; index++) + foreach (Dictionary state in points) { - var rule = rules[index]; - if (rule is null || !evaluator.Evaluate(rule, state)) + int first = -1; + for (int index = 0; index < rules.Length; index++) { - continue; - } + JsonNode? rule = rules[index]; + if (rule is null || !evaluator.Evaluate(rule, state)) + { + continue; + } - if (first < 0) - { - first = index; - continue; - } + if (first < 0) + { + first = index; + continue; + } - errors.Add(new ConfigurationError - { - Pointer = exits[index].Pointer, - Message = $"{exits[first].Description} and {exits[index].Description} are both true at the same time. " - + $"The state that triggers it is {StateDomain.Describe(state)}.", - Check = ConfigurationCheck.GuardExclusivity, - }); + errors.Add(new ConfigurationError + { + Pointer = exits[index].Pointer, + Message = $"{exits[first].Description} and {exits[index].Description} are both true at the same time. " + + $"The state that triggers it is {StateDomain.Describe(state)}.", + Check = ConfigurationCheck.GuardExclusivity, + }); - // One overlap for one group is enough. A second point repeats the same defect. - return; + // One overlap for one group is enough. A second point repeats the same defect. + return; + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/GuardOperators.cs b/src/AgentCore.Application/Configuration/Validation/GuardOperators.cs index 26e623db..3a9f5031 100644 --- a/src/AgentCore.Application/Configuration/Validation/GuardOperators.cs +++ b/src/AgentCore.Application/Configuration/Validation/GuardOperators.cs @@ -1,105 +1,103 @@ using System.Collections.Frozen; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// The JSONLogic operator allow-list of section 8.4. -/// -public static class GuardOperators +namespace AgentCore.Application.Configuration.Validation { - private static readonly FrozenSet AllowedSet = new[] - { - "var", "missing", "if", "===", "!==", ">", ">=", "<", "<=", "!", "!!", - "and", "or", "in", "+", "-", "*", "/", "min", "max", - }.ToFrozenSet(StringComparer.Ordinal); - - private static readonly FrozenSet RejectedSet = new[] - { - "==", "!=", "log", "map", "filter", "reduce", "all", "some", "none", "merge", "cat", "substr", - }.ToFrozenSet(StringComparer.Ordinal); - - private static readonly FrozenDictionary Replacements = new Dictionary + /// + /// The JSONLogic operator allow-list of section 8.4. + /// + public static class GuardOperators { - ["=="] = "===", - ["!="] = "!==", - }.ToFrozenDictionary(StringComparer.Ordinal); - - private static readonly FrozenSet NumericComparisonSet = new[] - { - ">", ">=", "<", "<=", - }.ToFrozenSet(StringComparer.Ordinal); - - private static readonly string[] AllowedOrder = - [ - "var", "missing", "if", "===", "!==", ">", ">=", "<", "<=", "!", "!!", - "and", "or", "in", "+", "-", "*", "/", "min", "max", - ]; - - private static readonly string[] RejectedOrder = - [ - "==", "!=", "log", "map", "filter", "reduce", "all", "some", "none", "merge", "cat", "substr", - ]; - - /// Gets every operator a guard may use, in the order section 8.4 lists them. - public static IReadOnlyList Allowed => AllowedOrder; - - /// Gets every operator section 8.4 names as rejected, in the order it lists them. - public static IReadOnlyList Rejected => RejectedOrder; - - /// Gets the message check 4 reports for the unary sugar form of !!. - public static string DoubleNegationSugarRejection - => "the operator '!!' is written in the unary sugar form, and JsonLogic reads that form for " - + "'!' only. Use '{\"!!\": [ x ]}' instead."; + private static readonly FrozenSet AllowedSet = new[] + { + "var", "missing", "if", "===", "!==", ">", ">=", "<", "<=", "!", "!!", + "and", "or", "in", "+", "-", "*", "/", "min", "max", + }.ToFrozenSet(StringComparer.Ordinal); - /// Reports whether a guard may use an operator. - /// The operator name, as it appears in the rule. - /// when the operator is on the allow-list. - public static bool IsAllowed(string name) - { - ArgumentNullException.ThrowIfNull(name); - return AllowedSet.Contains(name); - } + private static readonly FrozenSet RejectedSet = new[] + { + "==", "!=", "log", "map", "filter", "reduce", "all", "some", "none", "merge", "cat", "substr", + }.ToFrozenSet(StringComparer.Ordinal); - /// Reports whether section 8.4 names an operator as rejected. - /// The operator name, as it appears in the rule. - /// when the operator is on the rejected list. - public static bool IsNamedRejected(string name) - { - ArgumentNullException.ThrowIfNull(name); - return RejectedSet.Contains(name); - } + private static readonly FrozenDictionary Replacements = new Dictionary + { + ["=="] = "===", + ["!="] = "!==", + }.ToFrozenDictionary(StringComparer.Ordinal); - /// Reports whether an operator compares two numbers. - /// The operator name, as it appears in the rule. - /// for >, >=, <, and <=. - public static bool IsNumericComparison(string name) - { - ArgumentNullException.ThrowIfNull(name); - return NumericComparisonSet.Contains(name); - } + private static readonly FrozenSet NumericComparisonSet = new[] + { + ">", ">=", "<", "<=", + }.ToFrozenSet(StringComparer.Ordinal); + + private static readonly string[] AllowedOrder = + [ + "var", "missing", "if", "===", "!==", ">", ">=", "<", "<=", "!", "!!", + "and", "or", "in", "+", "-", "*", "/", "min", "max", + ]; + + private static readonly string[] RejectedOrder = + [ + "==", "!=", "log", "map", "filter", "reduce", "all", "some", "none", "merge", "cat", "substr", + ]; + + /// Gets every operator a guard may use, in the order section 8.4 lists them. + public static IReadOnlyList Allowed => AllowedOrder; + + /// Gets every operator section 8.4 names as rejected, in the order it lists them. + public static IReadOnlyList Rejected => RejectedOrder; + + /// Gets the message check 4 reports for the unary sugar form of !!. + public static string DoubleNegationSugarRejection + => "the operator '!!' is written in the unary sugar form, and JsonLogic reads that form for " + + "'!' only. Use '{\"!!\": [ x ]}' instead."; + + /// Reports whether a guard may use an operator. + /// The operator name, as it appears in the rule. + /// when the operator is on the allow-list. + public static bool IsAllowed(string name) + { + ArgumentNullException.ThrowIfNull(name); + return AllowedSet.Contains(name); + } - /// Gets the allowed operator that replaces a rejected one. - /// The rejected operator name. - /// The replacement, or when the operator has none. - public static string? ReplacementFor(string name) - { - ArgumentNullException.ThrowIfNull(name); - return Replacements.TryGetValue(name, out var replacement) ? replacement : null; - } + /// Reports whether section 8.4 names an operator as rejected. + /// The operator name, as it appears in the rule. + /// when the operator is on the rejected list. + public static bool IsNamedRejected(string name) + { + ArgumentNullException.ThrowIfNull(name); + return RejectedSet.Contains(name); + } - /// Writes the message check 4 reports for an operator that is not on the allow-list. - /// The operator name, as it appears in the rule. - /// The message. It names the replacement when one exists. - public static string DescribeRejection(string name) - { - ArgumentNullException.ThrowIfNull(name); + /// Reports whether an operator compares two numbers. + /// The operator name, as it appears in the rule. + /// for >, >=, <, and <=. + public static bool IsNumericComparison(string name) + { + ArgumentNullException.ThrowIfNull(name); + return NumericComparisonSet.Contains(name); + } - var replacement = ReplacementFor(name); - if (replacement is not null) + /// Gets the allowed operator that replaces a rejected one. + /// The rejected operator name. + /// The replacement, or when the operator has none. + public static string? ReplacementFor(string name) { - return $"the operator '{name}' is rejected because it is loose equality. Use '{replacement}' instead."; + ArgumentNullException.ThrowIfNull(name); + return Replacements.TryGetValue(name, out string? replacement) ? replacement : null; } - return $"the operator '{name}' is outside the section 8.4 allow-list"; + /// Writes the message check 4 reports for an operator that is not on the allow-list. + /// The operator name, as it appears in the rule. + /// The message. It names the replacement when one exists. + public static string DescribeRejection(string name) + { + ArgumentNullException.ThrowIfNull(name); + + string? replacement = ReplacementFor(name); + return replacement is not null + ? $"the operator '{name}' is rejected because it is loose equality. Use '{replacement}' instead." + : $"the operator '{name}' is outside the section 8.4 allow-list"; + } } } diff --git a/src/AgentCore.Application/Configuration/Validation/GuardRuleCheck.cs b/src/AgentCore.Application/Configuration/Validation/GuardRuleCheck.cs index fa9811d0..336c74e0 100644 --- a/src/AgentCore.Application/Configuration/Validation/GuardRuleCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/GuardRuleCheck.cs @@ -3,94 +3,95 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 4: guard operators and variables, over every rule the document holds. -internal static class GuardRuleCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, List errors) + /// Check 4: guard operators and variables, over every rule the document holds. + internal static class GuardRuleCheck { - foreach (var guard in configuration.Guards) + public static void Run(AgentCoreConfiguration configuration, List errors) { - CheckOneRule(configuration, guard.Value, ValidationPointer.Guard(guard.Key), errors); - } - - foreach (var slot in configuration.State) - { - if (slot.Value.Increment is { } increment) + foreach (KeyValuePair guard in configuration.Guards) { - CheckOneRule(configuration, increment, ConfigurationError.AppendPointer(ValidationPointer.State(slot.Key), "increment"), errors); + CheckOneRule(configuration, guard.Value, ValidationPointer.Guard(guard.Key), errors); } - } - foreach (var (name, entry) in configuration.Entries) - { - if (entry.Policy is { } policy) + foreach (KeyValuePair slot in configuration.State) { - CheckPolicyRules(configuration, name, policy, errors); + if (slot.Value.Increment is { } increment) + { + CheckOneRule(configuration, increment, ConfigurationError.AppendPointer(ValidationPointer.State(slot.Key), "increment"), errors); + } } - if (entry.Graph is { } graph) + foreach ((string? name, EntryConfiguration? entry) in configuration.Entries) { - CheckGraphRules(configuration, name, graph, errors); + if (entry.Policy is { } policy) + { + CheckPolicyRules(configuration, name, policy, errors); + } + + if (entry.Graph is { } graph) + { + CheckGraphRules(configuration, name, graph, errors); + } } } - } - private static void CheckPolicyRules(AgentCoreConfiguration configuration, string name, PolicyConfiguration policy, List errors) - { - for (var index = 0; index < policy.Stages.Count; index++) + private static void CheckPolicyRules(AgentCoreConfiguration configuration, string name, PolicyConfiguration policy, List errors) { - var stage = policy.Stages[index]; - for (var exit = 0; exit < stage.To.Count; exit++) + for (int index = 0; index < policy.Stages.Count; index++) { - if (stage.To[exit].When?.Rule is { } rule) + StageConfiguration stage = policy.Stages[index]; + for (int exit = 0; exit < stage.To.Count; exit++) { - CheckOneRule(configuration, rule, ConfigurationError.AppendPointer(ValidationPointer.Transition(name, index, exit), "when"), errors); + if (stage.To[exit].When?.Rule is { } rule) + { + CheckOneRule(configuration, rule, ConfigurationError.AppendPointer(ValidationPointer.Transition(name, index, exit), "when"), errors); + } } } } - } - private static void CheckGraphRules(AgentCoreConfiguration configuration, string name, GraphConfiguration graph, List errors) - { - for (var index = 0; index < graph.Edges.Count; index++) + private static void CheckGraphRules(AgentCoreConfiguration configuration, string name, GraphConfiguration graph, List errors) { - if (graph.Edges[index].When?.Rule is { } rule) + for (int index = 0; index < graph.Edges.Count; index++) { - CheckOneRule(configuration, rule, ConfigurationError.AppendPointer(ValidationPointer.Edge(name, index), "when"), errors); + if (graph.Edges[index].When?.Rule is { } rule) + { + CheckOneRule(configuration, rule, ConfigurationError.AppendPointer(ValidationPointer.Edge(name, index), "when"), errors); + } } } - } - - private static void CheckOneRule(AgentCoreConfiguration configuration, JsonNode rule, string pointer, List errors) - { - var facts = new GuardRuleFacts(); - facts.Collect(rule); - foreach (var name in facts.Operators.Where(name => !GuardOperators.IsAllowed(name))) + private static void CheckOneRule(AgentCoreConfiguration configuration, JsonNode rule, string pointer, List errors) { - errors.Add(Operators(pointer, GuardOperators.DescribeRejection(name))); - } + GuardRuleFacts facts = new(); + facts.Collect(rule); - if (facts.HasDoubleNegationSugar) - { - errors.Add(Operators(pointer, GuardOperators.DoubleNegationSugarRejection)); - } + foreach (string? name in facts.Operators.Where(name => !GuardOperators.IsAllowed(name))) + { + errors.Add(Operators(pointer, GuardOperators.DescribeRejection(name))); + } - foreach (var slot in facts.Variables.Where(slot => - !configuration.State.ContainsKey(slot) && !ReservedStateSlots.Contains(slot))) - { - errors.Add(Operators(pointer, $"the rule reads the slot '{slot}', and state: does not declare it")); - } + if (facts.HasDoubleNegationSugar) + { + errors.Add(Operators(pointer, GuardOperators.DoubleNegationSugarRejection)); + } - foreach (var comparison in facts.NumericComparisons) - { - if (configuration.State.TryGetValue(comparison.Value, out var slot) && slot.Type == StateSlotType.Boolean) + foreach (string? slot in facts.Variables.Where(slot => + !configuration.State.ContainsKey(slot) && !ReservedStateSlots.Contains(slot))) { - errors.Add(Operators( - pointer, - $"the operator '{comparison.Key}' compares the slot '{comparison.Value}', and that slot is a boolean rather than a number")); + errors.Add(Operators(pointer, $"the rule reads the slot '{slot}', and state: does not declare it")); + } + + foreach (KeyValuePair comparison in facts.NumericComparisons) + { + if (configuration.State.TryGetValue(comparison.Value, out StateSlotConfiguration? slot) && slot.Type == StateSlotType.Boolean) + { + errors.Add(Operators( + pointer, + $"the operator '{comparison.Key}' compares the slot '{comparison.Value}', and that slot is a boolean rather than a number")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/GuardRuleFacts.cs b/src/AgentCore.Application/Configuration/Validation/GuardRuleFacts.cs index 48af15c6..202b039b 100644 --- a/src/AgentCore.Application/Configuration/Validation/GuardRuleFacts.cs +++ b/src/AgentCore.Application/Configuration/Validation/GuardRuleFacts.cs @@ -1,237 +1,247 @@ using System.Text.Json; using System.Text.Json.Nodes; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Everything checks 4 and 5 read out of one or more raw JSONLogic rules. -/// -/// -/// One walk collects the operators a rule uses, the slots it names, the literals it compares each -/// slot with, and the numeric comparisons it makes. Check 4 reads the first three. Check 5 reads the -/// literals, because they are the thresholds the state domain buckets around. -/// -internal sealed class GuardRuleFacts +namespace AgentCore.Application.Configuration.Validation { - /// Gets every operator the rule uses, in first-seen order. - public List Operators { get; } = []; - - /// Gets every slot the rule names through var or missing, in first-seen order. - public List Variables { get; } = []; - - /// Gets the literals the rule compares each slot with, keyed by slot name. - public Dictionary> Literals { get; } = new(StringComparer.Ordinal); - - /// Gets every numeric comparison, as the operator and the slot it reads. - public List> NumericComparisons { get; } = []; - /// - /// Reports whether the rule writes !! in the unary sugar form, as {"!!": x}. + /// Everything checks 4 and 5 read out of one or more raw JSONLogic rules. /// /// - /// The JSONLogic specification allows the sugar, and this library implements it for ! and - /// not for !!. Both engines of package version 6.1.0 fail on the sugar form, so check 4 - /// rejects it and names the working form. !! stays on the section 8.4 allow-list. + /// One walk collects the operators a rule uses, the slots it names, the literals it compares each + /// slot with, and the numeric comparisons it makes. Check 4 reads the first three. Check 5 reads the + /// literals, because they are the thresholds the state domain buckets around. /// - public bool HasDoubleNegationSugar { get; private set; } - - private readonly HashSet _seenOperators = new(StringComparer.Ordinal); - private readonly HashSet _seenVariables = new(StringComparer.Ordinal); - - /// Walks one rule and adds what it holds. - /// The raw rule. A rule adds nothing. - public void Collect(JsonNode? rule) => Walk(rule); - - /// Reads the slot name out of a { var: name } node. - /// The node to read. - /// The slot name, or when the node is not a variable read. - public static string? TryReadVariable(JsonNode? node) + internal sealed class GuardRuleFacts { - if (node is not JsonObject holder || holder.Count != 1) - { - return null; - } + /// Gets every operator the rule uses, in first-seen order. + public List Operators { get; } = []; - return holder.TryGetPropertyValue("var", out var path) ? ReadVariableName(path) : null; - } + /// Gets every slot the rule names through var or missing, in first-seen order. + public List Variables { get; } = []; - private void Walk(JsonNode? node) - { - switch (node) - { - case JsonObject holder: - foreach (var entry in holder) - { - WalkOperator(entry.Key, entry.Value); - } - - break; + /// Gets the literals the rule compares each slot with, keyed by slot name. + public Dictionary> Literals { get; } = new(StringComparer.Ordinal); - case JsonArray array: - foreach (var item in array) - { - Walk(item); - } + /// Gets every numeric comparison, as the operator and the slot it reads. + public List> NumericComparisons { get; } = []; - break; + /// + /// Reports whether the rule writes !! in the unary sugar form, as {"!!": x}. + /// + /// + /// The JSONLogic specification allows the sugar, and this library implements it for ! and + /// not for !!. Both engines of package version 6.1.0 fail on the sugar form, so check 4 + /// rejects it and names the working form. !! stays on the section 8.4 allow-list. + /// + public bool HasDoubleNegationSugar { get; private set; } - default: - // A scalar is a literal and holds nothing to collect. - break; - } - } - - private void WalkOperator(string name, JsonNode? argument) - { - if (_seenOperators.Add(name)) - { - Operators.Add(name); - } + private readonly HashSet _seenOperators = new(StringComparer.Ordinal); + private readonly HashSet _seenVariables = new(StringComparer.Ordinal); - if (string.Equals(name, "var", StringComparison.Ordinal)) + /// Walks one rule and adds what it holds. + /// The raw rule. A rule adds nothing. + public void Collect(JsonNode? rule) { - AddVariable(ReadVariableName(argument)); - return; + Walk(rule); } - if (string.Equals(name, "missing", StringComparison.Ordinal)) + /// Reads the slot name out of a { var: name } node. + /// The node to read. + /// The slot name, or when the node is not a variable read. + public static string? TryReadVariable(JsonNode? node) { - foreach (var slot in ReadNames(argument)) + if (node is not JsonObject holder || holder.Count != 1) { - AddVariable(slot); + return null; } - return; + return holder.TryGetPropertyValue("var", out JsonNode? path) ? ReadVariableName(path) : null; } - if (string.Equals(name, "!!", StringComparison.Ordinal) && argument is not JsonArray) + private void Walk(JsonNode? node) { - HasDoubleNegationSugar = true; - } + switch (node) + { + case JsonObject holder: + foreach (KeyValuePair entry in holder) + { + WalkOperator(entry.Key, entry.Value); + } - List operands = argument is JsonArray array ? [.. array] : [argument]; - RecordComparison(name, operands); + break; - foreach (var operand in operands) - { - Walk(operand); + case JsonArray array: + foreach (JsonNode? item in array) + { + Walk(item); + } + + break; + + default: + // A scalar is a literal and holds nothing to collect. + break; + } } - } - private void RecordComparison(string name, List operands) - { - if (!IsComparison(name)) + private void WalkOperator(string name, JsonNode? argument) { - return; - } + if (_seenOperators.Add(name)) + { + Operators.Add(name); + } - var (slots, literals) = SplitOperands(operands); - var numeric = GuardOperators.IsNumericComparison(name); + if (string.Equals(name, "var", StringComparison.Ordinal)) + { + AddVariable(ReadVariableName(argument)); + return; + } - foreach (var slot in slots) - { - if (numeric) + if (string.Equals(name, "missing", StringComparison.Ordinal)) { - NumericComparisons.Add(new KeyValuePair(name, slot)); + foreach (string slot in ReadNames(argument)) + { + AddVariable(slot); + } + + return; } - if (literals.Count > 0) + if (string.Equals(name, "!!", StringComparison.Ordinal) && argument is not JsonArray) { - Bucket(slot).AddRange(literals); + HasDoubleNegationSugar = true; } - } - } - private static bool IsComparison(string name) - => GuardOperators.IsNumericComparison(name) - || string.Equals(name, "===", StringComparison.Ordinal) - || string.Equals(name, "!==", StringComparison.Ordinal) - || string.Equals(name, "in", StringComparison.Ordinal); + List operands = argument is JsonArray array ? [.. array] : [argument]; + RecordComparison(name, operands); - /// Sorts the operands of one comparison into the slots it reads and the literals it compares them with. - private static (List Slots, List Literals) SplitOperands(List operands) - { - var slots = new List(); - var literals = new List(); + foreach (JsonNode? operand in operands) + { + Walk(operand); + } + } - foreach (var operand in operands) + private void RecordComparison(string name, List operands) { - if (TryReadVariable(operand) is { } slot) + if (!IsComparison(name)) { - slots.Add(slot); + return; } - else + + (List? slots, List? literals) = SplitOperands(operands); + bool numeric = GuardOperators.IsNumericComparison(name); + + foreach (string slot in slots) { - literals.AddRange(ScalarsOf(operand)); + if (numeric) + { + NumericComparisons.Add(new KeyValuePair(name, slot)); + } + + if (literals.Count > 0) + { + Bucket(slot).AddRange(literals); + } } } - return (slots, literals); - } - - /// Reads the scalars an operand holds: the value itself, or the scalar members of a list. - private static IEnumerable ScalarsOf(JsonNode? operand) - => operand switch + private static bool IsComparison(string name) { - JsonValue value => [value], - JsonArray members => members.OfType(), - _ => [], - }; + return GuardOperators.IsNumericComparison(name) + || string.Equals(name, "===", StringComparison.Ordinal) + || string.Equals(name, "!==", StringComparison.Ordinal) + || string.Equals(name, "in", StringComparison.Ordinal); + } - private List Bucket(string slot) - { - if (!Literals.TryGetValue(slot, out var bucket)) + /// Sorts the operands of one comparison into the slots it reads and the literals it compares them with. + private static (List Slots, List Literals) SplitOperands(List operands) { - bucket = []; - Literals[slot] = bucket; + List slots = []; + List literals = []; + + foreach (JsonNode? operand in operands) + { + if (TryReadVariable(operand) is { } slot) + { + slots.Add(slot); + } + else + { + literals.AddRange(ScalarsOf(operand)); + } + } + + return (slots, literals); } - return bucket; - } + /// Reads the scalars an operand holds: the value itself, or the scalar members of a list. + private static IEnumerable ScalarsOf(JsonNode? operand) + { + return operand switch + { + JsonValue value => [value], + JsonArray members => members.OfType(), + _ => [], + }; + } - private void AddVariable(string? name) - { - if (name is null) + private List Bucket(string slot) { - return; + if (!Literals.TryGetValue(slot, out List? bucket)) + { + bucket = []; + Literals[slot] = bucket; + } + + return bucket; } - if (_seenVariables.Add(name)) + private void AddVariable(string? name) { - Variables.Add(name); + if (name is null) + { + return; + } + + if (_seenVariables.Add(name)) + { + Variables.Add(name); + } } - } - private static string? ReadVariableName(JsonNode? path) - => path switch + private static string? ReadVariableName(JsonNode? path) { - JsonValue value when value.GetValueKind() == JsonValueKind.String => value.GetValue(), - JsonArray array when array.Count > 0 => ReadVariableName(array[0]), - _ => null, - }; + return path switch + { + JsonValue value when value.GetValueKind() == JsonValueKind.String => value.GetValue(), + JsonArray array when array.Count > 0 => ReadVariableName(array[0]), + _ => null, + }; + } - private static IEnumerable ReadNames(JsonNode? argument) - { - switch (argument) + private static IEnumerable ReadNames(JsonNode? argument) { - case JsonValue value when value.GetValueKind() == JsonValueKind.String: - yield return value.GetValue(); - break; + switch (argument) + { + case JsonValue value when value.GetValueKind() == JsonValueKind.String: + yield return value.GetValue(); + break; - case JsonArray array: - foreach (var item in array) - { - var name = ReadVariableName(item); - if (name is not null) + case JsonArray array: + foreach (JsonNode? item in array) { - yield return name; + string? name = ReadVariableName(item); + if (name is not null) + { + yield return name; + } } - } - break; + break; - default: - break; + default: + break; + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/IGuardEvaluator.cs b/src/AgentCore.Application/Configuration/Validation/IGuardEvaluator.cs index 5ae6e94e..bb4266a1 100644 --- a/src/AgentCore.Application/Configuration/Validation/IGuardEvaluator.cs +++ b/src/AgentCore.Application/Configuration/Validation/IGuardEvaluator.cs @@ -1,51 +1,52 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Evaluates a JSONLogic guard against a snapshot of the declared state. -/// -/// -/// -/// Section 8.4 of the design defines the operator allow-list that an implementation accepts. Check 4 -/// of section 8.5 rejects a rule that leaves that list, so a rule reaching this interface at run time -/// has already passed validation. -/// -/// -/// Section 8.7 fixes the run-time failure behaviour: a guard that throws is possible and is not a -/// defect. An implementation logs the failure once and returns . It never -/// propagates the exception, because a failed guard must not drop a conversation. -/// -/// -/// An implementation resolves a named guard through the guards: table that it receives when it -/// is constructed. A name that the table does not hold is a check 2 failure at load time, so at run -/// time an implementation treats it as . -/// -/// -public interface IGuardEvaluator +namespace AgentCore.Application.Configuration.Validation { /// - /// Evaluates a named or inline guard reference against a state snapshot. + /// Evaluates a JSONLogic guard against a snapshot of the declared state. /// - /// The guard reference taken from a stage transition or a graph edge. - /// - /// The declared state slots and the three reserved slots in - /// , keyed by slot name. A value means the - /// slot is unfilled. - /// - /// when the guard holds; otherwise . - bool Evaluate(GuardReference guard, IReadOnlyDictionary state); + /// + /// + /// Section 8.4 of the design defines the operator allow-list that an implementation accepts. Check 4 + /// of section 8.5 rejects a rule that leaves that list, so a rule reaching this interface at run time + /// has already passed validation. + /// + /// + /// Section 8.7 fixes the run-time failure behaviour: a guard that throws is possible and is not a + /// defect. An implementation logs the failure once and returns . It never + /// propagates the exception, because a failed guard must not drop a conversation. + /// + /// + /// An implementation resolves a named guard through the guards: table that it receives when it + /// is constructed. A name that the table does not hold is a check 2 failure at load time, so at run + /// time an implementation treats it as . + /// + /// + public interface IGuardEvaluator + { + /// + /// Evaluates a named or inline guard reference against a state snapshot. + /// + /// The guard reference taken from a stage transition or a graph edge. + /// + /// The declared state slots and the three reserved slots in + /// , keyed by slot name. A value means the + /// slot is unfilled. + /// + /// when the guard holds; otherwise . + bool Evaluate(GuardReference guard, IReadOnlyDictionary state); - /// - /// Evaluates a raw JSONLogic rule against a state snapshot. - /// - /// The JSONLogic rule. - /// - /// The declared state slots and the three reserved slots in - /// , keyed by slot name. A value means the - /// slot is unfilled. - /// - /// when the rule holds; otherwise . - bool Evaluate(JsonNode rule, IReadOnlyDictionary state); + /// + /// Evaluates a raw JSONLogic rule against a state snapshot. + /// + /// The JSONLogic rule. + /// + /// The declared state slots and the three reserved slots in + /// , keyed by slot name. A value means the + /// slot is unfilled. + /// + /// when the rule holds; otherwise . + bool Evaluate(JsonNode rule, IReadOnlyDictionary state); + } } diff --git a/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs b/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs index bc66c56e..6a96fbc7 100644 --- a/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs @@ -1,134 +1,137 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Refuses a scope.filterable block the search tool could not be built from. -/// -internal static class KnowledgeFilterValidator +namespace AgentCore.Application.Configuration.Validation { - private const string Pointer = "/providers/knowledge/scope/filterable"; - - /// Checks the block, adding one error per fault. - /// The document's providers.knowledge.scope block, or . - /// Where the faults go. - /// is . - internal static void Check(KnowledgeScopeConfiguration? scope, List errors) + /// + /// Refuses a scope.filterable block the search tool could not be built from. + /// + internal static class KnowledgeFilterValidator { - ArgumentNullException.ThrowIfNull(errors); + private const string Pointer = "/providers/knowledge/scope/filterable"; - if (scope?.Filterable is not { Count: > 0 } filterable) + /// Checks the block, adding one error per fault. + /// The document's providers.knowledge.scope block, or . + /// Where the faults go. + /// is . + internal static void Check(KnowledgeScopeConfiguration? scope, List errors) { - return; - } + ArgumentNullException.ThrowIfNull(errors); - if (string.IsNullOrWhiteSpace(scope.Template)) - { - errors.Add(Reference( - Pointer, - "filterable names facets and scope.template is not set, so there is no payload path " - + "to resolve a facet key to. Set the template, or drop filterable.")); - } + if (scope?.Filterable is not { Count: > 0 } filterable) + { + return; + } + + if (string.IsNullOrWhiteSpace(scope.Template)) + { + errors.Add(Reference( + Pointer, + "filterable names facets and scope.template is not set, so there is no payload path " + + "to resolve a facet key to. Set the template, or drop filterable.")); + } + + HashSet seen = new(StringComparer.Ordinal); - HashSet seen = new(StringComparer.Ordinal); + for (int index = 0; index < filterable.Count; index++) + { + KnowledgeFilterableFacetConfiguration facet = filterable[index]; + string pointer = ConfigurationError.AppendPointer(Pointer, index); + + if (string.IsNullOrWhiteSpace(facet.Key)) + { + errors.Add(Reference(pointer, "the facet key is blank, so it names no facet.")); + } + else if (!seen.Add(facet.Key)) + { + errors.Add(Reference( + pointer, + $"the facet key '{facet.Key}' is named twice. One key is one choice in the " + + "search tool's filters argument, and a repeat offers the model the same choice " + + "again.")); + } + + if (string.IsNullOrWhiteSpace(facet.Description)) + { + errors.Add(Reference( + pointer, + $"the facet '{facet.Key}' has no description. The description is the only thing " + + "the model reads before it picks a value, so a facet without one is a key it " + + "can only guess at.")); + } + + if (facet.Resolve is { } resolve) + { + CheckResolve(facet, resolve, filterable, ConfigurationError.AppendPointer(pointer, "resolve"), errors); + } + } + } - for (var index = 0; index < filterable.Count; index++) + /// + /// The lookup runs one hop: a facet resolves through the cards of another facet, and that one + /// must be pickable from its description alone, or the model would chase a chain of lookups. + /// + private static void CheckResolve( + KnowledgeFilterableFacetConfiguration facet, + KnowledgeFacetResolveConfiguration resolve, + IReadOnlyList filterable, + string pointer, + List errors) { - var facet = filterable[index]; - var pointer = ConfigurationError.AppendPointer(Pointer, index); + string via = ConfigurationError.AppendPointer(pointer, "via"); + string viaKey = ConfigurationError.AppendPointer(via, "key"); - if (string.IsNullOrWhiteSpace(facet.Key)) + if (string.Equals(resolve.Via.Key, facet.Key, StringComparison.Ordinal)) { - errors.Add(Reference(pointer, "the facet key is blank, so it names no facet.")); + errors.Add(Reference( + viaKey, + $"the facet '{facet.Key}' resolves through itself. The lookup must search the cards " + + "of another facet, one whose value the model can pick without a lookup.")); } - else if (!seen.Add(facet.Key)) + else if (filterable.FirstOrDefault(other => string.Equals(other.Key, resolve.Via.Key, StringComparison.Ordinal)) + is not { } index) { errors.Add(Reference( - pointer, - $"the facet key '{facet.Key}' is named twice. One key is one choice in the " - + "search tool's filters argument, and a repeat offers the model the same choice " - + "again.")); + viaKey, + $"the facet '{facet.Key}' resolves through '{resolve.Via.Key}', which is not a " + + "filterable facet. The lookup is a filtered search, so the facet it filters on must " + + "be one the model may set.")); } - - if (string.IsNullOrWhiteSpace(facet.Description)) + else if (index.Resolve is not null) { errors.Add(Reference( - pointer, - $"the facet '{facet.Key}' has no description. The description is the only thing " - + "the model reads before it picks a value, so a facet without one is a key it " - + "can only guess at.")); + viaKey, + $"the facet '{facet.Key}' resolves through '{index.Key}', which resolves through " + + "something else in turn. One hop only: the facet a lookup filters on must be " + + "pickable from its description alone.")); } - if (facet.Resolve is { } resolve) + if (string.IsNullOrWhiteSpace(resolve.Via.Value)) { - CheckResolve(facet, resolve, filterable, ConfigurationError.AppendPointer(pointer, "resolve"), errors); + errors.Add(Reference( + ConfigurationError.AppendPointer(via, "value"), + $"the facet '{facet.Key}' resolves through '{resolve.Via.Key}' with a blank value, so " + + "the lookup would filter on nothing.")); } - } - } - /// - /// The lookup runs one hop: a facet resolves through the cards of another facet, and that one - /// must be pickable from its description alone, or the model would chase a chain of lookups. - /// - private static void CheckResolve( - KnowledgeFilterableFacetConfiguration facet, - KnowledgeFacetResolveConfiguration resolve, - IReadOnlyList filterable, - string pointer, - List errors) - { - var via = ConfigurationError.AppendPointer(pointer, "via"); - var viaKey = ConfigurationError.AppendPointer(via, "key"); - - if (string.Equals(resolve.Via.Key, facet.Key, StringComparison.Ordinal)) - { - errors.Add(Reference( - viaKey, - $"the facet '{facet.Key}' resolves through itself. The lookup must search the cards " - + "of another facet, one whose value the model can pick without a lookup.")); - } - else if (filterable.FirstOrDefault(other => string.Equals(other.Key, resolve.Via.Key, StringComparison.Ordinal)) - is not { } index) - { - errors.Add(Reference( - viaKey, - $"the facet '{facet.Key}' resolves through '{resolve.Via.Key}', which is not a " - + "filterable facet. The lookup is a filtered search, so the facet it filters on must " - + "be one the model may set.")); - } - else if (index.Resolve is not null) - { - errors.Add(Reference( - viaKey, - $"the facet '{facet.Key}' resolves through '{index.Key}', which resolves through " - + "something else in turn. One hop only: the facet a lookup filters on must be " - + "pickable from its description alone.")); - } - - if (string.IsNullOrWhiteSpace(resolve.Via.Value)) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(via, "value"), - $"the facet '{facet.Key}' resolves through '{resolve.Via.Key}' with a blank value, so " - + "the lookup would filter on nothing.")); - } + if (string.IsNullOrWhiteSpace(resolve.Query)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "query"), + $"the facet '{facet.Key}' has a blank resolve query, so the model has nothing to search for.")); + } - if (string.IsNullOrWhiteSpace(resolve.Query)) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, "query"), - $"the facet '{facet.Key}' has a blank resolve query, so the model has nothing to search for.")); + if (string.IsNullOrWhiteSpace(resolve.Read)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "read"), + $"the facet '{facet.Key}' does not say where on the card the value is read from.")); + } } - if (string.IsNullOrWhiteSpace(resolve.Read)) + private static ConfigurationError Reference(string pointer, string message) { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, "read"), - $"the facet '{facet.Key}' does not say where on the card the value is read from.")); + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ReferenceResolution }; } } - - private static ConfigurationError Reference(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ReferenceResolution }; } diff --git a/src/AgentCore.Application/Configuration/Validation/KnowledgeScopeCheck.cs b/src/AgentCore.Application/Configuration/Validation/KnowledgeScopeCheck.cs index 6ec16e0a..36e12f4d 100644 --- a/src/AgentCore.Application/Configuration/Validation/KnowledgeScopeCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/KnowledgeScopeCheck.cs @@ -2,148 +2,149 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 2, knowledge scope: a state-built scope must not produce a filter nobody meant. -/// -/// These are document checks, not store checks: KnowledgeStartup skips the store factory -/// for a host-supplied port, but the session composes the scope either way. -/// -internal static class KnowledgeScopeCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, List errors) + /// Check 2, knowledge scope: a state-built scope must not produce a filter nobody meant. + /// + /// These are document checks, not store checks: KnowledgeStartup skips the store factory + /// for a host-supplied port, but the session composes the scope either way. + /// + internal static class KnowledgeScopeCheck { - if (configuration.Providers?.Knowledge?.Scope is not { } scope) + public static void Run(AgentCoreConfiguration configuration, List errors) { - return; - } + if (configuration.Providers?.Knowledge?.Scope is not { } scope) + { + return; + } - KnowledgeFilterValidator.Check(scope, errors); + KnowledgeFilterValidator.Check(scope, errors); - if (scope.Wildcard is { } wildcard) - { - CheckWildcardShape(wildcard, errors); - } + if (scope.Wildcard is { } wildcard) + { + CheckWildcardShape(wildcard, errors); + } - // A wildcard without fromState is a supported shape: the deployment resolves its own facets - // and passes them as the conversation's scope, which the store still widens. See - // StateKnowledgeScope.Compose and KnowledgeStartup's K19 branch. Only the reverse is refused. - if (scope.FromState.Count == 0) - { - return; - } + // A wildcard without fromState is a supported shape: the deployment resolves its own facets + // and passes them as the conversation's scope, which the store still widens. See + // StateKnowledgeScope.Compose and KnowledgeStartup's K19 branch. Only the reverse is refused. + if (scope.FromState.Count == 0) + { + return; + } - CheckWildcardCoversFromState(scope, errors); + CheckWildcardCoversFromState(scope, errors); - if (configuration.Extractor is null) - { - errors.Add(Reference( - "/extractor", - "fromState names extractor slots and this document declares no extractor, so no slot " - + "is ever filled and every conversation searches only what the wildcard admits.")); + if (configuration.Extractor is null) + { + errors.Add(Reference( + "/extractor", + "fromState names extractor slots and this document declares no extractor, so no slot " + + "is ever filled and every conversation searches only what the wildcard admits.")); + } + + foreach (string name in scope.FromState) + { + if (configuration.State.TryGetValue(name, out StateSlotConfiguration? slot)) + { + CheckFacetSlot(name, slot, errors); + } + else + { + errors.Add(Reference( + ValidationPointer.FromState, + $"fromState names the slot '{name}', which this document does not declare.")); + } + } } - foreach (var name in scope.FromState) + private static void CheckWildcardShape(KnowledgeWildcardConfiguration wildcard, List errors) { - if (configuration.State.TryGetValue(name, out var slot)) + if (string.IsNullOrWhiteSpace(wildcard.Value)) { - CheckFacetSlot(name, slot, errors); + errors.Add(Reference( + ValidationPointer.WildcardValue, + "the wildcard value is blank, so it names no payload value a card could carry.")); } - else + + if (wildcard.Facets.Count == 0) { errors.Add(Reference( - ValidationPointer.FromState, - $"fromState names the slot '{name}', which this document does not declare.")); + ValidationPointer.WildcardFacets, + "the wildcard names no facets, so it widens nothing. Name the reach facets, and " + + "never an isolation facet such as a customer id.")); } } - } - - private static void CheckWildcardShape(KnowledgeWildcardConfiguration wildcard, List errors) - { - if (string.IsNullOrWhiteSpace(wildcard.Value)) - { - errors.Add(Reference( - ValidationPointer.WildcardValue, - "the wildcard value is blank, so it names no payload value a card could carry.")); - } - if (wildcard.Facets.Count == 0) + /// The wildcard facets and the fromState names must be the same set. + private static void CheckWildcardCoversFromState(KnowledgeScopeConfiguration scope, List errors) { - errors.Add(Reference( - ValidationPointer.WildcardFacets, - "the wildcard names no facets, so it widens nothing. Name the reach facets, and " - + "never an isolation facet such as a customer id.")); - } - } + if (scope.Wildcard is not { } widened) + { + errors.Add(Reference( + ValidationPointer.Wildcard, + "fromState is set and no wildcard is. An unknown slot would then leave its facet out " + + "of the scope, putting no condition on it, and every value of that facet would be " + + "in reach. Declare the wildcard, or drop fromState.")); + return; + } - /// The wildcard facets and the fromState names must be the same set. - private static void CheckWildcardCoversFromState(KnowledgeScopeConfiguration scope, List errors) - { - if (scope.Wildcard is not { } widened) - { - errors.Add(Reference( - ValidationPointer.Wildcard, - "fromState is set and no wildcard is. An unknown slot would then leave its facet out " - + "of the scope, putting no condition on it, and every value of that facet would be " - + "in reach. Declare the wildcard, or drop fromState.")); - return; - } + foreach (string? facet in widened.Facets.Where(facet => !scope.FromState.Contains(facet, StringComparer.Ordinal))) + { + errors.Add(Reference( + ValidationPointer.WildcardFacets, + $"wildcard.facets names '{facet}' and fromState does not. The scope filter only " + + $"ever puts a condition on a fromState facet, so there is no condition on " + + $"'{facet}' for the wildcard to widen.")); + } - foreach (var facet in widened.Facets.Where(facet => !scope.FromState.Contains(facet, StringComparer.Ordinal))) - { - errors.Add(Reference( - ValidationPointer.WildcardFacets, - $"wildcard.facets names '{facet}' and fromState does not. The scope filter only " - + $"ever puts a condition on a fromState facet, so there is no condition on " - + $"'{facet}' for the wildcard to widen.")); + foreach (string? name in scope.FromState.Where(name => !widened.Facets.Contains(name, StringComparer.Ordinal))) + { + errors.Add(Reference( + ValidationPointer.WildcardFacets, + $"fromState names '{name}' and wildcard.facets does not, so an unfilled '{name}' " + + "would be searched for the literal wildcard rather than widened by it.")); + } } - foreach (var name in scope.FromState.Where(name => !widened.Facets.Contains(name, StringComparer.Ordinal))) + /// A facet slot is a string enum the extractor fills, with no default. + private static void CheckFacetSlot(string name, StateSlotConfiguration slot, List errors) { - errors.Add(Reference( - ValidationPointer.WildcardFacets, - $"fromState names '{name}' and wildcard.facets does not, so an unfilled '{name}' " - + "would be searched for the literal wildcard rather than widened by it.")); - } - } - - /// A facet slot is a string enum the extractor fills, with no default. - private static void CheckFacetSlot(string name, StateSlotConfiguration slot, List errors) - { - var pointer = ValidationPointer.State(name); + string pointer = ValidationPointer.State(name); - if (slot.Default is not null) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, "default"), - $"the facet slot '{name}' declares a default. An unfilled slot reads as its " - + "default, so every conversation before the caller says otherwise would be scoped to a " - + "guess, with no error.")); - } + if (slot.Default is not null) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "default"), + $"the facet slot '{name}' declares a default. An unfilled slot reads as its " + + "default, so every conversation before the caller says otherwise would be scoped to a " + + "guess, with no error.")); + } - if (slot.Type != StateSlotType.String) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, "type"), - $"the facet slot '{name}' is not type string. A facet holds one string value.")); - } + if (slot.Type != StateSlotType.String) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "type"), + $"the facet slot '{name}' is not type string. A facet holds one string value.")); + } - if (slot.Writer != StateWriter.Extractor) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, "writer"), - $"the facet slot '{name}' is not written by the extractor. A const slot is filled " - + "before turn 1 and would scope every call to it; a tool slot could change the " - + "scope mid-conversation.")); - } + if (slot.Writer != StateWriter.Extractor) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "writer"), + $"the facet slot '{name}' is not written by the extractor. A const slot is filled " + + "before turn 1 and would scope every call to it; a tool slot could change the " + + "scope mid-conversation.")); + } - if (slot.EnumValues is not { Count: > 0 }) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(pointer, "enum"), - $"the facet slot '{name}' declares no enum. Nothing would then stop a value the " - + "corpus has never been tagged with, which the wildcard turns into an answer " - + "from the wrong bucket rather than an empty result.")); + if (slot.EnumValues is not { Count: > 0 }) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "enum"), + $"the facet slot '{name}' declares no enum. Nothing would then stop a value the " + + "corpus has never been tagged with, which the wildcard turns into an answer " + + "from the wrong bucket rather than an empty result.")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/McpCheck.cs b/src/AgentCore.Application/Configuration/Validation/McpCheck.cs index 34b1c336..0b4a9bd1 100644 --- a/src/AgentCore.Application/Configuration/Validation/McpCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/McpCheck.cs @@ -2,69 +2,70 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 2 over the mcp: list: unique ids, and no secret where it would leak. -internal static class McpCheck +namespace AgentCore.Application.Configuration.Validation { - /// - /// Refuses a duplicate id. A duplicate connects twice and its collision surfaces only at boot, - /// naming the served tool id rather than the mcp: entry that caused it. This runs before any - /// connection opens, so it costs nothing to check here. - /// - public static void ServerIds(AgentCoreConfiguration configuration, List errors) + /// Check 2 over the mcp: list: unique ids, and no secret where it would leak. + internal static class McpCheck { - var seen = new HashSet(StringComparer.Ordinal); - for (var index = 0; index < configuration.Mcp.Count; index++) + /// + /// Refuses a duplicate id. A duplicate connects twice and its collision surfaces only at boot, + /// naming the served tool id rather than the mcp: entry that caused it. This runs before any + /// connection opens, so it costs nothing to check here. + /// + public static void ServerIds(AgentCoreConfiguration configuration, List errors) { - var server = configuration.Mcp[index]; - if (!seen.Add(server.Id)) + HashSet seen = new(StringComparer.Ordinal); + for (int index = 0; index < configuration.Mcp.Count; index++) { - errors.Add(Reference( - ConfigurationError.AppendPointer(ValidationPointer.Mcp(index), "id"), - $"two mcp: entries declare the id '{server.Id}'. An id names one server, so rename " - + "one of them.")); + McpServerConfiguration server = configuration.Mcp[index]; + if (!seen.Add(server.Id)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(ValidationPointer.Mcp(index), "id"), + $"two mcp: entries declare the id '{server.Id}'. An id names one server, so rename " + + "one of them.")); + } } } - } - /// - /// Refuses a secret reference in command: or url:. command: becomes the child's - /// argv, which every user on the box can read out of ps, and url: is logged by proxies and - /// reverse proxies along the way. Neither is a SecretTemplate, so a reference written there - /// would be passed through as its literal characters and would leak while not even working. - /// The schema cannot express "this string may not hold that substring", so it is checked here. - /// - public static void SecretPlacement(AgentCoreConfiguration configuration, List errors) - { - for (var index = 0; index < configuration.Mcp.Count; index++) + /// + /// Refuses a secret reference in command: or url:. command: becomes the child's + /// argv, which every user on the box can read out of ps, and url: is logged by proxies and + /// reverse proxies along the way. Neither is a SecretTemplate, so a reference written there + /// would be passed through as its literal characters and would leak while not even working. + /// The schema cannot express "this string may not hold that substring", so it is checked here. + /// + public static void SecretPlacement(AgentCoreConfiguration configuration, List errors) { - var server = configuration.Mcp[index]; - - for (var word = 0; word < server.Command.Count; word++) + for (int index = 0; index < configuration.Mcp.Count; index++) { - if (!server.Command[word].Contains(SecretReference.Prefix, StringComparison.Ordinal)) + McpServerConfiguration server = configuration.Mcp[index]; + + for (int word = 0; word < server.Command.Count; word++) { - continue; - } + if (!server.Command[word].Contains(SecretReference.Prefix, StringComparison.Ordinal)) + { + continue; + } - errors.Add(Reference( - ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(ValidationPointer.Mcp(index), "command"), word), - $"the mcp: server '{server.Id}' writes a ${{secret:...}} reference in command:. A " - + "command becomes the child process's argv, which every user on this machine can " - + "read out of ps, and nothing resolves a reference there — it would be passed " - + "through as its own characters. Put the credential in env: instead.")); - } + errors.Add(Reference( + ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(ValidationPointer.Mcp(index), "command"), word), + $"the mcp: server '{server.Id}' writes a ${{secret:...}} reference in command:. A " + + "command becomes the child process's argv, which every user on this machine can " + + "read out of ps, and nothing resolves a reference there — it would be passed " + + "through as its own characters. Put the credential in env: instead.")); + } - if (server.Url is { } url && url.Contains(SecretReference.Prefix, StringComparison.Ordinal)) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(ValidationPointer.Mcp(index), "url"), - $"the mcp: server '{server.Id}' writes a ${{secret:...}} reference in url:. A URL is " - + "logged by every proxy it passes, and nothing resolves a reference there — it " - + "would be passed through as its own characters. Put the credential in headers: " - + "instead.")); + if (server.Url is { } url && url.Contains(SecretReference.Prefix, StringComparison.Ordinal)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(ValidationPointer.Mcp(index), "url"), + $"the mcp: server '{server.Id}' writes a ${{secret:...}} reference in url:. A URL is " + + "logged by every proxy it passes, and nothing resolves a reference there — it " + + "would be passed through as its own characters. Put the credential in headers: " + + "instead.")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ReachabilityCheck.cs b/src/AgentCore.Application/Configuration/Validation/ReachabilityCheck.cs index adee7866..35b87cc8 100644 --- a/src/AgentCore.Application/Configuration/Validation/ReachabilityCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/ReachabilityCheck.cs @@ -2,74 +2,75 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 6: every stage is reachable from the initial stage, and every node from the start node. -internal static class ReachabilityCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, List errors) + /// Check 6: every stage is reachable from the initial stage, and every node from the start node. + internal static class ReachabilityCheck { - foreach (var (name, entry) in configuration.Entries) + public static void Run(AgentCoreConfiguration configuration, List errors) { - if (entry.Policy is { } policy) + foreach ((string? name, EntryConfiguration? entry) in configuration.Entries) { - CheckPolicy(name, policy, errors); - } + if (entry.Policy is { } policy) + { + CheckPolicy(name, policy, errors); + } - if (entry.Graph is { } graph && graph.Nodes.Count > 0) - { - CheckGraph(name, graph, errors); + if (entry.Graph is { } graph && graph.Nodes.Count > 0) + { + CheckGraph(name, graph, errors); + } } } - } - - private static void CheckPolicy(string name, PolicyConfiguration policy, List errors) - { - var edges = new Dictionary>(StringComparer.Ordinal); - foreach (var stage in policy.Stages) - { - edges[stage.Id] = [.. stage.To.Select(static transition => transition.Stage)]; - } - - var reachable = GraphReach.Reach(policy.Initial, edges); - for (var index = 0; index < policy.Stages.Count; index++) + private static void CheckPolicy(string name, PolicyConfiguration policy, List errors) { - var stage = policy.Stages[index]; - if (!reachable.Contains(stage.Id)) + Dictionary> edges = new(StringComparer.Ordinal); + foreach (StageConfiguration stage in policy.Stages) { - errors.Add(Reachability( - ValidationPointer.Stage(name, index), - $"the stage '{stage.Id}' is unreachable from the initial stage '{policy.Initial}' in entry '{name}'")); + edges[stage.Id] = [.. stage.To.Select(static transition => transition.Stage)]; } - if (!stage.Terminal && stage.To.Count == 0) + HashSet reachable = GraphReach.Reach(policy.Initial, edges); + + for (int index = 0; index < policy.Stages.Count; index++) { - errors.Add(Reachability( - ValidationPointer.Stage(name, index), - $"the stage '{stage.Id}' is not terminal and has no exit")); + StageConfiguration stage = policy.Stages[index]; + if (!reachable.Contains(stage.Id)) + { + errors.Add(Reachability( + ValidationPointer.Stage(name, index), + $"the stage '{stage.Id}' is unreachable from the initial stage '{policy.Initial}' in entry '{name}'")); + } + + if (!stage.Terminal && stage.To.Count == 0) + { + errors.Add(Reachability( + ValidationPointer.Stage(name, index), + $"the stage '{stage.Id}' is not terminal and has no exit")); + } } } - } - // A graph with zero or several start nodes is refused by check 7, so this check stays silent on it. - private static void CheckGraph(string name, GraphConfiguration graph, List errors) - { - var starts = graph.Nodes.Where(static node => node.Start).Select(static node => node.Id).ToList(); - if (starts.Count != 1) + // A graph with zero or several start nodes is refused by check 7, so this check stays silent on it. + private static void CheckGraph(string name, GraphConfiguration graph, List errors) { - return; - } + List starts = [.. graph.Nodes.Where(static node => node.Start).Select(static node => node.Id)]; + if (starts.Count != 1) + { + return; + } - var live = GraphReach.Reach(starts[0], GraphReach.BuildAdjacency(graph)); + HashSet live = GraphReach.Reach(starts[0], GraphReach.BuildAdjacency(graph)); - for (var index = 0; index < graph.Nodes.Count; index++) - { - if (!live.Contains(graph.Nodes[index].Id)) + for (int index = 0; index < graph.Nodes.Count; index++) { - errors.Add(Reachability( - ValidationPointer.Node(name, index), - $"the node '{graph.Nodes[index].Id}' is unreachable from the start node '{starts[0]}' in entry '{name}'")); + if (!live.Contains(graph.Nodes[index].Id)) + { + errors.Add(Reachability( + ValidationPointer.Node(name, index), + $"the node '{graph.Nodes[index].Id}' is unreachable from the start node '{starts[0]}' in entry '{name}'")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs b/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs index fbdb40b7..ca29c59f 100644 --- a/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs @@ -2,120 +2,123 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Check 9 over the pair providers.llm[].reasoningEffort and model.temperature. -/// -/// -/// -/// A reasoning model samples at one temperature only. When the entry sets an effort above -/// none, the vendor answers 400 to any temperature other than 1, and the message names -/// temperature without naming the effort that made it illegal. The two keys sit in -/// different parts of the document, so the pair is refused here, where the error still carries a -/// pointer at the key the author has to change. -/// -/// -/// The check reads the document only. A caller that sets a temperature on its own conversation options in -/// code can still send one the entry forbids, because no configuration check can see that. -/// -/// -internal static class ReasoningTemperatureCheck +namespace AgentCore.Application.Configuration.Validation { - /// The one temperature a reasoning entry accepts. - private const double ReasoningTemperature = 1; - - /// The tolerance around that still counts as equal. - private const double TemperatureTolerance = 1e-9; + /// + /// Check 9 over the pair providers.llm[].reasoningEffort and model.temperature. + /// + /// + /// + /// A reasoning model samples at one temperature only. When the entry sets an effort above + /// none, the vendor answers 400 to any temperature other than 1, and the message names + /// temperature without naming the effort that made it illegal. The two keys sit in + /// different parts of the document, so the pair is refused here, where the error still carries a + /// pointer at the key the author has to change. + /// + /// + /// The check reads the document only. A caller that sets a temperature on its own conversation options in + /// code can still send one the entry forbids, because no configuration check can see that. + /// + /// + internal static class ReasoningTemperatureCheck + { + /// The one temperature a reasoning entry accepts. + private const double ReasoningTemperature = 1; - /// The one reasoningEffort value that leaves temperature free. - private const string NoReasoning = "none"; + /// The tolerance around that still counts as equal. + private const double TemperatureTolerance = 1e-9; - /// Refuses every model reference whose temperature its provider entry forbids. - /// The bound document. - /// Receives one error for each offending reference. - public static void Run(AgentCoreConfiguration configuration, List errors) - { - var reasoning = ReasoningEntries(configuration); - if (reasoning.Count == 0) + /// The one reasoningEffort value that leaves temperature free. + private const string NoReasoning = "none"; + + /// Refuses every model reference whose temperature its provider entry forbids. + /// The bound document. + /// Receives one error for each offending reference. + public static void Run(AgentCoreConfiguration configuration, List errors) { - return; - } + Dictionary reasoning = ReasoningEntries(configuration); + if (reasoning.Count == 0) + { + return; + } - Check(configuration.Extractor?.Model, "/extractor/model", reasoning, errors); - Check(configuration.Evaluation?.Judge, "/evaluation/judge", reasoning, errors); - Check(configuration.Titler?.Model, "/titler/model", reasoning, errors); - Check(configuration.Agents.Defaults?.Model, "/agents/defaults/model", reasoning, errors); + Check(configuration.Extractor?.Model, "/extractor/model", reasoning, errors); + Check(configuration.Evaluation?.Judge, "/evaluation/judge", reasoning, errors); + Check(configuration.Titler?.Model, "/titler/model", reasoning, errors); + Check(configuration.Agents.Defaults?.Model, "/agents/defaults/model", reasoning, errors); - var agents = configuration.Agents.Items; - for (var index = 0; index < agents.Count; index++) - { - Check(agents[index].Model, Reference("/agents/items", index), reasoning, errors); - } + IReadOnlyList agents = configuration.Agents.Items; + for (int index = 0; index < agents.Count; index++) + { + Check(agents[index].Model, Reference("/agents/items", index), reasoning, errors); + } - for (var index = 0; index < configuration.Tools.Count; index++) - { - Check(configuration.Tools[index].Model, Reference("/tools", index), reasoning, errors); + for (int index = 0; index < configuration.Tools.Count; index++) + { + Check(configuration.Tools[index].Model, Reference("/tools", index), reasoning, errors); + } } - } - /// Maps each as name that reasons to the effort it reasons at. - /// The bound document. - /// The map, empty when no entry reasons. - private static Dictionary ReasoningEntries(AgentCoreConfiguration configuration) - { - Dictionary reasoning = new(StringComparer.Ordinal); - foreach (var entry in configuration.Providers?.Llm ?? []) + /// Maps each as name that reasons to the effort it reasons at. + /// The bound document. + /// The map, empty when no entry reasons. + private static Dictionary ReasoningEntries(AgentCoreConfiguration configuration) { - if (entry.ReasoningEffort is { Length: > 0 } effort - && !string.Equals(effort, NoReasoning, StringComparison.OrdinalIgnoreCase)) + Dictionary reasoning = new(StringComparer.Ordinal); + foreach (LlmProviderConfiguration entry in configuration.Providers?.Llm ?? []) { - reasoning[entry.As] = effort; + if (entry.ReasoningEffort is { Length: > 0 } effort + && !string.Equals(effort, NoReasoning, StringComparison.OrdinalIgnoreCase)) + { + reasoning[entry.As] = effort; + } } - } - return reasoning; - } + return reasoning; + } - /// Refuses one model reference. - /// The reference, or when the document writes none. - /// The JSON Pointer to the reference itself, without a trailing key. - /// The entries that reason, by as name. - /// Receives the error. - private static void Check( - ModelReference? model, - string pointer, - Dictionary reasoning, - List errors) - { - if (model?.Temperature is not { } temperature - || Math.Abs(temperature - ReasoningTemperature) < TemperatureTolerance - || !reasoning.TryGetValue(model.Ref, out var effort)) + /// Refuses one model reference. + /// The reference, or when the document writes none. + /// The JSON Pointer to the reference itself, without a trailing key. + /// The entries that reason, by as name. + /// Receives the error. + private static void Check( + ModelReference? model, + string pointer, + Dictionary reasoning, + List errors) { - return; + if (model?.Temperature is not { } temperature + || Math.Abs(temperature - ReasoningTemperature) < TemperatureTolerance + || !reasoning.TryGetValue(model.Ref, out string? effort)) + { + return; + } + + errors.Add(new ConfigurationError + { + Pointer = ConfigurationError.AppendPointer(pointer, "temperature"), + Message = string.Format( + CultureInfo.InvariantCulture, + "temperature {0} is refused because the model '{1}' sets reasoningEffort '{2}' in " + + "providers.llm. A reasoning entry accepts temperature {3} only. Remove temperature, " + + "or set that entry's reasoningEffort to {4}.", + temperature, + model.Ref, + effort, + ReasoningTemperature, + NoReasoning), + Check = ConfigurationCheck.ValueRange, + }); } - errors.Add(new ConfigurationError + /// Points at the model of one item of a sequence. + /// The JSON Pointer to the sequence. + /// The zero-based index of the item. + /// The pointer to that item's model reference. + private static string Reference(string sequence, int index) { - Pointer = ConfigurationError.AppendPointer(pointer, "temperature"), - Message = string.Format( - CultureInfo.InvariantCulture, - "temperature {0} is refused because the model '{1}' sets reasoningEffort '{2}' in " - + "providers.llm. A reasoning entry accepts temperature {3} only. Remove temperature, " - + "or set that entry's reasoningEffort to {4}.", - temperature, - model.Ref, - effort, - ReasoningTemperature, - NoReasoning), - Check = ConfigurationCheck.ValueRange, - }); + return ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(sequence, index), "model"); + } } - - /// Points at the model of one item of a sequence. - /// The JSON Pointer to the sequence. - /// The zero-based index of the item. - /// The pointer to that item's model reference. - private static string Reference(string sequence, int index) - => ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(sequence, index), "model"); } diff --git a/src/AgentCore.Application/Configuration/Validation/ReferenceCheck.cs b/src/AgentCore.Application/Configuration/Validation/ReferenceCheck.cs index cb8afaec..4a62dd63 100644 --- a/src/AgentCore.Application/Configuration/Validation/ReferenceCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/ReferenceCheck.cs @@ -2,173 +2,174 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Check 2, reference resolution: every agent, model, guard, stage, and node a document names is -/// one it declares. Tool ids are the other half, in . -/// -internal static class ReferenceCheck +namespace AgentCore.Application.Configuration.Validation { - public static void Run(AgentCoreConfiguration configuration, DeclaredNames names, List errors) + /// + /// Check 2, reference resolution: every agent, model, guard, stage, and node a document names is + /// one it declares. Tool ids are the other half, in . + /// + internal static class ReferenceCheck { - CheckAgentTools(configuration.Tools, names, errors); - CheckTopLevelModels(configuration, names, errors); - CheckAgents(configuration.Agents, names, errors); - - foreach (var (name, entry) in configuration.Entries) + public static void Run(AgentCoreConfiguration configuration, DeclaredNames names, List errors) { - if (entry.Policy is { } policy) - { - CheckPolicy(name, policy, names, errors); - } + CheckAgentTools(configuration.Tools, names, errors); + CheckTopLevelModels(configuration, names, errors); + CheckAgents(configuration.Agents, names, errors); - if (entry.Graph is { } graph) + foreach ((string? name, EntryConfiguration? entry) in configuration.Entries) { - CheckGraph(name, graph, names, errors); + if (entry.Policy is { } policy) + { + CheckPolicy(name, policy, names, errors); + } + + if (entry.Graph is { } graph) + { + CheckGraph(name, graph, names, errors); + } } } - } - // A kind: agent tool names the agent it runs, and that name resolves whether or not any agent - // lists the tool. The compiler catches only the listed case, and only after the load passes. - private static void CheckAgentTools(IReadOnlyList tools, DeclaredNames names, List errors) - { - for (var index = 0; index < tools.Count; index++) + // A kind: agent tool names the agent it runs, and that name resolves whether or not any agent + // lists the tool. The compiler catches only the listed case, and only after the load passes. + private static void CheckAgentTools(IReadOnlyList tools, DeclaredNames names, List errors) { - var tool = tools[index]; - if (tool.Kind == ToolKind.Agent && tool.Agent is { } target) + for (int index = 0; index < tools.Count; index++) { - AddUnknownAgent(target, ConfigurationError.AppendPointer(ValidationPointer.Tool(index), ValidationPointer.AgentField), names, errors); + ToolConfiguration tool = tools[index]; + if (tool.Kind == ToolKind.Agent && tool.Agent is { } target) + { + AddUnknownAgent(target, ConfigurationError.AppendPointer(ValidationPointer.Tool(index), ValidationPointer.AgentField), names, errors); + } } } - } - private static void CheckTopLevelModels(AgentCoreConfiguration configuration, DeclaredNames names, List errors) - { - AddUnknownModel(configuration.Extractor?.Model, "/extractor/model/ref", names, errors); - AddUnknownModel(configuration.Evaluation?.Judge, "/evaluation/judge/ref", names, errors); - AddUnknownModel(configuration.Titler?.Model, "/titler/model/ref", names, errors); - AddUnknownModel(configuration.Agents.Defaults?.Model, "/agents/defaults/model/ref", names, errors); - } - - private static void CheckAgents(AgentsConfiguration agents, DeclaredNames names, List errors) - { - var items = agents.Items; - for (var index = 0; index < items.Count; index++) + private static void CheckTopLevelModels(AgentCoreConfiguration configuration, DeclaredNames names, List errors) { - var agent = items[index]; - var pointer = ValidationPointer.Agent(index); - - AddUnknownModel( - agent.Model, - ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "model"), "ref"), - names, - errors); + AddUnknownModel(configuration.Extractor?.Model, "/extractor/model/ref", names, errors); + AddUnknownModel(configuration.Evaluation?.Judge, "/evaluation/judge/ref", names, errors); + AddUnknownModel(configuration.Titler?.Model, "/titler/model/ref", names, errors); + AddUnknownModel(configuration.Agents.Defaults?.Model, "/agents/defaults/model/ref", names, errors); + } - for (var child = 0; child < agent.Background.Count; child++) + private static void CheckAgents(AgentsConfiguration agents, DeclaredNames names, List errors) + { + IReadOnlyList items = agents.Items; + for (int index = 0; index < items.Count; index++) { - AddUnknownAgent( - agent.Background[child], - ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "background"), child), + AgentConfiguration agent = items[index]; + string pointer = ValidationPointer.Agent(index); + + AddUnknownModel( + agent.Model, + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "model"), "ref"), names, errors); + + for (int child = 0; child < agent.Background.Count; child++) + { + AddUnknownAgent( + agent.Background[child], + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "background"), child), + names, + errors); + } } } - } - private static void CheckPolicy(string name, PolicyConfiguration policy, DeclaredNames names, List errors) - { - var stages = names.Stages[name]; - - AddUnknownStage(name, policy.Initial, ConfigurationError.AppendPointer(ValidationPointer.Policy(name), "initial"), stages, errors); - - for (var index = 0; index < policy.Stages.Count; index++) + private static void CheckPolicy(string name, PolicyConfiguration policy, DeclaredNames names, List errors) { - var stage = policy.Stages[index]; + HashSet stages = names.Stages[name]; - if (stage.Agent is { } agentId) - { - AddUnknownAgent(agentId, ConfigurationError.AppendPointer(ValidationPointer.Stage(name, index), ValidationPointer.AgentField), names, errors); - } + AddUnknownStage(name, policy.Initial, ConfigurationError.AppendPointer(ValidationPointer.Policy(name), "initial"), stages, errors); - for (var exit = 0; exit < stage.To.Count; exit++) + for (int index = 0; index < policy.Stages.Count; index++) { - var transition = stage.To[exit]; - var pointer = ValidationPointer.Transition(name, index, exit); + StageConfiguration stage = policy.Stages[index]; - AddUnknownStage(name, transition.Stage, ConfigurationError.AppendPointer(pointer, "stage"), stages, errors); - AddUnknownGuard(transition.When, ConfigurationError.AppendPointer(pointer, "when"), names, errors); - } - } - } + if (stage.Agent is { } agentId) + { + AddUnknownAgent(agentId, ConfigurationError.AppendPointer(ValidationPointer.Stage(name, index), ValidationPointer.AgentField), names, errors); + } - private static void CheckGraph(string name, GraphConfiguration graph, DeclaredNames names, List errors) - { - var nodes = names.Nodes[name]; + for (int exit = 0; exit < stage.To.Count; exit++) + { + StageTransition transition = stage.To[exit]; + string pointer = ValidationPointer.Transition(name, index, exit); - for (var index = 0; index < graph.Agents.Count; index++) - { - AddUnknownAgent(graph.Agents[index], ConfigurationError.AppendPointer(ValidationPointer.GraphAgents(name), index), names, errors); + AddUnknownStage(name, transition.Stage, ConfigurationError.AppendPointer(pointer, "stage"), stages, errors); + AddUnknownGuard(transition.When, ConfigurationError.AppendPointer(pointer, "when"), names, errors); + } + } } - for (var index = 0; index < graph.Nodes.Count; index++) + private static void CheckGraph(string name, GraphConfiguration graph, DeclaredNames names, List errors) { - if (graph.Nodes[index].Agent is { } nodeAgent) + HashSet nodes = names.Nodes[name]; + + for (int index = 0; index < graph.Agents.Count; index++) { - AddUnknownAgent(nodeAgent, ConfigurationError.AppendPointer(ValidationPointer.Node(name, index), ValidationPointer.AgentField), names, errors); + AddUnknownAgent(graph.Agents[index], ConfigurationError.AppendPointer(ValidationPointer.GraphAgents(name), index), names, errors); } - } - for (var index = 0; index < graph.Edges.Count; index++) - { - var edge = graph.Edges[index]; - var pointer = ValidationPointer.Edge(name, index); + for (int index = 0; index < graph.Nodes.Count; index++) + { + if (graph.Nodes[index].Agent is { } nodeAgent) + { + AddUnknownAgent(nodeAgent, ConfigurationError.AppendPointer(ValidationPointer.Node(name, index), ValidationPointer.AgentField), names, errors); + } + } + + for (int index = 0; index < graph.Edges.Count; index++) + { + GraphEdgeConfiguration edge = graph.Edges[index]; + string pointer = ValidationPointer.Edge(name, index); - AddUnknownNode(name, edge.From, ConfigurationError.AppendPointer(pointer, "from"), nodes, errors); - AddUnknownNode(name, edge.To, ConfigurationError.AppendPointer(pointer, "to"), nodes, errors); - AddUnknownGuard(edge.When, ConfigurationError.AppendPointer(pointer, "when"), names, errors); + AddUnknownNode(name, edge.From, ConfigurationError.AppendPointer(pointer, "from"), nodes, errors); + AddUnknownNode(name, edge.To, ConfigurationError.AppendPointer(pointer, "to"), nodes, errors); + AddUnknownGuard(edge.When, ConfigurationError.AppendPointer(pointer, "when"), names, errors); + } } - } - private static void AddUnknownAgent(string agentId, string pointer, DeclaredNames names, List errors) - { - if (!names.Agents.Contains(agentId)) + private static void AddUnknownAgent(string agentId, string pointer, DeclaredNames names, List errors) { - errors.Add(Reference(pointer, $"the agent '{agentId}' is not declared in agents.items")); + if (!names.Agents.Contains(agentId)) + { + errors.Add(Reference(pointer, $"the agent '{agentId}' is not declared in agents.items")); + } } - } - private static void AddUnknownStage(string entry, string stage, string pointer, HashSet stages, List errors) - { - if (!stages.Contains(stage)) + private static void AddUnknownStage(string entry, string stage, string pointer, HashSet stages, List errors) { - errors.Add(Reference(pointer, $"the stage '{stage}' is not declared in policy.stages in entry '{entry}'")); + if (!stages.Contains(stage)) + { + errors.Add(Reference(pointer, $"the stage '{stage}' is not declared in policy.stages in entry '{entry}'")); + } } - } - private static void AddUnknownNode(string entry, string node, string pointer, HashSet nodes, List errors) - { - if (!nodes.Contains(node)) + private static void AddUnknownNode(string entry, string node, string pointer, HashSet nodes, List errors) { - errors.Add(Reference(pointer, $"the node '{node}' is not declared in graph.nodes in entry '{entry}'")); + if (!nodes.Contains(node)) + { + errors.Add(Reference(pointer, $"the node '{node}' is not declared in graph.nodes in entry '{entry}'")); + } } - } - private static void AddUnknownGuard(GuardReference? guard, string pointer, DeclaredNames names, List errors) - { - if (guard?.Name is { } name && !names.Guards.Contains(name)) + private static void AddUnknownGuard(GuardReference? guard, string pointer, DeclaredNames names, List errors) { - errors.Add(Reference(pointer, $"the guard '{name}' is not declared in guards:")); + if (guard?.Name is { } name && !names.Guards.Contains(name)) + { + errors.Add(Reference(pointer, $"the guard '{name}' is not declared in guards:")); + } } - } - /// Resolves one model reference against the as: names of providers.llm. - private static void AddUnknownModel(ModelReference? model, string pointer, DeclaredNames names, List errors) - { - if (model is { } reference && !names.Models.Contains(reference.Ref)) + /// Resolves one model reference against the as: names of providers.llm. + private static void AddUnknownModel(ModelReference? model, string pointer, DeclaredNames names, List errors) { - errors.Add(Reference(pointer, $"the model '{reference.Ref}' is not declared in providers.llm")); + if (model is { } reference && !names.Models.Contains(reference.Ref)) + { + errors.Add(Reference(pointer, $"the model '{reference.Ref}' is not declared in providers.llm")); + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ServedReferenceCheck.cs b/src/AgentCore.Application/Configuration/Validation/ServedReferenceCheck.cs index 55e15631..cc263810 100644 --- a/src/AgentCore.Application/Configuration/Validation/ServedReferenceCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/ServedReferenceCheck.cs @@ -3,143 +3,146 @@ using Microsoft.Agents.AI; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// -/// Check 2, tool ids and skill names: the references only a registry or a bound folder can satisfy. -/// Decision 15 keeps these apart from because an MCP server's -/// discovery is the only thing that can satisfy a tool reference, so this half has to wait for it. -/// -internal static class ServedReferenceCheck +namespace AgentCore.Application.Configuration.Validation { - /// Resolves every from: state slot and every agent's tools: entry against what is served. - public static void Tools(AgentCoreConfiguration configuration, IReadOnlySet servedToolIds, List errors) + /// + /// Check 2, tool ids and skill names: the references only a registry or a bound folder can satisfy. + /// Decision 15 keeps these apart from because an MCP server's + /// discovery is the only thing that can satisfy a tool reference, so this half has to wait for it. + /// + internal static class ServedReferenceCheck { - foreach (var slot in configuration.State) + /// Resolves every from: state slot and every agent's tools: entry against what is served. + public static void Tools(AgentCoreConfiguration configuration, IReadOnlySet servedToolIds, List errors) { - if (slot.Value.From is { } from && !servedToolIds.Contains(from.ToolId)) + foreach (KeyValuePair slot in configuration.State) { - errors.Add(Reference( - ConfigurationError.AppendPointer(ValidationPointer.State(slot.Key), "from"), - UnservedTool(from.ToolId))); + if (slot.Value.From is { } from && !servedToolIds.Contains(from.ToolId)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(ValidationPointer.State(slot.Key), "from"), + UnservedTool(from.ToolId))); + } } - } - var items = configuration.Agents.Items; - for (var index = 0; index < items.Count; index++) - { - var agent = items[index]; - for (var slot = 0; slot < agent.Tools.Count; slot++) + IReadOnlyList items = configuration.Agents.Items; + for (int index = 0; index < items.Count; index++) { - if (!servedToolIds.Contains(agent.Tools[slot])) + AgentConfiguration agent = items[index]; + for (int slot = 0; slot < agent.Tools.Count; slot++) { - errors.Add(Reference(ValidationPointer.AgentTool(index, slot), UnservedTool(agent.Tools[slot]))); + if (!servedToolIds.Contains(agent.Tools[slot])) + { + errors.Add(Reference(ValidationPointer.AgentTool(index, slot), UnservedTool(agent.Tools[slot]))); + } } } } - } - /// Resolves every agent's skills: and pinned: entry against what the bound folder serves. - public static void Skills(AgentCoreConfiguration configuration, IReadOnlySet servedSkillNames, List errors) - { - var served = string.Join(", ", servedSkillNames.Order(StringComparer.Ordinal)); - var items = configuration.Agents.Items; - - for (var index = 0; index < items.Count; index++) + /// Resolves every agent's skills: and pinned: entry against what the bound folder serves. + public static void Skills(AgentCoreConfiguration configuration, IReadOnlySet servedSkillNames, List errors) { - var agent = items[index]; - SkillNames(agent.Skills, "skills", index, servedSkillNames, served, errors); - SkillNames(agent.Pinned, "pinned", index, servedSkillNames, served, errors); - } - } + string served = string.Join(", ", servedSkillNames.Order(StringComparer.Ordinal)); + IReadOnlyList items = configuration.Agents.Items; - /// - /// Refuses a skill that is both pinned and loadable. Its body would sit in the prompt and be - /// offered to load_skill at once, and the second copy is pure cost. - /// - public static void PinnedSkills(AgentCoreConfiguration configuration, List errors) - { - var items = configuration.Agents.Items; + for (int index = 0; index < items.Count; index++) + { + AgentConfiguration agent = items[index]; + SkillNames(agent.Skills, "skills", index, servedSkillNames, served, errors); + SkillNames(agent.Pinned, "pinned", index, servedSkillNames, served, errors); + } + } - for (var index = 0; index < items.Count; index++) + /// + /// Refuses a skill that is both pinned and loadable. Its body would sit in the prompt and be + /// offered to load_skill at once, and the second copy is pure cost. + /// + public static void PinnedSkills(AgentCoreConfiguration configuration, List errors) { - var agent = items[index]; - var loadable = new HashSet(agent.Skills, StringComparer.Ordinal); + IReadOnlyList items = configuration.Agents.Items; - for (var slot = 0; slot < agent.Pinned.Count; slot++) + for (int index = 0; index < items.Count; index++) { - if (!loadable.Contains(agent.Pinned[slot])) + AgentConfiguration agent = items[index]; + HashSet loadable = new(agent.Skills, StringComparer.Ordinal); + + for (int slot = 0; slot < agent.Pinned.Count; slot++) + { + if (!loadable.Contains(agent.Pinned[slot])) + { + continue; + } + + errors.Add(Reference( + ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(ValidationPointer.Agent(index), "pinned"), slot), + $"the skill '{agent.Pinned[slot]}' is both pinned and in the skills: list. " + + "A pinned skill is already in the prompt, so drop it from skills:.")); + } + } + } + + private static void SkillNames( + IReadOnlyList names, + string key, + int agentIndex, + IReadOnlySet servedSkillNames, + string served, + List errors) + { + for (int slot = 0; slot < names.Count; slot++) + { + if (servedSkillNames.Contains(names[slot])) { continue; } errors.Add(Reference( ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(ValidationPointer.Agent(index), "pinned"), slot), - $"the skill '{agent.Pinned[slot]}' is both pinned and in the skills: list. " - + "A pinned skill is already in the prompt, so drop it from skills:.")); + ConfigurationError.AppendPointer(ValidationPointer.Agent(agentIndex), key), slot), + $"the skill '{names[slot]}' is not in the bound skills folder. " + + $"The folder serves: {served}.")); } } - } - private static void SkillNames( - IReadOnlyList names, - string key, - int agentIndex, - IReadOnlySet servedSkillNames, - string served, - List errors) - { - for (var slot = 0; slot < names.Count; slot++) + /// + /// Refuses a declared tool id that the skills provider registers under the same name. The + /// provider's tools are added per agent and never pass through the tool registry, so a + /// collision is invisible until the model receives two tools of one name. + /// + public static void SkillToolNames(AgentCoreConfiguration configuration, List errors) { - if (servedSkillNames.Contains(names[slot])) + IReadOnlyList items = configuration.Agents.Items; + if (!items.Any(agent => agent.Skills.Count > 0)) { - continue; + return; } - errors.Add(Reference( - ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(ValidationPointer.Agent(agentIndex), key), slot), - $"the skill '{names[slot]}' is not in the bound skills folder. " - + $"The folder serves: {served}.")); - } - } + string[] reserved = + [ + AgentSkillsProvider.LoadSkillToolName, + AgentSkillsProvider.ReadSkillResourceToolName, + AgentSkillsProvider.RunSkillScriptToolName, + ]; - /// - /// Refuses a declared tool id that the skills provider registers under the same name. The - /// provider's tools are added per agent and never pass through the tool registry, so a - /// collision is invisible until the model receives two tools of one name. - /// - public static void SkillToolNames(AgentCoreConfiguration configuration, List errors) - { - var items = configuration.Agents.Items; - if (!items.Any(agent => agent.Skills.Count > 0)) - { - return; - } - - string[] reserved = - [ - AgentSkillsProvider.LoadSkillToolName, - AgentSkillsProvider.ReadSkillResourceToolName, - AgentSkillsProvider.RunSkillScriptToolName, - ]; - - var tools = configuration.Tools; - for (var index = 0; index < tools.Count; index++) - { - if (!reserved.Contains(tools[index].Id, StringComparer.Ordinal)) + IReadOnlyList tools = configuration.Tools; + for (int index = 0; index < tools.Count; index++) { - continue; + if (!reserved.Contains(tools[index].Id, StringComparer.Ordinal)) + { + continue; + } + + errors.Add(Reference( + ConfigurationError.AppendPointer(ValidationPointer.Tool(index), "id"), + $"the tool id '{tools[index].Id}' is reserved while any agent declares a skills: " + + "list, because the skills provider registers a tool of that name. Rename the tool.")); } + } - errors.Add(Reference( - ConfigurationError.AppendPointer(ValidationPointer.Tool(index), "id"), - $"the tool id '{tools[index].Id}' is reserved while any agent declares a skills: " - + "list, because the skills provider registers a tool of that name. Rename the tool.")); + private static string UnservedTool(string toolId) + { + return $"nothing serves the tool '{toolId}'. Declare it in tools:, or check that an mcp: server offers it."; } } - - private static string UnservedTool(string toolId) - => $"nothing serves the tool '{toolId}'. Declare it in tools:, or check that an mcp: server offers it."; } diff --git a/src/AgentCore.Application/Configuration/Validation/SiblingGroup.cs b/src/AgentCore.Application/Configuration/Validation/SiblingGroup.cs index 28888180..c8b0e899 100644 --- a/src/AgentCore.Application/Configuration/Validation/SiblingGroup.cs +++ b/src/AgentCore.Application/Configuration/Validation/SiblingGroup.cs @@ -1,14 +1,15 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Configuration.Validation; - -/// One group of siblings check 5 reads together: the exits of one stage, or the edges out of one node. -/// The siblings, in document order. -/// The JSON Pointer to the group, used by the coverage warning. -/// How the warning names the group. -/// Slots whose value the group already fixes, such as stage. -internal sealed record SiblingGroup( - IReadOnlyList Exits, - string Pointer, - string Description, - IReadOnlyDictionary Pinned); +namespace AgentCore.Application.Configuration.Validation +{ + /// One group of siblings check 5 reads together: the exits of one stage, or the edges out of one node. + /// The siblings, in document order. + /// The JSON Pointer to the group, used by the coverage warning. + /// How the warning names the group. + /// Slots whose value the group already fixes, such as stage. + internal sealed record SiblingGroup( + IReadOnlyList Exits, + string Pointer, + string Description, + IReadOnlyDictionary Pinned); +} diff --git a/src/AgentCore.Application/Configuration/Validation/SlotWriterCheck.cs b/src/AgentCore.Application/Configuration/Validation/SlotWriterCheck.cs index 4aacb33a..84304b61 100644 --- a/src/AgentCore.Application/Configuration/Validation/SlotWriterCheck.cs +++ b/src/AgentCore.Application/Configuration/Validation/SlotWriterCheck.cs @@ -2,73 +2,82 @@ using AgentCore.Application.Configuration.Schema; using static AgentCore.Application.Configuration.Validation.ValidationErrors; -namespace AgentCore.Application.Configuration.Validation; - -/// Check 3: one writer for each slot. -internal static class SlotWriterCheck +namespace AgentCore.Application.Configuration.Validation { - /// The increment: field of a counter slot. Named once, so the check and the two maps under it cannot drift apart. - private const string IncrementField = "increment"; - - public static void Run(AgentCoreConfiguration configuration, List errors) + /// Check 3: one writer for each slot. + internal static class SlotWriterCheck { - foreach (var entry in configuration.State) - { - var pointer = ValidationPointer.State(entry.Key); - var slot = entry.Value; + /// The increment: field of a counter slot. Named once, so the check and the two maps under it cannot drift apart. + private const string IncrementField = "increment"; - if (ReservedStateSlots.Contains(entry.Key)) + public static void Run(AgentCoreConfiguration configuration, List errors) + { + foreach (KeyValuePair entry in configuration.State) { - errors.Add(Writers( - pointer, - $"the slot has two writers: '{entry.Key}' is a reserved read-only slot that is always present, and state: declares it again")); - } + string pointer = ValidationPointer.State(entry.Key); + StateSlotConfiguration slot = entry.Value; - var owner = OwnerField(slot.Writer); - if (owner is not null && FieldValue(slot, owner) is null) - { - errors.Add(Writers( - pointer, - $"the slot has zero writers: writer: {WriterName(slot.Writer)} fills the slot from '{owner}:', and the slot declares none")); - } + if (ReservedStateSlots.Contains(entry.Key)) + { + errors.Add(Writers( + pointer, + $"the slot has two writers: '{entry.Key}' is a reserved read-only slot that is always present, and state: declares it again")); + } - foreach (var field in new[] { "from", IncrementField, "value" }) - { - if (string.Equals(field, owner, StringComparison.Ordinal) || FieldValue(slot, field) is null) + string? owner = OwnerField(slot.Writer); + if (owner is not null && FieldValue(slot, owner) is null) { - continue; + errors.Add(Writers( + pointer, + $"the slot has zero writers: writer: {WriterName(slot.Writer)} fills the slot from '{owner}:', and the slot declares none")); } - errors.Add(Writers( - ConfigurationError.AppendPointer(pointer, field), - $"the slot has two writers: writer: {WriterName(slot.Writer)} owns it, and '{field}:' names a second")); + foreach (string? field in new[] { "from", IncrementField, "value" }) + { + if (string.Equals(field, owner, StringComparison.Ordinal) || FieldValue(slot, field) is null) + { + continue; + } + + errors.Add(Writers( + ConfigurationError.AppendPointer(pointer, field), + $"the slot has two writers: writer: {WriterName(slot.Writer)} owns it, and '{field}:' names a second")); + } } } - } - private static string? OwnerField(StateWriter writer) - => writer switch + private static string? OwnerField(StateWriter writer) { - StateWriter.Tool => "from", - StateWriter.Counter => IncrementField, - StateWriter.Const => "value", - _ => null, - }; + return writer switch + { + StateWriter.Tool => "from", + StateWriter.Counter => IncrementField, + StateWriter.Const => "value", + StateWriter.Extractor => null, + _ => throw new ArgumentOutOfRangeException(nameof(writer), writer, "The state writer vocabulary is closed, and this value is not in it."), + }; + } - private static string WriterName(StateWriter writer) - => writer switch + private static string WriterName(StateWriter writer) { - StateWriter.Tool => "tool", - StateWriter.Counter => "counter", - StateWriter.Const => "const", - _ => "extractor", - }; + return writer switch + { + StateWriter.Tool => "tool", + StateWriter.Counter => "counter", + StateWriter.Const => "const", + StateWriter.Extractor => "extractor", + _ => throw new ArgumentOutOfRangeException(nameof(writer), writer, "The state writer vocabulary is closed, and this value is not in it."), + }; + } - private static object? FieldValue(StateSlotConfiguration slot, string field) - => field switch + private static object? FieldValue(StateSlotConfiguration slot, string field) { - "from" => slot.From, - IncrementField => slot.Increment, - _ => slot.Value, - }; + return field switch + { + "from" => slot.From, + IncrementField => slot.Increment, + _ => slot.Value, + }; + } + } } diff --git a/src/AgentCore.Application/Configuration/Validation/StateDomain.cs b/src/AgentCore.Application/Configuration/Validation/StateDomain.cs index d76e2cee..c516b24c 100644 --- a/src/AgentCore.Application/Configuration/Validation/StateDomain.cs +++ b/src/AgentCore.Application/Configuration/Validation/StateDomain.cs @@ -2,317 +2,321 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Configuration.Validation; - -/// One slot and every value check 5 gives it. -/// The slot name. -/// The values, in a stable order. -internal sealed record SlotDomain(string Name, IReadOnlyList Points); - -/// -/// The state-domain enumeration of check 5, section 8.5. -/// -/// -/// A boolean gives two points. An enum gives its members. A number is bucketed below, at, and above -/// each threshold the sibling rules mention. A string that no rule compares is not enumerated. Only -/// the slots the sibling rules name enter the product, so five booleans give 32 points. -/// -internal static class StateDomain +namespace AgentCore.Application.Configuration.Validation { - /// The point count above which check 5 samples instead of enumerating. - public const int MaximumPoints = 65536; - - /// The value a string slot takes to stand for "any value the rules do not name". - public const string OtherString = "\0agentcore-other"; - - private const int SampleSeed = 20250811; - - /// Builds the domain of every slot the sibling rules name. - /// What the walk found in the sibling rules. - /// The declared slots, keyed by name. - /// Slots whose value is already known, such as stage on a stage exit. - /// One domain for each named slot, in first-seen order. - public static List Build( - GuardRuleFacts facts, - IReadOnlyDictionary slots, - IReadOnlyDictionary pinned) + /// One slot and every value check 5 gives it. + /// The slot name. + /// The values, in a stable order. + internal sealed record SlotDomain(string Name, IReadOnlyList Points); + + /// + /// The state-domain enumeration of check 5, section 8.5. + /// + /// + /// A boolean gives two points. An enum gives its members. A number is bucketed below, at, and above + /// each threshold the sibling rules mention. A string that no rule compares is not enumerated. Only + /// the slots the sibling rules name enter the product, so five booleans give 32 points. + /// + internal static class StateDomain { - var domains = new List(); - - foreach (var name in facts.Variables) + /// The point count above which check 5 samples instead of enumerating. + public const int MaximumPoints = 65536; + + /// The value a string slot takes to stand for "any value the rules do not name". + public const string OtherString = "\0agentcore-other"; + + private const int SampleSeed = 20250811; + + /// Builds the domain of every slot the sibling rules name. + /// What the walk found in the sibling rules. + /// The declared slots, keyed by name. + /// Slots whose value is already known, such as stage on a stage exit. + /// One domain for each named slot, in first-seen order. + public static List Build( + GuardRuleFacts facts, + IReadOnlyDictionary slots, + IReadOnlyDictionary pinned) { - if (pinned.TryGetValue(name, out var fixedValue)) + List domains = []; + + foreach (string name in facts.Variables) { - domains.Add(new SlotDomain(name, [fixedValue])); - continue; + if (pinned.TryGetValue(name, out JsonNode? fixedValue)) + { + domains.Add(new SlotDomain(name, [fixedValue])); + continue; + } + + _ = facts.Literals.TryGetValue(name, out List? literals); + domains.Add(new SlotDomain(name, BuildPoints(name, slots, literals))); } - facts.Literals.TryGetValue(name, out var literals); - domains.Add(new SlotDomain(name, BuildPoints(name, slots, literals))); + return domains; } - return domains; - } - - /// Counts the points the product holds, and stops counting above a ceiling. - /// The slot domains. - /// The product, capped so it cannot overflow. - public static long CountPoints(IReadOnlyList domains) - { - ArgumentNullException.ThrowIfNull(domains); - - var total = 1L; - foreach (var count in domains.Select(domain => domain.Points.Count)) + /// Counts the points the product holds, and stops counting above a ceiling. + /// The slot domains. + /// The product, capped so it cannot overflow. + public static long CountPoints(IReadOnlyList domains) { - if (count == 0) - { - return 0; - } + ArgumentNullException.ThrowIfNull(domains); - total *= count; - if (total > MaximumPoints) + long total = 1L; + foreach (int count in domains.Select(domain => domain.Points.Count)) { - return long.MaxValue; - } - } - - return total; - } + if (count == 0) + { + return 0; + } - /// Walks the whole product, one state at a time. - /// The slot domains. - /// Every point of the product. - public static IEnumerable> Enumerate(IReadOnlyList domains) - { - ArgumentNullException.ThrowIfNull(domains); + total *= count; + if (total > MaximumPoints) + { + return long.MaxValue; + } + } - return EnumerateCore(domains); - } + return total; + } - /// Walks every point of the product. The caller checks the arguments. - private static IEnumerable> EnumerateCore(IReadOnlyList domains) - { - if (domains.Count == 0) + /// Walks the whole product, one state at a time. + /// The slot domains. + /// Every point of the product. + public static IEnumerable> Enumerate(IReadOnlyList domains) { - yield return new Dictionary(StringComparer.Ordinal); - yield break; + ArgumentNullException.ThrowIfNull(domains); + + return EnumerateCore(domains); } - var cursor = new int[domains.Count]; - while (true) + /// Walks every point of the product. The caller checks the arguments. + private static IEnumerable> EnumerateCore(IReadOnlyList domains) { - yield return Materialise(domains, cursor); + if (domains.Count == 0) + { + yield return new Dictionary(StringComparer.Ordinal); + yield break; + } - var index = domains.Count - 1; - while (index >= 0) + int[] cursor = new int[domains.Count]; + while (true) { - cursor[index]++; - if (cursor[index] < domains[index].Points.Count) + yield return Materialise(domains, cursor); + + int index = domains.Count - 1; + while (index >= 0) { - break; + cursor[index]++; + if (cursor[index] < domains[index].Points.Count) + { + break; + } + + cursor[index] = 0; + index--; } - cursor[index] = 0; - index--; - } - - if (index < 0) - { - yield break; + if (index < 0) + { + yield break; + } } } - } - /// Takes a fixed number of points at random out of a product that is too large to walk. - /// The slot domains. - /// How many points to take. - /// The sampled points. The seed is fixed, so a build repeats. - public static IEnumerable> Sample(IReadOnlyList domains, int count) - { - ArgumentNullException.ThrowIfNull(domains); + /// Takes a fixed number of points at random out of a product that is too large to walk. + /// The slot domains. + /// How many points to take. + /// The sampled points. The seed is fixed, so a build repeats. + public static IEnumerable> Sample(IReadOnlyList domains, int count) + { + ArgumentNullException.ThrowIfNull(domains); - return SampleCore(domains, count); - } + return SampleCore(domains, count); + } - /// Samples the product with the fixed seed. The caller checks the arguments. - [System.Diagnostics.CodeAnalysis.SuppressMessage( - "Security", - "S2245", - Justification = "Fixed-seed sampling of validation points. Repeatability is required; not a security use.")] - private static IEnumerable> SampleCore(IReadOnlyList domains, int count) - { - // The seed is fixed so that a failing build fails the same way twice. - var random = new Random(SampleSeed); + /// Samples the product with the fixed seed. The caller checks the arguments. + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Security", + "S2245", + Justification = "Fixed-seed sampling of validation points. Repeatability is required; not a security use.")] + private static IEnumerable> SampleCore(IReadOnlyList domains, int count) + { + // The seed is fixed so that a failing build fails the same way twice. + Random random = new(SampleSeed); - var cursor = new int[domains.Count]; + int[] cursor = new int[domains.Count]; - for (var taken = 0; taken < count; taken++) - { - for (var index = 0; index < domains.Count; index++) + for (int taken = 0; taken < count; taken++) { - cursor[index] = random.Next(domains[index].Points.Count); - } + for (int index = 0; index < domains.Count; index++) + { + cursor[index] = random.Next(domains[index].Points.Count); + } - yield return Materialise(domains, cursor); + yield return Materialise(domains, cursor); + } } - } - /// Writes one point as the JSON object a message prints. - /// The point. - /// The JSON text, with the slot names in order. - public static string Describe(IReadOnlyDictionary state) - { - ArgumentNullException.ThrowIfNull(state); - - var holder = new JsonObject(); - foreach (var entry in state) + /// Writes one point as the JSON object a message prints. + /// The point. + /// The JSON text, with the slot names in order. + public static string Describe(IReadOnlyDictionary state) { - var value = entry.Value; - if (value is JsonValue text - && value.GetValueKind() == JsonValueKind.String - && string.Equals(text.GetValue(), OtherString, StringComparison.Ordinal)) - { - holder[entry.Key] = ""; - continue; - } + ArgumentNullException.ThrowIfNull(state); - holder[entry.Key] = value?.DeepClone(); - } + JsonObject holder = []; + foreach (KeyValuePair entry in state) + { + JsonNode? value = entry.Value; + if (value is JsonValue text + && value.GetValueKind() == JsonValueKind.String + && string.Equals(text.GetValue(), OtherString, StringComparison.Ordinal)) + { + holder[entry.Key] = ""; + continue; + } - return holder.ToJsonString(); - } + holder[entry.Key] = value?.DeepClone(); + } - private static Dictionary Materialise(IReadOnlyList domains, int[] cursor) - { - var state = new Dictionary(domains.Count, StringComparer.Ordinal); - for (var index = 0; index < domains.Count; index++) - { - state[domains[index].Name] = domains[index].Points[cursor[index]]; + return holder.ToJsonString(); } - return state; - } - - private static IReadOnlyList BuildPoints( - string name, - IReadOnlyDictionary slots, - List? literals) - { - if (!slots.TryGetValue(name, out var slot)) + private static Dictionary Materialise(IReadOnlyList domains, int[] cursor) { - var reserved = ReservedStateSlots.Contains(name) ? ReservedSlot(name) : null; - if (reserved is null) + Dictionary state = new(domains.Count, StringComparer.Ordinal); + for (int index = 0; index < domains.Count; index++) { - // Check 4 already reports an undeclared slot. One point keeps the product finite. - return [null]; + state[domains[index].Name] = domains[index].Points[cursor[index]]; } - slot = reserved; + return state; } - if (slot.EnumValues is { Count: > 0 } members) + private static IReadOnlyList BuildPoints( + string name, + IReadOnlyDictionary slots, + List? literals) { - List points = [.. members.Select(static member => (JsonNode?)member.DeepClone())]; + if (!slots.TryGetValue(name, out StateSlotConfiguration? slot)) + { + StateSlotConfiguration? reserved = ReservedStateSlots.Contains(name) ? ReservedSlot(name) : null; + if (reserved is null) + { + // Check 4 already reports an undeclared slot. One point keeps the product finite. + return [null]; + } + + slot = reserved; + } - // A slot with no default reads as null until a writer fills it, and that is a state the - // guards run in. Without this point check 5 analyses a domain the conversation never starts in. - if (slot.Default is null) + if (slot.EnumValues is { Count: > 0 } members) { - points.Add(null); + List points = [.. members.Select(static member => (JsonNode?)member.DeepClone())]; + + // A slot with no default reads as null until a writer fills it, and that is a state the + // guards run in. Without this point check 5 analyses a domain the conversation never starts in. + if (slot.Default is null) + { + points.Add(null); + } + + return points; } - return points; + return slot.Type switch + { + StateSlotType.Boolean => [JsonValue.Create(false), JsonValue.Create(true)], + StateSlotType.Integer or StateSlotType.Number => NumericPoints(slot, literals), + StateSlotType.String => StringPoints(slot, literals), + _ => throw new ArgumentOutOfRangeException(nameof(slots), slot.Type, "The slot type vocabulary is closed, and this value is not in it."), + }; } - return slot.Type switch + private static StateSlotConfiguration ReservedSlot(string name) { - StateSlotType.Boolean => [JsonValue.Create(false), JsonValue.Create(true)], - StateSlotType.Integer or StateSlotType.Number => NumericPoints(slot, literals), - _ => StringPoints(slot, literals), - }; - } + return name switch + { + ReservedStateSlots.TurnIndex => new StateSlotConfiguration + { + Type = StateSlotType.Integer, + Writer = StateWriter.Const, + Default = JsonValue.Create(0), + }, + ReservedStateSlots.ConversationDurationSeconds => new StateSlotConfiguration + { + Type = StateSlotType.Number, + Writer = StateWriter.Const, + Default = JsonValue.Create(0), + }, + _ => new StateSlotConfiguration + { + Type = StateSlotType.String, + Writer = StateWriter.Const, + Default = null, + }, + }; + } - private static StateSlotConfiguration ReservedSlot(string name) - => name switch + private static IReadOnlyList NumericPoints(StateSlotConfiguration slot, List? literals) { - ReservedStateSlots.TurnIndex => new StateSlotConfiguration - { - Type = StateSlotType.Integer, - Writer = StateWriter.Const, - Default = JsonValue.Create(0), - }, - ReservedStateSlots.ConversationDurationSeconds => new StateSlotConfiguration + SortedSet thresholds = []; + foreach (JsonNode literal in literals ?? []) { - Type = StateSlotType.Number, - Writer = StateWriter.Const, - Default = JsonValue.Create(0), - }, - _ => new StateSlotConfiguration + if (literal is JsonValue value && value.GetValueKind() == JsonValueKind.Number) + { + _ = thresholds.Add(value.GetValue()); + } + } + + if (thresholds.Count == 0) { - Type = StateSlotType.String, - Writer = StateWriter.Const, - Default = null, - }, - }; + // No rule mentions a threshold, so the slot cannot split any sibling. One point is enough. + return [slot.Default?.DeepClone() ?? JsonValue.Create(0)]; + } - private static IReadOnlyList NumericPoints(StateSlotConfiguration slot, List? literals) - { - var thresholds = new SortedSet(); - foreach (var literal in literals ?? []) - { - if (literal is JsonValue value && value.GetValueKind() == JsonValueKind.Number) + SortedSet points = []; + foreach (decimal threshold in thresholds) { - thresholds.Add(value.GetValue()); + _ = points.Add(threshold - 1); + _ = points.Add(threshold); + _ = points.Add(threshold + 1); } - } - if (thresholds.Count == 0) - { - // No rule mentions a threshold, so the slot cannot split any sibling. One point is enough. - return [slot.Default?.DeepClone() ?? JsonValue.Create(0)]; + return [.. points.Select(static point => (JsonNode?)JsonValue.Create(point))]; } - var points = new SortedSet(); - foreach (var threshold in thresholds) + private static List StringPoints(StateSlotConfiguration slot, List? literals) { - points.Add(threshold - 1); - points.Add(threshold); - points.Add(threshold + 1); - } - - return [.. points.Select(static point => (JsonNode?)JsonValue.Create(point))]; - } - - private static List StringPoints(StateSlotConfiguration slot, List? literals) - { - var members = new List(); - var seen = new HashSet(StringComparer.Ordinal); + List members = []; + HashSet seen = new(StringComparer.Ordinal); - foreach (var literal in literals ?? []) - { - if (literal is JsonValue value && value.GetValueKind() == JsonValueKind.String) + foreach (JsonNode literal in literals ?? []) { - var text = value.GetValue(); - if (seen.Add(text)) + if (literal is JsonValue value && value.GetValueKind() == JsonValueKind.String) { - members.Add(text); + string text = value.GetValue(); + if (seen.Add(text)) + { + members.Add(text); + } } } - } - if (members.Count == 0) - { - // Section 8.5: a string that no rule compares is not enumerated. - return [slot.Default?.DeepClone()]; - } + if (members.Count == 0) + { + // Section 8.5: a string that no rule compares is not enumerated. + return [slot.Default?.DeepClone()]; + } - var points = new List(members.Count + 1); - foreach (var member in members) - { - points.Add(JsonValue.Create(member)); - } + List points = new(members.Count + 1); + foreach (string member in members) + { + points.Add(JsonValue.Create(member)); + } - points.Add(JsonValue.Create(OtherString)); - return points; + points.Add(JsonValue.Create(OtherString)); + return points; + } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ValidationErrors.cs b/src/AgentCore.Application/Configuration/Validation/ValidationErrors.cs index ae75e94a..58b265cb 100644 --- a/src/AgentCore.Application/Configuration/Validation/ValidationErrors.cs +++ b/src/AgentCore.Application/Configuration/Validation/ValidationErrors.cs @@ -1,70 +1,83 @@ using System.Globalization; using AgentCore.Application.Configuration.Parsing; -namespace AgentCore.Application.Configuration.Validation; - -/// Builds a tagged with the check that found it. -internal static class ValidationErrors +namespace AgentCore.Application.Configuration.Validation { - /// - /// The longest interval, in seconds, that every timer these values reach will accept. - /// CancellationTokenSource.CancelAfter, Task.WaitAsync and PeriodicTimer each - /// throw above milliseconds, from a conversation site that carries no pointer - /// into the document. - /// - public const int MaxIntervalSeconds = int.MaxValue / 1000; - - public static ConfigurationError Reference(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ReferenceResolution }; + /// Builds a tagged with the check that found it. + internal static class ValidationErrors + { + /// + /// The longest interval, in seconds, that every timer these values reach will accept. + /// CancellationTokenSource.CancelAfter, Task.WaitAsync and PeriodicTimer each + /// throw above milliseconds, from a conversation site that carries no pointer + /// into the document. + /// + public const int MaxIntervalSeconds = int.MaxValue / 1000; - public static ConfigurationError Range(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ValueRange }; + public static ConfigurationError Reference(string pointer, string message) + { + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ReferenceResolution }; + } - public static ConfigurationError Writers(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.SlotWriters }; + public static ConfigurationError Range(string pointer, string message) + { + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ValueRange }; + } - public static ConfigurationError Operators(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.GuardOperators }; + public static ConfigurationError Writers(string pointer, string message) + { + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.SlotWriters }; + } - public static ConfigurationError Reachability(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.Reachability }; + public static ConfigurationError Operators(string pointer, string message) + { + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.GuardOperators }; + } - public static ConfigurationError WellFormedness(string pointer, string message) - => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.GraphWellFormedness }; + public static ConfigurationError Reachability(string pointer, string message) + { + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.Reachability }; + } - /// Refuses a count or an interval that falls outside the range the runtime accepts. - /// The configured value. - /// The lowest accepted value, inclusive. - /// The highest accepted value, inclusive. means no ceiling. - /// The pointer at the field itself. - /// How the message names the field, as a noun phrase. - /// One or more sentences saying what the range protects. - /// Collects the refusal. - /// - /// Both bounds go through one conversation so a field cannot be given a floor and left without a ceiling: - /// every ceiling here stands between a document and a raw throw out of a timer at boot or mid-turn. - /// - public static void CheckRange( - int value, - int min, - int max, - string pointer, - string subject, - string why, - List errors) - { - if (value >= min && value <= max) + public static ConfigurationError WellFormedness(string pointer, string message) { - return; + return new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.GraphWellFormedness }; } - var accepted = max == int.MaxValue - ? $"the lowest accepted value is {min.ToString(CultureInfo.InvariantCulture)}" - : $"the accepted range is {min.ToString(CultureInfo.InvariantCulture)} to " - + max.ToString(CultureInfo.InvariantCulture); + /// Refuses a count or an interval that falls outside the range the runtime accepts. + /// The configured value. + /// The lowest accepted value, inclusive. + /// The highest accepted value, inclusive. means no ceiling. + /// The pointer at the field itself. + /// How the message names the field, as a noun phrase. + /// One or more sentences saying what the range protects. + /// Collects the refusal. + /// + /// Both bounds go through one conversation so a field cannot be given a floor and left without a ceiling: + /// every ceiling here stands between a document and a raw throw out of a timer at boot or mid-turn. + /// + public static void CheckRange( + int value, + int min, + int max, + string pointer, + string subject, + string why, + List errors) + { + if (value >= min && value <= max) + { + return; + } + + string accepted = max == int.MaxValue + ? $"the lowest accepted value is {min.ToString(CultureInfo.InvariantCulture)}" + : $"the accepted range is {min.ToString(CultureInfo.InvariantCulture)} to " + + max.ToString(CultureInfo.InvariantCulture); - errors.Add(Range( - pointer, - $"{subject} is {value.ToString(CultureInfo.InvariantCulture)}, and {accepted}. {why}")); + errors.Add(Range( + pointer, + $"{subject} is {value.ToString(CultureInfo.InvariantCulture)}, and {accepted}. {why}")); + } } } diff --git a/src/AgentCore.Application/Configuration/Validation/ValidationPointer.cs b/src/AgentCore.Application/Configuration/Validation/ValidationPointer.cs index a1601c17..70d0ff8e 100644 --- a/src/AgentCore.Application/Configuration/Validation/ValidationPointer.cs +++ b/src/AgentCore.Application/Configuration/Validation/ValidationPointer.cs @@ -1,56 +1,102 @@ using AgentCore.Application.Configuration.Parsing; -namespace AgentCore.Application.Configuration.Validation; - -/// JSON pointers into the bound document, shared by every check of section 8.5. -internal static class ValidationPointer +namespace AgentCore.Application.Configuration.Validation { - public const string Wildcard = "/providers/knowledge/scope/wildcard"; - - public const string WildcardValue = Wildcard + "/value"; - - public const string WildcardFacets = Wildcard + "/facets"; - - public const string FromState = "/providers/knowledge/scope/fromState"; - - public const string Ambiguity = "/providers/knowledge/ambiguity"; - - public const string Mapper = "/providers/knowledge/mapper"; - - /// The agent: field an entry, tool, stage, or node points at. - public const string AgentField = "agent"; - - public static string State(string slot) => ConfigurationError.AppendPointer("/state", slot); - - public static string Guard(string name) => ConfigurationError.AppendPointer("/guards", name); - - public static string Agent(int index) => ConfigurationError.AppendPointer("/agents/items", index); - - public static string AgentTool(int agent, int slot) - => ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Agent(agent), "tools"), slot); - - public static string Tool(int index) => ConfigurationError.AppendPointer("/tools", index); - - public static string Mcp(int index) => ConfigurationError.AppendPointer("/mcp", index); - - public static string Entry(string name) => ConfigurationError.AppendPointer("/entries", name); - - public static string Policy(string name) => ConfigurationError.AppendPointer(Entry(name), "policy"); - - public static string Graph(string name) => ConfigurationError.AppendPointer(Entry(name), "graph"); - - public static string GraphAgents(string name) => ConfigurationError.AppendPointer(Graph(name), "agents"); - - public static string GraphNodes(string name) => ConfigurationError.AppendPointer(Graph(name), "nodes"); - - public static string GraphEdges(string name) => ConfigurationError.AppendPointer(Graph(name), "edges"); - - public static string Stage(string name, int index) - => ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Policy(name), "stages"), index); - - public static string Transition(string name, int stage, int exit) - => ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Stage(name, stage), "to"), exit); - - public static string Node(string name, int index) => ConfigurationError.AppendPointer(GraphNodes(name), index); - - public static string Edge(string name, int index) => ConfigurationError.AppendPointer(GraphEdges(name), index); + /// JSON pointers into the bound document, shared by every check of section 8.5. + internal static class ValidationPointer + { + public const string Wildcard = "/providers/knowledge/scope/wildcard"; + + public const string WildcardValue = Wildcard + "/value"; + + public const string WildcardFacets = Wildcard + "/facets"; + + public const string FromState = "/providers/knowledge/scope/fromState"; + + public const string Ambiguity = "/providers/knowledge/ambiguity"; + + public const string Mapper = "/providers/knowledge/mapper"; + + /// The agent: field an entry, tool, stage, or node points at. + public const string AgentField = "agent"; + + public static string State(string slot) + { + return ConfigurationError.AppendPointer("/state", slot); + } + + public static string Guard(string name) + { + return ConfigurationError.AppendPointer("/guards", name); + } + + public static string Agent(int index) + { + return ConfigurationError.AppendPointer("/agents/items", index); + } + + public static string AgentTool(int agent, int slot) + { + return ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Agent(agent), "tools"), slot); + } + + public static string Tool(int index) + { + return ConfigurationError.AppendPointer("/tools", index); + } + + public static string Mcp(int index) + { + return ConfigurationError.AppendPointer("/mcp", index); + } + + public static string Entry(string name) + { + return ConfigurationError.AppendPointer("/entries", name); + } + + public static string Policy(string name) + { + return ConfigurationError.AppendPointer(Entry(name), "policy"); + } + + public static string Graph(string name) + { + return ConfigurationError.AppendPointer(Entry(name), "graph"); + } + + public static string GraphAgents(string name) + { + return ConfigurationError.AppendPointer(Graph(name), "agents"); + } + + public static string GraphNodes(string name) + { + return ConfigurationError.AppendPointer(Graph(name), "nodes"); + } + + public static string GraphEdges(string name) + { + return ConfigurationError.AppendPointer(Graph(name), "edges"); + } + + public static string Stage(string name, int index) + { + return ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Policy(name), "stages"), index); + } + + public static string Transition(string name, int stage, int exit) + { + return ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Stage(name, stage), "to"), exit); + } + + public static string Node(string name, int index) + { + return ConfigurationError.AppendPointer(GraphNodes(name), index); + } + + public static string Edge(string name, int index) + { + return ConfigurationError.AppendPointer(GraphEdges(name), index); + } + } } diff --git a/src/AgentCore.Application/Conversation/ChatConversationTitler.cs b/src/AgentCore.Application/Conversation/ChatConversationTitler.cs index c3e4b3fd..bcea874d 100644 --- a/src/AgentCore.Application/Conversation/ChatConversationTitler.cs +++ b/src/AgentCore.Application/Conversation/ChatConversationTitler.cs @@ -4,136 +4,137 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Conversation; - -/// The titler that asks the configured chat client. -/// The store, where the words are read and the finished title goes. -/// The model that writes it. -public sealed class ChatConversationTitler(IConversationStore conversations, IChatClient client) : IConversationTitler +namespace AgentCore.Application.Conversation { - private const int MaxMessages = 6; - - // A system message - private const string Instruction = - "You name conversations. The user message holds a transcript, one line per turn. " - + "Write a title for it: the topic the person raised, six words at most, " - + "no quotation marks, no final stop. When the transcript raises no topic yet, " - + "use the person's own first words as the title. Reply with the title alone."; - - /// - public IAsyncEnumerable GenerateAsync( - string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - - return GenerateCoreAsync(conversationId, cancellationToken); - } - - /// Reads the conversation's newest messages and streams the title writes. - private async IAsyncEnumerable GenerateCoreAsync( - string conversationId, [EnumeratorCancellation] CancellationToken cancellationToken) + /// The titler that asks the configured chat client. + /// The store, where the words are read and the finished title goes. + /// The model that writes it. + public sealed class ChatConversationTitler(IConversationStore conversations, IChatClient client) : IConversationTitler { - var rows = await conversations.ReadWindowAsync(conversationId, new TranscriptWindow(null, MaxMessages), cancellationToken).ConfigureAwait(false); - - if (rows.Count == 0) + private const int MaxMessages = 6; + + // A system message + private const string Instruction = + "You name conversations. The user message holds a transcript, one line per turn. " + + "Write a title for it: the topic the person raised, six words at most, " + + "no quotation marks, no final stop. When the transcript raises no topic yet, " + + "use the person's own first words as the title. Reply with the title alone."; + + /// + public IAsyncEnumerable GenerateAsync( + string conversationId, CancellationToken cancellationToken = default) { - yield break; - } + ArgumentNullException.ThrowIfNull(conversationId); - await foreach (var piece in NameAsync(conversationId, rows.TakeLast(MaxMessages).Select(row => row.Content), cancellationToken) - .ConfigureAwait(false)) - { - yield return piece; + return GenerateCoreAsync(conversationId, cancellationToken); } - } - /// - public IAsyncEnumerable GenerateFromAsync( - string conversationId, - IReadOnlyList messages, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(messages); + /// Reads the conversation's newest messages and streams the title writes. + private async IAsyncEnumerable GenerateCoreAsync( + string conversationId, [EnumeratorCancellation] CancellationToken cancellationToken) + { + IReadOnlyList rows = await conversations.ReadWindowAsync(conversationId, new TranscriptWindow(null, MaxMessages), cancellationToken).ConfigureAwait(false); - return GenerateFromCoreAsync(conversationId, messages, cancellationToken); - } + if (rows.Count == 0) + { + yield break; + } - /// Streams the title of caller-supplied messages once the conversation proves to exist. - private async IAsyncEnumerable GenerateFromCoreAsync( - string conversationId, - IReadOnlyList messages, - [EnumeratorCancellation] CancellationToken cancellationToken) - { - if (messages.Count == 0) - { - yield break; + await foreach (string? piece in NameAsync(conversationId, rows.TakeLast(MaxMessages).Select(row => row.Content), cancellationToken) + .ConfigureAwait(false)) + { + yield return piece; + } } - // Nothing else on this path touches the conversation, and RenameAsync on a missing one is a silent - // no-op in both stores. Without this the model runs and its answer is dropped. - if (await conversations.GetAsync(conversationId, cancellationToken).ConfigureAwait(false) is null) + /// + public IAsyncEnumerable GenerateFromAsync( + string conversationId, + IReadOnlyList messages, + CancellationToken cancellationToken = default) { - yield break; + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(messages); + + return GenerateFromCoreAsync(conversationId, messages, cancellationToken); } - await foreach (var piece in NameAsync(conversationId, messages, cancellationToken).ConfigureAwait(false)) + /// Streams the title of caller-supplied messages once the conversation proves to exist. + private async IAsyncEnumerable GenerateFromCoreAsync( + string conversationId, + IReadOnlyList messages, + [EnumeratorCancellation] CancellationToken cancellationToken) { - yield return piece; - } - } + if (messages.Count == 0) + { + yield break; + } - /// Asks the model for a name, streams it, and writes the finished one to the conversation. - /// The conversation the finished title belongs to. - /// The messages to name. The instruction is added here, not by the caller. - /// Stops the generation, leaving the title as it was. - /// The title in pieces, in order. - private async IAsyncEnumerable NameAsync( - string conversationId, - IEnumerable messages, - [EnumeratorCancellation] CancellationToken cancellationToken) - { - List prompt = - [ - new ChatMessage(ChatRole.System, Instruction), - new ChatMessage(ChatRole.User, Transcript(messages.Take(MaxMessages))), - ]; + // Nothing else on this path touches the conversation, and RenameAsync on a missing one is a silent + // no-op in both stores. Without this the model runs and its answer is dropped. + if (await conversations.GetAsync(conversationId, cancellationToken).ConfigureAwait(false) is null) + { + yield break; + } - StringBuilder title = new(); + await foreach (string? piece in NameAsync(conversationId, messages, cancellationToken).ConfigureAwait(false)) + { + yield return piece; + } + } - await foreach (var update in client - .GetStreamingResponseAsync(prompt, options: null, cancellationToken) - .ConfigureAwait(false)) + /// Asks the model for a name, streams it, and writes the finished one to the conversation. + /// The conversation the finished title belongs to. + /// The messages to name. The instruction is added here, not by the caller. + /// Stops the generation, leaving the title as it was. + /// The title in pieces, in order. + private async IAsyncEnumerable NameAsync( + string conversationId, + IEnumerable messages, + [EnumeratorCancellation] CancellationToken cancellationToken) { - var piece = update.Text; + List prompt = + [ + new ChatMessage(ChatRole.System, Instruction), + new ChatMessage(ChatRole.User, Transcript(messages.Take(MaxMessages))), + ]; + + StringBuilder title = new(); - if (string.IsNullOrEmpty(piece)) + await foreach (ChatResponseUpdate? update in client + .GetStreamingResponseAsync(prompt, options: null, cancellationToken) + .ConfigureAwait(false)) { - continue; + string piece = update.Text; + + if (string.IsNullOrEmpty(piece)) + { + continue; + } + + _ = title.Append(piece); + yield return piece; } - title.Append(piece); - yield return piece; - } + string whole = title.ToString().Trim(); - var whole = title.ToString().Trim(); + if (whole.Length > 0) + { + await conversations.RenameAsync(conversationId, whole, cancellationToken).ConfigureAwait(false); + } + } - if (whole.Length > 0) + /// Folds the messages into one text, one role: words line per message. + private static string Transcript(IEnumerable messages) { - await conversations.RenameAsync(conversationId, whole, cancellationToken).ConfigureAwait(false); - } - } + StringBuilder text = new(); - /// Folds the messages into one text, one role: words line per message. - private static string Transcript(IEnumerable messages) - { - StringBuilder text = new(); + foreach (ChatMessage message in messages) + { + _ = text.Append(message.Role.Value).Append(": ").AppendLine(message.Text); + } - foreach (var message in messages) - { - text.Append(message.Role.Value).Append(": ").AppendLine(message.Text); + return text.ToString(); } - - return text.ToString(); } } diff --git a/src/AgentCore.Application/Conversation/ConversationChannel.cs b/src/AgentCore.Application/Conversation/ConversationChannel.cs index 18086196..9eb59ade 100644 --- a/src/AgentCore.Application/Conversation/ConversationChannel.cs +++ b/src/AgentCore.Application/Conversation/ConversationChannel.cs @@ -1,78 +1,79 @@ using AgentCore.Application.Ports; -namespace AgentCore.Application.Conversation; - -/// -/// The two halves of one conversation, opened together and disposed together. -/// -/// -/// -/// A vendor that does both halves itself returns one object in both slots. A pair of separate -/// services returns two. Nothing above this type may ask which it got, and nothing above it can -/// tell: one, two, or two sharing private state all read the same here. -/// -/// -/// The bundled shape is why both ports speak text. Conversation Relay runs the audio on its own side of the -/// wire: transcripts arrive as text, replies leave as text, and the barge-in answer — what the -/// caller heard, and for how long — arrives already measured, in the vendor's own frame. One -/// connection is honestly both halves, so the factory hands the same object to both slots. -/// -/// -/// caller ─audio─▶ [ conversation relay ] ─text─▶ RelayConnection ─▶ agent -/// caller ◀─audio─ [ conversation relay ] ◀─text─ RelayConnection ◀─ agent reply -/// -/// -/// Two objects at the interface does not mean two independent objects underneath. A split adapter -/// measures the played duration on its speaking side and reports it on its listening side, so its -/// two halves share one clock. That sharing belongs to whichever adapter created them, which is -/// why it appears on neither interface. -/// -/// -/// That clock is the layer of indirection a split adapter must add. Separate STT and TTS services -/// merge nothing, so the adapter wraps the two vendor clients — the -/// Microsoft.Extensions.AI pair, ISpeechToTextClient and ITextToSpeechClient, -/// which stay inside the adapter and never enter this assembly, because they sit at the audio -/// boundary and are marked experimental — and computes for itself what the bundled vendor -/// reported for free: bytes written minus the transport's own queue, counted from the first -/// audibly played sound, mapped back to the words the model wrote — measured, never estimated. -/// The settled answer still arrives as a on the input stream, and -/// every settle path after carries a two-second -/// deadline, after which the reply counts as fully heard. Sections 2, 6, and 11 of the design -/// record the argument. -/// -/// -/// caller ─audio─▶ [ STT client ] ─text─▶ split input port ─┐ -/// ├─ ConversationChannel ─▶ agent -/// caller ◀─audio─ [ TTS client ] ◀─text─ split output port ─┘ -/// │ -/// [ playback clock ] -/// -/// -/// What the caller does. -/// What the agent says. -public sealed record ConversationChannel(IConversationInputPort Input, IConversationOutputPort Output) : IAsyncDisposable +namespace AgentCore.Application.Conversation { - private bool _disposed; - - /// Disposes both halves, and each underlying object exactly once. + /// + /// The two halves of one conversation, opened together and disposed together. + /// /// - /// Reference equality is the test, because one object filling both slots is the ordinary case - /// and not the exception. Disposing it twice would let an adapter's own teardown run twice. + /// + /// A vendor that does both halves itself returns one object in both slots. A pair of separate + /// services returns two. Nothing above this type may ask which it got, and nothing above it can + /// tell: one, two, or two sharing private state all read the same here. + /// + /// + /// The bundled shape is why both ports speak text. Conversation Relay runs the audio on its own side of the + /// wire: transcripts arrive as text, replies leave as text, and the barge-in answer — what the + /// caller heard, and for how long — arrives already measured, in the vendor's own frame. One + /// connection is honestly both halves, so the factory hands the same object to both slots. + /// + /// + /// caller ─audio─▶ [ conversation relay ] ─text─▶ RelayConnection ─▶ agent + /// caller ◀─audio─ [ conversation relay ] ◀─text─ RelayConnection ◀─ agent reply + /// + /// + /// Two objects at the interface does not mean two independent objects underneath. A split adapter + /// measures the played duration on its speaking side and reports it on its listening side, so its + /// two halves share one clock. That sharing belongs to whichever adapter created them, which is + /// why it appears on neither interface. + /// + /// + /// That clock is the layer of indirection a split adapter must add. Separate STT and TTS services + /// merge nothing, so the adapter wraps the two vendor clients — the + /// Microsoft.Extensions.AI pair, ISpeechToTextClient and ITextToSpeechClient, + /// which stay inside the adapter and never enter this assembly, because they sit at the audio + /// boundary and are marked experimental — and computes for itself what the bundled vendor + /// reported for free: bytes written minus the transport's own queue, counted from the first + /// audibly played sound, mapped back to the words the model wrote — measured, never estimated. + /// The settled answer still arrives as a on the input stream, and + /// every settle path after carries a two-second + /// deadline, after which the reply counts as fully heard. Sections 2, 6, and 11 of the design + /// record the argument. + /// + /// + /// caller ─audio─▶ [ STT client ] ─text─▶ split input port ─┐ + /// ├─ ConversationChannel ─▶ agent + /// caller ◀─audio─ [ TTS client ] ◀─text─ split output port ─┘ + /// │ + /// [ playback clock ] + /// /// - public async ValueTask DisposeAsync() + /// What the caller does. + /// What the agent says. + public sealed record ConversationChannel(IConversationInputPort Input, IConversationOutputPort Output) : IAsyncDisposable { - if (_disposed) + private bool _disposed; + + /// Disposes both halves, and each underlying object exactly once. + /// + /// Reference equality is the test, because one object filling both slots is the ordinary case + /// and not the exception. Disposing it twice would let an adapter's own teardown run twice. + /// + public async ValueTask DisposeAsync() { - return; - } + if (_disposed) + { + return; + } - _disposed = true; + _disposed = true; - await Input.DisposeAsync().ConfigureAwait(false); + await Input.DisposeAsync().ConfigureAwait(false); - if (!ReferenceEquals(Input, Output)) - { - await Output.DisposeAsync().ConfigureAwait(false); + if (!ReferenceEquals(Input, Output)) + { + await Output.DisposeAsync().ConfigureAwait(false); + } } } } diff --git a/src/AgentCore.Application/Conversation/ConversationChannelContext.cs b/src/AgentCore.Application/Conversation/ConversationChannelContext.cs index 8435ecaa..0b109aae 100644 --- a/src/AgentCore.Application/Conversation/ConversationChannelContext.cs +++ b/src/AgentCore.Application/Conversation/ConversationChannelContext.cs @@ -1,10 +1,11 @@ -namespace AgentCore.Application.Conversation; - -/// What one conversation needs to open its channel. -/// The AgentCore conversation id, which the channel must not invent for itself. -/// Per-conversation values the host attached, or . -/// -/// This carries no vendor field and no wire frame, so D8 holds: a factory learns what the conversation is -/// without the core learning what the vendor is. -/// -public sealed record ConversationChannelContext(string ConversationId, IReadOnlyDictionary? CustomParameters); +namespace AgentCore.Application.Conversation +{ + /// What one conversation needs to open its channel. + /// The AgentCore conversation id, which the channel must not invent for itself. + /// Per-conversation values the host attached, or . + /// + /// This carries no vendor field and no wire frame, so D8 holds: a factory learns what the conversation is + /// without the core learning what the vendor is. + /// + public sealed record ConversationChannelContext(string ConversationId, IReadOnlyDictionary? CustomParameters); +} diff --git a/src/AgentCore.Application/Conversation/ConversationClarificationState.cs b/src/AgentCore.Application/Conversation/ConversationClarificationState.cs index 6e394a96..a52c78b0 100644 --- a/src/AgentCore.Application/Conversation/ConversationClarificationState.cs +++ b/src/AgentCore.Application/Conversation/ConversationClarificationState.cs @@ -1,13 +1,14 @@ -namespace AgentCore.Application.Conversation; - -/// What one slot's knowledge probe has already spent of its ask budget (§8). -/// -/// Carried on so a caller who drops and reconnects mid-conversation is not -/// asked the same clarification a second maxAsks times. What was last named to the caller is -/// deliberately absent: it belongs to a turn the reconnected caller is no longer in. -/// -public sealed record ConversationClarificationState +namespace AgentCore.Application.Conversation { - /// Gets how many times the knowledge probe has offered this slot (§8, K22). - public int ProbeAsks { get; init; } + /// What one slot's knowledge probe has already spent of its ask budget (§8). + /// + /// Carried on so a caller who drops and reconnects mid-conversation is not + /// asked the same clarification a second maxAsks times. What was last named to the caller is + /// deliberately absent: it belongs to a turn the reconnected caller is no longer in. + /// + public sealed record ConversationClarificationState + { + /// Gets how many times the knowledge probe has offered this slot (§8, K22). + public int ProbeAsks { get; init; } + } } diff --git a/src/AgentCore.Application/Conversation/ConversationCursor.cs b/src/AgentCore.Application/Conversation/ConversationCursor.cs index 5359f48a..e5959212 100644 --- a/src/AgentCore.Application/Conversation/ConversationCursor.cs +++ b/src/AgentCore.Application/Conversation/ConversationCursor.cs @@ -2,72 +2,73 @@ using System.Globalization; using System.Text; -namespace AgentCore.Application.Conversation; - -/// -/// The place in a listing that a page ended, as one opaque string. -/// -public static class ConversationCursor +namespace AgentCore.Application.Conversation { - private const char Separator = '|'; - - /// Encodes where a page ended. - /// The last row's sort time. - /// The last row's conversation id. - /// A string the caller hands back unread. - /// The conversation id is . - public static string Encode(DateTimeOffset sortAt, string conversationId) + /// + /// The place in a listing that a page ended, as one opaque string. + /// + public static class ConversationCursor { - ArgumentNullException.ThrowIfNull(conversationId); + private const char Separator = '|'; - var plain = string.Create( - CultureInfo.InvariantCulture, - $"{sortAt.UtcTicks}{Separator}{conversationId}"); + /// Encodes where a page ended. + /// The last row's sort time. + /// The last row's conversation id. + /// A string the caller hands back unread. + /// The conversation id is . + public static string Encode(DateTimeOffset sortAt, string conversationId) + { + ArgumentNullException.ThrowIfNull(conversationId); - return Convert.ToBase64String(Encoding.UTF8.GetBytes(plain)); - } + string plain = string.Create( + CultureInfo.InvariantCulture, + $"{sortAt.UtcTicks}{Separator}{conversationId}"); - /// Reads a cursor this class wrote. - /// The value a caller handed back, which may be anything at all. - /// The sort time it held, or . - /// The conversation id it held, or an empty string. - /// when the value was a cursor. - public static bool TryDecode(string? cursor, out DateTimeOffset sortAt, out string conversationId) - { - sortAt = default; - - conversationId = string.Empty; + return Convert.ToBase64String(Encoding.UTF8.GetBytes(plain)); + } - if (string.IsNullOrEmpty(cursor)) + /// Reads a cursor this class wrote. + /// The value a caller handed back, which may be anything at all. + /// The sort time it held, or . + /// The conversation id it held, or an empty string. + /// when the value was a cursor. + public static bool TryDecode(string? cursor, out DateTimeOffset sortAt, out string conversationId) { - return false; - } + sortAt = default; - Span bytes = new byte[Base64.GetMaxDecodedFromUtf8Length(cursor.Length)]; + conversationId = string.Empty; - if (!Convert.TryFromBase64String(cursor, bytes, out var written)) - { - return false; - } + if (string.IsNullOrEmpty(cursor)) + { + return false; + } - var plain = Encoding.UTF8.GetString(bytes[..written]); - var split = plain.IndexOf(Separator, StringComparison.Ordinal); + Span bytes = new byte[Base64.GetMaxDecodedFromUtf8Length(cursor.Length)]; - if (split <= 0 || split == plain.Length - 1) - { - return false; - } + if (!Convert.TryFromBase64String(cursor, bytes, out int written)) + { + return false; + } - if (!long.TryParse(plain[..split], CultureInfo.InvariantCulture, out var ticks) - || ticks < 0 - || ticks > DateTimeOffset.MaxValue.UtcTicks) - { - return false; - } + string plain = Encoding.UTF8.GetString(bytes[..written]); + int split = plain.IndexOf(Separator, StringComparison.Ordinal); + + if (split <= 0 || split == plain.Length - 1) + { + return false; + } - sortAt = new DateTimeOffset(ticks, TimeSpan.Zero); - conversationId = plain[(split + 1)..]; + if (!long.TryParse(plain[..split], CultureInfo.InvariantCulture, out long ticks) + || ticks < 0 + || ticks > DateTimeOffset.MaxValue.UtcTicks) + { + return false; + } - return true; + sortAt = new DateTimeOffset(ticks, TimeSpan.Zero); + conversationId = plain[(split + 1)..]; + + return true; + } } } diff --git a/src/AgentCore.Application/Conversation/ConversationInput.cs b/src/AgentCore.Application/Conversation/ConversationInput.cs index 0965fa65..11cec98f 100644 --- a/src/AgentCore.Application/Conversation/ConversationInput.cs +++ b/src/AgentCore.Application/Conversation/ConversationInput.cs @@ -1,47 +1,48 @@ -namespace AgentCore.Application.Conversation; - -/// -/// One thing the caller did, in the order it happened. -/// -/// -/// -/// One ordered stream carries every inbound event, and the kind is a case of this hierarchy -/// rather than a separate stream for each. Section 3.2 asks for exactly that shape, and -/// RelayFrame in the Telnyx adapter already reads this way. -/// -/// -/// The constructor is , so the set is closed: nothing outside -/// this assembly can add a case, and a consumer's switch over the three below is exhaustive. -/// -/// -public abstract record ConversationInput +namespace AgentCore.Application.Conversation { - private protected ConversationInput() + /// + /// One thing the caller did, in the order it happened. + /// + /// + /// + /// One ordered stream carries every inbound event, and the kind is a case of this hierarchy + /// rather than a separate stream for each. Section 3.2 asks for exactly that shape, and + /// RelayFrame in the Telnyx adapter already reads this way. + /// + /// + /// The constructor is , so the set is closed: nothing outside + /// this assembly can add a case, and a consumer's switch over the three below is exhaustive. + /// + /// + public abstract record ConversationInput { - } + private protected ConversationInput() + { + } - /// The caller spoke. - /// What the recognizer heard. - /// The language it reported, for example en. - /// - /// marks the end of the turn. is an interim - /// transcript, and a recognizer sends many of those for one sentence. - /// - public sealed record Utterance(string Text, string Language, bool IsFinal) : ConversationInput; + /// The caller spoke. + /// What the recognizer heard. + /// The language it reported, for example en. + /// + /// marks the end of the turn. is an interim + /// transcript, and a recognizer sends many of those for one sentence. + /// + public sealed record Utterance(string Text, string Language, bool IsFinal) : ConversationInput; - /// The caller pressed one key. - /// The key. A keypad carries card numbers and PINs, so no log line may hold it. - public sealed record Keypress(string Key) : ConversationInput; + /// The caller pressed one key. + /// The key. A keypad carries card numbers and PINs, so no log line may hold it. + public sealed record Keypress(string Key) : ConversationInput; - /// The caller cut the reply off. - /// - /// The text the caller actually heard. An empty string means the caller heard nothing at all, - /// which is a measured answer and not a missing one: a barge-in can land before the first word - /// leaves the synthesizer. A consumer must not record an assistant turn for an empty value. - /// - /// - /// How much of the reply played. Measured, never estimated: D28 forbids the estimator that - /// would otherwise stand here, and item 6c of section 11 asks for the same. - /// - public sealed record Barge(string HeardText, TimeSpan PlayedDuration) : ConversationInput; + /// The caller cut the reply off. + /// + /// The text the caller actually heard. An empty string means the caller heard nothing at all, + /// which is a measured answer and not a missing one: a barge-in can land before the first word + /// leaves the synthesizer. A consumer must not record an assistant turn for an empty value. + /// + /// + /// How much of the reply played. Measured, never estimated: D28 forbids the estimator that + /// would otherwise stand here, and item 6c of section 11 asks for the same. + /// + public sealed record Barge(string HeardText, TimeSpan PlayedDuration) : ConversationInput; + } } diff --git a/src/AgentCore.Application/Conversation/ConversationPage.cs b/src/AgentCore.Application/Conversation/ConversationPage.cs index 46fc12c0..35e28dc1 100644 --- a/src/AgentCore.Application/Conversation/ConversationPage.cs +++ b/src/AgentCore.Application/Conversation/ConversationPage.cs @@ -1,9 +1,10 @@ -namespace AgentCore.Application.Conversation; - -/// One page of a listing. -/// The page's rows, most recently active first. -/// -/// What to pass as after for the following page, or when this page was -/// the last. A full page always carries one; a short page never does. -/// -public sealed record ConversationPage(IReadOnlyList Conversations, string? NextCursor); +namespace AgentCore.Application.Conversation +{ + /// One page of a listing. + /// The page's rows, most recently active first. + /// + /// What to pass as after for the following page, or when this page was + /// the last. A full page always carries one; a short page never does. + /// + public sealed record ConversationPage(IReadOnlyList Conversations, string? NextCursor); +} diff --git a/src/AgentCore.Application/Conversation/ConversationRecord.cs b/src/AgentCore.Application/Conversation/ConversationRecord.cs index b00053b6..6893f146 100644 --- a/src/AgentCore.Application/Conversation/ConversationRecord.cs +++ b/src/AgentCore.Application/Conversation/ConversationRecord.cs @@ -1,35 +1,36 @@ using System.Text.Json; -namespace AgentCore.Application.Conversation; - -/// One conversation, apart from its words. It is one row of store 0. -/// The conversation this describes. It is the join to stores 1 and 3. -/// What to show in a list, or until one is made. -/// Whether the conversation is still listed as usual. -/// A consumer's own id for the conversation, or . -/// A consumer's own fields, or . -/// When the conversation row was made. UTC. -/// -/// When store 1 last wrote a word of this conversation, or when it holds none. UTC. -/// Derived at read time; store 0 keeps no such column. -/// -/// -/// What the session of this conversation held, or for a conversation that has run no turn -/// under a build that writes it. Read by GetAsync and CreateAsync only: a listing does -/// not need it and does not pay for it. -/// -/// -/// The ordinal the conversation's next appended row takes. Read by GetAsync and CreateAsync -/// only, on the same terms as : a listing leaves it at its default 0 rather -/// than paying to read it. -/// -public sealed record ConversationRecord( - string ConversationId, - string? Title, - ConversationStatus Status, - string? ExternalId, - JsonElement? Custom, - DateTimeOffset CreatedAt, - DateTimeOffset? LastMessageAt, - ConversationSessionState? State = null, - int NextOrdinal = 0); +namespace AgentCore.Application.Conversation +{ + /// One conversation, apart from its words. It is one row of store 0. + /// The conversation this describes. It is the join to stores 1 and 3. + /// What to show in a list, or until one is made. + /// Whether the conversation is still listed as usual. + /// A consumer's own id for the conversation, or . + /// A consumer's own fields, or . + /// When the conversation row was made. UTC. + /// + /// When store 1 last wrote a word of this conversation, or when it holds none. UTC. + /// Derived at read time; store 0 keeps no such column. + /// + /// + /// What the session of this conversation held, or for a conversation that has run no turn + /// under a build that writes it. Read by GetAsync and CreateAsync only: a listing does + /// not need it and does not pay for it. + /// + /// + /// The ordinal the conversation's next appended row takes. Read by GetAsync and CreateAsync + /// only, on the same terms as : a listing leaves it at its default 0 rather + /// than paying to read it. + /// + public sealed record ConversationRecord( + string ConversationId, + string? Title, + ConversationStatus Status, + string? ExternalId, + JsonElement? Custom, + DateTimeOffset CreatedAt, + DateTimeOffset? LastMessageAt, + ConversationSessionState? State = null, + int NextOrdinal = 0); +} diff --git a/src/AgentCore.Application/Conversation/ConversationSessionState.cs b/src/AgentCore.Application/Conversation/ConversationSessionState.cs index 31e683a9..30d7a1b4 100644 --- a/src/AgentCore.Application/Conversation/ConversationSessionState.cs +++ b/src/AgentCore.Application/Conversation/ConversationSessionState.cs @@ -2,59 +2,60 @@ using System.Text.Json; using System.Text.Json.Nodes; -namespace AgentCore.Application.Conversation; - -/// Everything one conversation's session holds that has no other durable home. -public sealed record ConversationSessionState +namespace AgentCore.Application.Conversation { - /// The slots of a state whose writers filled none. - private static readonly IReadOnlyDictionary NoSlots = - ReadOnlyDictionary.Empty; - - /// The slots of a conversation whose knowledge probe asked about none. - private static readonly IReadOnlyDictionary NoClarifications = - ReadOnlyDictionary.Empty; - - /// The providers of a conversation whose document declares no harness switch. - private static readonly IReadOnlyDictionary NoProviders = - ReadOnlyDictionary.Empty; - - /// The shape this version of the library writes. - public const int CurrentVersion = 1; - - /// Gets the shape this blob was written in. - public int Version { get; init; } = CurrentVersion; - - /// Gets the index the conversation's next turn takes. - public int NextTurnIndex { get; init; } - - /// Gets the stage the machine held. It is empty when the document declares no policy. - public string Stage { get; init; } = string.Empty; - - /// Gets whether the machine had already reached a terminal stage. - public bool IsComplete { get; init; } - - /// Gets the declared slots a writer had filled, by name. An unfilled slot is absent. - public IReadOnlyDictionary Slots { get; init; } = NoSlots; - - /// - /// Gets what each slot's knowledge probe has spent of its ask budget, by slot name. A slot - /// nothing has asked about is absent. - /// - public IReadOnlyDictionary Clarifications { get; init; } = NoClarifications; - - /// - /// Gets the MAF provider state a harness switch (todos:, mode:, memory:, - /// files:, background:) held, keyed by that provider's state key. A document with - /// no harness switch holds none. Absent in an old blob, which restores its stage and slots as before. - /// - public IReadOnlyDictionary Providers { get; init; } = NoProviders; - - /// - /// Gets the opaque workflow session of a graph row's conversation, carrying the harness providers' - /// checkpointed state across turns. Only a graph row whose document declares a harness switch - /// writes one; rows 1 and 2 keep provider state in , and any other conversation - /// keeps neither. Absent in an old blob, which resumes with a fresh session. - /// - public JsonElement? WorkflowState { get; init; } + /// Everything one conversation's session holds that has no other durable home. + public sealed record ConversationSessionState + { + /// The slots of a state whose writers filled none. + private static readonly IReadOnlyDictionary NoSlots = + ReadOnlyDictionary.Empty; + + /// The slots of a conversation whose knowledge probe asked about none. + private static readonly IReadOnlyDictionary NoClarifications = + ReadOnlyDictionary.Empty; + + /// The providers of a conversation whose document declares no harness switch. + private static readonly IReadOnlyDictionary NoProviders = + ReadOnlyDictionary.Empty; + + /// The shape this version of the library writes. + public const int CurrentVersion = 1; + + /// Gets the shape this blob was written in. + public int Version { get; init; } = CurrentVersion; + + /// Gets the index the conversation's next turn takes. + public int NextTurnIndex { get; init; } + + /// Gets the stage the machine held. It is empty when the document declares no policy. + public string Stage { get; init; } = string.Empty; + + /// Gets whether the machine had already reached a terminal stage. + public bool IsComplete { get; init; } + + /// Gets the declared slots a writer had filled, by name. An unfilled slot is absent. + public IReadOnlyDictionary Slots { get; init; } = NoSlots; + + /// + /// Gets what each slot's knowledge probe has spent of its ask budget, by slot name. A slot + /// nothing has asked about is absent. + /// + public IReadOnlyDictionary Clarifications { get; init; } = NoClarifications; + + /// + /// Gets the MAF provider state a harness switch (todos:, mode:, memory:, + /// files:, background:) held, keyed by that provider's state key. A document with + /// no harness switch holds none. Absent in an old blob, which restores its stage and slots as before. + /// + public IReadOnlyDictionary Providers { get; init; } = NoProviders; + + /// + /// Gets the opaque workflow session of a graph row's conversation, carrying the harness providers' + /// checkpointed state across turns. Only a graph row whose document declares a harness switch + /// writes one; rows 1 and 2 keep provider state in , and any other conversation + /// keeps neither. Absent in an old blob, which resumes with a fresh session. + /// + public JsonElement? WorkflowState { get; init; } + } } diff --git a/src/AgentCore.Application/Conversation/ConversationSpeechPairing.cs b/src/AgentCore.Application/Conversation/ConversationSpeechPairing.cs index 2437b9b5..ac62b72c 100644 --- a/src/AgentCore.Application/Conversation/ConversationSpeechPairing.cs +++ b/src/AgentCore.Application/Conversation/ConversationSpeechPairing.cs @@ -2,93 +2,94 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; -namespace AgentCore.Application.Conversation; - -/// -/// Refuses a document whose conversation transport and speech vendors cannot coexist. -/// -/// -/// -/// A transport whose frames already carry text is the recognizer and the synthesizer. A -/// document naming it for the pipe and something else for the ears or the mouth describes a -/// deployment that cannot exist, and the failure it would otherwise produce — a conversation that connects -/// and never transcribes — is among the most expensive kinds to diagnose. -/// -/// -/// The two roles are checked one at a time. A document that gets both wrong is wrong twice, and -/// hearing about one of them, fixing it, and starting again to hear about the other is the slow way -/// to learn that. -/// -/// -/// No vendor name appears here. is declared by the -/// adapter, so a second bundled vendor is one new adapter and no edit to this file. A guard that -/// grew an || per vendor is the design this one exists to avoid. -/// -/// -/// It runs from AddAgentCoreAsync rather than from the route extension, so a host that -/// forgets to map a route still learns its document is self-contradictory. -/// -/// -public static class ConversationSpeechPairing +namespace AgentCore.Application.Conversation { - /// Checks that both speech roles are compatible with the selected conversation transport. - /// The providers.conversation block. - /// The providers.speech block, with both of its roles. - /// The adapter providers.conversation.kind selected. - /// Any argument is . - /// - /// The transport carries text and at least one speech role names a different vendor. The - /// exception carries one error per offending role, recognition first. - /// - public static void Validate( - ConversationProviderConfiguration conversation, - SpeechProviderConfiguration speech, - IConversationAdapter selectedConversation) + /// + /// Refuses a document whose conversation transport and speech vendors cannot coexist. + /// + /// + /// + /// A transport whose frames already carry text is the recognizer and the synthesizer. A + /// document naming it for the pipe and something else for the ears or the mouth describes a + /// deployment that cannot exist, and the failure it would otherwise produce — a conversation that connects + /// and never transcribes — is among the most expensive kinds to diagnose. + /// + /// + /// The two roles are checked one at a time. A document that gets both wrong is wrong twice, and + /// hearing about one of them, fixing it, and starting again to hear about the other is the slow way + /// to learn that. + /// + /// + /// No vendor name appears here. is declared by the + /// adapter, so a second bundled vendor is one new adapter and no edit to this file. A guard that + /// grew an || per vendor is the design this one exists to avoid. + /// + /// + /// It runs from AddAgentCoreAsync rather than from the route extension, so a host that + /// forgets to map a route still learns its document is self-contradictory. + /// + /// + public static class ConversationSpeechPairing { - ArgumentNullException.ThrowIfNull(conversation); - ArgumentNullException.ThrowIfNull(speech); - ArgumentNullException.ThrowIfNull(selectedConversation); - - if (!selectedConversation.CarriesText) + /// Checks that both speech roles are compatible with the selected conversation transport. + /// The providers.conversation block. + /// The providers.speech block, with both of its roles. + /// The adapter providers.conversation.kind selected. + /// Any argument is . + /// + /// The transport carries text and at least one speech role names a different vendor. The + /// exception carries one error per offending role, recognition first. + /// + public static void Validate( + ConversationProviderConfiguration conversation, + SpeechProviderConfiguration speech, + IConversationAdapter selectedConversation) { - // The socket carries audio, so a separate speech vendor is exactly what is wanted and - // the kinds are expected to differ from the conversation's. - return; - } + ArgumentNullException.ThrowIfNull(conversation); + ArgumentNullException.ThrowIfNull(speech); + ArgumentNullException.ThrowIfNull(selectedConversation); - List errors = []; + if (!selectedConversation.CarriesText) + { + // The socket carries audio, so a separate speech vendor is exactly what is wanted and + // the kinds are expected to differ from the conversation's. + return; + } - Check(errors, conversation.Kind, speech.Stt.Kind, "stt"); - Check(errors, conversation.Kind, speech.Tts.Kind, "tts"); + List errors = []; - if (errors.Count > 0) - { - throw new ConfigurationLoadException(errors); - } - } + Check(errors, conversation.Kind, speech.Stt.Kind, "stt"); + Check(errors, conversation.Kind, speech.Tts.Kind, "tts"); - /// Adds one error when a role names a vendor the text-carrying transport is not. - /// The errors collected so far. One start reports every offending role. - /// The vendor providers.conversation.kind names. - /// The vendor this role names. - /// The role's own name in the document, stt or tts. - private static void Check(List errors, string conversationKind, string roleKind, string role) - { - if (string.Equals(roleKind, conversationKind, StringComparison.OrdinalIgnoreCase)) - { - return; + if (errors.Count > 0) + { + throw new ConfigurationLoadException(errors); + } } - errors.Add(new ConfigurationError + /// Adds one error when a role names a vendor the text-carrying transport is not. + /// The errors collected so far. One start reports every offending role. + /// The vendor providers.conversation.kind names. + /// The vendor this role names. + /// The role's own name in the document, stt or tts. + private static void Check(List errors, string conversationKind, string roleKind, string role) { - Pointer = $"/providers/speech/{role}/kind", - Message = - $"providers.conversation is kind: {conversationKind}, and that transport carries text, so it " - + $"performs recognition and synthesis itself. providers.speech.{role} is kind: " - + $"{roleKind}, which would never be asked to do anything. Set " - + $"providers.speech.{role} to '{conversationKind}', or choose a conversation transport that " - + $"carries audio.", - Check = ConfigurationCheck.ReferenceResolution, - }); + if (string.Equals(roleKind, conversationKind, StringComparison.OrdinalIgnoreCase)) + { + return; + } + + errors.Add(new ConfigurationError + { + Pointer = $"/providers/speech/{role}/kind", + Message = + $"providers.conversation is kind: {conversationKind}, and that transport carries text, so it " + + $"performs recognition and synthesis itself. providers.speech.{role} is kind: " + + $"{roleKind}, which would never be asked to do anything. Set " + + $"providers.speech.{role} to '{conversationKind}', or choose a conversation transport that " + + $"carries audio.", + Check = ConfigurationCheck.ReferenceResolution, + }); + } } } diff --git a/src/AgentCore.Application/Conversation/ConversationStateJson.cs b/src/AgentCore.Application/Conversation/ConversationStateJson.cs index 32404fd4..75abb5c7 100644 --- a/src/AgentCore.Application/Conversation/ConversationStateJson.cs +++ b/src/AgentCore.Application/Conversation/ConversationStateJson.cs @@ -1,19 +1,20 @@ using System.Text.Json; -namespace AgentCore.Application.Conversation; - -/// How is encoded. Every store agrees on it. -public static class ConversationStateJson +namespace AgentCore.Application.Conversation { - /// The shared options. - public static JsonSerializerOptions Options { get; } = Build(); - - private static JsonSerializerOptions Build() + /// How is encoded. Every store agrees on it. + public static class ConversationStateJson { - JsonSerializerOptions options = new(JsonSerializerDefaults.Web); + /// The shared options. + public static JsonSerializerOptions Options { get; } = Build(); + + private static JsonSerializerOptions Build() + { + JsonSerializerOptions options = new(JsonSerializerDefaults.Web); + + options.MakeReadOnly(populateMissingResolver: true); - options.MakeReadOnly(populateMissingResolver: true); - - return options; + return options; + } } } diff --git a/src/AgentCore.Application/Conversation/ConversationStatus.cs b/src/AgentCore.Application/Conversation/ConversationStatus.cs index 6d281dbd..9c984102 100644 --- a/src/AgentCore.Application/Conversation/ConversationStatus.cs +++ b/src/AgentCore.Application/Conversation/ConversationStatus.cs @@ -1,11 +1,12 @@ -namespace AgentCore.Application.Conversation; - -/// Whether a conversation still belongs in a caller's list. -public enum ConversationStatus +namespace AgentCore.Application.Conversation { - /// Listed as usual. - Regular, + /// Whether a conversation still belongs in a caller's list. + public enum ConversationStatus + { + /// Listed as usual. + Regular, - /// Kept, but out of the way. - Archived, + /// Kept, but out of the way. + Archived, + } } diff --git a/src/AgentCore.Application/Conversation/ConversationStoreFactory.cs b/src/AgentCore.Application/Conversation/ConversationStoreFactory.cs index 4285b104..54fa0385 100644 --- a/src/AgentCore.Application/Conversation/ConversationStoreFactory.cs +++ b/src/AgentCore.Application/Conversation/ConversationStoreFactory.cs @@ -4,46 +4,47 @@ using AgentCore.Application.Ports; using AgentCore.Application.Providers; -namespace AgentCore.Application.Conversation; - -/// -/// Opens the store 0 backing the document names, from the adapters the host registered. -/// -public static class ConversationStoreFactory +namespace AgentCore.Application.Conversation { - /// The built-in kind, and the one a document that names no provider gets. - public const string MemoryKind = "memory"; - - /// What this seam conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam Seam = - new("providers.conversations", "/providers/conversations/kind", "options.UseConversationStores(...)", "stores"); - - /// Opens the store providers.conversations names, or the built-in one. - /// The loaded document. - /// The chain a credential resolves through, or . - /// The vendors this host supports. - /// Cancels the open. - /// The store, which is never . - /// The configuration or the adapters are . - /// - /// The document names a kind no adapter serves, or a kind two adapters answer to. - /// - public static ValueTask OpenAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) + /// + /// Opens the store 0 backing the document names, from the adapters the host registered. + /// + public static class ConversationStoreFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + /// The built-in kind, and the one a document that names no provider gets. + public const string MemoryKind = "memory"; + + /// What this seam conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam Seam = + new("providers.conversations", "/providers/conversations/kind", "options.UseConversationStores(...)", "stores"); - if (configuration.Providers?.Conversations is not { } entry - || string.Equals(entry.Kind, MemoryKind, StringComparison.OrdinalIgnoreCase)) + /// Opens the store providers.conversations names, or the built-in one. + /// The loaded document. + /// The chain a credential resolves through, or . + /// The vendors this host supports. + /// Cancels the open. + /// The store, which is never . + /// The configuration or the adapters are . + /// + /// The document names a kind no adapter serves, or a kind two adapters answer to. + /// + public static ValueTask OpenAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - return ValueTask.FromResult(new InMemoryConversationStore()); - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); + + if (configuration.Providers?.Conversations is not { } entry + || string.Equals(entry.Kind, MemoryKind, StringComparison.OrdinalIgnoreCase)) + { + return ValueTask.FromResult(new InMemoryConversationStore()); + } - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); - return adapter.OpenAsync(entry, secrets, cancellationToken); + IConversationStoreAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); + return adapter.OpenAsync(entry, secrets, cancellationToken); + } } } diff --git a/src/AgentCore.Application/Conversation/Conversations.cs b/src/AgentCore.Application/Conversation/Conversations.cs index fb8ac666..0f75cebc 100644 --- a/src/AgentCore.Application/Conversation/Conversations.cs +++ b/src/AgentCore.Application/Conversation/Conversations.cs @@ -4,211 +4,252 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Conversation; - -/// -/// Everything a host or a consumer does with a stored conversation: its row, its words, and the files it -/// published. The one door; the stores behind it are adapters nobody else needs to name. A consumer -/// takes it as ; the turn loop and the sweeper take it as -/// . -/// -public sealed class Conversations : IConversations, IConversationStore +namespace AgentCore.Application.Conversation { - private readonly IConversationStore _conversations; - - private readonly IBlobStore? _blobs; - - /// Makes the door over the stores the document opened. - /// The store the rows and words live in. - /// The store the published files live in, or when the document names none. - public Conversations(IConversationStore conversations, IBlobStore? blobs) + /// + /// Everything a host or a consumer does with a stored conversation: its row, its words, and the files it + /// published. The one door; the stores behind it are adapters nobody else needs to name. A consumer + /// takes it as ; the turn loop and the sweeper take it as + /// . + /// + public sealed class Conversations : IConversations, IConversationStore { - ArgumentNullException.ThrowIfNull(conversations); - - _conversations = conversations; - _blobs = blobs; - } + private readonly IBlobStore? _blobs; - /// The adapter the rows live in. For a host checking which vendor it opened; go through the door for everything else. - public IConversationStore Store => _conversations; + /// Makes the door over the stores the document opened. + /// The store the rows and words live in. + /// The store the published files live in, or when the document names none. + public Conversations(IConversationStore conversations, IBlobStore? blobs) + { + ArgumentNullException.ThrowIfNull(conversations); - /// - public async ValueTask LoadWindowAsync( - string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); + Store = conversations; + _blobs = blobs; + } - var record = await _conversations.GetAsync(conversationId, cancellationToken).ConfigureAwait(false); + /// The adapter the rows live in. For a host checking which vendor it opened; go through the door for everything else. + public IConversationStore Store { get; } - if (record is null) + /// + public async ValueTask LoadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) { - return null; - } + ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); - var messages = await _conversations.ReadWindowAsync(conversationId, window, cancellationToken).ConfigureAwait(false); - - var files = await LinkFilesAsync(conversationId, messages.Select(message => message.Content), cancellationToken).ConfigureAwait(false); + ConversationRecord? record = await Store.GetAsync(conversationId, cancellationToken).ConfigureAwait(false); - var turns = messages.Select(message => message.TurnIndex).Distinct().Count(); + if (record is null) + { + return null; + } - return new StoredConversation(record, messages, files) - { - OlderBefore = turns == window.Turns ? messages.Min(message => message.TurnIndex) : null, - }; - } + IReadOnlyList messages = await Store.ReadWindowAsync(conversationId, window, cancellationToken).ConfigureAwait(false); - /// Links every published file the messages carry and the store kept, each name once, in first-seen order. - /// The conversation that owns the files. - /// The messages to read the references off: the stored transcript, or one turn's updates. - /// Cancels the signing. - /// One link per kept file. - public async Task> LinkFilesAsync( - string conversationId, - IEnumerable messages, - CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); - ArgumentNullException.ThrowIfNull(messages); + IReadOnlyList files = await LinkFilesAsync(conversationId, messages.Select(message => message.Content), cancellationToken).ConfigureAwait(false); - if (_blobs is null) - { - return []; - } + int turns = messages.Select(message => message.TurnIndex).Distinct().Count(); - List kept = []; + return new StoredConversation(record, messages, files) + { + OlderBefore = turns == window.Turns ? messages.Min(message => message.TurnIndex) : null, + }; + } - foreach (var file in messages.SelectMany(message => message.Contents).OfType()) + /// Links every published file the messages carry and the store kept, each name once, in first-seen order. + /// The conversation that owns the files. + /// The messages to read the references off: the stored transcript, or one turn's updates. + /// Cancels the signing. + /// One link per kept file. + public async Task> LinkFilesAsync( + string conversationId, + IEnumerable messages, + CancellationToken cancellationToken = default) { - if (!file.Kept || !BlobName.IsSafe(file.Name)) + ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); + ArgumentNullException.ThrowIfNull(messages); + + if (_blobs is null) + { + return []; + } + + List kept = []; + + foreach (FileContent file in messages.SelectMany(message => message.Contents).OfType()) { - continue; + if (!file.Kept || !BlobName.IsSafe(file.Name)) + { + continue; + } + + BlobRef blob = new(conversationId, file.Name, file.MediaType, file.Length); + int at = kept.FindIndex(known => string.Equals(known.Name, blob.Name, StringComparison.Ordinal)); + + if (at >= 0) + { + kept[at] = blob; + } + else + { + kept.Add(blob); + } } - BlobRef blob = new(conversationId, file.Name, file.MediaType, file.Length); - var at = kept.FindIndex(known => string.Equals(known.Name, blob.Name, StringComparison.Ordinal)); + List links = []; - if (at >= 0) + foreach (BlobRef blob in kept) { - kept[at] = blob; + Uri? url = await _blobs.LinkAsync(blob, BlobLink.Lifetime, cancellationToken).ConfigureAwait(false); + links.Add(new FileLink(blob, url)); } - else + + return links; + } + + /// + public async ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) + { + if (_blobs is not null) { - kept.Add(blob); + await _blobs.DeleteByOwnerAsync(conversationId, cancellationToken).ConfigureAwait(false); } + + await Store.DeleteAsync(conversationId, cancellationToken).ConfigureAwait(false); } - List links = []; + /// + public ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default) + { + return Store.CreateAsync(conversationId, cancellationToken); + } - foreach (var blob in kept) + /// + public ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default) { - var url = await _blobs.LinkAsync(blob, BlobLink.Lifetime, cancellationToken).ConfigureAwait(false); - links.Add(new FileLink(blob, url)); + return Store.GetAsync(conversationId, cancellationToken); } - return links; - } + /// + public ValueTask ListAsync( + string principalKey, + string? after, + int limit, + ConversationStatus? status = null, + CancellationToken cancellationToken = default) + { + return Store.ListAsync(principalKey, after, limit, status, cancellationToken); + } - /// - public async ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) - { - if (_blobs is not null) + /// + public ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default) { - await _blobs.DeleteByOwnerAsync(conversationId, cancellationToken).ConfigureAwait(false); + return Store.RenameAsync(conversationId, title, cancellationToken); } - await _conversations.DeleteAsync(conversationId, cancellationToken).ConfigureAwait(false); - } + /// + public ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) + { + return Store.SetStatusAsync(conversationId, status, cancellationToken); + } + + /// + public ValueTask SetCustomAsync(string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) + { + return Store.SetCustomAsync(conversationId, custom, cancellationToken); + } + + /// + public ValueTask SetExternalIdAsync(string conversationId, string? externalId, CancellationToken cancellationToken = default) + { + return Store.SetExternalIdAsync(conversationId, externalId, cancellationToken); + } - /// - public ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default) - => _conversations.CreateAsync(conversationId, cancellationToken); - - /// - public ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default) - => _conversations.GetAsync(conversationId, cancellationToken); - - /// - public ValueTask ListAsync( - string principalKey, - string? after, - int limit, - ConversationStatus? status = null, - CancellationToken cancellationToken = default) - => _conversations.ListAsync(principalKey, after, limit, status, cancellationToken); - - /// - public ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default) - => _conversations.RenameAsync(conversationId, title, cancellationToken); - - /// - public ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) - => _conversations.SetStatusAsync(conversationId, status, cancellationToken); - - /// - public ValueTask SetCustomAsync(string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) - => _conversations.SetCustomAsync(conversationId, custom, cancellationToken); - - /// - public ValueTask SetExternalIdAsync(string conversationId, string? externalId, CancellationToken cancellationToken = default) - => _conversations.SetExternalIdAsync(conversationId, externalId, cancellationToken); - - /// - public ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - => _conversations.AppendAsync(conversationId, messages, state, cancellationToken); - - /// - public ValueTask AppendMessageAsync(string conversationId, ChatMessage message, CancellationToken cancellationToken = default) - => _conversations.AppendMessageAsync(conversationId, message, cancellationToken); - - /// - public ValueTask RewriteAsync(string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - => _conversations.RewriteAsync(conversationId, messageId, content, cancellationToken); - - /// - public ValueTask> ReadForSessionAsync(string conversationId, CancellationToken cancellationToken = default) - => _conversations.ReadForSessionAsync(conversationId, cancellationToken); - - /// - public ValueTask> ReadWindowAsync(string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) - => _conversations.ReadWindowAsync(conversationId, window, cancellationToken); - - /// - public ValueTask OrdinalOfAsync(string conversationId, string messageId, CancellationToken cancellationToken = default) - => _conversations.OrdinalOfAsync(conversationId, messageId, cancellationToken); - - /// - public ValueTask TruncateAsync(string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) - => _conversations.TruncateAsync(conversationId, fromOrdinal, cancellationToken); - - /// - public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - => _conversations.EraseAsync(conversationId, cancellationToken); - - /// - public ValueTask SweepAsync(TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) - => _conversations.SweepAsync(retention, batchSize, cancellationToken); - - /// - public ValueTask AttachPrincipalAsync(string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) - => _conversations.AttachPrincipalAsync(conversationId, principalKey, role, cancellationToken); - - /// - public ValueTask DetachPrincipalAsync(string conversationId, string principalKey, CancellationToken cancellationToken = default) - => _conversations.DetachPrincipalAsync(conversationId, principalKey, cancellationToken); - - /// - public ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) - => _conversations.SaveContinuationAsync(continuationId, envelope, cancellationToken); - - /// - public ValueTask GetContinuationAsync(string continuationId, CancellationToken cancellationToken = default) - => _conversations.GetContinuationAsync(continuationId, cancellationToken); - - /// - public ValueTask DeleteContinuationAsync(string continuationId, CancellationToken cancellationToken = default) - => _conversations.DeleteContinuationAsync(continuationId, cancellationToken); + /// + public ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + return Store.AppendAsync(conversationId, messages, state, cancellationToken); + } + + /// + public ValueTask AppendMessageAsync(string conversationId, ChatMessage message, CancellationToken cancellationToken = default) + { + return Store.AppendMessageAsync(conversationId, message, cancellationToken); + } + + /// + public ValueTask RewriteAsync(string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + return Store.RewriteAsync(conversationId, messageId, content, cancellationToken); + } + + /// + public ValueTask> ReadForSessionAsync(string conversationId, CancellationToken cancellationToken = default) + { + return Store.ReadForSessionAsync(conversationId, cancellationToken); + } + + /// + public ValueTask> ReadWindowAsync(string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + return Store.ReadWindowAsync(conversationId, window, cancellationToken); + } + + /// + public ValueTask OrdinalOfAsync(string conversationId, string messageId, CancellationToken cancellationToken = default) + { + return Store.OrdinalOfAsync(conversationId, messageId, cancellationToken); + } + + /// + public ValueTask TruncateAsync(string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + { + return Store.TruncateAsync(conversationId, fromOrdinal, cancellationToken); + } + + /// + public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + return Store.EraseAsync(conversationId, cancellationToken); + } + + /// + public ValueTask SweepAsync(TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) + { + return Store.SweepAsync(retention, batchSize, cancellationToken); + } + + /// + public ValueTask AttachPrincipalAsync(string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) + { + return Store.AttachPrincipalAsync(conversationId, principalKey, role, cancellationToken); + } + + /// + public ValueTask DetachPrincipalAsync(string conversationId, string principalKey, CancellationToken cancellationToken = default) + { + return Store.DetachPrincipalAsync(conversationId, principalKey, cancellationToken); + } + + /// + public ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) + { + return Store.SaveContinuationAsync(continuationId, envelope, cancellationToken); + } + + /// + public ValueTask GetContinuationAsync(string continuationId, CancellationToken cancellationToken = default) + { + return Store.GetContinuationAsync(continuationId, cancellationToken); + } + + /// + public ValueTask DeleteContinuationAsync(string continuationId, CancellationToken cancellationToken = default) + { + return Store.DeleteContinuationAsync(continuationId, cancellationToken); + } + } } diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs index c8ef8980..d19a79e0 100644 --- a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationClaims.cs @@ -1,29 +1,41 @@ -namespace AgentCore.Application.Conversation.Memory; - -/// -/// Which principal may see which conversation, held beside the in-memory store's conversations. Every -/// member runs under the owning store's lock; nothing here takes one. -/// -internal sealed class InMemoryConversationClaims +namespace AgentCore.Application.Conversation.Memory { - private readonly HashSet<(string ConversationId, string PrincipalKey)> _claims = []; + /// + /// Which principal may see which conversation, held beside the in-memory store's conversations. Every + /// member runs under the owning store's lock; nothing here takes one. + /// + internal sealed class InMemoryConversationClaims + { + private readonly HashSet<(string ConversationId, string PrincipalKey)> _claims = []; - /// Gives a principal a claim on a conversation. - /// The conversation to claim. - /// The opaque key that claims it. - public void Attach(string conversationId, string principalKey) => _claims.Add((conversationId, principalKey)); + /// Gives a principal a claim on a conversation. + /// The conversation to claim. + /// The opaque key that claims it. + public void Attach(string conversationId, string principalKey) + { + _ = _claims.Add((conversationId, principalKey)); + } - /// Takes a principal's claim off a conversation. - /// The conversation to unclaim. - /// The key to remove. - public void Detach(string conversationId, string principalKey) => _claims.Remove((conversationId, principalKey)); + /// Takes a principal's claim off a conversation. + /// The conversation to unclaim. + /// The key to remove. + public void Detach(string conversationId, string principalKey) + { + _ = _claims.Remove((conversationId, principalKey)); + } - /// Reads the ids of the conversations one principal has claimed. - /// The opaque key to look up. - public IEnumerable ConversationsOf(string principalKey) - => _claims.Where(claim => claim.PrincipalKey == principalKey).Select(claim => claim.ConversationId); + /// Reads the ids of the conversations one principal has claimed. + /// The opaque key to look up. + public IEnumerable ConversationsOf(string principalKey) + { + return _claims.Where(claim => claim.PrincipalKey == principalKey).Select(claim => claim.ConversationId); + } - /// Withdraws every claim on a conversation. - /// The conversation that is going. - public void Forget(string conversationId) => _claims.RemoveWhere(claim => claim.ConversationId == conversationId); + /// Withdraws every claim on a conversation. + /// The conversation that is going. + public void Forget(string conversationId) + { + _ = _claims.RemoveWhere(claim => claim.ConversationId == conversationId); + } + } } diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs index dd98c73d..0d882986 100644 --- a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationContinuations.cs @@ -1,27 +1,36 @@ using System.Text.Json; -namespace AgentCore.Application.Conversation.Memory; - -/// -/// One serialized agent session per continuation id, held beside the in-memory store's conversations. -/// Every member runs under the owning store's lock; nothing here takes one. -/// -internal sealed class InMemoryConversationContinuations +namespace AgentCore.Application.Conversation.Memory { - private readonly Dictionary _envelopes = []; + /// + /// One serialized agent session per continuation id, held beside the in-memory store's conversations. + /// Every member runs under the owning store's lock; nothing here takes one. + /// + internal sealed class InMemoryConversationContinuations + { + private readonly Dictionary _envelopes = []; - /// Files one session envelope under one continuation id, replacing any envelope already there. - /// The continuation id: a conversation id or a response id. - /// The serialized session, as the agent wrote it. - public void Save(string continuationId, JsonElement envelope) => _envelopes[continuationId] = envelope.Clone(); + /// Files one session envelope under one continuation id, replacing any envelope already there. + /// The continuation id: a conversation id or a response id. + /// The serialized session, as the agent wrote it. + public void Save(string continuationId, JsonElement envelope) + { + _envelopes[continuationId] = envelope.Clone(); + } - /// Reads the envelope one continuation id names. - /// The continuation id to look up. - /// The envelope, or when nothing is filed under that id. - public JsonElement? Get(string continuationId) - => _envelopes.TryGetValue(continuationId, out var envelope) ? envelope : null; + /// Reads the envelope one continuation id names. + /// The continuation id to look up. + /// The envelope, or when nothing is filed under that id. + public JsonElement? Get(string continuationId) + { + return _envelopes.TryGetValue(continuationId, out JsonElement envelope) ? envelope : null; + } - /// Withdraws whatever one continuation id names, if anything. - /// The continuation id to forget. - public void Forget(string continuationId) => _envelopes.Remove(continuationId); + /// Withdraws whatever one continuation id names, if anything. + /// The continuation id to forget. + public void Forget(string continuationId) + { + _ = _envelopes.Remove(continuationId); + } + } } diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs index 8f17582a..b5d53e7d 100644 --- a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationListing.cs @@ -1,39 +1,42 @@ -namespace AgentCore.Application.Conversation.Memory; -/// How the in-memory store ranks and pages one principal's conversations. -internal static class InMemoryConversationListing +namespace AgentCore.Application.Conversation.Memory { - /// Takes one page of conversations, most recently active first. - /// Every conversation the principal has a claim on. - /// A cursor from an earlier page, or for the first. - /// How many rows this page may hold. - /// The one status to return, or for every status. - /// The page, and a cursor when a following page exists. - public static ConversationPage Page( - IEnumerable claimed, string? after, int limit, ConversationStatus? status) + /// How the in-memory store ranks and pages one principal's conversations. + internal static class InMemoryConversationListing { - var hasCursor = ConversationCursor.TryDecode(after, out var sortAt, out var cursorId); + /// Takes one page of conversations, most recently active first. + /// Every conversation the principal has a claim on. + /// A cursor from an earlier page, or for the first. + /// How many rows this page may hold. + /// The one status to return, or for every status. + /// The page, and a cursor when a following page exists. + public static ConversationPage Page( + IEnumerable claimed, string? after, int limit, ConversationStatus? status) + { + bool hasCursor = ConversationCursor.TryDecode(after, out DateTimeOffset sortAt, out string? cursorId); - var ordered = claimed - .Where(conversation => status is null || conversation.Status == status) - .Where(conversation => !hasCursor - || SortValue(conversation) < sortAt - || (SortValue(conversation) == sortAt - && string.CompareOrdinal(conversation.ConversationId, cursorId) < 0)) - .OrderByDescending(SortValue) - .ThenByDescending(conversation => conversation.ConversationId, StringComparer.Ordinal) - .Take(limit) - .ToList(); + List ordered = [.. claimed + .Where(conversation => status is null || conversation.Status == status) + .Where(conversation => !hasCursor + || SortValue(conversation) < sortAt + || (SortValue(conversation) == sortAt + && string.CompareOrdinal(conversation.ConversationId, cursorId) < 0)) + .OrderByDescending(SortValue) + .ThenByDescending(conversation => conversation.ConversationId, StringComparer.Ordinal) + .Take(limit)]; - var next = ordered.Count == limit - ? ConversationCursor.Encode(SortValue(ordered[^1]), ordered[^1].ConversationId) - : null; + string? next = ordered.Count == limit + ? ConversationCursor.Encode(SortValue(ordered[^1]), ordered[^1].ConversationId) + : null; - return new ConversationPage(ordered, next); - } + return new ConversationPage(ordered, next); + } - /// The clock a conversation is ranked by: its last message, or its making when it holds none. - /// The conversation to rank. - public static DateTimeOffset SortValue(ConversationRecord conversation) - => conversation.LastMessageAt ?? conversation.CreatedAt; + /// The clock a conversation is ranked by: its last message, or its making when it holds none. + /// The conversation to rank. + public static DateTimeOffset SortValue(ConversationRecord conversation) + { + return conversation.LastMessageAt ?? conversation.CreatedAt; + } + } } diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs index 9bbe33fa..51cc5dd0 100644 --- a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationStore.cs @@ -3,373 +3,371 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Conversation.Memory; - -/// The store backing that keeps every row in this process: a conversation, and its words. -public sealed class InMemoryConversationStore : IConversationStore +namespace AgentCore.Application.Conversation.Memory { - private readonly Lock _lock = new(); - - private readonly Dictionary _conversations = []; + /// The store backing that keeps every row in this process: a conversation, and its words. + /// Creates the store. + /// Where created_at comes from, or for the system clock. + public sealed class InMemoryConversationStore(TimeProvider? timeProvider = null) : IConversationStore + { + private readonly Lock _lock = new(); - private readonly InMemoryConversationWords _words = new(); + private readonly Dictionary _conversations = []; - /// The resume blob of each conversation, beside the row rather than on it. - private readonly Dictionary _state = []; + private readonly InMemoryConversationWords _words = new(); - private readonly InMemoryConversationClaims _claims = new(); + /// The resume blob of each conversation, beside the row rather than on it. + private readonly Dictionary _state = []; - private readonly InMemoryConversationContinuations _continuations = new(); + private readonly InMemoryConversationClaims _claims = new(); - private readonly TimeProvider _time; + private readonly InMemoryConversationContinuations _continuations = new(); - /// Creates the store. - /// Where created_at comes from, or for the system clock. - public InMemoryConversationStore(TimeProvider? timeProvider = null) => _time = timeProvider ?? TimeProvider.System; + private readonly TimeProvider _time = timeProvider ?? TimeProvider.System; - /// - public ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - - lock (_lock) + /// + public ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default) { - if (!_conversations.TryGetValue(conversationId, out var existing)) - { - var now = _time.GetUtcNow(); - existing = new ConversationRecord(conversationId, null, ConversationStatus.Regular, null, null, now, null); - _conversations[conversationId] = existing; - } + ArgumentNullException.ThrowIfNull(conversationId); - return ValueTask.FromResult(existing with + lock (_lock) { - State = _state.GetValueOrDefault(conversationId), - NextOrdinal = _words.NextOrdinal(conversationId), - }); - } - } - - /// - public ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - - lock (_lock) - { - var conversation = _conversations.GetValueOrDefault(conversationId); + if (!_conversations.TryGetValue(conversationId, out ConversationRecord? existing)) + { + DateTimeOffset now = _time.GetUtcNow(); + existing = new ConversationRecord(conversationId, null, ConversationStatus.Regular, null, null, now, null); + _conversations[conversationId] = existing; + } - return ValueTask.FromResult(conversation is null - ? null - : conversation with + return ValueTask.FromResult(existing with { State = _state.GetValueOrDefault(conversationId), NextOrdinal = _words.NextOrdinal(conversationId), }); + } } - } - /// - public ValueTask ListAsync( - string principalKey, - string? after, - int limit, - ConversationStatus? status = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(principalKey); - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(limit); - - lock (_lock) + /// + public ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default) { - var claimed = _claims - .ConversationsOf(principalKey) - .Select(_conversations.GetValueOrDefault) - .OfType(); + ArgumentNullException.ThrowIfNull(conversationId); - return ValueTask.FromResult(InMemoryConversationListing.Page(claimed, after, limit, status)); + lock (_lock) + { + ConversationRecord? conversation = _conversations.GetValueOrDefault(conversationId); + + return ValueTask.FromResult(conversation is null + ? null + : conversation with + { + State = _state.GetValueOrDefault(conversationId), + NextOrdinal = _words.NextOrdinal(conversationId), + }); + } } - } - - /// - public ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(title); - - return Amend(conversationId, conversation => conversation with { Title = title }); - } - /// - public ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + public ValueTask ListAsync( + string principalKey, + string? after, + int limit, + ConversationStatus? status = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(principalKey); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(limit); - return Amend(conversationId, conversation => conversation with { Status = status }); - } + lock (_lock) + { + IEnumerable claimed = _claims + .ConversationsOf(principalKey) + .Select(_conversations.GetValueOrDefault) + .OfType(); - /// - public ValueTask SetCustomAsync( - string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + return ValueTask.FromResult(InMemoryConversationListing.Page(claimed, after, limit, status)); + } + } - return Amend(conversationId, conversation => conversation with { Custom = custom?.Clone() }); - } + /// + public ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(title); - /// - public ValueTask SetExternalIdAsync( - string conversationId, string? externalId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + return Amend(conversationId, conversation => conversation with { Title = title }); + } - return Amend(conversationId, conversation => conversation with { ExternalId = externalId }); - } + /// + public ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + return Amend(conversationId, conversation => conversation with { Status = status }); + } - lock (_lock) + /// + public ValueTask SetCustomAsync( + string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) { - Forget(conversationId); + ArgumentNullException.ThrowIfNull(conversationId); + + return Amend(conversationId, conversation => conversation with { Custom = custom?.Clone() }); } - return default; - } + /// + public ValueTask SetExternalIdAsync( + string conversationId, string? externalId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask SweepAsync( - TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) - { - ArgumentOutOfRangeException.ThrowIfLessThan(retention, TimeSpan.Zero); - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(batchSize); + return Amend(conversationId, conversation => conversation with { ExternalId = externalId }); + } - lock (_lock) + /// + public ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) { - var cutoff = _time.GetUtcNow() - retention; - - // SortValue is the clock ListAsync ranks by, so a conversation is swept exactly when it has - // fallen off the end of the list. - // - // batchSize is read for its guard and then ignored. It exists to keep one transaction - // short in a durable backing, and this store has no transaction; honouring it here would - // only make the caller loop for the same answer. - var going = _conversations.Values - .Where(conversation => InMemoryConversationListing.SortValue(conversation) < cutoff) - .Select(conversation => conversation.ConversationId) - .ToList(); - - foreach (var conversationId in going) + ArgumentNullException.ThrowIfNull(conversationId); + + lock (_lock) { Forget(conversationId); } - return ValueTask.FromResult(going.Count); + return default; } - } - /// - public ValueTask AttachPrincipalAsync( - string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(principalKey); - ArgumentNullException.ThrowIfNull(role); - - lock (_lock) + /// + public ValueTask SweepAsync( + TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) { - _claims.Attach(conversationId, principalKey); - } + ArgumentOutOfRangeException.ThrowIfLessThan(retention, TimeSpan.Zero); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(batchSize); - return default; - } + lock (_lock) + { + DateTimeOffset cutoff = _time.GetUtcNow() - retention; + + // SortValue is the clock ListAsync ranks by, so a conversation is swept exactly when it has + // fallen off the end of the list. + // + // batchSize is read for its guard and then ignored. It exists to keep one transaction + // short in a durable backing, and this store has no transaction; honouring it here would + // only make the caller loop for the same answer. + List going = [.. _conversations.Values + .Where(conversation => InMemoryConversationListing.SortValue(conversation) < cutoff) + .Select(conversation => conversation.ConversationId)]; + + foreach (string? conversationId in going) + { + Forget(conversationId); + } - /// - public ValueTask DetachPrincipalAsync( - string conversationId, string principalKey, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(principalKey); + return ValueTask.FromResult(going.Count); + } + } - lock (_lock) + /// + public ValueTask AttachPrincipalAsync( + string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) { - _claims.Detach(conversationId, principalKey); - } + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(principalKey); + ArgumentNullException.ThrowIfNull(role); - return default; - } + lock (_lock) + { + _claims.Attach(conversationId, principalKey); + } - /// - public ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(messages); + return default; + } - if (messages.Count == 0) + /// + public ValueTask DetachPrincipalAsync( + string conversationId, string principalKey, CancellationToken cancellationToken = default) { - return ValueTask.FromResult>([]); + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(principalKey); + + lock (_lock) + { + _claims.Detach(conversationId, principalKey); + } + + return default; } - lock (_lock) + /// + public ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) { - if (!_conversations.TryGetValue(conversationId, out var conversation)) + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(messages); + + if (messages.Count == 0) { - throw new InvalidOperationException($"Store 0 holds no conversation '{conversationId}' to append words to."); + return ValueTask.FromResult>([]); } - var fallbackTurnIndex = _state.GetValueOrDefault(conversationId)?.NextTurnIndex ?? 0; - var rows = _words.Append(conversationId, messages, fallbackTurnIndex); + lock (_lock) + { + if (!_conversations.TryGetValue(conversationId, out ConversationRecord? conversation)) + { + throw new InvalidOperationException($"Store 0 holds no conversation '{conversationId}' to append words to."); + } + + int fallbackTurnIndex = _state.GetValueOrDefault(conversationId)?.NextTurnIndex ?? 0; + IReadOnlyList rows = _words.Append(conversationId, messages, fallbackTurnIndex); + + DateTimeOffset now = _time.GetUtcNow(); + _conversations[conversationId] = conversation with { LastMessageAt = now }; + + if (state is not null) + { + _state[conversationId] = state; + } - var now = _time.GetUtcNow(); - _conversations[conversationId] = conversation with { LastMessageAt = now }; + return ValueTask.FromResult(rows); + } + } + + /// + public ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); + ArgumentNullException.ThrowIfNull(content); - if (state is not null) + lock (_lock) { - _state[conversationId] = state; + _words.Rewrite(conversationId, messageId, content); } - return ValueTask.FromResult(rows); + return default; } - } - - /// - public ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentException.ThrowIfNullOrEmpty(messageId); - ArgumentNullException.ThrowIfNull(content); - lock (_lock) + /// + public ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) { - _words.Rewrite(conversationId, messageId, content); + ArgumentNullException.ThrowIfNull(conversationId); + + lock (_lock) + { + return ValueTask.FromResult(_words.ReadForSession(conversationId)); + } } - return default; - } + /// + public ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + lock (_lock) + { + return ValueTask.FromResult(_words.Read(conversationId, window)); + } + } - lock (_lock) + /// + public ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) { - return ValueTask.FromResult(_words.ReadForSession(conversationId)); - } - } + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); - /// - public ValueTask> ReadWindowAsync( - string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + lock (_lock) + { + return ValueTask.FromResult(_words.OrdinalOf(conversationId, messageId)); + } + } - lock (_lock) + /// + public ValueTask TruncateAsync( + string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) { - return ValueTask.FromResult(_words.Read(conversationId, window)); - } - } + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask OrdinalOfAsync( - string conversationId, string messageId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentException.ThrowIfNullOrEmpty(messageId); + lock (_lock) + { + return ValueTask.FromResult(_words.Truncate(conversationId, fromOrdinal)); + } + } - lock (_lock) + /// + public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) { - return ValueTask.FromResult(_words.OrdinalOf(conversationId, messageId)); - } - } + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask TruncateAsync( - string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + lock (_lock) + { + return ValueTask.FromResult(_words.Erase(conversationId)); + } + } - lock (_lock) + /// + public ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) { - return ValueTask.FromResult(_words.Truncate(conversationId, fromOrdinal)); - } - } + ArgumentNullException.ThrowIfNull(continuationId); - /// - public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + lock (_lock) + { + _continuations.Save(continuationId, envelope); + } - lock (_lock) - { - return ValueTask.FromResult(_words.Erase(conversationId)); + return default; } - } - - /// - public ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(continuationId); - lock (_lock) + /// + public ValueTask GetContinuationAsync(string continuationId, CancellationToken cancellationToken = default) { - _continuations.Save(continuationId, envelope); + ArgumentNullException.ThrowIfNull(continuationId); + + lock (_lock) + { + return ValueTask.FromResult(_continuations.Get(continuationId)); + } } - return default; - } + /// + public ValueTask DeleteContinuationAsync(string continuationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(continuationId); - /// - public ValueTask GetContinuationAsync(string continuationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(continuationId); + lock (_lock) + { + _continuations.Forget(continuationId); + } - lock (_lock) - { - return ValueTask.FromResult(_continuations.Get(continuationId)); + return default; } - } - - /// - public ValueTask DeleteContinuationAsync(string continuationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(continuationId); - lock (_lock) + /// Drops a conversation, its claims, its state, its continuation and its words. Runs under the lock. + private void Forget(string conversationId) { - _continuations.Forget(continuationId); + _ = _conversations.Remove(conversationId); + _claims.Forget(conversationId); + _ = _state.Remove(conversationId); + _continuations.Forget(conversationId); + _words.Forget(conversationId); } - return default; - } - - /// Drops a conversation, its claims, its state, its continuation and its words. Runs under the lock. - private void Forget(string conversationId) - { - _conversations.Remove(conversationId); - _claims.Forget(conversationId); - _state.Remove(conversationId); - _continuations.Forget(conversationId); - _words.Forget(conversationId); - } - - private ValueTask Amend(string conversationId, Func amend) - { - lock (_lock) + private ValueTask Amend(string conversationId, Func amend) { - if (_conversations.TryGetValue(conversationId, out var conversation)) + lock (_lock) { - _conversations[conversationId] = amend(conversation); + if (_conversations.TryGetValue(conversationId, out ConversationRecord? conversation)) + { + _conversations[conversationId] = amend(conversation); + } } - } - return default; + return default; + } } } diff --git a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs index e0a34ade..d5b99ff9 100644 --- a/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs +++ b/src/AgentCore.Application/Conversation/Memory/InMemoryConversationWords.cs @@ -2,163 +2,173 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Conversation.Memory; - -/// -/// The words of every conversation the in-memory store holds, by ordinal, and the next ordinal each -/// conversation will issue. Every member runs under the owning store's lock; nothing here takes one. -/// -internal sealed class InMemoryConversationWords +namespace AgentCore.Application.Conversation.Memory { - private readonly Dictionary<(string ConversationId, int Ordinal), ConversationMessage> _rows = []; - - /// The next free ordinal of each conversation. Never rewound, even when its words are. - private readonly Dictionary _nextOrdinal = []; - - /// Reads the ordinal a conversation's next row will take. - /// The conversation to ask about. - /// The next free ordinal, or zero for a conversation that has never spoken. - public int NextOrdinal(string conversationId) => _nextOrdinal.GetValueOrDefault(conversationId); - - /// Numbers and keeps a turn's new rows. - /// The conversation the rows belong to. - /// The rows to keep, oldest first. - /// The turn a draft that names none is filed under. - /// The rows as kept, in the order given. - public IReadOnlyList Append( - string conversationId, IReadOnlyList drafts, int fallbackTurnIndex) + /// + /// The words of every conversation the in-memory store holds, by ordinal, and the next ordinal each + /// conversation will issue. Every member runs under the owning store's lock; nothing here takes one. + /// + internal sealed class InMemoryConversationWords { - var first = NextOrdinal(conversationId); + private readonly Dictionary<(string ConversationId, int Ordinal), ConversationMessage> _rows = []; - var rows = new List(drafts.Count); - for (var index = 0; index < drafts.Count; index++) - { - var draft = drafts[index]; - ConversationMessage row = new( - conversationId, first + index, draft.TurnIndex ?? fallbackTurnIndex, draft.Content, draft.MessageId) - { - CoversUpTo = draft.CoversUpTo, - }; + /// The next free ordinal of each conversation. Never rewound, even when its words are. + private readonly Dictionary _nextOrdinal = []; - rows.Add(row); - _rows.Add((row.ConversationId, row.Ordinal), row); + /// Reads the ordinal a conversation's next row will take. + /// The conversation to ask about. + /// The next free ordinal, or zero for a conversation that has never spoken. + public int NextOrdinal(string conversationId) + { + return _nextOrdinal.GetValueOrDefault(conversationId); } - _nextOrdinal[conversationId] = first + drafts.Count; + /// Numbers and keeps a turn's new rows. + /// The conversation the rows belong to. + /// The rows to keep, oldest first. + /// The turn a draft that names none is filed under. + /// The rows as kept, in the order given. + public IReadOnlyList Append( + string conversationId, IReadOnlyList drafts, int fallbackTurnIndex) + { + int first = NextOrdinal(conversationId); - return rows; - } + List rows = new(drafts.Count); + for (int index = 0; index < drafts.Count; index++) + { + ConversationMessageDraft draft = drafts[index]; + ConversationMessage row = new( + conversationId, first + index, draft.TurnIndex ?? fallbackTurnIndex, draft.Content, draft.MessageId) + { + CoversUpTo = draft.CoversUpTo, + }; + + rows.Add(row); + _rows.Add((row.ConversationId, row.Ordinal), row); + } - /// Replaces one row's content in place, by the name the caller knows it by. - /// The conversation the row belongs to. - /// The row to rewrite. - /// What it now says. - public void Rewrite(string conversationId, string messageId, ChatMessage content) - { - foreach (var pair in _rows) + _nextOrdinal[conversationId] = first + drafts.Count; + + return rows; + } + + /// Replaces one row's content in place, by the name the caller knows it by. + /// The conversation the row belongs to. + /// The row to rewrite. + /// What it now says. + public void Rewrite(string conversationId, string messageId, ChatMessage content) { - if (pair.Key.ConversationId != conversationId || pair.Value.MessageId != messageId) + foreach (KeyValuePair<(string ConversationId, int Ordinal), ConversationMessage> pair in _rows) { - continue; - } + if (pair.Key.ConversationId != conversationId || pair.Value.MessageId != messageId) + { + continue; + } - _rows[pair.Key] = pair.Value with { Content = content }; - break; + _rows[pair.Key] = pair.Value with { Content = content }; + break; + } } - } - private IReadOnlyList Read(string conversationId) - => [.. Said(conversationId).OrderBy(row => row.Ordinal)]; + private IReadOnlyList Read(string conversationId) + { + return [.. Said(conversationId).OrderBy(row => row.Ordinal)]; + } - /// Reads one conversation as its session opens it: the newest summary, and every row above what it covers. - /// The conversation to read. - /// The rows, oldest ordinal first. - public IReadOnlyList ReadForSession(string conversationId) - { - var summary = Of(conversationId).Where(row => row.CoversUpTo is not null).MaxBy(row => row.Ordinal); - if (summary is not { CoversUpTo: { } covered }) + /// Reads one conversation as its session opens it: the newest summary, and every row above what it covers. + /// The conversation to read. + /// The rows, oldest ordinal first. + public IReadOnlyList ReadForSession(string conversationId) { - return Read(conversationId); + ConversationMessage? summary = Of(conversationId).Where(row => row.CoversUpTo is not null).MaxBy(row => row.Ordinal); + return summary is not { CoversUpTo: { } covered } + ? Read(conversationId) + : [.. Of(conversationId) + .Where(row => row.Ordinal > covered && (row.CoversUpTo is null || row.Ordinal == summary.Ordinal)) + .OrderBy(row => row.Ordinal)]; } - return [.. Of(conversationId) - .Where(row => row.Ordinal > covered && (row.CoversUpTo is null || row.Ordinal == summary.Ordinal)) - .OrderBy(row => row.Ordinal)]; - } + /// Reads the newest turns of one conversation before a given one, oldest row first. Summary rows are left out. + /// The conversation to read. + /// Which turns. + /// Every row of those turns. + public IReadOnlyList Read(string conversationId, TranscriptWindow window) + { + List rows = [.. Said(conversationId).Where(row => window.Admits(row.TurnIndex))]; - /// Reads the newest turns of one conversation before a given one, oldest row first. Summary rows are left out. - /// The conversation to read. - /// Which turns. - /// Every row of those turns. - public IReadOnlyList Read(string conversationId, TranscriptWindow window) - { - var rows = Said(conversationId).Where(row => window.Admits(row.TurnIndex)).ToList(); + HashSet kept = [.. rows + .Select(row => row.TurnIndex) + .Distinct() + .OrderByDescending(turn => turn) + .Take(window.Turns)]; - var kept = rows - .Select(row => row.TurnIndex) - .Distinct() - .OrderByDescending(turn => turn) - .Take(window.Turns) - .ToHashSet(); + return [.. rows.Where(row => kept.Contains(row.TurnIndex)).OrderBy(row => row.Ordinal)]; + } - return [.. rows.Where(row => kept.Contains(row.TurnIndex)).OrderBy(row => row.Ordinal)]; - } + /// Finds the ordinal of one row somebody said (). + /// The conversation to search. + /// The row to find. + /// The ordinal, or when no spoken row carries that id. + public int? OrdinalOf(string conversationId, string messageId) + { + return Said(conversationId).FirstOrDefault(row => string.Equals(row.MessageId, messageId, StringComparison.Ordinal))?.Ordinal; + } - /// Finds the ordinal of one row somebody said (). - /// The conversation to search. - /// The row to find. - /// The ordinal, or when no spoken row carries that id. - public int? OrdinalOf(string conversationId, string messageId) - => Said(conversationId).FirstOrDefault(row => string.Equals(row.MessageId, messageId, StringComparison.Ordinal))?.Ordinal; + /// + /// Removes a conversation's rows from one ordinal onward. A summary row goes only when the cut + /// reaches a row it covers (). + /// + /// The conversation to cut. + /// The first ordinal to remove. It goes too. + /// How many rows went, and the span of turns they belonged to. + public ConversationCut Truncate(string conversationId, int fromOrdinal) + { + List spoken = [.. Said(conversationId).Where(row => row.Ordinal >= fromOrdinal).Select(row => row.TurnIndex)]; + WithdrawnTurns? turns = spoken.Count == 0 ? null : new(spoken.Min(), spoken.Max()); - /// - /// Removes a conversation's rows from one ordinal onward. A summary row goes only when the cut - /// reaches a row it covers (). - /// - /// The conversation to cut. - /// The first ordinal to remove. It goes too. - /// How many rows went, and the span of turns they belonged to. - public ConversationCut Truncate(string conversationId, int fromOrdinal) - { - var spoken = Said(conversationId).Where(row => row.Ordinal >= fromOrdinal).Select(row => row.TurnIndex).ToList(); - WithdrawnTurns? turns = spoken.Count == 0 ? null : new(spoken.Min(), spoken.Max()); + int rows = Remove(conversationId, row => row.Ordinal >= fromOrdinal && (row.CoversUpTo is null || row.CoversUpTo >= fromOrdinal)); - var rows = Remove(conversationId, row => row.Ordinal >= fromOrdinal && (row.CoversUpTo is null || row.CoversUpTo >= fromOrdinal)); + return new(rows, turns); + } - return new(rows, turns); - } + /// Removes every row of a conversation and keeps its next ordinal. + /// The conversation to quieten. + /// How many rows went. + public int Erase(string conversationId) + { + return Remove(conversationId, static _ => true); + } - /// Removes every row of a conversation and keeps its next ordinal. - /// The conversation to quieten. - /// How many rows went. - public int Erase(string conversationId) => Remove(conversationId, static _ => true); + /// Removes every row of a conversation and forgets its next ordinal. + /// The conversation that is going. + public void Forget(string conversationId) + { + _ = _nextOrdinal.Remove(conversationId); + _ = Erase(conversationId); + } - /// Removes every row of a conversation and forgets its next ordinal. - /// The conversation that is going. - public void Forget(string conversationId) - { - _nextOrdinal.Remove(conversationId); - Erase(conversationId); - } + private IEnumerable Of(string conversationId) + { + return _rows.Values.Where(row => string.Equals(row.ConversationId, conversationId, StringComparison.Ordinal)); + } - private IEnumerable Of(string conversationId) - => _rows.Values.Where(row => string.Equals(row.ConversationId, conversationId, StringComparison.Ordinal)); + private IEnumerable Said(string conversationId) + { + return Of(conversationId).Where(static row => row.CoversUpTo is null); + } - private IEnumerable Said(string conversationId) - => Of(conversationId).Where(static row => row.CoversUpTo is null); + private int Remove(string conversationId, Func going) + { + List<(string ConversationId, int Ordinal)> keys = [.. Of(conversationId) + .Where(going) + .Select(row => (row.ConversationId, row.Ordinal))]; - private int Remove(string conversationId, Func going) - { - var keys = Of(conversationId) - .Where(going) - .Select(row => (row.ConversationId, row.Ordinal)) - .ToList(); + foreach ((string ConversationId, int Ordinal) key in keys) + { + _ = _rows.Remove(key); + } - foreach (var key in keys) - { - _rows.Remove(key); + return keys.Count; } - - return keys.Count; } } diff --git a/src/AgentCore.Application/Conversation/StoredConversation.cs b/src/AgentCore.Application/Conversation/StoredConversation.cs index 7427e3a4..4a908714 100644 --- a/src/AgentCore.Application/Conversation/StoredConversation.cs +++ b/src/AgentCore.Application/Conversation/StoredConversation.cs @@ -1,23 +1,24 @@ using AgentCore.Application.Blobs; using AgentCore.Application.Transcript; -namespace AgentCore.Application.Conversation; - -/// One conversation as the stores hold it: ready for a browser, nothing left to join. -/// The row. -/// The stored messages, oldest first: every one, or one window's worth. -/// -/// One link per file the messages name and the blob store kept, each name once, in first-seen order. -/// The links expire; read them out at once rather than keeping this record around. -/// -public sealed record StoredConversation( - ConversationRecord Conversation, - IReadOnlyList Messages, - IReadOnlyList Files) +namespace AgentCore.Application.Conversation { - /// - /// Gets the turn to read the next older window before, or when - /// reaches the conversation's start — or holds the whole conversation. - /// - public int? OlderBefore { get; init; } + /// One conversation as the stores hold it: ready for a browser, nothing left to join. + /// The row. + /// The stored messages, oldest first: every one, or one window's worth. + /// + /// One link per file the messages name and the blob store kept, each name once, in first-seen order. + /// The links expire; read them out at once rather than keeping this record around. + /// + public sealed record StoredConversation( + ConversationRecord Conversation, + IReadOnlyList Messages, + IReadOnlyList Files) + { + /// + /// Gets the turn to read the next older window before, or when + /// reaches the conversation's start — or holds the whole conversation. + /// + public int? OlderBefore { get; init; } + } } diff --git a/src/AgentCore.Application/Diagnostics/AgentCoreTelemetry.cs b/src/AgentCore.Application/Diagnostics/AgentCoreTelemetry.cs index da3b2bf9..4c8d9707 100644 --- a/src/AgentCore.Application/Diagnostics/AgentCoreTelemetry.cs +++ b/src/AgentCore.Application/Diagnostics/AgentCoreTelemetry.cs @@ -1,144 +1,151 @@ using System.Diagnostics; using System.Diagnostics.Metrics; -namespace AgentCore.Application.Diagnostics; - -/// -/// The one and the one the library owns. -/// -public static class AgentCoreTelemetry +namespace AgentCore.Application.Diagnostics { - /// The name a host passes to AddSource to receive the spans of this library. - public const string ActivitySourceName = "AgentCore"; + /// + /// The one and the one the library owns. + /// + public static class AgentCoreTelemetry + { + /// The name a host passes to AddSource to receive the spans of this library. + public const string ActivitySourceName = "AgentCore"; - /// The name a host passes to AddMeter to receive the metrics of this library. - public const string MeterName = "AgentCore"; + /// The name a host passes to AddMeter to receive the metrics of this library. + public const string MeterName = "AgentCore"; - /// The name of the span one turn opens. - public const string TurnActivityName = "agentcore.turn"; + /// The name of the span one turn opens. + public const string TurnActivityName = "agentcore.turn"; - /// The outcome of a turn that answered the caller. - internal const string OutcomeCompleted = "completed"; + /// The outcome of a turn that answered the caller. + internal const string OutcomeCompleted = "completed"; - /// The outcome of a turn the caller spoke over. - internal const string OutcomeInterrupted = "interrupted"; + /// The outcome of a turn the caller spoke over. + internal const string OutcomeInterrupted = "interrupted"; - /// The outcome of a turn that spoke the fallback of section 8.7. - internal const string OutcomeFailed = "failed"; + /// The outcome of a turn that spoke the fallback of section 8.7. + internal const string OutcomeFailed = "failed"; - /// The failure kind of section 8.7, row six: a tool failed four times in a row. - internal const string FailureTool = "tool"; + /// The failure kind of section 8.7, row six: a tool failed four times in a row. + internal const string FailureTool = "tool"; - /// The failure kind of section 8.7, last row: the run returned quietly with no text. - internal const string FailureEmptyReply = "empty_reply"; + /// The failure kind of section 8.7, last row: the run returned quietly with no text. + internal const string FailureEmptyReply = "empty_reply"; - /// The failure kind of section 8.7, row two: the extractor returned an invalid object. - internal const string FailureExtraction = "extraction"; + /// The failure kind of section 8.7, row two: the extractor returned an invalid object. + internal const string FailureExtraction = "extraction"; - /// The moderation outcome of a turn the endpoint checked and flagged nothing in. - internal const string ModerationClean = "clean"; + /// The moderation outcome of a turn the endpoint checked and flagged nothing in. + internal const string ModerationClean = "clean"; - /// The moderation outcome of a turn the endpoint flagged, so the agent refused it. - internal const string ModerationFlagged = "flagged"; + /// The moderation outcome of a turn the endpoint flagged, so the agent refused it. + internal const string ModerationFlagged = "flagged"; - /// The moderation outcome of a turn the endpoint did not answer for. - internal const string ModerationUnavailable = "unavailable"; + /// The moderation outcome of a turn the endpoint did not answer for. + internal const string ModerationUnavailable = "unavailable"; - private static readonly ActivitySource Source = new(ActivitySourceName); + private static readonly ActivitySource Source = new(ActivitySourceName); - private static readonly Meter Instruments = new(MeterName); + private static readonly Meter Instruments = new(MeterName); - private static readonly Histogram TurnDuration = Instruments.CreateHistogram( - "agentcore.turn.duration", - unit: "s", - description: "How long one turn took, from the caller's words to the spoken line."); + private static readonly Histogram TurnDuration = Instruments.CreateHistogram( + "agentcore.turn.duration", + unit: "s", + description: "How long one turn took, from the caller's words to the spoken line."); - private static readonly Counter TurnFailures = Instruments.CreateCounter( - "agentcore.turn.failures", - unit: "{failure}", - description: "Turns that met one of the section 8.7 failure rows."); + private static readonly Counter TurnFailures = Instruments.CreateCounter( + "agentcore.turn.failures", + unit: "{failure}", + description: "Turns that met one of the section 8.7 failure rows."); - private static readonly Counter AuditEvents = Instruments.CreateCounter( - "agentcore.audit.events", - unit: "{event}", - description: "Audit events the turn loop handed to the sink, by kind."); + private static readonly Counter AuditEvents = Instruments.CreateCounter( + "agentcore.audit.events", + unit: "{event}", + description: "Audit events the turn loop handed to the sink, by kind."); - private static readonly Counter ModerationVerdicts = Instruments.CreateCounter( - "agentcore.moderation.verdicts", - unit: "{verdict}", - description: "Turns the moderation endpoint checked, by outcome."); + private static readonly Counter ModerationVerdicts = Instruments.CreateCounter( + "agentcore.moderation.verdicts", + unit: "{verdict}", + description: "Turns the moderation endpoint checked, by outcome."); - /// Opens the span of one turn. - /// The id of the conversation. It goes on the span, and never on a metric. - /// The zero-based index of the turn. - /// The stage the turn speaks in. - /// The span, or when nothing listens. - internal static Activity? StartTurn(string conversationId, int turnIndex, string stageBefore) - { - Activity? activity = Source.StartActivity(TurnActivityName, ActivityKind.Internal); - if (activity is null) + /// Opens the span of one turn. + /// The id of the conversation. It goes on the span, and never on a metric. + /// The zero-based index of the turn. + /// The stage the turn speaks in. + /// The span, or when nothing listens. + internal static Activity? StartTurn(string conversationId, int turnIndex, string stageBefore) { - return null; - } + Activity? activity = Source.StartActivity(TurnActivityName, ActivityKind.Internal); + if (activity is null) + { + return null; + } - activity.SetTag("gen_ai.conversation.id", conversationId); - activity.SetTag("agentcore.turn.index", turnIndex); + _ = activity.SetTag("gen_ai.conversation.id", conversationId); + _ = activity.SetTag("agentcore.turn.index", turnIndex); - if (stageBefore.Length > 0) - { - activity.SetTag("agentcore.stage.before", stageBefore); - } - - return activity; - } + if (stageBefore.Length > 0) + { + _ = activity.SetTag("agentcore.stage.before", stageBefore); + } - /// Closes the span of one turn and records how long it took. - /// The span opened, or . - /// How long the turn took. - /// One of the three closed outcome values. - /// The stage the machine holds after the turn. - /// The section 8.7 reason, or when the turn answered. - internal static void EndTurn( - Activity? activity, - TimeSpan elapsed, - string outcome, - string stageAfter, - string? failure) - { - TurnDuration.Record(elapsed.TotalSeconds, new KeyValuePair("agentcore.turn.outcome", outcome)); + return activity; + } - if (activity is null) + /// Closes the span of one turn and records how long it took. + /// The span opened, or . + /// How long the turn took. + /// One of the three closed outcome values. + /// The stage the machine holds after the turn. + /// The section 8.7 reason, or when the turn answered. + internal static void EndTurn( + Activity? activity, + TimeSpan elapsed, + string outcome, + string stageAfter, + string? failure) { - return; + TurnDuration.Record(elapsed.TotalSeconds, new KeyValuePair("agentcore.turn.outcome", outcome)); + + if (activity is null) + { + return; + } + + _ = activity.SetTag("agentcore.turn.outcome", outcome); + + if (stageAfter.Length > 0) + { + _ = activity.SetTag("agentcore.stage.after", stageAfter); + } + + if (failure is not null) + { + // A failed turn still speaks a line, so the conversation is alive. The span says the turn failed + // and the reason names the row of section 8.7 it met. + _ = activity.SetStatus(ActivityStatusCode.Error, failure); + } } - activity.SetTag("agentcore.turn.outcome", outcome); + /// Counts one turn that met a section 8.7 failure row. + /// One of the three closed failure kinds. + internal static void RecordFailure(string kind) + { + TurnFailures.Add(1, new KeyValuePair("agentcore.failure.kind", kind)); + } - if (stageAfter.Length > 0) + /// Counts one audit event the turn loop handed to the sink. + /// The wire token of the event kind. The vocabulary is closed at seven. + internal static void RecordAuditEvent(string kindToken) { - activity.SetTag("agentcore.stage.after", stageAfter); + AuditEvents.Add(1, new KeyValuePair("agentcore.audit.kind", kindToken)); } - if (failure is not null) + /// Counts one turn the moderation endpoint was asked about. + /// One of the three closed moderation outcomes. + internal static void RecordModeration(string outcome) { - // A failed turn still speaks a line, so the conversation is alive. The span says the turn failed - // and the reason names the row of section 8.7 it met. - activity.SetStatus(ActivityStatusCode.Error, failure); + ModerationVerdicts.Add(1, new KeyValuePair("agentcore.moderation.outcome", outcome)); } } - - /// Counts one turn that met a section 8.7 failure row. - /// One of the three closed failure kinds. - internal static void RecordFailure(string kind) - => TurnFailures.Add(1, new KeyValuePair("agentcore.failure.kind", kind)); - - /// Counts one audit event the turn loop handed to the sink. - /// The wire token of the event kind. The vocabulary is closed at seven. - internal static void RecordAuditEvent(string kindToken) - => AuditEvents.Add(1, new KeyValuePair("agentcore.audit.kind", kindToken)); - - /// Counts one turn the moderation endpoint was asked about. - /// One of the three closed moderation outcomes. - internal static void RecordModeration(string outcome) - => ModerationVerdicts.Add(1, new KeyValuePair("agentcore.moderation.outcome", outcome)); } diff --git a/src/AgentCore.Application/Diagnostics/Log.cs b/src/AgentCore.Application/Diagnostics/Log.cs index e223c501..d8edb07f 100644 --- a/src/AgentCore.Application/Diagnostics/Log.cs +++ b/src/AgentCore.Application/Diagnostics/Log.cs @@ -2,333 +2,334 @@ using AgentCore.Domain.Knowledge; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Diagnostics; - -/// -/// Every line the library writes. Three of them are the "log once" rows of section 8.7. -/// -internal static partial class Log +namespace AgentCore.Application.Diagnostics { - /// Section 8.7, row two. The extractor returned an invalid object. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn that just ran. - /// Why the extractor produced nothing. - [LoggerMessage( - EventId = 1, - Level = LogLevel.Warning, - Message = "The extractor of conversation {ConversationId} produced nothing for turn {TurnIndex}: {Reason} " - + "The slots stay unchanged and the conversation continues.")] - public static partial void ExtractionFailed(ILogger logger, string conversationId, int turnIndex, string reason); + /// + /// Every line the library writes. Three of them are the "log once" rows of section 8.7. + /// + internal static partial class Log + { + /// Section 8.7, row two. The extractor returned an invalid object. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that just ran. + /// Why the extractor produced nothing. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Warning, + Message = "The extractor of conversation {ConversationId} produced nothing for turn {TurnIndex}: {Reason} " + + "The slots stay unchanged and the conversation continues.")] + public static partial void ExtractionFailed(ILogger logger, string conversationId, int turnIndex, string reason); - /// Section 8.7, row six. A tool failed four times in a row and the run threw. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn that just ran. - /// The message of the fault. - [LoggerMessage( - EventId = 2, - Level = LogLevel.Error, - Message = "A tool of conversation {ConversationId} failed four times in turn {TurnIndex}: {Reason} " - + "The turn spoke the fallback and the conversation continues.")] - public static partial void ToolBudgetSpent(ILogger logger, string conversationId, int turnIndex, string reason); + /// Section 8.7, row six. A tool failed four times in a row and the run threw. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that just ran. + /// The message of the fault. + [LoggerMessage( + EventId = 2, + Level = LogLevel.Error, + Message = "A tool of conversation {ConversationId} failed four times in turn {TurnIndex}: {Reason} " + + "The turn spoke the fallback and the conversation continues.")] + public static partial void ToolBudgetSpent(ILogger logger, string conversationId, int turnIndex, string reason); - /// Section 8.7, last row. The run returned quietly with no text. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn that just ran. - [LoggerMessage( - EventId = 3, - Level = LogLevel.Warning, - Message = "Turn {TurnIndex} of conversation {ConversationId} returned an empty reply, so it spoke the fallback. " - + "The run reached 40 tool rounds, or the model answered nothing.")] - public static partial void EmptyReply(ILogger logger, string conversationId, int turnIndex); + /// Section 8.7, last row. The run returned quietly with no text. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that just ran. + [LoggerMessage( + EventId = 3, + Level = LogLevel.Warning, + Message = "Turn {TurnIndex} of conversation {ConversationId} returned an empty reply, so it spoke the fallback. " + + "The run reached 40 tool rounds, or the model answered nothing.")] + public static partial void EmptyReply(ILogger logger, string conversationId, int turnIndex); - /// Section 8.7, row five. A guard threw at run time, or its rule did not parse. - /// The logger of the composition root. - /// The guard name, or the rule text of an inline guard. - /// The cause. - [LoggerMessage( - EventId = 4, - Level = LogLevel.Warning, - Message = "The guard {Guard} failed. It is treated as false and the conversation continues.")] - public static partial void GuardFailed(ILogger logger, string guard, Exception exception); + /// Section 8.7, row five. A guard threw at run time, or its rule did not parse. + /// The logger of the composition root. + /// The guard name, or the rule text of an inline guard. + /// The cause. + [LoggerMessage( + EventId = 4, + Level = LogLevel.Warning, + Message = "The guard {Guard} failed. It is treated as false and the conversation continues.")] + public static partial void GuardFailed(ILogger logger, string guard, Exception exception); - /// An observer of the conversation refused an event, or faulted behind its own enqueue. - /// The logger of the session. - /// The id of the conversation. - /// The wire token of the event kind. - /// The cause. - [LoggerMessage( - EventId = 5, - Level = LogLevel.Error, - Message = "The audit sink did not accept the {Kind} event of conversation {ConversationId}. " - + "The turn continues and the chain has a gap.")] - public static partial void AuditAppendFailed(ILogger logger, string conversationId, string kind, Exception exception); + /// An observer of the conversation refused an event, or faulted behind its own enqueue. + /// The logger of the session. + /// The id of the conversation. + /// The wire token of the event kind. + /// The cause. + [LoggerMessage( + EventId = 5, + Level = LogLevel.Error, + Message = "The audit sink did not accept the {Kind} event of conversation {ConversationId}. " + + "The turn continues and the chain has a gap.")] + public static partial void AuditAppendFailed(ILogger logger, string conversationId, string kind, Exception exception); - /// The moderation endpoint flagged what the caller said, so the agent refused the turn. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn. - /// The categories the endpoint flagged, comma-separated, in its order. - [LoggerMessage( - EventId = 6, - Level = LogLevel.Warning, - Message = "Moderation flagged turn {TurnIndex} of conversation {ConversationId} for {Categories}, " - + "so the agent refused it and spoke the refusal line.")] - public static partial void PromptRefused(ILogger logger, string conversationId, int turnIndex, string categories); + /// The moderation endpoint flagged what the caller said, so the agent refused the turn. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn. + /// The categories the endpoint flagged, comma-separated, in its order. + [LoggerMessage( + EventId = 6, + Level = LogLevel.Warning, + Message = "Moderation flagged turn {TurnIndex} of conversation {ConversationId} for {Categories}, " + + "so the agent refused it and spoke the refusal line.")] + public static partial void PromptRefused(ILogger logger, string conversationId, int turnIndex, string categories); - /// The moderation endpoint did not answer, so the turn ran unchecked. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn. - /// What went wrong. - [LoggerMessage( - EventId = 7, - Level = LogLevel.Warning, - Message = "Moderation did not answer for turn {TurnIndex} of conversation {ConversationId} ({Reason}). " - + "The turn ran unchecked, because moderation fails open.")] - public static partial void ModerationUnavailable(ILogger logger, string conversationId, int turnIndex, string reason); + /// The moderation endpoint did not answer, so the turn ran unchecked. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn. + /// What went wrong. + [LoggerMessage( + EventId = 7, + Level = LogLevel.Warning, + Message = "Moderation did not answer for turn {TurnIndex} of conversation {ConversationId} ({Reason}). " + + "The turn ran unchecked, because moderation fails open.")] + public static partial void ModerationUnavailable(ILogger logger, string conversationId, int turnIndex, string reason); - /// The audit queue had no room, so the event was dropped. - /// The logger of the queue. - /// The id of the conversation the dropped event belongs to. - /// The identity of the dropped event. - [LoggerMessage( - EventId = 8, - Level = LogLevel.Error, - Message = "The audit queue was full, so event {EventId} of conversation {ConversationId} was dropped. " - + "The conversation continues and the chain has a gap.")] - public static partial void AuditQueueFull(ILogger logger, string conversationId, Guid eventId); + /// The audit queue had no room, so the event was dropped. + /// The logger of the queue. + /// The id of the conversation the dropped event belongs to. + /// The identity of the dropped event. + [LoggerMessage( + EventId = 8, + Level = LogLevel.Error, + Message = "The audit queue was full, so event {EventId} of conversation {ConversationId} was dropped. " + + "The conversation continues and the chain has a gap.")] + public static partial void AuditQueueFull(ILogger logger, string conversationId, Guid eventId); - /// A store 1 write was refused, so the turn has no durable record. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn that was being written. - /// The cause. - [LoggerMessage( - EventId = 9, - Level = LogLevel.Warning, - Message = "The transcript store did not accept turn {TurnIndex} of conversation {ConversationId}. " - + "The conversation continues and the turn has no durable record.")] - public static partial void TranscriptWriteFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); + /// A store 1 write was refused, so the turn has no durable record. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that was being written. + /// The cause. + [LoggerMessage( + EventId = 9, + Level = LogLevel.Warning, + Message = "The transcript store did not accept turn {TurnIndex} of conversation {ConversationId}. " + + "The conversation continues and the turn has no durable record.")] + public static partial void TranscriptWriteFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); - /// A barge-in cut a reply, so the record now holds what the caller heard. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn whose reply was cut. - /// How much of the reply was played, as the vendor reported it. - [LoggerMessage( - EventId = 10, - Level = LogLevel.Debug, - Message = "A barge-in cut the reply of turn {TurnIndex} of conversation {ConversationId} " - + "after {PlayedMilliseconds} ms, so the record holds what the caller heard.")] - public static partial void ReplyTruncated(ILogger logger, string conversationId, int turnIndex, double playedMilliseconds); + /// A barge-in cut a reply, so the record now holds what the caller heard. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn whose reply was cut. + /// How much of the reply was played, as the vendor reported it. + [LoggerMessage( + EventId = 10, + Level = LogLevel.Debug, + Message = "A barge-in cut the reply of turn {TurnIndex} of conversation {ConversationId} " + + "after {PlayedMilliseconds} ms, so the record holds what the caller heard.")] + public static partial void ReplyTruncated(ILogger logger, string conversationId, int turnIndex, double playedMilliseconds); - /// One knowledge retrieval answered, with what it cost and what it returned. - /// The logger of the knowledge provider. - /// The id of the agent that asked. - /// How many cards the store returned, ranked and linked together. - /// The loggable part of the retrieval, as a structured field. - [LoggerMessage( - EventId = 11, - Level = LogLevel.Debug, - Message = "The knowledge base answered agent {Agent} with {CardCount} cards. {Record}")] - public static partial void KnowledgeRetrieved( - ILogger logger, string agent, int cardCount, KnowledgeAuditRecord.LogView record); + /// One knowledge retrieval answered, with what it cost and what it returned. + /// The logger of the knowledge provider. + /// The id of the agent that asked. + /// How many cards the store returned, ranked and linked together. + /// The loggable part of the retrieval, as a structured field. + [LoggerMessage( + EventId = 11, + Level = LogLevel.Debug, + Message = "The knowledge base answered agent {Agent} with {CardCount} cards. {Record}")] + public static partial void KnowledgeRetrieved( + ILogger logger, string agent, int cardCount, KnowledgeAuditRecord.LogView record); - /// A19. One knowledge retrieval threw, and this is the only place the cause survives. - /// The logger of the knowledge provider. - /// The id of the agent that asked. - /// The loggable part of the retrieval, as a structured field. - /// The cause. This, and not the record, is where the stack trace lives. - [LoggerMessage( - EventId = 12, - Level = LogLevel.Error, - Message = "The knowledge base did not answer agent {Agent}. The turn was told it is " - + "unreachable and the conversation continues. {Record}")] - public static partial void KnowledgeRetrievalFailed( - ILogger logger, string agent, KnowledgeAuditRecord.LogView record, Exception exception); + /// A19. One knowledge retrieval threw, and this is the only place the cause survives. + /// The logger of the knowledge provider. + /// The id of the agent that asked. + /// The loggable part of the retrieval, as a structured field. + /// The cause. This, and not the record, is where the stack trace lives. + [LoggerMessage( + EventId = 12, + Level = LogLevel.Error, + Message = "The knowledge base did not answer agent {Agent}. The turn was told it is " + + "unreachable and the conversation continues. {Record}")] + public static partial void KnowledgeRetrievalFailed( + ILogger logger, string agent, KnowledgeAuditRecord.LogView record, Exception exception); - /// A resumed conversation could not restore part of its stored state, so it went on without it. - /// The logger of the session. - /// The id of the conversation being resumed. - /// Which part was dropped, and why it would not go back. - [LoggerMessage( - EventId = 13, - Level = LogLevel.Warning, - Message = "Conversation {ConversationId} could not restore part of its stored state: {Reason} " - + "The conversation resumes without that part.")] - public static partial void StateRestorePartial(ILogger logger, string conversationId, string reason); + /// A resumed conversation could not restore part of its stored state, so it went on without it. + /// The logger of the session. + /// The id of the conversation being resumed. + /// Which part was dropped, and why it would not go back. + [LoggerMessage( + EventId = 13, + Level = LogLevel.Warning, + Message = "Conversation {ConversationId} could not restore part of its stored state: {Reason} " + + "The conversation resumes without that part.")] + public static partial void StateRestorePartial(ILogger logger, string conversationId, string reason); - /// One conversation had its tail withdrawn, because a caller sent an earlier message again. - /// The logger of the history provider. - /// The conversation that was cut. - /// The first ordinal withdrawn. It went too. - /// The turn the conversation had reached when the cut arrived. - [LoggerMessage( - EventId = 14, - Level = LogLevel.Debug, - Message = "An edit withdrew conversation {ConversationId} from ordinal {FromOrdinal} onward, " - + "at turn {TurnIndex}.")] - public static partial void ConversationTruncated(ILogger logger, string conversationId, int fromOrdinal, int turnIndex); + /// One conversation had its tail withdrawn, because a caller sent an earlier message again. + /// The logger of the history provider. + /// The conversation that was cut. + /// The first ordinal withdrawn. It went too. + /// The turn the conversation had reached when the cut arrived. + [LoggerMessage( + EventId = 14, + Level = LogLevel.Debug, + Message = "An edit withdrew conversation {ConversationId} from ordinal {FromOrdinal} onward, " + + "at turn {TurnIndex}.")] + public static partial void ConversationTruncated(ILogger logger, string conversationId, int fromOrdinal, int turnIndex); - /// - /// One turn composed its knowledge scope. Every facet logged - /// is a facet nothing set: this line is the only warning a deployment gets that wildcard.facets - /// names a key nothing ever sets. - /// - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn. - /// Where each facet's value came from. - [LoggerMessage( - EventId = 15, - Level = LogLevel.Debug, - Message = "Conversation {ConversationId} turn {TurnIndex} composed the knowledge scope {Origins}.")] - public static partial void KnowledgeScopeComposed( - ILogger logger, - string conversationId, - int turnIndex, - IReadOnlyDictionary origins); + /// + /// One turn composed its knowledge scope. Every facet logged + /// is a facet nothing set: this line is the only warning a deployment gets that wildcard.facets + /// names a key nothing ever sets. + /// + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn. + /// Where each facet's value came from. + [LoggerMessage( + EventId = 15, + Level = LogLevel.Debug, + Message = "Conversation {ConversationId} turn {TurnIndex} composed the knowledge scope {Origins}.")] + public static partial void KnowledgeScopeComposed( + ILogger logger, + string conversationId, + int turnIndex, + IReadOnlyDictionary origins); - /// §8's probe answered: it dropped one facet, re-searched, and found this many candidates. - /// The logger of the knowledge provider. - /// The id of the agent that asked. - /// The facet the probe dropped. - /// How many distinct values the union of the probe's cards named. - [LoggerMessage( - EventId = 16, - Level = LogLevel.Debug, - Message = "The probe of agent {Agent} dropped facet {Facet} and found {CandidateCount} candidates.")] - public static partial void KnowledgeProbeRan(ILogger logger, string agent, string facet, int candidateCount); + /// §8's probe answered: it dropped one facet, re-searched, and found this many candidates. + /// The logger of the knowledge provider. + /// The id of the agent that asked. + /// The facet the probe dropped. + /// How many distinct values the union of the probe's cards named. + [LoggerMessage( + EventId = 16, + Level = LogLevel.Debug, + Message = "The probe of agent {Agent} dropped facet {Facet} and found {CandidateCount} candidates.")] + public static partial void KnowledgeProbeRan(ILogger logger, string agent, string facet, int candidateCount); - /// - /// §8 step 4's probe search threw or timed out. The turn was told the knowledge base holds nothing - /// rather than that it is unreachable, because the main search that already ran is what answers for - /// reachability; the probe is an extra question on top of it. - /// - /// The logger of the knowledge provider. - /// The id of the agent that asked. - /// The facet the probe was trying to drop. - /// The cause. - [LoggerMessage( - EventId = 17, - Level = LogLevel.Error, - Message = "The probe of agent {Agent} did not answer for facet {Facet}. The turn was told the " - + "knowledge base holds nothing and the conversation continues.")] - public static partial void KnowledgeProbeFailed(ILogger logger, string agent, string facet, Exception exception); + /// + /// §8 step 4's probe search threw or timed out. The turn was told the knowledge base holds nothing + /// rather than that it is unreachable, because the main search that already ran is what answers for + /// reachability; the probe is an extra question on top of it. + /// + /// The logger of the knowledge provider. + /// The id of the agent that asked. + /// The facet the probe was trying to drop. + /// The cause. + [LoggerMessage( + EventId = 17, + Level = LogLevel.Error, + Message = "The probe of agent {Agent} did not answer for facet {Facet}. The turn was told the " + + "knowledge base holds nothing and the conversation continues.")] + public static partial void KnowledgeProbeFailed(ILogger logger, string agent, string facet, Exception exception); - /// An agent declared a hosted tool, and its model reports it cannot run it. - /// The logger of the compiler. - /// The id of the agent that declared the tool. - /// The id of the tool that was dropped. - /// The marker type, such as HostedWebSearchTool, so the reader knows which hosted capability was missing. - /// - /// A phrase naming the model, such as "the model 'reply'" or "this agent's default - /// model" when the agent names none. Built at the conversation site so this message never renders an - /// empty pair of quotes. - /// - [LoggerMessage( - EventId = 18, - Level = LogLevel.Warning, - Message = "The agent '{AgentId}' declares the tool '{ToolId}' of type '{Marker}', which asks the model provider " - + "to run it hosted, and {Model} reports it cannot, so the tool was not " - + "added. Point this agent at a model whose vendor runs it hosted, or remove " - + "the tool from this agent.")] - public static partial void HostedToolDropped(ILogger logger, string agentId, string toolId, string marker, string model); + /// An agent declared a hosted tool, and its model reports it cannot run it. + /// The logger of the compiler. + /// The id of the agent that declared the tool. + /// The id of the tool that was dropped. + /// The marker type, such as HostedWebSearchTool, so the reader knows which hosted capability was missing. + /// + /// A phrase naming the model, such as "the model 'reply'" or "this agent's default + /// model" when the agent names none. Built at the conversation site so this message never renders an + /// empty pair of quotes. + /// + [LoggerMessage( + EventId = 18, + Level = LogLevel.Warning, + Message = "The agent '{AgentId}' declares the tool '{ToolId}' of type '{Marker}', which asks the model provider " + + "to run it hosted, and {Model} reports it cannot, so the tool was not " + + "added. Point this agent at a model whose vendor runs it hosted, or remove " + + "the tool from this agent.")] + public static partial void HostedToolDropped(ILogger logger, string agentId, string toolId, string marker, string model); - /// Store 1 could not be read as a turn opened, so the turn ran on the words already held. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn that was opening. - /// The cause. - [LoggerMessage( - EventId = 19, - Level = LogLevel.Warning, - Message = "The transcript store could not be read as turn {TurnIndex} of conversation {ConversationId} opened. " - + "The turn runs on the words the session already holds; a message appended outside a " - + "turn since the last read is not among them.")] - public static partial void TranscriptResyncFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); + /// Store 1 could not be read as a turn opened, so the turn ran on the words already held. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that was opening. + /// The cause. + [LoggerMessage( + EventId = 19, + Level = LogLevel.Warning, + Message = "The transcript store could not be read as turn {TurnIndex} of conversation {ConversationId} opened. " + + "The turn runs on the words the session already holds; a message appended outside a " + + "turn since the last read is not among them.")] + public static partial void TranscriptResyncFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); - /// A conversation's workspace folder could not be deleted when the conversation ended. - /// The logger of the session. - /// The folder that could not be deleted. - /// The cause. - [LoggerMessage( - EventId = 20, - Level = LogLevel.Warning, - Message = "Could not delete the conversation workspace at '{Path}'.")] - public static partial void WorkspaceDeleteFailed(ILogger logger, string path, Exception exception); + /// A conversation's workspace folder could not be deleted when the conversation ended. + /// The logger of the session. + /// The folder that could not be deleted. + /// The cause. + [LoggerMessage( + EventId = 20, + Level = LogLevel.Warning, + Message = "Could not delete the conversation workspace at '{Path}'.")] + public static partial void WorkspaceDeleteFailed(ILogger logger, string path, Exception exception); - /// A conversation's shell executor could not be disposed when the conversation ended. - /// The logger of the session. - /// The conversation's workspace folder, whose shell failed to dispose. - /// The cause. - [LoggerMessage( - EventId = 21, - Level = LogLevel.Warning, - Message = "Could not dispose a shell: executor of the conversation at workspace '{Workspace}'.")] - public static partial void ShellDisposeFailed(ILogger logger, string workspace, Exception exception); + /// A conversation's shell executor could not be disposed when the conversation ended. + /// The logger of the session. + /// The conversation's workspace folder, whose shell failed to dispose. + /// The cause. + [LoggerMessage( + EventId = 21, + Level = LogLevel.Warning, + Message = "Could not dispose a shell: executor of the conversation at workspace '{Workspace}'.")] + public static partial void ShellDisposeFailed(ILogger logger, string workspace, Exception exception); - /// A conversation's background agent sessions could not be released when the conversation ended. - /// The logger of the session. - /// The id of the conversation whose children were being released. - /// The cause. - [LoggerMessage( - EventId = 22, - Level = LogLevel.Warning, - Message = "Could not release the background agent sessions of the conversation '{ConversationId}'.")] - public static partial void BackgroundReleaseFailed(ILogger logger, string conversationId, Exception exception); + /// A conversation's background agent sessions could not be released when the conversation ended. + /// The logger of the session. + /// The id of the conversation whose children were being released. + /// The cause. + [LoggerMessage( + EventId = 22, + Level = LogLevel.Warning, + Message = "Could not release the background agent sessions of the conversation '{ConversationId}'.")] + public static partial void BackgroundReleaseFailed(ILogger logger, string conversationId, Exception exception); - /// A workspace file could not be published: the run had no call to own it. - /// The logger of the tool. - /// The tool the model called. - [LoggerMessage( - EventId = 23, - Level = LogLevel.Warning, - Message = "A file published through '{Tool}' was not kept: the run has no conversation id. " - + "Files are kept only for a run through a ConversationSession, or a background child of one.")] - public static partial void SandboxFileHasNoOwner(ILogger logger, string tool); + /// A workspace file could not be published: the run had no call to own it. + /// The logger of the tool. + /// The tool the model called. + [LoggerMessage( + EventId = 23, + Level = LogLevel.Warning, + Message = "A file published through '{Tool}' was not kept: the run has no conversation id. " + + "Files are kept only for a run through a ConversationSession, or a background child of one.")] + public static partial void SandboxFileHasNoOwner(ILogger logger, string tool); - /// A workspace file was refused by name or by policy, and the model was told why. - /// The logger of the tool. - /// The conversation that would have owned the file. - /// The file's name. - /// Why it was refused. - [LoggerMessage( - EventId = 24, - Level = LogLevel.Warning, - Message = "The file '{Name}' of conversation {ConversationId} was not published: {Reason}.")] - public static partial void SandboxFileRefused(ILogger logger, string conversationId, string name, string reason); + /// A workspace file was refused by name or by policy, and the model was told why. + /// The logger of the tool. + /// The conversation that would have owned the file. + /// The file's name. + /// Why it was refused. + [LoggerMessage( + EventId = 24, + Level = LogLevel.Warning, + Message = "The file '{Name}' of conversation {ConversationId} was not published: {Reason}.")] + public static partial void SandboxFileRefused(ILogger logger, string conversationId, string name, string reason); - /// A workspace file could not be read or stored, and the model was told so. - /// The logger of the tool. - /// The conversation that would have owned the file. - /// The file's name. - /// The cause. - [LoggerMessage( - EventId = 25, - Level = LogLevel.Warning, - Message = "The file '{Name}' of conversation {ConversationId} could not be published.")] - public static partial void SandboxFileCaptureFailed(ILogger logger, string conversationId, string name, Exception exception); + /// A workspace file could not be read or stored, and the model was told so. + /// The logger of the tool. + /// The conversation that would have owned the file. + /// The file's name. + /// The cause. + [LoggerMessage( + EventId = 25, + Level = LogLevel.Warning, + Message = "The file '{Name}' of conversation {ConversationId} could not be published.")] + public static partial void SandboxFileCaptureFailed(ILogger logger, string conversationId, string name, Exception exception); - /// The compaction strategy threw after a turn committed, so the session keeps the view it had. - /// The logger of the session. - /// The id of the conversation. - /// The zero-based index of the turn that committed. - /// The cause. - [LoggerMessage( - EventId = 26, - Level = LogLevel.Warning, - Message = "The transcript of conversation {ConversationId} could not be compacted before turn {TurnIndex}. " - + "The session keeps the view it had and tries again before the next turn.")] - public static partial void TranscriptCompactionFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); + /// The compaction strategy threw after a turn committed, so the session keeps the view it had. + /// The logger of the session. + /// The id of the conversation. + /// The zero-based index of the turn that committed. + /// The cause. + [LoggerMessage( + EventId = 26, + Level = LogLevel.Warning, + Message = "The transcript of conversation {ConversationId} could not be compacted before turn {TurnIndex}. " + + "The session keeps the view it had and tries again before the next turn.")] + public static partial void TranscriptCompactionFailed(ILogger logger, string conversationId, int turnIndex, Exception exception); - [LoggerMessage( - EventId = 27, - Level = LogLevel.Warning, - Message = "The compaction strategy of conversation {ConversationId} produced, before turn {TurnIndex}, a shape one summary row " - + "cannot stand for: not one new message over the oldest rows with the rest kept in order. The session keeps the view it had.")] - public static partial void TranscriptCompactionUnsupported(ILogger logger, string conversationId, int turnIndex); + [LoggerMessage( + EventId = 27, + Level = LogLevel.Warning, + Message = "The compaction strategy of conversation {ConversationId} produced, before turn {TurnIndex}, a shape one summary row " + + "cannot stand for: not one new message over the oldest rows with the rest kept in order. The session keeps the view it had.")] + public static partial void TranscriptCompactionUnsupported(ILogger logger, string conversationId, int turnIndex); + } } diff --git a/src/AgentCore.Application/Diagnostics/LoggingConversationObserver.cs b/src/AgentCore.Application/Diagnostics/LoggingConversationObserver.cs index f55df47c..0612797c 100644 --- a/src/AgentCore.Application/Diagnostics/LoggingConversationObserver.cs +++ b/src/AgentCore.Application/Diagnostics/LoggingConversationObserver.cs @@ -4,122 +4,136 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Diagnostics; - -/// -/// Writes the "log once" rows of section 8.7, one line for each fact that earns one. -/// -internal sealed class LoggingConversationObserver : IConversationObserver +namespace AgentCore.Application.Diagnostics { - /// The turn a line names when the fact carried no index. No turn has it. - private const int NoTurn = -1; - - private readonly ILogger _logger; - - /// Creates the observer that writes the lines of section 8.7. + /// + /// Writes the "log once" rows of section 8.7, one line for each fact that earns one. + /// + /// Creates the observer that writes the lines of section 8.7. /// /// Where the lines go, or for . The /// library never throws for want of one. /// - public LoggingConversationObserver(ILogger? logger = null) => _logger = logger ?? NullLogger.Instance; - - /// - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + internal sealed class LoggingConversationObserver(ILogger? logger = null) : IConversationObserver { - ArgumentNullException.ThrowIfNull(conversationEvent); + /// The turn a line names when the fact carried no index. No turn has it. + private const int NoTurn = -1; + + private readonly ILogger _logger = logger ?? NullLogger.Instance; - switch (conversationEvent.Kind) + /// + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - case ConversationEventKind.ToolFailed: - // Section 8.7, row six. The turn spoke the fallback and the conversation stays alive, so - // nothing here is fatal, and the level says Error because a spent retry budget is a - // defect in the tool. - // - // This kind is now raised at two altitudes, and only the TURN one earns a line. A - // fact that carries a tool call id is one failing conversation, and a turn spends up to four - // of them; the chain of D23 keeps every one, which is where a record of a conversation - // belongs, and section 8.7 asks for one line and not four. The turn-level fact - // carries no conversation id, because the fault reaches the session with no function name on - // it at all, so the absent key is exactly the test. - if (conversationEvent.Payload.ContainsKey(AuditPayloadKeys.ToolCallId)) - { + ArgumentNullException.ThrowIfNull(conversationEvent); + + switch (conversationEvent.Kind) + { + case ConversationEventKind.ToolFailed: + // Section 8.7, row six. The turn spoke the fallback and the conversation stays alive, so + // nothing here is fatal, and the level says Error because a spent retry budget is a + // defect in the tool. + // + // This kind is now raised at two altitudes, and only the TURN one earns a line. A + // fact that carries a tool call id is one failing conversation, and a turn spends up to four + // of them; the chain of D23 keeps every one, which is where a record of a conversation + // belongs, and section 8.7 asks for one line and not four. The turn-level fact + // carries no conversation id, because the fault reaches the session with no function name on + // it at all, so the absent key is exactly the test. + if (conversationEvent.Payload.ContainsKey(AuditPayloadKeys.ToolCallId)) + { + break; + } + + Log.ToolBudgetSpent( + _logger, + conversationEvent.ConversationId, + TurnOf(conversationEvent), + Detail(conversationEvent, AuditPayloadKeys.ToolError)); break; - } - Log.ToolBudgetSpent( - _logger, - conversationEvent.ConversationId, - TurnOf(conversationEvent), - Detail(conversationEvent, AuditPayloadKeys.ToolError)); - break; + case ConversationEventKind.EmptyReply: + // Section 8.7, last row. On a voice call the silence is the failure. + Log.EmptyReply(_logger, conversationEvent.ConversationId, TurnOf(conversationEvent)); + break; + + case ConversationEventKind.ExtractionFailed: + // Section 8.7, row two. The slots stay unchanged and the conversation continues, so this is a + // warning and never an error. + Log.ExtractionFailed( + _logger, + conversationEvent.ConversationId, + TurnOf(conversationEvent), + Detail(conversationEvent, ConversationEventPayloadKeys.Reason)); + break; + + case ConversationEventKind.PromptFlagged: + Log.PromptRefused( + _logger, + conversationEvent.ConversationId, + TurnOf(conversationEvent), + Detail(conversationEvent, AuditPayloadKeys.ModerationCategories)); + break; - case ConversationEventKind.EmptyReply: - // Section 8.7, last row. On a voice call the silence is the failure. - Log.EmptyReply(_logger, conversationEvent.ConversationId, TurnOf(conversationEvent)); - break; + case ConversationEventKind.ModerationUnavailable: + // A vendor that did not answer is not a defect in this library, so it is a warning. + Log.ModerationUnavailable( + _logger, + conversationEvent.ConversationId, + TurnOf(conversationEvent), + Detail(conversationEvent, ConversationEventPayloadKeys.Reason)); + break; - case ConversationEventKind.ExtractionFailed: - // Section 8.7, row two. The slots stay unchanged and the conversation continues, so this is a - // warning and never an error. - Log.ExtractionFailed( - _logger, - conversationEvent.ConversationId, - TurnOf(conversationEvent), - Detail(conversationEvent, ConversationEventPayloadKeys.Reason)); - break; + case ConversationEventKind.StateRestorePartial: + // Not a turn's fact and not section 8.7's: it happens once, as the conversation opens, and it + // carries no turn index. It earns a line all the same because it is the only signal + // there is. A document change costs a resumed conversation its stage or a slot, the chain + // stores no diagnostic kind, and the caller notices only that the agent has forgotten + // them — so without this line the fault is visible to nobody but a host that wrote an + // IConversationObserver of its own. + Log.StateRestorePartial( + _logger, + conversationEvent.ConversationId, + Detail(conversationEvent, ConversationEventPayloadKeys.Reason)); + break; - case ConversationEventKind.PromptFlagged: - Log.PromptRefused( - _logger, - conversationEvent.ConversationId, - TurnOf(conversationEvent), - Detail(conversationEvent, AuditPayloadKeys.ModerationCategories)); - break; + case ConversationEventKind.ConversationStarted: + case ConversationEventKind.ModerationClean: + case ConversationEventKind.TurnCompleted: + case ConversationEventKind.ReplyInterrupted: + case ConversationEventKind.TurnSuperseded: + case ConversationEventKind.TranscriptWriteFailed: + case ConversationEventKind.ConversationEnded: + case ConversationEventKind.TranscriptResyncFailed: + // The chain of D23 is the record of a normal conversation, and a log is not. + break; - case ConversationEventKind.ModerationUnavailable: - // A vendor that did not answer is not a defect in this library, so it is a warning. - Log.ModerationUnavailable( - _logger, - conversationEvent.ConversationId, - TurnOf(conversationEvent), - Detail(conversationEvent, ConversationEventPayloadKeys.Reason)); - break; + default: + break; + } - case ConversationEventKind.StateRestorePartial: - // Not a turn's fact and not section 8.7's: it happens once, as the conversation opens, and it - // carries no turn index. It earns a line all the same because it is the only signal - // there is. A document change costs a resumed conversation its stage or a slot, the chain - // stores no diagnostic kind, and the caller notices only that the agent has forgotten - // them — so without this line the fault is visible to nobody but a host that wrote an - // IConversationObserver of its own. - Log.StateRestorePartial( - _logger, - conversationEvent.ConversationId, - Detail(conversationEvent, ConversationEventPayloadKeys.Reason)); - break; + return ValueTask.CompletedTask; + } - default: - // The chain of D23 is the record of a normal conversation, and a log is not. - break; + /// Reads the turn a line names. + /// The fact being reported. + /// Its turn index, or when it carried none. + private static int TurnOf(ConversationEvent conversationEvent) + { + return conversationEvent.TurnIndex ?? NoTurn; } - return ValueTask.CompletedTask; + /// Reads one detail a line reports. + /// The fact being reported. + /// The payload key the detail sits under. + /// The detail, or an empty string when the fact carried none. + /// + /// A missing fact is an absent key and never the word "unknown", per the rule the turn loop keeps + /// for a payload. The line is still written: what happened is the point of it, and the detail is + /// the part a reader may have to do without. + /// + private static string Detail(ConversationEvent conversationEvent, string key) + { + return conversationEvent.Payload.TryGetValue(key, out string? detail) ? detail : string.Empty; + } } - - /// Reads the turn a line names. - /// The fact being reported. - /// Its turn index, or when it carried none. - private static int TurnOf(ConversationEvent conversationEvent) => conversationEvent.TurnIndex ?? NoTurn; - - /// Reads one detail a line reports. - /// The fact being reported. - /// The payload key the detail sits under. - /// The detail, or an empty string when the fact carried none. - /// - /// A missing fact is an absent key and never the word "unknown", per the rule the turn loop keeps - /// for a payload. The line is still written: what happened is the point of it, and the detail is - /// the part a reader may have to do without. - /// - private static string Detail(ConversationEvent conversationEvent, string key) - => conversationEvent.Payload.TryGetValue(key, out string? detail) ? detail : string.Empty; } diff --git a/src/AgentCore.Application/Diagnostics/TelemetryConversationObserver.cs b/src/AgentCore.Application/Diagnostics/TelemetryConversationObserver.cs index 76040910..eff10692 100644 --- a/src/AgentCore.Application/Diagnostics/TelemetryConversationObserver.cs +++ b/src/AgentCore.Application/Diagnostics/TelemetryConversationObserver.cs @@ -2,71 +2,81 @@ using AgentCore.Application.Runtime; using AgentCore.Domain.Audit; -namespace AgentCore.Application.Diagnostics; - -/// -/// Counts the facts of a conversation on the three instruments of section 8.6. -/// -internal sealed class TelemetryConversationObserver : IConversationObserver +namespace AgentCore.Application.Diagnostics { - /// - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + /// + /// Counts the facts of a conversation on the three instruments of section 8.6. + /// + internal sealed class TelemetryConversationObserver : IConversationObserver { - ArgumentNullException.ThrowIfNull(conversationEvent); - - switch (conversationEvent.Kind) + /// + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - case ConversationEventKind.PromptFlagged: - AgentCoreTelemetry.RecordModeration(AgentCoreTelemetry.ModerationFlagged); - break; + ArgumentNullException.ThrowIfNull(conversationEvent); - case ConversationEventKind.ModerationUnavailable: - // The turn ran unchecked, because moderation fails open. This value is the only - // record of that, so an operator alerts on it rather than on a log line. - AgentCoreTelemetry.RecordModeration(AgentCoreTelemetry.ModerationUnavailable); - break; + switch (conversationEvent.Kind) + { + case ConversationEventKind.PromptFlagged: + AgentCoreTelemetry.RecordModeration(AgentCoreTelemetry.ModerationFlagged); + break; - case ConversationEventKind.ModerationClean: - AgentCoreTelemetry.RecordModeration(AgentCoreTelemetry.ModerationClean); - break; + case ConversationEventKind.ModerationUnavailable: + // The turn ran unchecked, because moderation fails open. This value is the only + // record of that, so an operator alerts on it rather than on a log line. + AgentCoreTelemetry.RecordModeration(AgentCoreTelemetry.ModerationUnavailable); + break; - case ConversationEventKind.ToolFailed: - AgentCoreTelemetry.RecordFailure(AgentCoreTelemetry.FailureTool); - break; + case ConversationEventKind.ModerationClean: + AgentCoreTelemetry.RecordModeration(AgentCoreTelemetry.ModerationClean); + break; - case ConversationEventKind.EmptyReply: - AgentCoreTelemetry.RecordFailure(AgentCoreTelemetry.FailureEmptyReply); - break; + case ConversationEventKind.ToolFailed: + AgentCoreTelemetry.RecordFailure(AgentCoreTelemetry.FailureTool); + break; - case ConversationEventKind.ExtractionFailed: - AgentCoreTelemetry.RecordFailure(AgentCoreTelemetry.FailureExtraction); - break; + case ConversationEventKind.EmptyReply: + AgentCoreTelemetry.RecordFailure(AgentCoreTelemetry.FailureEmptyReply); + break; - default: - // Six kinds reach here. Four of them — ConversationStarted, TurnCompleted, ReplyInterrupted - // and ConversationEnded — are counted below, as rows of the chain, and nowhere else. - // - // The other two, TranscriptWriteFailed and StateRestorePartial, are counted NOWHERE. - // Neither has an instrument that would take it: agentcore.turn.failures counts what a - // TURN failed at, by a closed set of values T61 keeps closed because a new value costs - // a permanent series. A refused store 1 write is a fault of the system rather than of - // the turn, and a dropped slot happens before any turn has run, so both would need an - // instrument of their own and not a fourth value on that one. They are reported as log - // lines instead, and saying so here is cheaper than an operator reading this switch and - // assuming a counter exists. - break; - } + case ConversationEventKind.ExtractionFailed: + AgentCoreTelemetry.RecordFailure(AgentCoreTelemetry.FailureExtraction); + break; - // Section 8.6 counts the events the turn loop handed to the sink, by kind, and it counted them - // whatever the sink then did with them: the old conversation sat at the top of ConversationSession.Append, - // above the enqueue and above the try. A kind the chain does not store is not one of them, so - // the six diagnostic kinds are counted by their failure or their verdict above, or not at all, - // and never here. - if (ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind auditKind)) - { - AgentCoreTelemetry.RecordAuditEvent(AuditEventKinds.ToToken(auditKind)); - } + case ConversationEventKind.ConversationStarted: + case ConversationEventKind.TurnCompleted: + case ConversationEventKind.ReplyInterrupted: + case ConversationEventKind.TurnSuperseded: + case ConversationEventKind.ConversationEnded: + // Counted below, as rows of the chain, and nowhere else. + break; - return ValueTask.CompletedTask; + case ConversationEventKind.TranscriptWriteFailed: + case ConversationEventKind.StateRestorePartial: + case ConversationEventKind.TranscriptResyncFailed: + // Counted NOWHERE. No instrument would take them: agentcore.turn.failures counts what + // a TURN failed at, by a closed set of values T61 keeps closed because a new value costs + // a permanent series. A refused store 1 write is a fault of the system rather than of + // the turn, and a dropped slot happens before any turn has run, so each would need an + // instrument of its own and not another value on that one. They are reported as log + // lines instead, and saying so here is cheaper than an operator reading this switch and + // assuming a counter exists. + break; + + default: + break; + } + + // Section 8.6 counts the events the turn loop handed to the sink, by kind, and it counted them + // whatever the sink then did with them: the old conversation sat at the top of ConversationSession.Append, + // above the enqueue and above the try. A kind the chain does not store is not one of them, so + // the six diagnostic kinds are counted by their failure or their verdict above, or not at all, + // and never here. + if (ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind auditKind)) + { + AgentCoreTelemetry.RecordAuditEvent(AuditEventKinds.ToToken(auditKind)); + } + + return ValueTask.CompletedTask; + } } } diff --git a/src/AgentCore.Application/Diagnostics/TelemetrySessionFactory.cs b/src/AgentCore.Application/Diagnostics/TelemetrySessionFactory.cs index 2e19efc4..21606509 100644 --- a/src/AgentCore.Application/Diagnostics/TelemetrySessionFactory.cs +++ b/src/AgentCore.Application/Diagnostics/TelemetrySessionFactory.cs @@ -3,61 +3,62 @@ using AgentCore.Application.Ports; using AgentCore.Application.Providers; -namespace AgentCore.Application.Diagnostics; - -/// -/// Starts the telemetry session the document names, from the adapters the host registered. -/// -/// -/// -/// This is the telemetry mirror of ModerationEvaluatorFactory and -/// CompositeKnowledgeStoreFactory, and it takes the same shape: the host lists the vendors it -/// supports once, providers.telemetry.kind picks one, and a document that changes vendors -/// changes no code. -/// -/// -/// A document that names no providers.telemetry gets no session, and a host that registered no -/// adapter for a kind the document does name fails the start. Both are deliberate: the first is a -/// document that asked for nothing, and the second is a document that asked for something this host -/// cannot give. -/// -/// -public static class TelemetrySessionFactory +namespace AgentCore.Application.Diagnostics { - /// What this seam conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam Seam = - new("providers.telemetry", "/providers/telemetry/kind", "options.UseTelemetry(...)", "collectors"); - - /// Starts the session providers.telemetry names, or none. - /// The loaded document. - /// The chain a credential resolves through, or . - /// The vendors this host supports. - /// Cancels the start. - /// - /// The running session, or when the document names no telemetry provider. - /// The caller owns it and must dispose it, because disposal is what flushes. - /// - /// The configuration or the adapters are . - /// - /// The document names a kind no adapter serves, or a kind two adapters answer to. - /// - public static async ValueTask StartAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) + /// + /// Starts the telemetry session the document names, from the adapters the host registered. + /// + /// + /// + /// This is the telemetry mirror of ModerationEvaluatorFactory and + /// CompositeKnowledgeStoreFactory, and it takes the same shape: the host lists the vendors it + /// supports once, providers.telemetry.kind picks one, and a document that changes vendors + /// changes no code. + /// + /// + /// A document that names no providers.telemetry gets no session, and a host that registered no + /// adapter for a kind the document does name fails the start. Both are deliberate: the first is a + /// document that asked for nothing, and the second is a document that asked for something this host + /// cannot give. + /// + /// + public static class TelemetrySessionFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + /// What this seam conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam Seam = + new("providers.telemetry", "/providers/telemetry/kind", "options.UseTelemetry(...)", "collectors"); - if (configuration.Providers?.Telemetry is not { } entry) + /// Starts the session providers.telemetry names, or none. + /// The loaded document. + /// The chain a credential resolves through, or . + /// The vendors this host supports. + /// Cancels the start. + /// + /// The running session, or when the document names no telemetry provider. + /// The caller owns it and must dispose it, because disposal is what flushes. + /// + /// The configuration or the adapters are . + /// + /// The document names a kind no adapter serves, or a kind two adapters answer to. + /// + public static async ValueTask StartAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - // The document asked for nothing, so no adapter is asked to start anything and no - // credential is read. A host that registers a vendor still starts with no key. - return null; - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); - return await adapter.StartAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + if (configuration.Providers?.Telemetry is not { } entry) + { + // The document asked for nothing, so no adapter is asked to start anything and no + // credential is read. A host that registers a vendor still starts with no key. + return null; + } + + ITelemetryAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); + return await adapter.StartAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.Application/Embeddings/CompositeEmbeddingGeneratorFactory.cs b/src/AgentCore.Application/Embeddings/CompositeEmbeddingGeneratorFactory.cs index 0f272065..f0c61765 100644 --- a/src/AgentCore.Application/Embeddings/CompositeEmbeddingGeneratorFactory.cs +++ b/src/AgentCore.Application/Embeddings/CompositeEmbeddingGeneratorFactory.cs @@ -3,45 +3,46 @@ using AgentCore.Application.Providers; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Embeddings; - -/// -/// The composite a config-driven host builds its embedding generator through. It routes -/// providers.embeddings.kind to the whose kind -/// matches. -/// -public static class CompositeEmbeddingGeneratorFactory +namespace AgentCore.Application.Embeddings { - /// What the embeddings field conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam EmbeddingSeam = - new("providers.embeddings.kind", "/providers/embeddings/kind", "options.UseEmbeddings(...)", "generators"); - - /// Builds the generator the document names, or nothing when it names none. - /// The loaded document. - /// The chain the adapter resolves its credential through, or . - /// The adapters the host registers, one for each vendor it supports. - /// Cancels the build. - /// The generator, or when the document has no providers.embeddings block. - /// - /// providers.embeddings.kind names a kind no adapter serves, or a kind two adapters - /// answer to. - /// - public static async ValueTask>?> CreateAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) + /// + /// The composite a config-driven host builds its embedding generator through. It routes + /// providers.embeddings.kind to the whose kind + /// matches. + /// + public static class CompositeEmbeddingGeneratorFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + /// What the embeddings field conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam EmbeddingSeam = + new("providers.embeddings.kind", "/providers/embeddings/kind", "options.UseEmbeddings(...)", "generators"); - if (configuration.Providers?.Embeddings is not { } entry) + /// Builds the generator the document names, or nothing when it names none. + /// The loaded document. + /// The chain the adapter resolves its credential through, or . + /// The adapters the host registers, one for each vendor it supports. + /// Cancels the build. + /// The generator, or when the document has no providers.embeddings block. + /// + /// providers.embeddings.kind names a kind no adapter serves, or a kind two adapters + /// answer to. + /// + public static async ValueTask>?> CreateAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - return null; - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, EmbeddingSeam); + if (configuration.Providers?.Embeddings is not { } entry) + { + return null; + } - return await adapter.CreateGeneratorAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + IEmbeddingGeneratorAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, EmbeddingSeam); + + return await adapter.CreateGeneratorAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.Application/Embeddings/HybridCachingEmbeddingGenerator.cs b/src/AgentCore.Application/Embeddings/HybridCachingEmbeddingGenerator.cs index 02403b81..4e5b9854 100644 --- a/src/AgentCore.Application/Embeddings/HybridCachingEmbeddingGenerator.cs +++ b/src/AgentCore.Application/Embeddings/HybridCachingEmbeddingGenerator.cs @@ -1,66 +1,71 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Caching.Hybrid; -namespace AgentCore.Application.Embeddings; - -/// -/// Remembers each text's embedding in the host's cache, so a repeat of the same text under the same -/// model skips the vendor call. The framework's base class wants a plain read and a plain write; -/// has no plain read, so the read is a create that is told not to create. -/// -public sealed class HybridCachingEmbeddingGenerator : CachingEmbeddingGenerator> +namespace AgentCore.Application.Embeddings { - /// How long an entry lives when the host names no lifetime. - public static readonly TimeSpan DefaultLifetime = TimeSpan.FromDays(1); + /// + /// Remembers each text's embedding in the host's cache, so a repeat of the same text under the same + /// model skips the vendor call. The framework's base class wants a plain read and a plain write; + /// has no plain read, so the read is a create that is told not to create. + /// + public sealed class HybridCachingEmbeddingGenerator : CachingEmbeddingGenerator> + { + /// How long an entry lives when the host names no lifetime. + public static readonly TimeSpan DefaultLifetime = TimeSpan.FromDays(1); - private const string KeyPrefix = "agentcore:embedding:"; + private const string KeyPrefix = "agentcore:embedding:"; - private static readonly HybridCacheEntryOptions ReadOnly = new() - { - Flags = HybridCacheEntryFlags.DisableUnderlyingData, - }; + private static readonly HybridCacheEntryOptions ReadOnly = new() + { + Flags = HybridCacheEntryFlags.DisableUnderlyingData, + }; - private readonly HybridCache _cache; + private readonly HybridCache _cache; - private readonly HybridCacheEntryOptions _write; + private readonly HybridCacheEntryOptions _write; - private readonly string? _defaultModel; + private readonly string? _defaultModel; - /// Wraps one generator in the cache. - /// The generator that talks to the vendor. - /// The host's cache. - /// How long one embedding stays cached, or for . - public HybridCachingEmbeddingGenerator( - IEmbeddingGenerator> inner, - HybridCache cache, - TimeSpan? lifetime = null) - : base(inner) - { - ArgumentNullException.ThrowIfNull(cache); + /// Wraps one generator in the cache. + /// The generator that talks to the vendor. + /// The host's cache. + /// How long one embedding stays cached, or for . + public HybridCachingEmbeddingGenerator( + IEmbeddingGenerator> inner, + HybridCache cache, + TimeSpan? lifetime = null) + : base(inner) + { + ArgumentNullException.ThrowIfNull(cache); - _cache = cache; - _write = new HybridCacheEntryOptions { Expiration = lifetime ?? DefaultLifetime }; - _defaultModel = inner.GetService()?.DefaultModelId; - } + _cache = cache; + _write = new HybridCacheEntryOptions { Expiration = lifetime ?? DefaultLifetime }; + _defaultModel = inner.GetService()?.DefaultModelId; + } - /// - /// - /// The base hands in the text and the call's options. The options may name no model, in which - /// case the vendor falls back to the generator's default, so that default joins the key. - /// - protected override string GetCacheKey(params ReadOnlySpan values) - { - object?[] parts = [.. values, _defaultModel]; - return KeyPrefix + AIJsonUtilities.HashDataToString(parts, AIJsonUtilities.DefaultOptions); - } + /// + /// + /// The base hands in the text and the call's options. The options may name no model, in which + /// case the vendor falls back to the generator's default, so that default joins the key. + /// + protected override string GetCacheKey(params ReadOnlySpan values) + { + object?[] parts = [.. values, _defaultModel]; + return KeyPrefix + AIJsonUtilities.HashDataToString(parts, AIJsonUtilities.DefaultOptions); + } - /// - protected override async Task?> ReadCacheAsync(string key, CancellationToken cancellationToken) - => await _cache - .GetOrCreateAsync(key, static _ => ValueTask.FromResult?>(null), ReadOnly, cancellationToken: cancellationToken) - .ConfigureAwait(false); + /// + protected override async Task?> ReadCacheAsync(string key, CancellationToken cancellationToken) + { + return await _cache + .GetOrCreateAsync(key, static _ => ValueTask.FromResult?>(null), ReadOnly, cancellationToken: cancellationToken) + .ConfigureAwait(false); + } - /// - protected override Task WriteCacheAsync(string key, Embedding value, CancellationToken cancellationToken) - => _cache.SetAsync(key, value, _write, cancellationToken: cancellationToken).AsTask(); + /// + protected override Task WriteCacheAsync(string key, Embedding value, CancellationToken cancellationToken) + { + return _cache.SetAsync(key, value, _write, cancellationToken: cancellationToken).AsTask(); + } + } } diff --git a/src/AgentCore.Application/Evaluation/DocumentRecallEvaluator.cs b/src/AgentCore.Application/Evaluation/DocumentRecallEvaluator.cs index d974a28f..4ea4b8c1 100644 --- a/src/AgentCore.Application/Evaluation/DocumentRecallEvaluator.cs +++ b/src/AgentCore.Application/Evaluation/DocumentRecallEvaluator.cs @@ -1,97 +1,103 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// Measures the share of the expected documents one search returned. -/// -/// -/// -/// This is the retrieval half of the offline set of D13. It answers one question: did the search -/// return the file that holds the answer. It does not read the passage, and it does not read the -/// reply. reads the reply. -/// -/// -/// It calls no model, so it runs where no key is set. That is what makes it the metric a pull request -/// can gate on, and it is the same reason guards path 1 rather than a -/// judge. -/// -/// -/// The score is recall and never precision. A store that returns the answer plus four other files -/// still answered the question, because the model reads what comes back and the reply is what section -/// 9 measures. A store that returns the answer nowhere in the first limit hits has failed, and -/// no later metric can recover from it. -/// -/// -/// A document id is compared with , the same as every other name -/// in the library. -/// -/// -public sealed class DocumentRecallEvaluator : IEvaluator +namespace AgentCore.Application.Evaluation { - /// The name of the one metric this evaluator produces. - public const string DocumentRecallMetricName = "Document Recall"; - - /// - public IReadOnlyCollection EvaluationMetricNames => [DocumentRecallMetricName]; - - /// + /// + /// Measures the share of the expected documents one search returned. + /// /// - /// The evaluation needs one in - /// , and that context has to name at least one expected - /// document. Without it the evaluator returns a metric with no value and an error diagnostic, - /// rather than a passing score: a row that expects nothing measures nothing. + /// + /// This is the retrieval half of the offline set of D13. It answers one question: did the search + /// return the file that holds the answer. It does not read the passage, and it does not read the + /// reply. reads the reply. + /// + /// + /// It calls no model, so it runs where no key is set. That is what makes it the metric a pull request + /// can gate on, and it is the same reason guards path 1 rather than a + /// judge. + /// + /// + /// The score is recall and never precision. A store that returns the answer plus four other files + /// still answered the question, because the model reads what comes back and the reply is what section + /// 9 measures. A store that returns the answer nowhere in the first limit hits has failed, and + /// no later metric can recover from it. + /// + /// + /// A document id is compared with , the same as every other name + /// in the library. + /// /// - public ValueTask EvaluateAsync( - IEnumerable messages, - ChatResponse modelResponse, - ChatConfiguration? chatConfiguration = null, - IEnumerable? additionalContext = null, - CancellationToken cancellationToken = default) + public sealed class DocumentRecallEvaluator : IEvaluator { - cancellationToken.ThrowIfCancellationRequested(); + /// The name of the one metric this evaluator produces. + public const string DocumentRecallMetricName = "Document Recall"; - RetrievedDocumentsContext? context = - additionalContext?.OfType().FirstOrDefault(); + /// + public IReadOnlyCollection EvaluationMetricNames => [DocumentRecallMetricName]; - if (context is null || context.Expected.Count == 0) + /// + /// + /// The evaluation needs one in + /// , and that context has to name at least one expected + /// document. Without it the evaluator returns a metric with no value and an error diagnostic, + /// rather than a passing score: a row that expects nothing measures nothing. + /// + public ValueTask EvaluateAsync( + IEnumerable messages, + ChatResponse modelResponse, + ChatConfiguration? chatConfiguration = null, + IEnumerable? additionalContext = null, + CancellationToken cancellationToken = default) { - NumericMetric unknown = new(DocumentRecallMetricName, value: null); - unknown.AddDiagnostics(EvaluationDiagnostic.Error( - $"the evaluation needs one {nameof(RetrievedDocumentsContext)} that names an expected document.")); - unknown.Interpretation = new EvaluationMetricInterpretation( - EvaluationRating.Inconclusive, - failed: false, - reason: "nothing named the documents the row expects."); + cancellationToken.ThrowIfCancellationRequested(); - return ValueTask.FromResult(new EvaluationResult(unknown)); - } + RetrievedDocumentsContext? context = + additionalContext?.OfType().FirstOrDefault(); - HashSet returned = new(context.Retrieved, StringComparer.Ordinal); - List missed = [.. context.Expected.Where(id => !returned.Contains(id))]; + if (context is null || context.Expected.Count == 0) + { + NumericMetric unknown = new(DocumentRecallMetricName, value: null); + unknown.AddDiagnostics(EvaluationDiagnostic.Error( + $"the evaluation needs one {nameof(RetrievedDocumentsContext)} that names an expected document.")); + unknown.Interpretation = new EvaluationMetricInterpretation( + EvaluationRating.Inconclusive, + failed: false, + reason: "nothing named the documents the row expects."); - double recall = (context.Expected.Count - missed.Count) / (double)context.Expected.Count; + return ValueTask.FromResult(new EvaluationResult(unknown)); + } - NumericMetric metric = new(DocumentRecallMetricName, recall, Explain(missed)); - metric.Interpretation = new EvaluationMetricInterpretation( - Rate(recall), - failed: missed.Count > 0, - reason: metric.Reason); + HashSet returned = new(context.Retrieved, StringComparer.Ordinal); + List missed = [.. context.Expected.Where(id => !returned.Contains(id))]; - return ValueTask.FromResult(new EvaluationResult(metric)); - } + double recall = (context.Expected.Count - missed.Count) / (double)context.Expected.Count; - private static EvaluationRating Rate(double recall) => recall switch - { - >= 1.0 => EvaluationRating.Exceptional, - >= 0.5 => EvaluationRating.Poor, - > 0.0 => EvaluationRating.Unacceptable, - _ => EvaluationRating.Unacceptable, - }; + NumericMetric metric = new(DocumentRecallMetricName, recall, Explain(missed)); + metric.Interpretation = new EvaluationMetricInterpretation( + Rate(recall), + failed: missed.Count > 0, + reason: metric.Reason); + + return ValueTask.FromResult(new EvaluationResult(metric)); + } + + private static EvaluationRating Rate(double recall) + { + return recall switch + { + >= 1.0 => EvaluationRating.Exceptional, + >= 0.5 => EvaluationRating.Poor, + > 0.0 => EvaluationRating.Unacceptable, + _ => EvaluationRating.Unacceptable, + }; + } - private static string Explain(List missed) - => missed.Count == 0 - ? "the search returned every document the row expects." - : $"the search did not return {string.Join(", ", missed)}."; + private static string Explain(List missed) + { + return missed.Count == 0 + ? "the search returned every document the row expects." + : $"the search did not return {string.Join(", ", missed)}."; + } + } } diff --git a/src/AgentCore.Application/Evaluation/EvaluationSampler.cs b/src/AgentCore.Application/Evaluation/EvaluationSampler.cs index 90f010ab..aa12e66a 100644 --- a/src/AgentCore.Application/Evaluation/EvaluationSampler.cs +++ b/src/AgentCore.Application/Evaluation/EvaluationSampler.cs @@ -1,80 +1,76 @@ -namespace AgentCore.Application.Evaluation; - -/// -/// The decision to evaluate one finished turn, or to skip it. -/// -/// -/// -/// Triage row T18 defers online sampled evaluation and says the sample rate comes from -/// configuration. This type answers one question and does nothing else: it never calls an evaluator, -/// never starts a task, and never touches a turn. Decision D9 says a judge must never block a turn, -/// so the sampler stays a decision and the caller owns what happens after it. -/// -/// -/// The rate comes from evaluation.sampleRate, which T18 asks for and D15 permits as an -/// optional key inside agentcore/v1. The composition root reads the document and passes the -/// rate here. A document that sets no rate takes -/// , which evaluates no -/// turn. -/// -/// -/// A rate of 0 answers and a rate of 1 answers without -/// drawing a number, so the two ends are deterministic with no test seam at all. Every rate between -/// them draws once, and the test passes its own draw. -/// -/// -/// Microsoft.Extensions.AI.Evaluation ships no sampler, so this type has no library -/// replacement to defer to. When T18 opens, prefer expressing the decision as a decorating -/// IEvaluator that returns an empty evaluation result for a turn this sampler skips, so it -/// composes into CompositeEvaluator or ReportingConfiguration.Evaluators rather than -/// sitting beside them as a singleton every caller must remember to consult. -/// -/// -public sealed class EvaluationSampler +namespace AgentCore.Application.Evaluation { - private readonly Func _draw; - - /// Builds a sampler that draws from . - /// The share of turns to evaluate, from 0 through 1. - /// The rate is not a number from 0 through 1. - public EvaluationSampler(double rate) - : this(rate, Random.Shared.NextDouble) - { - } - - /// Builds a sampler that draws from the supplied source. - /// The share of turns to evaluate, from 0 through 1. - /// The source of one number in the range 0 through 1. - /// The rate is not a number from 0 through 1. + /// + /// The decision to evaluate one finished turn, or to skip it. + /// /// - /// A test passes a fixed source here, so a rate between the two ends is deterministic too. The - /// source runs on the caller's thread, so a source a test writes needs no lock. + /// + /// Triage row T18 defers online sampled evaluation and says the sample rate comes from + /// configuration. This type answers one question and does nothing else: it never calls an evaluator, + /// never starts a task, and never touches a turn. Decision D9 says a judge must never block a turn, + /// so the sampler stays a decision and the caller owns what happens after it. + /// + /// + /// The rate comes from evaluation.sampleRate, which T18 asks for and D15 permits as an + /// optional key inside agentcore/v1. The composition root reads the document and passes the + /// rate here. A document that sets no rate takes + /// , which evaluates no + /// turn. + /// + /// + /// A rate of 0 answers and a rate of 1 answers without + /// drawing a number, so the two ends are deterministic with no test seam at all. Every rate between + /// them draws once, and the test passes its own draw. + /// + /// + /// Microsoft.Extensions.AI.Evaluation ships no sampler, so this type has no library + /// replacement to defer to. When T18 opens, prefer expressing the decision as a decorating + /// IEvaluator that returns an empty evaluation result for a turn this sampler skips, so it + /// composes into CompositeEvaluator or ReportingConfiguration.Evaluators rather than + /// sitting beside them as a singleton every caller must remember to consult. + /// /// - public EvaluationSampler(double rate, Func draw) + public sealed class EvaluationSampler { - ArgumentNullException.ThrowIfNull(draw); + private readonly Func _draw; - if (double.IsNaN(rate) || rate < 0 || rate > 1) + /// Builds a sampler that draws from . + /// The share of turns to evaluate, from 0 through 1. + /// The rate is not a number from 0 through 1. + public EvaluationSampler(double rate) + : this(rate, Random.Shared.NextDouble) { - throw new ArgumentOutOfRangeException(nameof(rate), rate, "the sample rate runs from 0 through 1."); } - Rate = rate; - _draw = draw; - } + /// Builds a sampler that draws from the supplied source. + /// The share of turns to evaluate, from 0 through 1. + /// The source of one number in the range 0 through 1. + /// The rate is not a number from 0 through 1. + /// + /// A test passes a fixed source here, so a rate between the two ends is deterministic too. The + /// source runs on the caller's thread, so a source a test writes needs no lock. + /// + public EvaluationSampler(double rate, Func draw) + { + ArgumentNullException.ThrowIfNull(draw); - /// Gets the share of turns this sampler selects. - public double Rate { get; } + if (double.IsNaN(rate) || rate < 0 || rate > 1) + { + throw new ArgumentOutOfRangeException(nameof(rate), rate, "the sample rate runs from 0 through 1."); + } - /// Decides whether to evaluate one finished turn. - /// when the turn falls in the sample. - public bool ShouldSample() - { - if (Rate <= 0) - { - return false; + Rate = rate; + _draw = draw; } - return Rate >= 1 || _draw() < Rate; + /// Gets the share of turns this sampler selects. + public double Rate { get; } + + /// Decides whether to evaluate one finished turn. + /// when the turn falls in the sample. + public bool ShouldSample() + { + return Rate > 0 && (Rate >= 1 || _draw() < Rate); + } } } diff --git a/src/AgentCore.Application/Evaluation/EvaluationScore.cs b/src/AgentCore.Application/Evaluation/EvaluationScore.cs index c47fdd32..fa946f77 100644 --- a/src/AgentCore.Application/Evaluation/EvaluationScore.cs +++ b/src/AgentCore.Application/Evaluation/EvaluationScore.cs @@ -1,15 +1,16 @@ using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// One finished evaluation, ready to leave the library. -/// -/// -/// The score names the evaluator that produced it, because one turn may pass through several and a -/// reader has to tell the metrics apart. It carries nothing else. The library holds no domain type -/// under D15, so a turn identifier and a timestamp belong to whatever the host publishes into. -/// -/// The name the evaluator carries in . -/// The metrics the evaluator produced. -public sealed record EvaluationScore(string Evaluator, EvaluationResult Result); +namespace AgentCore.Application.Evaluation +{ + /// + /// One finished evaluation, ready to leave the library. + /// + /// + /// The score names the evaluator that produced it, because one turn may pass through several and a + /// reader has to tell the metrics apart. It carries nothing else. The library holds no domain type + /// under D15, so a turn identifier and a timestamp belong to whatever the host publishes into. + /// + /// The name the evaluator carries in . + /// The metrics the evaluator produced. + public sealed record EvaluationScore(string Evaluator, EvaluationResult Result); +} diff --git a/src/AgentCore.Application/Evaluation/EvaluatorRegistry.cs b/src/AgentCore.Application/Evaluation/EvaluatorRegistry.cs index d26cca78..4bcde689 100644 --- a/src/AgentCore.Application/Evaluation/EvaluatorRegistry.cs +++ b/src/AgentCore.Application/Evaluation/EvaluatorRegistry.cs @@ -1,72 +1,70 @@ using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// The map from a name to the behind it. -/// -/// -/// -/// Decision D13 makes the evaluation port and keeps evaluation inside the -/// library. A quality evaluator, an NLP evaluator, the custom evaluators in this folder, and the -/// moderation adapter in Infrastructure/Evaluation/OpenAiModeration/ all arrive here under one -/// name, so the composition root reads the same as it does for a tool or a binding. -/// -/// -/// This registry takes the shape takes, because D13 asks the -/// registries to be one shape. A name is compared with . -/// Registration happens at startup and reading happens later, so the registry is safe to read from -/// many turns at once once the host stops writing to it. -/// -/// -/// The registry holds evaluators. It never runs one. Triage row T18 defers online sampled -/// evaluation, and D9 says a judge must never block a turn, so nothing here reaches a turn loop. -/// -/// -public sealed class EvaluatorRegistry +namespace AgentCore.Application.Evaluation { - private readonly Dictionary _evaluators = new(StringComparer.Ordinal); - - /// Gets the number of names the host registered. - public int Count => _evaluators.Count; + /// + /// The map from a name to the behind it. + /// + /// + /// + /// Decision D13 makes the evaluation port and keeps evaluation inside the + /// library. A quality evaluator, an NLP evaluator, the custom evaluators in this folder, and the + /// moderation adapter in Infrastructure/Evaluation/OpenAiModeration/ all arrive here under one + /// name, so the composition root reads the same as it does for a tool or a binding. + /// + /// + /// This registry takes the shape takes, because D13 asks the + /// registries to be one shape. A name is compared with . + /// Registration happens at startup and reading happens later, so the registry is safe to read from + /// many turns at once once the host stops writing to it. + /// + /// + /// The registry holds evaluators. It never runs one. Triage row T18 defers online sampled + /// evaluation, and D9 says a judge must never block a turn, so nothing here reaches a turn loop. + /// + /// + public sealed class EvaluatorRegistry + { + private readonly Dictionary _evaluators = new(StringComparer.Ordinal); - /// Gets the names the host registered. - public IReadOnlyCollection Names => _evaluators.Keys; + /// Gets the number of names the host registered. + public int Count => _evaluators.Count; - /// Registers one evaluator. - /// The name the host reads the evaluator back by. - /// The evaluator. - /// This registry, so a host chains its registrations. - /// The name is already registered. - public EvaluatorRegistry Register(string name, IEvaluator evaluator) - { - ArgumentException.ThrowIfNullOrEmpty(name); - ArgumentNullException.ThrowIfNull(evaluator); + /// Gets the names the host registered. + public IReadOnlyCollection Names => _evaluators.Keys; - if (!_evaluators.TryAdd(name, evaluator)) + /// Registers one evaluator. + /// The name the host reads the evaluator back by. + /// The evaluator. + /// This registry, so a host chains its registrations. + /// The name is already registered. + public EvaluatorRegistry Register(string name, IEvaluator evaluator) { - throw new ArgumentException($"the evaluator '{name}' is already registered.", nameof(name)); - } + ArgumentException.ThrowIfNullOrEmpty(name); + ArgumentNullException.ThrowIfNull(evaluator); - return this; - } + return !_evaluators.TryAdd(name, evaluator) + ? throw new ArgumentException($"the evaluator '{name}' is already registered.", nameof(name)) + : this; + } - /// Reports whether one name is registered. - /// The name the host registered. - /// when the host registered the name. - public bool Contains(string name) - { - ArgumentNullException.ThrowIfNull(name); - return _evaluators.ContainsKey(name); - } + /// Reports whether one name is registered. + /// The name the host registered. + /// when the host registered the name. + public bool Contains(string name) + { + ArgumentNullException.ThrowIfNull(name); + return _evaluators.ContainsKey(name); + } - /// Reads the evaluator one name points at. - /// The name the host registered. - /// The evaluator, when the name is registered. - /// when the host registered the name. - public bool TryGetEvaluator(string name, out IEvaluator? evaluator) - { - ArgumentNullException.ThrowIfNull(name); - return _evaluators.TryGetValue(name, out evaluator); + /// Reads the evaluator one name points at. + /// The name the host registered. + /// The evaluator, when the name is registered. + /// when the host registered the name. + public bool TryGetEvaluator(string name, out IEvaluator? evaluator) + { + ArgumentNullException.ThrowIfNull(name); + return _evaluators.TryGetValue(name, out evaluator); + } } } diff --git a/src/AgentCore.Application/Evaluation/FaultCodeContext.cs b/src/AgentCore.Application/Evaluation/FaultCodeContext.cs index b911cdee..b5db7dd1 100644 --- a/src/AgentCore.Application/Evaluation/FaultCodeContext.cs +++ b/src/AgentCore.Application/Evaluation/FaultCodeContext.cs @@ -1,47 +1,50 @@ using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// The fault codes access path 1 resolved for one turn. -/// -/// -/// -/// Decision D10 makes fault-code lookup a path convention, so the turn already knows which codes it -/// read: (model, code) named a file and the agent read that file. This context carries those -/// codes to , which is the only reader of it. -/// -/// -/// The context holds what the lookup resolved, not what the reply says. Section 9 makes the point -/// this exists for: the lookup is deterministic and the data is not, so the reply is the part nothing -/// else checks. -/// -/// -public sealed class FaultCodeContext : EvaluationContext +namespace AgentCore.Application.Evaluation { - /// The name this context carries. - public const string FaultCodeContextName = "Fault Codes"; - - /// Builds a context from the codes the lookup resolved. - /// - /// The fault codes access path 1 resolved, written as the knowledge base writes them. - /// - /// The codes are . - public FaultCodeContext(IEnumerable codes) - : this(Materialize(codes)) + /// + /// The fault codes access path 1 resolved for one turn. + /// + /// + /// + /// Decision D10 makes fault-code lookup a path convention, so the turn already knows which codes it + /// read: (model, code) named a file and the agent read that file. This context carries those + /// codes to , which is the only reader of it. + /// + /// + /// The context holds what the lookup resolved, not what the reply says. Section 9 makes the point + /// this exists for: the lookup is deterministic and the data is not, so the reply is the part nothing + /// else checks. + /// + /// + public sealed class FaultCodeContext : EvaluationContext { - } + /// The name this context carries. + public const string FaultCodeContextName = "Fault Codes"; - private FaultCodeContext(string[] codes) - : base(FaultCodeContextName, string.Join(", ", codes)) - => Codes = codes; + /// Builds a context from the codes the lookup resolved. + /// + /// The fault codes access path 1 resolved, written as the knowledge base writes them. + /// + /// The codes are . + public FaultCodeContext(IEnumerable codes) + : this(Materialize(codes)) + { + } - /// Gets the fault codes access path 1 resolved. - public IReadOnlyList Codes { get; } + private FaultCodeContext(string[] codes) + : base(FaultCodeContextName, string.Join(", ", codes)) + { + Codes = codes; + } - private static string[] Materialize(IEnumerable codes) - { - ArgumentNullException.ThrowIfNull(codes); - return [.. codes]; + /// Gets the fault codes access path 1 resolved. + public IReadOnlyList Codes { get; } + + private static string[] Materialize(IEnumerable codes) + { + ArgumentNullException.ThrowIfNull(codes); + return [.. codes]; + } } } diff --git a/src/AgentCore.Application/Evaluation/FaultCodeEvaluator.cs b/src/AgentCore.Application/Evaluation/FaultCodeEvaluator.cs index 8d0f065f..4f77d9f1 100644 --- a/src/AgentCore.Application/Evaluation/FaultCodeEvaluator.cs +++ b/src/AgentCore.Application/Evaluation/FaultCodeEvaluator.cs @@ -2,144 +2,145 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// Measures whether a reply states the fault codes access path 1 resolved, and no others. -/// -/// -/// -/// Decision D13 asks for custom evaluators, and names this one. It is written once and used twice: -/// the offline golden set in tests/AgentCore.Evals runs it over recorded rows, and the online -/// path runs it over a sampled turn when triage row T18 opens. -/// -/// -/// The evaluator measures two failures, and both come from section 9. A reply that omits the code the -/// lookup resolved sends the caller to the wrong page. A reply that states a code the lookup did not -/// resolve invented it, and D10 cannot catch that, because the lookup already succeeded. -/// -/// -/// It calls no model. The measurement is a set comparison over the reply text, so it costs nothing, -/// it never blocks, and it gives the same answer every time. That is why this evaluator, and not a -/// judge, guards path 1. -/// -/// -/// A code is compared with , the same as every other name in -/// the library. The reply has to write the code the way the knowledge base writes it, which is what -/// the caller reads off the console. -/// -/// -public sealed class FaultCodeEvaluator : IEvaluator +namespace AgentCore.Application.Evaluation { - /// The name of the one metric this evaluator produces. - public const string FaultCodeAccuracyMetricName = "Fault Code Accuracy"; - - /// The shape a fault code takes when no host names another. - /// - /// It matches one to three capital letters, an optional hyphen, and one to three digits, so - /// E7 and LS-12 both count. The shape belongs to the knowledge base, not to this - /// library, so a host with another convention passes its own pattern. A host whose model names - /// take this shape too, such as F85, has to pass a narrower pattern, or every reply that - /// names the machine reads as an invented code. - /// - public const string DefaultCodePattern = @"\b[A-Z]{1,3}-?[0-9]{1,3}\b"; - - private static readonly TimeSpan MatchTimeout = TimeSpan.FromSeconds(1); - - private readonly Regex _codeShape; - - /// Builds an evaluator that reads codes with . - public FaultCodeEvaluator() - : this(DefaultCodePattern) - { - } - - /// Builds an evaluator that reads codes with the supplied pattern. - /// The shape a fault code takes in the knowledge base. - /// The pattern is empty or does not compile. - /// - /// The pattern is a C# value, not a configuration key. Decision D15 closes the configuration - /// document, and no key describes a fault code today, so the host passes the shape in. - /// - public FaultCodeEvaluator(string codePattern) - { - ArgumentException.ThrowIfNullOrEmpty(codePattern); - _codeShape = new Regex(codePattern, RegexOptions.CultureInvariant, MatchTimeout); - } - - /// - public IReadOnlyCollection EvaluationMetricNames => [FaultCodeAccuracyMetricName]; - - /// + /// + /// Measures whether a reply states the fault codes access path 1 resolved, and no others. + /// /// - /// The evaluation needs one in . - /// Without it the evaluator cannot know what the lookup resolved, so it returns a metric with no - /// value and an error diagnostic rather than a passing score. + /// + /// Decision D13 asks for custom evaluators, and names this one. It is written once and used twice: + /// the offline golden set in tests/AgentCore.Evals runs it over recorded rows, and the online + /// path runs it over a sampled turn when triage row T18 opens. + /// + /// + /// The evaluator measures two failures, and both come from section 9. A reply that omits the code the + /// lookup resolved sends the caller to the wrong page. A reply that states a code the lookup did not + /// resolve invented it, and D10 cannot catch that, because the lookup already succeeded. + /// + /// + /// It calls no model. The measurement is a set comparison over the reply text, so it costs nothing, + /// it never blocks, and it gives the same answer every time. That is why this evaluator, and not a + /// judge, guards path 1. + /// + /// + /// A code is compared with , the same as every other name in + /// the library. The reply has to write the code the way the knowledge base writes it, which is what + /// the caller reads off the console. + /// /// - public ValueTask EvaluateAsync( - IEnumerable messages, - ChatResponse modelResponse, - ChatConfiguration? chatConfiguration = null, - IEnumerable? additionalContext = null, - CancellationToken cancellationToken = default) + public sealed class FaultCodeEvaluator : IEvaluator { - ArgumentNullException.ThrowIfNull(modelResponse); - cancellationToken.ThrowIfCancellationRequested(); - - FaultCodeContext? context = additionalContext?.OfType().FirstOrDefault(); - if (context is null) + /// The name of the one metric this evaluator produces. + public const string FaultCodeAccuracyMetricName = "Fault Code Accuracy"; + + /// The shape a fault code takes when no host names another. + /// + /// It matches one to three capital letters, an optional hyphen, and one to three digits, so + /// E7 and LS-12 both count. The shape belongs to the knowledge base, not to this + /// library, so a host with another convention passes its own pattern. A host whose model names + /// take this shape too, such as F85, has to pass a narrower pattern, or every reply that + /// names the machine reads as an invented code. + /// + public const string DefaultCodePattern = @"\b[A-Z]{1,3}-?[0-9]{1,3}\b"; + + private static readonly TimeSpan MatchTimeout = TimeSpan.FromSeconds(1); + + private readonly Regex _codeShape; + + /// Builds an evaluator that reads codes with . + public FaultCodeEvaluator() + : this(DefaultCodePattern) { - BooleanMetric unknown = new(FaultCodeAccuracyMetricName, value: null); - unknown.AddDiagnostics( - EvaluationDiagnostic.Error($"the evaluation needs one {nameof(FaultCodeContext)}.")); - unknown.Interpretation = new EvaluationMetricInterpretation( - EvaluationRating.Inconclusive, - failed: false, - reason: "nothing named the codes access path 1 resolved."); - - return ValueTask.FromResult(new EvaluationResult(unknown)); } - string reply = modelResponse.Text; - - List missing = [.. context.Codes.Where(code => !reply.Contains(code, StringComparison.Ordinal))]; - HashSet resolved = new(context.Codes, StringComparer.Ordinal); - List invented = - [ - .. _codeShape.Matches(reply) - .Select(match => match.Value) - .Where(cited => !resolved.Contains(cited)) - .Distinct(StringComparer.Ordinal), - ]; - - bool accurate = missing.Count == 0 && invented.Count == 0; - BooleanMetric metric = new(FaultCodeAccuracyMetricName, accurate, Explain(missing, invented)); - metric.Interpretation = new EvaluationMetricInterpretation( - accurate ? EvaluationRating.Exceptional : EvaluationRating.Unacceptable, - failed: !accurate, - reason: metric.Reason); - - return ValueTask.FromResult(new EvaluationResult(metric)); - } - - private static string Explain(List missing, List invented) - { - if (missing.Count == 0 && invented.Count == 0) + /// Builds an evaluator that reads codes with the supplied pattern. + /// The shape a fault code takes in the knowledge base. + /// The pattern is empty or does not compile. + /// + /// The pattern is a C# value, not a configuration key. Decision D15 closes the configuration + /// document, and no key describes a fault code today, so the host passes the shape in. + /// + public FaultCodeEvaluator(string codePattern) { - return "the reply states every code the lookup resolved, and no other."; + ArgumentException.ThrowIfNullOrEmpty(codePattern); + _codeShape = new Regex(codePattern, RegexOptions.CultureInvariant, MatchTimeout); } - List parts = []; - if (missing.Count > 0) + /// + public IReadOnlyCollection EvaluationMetricNames => [FaultCodeAccuracyMetricName]; + + /// + /// + /// The evaluation needs one in . + /// Without it the evaluator cannot know what the lookup resolved, so it returns a metric with no + /// value and an error diagnostic rather than a passing score. + /// + public ValueTask EvaluateAsync( + IEnumerable messages, + ChatResponse modelResponse, + ChatConfiguration? chatConfiguration = null, + IEnumerable? additionalContext = null, + CancellationToken cancellationToken = default) { - parts.Add($"the reply omits {string.Join(", ", missing)}."); + ArgumentNullException.ThrowIfNull(modelResponse); + cancellationToken.ThrowIfCancellationRequested(); + + FaultCodeContext? context = additionalContext?.OfType().FirstOrDefault(); + if (context is null) + { + BooleanMetric unknown = new(FaultCodeAccuracyMetricName, value: null); + unknown.AddDiagnostics( + EvaluationDiagnostic.Error($"the evaluation needs one {nameof(FaultCodeContext)}.")); + unknown.Interpretation = new EvaluationMetricInterpretation( + EvaluationRating.Inconclusive, + failed: false, + reason: "nothing named the codes access path 1 resolved."); + + return ValueTask.FromResult(new EvaluationResult(unknown)); + } + + string reply = modelResponse.Text; + + List missing = [.. context.Codes.Where(code => !reply.Contains(code, StringComparison.Ordinal))]; + HashSet resolved = new(context.Codes, StringComparer.Ordinal); + List invented = + [ + .. _codeShape.Matches(reply) + .Select(match => match.Value) + .Where(cited => !resolved.Contains(cited)) + .Distinct(StringComparer.Ordinal), + ]; + + bool accurate = missing.Count == 0 && invented.Count == 0; + BooleanMetric metric = new(FaultCodeAccuracyMetricName, accurate, Explain(missing, invented)); + metric.Interpretation = new EvaluationMetricInterpretation( + accurate ? EvaluationRating.Exceptional : EvaluationRating.Unacceptable, + failed: !accurate, + reason: metric.Reason); + + return ValueTask.FromResult(new EvaluationResult(metric)); } - if (invented.Count > 0) + private static string Explain(List missing, List invented) { - parts.Add($"the reply states {string.Join(", ", invented)}, which the lookup did not resolve."); + if (missing.Count == 0 && invented.Count == 0) + { + return "the reply states every code the lookup resolved, and no other."; + } + + List parts = []; + if (missing.Count > 0) + { + parts.Add($"the reply omits {string.Join(", ", missing)}."); + } + + if (invented.Count > 0) + { + parts.Add($"the reply states {string.Join(", ", invented)}, which the lookup did not resolve."); + } + + return string.Join(" ", parts); } - - return string.Join(" ", parts); } } diff --git a/src/AgentCore.Application/Evaluation/InMemoryEvaluationScorePublisher.cs b/src/AgentCore.Application/Evaluation/InMemoryEvaluationScorePublisher.cs index db94ceb7..36700661 100644 --- a/src/AgentCore.Application/Evaluation/InMemoryEvaluationScorePublisher.cs +++ b/src/AgentCore.Application/Evaluation/InMemoryEvaluationScorePublisher.cs @@ -1,49 +1,50 @@ using AgentCore.Application.Ports; -namespace AgentCore.Application.Evaluation; - -/// -/// The publisher that keeps every score in a list. -/// -/// -/// -/// This is the default the seam ships with. It writes nowhere, so a host that registers nothing else -/// still runs, and the offline golden set in tests/AgentCore.Evals reads its scores back -/// without a sink. -/// -/// -/// The list grows without a bound, so a long-running host replaces this publisher rather than -/// keeping it. Scores may arrive from several turns at once, so the append takes a lock. -/// -/// -public sealed class InMemoryEvaluationScorePublisher : IEvaluationScorePublisher +namespace AgentCore.Application.Evaluation { - private readonly Lock _gate = new(); - private readonly List _scores = []; - - /// Gets the scores this publisher holds, in the order they arrived. - public IReadOnlyList Scores + /// + /// The publisher that keeps every score in a list. + /// + /// + /// + /// This is the default the seam ships with. It writes nowhere, so a host that registers nothing else + /// still runs, and the offline golden set in tests/AgentCore.Evals reads its scores back + /// without a sink. + /// + /// + /// The list grows without a bound, so a long-running host replaces this publisher rather than + /// keeping it. Scores may arrive from several turns at once, so the append takes a lock. + /// + /// + public sealed class InMemoryEvaluationScorePublisher : IEvaluationScorePublisher { - get + private readonly Lock _gate = new(); + private readonly List _scores = []; + + /// Gets the scores this publisher holds, in the order they arrived. + public IReadOnlyList Scores { - lock (_gate) + get { - return [.. _scores]; + lock (_gate) + { + return [.. _scores]; + } } } - } - - /// - public ValueTask PublishAsync(EvaluationScore score, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(score); - cancellationToken.ThrowIfCancellationRequested(); - lock (_gate) + /// + public ValueTask PublishAsync(EvaluationScore score, CancellationToken cancellationToken = default) { - _scores.Add(score); - } + ArgumentNullException.ThrowIfNull(score); + cancellationToken.ThrowIfCancellationRequested(); + + lock (_gate) + { + _scores.Add(score); + } - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } } diff --git a/src/AgentCore.Application/Evaluation/ModerationEvaluatorFactory.cs b/src/AgentCore.Application/Evaluation/ModerationEvaluatorFactory.cs index 1f0e19c1..38eaa35c 100644 --- a/src/AgentCore.Application/Evaluation/ModerationEvaluatorFactory.cs +++ b/src/AgentCore.Application/Evaluation/ModerationEvaluatorFactory.cs @@ -4,59 +4,60 @@ using AgentCore.Application.Providers; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// Builds the moderation evaluator the document names, from the adapters the host registered. -/// -/// -/// -/// This is the moderation mirror of CompositeKnowledgeStoreFactory, and it takes the same -/// shape: the host lists the vendors it supports once, providers.moderation.kind picks one, -/// and a document that changes vendors changes no code. -/// -/// -/// A document that names no providers.moderation gets no evaluator, and a host that -/// registered no adapter for a kind the document does name fails the start. Both are deliberate: the -/// first is a document that asked for nothing, and the second is a document that asked for something -/// this host cannot give. -/// -/// -public static class ModerationEvaluatorFactory +namespace AgentCore.Application.Evaluation { - /// What this seam conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam Seam = - new("providers.moderation", "/providers/moderation/kind", "options.UseModeration(...)", "endpoints"); - - /// Builds the evaluator providers.moderation names, or none. - /// The loaded document. - /// The chain a credential resolves through, or . - /// The vendors this host supports. - /// Cancels the build. - /// - /// The evaluator, or when the document names no moderation provider. - /// - /// The configuration or the adapters are . - /// - /// The document names a kind no adapter serves, or a kind two adapters answer to. - /// - public static async ValueTask CreateAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) + /// + /// Builds the moderation evaluator the document names, from the adapters the host registered. + /// + /// + /// + /// This is the moderation mirror of CompositeKnowledgeStoreFactory, and it takes the same + /// shape: the host lists the vendors it supports once, providers.moderation.kind picks one, + /// and a document that changes vendors changes no code. + /// + /// + /// A document that names no providers.moderation gets no evaluator, and a host that + /// registered no adapter for a kind the document does name fails the start. Both are deliberate: the + /// first is a document that asked for nothing, and the second is a document that asked for something + /// this host cannot give. + /// + /// + public static class ModerationEvaluatorFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + /// What this seam conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam Seam = + new("providers.moderation", "/providers/moderation/kind", "options.UseModeration(...)", "endpoints"); - if (configuration.Providers?.Moderation is not { } entry) + /// Builds the evaluator providers.moderation names, or none. + /// The loaded document. + /// The chain a credential resolves through, or . + /// The vendors this host supports. + /// Cancels the build. + /// + /// The evaluator, or when the document names no moderation provider. + /// + /// The configuration or the adapters are . + /// + /// The document names a kind no adapter serves, or a kind two adapters answer to. + /// + public static async ValueTask CreateAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - // The document asked for nothing, so no adapter is asked to build anything and no - // credential is read. A host that registers a vendor still starts with no key. - return null; - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); - return await adapter.CreateAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + if (configuration.Providers?.Moderation is not { } entry) + { + // The document asked for nothing, so no adapter is asked to build anything and no + // credential is read. A host that registers a vendor still starts with no key. + return null; + } + + IModerationAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam); + return await adapter.CreateAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.Application/Evaluation/ModerationVerdict.cs b/src/AgentCore.Application/Evaluation/ModerationVerdict.cs index 279921e3..723f090c 100644 --- a/src/AgentCore.Application/Evaluation/ModerationVerdict.cs +++ b/src/AgentCore.Application/Evaluation/ModerationVerdict.cs @@ -1,113 +1,114 @@ using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// What the moderation endpoint answered about one piece of text. -/// -/// -/// -/// Decision D13 makes the moderation port and refuses a second one, so the -/// verdict has to travel on the result the evaluator already returns. This type is that carrier. The -/// moderation adapter attaches it to its metric, and the caller reads it back through -/// . Nothing between the two parses a metric name, a reason, or a metadata -/// string. -/// -/// -/// It lives in Application/Evaluation/ and not beside the adapter, for two reasons. D3 forbids -/// AgentCore.Application from referencing AgentCore.Infrastructure, and the code that -/// records a flagged turn sits in , which is in Application. And -/// D13 promises that replacing OpenAI with a self-hosted classifier behind the same -/// is a one-file change, which holds only while this type names no vendor. -/// -/// -/// The categories keep the order the endpoint returned them in, because -/// promises that order to a reader -/// of the audit chain. Nothing here sorts them, renames them, or checks them against a list: the -/// taxonomy belongs to the endpoint and it is open. A category this library never named still -/// reaches the chain. -/// -/// -/// is the shape this follows: an that -/// carries a typed payload beside a metric. -/// -/// -public sealed class ModerationVerdict : EvaluationContext +namespace AgentCore.Application.Evaluation { - /// The name this verdict carries on the metric. - public const string ModerationVerdictName = "Moderation Verdict"; - - /// The text a verdict with no flagged category carries as its content. - public const string NothingFlagged = "the endpoint flagged no category."; - - /// Builds a verdict from what the endpoint answered. - /// Whether the endpoint flagged the text. - /// - /// The categories the endpoint flagged, in the order it returned them. It is empty when the - /// endpoint flagged nothing. - /// - /// The categories are . - /// - /// The endpoint owns , and this type never recomputes it from - /// . A model that flags text without naming a category still reads - /// as flagged, and a threshold the vendor moves does not drift the answer. - /// - public ModerationVerdict(bool flagged, IEnumerable categories) - : this(flagged, Materialize(categories)) - { - } - - private ModerationVerdict(bool flagged, string[] categories) - : base(ModerationVerdictName, categories.Length == 0 ? NothingFlagged : string.Join(", ", categories)) - { - Flagged = flagged; - Categories = categories; - } - - /// Gets whether the endpoint flagged the text. - public bool Flagged { get; } - - /// Gets the categories the endpoint flagged, in the order it returned them. - public IReadOnlyList Categories { get; } - - /// Reads the verdict one evaluation carries. - /// What the moderation evaluator returned. - /// The verdict, when one metric carries it. - /// when the endpoint answered. - /// The result is . + /// + /// What the moderation endpoint answered about one piece of text. + /// /// /// - /// A verdict is present only when the endpoint answered. An evaluation that failed, timed - /// out, or read a body it could not parse carries an inconclusive metric and no verdict, so this - /// answers . The caller then knows the text is unchecked, which is a - /// different fact from "the endpoint checked it and flagged nothing". + /// Decision D13 makes the moderation port and refuses a second one, so the + /// verdict has to travel on the result the evaluator already returns. This type is that carrier. The + /// moderation adapter attaches it to its metric, and the caller reads it back through + /// . Nothing between the two parses a metric name, a reason, or a metadata + /// string. + /// + /// + /// It lives in Application/Evaluation/ and not beside the adapter, for two reasons. D3 forbids + /// AgentCore.Application from referencing AgentCore.Infrastructure, and the code that + /// records a flagged turn sits in , which is in Application. And + /// D13 promises that replacing OpenAI with a self-hosted classifier behind the same + /// is a one-file change, which holds only while this type names no vendor. + /// + /// + /// The categories keep the order the endpoint returned them in, because + /// promises that order to a reader + /// of the audit chain. Nothing here sorts them, renames them, or checks them against a list: the + /// taxonomy belongs to the endpoint and it is open. A category this library never named still + /// reaches the chain. /// /// - /// It searches every metric and names none, so the caller compiles against this assembly alone - /// and never against the adapter that produced the result. + /// is the shape this follows: an that + /// carries a typed payload beside a metric. /// /// - public static bool TryRead(EvaluationResult result, out ModerationVerdict? verdict) + public sealed class ModerationVerdict : EvaluationContext { - ArgumentNullException.ThrowIfNull(result); + /// The name this verdict carries on the metric. + public const string ModerationVerdictName = "Moderation Verdict"; - foreach (EvaluationMetric metric in result.Metrics.Values) + /// The text a verdict with no flagged category carries as its content. + public const string NothingFlagged = "the endpoint flagged no category."; + + /// Builds a verdict from what the endpoint answered. + /// Whether the endpoint flagged the text. + /// + /// The categories the endpoint flagged, in the order it returned them. It is empty when the + /// endpoint flagged nothing. + /// + /// The categories are . + /// + /// The endpoint owns , and this type never recomputes it from + /// . A model that flags text without naming a category still reads + /// as flagged, and a threshold the vendor moves does not drift the answer. + /// + public ModerationVerdict(bool flagged, IEnumerable categories) + : this(flagged, Materialize(categories)) + { + } + + private ModerationVerdict(bool flagged, string[] categories) + : base(ModerationVerdictName, categories.Length == 0 ? NothingFlagged : string.Join(", ", categories)) + { + Flagged = flagged; + Categories = categories; + } + + /// Gets whether the endpoint flagged the text. + public bool Flagged { get; } + + /// Gets the categories the endpoint flagged, in the order it returned them. + public IReadOnlyList Categories { get; } + + /// Reads the verdict one evaluation carries. + /// What the moderation evaluator returned. + /// The verdict, when one metric carries it. + /// when the endpoint answered. + /// The result is . + /// + /// + /// A verdict is present only when the endpoint answered. An evaluation that failed, timed + /// out, or read a body it could not parse carries an inconclusive metric and no verdict, so this + /// answers . The caller then knows the text is unchecked, which is a + /// different fact from "the endpoint checked it and flagged nothing". + /// + /// + /// It searches every metric and names none, so the caller compiles against this assembly alone + /// and never against the adapter that produced the result. + /// + /// + public static bool TryRead(EvaluationResult result, out ModerationVerdict? verdict) { - if (metric.Context?.TryGetValue(ModerationVerdictName, out EvaluationContext? context) == true - && context is ModerationVerdict found) + ArgumentNullException.ThrowIfNull(result); + + foreach (EvaluationMetric metric in result.Metrics.Values) { - verdict = found; - return true; + if (metric.Context?.TryGetValue(ModerationVerdictName, out EvaluationContext? context) == true + && context is ModerationVerdict found) + { + verdict = found; + return true; + } } - } - verdict = null; - return false; - } + verdict = null; + return false; + } - private static string[] Materialize(IEnumerable categories) - { - ArgumentNullException.ThrowIfNull(categories); - return [.. categories]; + private static string[] Materialize(IEnumerable categories) + { + ArgumentNullException.ThrowIfNull(categories); + return [.. categories]; + } } } diff --git a/src/AgentCore.Application/Evaluation/PromptModerator.cs b/src/AgentCore.Application/Evaluation/PromptModerator.cs index 37c0fdfd..2bac8dea 100644 --- a/src/AgentCore.Application/Evaluation/PromptModerator.cs +++ b/src/AgentCore.Application/Evaluation/PromptModerator.cs @@ -1,107 +1,108 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Evaluation; - -/// -/// Reads which moderation categories flagged what the caller said. -/// -/// -/// -/// The agent moderates the caller's words BEFORE the model runs, and refuses the turn when the -/// endpoint flags them. That is a decision of the owner, taken on 2026-08-13, and it departs from -/// section 11 item 11, which asked for the agent's reply to be moderated and recorded instead. -/// Reply moderation is withdrawn, not deferred: the reply comes from a model that already -/// carries safety training, so a second check of its own output buys little. The caller's words are -/// the text nothing else has filtered. -/// -/// -/// D13 makes the moderation port and refuses a second one, so this type is -/// not a port. It is the one place that turns an into the fact the -/// audit chain records, and it exists so that holds no registry -/// key, no metric name, and no decode. -/// -/// -/// D13 also says moderation checks EVERY turn, because the endpoint is free at any volume and counts -/// against no usage limit: "Sampling buys nothing when the conversation is free." Nothing here reads -/// , and nothing should. -/// -/// -/// Nothing here catches. A timeout, a log line, and the decision to answer anyway all belong -/// to , which owns the turn and the clock. This type calls the -/// evaluator and reads the answer. -/// -/// -public sealed class PromptModerator +namespace AgentCore.Application.Evaluation { - /// The name the composition root registers the moderation evaluator under. - public const string ModerationEvaluatorName = "moderation"; + /// + /// Reads which moderation categories flagged what the caller said. + /// + /// + /// + /// The agent moderates the caller's words BEFORE the model runs, and refuses the turn when the + /// endpoint flags them. That is a decision of the owner, taken on 2026-08-13, and it departs from + /// section 11 item 11, which asked for the agent's reply to be moderated and recorded instead. + /// Reply moderation is withdrawn, not deferred: the reply comes from a model that already + /// carries safety training, so a second check of its own output buys little. The caller's words are + /// the text nothing else has filtered. + /// + /// + /// D13 makes the moderation port and refuses a second one, so this type is + /// not a port. It is the one place that turns an into the fact the + /// audit chain records, and it exists so that holds no registry + /// key, no metric name, and no decode. + /// + /// + /// D13 also says moderation checks EVERY turn, because the endpoint is free at any volume and counts + /// against no usage limit: "Sampling buys nothing when the conversation is free." Nothing here reads + /// , and nothing should. + /// + /// + /// Nothing here catches. A timeout, a log line, and the decision to answer anyway all belong + /// to , which owns the turn and the clock. This type calls the + /// evaluator and reads the answer. + /// + /// + public sealed class PromptModerator + { + /// The name the composition root registers the moderation evaluator under. + public const string ModerationEvaluatorName = "moderation"; - private static readonly IReadOnlyList NothingFlagged = []; + private static readonly IReadOnlyList NothingFlagged = []; - private readonly IEvaluator _evaluator; + private readonly IEvaluator _evaluator; - /// Builds a moderator over one evaluator. - /// The evaluator that reaches the moderation endpoint. - /// The evaluator is . - public PromptModerator(IEvaluator evaluator) - { - ArgumentNullException.ThrowIfNull(evaluator); - _evaluator = evaluator; - } + /// Builds a moderator over one evaluator. + /// The evaluator that reaches the moderation endpoint. + /// The evaluator is . + public PromptModerator(IEvaluator evaluator) + { + ArgumentNullException.ThrowIfNull(evaluator); + _evaluator = evaluator; + } - /// Builds a moderator over the evaluator the host registered, or none. - /// The registry the composition root filled. - /// - /// The moderator, or when the registry holds no evaluator under - /// . - /// - /// The registry is . - /// - /// A host that registers no moderation evaluator runs every turn and refuses none, exactly as a - /// host that binds no audit sink still answers a conversation. Moderation needs a vendor account, and a - /// library that refused to run without one would be unusable in a test. - /// - public static PromptModerator? FromRegistry(EvaluatorRegistry registry) - { - ArgumentNullException.ThrowIfNull(registry); + /// Builds a moderator over the evaluator the host registered, or none. + /// The registry the composition root filled. + /// + /// The moderator, or when the registry holds no evaluator under + /// . + /// + /// The registry is . + /// + /// A host that registers no moderation evaluator runs every turn and refuses none, exactly as a + /// host that binds no audit sink still answers a conversation. Moderation needs a vendor account, and a + /// library that refused to run without one would be unusable in a test. + /// + public static PromptModerator? FromRegistry(EvaluatorRegistry registry) + { + ArgumentNullException.ThrowIfNull(registry); - return registry.TryGetEvaluator(ModerationEvaluatorName, out IEvaluator? evaluator) && evaluator is not null - ? new PromptModerator(evaluator) - : null; - } + return registry.TryGetEvaluator(ModerationEvaluatorName, out IEvaluator? evaluator) && evaluator is not null + ? new PromptModerator(evaluator) + : null; + } - /// Reads which categories flagged what the caller said. - /// The words the caller spoke this turn. - /// Cancels the endpoint conversation. - /// - /// The categories, in the order the endpoint returned them, or an empty list when the endpoint - /// flagged nothing. - /// - /// The text is . - /// - /// An endpoint that did not answer reads as "nothing flagged", and the turn goes on. That - /// is the fail-open rule, and it is deliberate: a vendor outage must not refuse every caller on - /// a support line. answers for a - /// failed evaluation, so the two cases meet here and the caller of this method cannot tell them - /// apart. counts them apart on a metric instead. - /// - public async ValueTask> FlaggedCategoriesAsync( - string callerText, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(callerText); + /// Reads which categories flagged what the caller said. + /// The words the caller spoke this turn. + /// Cancels the endpoint conversation. + /// + /// The categories, in the order the endpoint returned them, or an empty list when the endpoint + /// flagged nothing. + /// + /// The text is . + /// + /// An endpoint that did not answer reads as "nothing flagged", and the turn goes on. That + /// is the fail-open rule, and it is deliberate: a vendor outage must not refuse every caller on + /// a support line. answers for a + /// failed evaluation, so the two cases meet here and the caller of this method cannot tell them + /// apart. counts them apart on a metric instead. + /// + public async ValueTask> FlaggedCategoriesAsync( + string callerText, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(callerText); - // The IEvaluator signature carries the text under test on the response, so the caller's words - // ride there. The evaluator moderates whatever text it is given and never asks who said it. - ChatResponse spoken = new(new ChatMessage(ChatRole.User, callerText)); + // The IEvaluator signature carries the text under test on the response, so the caller's words + // ride there. The evaluator moderates whatever text it is given and never asks who said it. + ChatResponse spoken = new(new ChatMessage(ChatRole.User, callerText)); - EvaluationResult result = await _evaluator - .EvaluateAsync([], spoken, cancellationToken: cancellationToken) - .ConfigureAwait(false); + EvaluationResult result = await _evaluator + .EvaluateAsync([], spoken, cancellationToken: cancellationToken) + .ConfigureAwait(false); - return ModerationVerdict.TryRead(result, out ModerationVerdict? verdict) && verdict is { Flagged: true } - ? verdict.Categories - : NothingFlagged; + return ModerationVerdict.TryRead(result, out ModerationVerdict? verdict) && verdict is { Flagged: true } + ? verdict.Categories + : NothingFlagged; + } } } diff --git a/src/AgentCore.Application/Evaluation/RetrievedDocumentsContext.cs b/src/AgentCore.Application/Evaluation/RetrievedDocumentsContext.cs index f510758c..5dc99ac3 100644 --- a/src/AgentCore.Application/Evaluation/RetrievedDocumentsContext.cs +++ b/src/AgentCore.Application/Evaluation/RetrievedDocumentsContext.cs @@ -1,52 +1,53 @@ using Microsoft.Extensions.AI.Evaluation; using System.Runtime.CompilerServices; -namespace AgentCore.Application.Evaluation; - -/// -/// The documents one search returned, and the documents the golden row expects. -/// -public sealed class RetrievedDocumentsContext : EvaluationContext +namespace AgentCore.Application.Evaluation { - /// The name this context carries. - public const string RetrievedDocumentsContextName = "Retrieved Documents"; - - /// Builds a context from the expected documents and the returned documents. - /// The document ids that answer the query. - /// The document ids the search returned, best first. - /// Either list is . - public RetrievedDocumentsContext(IEnumerable expected, IEnumerable retrieved) - : this(Materialize(expected), Materialize(retrieved)) - { - } - - private RetrievedDocumentsContext(string[] expected, string[] retrieved) - : base(RetrievedDocumentsContextName, Describe(expected, retrieved)) + /// + /// The documents one search returned, and the documents the golden row expects. + /// + public sealed class RetrievedDocumentsContext : EvaluationContext { - Expected = expected; - Retrieved = retrieved; - } + /// The name this context carries. + public const string RetrievedDocumentsContextName = "Retrieved Documents"; + + /// Builds a context from the expected documents and the returned documents. + /// The document ids that answer the query. + /// The document ids the search returned, best first. + /// Either list is . + public RetrievedDocumentsContext(IEnumerable expected, IEnumerable retrieved) + : this(Materialize(expected), Materialize(retrieved)) + { + } - /// Gets the document ids that answer the query. - public IReadOnlyList Expected { get; } + private RetrievedDocumentsContext(string[] expected, string[] retrieved) + : base(RetrievedDocumentsContextName, Describe(expected, retrieved)) + { + Expected = expected; + Retrieved = retrieved; + } - /// Gets the document ids the search returned, best first. - public IReadOnlyList Retrieved { get; } + /// Gets the document ids that answer the query. + public IReadOnlyList Expected { get; } - private static string Describe(string[] expected, string[] retrieved) - => $"expected: {Join(expected)}; retrieved: {Join(retrieved)}"; + /// Gets the document ids the search returned, best first. + public IReadOnlyList Retrieved { get; } - private static string Join(string[] ids) => ids.Length == 0 ? "none" : string.Join(", ", ids); + private static string Describe(string[] expected, string[] retrieved) + { + return $"expected: {Join(expected)}; retrieved: {Join(retrieved)}"; + } - private static string[] Materialize( - IEnumerable ids, - [CallerArgumentExpression(nameof(ids))] string parameterName = "") - { - if (ids is null) + private static string Join(string[] ids) { - throw new ArgumentNullException(parameterName); + return ids.Length == 0 ? "none" : string.Join(", ", ids); } - return [.. ids]; + private static string[] Materialize( + IEnumerable ids, + [CallerArgumentExpression(nameof(ids))] string parameterName = "") + { + return ids is null ? throw new ArgumentNullException(parameterName) : [.. ids]; + } } } diff --git a/src/AgentCore.Application/Knowledge/ClaimedProbe.cs b/src/AgentCore.Application/Knowledge/ClaimedProbe.cs index f30888b8..3022306b 100644 --- a/src/AgentCore.Application/Knowledge/ClaimedProbe.cs +++ b/src/AgentCore.Application/Knowledge/ClaimedProbe.cs @@ -1,9 +1,10 @@ using AgentCore.Application.Runtime; -namespace AgentCore.Application.Knowledge; - -/// The one probe this turn won, and the facet it is about to drop. -/// The conversation's ambiguity holder. -/// The latch this caller won. Every way out publishes or fails it. -/// The facet the probe drops, and charges. -internal sealed record ClaimedProbe(Clarifications Clarifications, Clarifications.Probe Probe, string Facet); +namespace AgentCore.Application.Knowledge +{ + /// The one probe this turn won, and the facet it is about to drop. + /// The conversation's ambiguity holder. + /// The latch this caller won. Every way out publishes or fails it. + /// The facet the probe drops, and charges. + internal sealed record ClaimedProbe(Clarifications Clarifications, Clarifications.Probe Probe, string Facet); +} diff --git a/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs b/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs index ccf87e40..0b6e4dba 100644 --- a/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs +++ b/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs @@ -4,131 +4,132 @@ using AgentCore.Application.Providers; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Knowledge; - -/// -/// The composite a config-driven host binds its knowledge port through. It routes -/// providers.knowledge.kind to the whose kind matches. -/// -public static class CompositeKnowledgeStoreFactory +namespace AgentCore.Application.Knowledge { - /// What the knowledge field conversations itself, so the shared selector writes its failures. - private static readonly VendorSeam KnowledgeSeam = - new("providers.knowledge.kind", "/providers/knowledge/kind", "options.UseKnowledgeStores(...)", "stores"); - - /// Builds the knowledge port the document names. - public static async ValueTask CreateAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - IEmbeddingGenerator>? embeddings, - bool scopeDeclared, - bool requireScope, - CancellationToken cancellationToken = default) + /// + /// The composite a config-driven host binds its knowledge port through. It routes + /// providers.knowledge.kind to the whose kind matches. + /// + public static class CompositeKnowledgeStoreFactory { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); - - // No invented entry. AgentCore knows no collection name, no vendor and no payload shape, so a - // document that reads a knowledge base has to say what it reads. Standing one up from - // defaults would guess all three and fail somewhere further in, against a store nobody named. - var entry = configuration.Providers?.Knowledge ?? throw Fail( - "/providers/knowledge", - "an agent declares a knowledge: block and this document has no providers.knowledge, so " - + "there is no store to read and no payload shape to read it with. Write the block, or " - + "remove knowledge: from every agent."); - - if (entry.Mapper is null && entry.Fields?.Body is not { Length: > 0 }) + /// What the knowledge field conversations itself, so the shared selector writes its failures. + private static readonly VendorSeam KnowledgeSeam = + new("providers.knowledge.kind", "/providers/knowledge/kind", "options.UseKnowledgeStores(...)", "stores"); + + /// Builds the knowledge port the document names. + public static async ValueTask CreateAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + IEmbeddingGenerator>? embeddings, + bool scopeDeclared, + bool requireScope, + CancellationToken cancellationToken = default) { - throw Fail( - "/providers/knowledge/fields/body", - "providers.knowledge names no mapper, so the built-in fields: mapping reads every card, " - + "and it maps no body. AgentCore has no default field names: the card the model reads " - + "would be empty on every turn. Map providers.knowledge.fields.body to the payload " - + "field holding the text, or name an IKnowledgePointMapper with mapper:."); + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); + + // No invented entry. AgentCore knows no collection name, no vendor and no payload shape, so a + // document that reads a knowledge base has to say what it reads. Standing one up from + // defaults would guess all three and fail somewhere further in, against a store nobody named. + KnowledgeProviderConfiguration entry = configuration.Providers?.Knowledge ?? throw Fail( + "/providers/knowledge", + "an agent declares a knowledge: block and this document has no providers.knowledge, so " + + "there is no store to read and no payload shape to read it with. Write the block, or " + + "remove knowledge: from every agent."); + + if (entry.Mapper is null && entry.Fields?.Body is not { Length: > 0 }) + { + throw Fail( + "/providers/knowledge/fields/body", + "providers.knowledge names no mapper, so the built-in fields: mapping reads every card, " + + "and it maps no body. AgentCore has no default field names: the card the model reads " + + "would be empty on every turn. Map providers.knowledge.fields.body to the payload " + + "field holding the text, or name an IKnowledgePointMapper with mapper:."); + } + + if (scopeDeclared && entry.Scope.Template is not { Length: > 0 }) + { + throw Fail( + "/providers/knowledge/scope/template", + "an agent declares knowledge: { scoped: true } and providers.knowledge.scope names no " + + "template, so AgentCore does not know where this collection keeps its facets. " + + ScopeTemplate.WriteOneAdvice); + } + + if (entry.Mapper is null + && CitationsDeclared(configuration) + && entry.Fields?.Source is not { Length: > 0 } + && entry.Fields?.Locator is not { Length: > 0 }) + { + throw Fail( + "/providers/knowledge/fields/source", + "an agent declares knowledge: { citations: true } and providers.knowledge.fields maps " + + "neither source nor locator, so every citation would be silently empty. Map one of " + + "the two fields, or set citations: false on every agent."); + } + + IKnowledgeStoreAdapter adapter = Resolve(adapters, entry.Kind, scopeDeclared); + + return await adapter + .CreateSearchAsync(entry, secrets, embeddings, requireScope, cancellationToken) + .ConfigureAwait(false); } - if (scopeDeclared && entry.Scope.Template is not { Length: > 0 }) + /// Finds the one adapter providers.knowledge.kind names, and proves it serves. + private static IKnowledgeStoreAdapter Resolve( + IReadOnlyList adapters, + string kind, + bool scopeDeclared) { - throw Fail( - "/providers/knowledge/scope/template", - "an agent declares knowledge: { scoped: true } and providers.knowledge.scope names no " - + "template, so AgentCore does not know where this collection keeps its facets. " - + ScopeTemplate.WriteOneAdvice); + IKnowledgeStoreAdapter adapter = VendorAdapterSelector.Select(kind, adapters, KnowledgeSeam); + + if (!adapter.CanServeSearch) + { + throw Fail( + KnowledgeSeam.Pointer, + $"{KnowledgeSeam.DocumentPath} names kind '{kind}', and that adapter does not serve " + + $"{nameof(IKnowledgeRetrievalPort)}. This host registers {Registered(adapters)}. " + + "Name a kind that serves this port."); + } + + return scopeDeclared && !adapter.CanScope + ? throw Fail( + KnowledgeSeam.Pointer, + $"{KnowledgeSeam.DocumentPath} names kind '{kind}', an agent declares scoped: true, and that " + + "adapter cannot apply a scope. A search that ignores a scope serves every customer " + + "every card. Name a kind that scopes, or set scoped: false on every agent.") + : adapter; } - if (entry.Mapper is null - && CitationsDeclared(configuration) - && entry.Fields?.Source is not { Length: > 0 } - && entry.Fields?.Locator is not { Length: > 0 }) + /// Whether any agent in the document turns citations on, directly or through defaults. + private static bool CitationsDeclared(AgentCoreConfiguration configuration) { - throw Fail( - "/providers/knowledge/fields/source", - "an agent declares knowledge: { citations: true } and providers.knowledge.fields maps " - + "neither source nor locator, so every citation would be silently empty. Map one of " - + "the two fields, or set citations: false on every agent."); + return configuration.Agents is { } agents + && (agents.Defaults?.Knowledge?.Citations == true + || agents.Items.Any(agent => agent.Knowledge?.Citations == true)); } - var adapter = Resolve(adapters, entry.Kind, scopeDeclared); - - return await adapter - .CreateSearchAsync(entry, secrets, embeddings, requireScope, cancellationToken) - .ConfigureAwait(false); - } - - /// Finds the one adapter providers.knowledge.kind names, and proves it serves. - private static IKnowledgeStoreAdapter Resolve( - IReadOnlyList adapters, - string kind, - bool scopeDeclared) - { - var adapter = VendorAdapterSelector.Select(kind, adapters, KnowledgeSeam); - - if (!adapter.CanServeSearch) + /// Writes the registered kinds, so a failure names what the host does register. + private static string Registered(IReadOnlyList adapters) { - throw Fail( - KnowledgeSeam.Pointer, - $"{KnowledgeSeam.DocumentPath} names kind '{kind}', and that adapter does not serve " - + $"{nameof(IKnowledgeRetrievalPort)}. This host registers {Registered(adapters)}. " - + "Name a kind that serves this port."); + List kinds = [.. adapters + .Select(adapter => adapter.Kind) + .Distinct(StringComparer.OrdinalIgnoreCase) + .Select(kind => "'" + kind + "'")]; + + return kinds.Count == 0 ? "no adapter" : string.Join(", ", kinds); } - if (scopeDeclared && !adapter.CanScope) + /// Builds the one exception every failure of this factory uses. + private static ConfigurationLoadException Fail(string pointer, string message) { - throw Fail( - KnowledgeSeam.Pointer, - $"{KnowledgeSeam.DocumentPath} names kind '{kind}', an agent declares scoped: true, and that " - + "adapter cannot apply a scope. A search that ignores a scope serves every customer " - + "every card. Name a kind that scopes, or set scoped: false on every agent."); + return new(new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.ReferenceResolution, + }); } - - return adapter; } - - /// Whether any agent in the document turns citations on, directly or through defaults. - private static bool CitationsDeclared(AgentCoreConfiguration configuration) - => configuration.Agents is { } agents - && (agents.Defaults?.Knowledge?.Citations == true - || agents.Items.Any(agent => agent.Knowledge?.Citations == true)); - - /// Writes the registered kinds, so a failure names what the host does register. - private static string Registered(IReadOnlyList adapters) - { - var kinds = adapters - .Select(adapter => adapter.Kind) - .Distinct(StringComparer.OrdinalIgnoreCase) - .Select(kind => "'" + kind + "'") - .ToList(); - - return kinds.Count == 0 ? "no adapter" : string.Join(", ", kinds); - } - - /// Builds the one exception every failure of this factory uses. - private static ConfigurationLoadException Fail(string pointer, string message) - => new(new ConfigurationError - { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.ReferenceResolution, - }); } diff --git a/src/AgentCore.Application/Knowledge/FacetFilterProvider.cs b/src/AgentCore.Application/Knowledge/FacetFilterProvider.cs index dd2e1b4e..e47f8222 100644 --- a/src/AgentCore.Application/Knowledge/FacetFilterProvider.cs +++ b/src/AgentCore.Application/Knowledge/FacetFilterProvider.cs @@ -3,69 +3,72 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Knowledge; - -/// -/// Puts a filters argument on whichever search function the inner provider offers. -/// -internal sealed class FacetFilterProvider( - AIContextProvider innerProvider, - IReadOnlyList? facets, - KnowledgeSearch.Core core) - : AIContextProvider +namespace AgentCore.Application.Knowledge { - private readonly AIContextProvider _inner = innerProvider - ?? throw new ArgumentNullException(nameof(innerProvider)); + /// + /// Puts a filters argument on whichever search function the inner provider offers. + /// + internal sealed class FacetFilterProvider( + AIContextProvider innerProvider, + IReadOnlyList? facets, + KnowledgeSearch.Core core) + : AIContextProvider + { + private readonly AIContextProvider _inner = innerProvider + ?? throw new ArgumentNullException(nameof(innerProvider)); - private readonly IReadOnlyList? _facets = facets; + private readonly IReadOnlyList? _facets = facets; - private readonly KnowledgeSearch.Core _core = core - ?? throw new ArgumentNullException(nameof(core)); + private readonly KnowledgeSearch.Core _core = core + ?? throw new ArgumentNullException(nameof(core)); - /// - public override IReadOnlyList StateKeys => _inner.StateKeys; + /// + public override IReadOnlyList StateKeys => _inner.StateKeys; - /// - public override object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); + /// + public override object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); - return serviceType.IsInstanceOfType(this) && serviceKey is null - ? this - : _inner.GetService(serviceType, serviceKey); - } + return serviceType.IsInstanceOfType(this) && serviceKey is null + ? this + : _inner.GetService(serviceType, serviceKey); + } - /// - protected override async ValueTask InvokingCoreAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - HashSet? existing = context.AIContext.Tools is { } input - ? [.. input] - : null; + /// + protected override async ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + HashSet? existing = context.AIContext.Tools is { } input + ? [.. input] + : null; - var provided = await _inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); + AIContext provided = await _inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); + + if (provided.Tools is not { } tools) + { + return provided; + } + + List wrapped = []; + + foreach (AITool tool in tools) + { + wrapped.Add(tool is AIFunction function && existing?.Contains(tool) is not true + ? new FacetFilteredSearch(function, _facets, _core) + : tool); + } + + provided.Tools = wrapped; - if (provided.Tools is not { } tools) - { return provided; } - List wrapped = []; - - foreach (var tool in tools) + /// + protected override ValueTask InvokedCoreAsync( + InvokedContext context, CancellationToken cancellationToken = default) { - wrapped.Add(tool is AIFunction function && existing?.Contains(tool) is not true - ? new FacetFilteredSearch(function, _facets, _core) - : tool); + return _inner.InvokedAsync(context, cancellationToken); } - - provided.Tools = wrapped; - - return provided; } - - /// - protected override ValueTask InvokedCoreAsync( - InvokedContext context, CancellationToken cancellationToken = default) - => _inner.InvokedAsync(context, cancellationToken); } diff --git a/src/AgentCore.Application/Knowledge/FacetFilterReader.cs b/src/AgentCore.Application/Knowledge/FacetFilterReader.cs index 2cbd9c1b..c8466e01 100644 --- a/src/AgentCore.Application/Knowledge/FacetFilterReader.cs +++ b/src/AgentCore.Application/Knowledge/FacetFilterReader.cs @@ -4,76 +4,79 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Knowledge; - -/// -/// Reads the filters argument into the facets one search narrows by. -/// -internal static class FacetFilterReader +namespace AgentCore.Application.Knowledge { - /// Reads the argument, keeping only the facets the document declared. - /// What the model called the search tool with. - /// What scope.filterable declared. - /// The facet key to value, as the model wrote it. Empty when the argument named none, or none survived. - /// A required argument is . - internal static IReadOnlyDictionary Read( - AIFunctionArguments arguments, - IReadOnlyList facets) + /// + /// Reads the filters argument into the facets one search narrows by. + /// + internal static class FacetFilterReader { - ArgumentNullException.ThrowIfNull(arguments); - ArgumentNullException.ThrowIfNull(facets); + /// Reads the argument, keeping only the facets the document declared. + /// What the model called the search tool with. + /// What scope.filterable declared. + /// The facet key to value, as the model wrote it. Empty when the argument named none, or none survived. + /// A required argument is . + internal static IReadOnlyDictionary Read( + AIFunctionArguments arguments, + IReadOnlyList facets) + { + ArgumentNullException.ThrowIfNull(arguments); + ArgumentNullException.ThrowIfNull(facets); - Dictionary read = new(StringComparer.Ordinal); + Dictionary read = new(StringComparer.Ordinal); - if (!arguments.TryGetValue(FacetFilterSchema.ArgumentName, out var raw) || raw is null) - { - return read; - } + if (!arguments.TryGetValue(FacetFilterSchema.ArgumentName, out object? raw) || raw is null) + { + return read; + } - if (Array(raw) is not { } entries) - { - return read; - } + if (Array(raw) is not { } entries) + { + return read; + } - foreach (var entry in entries.EnumerateArray()) - { - if (Text(entry, FacetFilterSchema.KeyProperty) is not { Length: > 0 } key - || Text(entry, FacetFilterSchema.ValueProperty) is not { Length: > 0 } value - || !facets.Any(facet => string.Equals(facet.Key, key, StringComparison.Ordinal))) + foreach (JsonElement entry in entries.EnumerateArray()) { - continue; + if (Text(entry, FacetFilterSchema.KeyProperty) is not { Length: > 0 } key + || Text(entry, FacetFilterSchema.ValueProperty) is not { Length: > 0 } value + || !facets.Any(facet => string.Equals(facet.Key, key, StringComparison.Ordinal))) + { + continue; + } + + read[key] = value; } - read[key] = value; + return read; } - return read; - } - - /// The argument as an array, whatever shape the caller handed it in. - private static JsonElement? Array(object raw) - { - var element = raw as JsonElement? ?? Reserialized(raw); + /// The argument as an array, whatever shape the caller handed it in. + private static JsonElement? Array(object raw) + { + JsonElement? element = raw as JsonElement? ?? Reserialized(raw); - return element is { ValueKind: JsonValueKind.Array } array ? array : null; - } + return element is { ValueKind: JsonValueKind.Array } array ? array : null; + } - private static JsonElement? Reserialized(object raw) - { - try + private static JsonElement? Reserialized(object raw) { - return JsonSerializer.SerializeToElement(raw); + try + { + return JsonSerializer.SerializeToElement(raw); + } + catch (NotSupportedException) + { + return null; + } } - catch (NotSupportedException) + + private static string? Text(JsonElement entry, string property) { - return null; + return entry.ValueKind == JsonValueKind.Object + && entry.TryGetProperty(property, out JsonElement value) + && value.ValueKind == JsonValueKind.String + ? value.GetString() + : null; } } - - private static string? Text(JsonElement entry, string property) - => entry.ValueKind == JsonValueKind.Object - && entry.TryGetProperty(property, out var value) - && value.ValueKind == JsonValueKind.String - ? value.GetString() - : null; } diff --git a/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs b/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs index 14dce185..59891259 100644 --- a/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs +++ b/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs @@ -4,103 +4,108 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Knowledge; - -/// -/// Grows the framework's one-string search schema by a filters argument. -/// -internal static class FacetFilterSchema +namespace AgentCore.Application.Knowledge { - /// The argument the model fills to narrow its own search. - internal const string ArgumentName = "filters"; - - /// The key of one filter entry. - internal const string KeyProperty = "key"; - - /// The value of one filter entry. - internal const string ValueProperty = "value"; - - /// Adds the argument to a schema that does not carry it. - /// The schema of the function being wrapped. - /// What scope.filterable declared, in document order. - /// The extended schema. - /// is . - internal static JsonElement Extend( - JsonElement innerSchema, IReadOnlyList facets) + /// + /// Grows the framework's one-string search schema by a filters argument. + /// + internal static class FacetFilterSchema { - ArgumentNullException.ThrowIfNull(facets); - - if (JsonSerializer.Deserialize(innerSchema) is not JsonObject schema) + /// The argument the model fills to narrow its own search. + internal const string ArgumentName = "filters"; + + /// The key of one filter entry. + internal const string KeyProperty = "key"; + + /// The value of one filter entry. + internal const string ValueProperty = "value"; + + /// Adds the argument to a schema that does not carry it. + /// The schema of the function being wrapped. + /// What scope.filterable declared, in document order. + /// The extended schema. + /// is . + internal static JsonElement Extend( + JsonElement innerSchema, IReadOnlyList facets) { - return innerSchema; - } + ArgumentNullException.ThrowIfNull(facets); - if (schema["properties"] is not JsonObject properties) - { - properties = []; - schema["properties"] = properties; - } + if (JsonSerializer.Deserialize(innerSchema) is not JsonObject schema) + { + return innerSchema; + } - properties[ArgumentName] = Argument(facets); + if (schema["properties"] is not JsonObject properties) + { + properties = []; + schema["properties"] = properties; + } - return JsonSerializer.Deserialize(schema); - } + properties[ArgumentName] = Argument(facets); - private static JsonObject Argument(IReadOnlyList facets) - => new() + return JsonSerializer.Deserialize(schema); + } + + private static JsonObject Argument(IReadOnlyList facets) { - ["type"] = "array", - ["description"] = Wording(facets), - ["items"] = new JsonObject + return new() { - ["type"] = "object", - ["properties"] = new JsonObject + ["type"] = "array", + ["description"] = Wording(facets), + ["items"] = new JsonObject { - [KeyProperty] = new JsonObject - { - ["type"] = "string", - ["enum"] = new JsonArray([.. facets.Select(facet => (JsonNode)facet.Key)]), - }, - [ValueProperty] = new JsonObject + ["type"] = "object", + ["properties"] = new JsonObject { - ["type"] = "string", - ["description"] = - "The value, exactly as the cards store it; it is matched exactly. A key " - + "that says how to find its value must be found that way first.", + [KeyProperty] = new JsonObject + { + ["type"] = "string", + ["enum"] = new JsonArray([.. facets.Select(facet => (JsonNode)facet.Key)]), + }, + [ValueProperty] = new JsonObject + { + ["type"] = "string", + ["description"] = + "The value, exactly as the cards store it; it is matched exactly. A key " + + "that says how to find its value must be found that way first.", + }, }, + ["required"] = new JsonArray(KeyProperty, ValueProperty), }, - ["required"] = new JsonArray(KeyProperty, ValueProperty), - }, - }; - - /// - /// The one place a facet's meaning reaches the model. - /// - /// - /// Per key, because JSON Schema hangs no description off an enum member, and the alternative — - /// an anyOf of const branches — is read unevenly across vendors. - /// - private static string Wording(IReadOnlyList facets) - { - StringBuilder wording = new( - "Narrow the search to cards carrying these facet values. Leave it out when the question " - + "names none: a filter that matches nothing returns nothing. The keys are:"); + }; + } - foreach (var facet in facets) + /// + /// The one place a facet's meaning reaches the model. + /// + /// + /// Per key, because JSON Schema hangs no description off an enum member, and the alternative — + /// an anyOf of const branches — is read unevenly across vendors. + /// + private static string Wording(IReadOnlyList facets) { - wording.Append("\n- ").Append(facet.Key).Append(": ").Append(facet.Description); + StringBuilder wording = new( + "Narrow the search to cards carrying these facet values. Leave it out when the question " + + "names none: a filter that matches nothing returns nothing. The keys are:"); - if (facet.Resolve is { } resolve) + foreach (KnowledgeFilterableFacetConfiguration facet in facets) { - wording.Append(' ').Append(Recipe(resolve)); + _ = wording.Append("\n- ").Append(facet.Key).Append(": ").Append(facet.Description); + + if (facet.Resolve is { } resolve) + { + _ = wording.Append(' ').Append(Recipe(resolve)); + } } + + return wording.ToString(); } - return wording.ToString(); + private static string Recipe(KnowledgeFacetResolveConfiguration resolve) + { + return $"To find the value: search once for \"{resolve.Query}\" with filters " + + $"[{{key: {resolve.Via.Key}, value: {resolve.Via.Value}}}], and read {resolve.Read}. " + + "Copy it exactly; never build one."; + } } - - private static string Recipe(KnowledgeFacetResolveConfiguration resolve) - => $"To find the value: search once for \"{resolve.Query}\" with filters " - + $"[{{key: {resolve.Via.Key}, value: {resolve.Via.Value}}}], and read {resolve.Read}. " - + "Copy it exactly; never build one."; } diff --git a/src/AgentCore.Application/Knowledge/FacetFilteredSearch.cs b/src/AgentCore.Application/Knowledge/FacetFilteredSearch.cs index 637a001e..0fc9d7f7 100644 --- a/src/AgentCore.Application/Knowledge/FacetFilteredSearch.cs +++ b/src/AgentCore.Application/Knowledge/FacetFilteredSearch.cs @@ -6,91 +6,85 @@ using Microsoft.Extensions.AI; using Microsoft.Agents.AI; -namespace AgentCore.Application.Knowledge; - -/// -/// The framework's search function, with a filters argument in front of it. -/// -internal sealed class FacetFilteredSearch : DelegatingAIFunction +namespace AgentCore.Application.Knowledge { - private readonly IReadOnlyList? _facets; - - private readonly KnowledgeSearch.Core _core; - - private readonly JsonElement _schema; - - /// Wraps one search function. - /// The function the framework built: the schema donor, never invoked. - /// What scope.filterable declared, in document order — or null when it declared none. - /// The search bound to this agent's store and wiring. - /// A required argument is . - internal FacetFilteredSearch( - AIFunction innerFunction, - IReadOnlyList? facets, - KnowledgeSearch.Core core) - : base(innerFunction) + /// + /// The framework's search function, with a filters argument in front of it. + /// + internal sealed class FacetFilteredSearch : DelegatingAIFunction { - ArgumentNullException.ThrowIfNull(innerFunction); - ArgumentNullException.ThrowIfNull(core); + private readonly IReadOnlyList? _facets; + + private readonly KnowledgeSearch.Core _core; + + private readonly JsonElement _schema; + + /// Wraps one search function. + /// The function the framework built: the schema donor, never invoked. + /// What scope.filterable declared, in document order — or null when it declared none. + /// The search bound to this agent's store and wiring. + /// A required argument is . + internal FacetFilteredSearch( + AIFunction innerFunction, + IReadOnlyList? facets, + KnowledgeSearch.Core core) + : base(innerFunction) + { + ArgumentNullException.ThrowIfNull(innerFunction); + ArgumentNullException.ThrowIfNull(core); + + _facets = facets; + _core = core; + _schema = facets is { Count: > 0 } + ? FacetFilterSchema.Extend(innerFunction.JsonSchema, facets) + : innerFunction.JsonSchema; + } - _facets = facets; - _core = core; - _schema = facets is { Count: > 0 } - ? FacetFilterSchema.Extend(innerFunction.JsonSchema, facets) - : innerFunction.JsonSchema; - } + /// + public override JsonElement JsonSchema => _schema; - /// - public override JsonElement JsonSchema => _schema; + /// + protected override async ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(arguments); - /// - protected override async ValueTask InvokeCoreAsync( - AIFunctionArguments arguments, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(arguments); + IReadOnlyDictionary? named = _facets is { Count: > 0 } + ? FacetFilterReader.Read(arguments, _facets) + : null; - var named = _facets is { Count: > 0 } - ? FacetFilterReader.Read(arguments, _facets) - : null; + TurnInvocation? turn = TurnInvocation.FiledIn(arguments); - var turn = TurnInvocation.FiledIn(arguments); + // The donor's own declaration names the question: the model was built against it. + string question = (FirstQueryArgument(InnerFunction.JsonSchema) is { } name + && arguments.TryGetValue(name, out object? asked) + ? QueryText(asked) + : null) ?? throw new InvalidOperationException( + "The knowledge search was called without a search question, so there is nothing to look up."); + IReadOnlyList results = + await _core(question, named?.Count > 0 ? named : null, turn, cancellationToken).ConfigureAwait(false); - // The donor's own declaration names the question: the model was built against it. - var question = FirstQueryArgument(InnerFunction.JsonSchema) is { } name - && arguments.TryGetValue(name, out var asked) - ? QueryText(asked) - : null; + return results; + } - if (question is null) + /// Reads the donor's question argument name off its own schema. + private static string? FirstQueryArgument(JsonElement schema) { - throw new InvalidOperationException( - "The knowledge search was called without a search question, so there is nothing to look up."); + return schema.ValueKind is not JsonValueKind.Object + || !schema.TryGetProperty("properties", out JsonElement properties) + || properties.ValueKind is not JsonValueKind.Object + ? null + : properties.EnumerateObject().Select(property => property.Name).FirstOrDefault(); } - IReadOnlyList results = - await _core(question, named?.Count > 0 ? named : null, turn, cancellationToken).ConfigureAwait(false); - - return results; - } - - /// Reads the donor's question argument name off its own schema. - private static string? FirstQueryArgument(JsonElement schema) - { - if (schema.ValueKind is not JsonValueKind.Object - || !schema.TryGetProperty("properties", out var properties) - || properties.ValueKind is not JsonValueKind.Object) + private static string? QueryText(object? value) { - return null; + return value switch + { + string text => text, + JsonElement { ValueKind: JsonValueKind.String } element => element.GetString(), + _ => null, + }; } - - return properties.EnumerateObject().Select(property => property.Name).FirstOrDefault(); } - - private static string? QueryText(object? value) - => value switch - { - string text => text, - JsonElement { ValueKind: JsonValueKind.String } element => element.GetString(), - _ => null, - }; } diff --git a/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs b/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs index 5e0ff80b..a60156c2 100644 --- a/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs +++ b/src/AgentCore.Application/Knowledge/HybridCachingKnowledgeRetrievalPort.cs @@ -3,103 +3,106 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Caching.Hybrid; -namespace AgentCore.Application.Knowledge; - -/// -/// Remembers each search's cards in the host's cache, so a repeat of the same query under the same -/// scope skips the store. A store answers the same way to the same question until it is re-indexed, -/// so the lifetime is short by default: a stale answer costs a wrong card, not a wrong embedding. -/// -public sealed class HybridCachingKnowledgeRetrievalPort : IKnowledgeRetrievalPort, IAsyncDisposable +namespace AgentCore.Application.Knowledge { - /// How long an entry lives when the host names no lifetime. - public static readonly TimeSpan DefaultLifetime = TimeSpan.FromMinutes(5); - - private const string KeyPrefix = "agentcore:knowledge:"; - - private readonly IKnowledgeRetrievalPort _inner; + /// + /// Remembers each search's cards in the host's cache, so a repeat of the same query under the same + /// scope skips the store. A store answers the same way to the same question until it is re-indexed, + /// so the lifetime is short by default: a stale answer costs a wrong card, not a wrong embedding. + /// + public sealed class HybridCachingKnowledgeRetrievalPort : IKnowledgeRetrievalPort, IAsyncDisposable + { + /// How long an entry lives when the host names no lifetime. + public static readonly TimeSpan DefaultLifetime = TimeSpan.FromMinutes(5); - private readonly HybridCache _cache; + private const string KeyPrefix = "agentcore:knowledge:"; - private readonly HybridCacheEntryOptions _entry; + private readonly IKnowledgeRetrievalPort _inner; - /// Wraps one store in the cache. - /// The store that runs the search. - /// The host's cache. - /// How long one answer stays cached, or for . - /// The store or the cache is . - public HybridCachingKnowledgeRetrievalPort( - IKnowledgeRetrievalPort inner, - HybridCache cache, - TimeSpan? lifetime = null) - { - ArgumentNullException.ThrowIfNull(inner); - ArgumentNullException.ThrowIfNull(cache); + private readonly HybridCache _cache; - _inner = inner; - _cache = cache; - _entry = new HybridCacheEntryOptions { Expiration = lifetime ?? DefaultLifetime }; - } + private readonly HybridCacheEntryOptions _entry; - /// - /// - /// The store's own exceptions pass straight through and cache nothing, so a store that is down - /// or a scope it refuses reads exactly as it does without the cache. - /// - public async ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(query); + /// Wraps one store in the cache. + /// The store that runs the search. + /// The host's cache. + /// How long one answer stays cached, or for . + /// The store or the cache is . + public HybridCachingKnowledgeRetrievalPort( + IKnowledgeRetrievalPort inner, + HybridCache cache, + TimeSpan? lifetime = null) + { + ArgumentNullException.ThrowIfNull(inner); + ArgumentNullException.ThrowIfNull(cache); - // The cards ride as one JSON string so the host's serializer configuration never sees them: - // Extras is an object tree, and only KnowledgeCardCodec knows how to read it back. - var json = await _cache - .GetOrCreateAsync( - CacheKey(query, scope), - (Port: _inner, Query: query, Scope: scope), - static async (state, token) => KnowledgeCardCodec.Encode( - await state.Port.SearchAsync(state.Query, state.Scope, token).ConfigureAwait(false)), - _entry, - cancellationToken: cancellationToken) - .ConfigureAwait(false); + _inner = inner; + _cache = cache; + _entry = new HybridCacheEntryOptions { Expiration = lifetime ?? DefaultLifetime }; + } - return KnowledgeCardCodec.Decode(json); - } + /// + /// + /// The store's own exceptions pass straight through and cache nothing, so a store that is down + /// or a scope it refuses reads exactly as it does without the cache. + /// + public async ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(query); + + // The cards ride as one JSON string so the host's serializer configuration never sees them: + // Extras is an object tree, and only KnowledgeCardCodec knows how to read it back. + string json = await _cache + .GetOrCreateAsync( + CacheKey(query, scope), + (Port: _inner, Query: query, Scope: scope), + static async (state, token) => KnowledgeCardCodec.Encode( + await state.Port.SearchAsync(state.Query, state.Scope, token).ConfigureAwait(false)), + _entry, + cancellationToken: cancellationToken) + .ConfigureAwait(false); + + return KnowledgeCardCodec.Decode(json); + } - /// - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); + /// + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) - ? this - : _inner.GetService(serviceType, serviceKey); - } + return serviceKey is null && serviceType.IsInstanceOfType(this) + ? this + : _inner.GetService(serviceType, serviceKey); + } - /// Closes the store this wraps. - public async ValueTask DisposeAsync() - { - switch (_inner) + /// Closes the store this wraps. + public async ValueTask DisposeAsync() { - case IAsyncDisposable asyncDisposable: - await asyncDisposable.DisposeAsync().ConfigureAwait(false); - break; - case IDisposable disposable: - disposable.Dispose(); - break; + switch (_inner) + { + case IAsyncDisposable asyncDisposable: + await asyncDisposable.DisposeAsync().ConfigureAwait(false); + break; + case IDisposable disposable: + disposable.Dispose(); + break; + default: + break; + } } - } - private static string CacheKey(string query, KnowledgeScope? scope) - { - string[][] facets = scope is null - ? [] - : [.. scope.Facets - .OrderBy(entry => entry.Key, StringComparer.Ordinal) - .Select(entry => new[] { entry.Key, entry.Value })]; + private static string CacheKey(string query, KnowledgeScope? scope) + { + string[][] facets = scope is null + ? [] + : [.. scope.Facets + .OrderBy(entry => entry.Key, StringComparer.Ordinal) + .Select(entry => new[] { entry.Key, entry.Value })]; - return KeyPrefix + AIJsonUtilities.HashDataToString([query, facets], AIJsonUtilities.DefaultOptions); + return KeyPrefix + AIJsonUtilities.HashDataToString([query, facets], AIJsonUtilities.DefaultOptions); + } } } diff --git a/src/AgentCore.Application/Knowledge/IKnowledgeCitationFormatter.cs b/src/AgentCore.Application/Knowledge/IKnowledgeCitationFormatter.cs index 13591f2e..510c3324 100644 --- a/src/AgentCore.Application/Knowledge/IKnowledgeCitationFormatter.cs +++ b/src/AgentCore.Application/Knowledge/IKnowledgeCitationFormatter.cs @@ -1,22 +1,23 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Turns one card into the source label the model is shown beside it. -/// -/// -/// A citation is a sentence a deployment says about its own documents, so its wording belongs to -/// the deployment. This seam is how it says it: read whichever fields the collection carries, -/// including anything in , and return the label. -/// -public interface IKnowledgeCitationFormatter +namespace AgentCore.Application.Knowledge { - /// Gets the name providers.knowledge.citation selects this by. - string Name { get; } + /// + /// Turns one card into the source label the model is shown beside it. + /// + /// + /// A citation is a sentence a deployment says about its own documents, so its wording belongs to + /// the deployment. This seam is how it says it: read whichever fields the collection carries, + /// including anything in , and return the label. + /// + public interface IKnowledgeCitationFormatter + { + /// Gets the name providers.knowledge.citation selects this by. + string Name { get; } - /// Reads one card's source label, or to cite nothing for it. - /// The card about to be shown to the model. - /// The label, or . - string? Format(KnowledgeCard card); + /// Reads one card's source label, or to cite nothing for it. + /// The card about to be shown to the model. + /// The label, or . + string? Format(KnowledgeCard card); + } } diff --git a/src/AgentCore.Application/Knowledge/IKnowledgePointMapper.cs b/src/AgentCore.Application/Knowledge/IKnowledgePointMapper.cs index 70ab2e58..61483a38 100644 --- a/src/AgentCore.Application/Knowledge/IKnowledgePointMapper.cs +++ b/src/AgentCore.Application/Knowledge/IKnowledgePointMapper.cs @@ -1,16 +1,17 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Turns one retrieved point into the card AgentCore injects, for collections whose card is not -/// expressible as field paths. -/// -public interface IKnowledgePointMapper +namespace AgentCore.Application.Knowledge { - /// Gets the name providers.knowledge.mapper selects this by. - string Name { get; } + /// + /// Turns one retrieved point into the card AgentCore injects, for collections whose card is not + /// expressible as field paths. + /// + public interface IKnowledgePointMapper + { + /// Gets the name providers.knowledge.mapper selects this by. + string Name { get; } - /// Reads one point into a card, or to skip the point. - KnowledgeCard? Map(KnowledgePoint point); + /// Reads one point into a card, or to skip the point. + KnowledgeCard? Map(KnowledgePoint point); + } } diff --git a/src/AgentCore.Application/Knowledge/IKnowledgeQueryAnalyzer.cs b/src/AgentCore.Application/Knowledge/IKnowledgeQueryAnalyzer.cs index 9ed1f75a..60110b7a 100644 --- a/src/AgentCore.Application/Knowledge/IKnowledgeQueryAnalyzer.cs +++ b/src/AgentCore.Application/Knowledge/IKnowledgeQueryAnalyzer.cs @@ -1,13 +1,14 @@ -namespace AgentCore.Application.Knowledge; - -/// -/// Picks the terms one search must match, on top of vector similarity. -/// -public interface IKnowledgeQueryAnalyzer +namespace AgentCore.Application.Knowledge { - /// Gets the name providers.knowledge.analyzer selects this by. - string Name { get; } + /// + /// Picks the terms one search must match, on top of vector similarity. + /// + public interface IKnowledgeQueryAnalyzer + { + /// Gets the name providers.knowledge.analyzer selects this by. + string Name { get; } - /// Reads the terms one query requires. - IReadOnlyList RequiredTerms(string query); + /// Reads the terms one query requires. + IReadOnlyList RequiredTerms(string query); + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs b/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs index d9c09437..2f60b509 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs @@ -1,107 +1,19 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// What one retrieval actually did — the reader is the on-conversation engineer, and the model never sees it. -/// -internal sealed record KnowledgeAuditRecord +namespace AgentCore.Application.Knowledge { - private static readonly IReadOnlyDictionary EmptyScope = - new Dictionary(StringComparer.Ordinal); - - private static readonly IReadOnlyDictionary EmptyOrigins = - new Dictionary(StringComparer.Ordinal); - - /// Gets the turn the retrieval ran inside, or when nothing names it. - public string? TurnId { get; init; } - - /// Gets the id of the agent that asked. - public required string Agent { get; init; } - - /// Gets the mode the agent's knowledge: block declared. - public required KnowledgeMode Mode { get; init; } - - /// Gets the search text. - public required string Query { get; init; } - - /// Gets the facets the turn's scope carried, or empty when none was open. - public required IReadOnlyDictionary Scope { get; init; } - - /// Gets where each facet's value came from, or empty when none was open. - public required IReadOnlyDictionary ScopeOrigins { get; init; } - - /// Gets how long the whole retrieval took, in milliseconds. - public required double LatencyMs { get; init; } - - /// Gets the cards the search returned, ranked cards first. - public required IReadOnlyList Cards { get; init; } - - /// Gets what the port threw, or when the search succeeded. - public string? Failure { get; init; } - - /// Builds the record of one retrieval. - /// - /// stays empty: the provider that writes this record can reach no conversation - /// id and no turn index, and a synthesised one would read as real to whoever greps for it. - /// - public static KnowledgeAuditRecord For( - string agent, - KnowledgeMode mode, - string query, - KnowledgeScope? scope, - IReadOnlyList cards, - double latencyMs, - Exception? failure) - { - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(query); - ArgumentNullException.ThrowIfNull(cards); - - return new KnowledgeAuditRecord - { - Agent = agent, - Mode = mode, - Query = query, - Scope = scope?.Facets ?? EmptyScope, - ScopeOrigins = scope?.Origins ?? EmptyOrigins, - LatencyMs = latencyMs, - Cards = [.. cards.Select(CardEntry.From)], - Failure = failure?.ToString(), - }; - } - - /// Reads this record into the part of it a log store may hold. - /// The view. It carries no search text. - public LogView ForLog() => new() - { - TurnId = TurnId, - Agent = Agent, - Mode = Mode, - QueryLength = Query.Length, - Scope = ScopeText(), - LatencyMs = LatencyMs, - Cards = Cards, - }; - - /// - /// Writes the scope as code=* (Wildcard), model=f85-2019 (Tool), keys in ordinal order. - /// The log line prints the view with the record's own ToString, and a dictionary prints - /// as its type name there. - /// - private string ScopeText() - => string.Join(", ", Scope - .OrderBy(facet => facet.Key, StringComparer.Ordinal) - .Select(facet => ScopeOrigins.TryGetValue(facet.Key, out var origin) - ? $"{facet.Key}={facet.Value} ({origin})" - : $"{facet.Key}={facet.Value}")); - /// - /// The part of one retrieval that may be written to a log store. + /// What one retrieval actually did — the reader is the on-conversation engineer, and the model never sees it. /// - internal sealed record LogView + internal sealed record KnowledgeAuditRecord { + private static readonly IReadOnlyDictionary EmptyScope = + new Dictionary(StringComparer.Ordinal); + + private static readonly IReadOnlyDictionary EmptyOrigins = + new Dictionary(StringComparer.Ordinal); + /// Gets the turn the retrieval ran inside, or when nothing names it. public string? TurnId { get; init; } @@ -111,54 +23,151 @@ internal sealed record LogView /// Gets the mode the agent's knowledge: block declared. public required KnowledgeMode Mode { get; init; } - /// Gets how many characters the search input held. Never the input itself. - public required int QueryLength { get; init; } + /// Gets the search text. + public required string Query { get; init; } - /// - /// Gets the facets the turn's scope carried, each with where its value came from, as - /// code=* (Wildcard), model=f85-2019 (Tool). Empty when no scope was open. - /// - public required string Scope { get; init; } + /// Gets the facets the turn's scope carried, or empty when none was open. + public required IReadOnlyDictionary Scope { get; init; } + + /// Gets where each facet's value came from, or empty when none was open. + public required IReadOnlyDictionary ScopeOrigins { get; init; } /// Gets how long the whole retrieval took, in milliseconds. public required double LatencyMs { get; init; } - /// Gets the cards the search returned, ranked cards first. Never a card body. + /// Gets the cards the search returned, ranked cards first. public required IReadOnlyList Cards { get; init; } - } - /// One card, as the audit record keeps it. - internal sealed record CardEntry - { - /// Gets the card id. - public required string CardId { get; init; } + /// Gets what the port threw, or when the search succeeded. + public string? Failure { get; init; } + + /// Builds the record of one retrieval. + /// + /// stays empty: the provider that writes this record can reach no conversation + /// id and no turn index, and a synthesised one would read as real to whoever greps for it. + /// + public static KnowledgeAuditRecord For( + string agent, + KnowledgeMode mode, + string query, + KnowledgeScope? scope, + IReadOnlyList cards, + double latencyMs, + Exception? failure) + { + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(query); + ArgumentNullException.ThrowIfNull(cards); + + return new KnowledgeAuditRecord + { + Agent = agent, + Mode = mode, + Query = query, + Scope = scope?.Facets ?? EmptyScope, + ScopeOrigins = scope?.Origins ?? EmptyOrigins, + LatencyMs = latencyMs, + Cards = [.. cards.Select(CardEntry.From)], + Failure = failure?.ToString(), + }; + } + + /// Reads this record into the part of it a log store may hold. + /// The view. It carries no search text. + public LogView ForLog() + { + return new() + { + TurnId = TurnId, + Agent = Agent, + Mode = Mode, + QueryLength = Query.Length, + Scope = ScopeText(), + LatencyMs = LatencyMs, + Cards = Cards, + }; + } + + /// + /// Writes the scope as code=* (Wildcard), model=f85-2019 (Tool), keys in ordinal order. + /// The log line prints the view with the record's own ToString, and a dictionary prints + /// as its type name there. + /// + private string ScopeText() + { + return string.Join(", ", Scope + .OrderBy(facet => facet.Key, StringComparer.Ordinal) + .Select(facet => ScopeOrigins.TryGetValue(facet.Key, out KnowledgeFacetOrigin origin) + ? $"{facet.Key}={facet.Value} ({origin})" + : $"{facet.Key}={facet.Value}")); + } + + /// + /// The part of one retrieval that may be written to a log store. + /// + internal sealed record LogView + { + /// Gets the turn the retrieval ran inside, or when nothing names it. + public string? TurnId { get; init; } + + /// Gets the id of the agent that asked. + public required string Agent { get; init; } - /// Gets the retrieval score — cosine similarity under one leg, a fused rank score under several — or when a link pulled the card in. - public double? Score { get; init; } + /// Gets the mode the agent's knowledge: block declared. + public required KnowledgeMode Mode { get; init; } - /// Gets how much the source is trusted, or null when the store maps no such field. - public int? Authority { get; init; } + /// Gets how many characters the search input held. Never the input itself. + public required int QueryLength { get; init; } - /// Gets the manifest row the card came from. - public required string SourceRef { get; init; } + /// + /// Gets the facets the turn's scope carried, each with where its value came from, as + /// code=* (Wildcard), model=f85-2019 (Tool). Empty when no scope was open. + /// + public required string Scope { get; init; } - /// Gets where in that source it sits. - public required string Locator { get; init; } + /// Gets how long the whole retrieval took, in milliseconds. + public required double LatencyMs { get; init; } - /// Gets "ranked" when the search scored the card, or "link" when a link pulled it in. - public required string Via { get; init; } + /// Gets the cards the search returned, ranked cards first. Never a card body. + public required IReadOnlyList Cards { get; init; } + } - /// Reads one card into its audit entry. - /// The card to record. - /// The entry. - internal static CardEntry From(KnowledgeCard card) => new() + /// One card, as the audit record keeps it. + internal sealed record CardEntry { - CardId = card.CardId, - Score = card.Score, - Authority = card.Authority, - SourceRef = card.SourceRef, - Locator = card.SourceLocator, - Via = card.ViaLink ? "link" : "ranked", - }; + /// Gets the card id. + public required string CardId { get; init; } + + /// Gets the retrieval score — cosine similarity under one leg, a fused rank score under several — or when a link pulled the card in. + public double? Score { get; init; } + + /// Gets how much the source is trusted, or null when the store maps no such field. + public int? Authority { get; init; } + + /// Gets the manifest row the card came from. + public required string SourceRef { get; init; } + + /// Gets where in that source it sits. + public required string Locator { get; init; } + + /// Gets "ranked" when the search scored the card, or "link" when a link pulled it in. + public required string Via { get; init; } + + /// Reads one card into its audit entry. + /// The card to record. + /// The entry. + internal static CardEntry From(KnowledgeCard card) + { + return new() + { + CardId = card.CardId, + Score = card.Score, + Authority = card.Authority, + SourceRef = card.SourceRef, + Locator = card.SourceLocator, + Via = card.ViaLink ? "link" : "ranked", + }; + } + } } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeBinding.cs b/src/AgentCore.Application/Knowledge/KnowledgeBinding.cs index 5d5a151a..80251c6c 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeBinding.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeBinding.cs @@ -2,17 +2,18 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Knowledge; - -/// What one agent's knowledge search is bound to, once, at compile time. -/// The store every search reads. -/// The agent's resolved knowledge: block. -/// The id of the agent that asks, for the log line. -/// The wording providers.knowledge.citation named. -/// Where the search's own log events go. -internal sealed record KnowledgeBinding( - IKnowledgeRetrievalPort Port, - ResolvedKnowledge Knowledge, - string Agent, - IKnowledgeCitationFormatter Citations, - ILogger Logger); +namespace AgentCore.Application.Knowledge +{ + /// What one agent's knowledge search is bound to, once, at compile time. + /// The store every search reads. + /// The agent's resolved knowledge: block. + /// The id of the agent that asks, for the log line. + /// The wording providers.knowledge.citation named. + /// Where the search's own log events go. + internal sealed record KnowledgeBinding( + IKnowledgeRetrievalPort Port, + ResolvedKnowledge Knowledge, + string Agent, + IKnowledgeCitationFormatter Citations, + ILogger Logger); +} diff --git a/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs b/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs index 23c056d5..93d2ae61 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs @@ -1,34 +1,39 @@ -namespace AgentCore.Application.Knowledge; - -/// -/// Tells a caller who hung up apart from a retrieval that failed. -/// -/// -/// The two are answered differently everywhere in this folder: a hang-up is rethrown and charges the -/// conversation nothing, while a failure is reported to the model and logged. -/// -internal static class KnowledgeCancellation +namespace AgentCore.Application.Knowledge { - /// Whether a failure is the caller ending the turn. - /// What the search threw. - /// The caller's token. - /// when the caller hung up. - internal static bool ByCaller(Exception failure, CancellationToken cancellationToken) - => failure is OperationCanceledException && cancellationToken.IsCancellationRequested; - - /// Whether a search under a deadline was ended by the caller rather than by that deadline. - /// What the search threw. - /// The deadline's own source, cancelled by its timer and by nothing else. - /// The caller's token. - /// when the caller hung up. + /// + /// Tells a caller who hung up apart from a retrieval that failed. + /// /// - /// The caller's token standing cancelled is not enough on its own. A caller that hangs up in the - /// moment after the deadline fired would make a genuine timeout read as a hang-up, and the refund - /// that follows would hand the facet back an ask it had already spent — letting a probe that - /// always times out offer the same facet forever, which is what K22's cap exists to stop. Only the - /// timer cancels , so a tie is settled in favour of the timeout. + /// The two are answered differently everywhere in this folder: a hang-up is rethrown and charges the + /// conversation nothing, while a failure is reported to the model and logged. /// - internal static bool ByCaller( - Exception failure, CancellationTokenSource timeout, CancellationToken cancellationToken) - => !timeout.IsCancellationRequested && ByCaller(failure, cancellationToken); + internal static class KnowledgeCancellation + { + /// Whether a failure is the caller ending the turn. + /// What the search threw. + /// The caller's token. + /// when the caller hung up. + internal static bool ByCaller(Exception failure, CancellationToken cancellationToken) + { + return failure is OperationCanceledException && cancellationToken.IsCancellationRequested; + } + + /// Whether a search under a deadline was ended by the caller rather than by that deadline. + /// What the search threw. + /// The deadline's own source, cancelled by its timer and by nothing else. + /// The caller's token. + /// when the caller hung up. + /// + /// The caller's token standing cancelled is not enough on its own. A caller that hangs up in the + /// moment after the deadline fired would make a genuine timeout read as a hang-up, and the refund + /// that follows would hand the facet back an ask it had already spent — letting a probe that + /// always times out offer the same facet forever, which is what K22's cap exists to stop. Only the + /// timer cancels , so a tie is settled in favour of the timeout. + /// + internal static bool ByCaller( + Exception failure, CancellationTokenSource timeout, CancellationToken cancellationToken) + { + return !timeout.IsCancellationRequested && ByCaller(failure, cancellationToken); + } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs b/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs index 8d015872..270f5995 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeCardCodec.cs @@ -1,52 +1,64 @@ using System.Text.Json; using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Writes a list of cards to JSON and reads it back with the same payload shape the store gave. -/// -internal static class KnowledgeCardCodec +namespace AgentCore.Application.Knowledge { - private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web); - - public static string Encode(IReadOnlyList cards) - => JsonSerializer.Serialize(cards, Options); - - public static IReadOnlyList Decode(string json) + /// + /// Writes a list of cards to JSON and reads it back with the same payload shape the store gave. + /// + internal static class KnowledgeCardCodec { - var cards = JsonSerializer.Deserialize>(json, Options) ?? []; + private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web); - for (var index = 0; index < cards.Count; index++) + public static string Encode(IReadOnlyList cards) { - cards[index] = cards[index] with { Extras = RebuildMap(cards[index].Extras) }; + return JsonSerializer.Serialize(cards, Options); } - return cards; - } + public static IReadOnlyList Decode(string json) + { + List cards = JsonSerializer.Deserialize>(json, Options) ?? []; - private static Dictionary RebuildMap(IReadOnlyDictionary map) - => map.ToDictionary(entry => entry.Key, entry => Rebuild(entry.Value), StringComparer.Ordinal); + for (int index = 0; index < cards.Count; index++) + { + cards[index] = cards[index] with { Extras = RebuildMap(cards[index].Extras) }; + } - private static object? Rebuild(object? value) => value switch - { - JsonElement element => Rebuild(element), - IReadOnlyDictionary map => RebuildMap(map), - _ => value, - }; + return cards; + } - /// Mirrors the shape QdrantPointConverter produces: long, double, bool, string, list, map. - private static object? Rebuild(JsonElement element) => element.ValueKind switch - { - JsonValueKind.String => element.GetString(), - // Boxed on each arm: a bare long/double conditional promotes the long to a double. - JsonValueKind.Number => element.TryGetInt64(out var whole) ? (object)whole : element.GetDouble(), - JsonValueKind.True => true, - JsonValueKind.False => false, - JsonValueKind.Array => (IReadOnlyList)[.. element.EnumerateArray().Select(Rebuild)], - JsonValueKind.Object => element - .EnumerateObject() - .ToDictionary(property => property.Name, property => Rebuild(property.Value), StringComparer.Ordinal), - _ => null, - }; + private static Dictionary RebuildMap(IReadOnlyDictionary map) + { + return map.ToDictionary(entry => entry.Key, entry => Rebuild(entry.Value), StringComparer.Ordinal); + } + + private static object? Rebuild(object? value) + { + return value switch + { + JsonElement element => Rebuild(element), + IReadOnlyDictionary map => RebuildMap(map), + _ => value, + }; + } + + /// Mirrors the shape QdrantPointConverter produces: long, double, bool, string, list, map. + private static object? Rebuild(JsonElement element) + { + return element.ValueKind switch + { + JsonValueKind.String => element.GetString(), + // Boxed on each arm: a bare long/double conditional promotes the long to a double. + JsonValueKind.Number => element.TryGetInt64(out long whole) ? (object)whole : element.GetDouble(), + JsonValueKind.True => true, + JsonValueKind.False => false, + JsonValueKind.Array => (IReadOnlyList)[.. element.EnumerateArray().Select(Rebuild)], + JsonValueKind.Object => element + .EnumerateObject() + .ToDictionary(property => property.Name, property => Rebuild(property.Value), StringComparer.Ordinal), + JsonValueKind.Null or JsonValueKind.Undefined => null, + _ => null, + }; + } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeCardMapper.cs b/src/AgentCore.Application/Knowledge/KnowledgeCardMapper.cs index 8c9124cf..14c328c7 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeCardMapper.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeCardMapper.cs @@ -1,37 +1,40 @@ using AgentCore.Domain.Knowledge; using Microsoft.Agents.AI; -namespace AgentCore.Application.Knowledge; - -/// -/// Turns a card into what the framework injects, and applies citations. -/// -internal static class KnowledgeCardMapper +namespace AgentCore.Application.Knowledge { - /// Maps one card. - /// The card the store returned. - /// Whether this agent shows the model where the card came from. - /// The wording providers.knowledge.citation named. - /// The result the framework injects. - internal static TextSearchProvider.TextSearchResult ToResult( - KnowledgeCard card, bool citations, IKnowledgeCitationFormatter formatter) + /// + /// Turns a card into what the framework injects, and applies citations. + /// + internal static class KnowledgeCardMapper { - ArgumentNullException.ThrowIfNull(card); - ArgumentNullException.ThrowIfNull(formatter); - - return new TextSearchProvider.TextSearchResult + /// Maps one card. + /// The card the store returned. + /// Whether this agent shows the model where the card came from. + /// The wording providers.knowledge.citation named. + /// The result the framework injects. + internal static TextSearchProvider.TextSearchResult ToResult( + KnowledgeCard card, bool citations, IKnowledgeCitationFormatter formatter) { - Text = card.Text, + ArgumentNullException.ThrowIfNull(card); + ArgumentNullException.ThrowIfNull(formatter); - // An empty label is not a label. The framework renders whatever is here, so a formatter - // that returns "" would put a bare separator in front of the model instead of nothing. - SourceName = citations ? Trimmed(formatter.Format(card)) : null, - SourceLink = null, - RawRepresentation = card, - }; - } + return new TextSearchProvider.TextSearchResult + { + Text = card.Text, - /// Reads a formatter's answer, treating blank as no citation. - private static string? Trimmed(string? label) - => label is { Length: > 0 } && label.Trim().Length > 0 ? label : null; + // An empty label is not a label. The framework renders whatever is here, so a formatter + // that returns "" would put a bare separator in front of the model instead of nothing. + SourceName = citations ? Trimmed(formatter.Format(card)) : null, + SourceLink = null, + RawRepresentation = card, + }; + } + + /// Reads a formatter's answer, treating blank as no citation. + private static string? Trimmed(string? label) + { + return label is { Length: > 0 } && label.Trim().Length > 0 ? label : null; + } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeCitationFormatterFactory.cs b/src/AgentCore.Application/Knowledge/KnowledgeCitationFormatterFactory.cs index f5338c44..27713098 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeCitationFormatterFactory.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeCitationFormatterFactory.cs @@ -1,46 +1,47 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Knowledge; - -/// -/// Picks the formatter providers.knowledge.citation names. -/// -public static class KnowledgeCitationFormatterFactory +namespace AgentCore.Application.Knowledge { - /// The JSON Pointer an unknown name reports. - private const string Pointer = "/providers/knowledge/citation"; - - /// Resolves the formatter the document names, or the shipped one. - /// The loaded document. It carries providers.knowledge.citation. - /// What the host bound with UseKnowledgeCitationFormatters. - /// The formatter every agent that declares citations: true writes through. - /// is . - /// No formatter answers to the name the document wrote. - public static IKnowledgeCitationFormatter Resolve( - AgentCoreConfiguration configuration, - IReadOnlyList? registered) + /// + /// Picks the formatter providers.knowledge.citation names. + /// + public static class KnowledgeCitationFormatterFactory { - ArgumentNullException.ThrowIfNull(configuration); + /// The JSON Pointer an unknown name reports. + private const string Pointer = "/providers/knowledge/citation"; + + /// Resolves the formatter the document names, or the shipped one. + /// The loaded document. It carries providers.knowledge.citation. + /// What the host bound with UseKnowledgeCitationFormatters. + /// The formatter every agent that declares citations: true writes through. + /// is . + /// No formatter answers to the name the document wrote. + public static IKnowledgeCitationFormatter Resolve( + AgentCoreConfiguration configuration, + IReadOnlyList? registered) + { + ArgumentNullException.ThrowIfNull(configuration); - var name = configuration.Providers?.Knowledge?.Citation - ?? KnowledgeProviderConfiguration.DefaultCitation; + string name = configuration.Providers?.Knowledge?.Citation + ?? KnowledgeProviderConfiguration.DefaultCitation; - // The host's own registrations win, so a deployment can replace the shipped wording under - // its own name without the framework knowing that name exists. - var candidates = registered is { Count: > 0 } - ? [.. registered, new SourceLocatorCitationFormatter()] - : new List { new SourceLocatorCitationFormatter() }; + // The host's own registrations win, so a deployment can replace the shipped wording under + // its own name without the framework knowing that name exists. + List candidates = registered is { Count: > 0 } + ? [.. registered, new SourceLocatorCitationFormatter()] + : [new SourceLocatorCitationFormatter()]; - return candidates.FirstOrDefault(one => string.Equals(one.Name, name, StringComparison.Ordinal)) - ?? throw new ConfigurationLoadException(new ConfigurationError - { - Pointer = Pointer, - Message = $"providers.knowledge.citation is '{name}', and no registered " - + $"{nameof(IKnowledgeCitationFormatter)} answers to it. This host offers " - + $"{string.Join(", ", candidates.Select(one => $"'{one.Name}'"))}. Register one " - + "with options.UseKnowledgeCitationFormatters, or name one of those.", - Check = ConfigurationCheck.ReferenceResolution, - }); + return candidates.FirstOrDefault(one => string.Equals(one.Name, name, StringComparison.Ordinal)) + ?? throw new ConfigurationLoadException(new ConfigurationError + { + Pointer = Pointer, + Message = $"providers.knowledge.citation is '{name}', and no registered " + + $"{nameof(IKnowledgeCitationFormatter)} answers to it. This host offers " + + $"{string.Join(", ", candidates.Select(one => $"'{one.Name}'"))}. Register one " + + "with options.UseKnowledgeCitationFormatters, or name one of those.", + Check = ConfigurationCheck.ReferenceResolution, + }); + } } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs b/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs index c5cd72a6..9776e054 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs @@ -1,35 +1,38 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Knowledge; - -/// -/// What a knowledge search puts in front of the model when it has no cards to show. -/// -internal static class KnowledgeNotices +namespace AgentCore.Application.Knowledge { - /// The source name every notice carries, so the model can never cite one as a card. - internal const string SourceName = "agentcore:notice"; + /// + /// What a knowledge search puts in front of the model when it has no cards to show. + /// + internal static class KnowledgeNotices + { + /// The source name every notice carries, so the model can never cite one as a card. + internal const string SourceName = "agentcore:notice"; - /// What the model is told when the search itself failed. - internal const string Unreachable = - "The knowledge base is unreachable for this turn. Say so, and do not answer from memory."; + /// What the model is told when the search itself failed. + internal const string Unreachable = + "The knowledge base is unreachable for this turn. Say so, and do not answer from memory."; - /// What the model is told when this agent is scoped and the turn has no scope open. - internal const string NoScope = - "The knowledge base was not searched for this turn, because no scope is open to search " - + "within. Say you cannot look this up, and do not answer from memory."; + /// What the model is told when this agent is scoped and the turn has no scope open. + internal const string NoScope = + "The knowledge base was not searched for this turn, because no scope is open to search " + + "within. Say you cannot look this up, and do not answer from memory."; - /// What the model is told when the search ran and matched nothing. - /// - /// Tool mode only. Prefetch searches before every invocation on a query composed from recent - /// messages, so a greeting would otherwise open the conversation by announcing an empty knowledge base. - /// - internal const string Empty = - "The knowledge base holds nothing for this question. Say so, and do not answer from memory."; + /// What the model is told when the search ran and matched nothing. + /// + /// Tool mode only. Prefetch searches before every invocation on a query composed from recent + /// messages, so a greeting would otherwise open the conversation by announcing an empty knowledge base. + /// + internal const string Empty = + "The knowledge base holds nothing for this question. Say so, and do not answer from memory."; - /// Wraps one sentence for the model in the shape the framework injects. - /// What the model is told. - /// The result. - internal static TextSearchProvider.TextSearchResult Of(string text) - => new() { Text = text, SourceName = SourceName }; + /// Wraps one sentence for the model in the shape the framework injects. + /// What the model is told. + /// The result. + internal static TextSearchProvider.TextSearchResult Of(string text) + { + return new() { Text = text, SourceName = SourceName }; + } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgePoint.cs b/src/AgentCore.Application/Knowledge/KnowledgePoint.cs index b7875dde..ae3e1b93 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgePoint.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgePoint.cs @@ -1,14 +1,15 @@ -namespace AgentCore.Application.Knowledge; - -/// One retrieved point, stripped of every vendor type.s -public sealed record KnowledgePoint +namespace AgentCore.Application.Knowledge { - /// Gets the store's own key for the point, as text. A numeric key is decimal digits. - public required string PointId { get; init; } + /// One retrieved point, stripped of every vendor type.s + public sealed record KnowledgePoint + { + /// Gets the store's own key for the point, as text. A numeric key is decimal digits. + public required string PointId { get; init; } - /// Gets the retrieval score — cosine similarity under one leg, a fused rank score under several — or when the point was fetched rather than ranked. - public double? Score { get; init; } + /// Gets the retrieval score — cosine similarity under one leg, a fused rank score under several — or when the point was fetched rather than ranked. + public double? Score { get; init; } - /// Gets the payload, vendor-free. - public required IReadOnlyDictionary Payload { get; init; } + /// Gets the payload, vendor-free. + public required IReadOnlyDictionary Payload { get; init; } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgePrefetchProvider.cs b/src/AgentCore.Application/Knowledge/KnowledgePrefetchProvider.cs index 8a8b48c7..ecac7d81 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgePrefetchProvider.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgePrefetchProvider.cs @@ -1,63 +1,67 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.Logging; using AgentCore.Application.Runtime.Turn; +using AgentCore.Application.Runtime; -namespace AgentCore.Application.Knowledge; - -// The prefetch half of one agent's knowledge block: runs the framework's own search provider -// per invocation, bound to that invocation's turn. A shared provider cannot serve prefetch — -// the framework invokes its search as (query, cancellation) with no turn — so this builds a -// provider per conversation around the same options, closing over the turn the session filed. State -// keys and post-invocation storage forward to the shared template: accumulation lives in -// the session store, not on any instance, so a fresh provider per conversation loses nothing. -internal sealed class KnowledgePrefetchProvider( - AIContextProvider template, - TextSearchProviderOptions options, - ILoggerFactory? loggers, - KnowledgeSearch.Core core) - : AIContextProvider +namespace AgentCore.Application.Knowledge { - private readonly AIContextProvider _template = template - ?? throw new ArgumentNullException(nameof(template)); + // The prefetch half of one agent's knowledge block: runs the framework's own search provider + // per invocation, bound to that invocation's turn. A shared provider cannot serve prefetch — + // the framework invokes its search as (query, cancellation) with no turn — so this builds a + // provider per conversation around the same options, closing over the turn the session filed. State + // keys and post-invocation storage forward to the shared template: accumulation lives in + // the session store, not on any instance, so a fresh provider per conversation loses nothing. + internal sealed class KnowledgePrefetchProvider( + AIContextProvider template, + TextSearchProviderOptions options, + ILoggerFactory? loggers, + KnowledgeSearch.Core core) + : AIContextProvider + { + private readonly AIContextProvider _template = template + ?? throw new ArgumentNullException(nameof(template)); - private readonly TextSearchProviderOptions _options = options - ?? throw new ArgumentNullException(nameof(options)); + private readonly TextSearchProviderOptions _options = options + ?? throw new ArgumentNullException(nameof(options)); - private readonly ILoggerFactory? _loggers = loggers; + private readonly ILoggerFactory? _loggers = loggers; - private readonly KnowledgeSearch.Core _core = core - ?? throw new ArgumentNullException(nameof(core)); + private readonly KnowledgeSearch.Core _core = core + ?? throw new ArgumentNullException(nameof(core)); - /// - public override IReadOnlyList StateKeys => _template.StateKeys; + /// + public override IReadOnlyList StateKeys => _template.StateKeys; - /// - public override object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); + /// + public override object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); - return serviceType.IsInstanceOfType(this) && serviceKey is null - ? this - : _template.GetService(serviceType, serviceKey); - } + return serviceType.IsInstanceOfType(this) && serviceKey is null + ? this + : _template.GetService(serviceType, serviceKey); + } - /// - protected override async ValueTask InvokingCoreAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - var turn = TurnRegistry.For(context.Session); + /// + protected override async ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + TurnInvocation? turn = TurnRegistry.For(context.Session); - AIContextProvider inner = new TextSearchProvider( - async (query, token) => - (IEnumerable)await _core(query, null, turn, token).ConfigureAwait(false), - _options, - _loggers); + AIContextProvider inner = new TextSearchProvider( + async (query, token) => + await _core(query, null, turn, token).ConfigureAwait(false), + _options, + _loggers); - return await inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); - } + return await inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); + } - /// - protected override ValueTask InvokedCoreAsync( - InvokedContext context, CancellationToken cancellationToken = default) - => _template.InvokedAsync(context, cancellationToken); + /// + protected override ValueTask InvokedCoreAsync( + InvokedContext context, CancellationToken cancellationToken = default) + { + return _template.InvokedAsync(context, cancellationToken); + } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs b/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs index ece8a724..13543e6b 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs @@ -1,322 +1,322 @@ using System.Diagnostics; -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Diagnostics; -using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Domain.Knowledge; using Microsoft.Agents.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Knowledge; - -/// -/// §8 steps 3-6: the probe. When a scoped search clears no card, it drops one wildcard-filled facet, -/// searches again, and names what the wider search holds. -/// -internal static class KnowledgeProbe +namespace AgentCore.Application.Knowledge { - /// Runs the probe. - /// The agent's port, wiring and logger. The probe's own second search reads the same port. - /// The live scope the main search just ran under. - /// The search text the framework composed. - /// The conversation's ambiguity holder, or inside a nested tool call. - /// Whether this row's session carries the caller's own history. - /// The caller's own token — cancelling this is the caller hanging up, not a timeout. - /// What the probe found: its note, or the "holds nothing" notice. - internal static async Task> RunAsync( - KnowledgeBinding binding, - KnowledgeScope scope, - string query, - Clarifications? clarifications, - bool carriesHistory, - CancellationToken cancellationToken) + /// + /// §8 steps 3-6: the probe. When a scoped search clears no card, it drops one wildcard-filled facet, + /// searches again, and names what the wider search holds. + /// + internal static class KnowledgeProbe { - // K42: a nested tool call runs with the holder stripped from its invocation, so a delegated - // run's own search cannot latch, count or record — but a scoped run still owes the caller - // the notice. - if (clarifications is null || ProbeWiring.From(binding.Knowledge.Clarification) is not { } wiring) + /// Runs the probe. + /// The agent's port, wiring and logger. The probe's own second search reads the same port. + /// The live scope the main search just ran under. + /// The search text the framework composed. + /// The conversation's ambiguity holder, or inside a nested tool call. + /// Whether this row's session carries the caller's own history. + /// The caller's own token — cancelling this is the caller hanging up, not a timeout. + /// What the probe found: its note, or the "holds nothing" notice. + internal static async Task> RunAsync( + KnowledgeBinding binding, + KnowledgeScope scope, + string query, + Clarifications? clarifications, + bool carriesHistory, + CancellationToken cancellationToken) { - return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; - } + // K42: a nested tool call runs with the holder stripped from its invocation, so a delegated + // run's own search cannot latch, count or record — but a scoped run still owes the caller + // the notice. + if (clarifications is null || ProbeWiring.From(binding.Knowledge.Clarification) is not { } wiring) + { + return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; + } - // §8 step 3. Recomputed fresh on every call in the turn — including one that arrives after the - // turn's probe has already run — so it must stay cheap, deterministic and repeatable rather - // than mutate anything. Nothing is latched by this exit: a second call that also finds no - // droppable facet simply reaches this same conclusion again. - if (DroppableFacet(wiring, scope, clarifications) is not { } facet) - { - return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; - } + // §8 step 3. Recomputed fresh on every call in the turn — including one that arrives after the + // turn's probe has already run — so it must stay cheap, deterministic and repeatable rather + // than mutate anything. Nothing is latched by this exit: a second call that also finds no + // droppable facet simply reaches this same conclusion again. + if (DroppableFacet(wiring, scope, clarifications) is not { } facet) + { + return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; + } - var probe = clarifications.ClaimProbe(); - if (!probe.Won) - { - return await ReplayAsync(probe, wiring.Ambiguity, cancellationToken).ConfigureAwait(false); - } + Clarifications.Probe probe = clarifications.ClaimProbe(); + if (!probe.Won) + { + return await ReplayAsync(probe, wiring.Ambiguity, cancellationToken).ConfigureAwait(false); + } - ClaimedProbe claimed = new(clarifications, probe, facet); + ClaimedProbe claimed = new(clarifications, probe, facet); - // Every way out of the winner's path has to resolve the latch. Fail() is the catch-all: it - // does nothing once an outcome has been published, and where nothing was published it wakes - // the turn's other callers instead of leaving them to wait out the full margin for an answer - // that a throw already took away. - try - { - // §8 step 4: the latch and the increment both belong before the search runs. An increment - // placed after it would let a probe that always times out offer the same facet forever; a - // latch placed after it would leave a throwing first call's latch unset, so a second call - // in the same turn would re-run the search and advance probeAsks a second time. - clarifications.Update(facet, s => s.ProbeAsks++); + // Every way out of the winner's path has to resolve the latch. Fail() is the catch-all: it + // does nothing once an outcome has been published, and where nothing was published it wakes + // the turn's other callers instead of leaving them to wait out the full margin for an answer + // that a throw already took away. + try + { + // §8 step 4: the latch and the increment both belong before the search runs. An increment + // placed after it would let a probe that always times out offer the same facet forever; a + // latch placed after it would leave a throwing first call's latch unset, so a second call + // in the same turn would re-run the search and advance probeAsks a second time. + clarifications.Update(facet, s => s.ProbeAsks++); - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(wiring.Ambiguity.ProbeDeadlineSeconds)); + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(wiring.Ambiguity.ProbeDeadlineSeconds)); - using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeout.Token); + using CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeout.Token); - IReadOnlyList probeCards; + IReadOnlyList probeCards; - try - { - probeCards = await SearchAsync(binding, WithoutFacet(scope, facet), query, deadline.Token).ConfigureAwait(false); - } - catch (Exception failure) when (KnowledgeCancellation.ByCaller(failure, timeout, cancellationToken)) - { - // The caller hung up: nothing was asked and nothing was learned, so the facet must not - // be charged for a turn that never happened. The payload is FAILED, not dropped, so - // every waiter wakes rather than burning its own wait margin on an answer that will - // never come — and the latch stays claimed, so the corpse of this cancelled turn - // cannot probe again. - clarifications.Update(facet, s => s.ProbeAsks--); - throw; + try + { + probeCards = await SearchAsync(binding, WithoutFacet(scope, facet), query, deadline.Token).ConfigureAwait(false); + } + catch (Exception failure) when (KnowledgeCancellation.ByCaller(failure, timeout, cancellationToken)) + { + // The caller hung up: nothing was asked and nothing was learned, so the facet must not + // be charged for a turn that never happened. The payload is FAILED, not dropped, so + // every waiter wakes rather than burning its own wait margin on an answer that will + // never come — and the latch stays claimed, so the corpse of this cancelled turn + // cannot probe again. + clarifications.Update(facet, s => s.ProbeAsks--); + throw; + } + catch (Exception failure) + { + // A throw or a timeout that is not caller cancellation: the main search already + // answered for reachability, so this says "holds nothing", never "unreachable". + Log.KnowledgeProbeFailed(binding.Logger, binding.Agent, facet, failure); + + return Publish(probe, KnowledgeNotices.Empty); + } + + return Name(binding, wiring, claimed, probeCards, carriesHistory); } - catch (Exception failure) + finally { - // A throw or a timeout that is not caller cancellation: the main search already - // answered for reachability, so this says "holds nothing", never "unreachable". - Log.KnowledgeProbeFailed(binding.Logger, binding.Agent, facet, failure); - - return Publish(probe, KnowledgeNotices.Empty); + probe.Fail(); } - - return Name(binding, wiring, claimed, probeCards, carriesHistory); } - finally + + /// §8 step 4: the probe's own second search, under the narrowed scope, logged like the main one. + private static async Task> SearchAsync( + KnowledgeBinding binding, + KnowledgeScope narrowedScope, + string query, + CancellationToken deadline) { - probe.Fail(); - } - } + long started = Stopwatch.GetTimestamp(); - /// §8 step 4: the probe's own second search, under the narrowed scope, logged like the main one. - private static async Task> SearchAsync( - KnowledgeBinding binding, - KnowledgeScope narrowedScope, - string query, - CancellationToken deadline) - { - var started = Stopwatch.GetTimestamp(); + IReadOnlyList probeCards = await binding.Port.SearchAsync(query, narrowedScope, deadline).ConfigureAwait(false); - var probeCards = await binding.Port.SearchAsync(query, narrowedScope, deadline).ConfigureAwait(false); + if (binding.Logger.IsEnabled(LogLevel.Debug)) + { + KnowledgeAuditRecord.LogView record = KnowledgeSearchRecord.Of( + binding.Agent, + binding.Knowledge, + query, + narrowedScope, + probeCards, + Stopwatch.GetElapsedTime(started).TotalMilliseconds, + failure: null).ForLog(); + + Log.KnowledgeRetrieved(binding.Logger, binding.Agent, probeCards.Count, record); + } - if (binding.Logger.IsEnabled(LogLevel.Debug)) - { - var record = KnowledgeSearchRecord.Of( - binding.Agent, - binding.Knowledge, - query, - narrowedScope, - probeCards, - Stopwatch.GetElapsedTime(started).TotalMilliseconds, - failure: null).ForLog(); - - Log.KnowledgeRetrieved(binding.Logger, binding.Agent, probeCards.Count, record); + return probeCards; } - return probeCards; - } - - /// K43: replays the outcome of the one probe this turn already claimed. - private static async Task> ReplayAsync( - Clarifications.Probe probe, - KnowledgeAmbiguityConfiguration ambiguity, - CancellationToken cancellationToken) - { - var wait = TimeSpan.FromSeconds(ambiguity.ProbeDeadlineSeconds + ambiguity.ProbeWaitMarginSeconds); - - try + /// K43: replays the outcome of the one probe this turn already claimed. + private static async Task> ReplayAsync( + Clarifications.Probe probe, + KnowledgeAmbiguityConfiguration ambiguity, + CancellationToken cancellationToken) { - return await probe.WaitAsync(wait, cancellationToken).ConfigureAwait(false); + TimeSpan wait = TimeSpan.FromSeconds(ambiguity.ProbeDeadlineSeconds + ambiguity.ProbeWaitMarginSeconds); + + try + { + return await probe.WaitAsync(wait, cancellationToken).ConfigureAwait(false); + } + catch (Exception failure) when (!KnowledgeCancellation.ByCaller(failure, cancellationToken)) + { + // The winner's own search already answered for reachability (§8 step 4's own catch says + // the same thing): a wait that timed out, or a payload the winner failed via Probe.Fail(), + // is never grounds to tell this caller the store is unreachable. + return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; + } } - catch (Exception failure) when (!KnowledgeCancellation.ByCaller(failure, cancellationToken)) + + /// §8 steps 5-6: reads the candidates out of the probe's cards and decides what to say. + private static IReadOnlyList Name( + KnowledgeBinding binding, + ProbeWiring wiring, + ClaimedProbe claimed, + IReadOnlyList probeCards, + bool carriesHistory) { - // The winner's own search already answered for reachability (§8 step 4's own catch says - // the same thing): a wait that timed out, or a payload the winner failed via Probe.Fail(), - // is never grounds to tell this caller the store is unreachable. - return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; - } - } + (Clarifications? clarifications, Clarifications.Probe? probe, string? facet) = claimed; - /// §8 steps 5-6: reads the candidates out of the probe's cards and decides what to say. - private static IReadOnlyList Name( - KnowledgeBinding binding, - ProbeWiring wiring, - ClaimedProbe claimed, - IReadOnlyList probeCards, - bool carriesHistory) - { - var (clarifications, probe, facet) = claimed; + // §8 step 5: the value at the facet's payload path is a string or a list of strings alike — + // the real corpus stores arrays, and a cast straight to string would silently return null for + // every card on a multi-model collection. + string path = wiring.Template.Resolve(facet); + SortedSet union = new(StringComparer.Ordinal); - // §8 step 5: the value at the facet's payload path is a string or a list of strings alike — - // the real corpus stores arrays, and a cast straight to string would silently return null for - // every card on a multi-model collection. - var path = wiring.Template.Resolve(facet); - SortedSet union = new(StringComparer.Ordinal); + union.UnionWith(probeCards + .SelectMany(card => FacetValues(card, path)) + .Where(value => !string.Equals(value, wiring.WildcardValue, StringComparison.Ordinal))); - union.UnionWith(probeCards - .SelectMany(card => FacetValues(card, path)) - .Where(value => !string.Equals(value, wiring.WildcardValue, StringComparison.Ordinal))); + Log.KnowledgeProbeRan(binding.Logger, binding.Agent, facet, union.Count); - Log.KnowledgeProbeRan(binding.Logger, binding.Agent, facet, union.Count); + if (union.Count == 0) + { + return Publish(probe, KnowledgeNotices.Empty); + } - if (union.Count == 0) - { - return Publish(probe, KnowledgeNotices.Empty); - } + // §8 step 6. probeAsks was already advanced in step 4; nothing below chooses anything but the + // message. + Clarifications.LastNamed wouldName = Clarifications.LastNamed.For(union, wiring.Ambiguity.MaxCandidates); + List candidates = [.. union]; - // §8 step 6. probeAsks was already advanced in step 4; nothing below chooses anything but the - // message. - var wouldName = Clarifications.LastNamed.For(union, wiring.Ambiguity.MaxCandidates); - var candidates = union.ToList(); + // K39, drawn for the record rather than for the message: on a graph row AgentCore cannot know + // whether the participant's own tool result ever reached the caller, so the note still goes + // out, but the record of what was named — which arms K21's tie-break — does not. The flag + // arrives as a parameter because the probe runs inside a search delegate that is never + // handed a session to compare. - // K39, drawn for the record rather than for the message: on a graph row AgentCore cannot know - // whether the participant's own tool result ever reached the caller, so the note still goes - // out, but the record of what was named — which arms K21's tie-break — does not. The flag - // arrives as a parameter because the probe runs inside a search delegate that is never - // handed a session to compare. + // Whether the note repeats what was last named, and the record that follows from it, are one + // transition under one lock acquisition. Deciding from an earlier Read() and writing after + // would let a concurrent participant on the same conversation slip between the two. + bool repeats = false; - // Whether the note repeats what was last named, and the record that follows from it, are one - // transition under one lock acquisition. Deciding from an earlier Read() and writing after - // would let a concurrent participant on the same conversation slip between the two. - var repeats = false; + clarifications.Update(facet, s => + { + repeats = wouldName.Names(s.LastNamed); - clarifications.Update(facet, s => - { - repeats = wouldName.Names(s.LastNamed); + if (!repeats && carriesHistory) + { + s.LastNamed = wouldName; + } + }); - if (!repeats && carriesHistory) + if (repeats) { - s.LastNamed = wouldName; + return Publish(probe, KnowledgeNotices.Empty); } - }); - - if (repeats) - { - return Publish(probe, KnowledgeNotices.Empty); - } - - var description = ClarificationText.DescriptionOf(facet, wiring.SlotDescriptions); - return Publish(probe, ClarificationText.Note(description, candidates, wiring.Ambiguity.MaxCandidates)); - } + string description = ClarificationText.DescriptionOf(facet, wiring.SlotDescriptions); - /// Hands one notice to this caller and to every other search in the turn alike. - private static IReadOnlyList Publish( - Clarifications.Probe probe, string text) - { - IReadOnlyList outcome = [KnowledgeNotices.Of(text)]; - probe.Publish(outcome); - return outcome; - } + return Publish(probe, ClarificationText.Note(description, candidates, wiring.Ambiguity.MaxCandidates)); + } - /// - /// §8 step 3: the first facet, in fromState declaration order, the wildcard filled and that - /// dropping would not empty the scope or skip a slot at its ask cap. - /// - private static string? DroppableFacet(ProbeWiring wiring, KnowledgeScope scope, Clarifications clarifications) - { - // K33: the scope's only facet is undroppable — opening it empty is what a scoped store - // refuses. This holds for every candidate alike, so no candidate can be droppable at all. - if (scope.Facets.Count <= 1) + /// Hands one notice to this caller and to every other search in the turn alike. + private static IReadOnlyList Publish( + Clarifications.Probe probe, string text) { - return null; + IReadOnlyList outcome = [KnowledgeNotices.Of(text)]; + probe.Publish(outcome); + return outcome; } - foreach (var name in wiring.FromState) + /// + /// §8 step 3: the first facet, in fromState declaration order, the wildcard filled and that + /// dropping would not empty the scope or skip a slot at its ask cap. + /// + private static string? DroppableFacet(ProbeWiring wiring, KnowledgeScope scope, Clarifications clarifications) { - // K14: the wildcard filled it — its value is the wildcard's own, and the facet is named - // among the ones the wildcard is allowed to widen. Origins overrules the value where it - // has an entry: a host that pinned a facet to the wildcard literal meant "every value of - // it", and widening that facet would overrule an instruction rather than recover a lost - // one. A scope composed without origins carries none, so an absent entry falls back to - // the value alone. - if (!wiring.WildcardFacets.Contains(name, StringComparer.Ordinal) - || !scope.Facets.TryGetValue(name, out var value) - || !string.Equals(value, wiring.WildcardValue, StringComparison.Ordinal) - || (scope.Origins.TryGetValue(name, out var origin) - && origin != KnowledgeFacetOrigin.Wildcard)) + // K33: the scope's only facet is undroppable — opening it empty is what a scoped store + // refuses. This holds for every candidate alike, so no candidate can be droppable at all. + if (scope.Facets.Count <= 1) { - continue; + return null; } - // K22: the probe's own counter is monotone and capped at maxAsks. - if (clarifications.Read(name).ProbeAsks >= wiring.Ambiguity.MaxAsks) + foreach (string name in wiring.FromState) { - continue; - } - - return name; - } + // K14: the wildcard filled it — its value is the wildcard's own, and the facet is named + // among the ones the wildcard is allowed to widen. Origins overrules the value where it + // has an entry: a host that pinned a facet to the wildcard literal meant "every value of + // it", and widening that facet would overrule an instruction rather than recover a lost + // one. A scope composed without origins carries none, so an absent entry falls back to + // the value alone. + if (!wiring.WildcardFacets.Contains(name, StringComparer.Ordinal) + || !scope.Facets.TryGetValue(name, out string? value) + || !string.Equals(value, wiring.WildcardValue, StringComparison.Ordinal) + || (scope.Origins.TryGetValue(name, out KnowledgeFacetOrigin origin) + && origin != KnowledgeFacetOrigin.Wildcard)) + { + continue; + } - return null; - } + // K22: the probe's own counter is monotone and capped at maxAsks. + if (clarifications.Read(name).ProbeAsks >= wiring.Ambiguity.MaxAsks) + { + continue; + } - /// Opens the same scope with one facet removed, for §8 step 4's second search. - /// The scope the main search ran under. - /// The facet to drop. - /// The narrowed scope. - /// - /// Each map keeps its own comparer. Rebuilding on a fixed ordinal comparer would narrow how a - /// case-insensitive caller's facets match, so the second search would run under different matching - /// rules than the first. Origins loses the facet alongside Facets, because it describes what the - /// query actually filters on — a retrieval record built from a scope that kept it would name a - /// facet the probe's search never constrained. - /// - private static KnowledgeScope WithoutFacet(KnowledgeScope scope, string facet) - { - Dictionary facets = new(scope.Facets, ComparerOf(scope.Facets)); - facets.Remove(facet); + return name; + } - Dictionary origins = new(scope.Origins, ComparerOf(scope.Origins)); - origins.Remove(facet); + return null; + } - return scope with { Facets = facets, Origins = origins }; - } + /// Opens the same scope with one facet removed, for §8 step 4's second search. + /// The scope the main search ran under. + /// The facet to drop. + /// The narrowed scope. + /// + /// Each map keeps its own comparer. Rebuilding on a fixed ordinal comparer would narrow how a + /// case-insensitive caller's facets match, so the second search would run under different matching + /// rules than the first. Origins loses the facet alongside Facets, because it describes what the + /// query actually filters on — a retrieval record built from a scope that kept it would name a + /// facet the probe's search never constrained. + /// + private static KnowledgeScope WithoutFacet(KnowledgeScope scope, string facet) + { + Dictionary facets = new(scope.Facets, ComparerOf(scope.Facets)); + _ = facets.Remove(facet); - /// Reads back the comparer a scope's map was built on, or ordinal when it cannot be seen. - private static IEqualityComparer ComparerOf(IReadOnlyDictionary map) - => map is Dictionary concrete ? concrete.Comparer : StringComparer.Ordinal; + Dictionary origins = new(scope.Origins, ComparerOf(scope.Origins)); + _ = origins.Remove(facet); - /// - /// §8 step 5: walks a dotted path into one card's Extras, reading a string or a list of - /// strings alike — the shape QdrantPointConverter gives a Qdrant scalar or list value. - /// - private static IEnumerable FacetValues(KnowledgeCard card, string path) - { - var current = PayloadPath.Read(card.Extras, path); + return scope with { Facets = facets, Origins = origins }; + } - if (current is string single) + /// Reads back the comparer a scope's map was built on, or ordinal when it cannot be seen. + private static IEqualityComparer ComparerOf(IReadOnlyDictionary map) { - yield return single; - yield break; + return map is Dictionary concrete ? concrete.Comparer : StringComparer.Ordinal; } - if (current is IReadOnlyList many) + /// + /// §8 step 5: walks a dotted path into one card's Extras, reading a string or a list of + /// strings alike — the shape QdrantPointConverter gives a Qdrant scalar or list value. + /// + private static IEnumerable FacetValues(KnowledgeCard card, string path) { - foreach (var item in many) + object? current = PayloadPath.Read(card.Extras, path); + + if (current is string single) + { + yield return single; + yield break; + } + + if (current is IReadOnlyList many) { - if (item is string text) + foreach (object? item in many) { - yield return text; + if (item is string text) + { + yield return text; + } } } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs b/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs index 70b66529..8d0abf74 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs @@ -5,74 +5,74 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Knowledge; - -/// -/// Binds one agent's resolved knowledge: block to the framework's retrieval seam. -/// -internal static class KnowledgeProviderFactory +namespace AgentCore.Application.Knowledge { - - /// Builds the provider one agent binds. - /// The store every agent shares. - /// The agent's resolved knowledge: block. - /// The id of the agent this provider hangs on, for the log line. - /// The wording providers.knowledge.citation named. - /// - /// Where the retrieval record and the framework's own provider log go, or - /// when the host wired none. Ruling 21: this is the one reachable observability seam — the audit - /// sink is not, because AuditEvent requires a conversation id and a sequence number that this - /// seam doesn't carry down here. - /// - /// The document's providers.knowledge.scope block, or . - /// The provider to hang on that agent. - /// A required argument is . - internal static AIContextProvider Create( - IKnowledgeRetrievalPort port, - ResolvedKnowledge knowledge, - string agent, - IKnowledgeCitationFormatter citations, - ILoggerFactory? loggers, - KnowledgeScopeConfiguration? scope = null) + /// + /// Binds one agent's resolved knowledge: block to the framework's retrieval seam. + /// + internal static class KnowledgeProviderFactory { - ArgumentNullException.ThrowIfNull(port); - ArgumentNullException.ThrowIfNull(knowledge); - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(citations); - - var logger = loggers?.CreateLogger(typeof(KnowledgeProviderFactory)) ?? NullLogger.Instance; - TextSearchProviderOptions options = new() + /// Builds the provider one agent binds. + /// The store every agent shares. + /// The agent's resolved knowledge: block. + /// The id of the agent this provider hangs on, for the log line. + /// The wording providers.knowledge.citation named. + /// + /// Where the retrieval record and the framework's own provider log go, or + /// when the host wired none. Ruling 21: this is the one reachable observability seam — the audit + /// sink is not, because AuditEvent requires a conversation id and a sequence number that this + /// seam doesn't carry down here. + /// + /// The document's providers.knowledge.scope block, or . + /// The provider to hang on that agent. + /// A required argument is . + internal static AIContextProvider Create( + IKnowledgeRetrievalPort port, + ResolvedKnowledge knowledge, + string agent, + IKnowledgeCitationFormatter citations, + ILoggerFactory? loggers, + KnowledgeScopeConfiguration? scope = null) { - SearchTime = knowledge.Mode == KnowledgeMode.Tool - ? TextSearchProviderOptions.TextSearchBehavior.OnDemandFunctionCalling - : TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke, + ArgumentNullException.ThrowIfNull(port); + ArgumentNullException.ThrowIfNull(knowledge); + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(citations); - CitationsPrompt = knowledge.Citations - ? "Name the source document when you use it. Do not invent a link." - : string.Empty, + ILogger logger = loggers?.CreateLogger(typeof(KnowledgeProviderFactory)) ?? NullLogger.Instance; - RecentMessageMemoryLimit = 4, - }; + TextSearchProviderOptions options = new() + { + SearchTime = knowledge.Mode == KnowledgeMode.Tool + ? TextSearchProviderOptions.TextSearchBehavior.OnDemandFunctionCalling + : TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke, - KnowledgeSearch.Core core = KnowledgeSearch.Bind(new KnowledgeBinding(port, knowledge, agent, citations, logger)); + CitationsPrompt = knowledge.Citations + ? "Name the source document when you use it. Do not invent a link." + : string.Empty, - // The template's own delegate never runs: tool-mode searches go through the - // invocation-bound wrapper, prefetch through per-invocation providers. It fails - // loudly if either path ever leaks through. - AIContextProvider template = new TextSearchProvider(UnreachableSearch, options, loggers); + RecentMessageMemoryLimit = 4, + }; - if (knowledge.Mode != KnowledgeMode.Tool) - { - return new KnowledgePrefetchProvider(template, options, loggers, core); + KnowledgeSearch.Core core = KnowledgeSearch.Bind(new KnowledgeBinding(port, knowledge, agent, citations, logger)); + + // The template's own delegate never runs: tool-mode searches go through the + // invocation-bound wrapper, prefetch through per-invocation providers. It fails + // loudly if either path ever leaks through. + AIContextProvider template = new TextSearchProvider(UnreachableSearch, options, loggers); + + return knowledge.Mode != KnowledgeMode.Tool + ? new KnowledgePrefetchProvider(template, options, loggers, core) + : new FacetFilterProvider(template, scope?.Filterable, core); } - return new FacetFilterProvider(template, scope?.Filterable, core); + private static Task> UnreachableSearch( + string query, CancellationToken cancellationToken) + { + return Task.FromException>( + new InvalidOperationException( + "A knowledge search ran outside its turn. Searches run through the turn's own provider or tool.")); + } } - - private static Task> UnreachableSearch( - string query, CancellationToken cancellationToken) - => Task.FromException>( - new InvalidOperationException( - "A knowledge search ran outside its turn. Searches run through the turn's own provider or tool.")); } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeRetrievalPortExtensions.cs b/src/AgentCore.Application/Knowledge/KnowledgeRetrievalPortExtensions.cs index a3000947..9826c27b 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeRetrievalPortExtensions.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeRetrievalPortExtensions.cs @@ -1,22 +1,23 @@ using AgentCore.Application.Ports; -namespace AgentCore.Application.Knowledge; - -/// -/// Typed helpers over . -/// -public static class KnowledgeRetrievalPortExtensions +namespace AgentCore.Application.Knowledge { - /// Asks one store for a capability it may also serve. - /// The capability being asked for. - /// The store to ask. - /// Names one of several, when a store serves more than one. - /// The capability, or when this store does not serve it. - /// is . - public static TService? GetService(this IKnowledgeRetrievalPort port, object? serviceKey = null) + /// + /// Typed helpers over . + /// + public static class KnowledgeRetrievalPortExtensions { - ArgumentNullException.ThrowIfNull(port); + /// Asks one store for a capability it may also serve. + /// The capability being asked for. + /// The store to ask. + /// Names one of several, when a store serves more than one. + /// The capability, or when this store does not serve it. + /// is . + public static TService? GetService(this IKnowledgeRetrievalPort port, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(port); - return port.GetService(typeof(TService), serviceKey) is TService service ? service : default; + return port.GetService(typeof(TService), serviceKey) is TService service ? service : default; + } } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeSearch.cs b/src/AgentCore.Application/Knowledge/KnowledgeSearch.cs index 9aeb80b6..99ed719d 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeSearch.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeSearch.cs @@ -9,185 +9,186 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Knowledge; - -// One search against the store with everything the turn hands it, as explicit values: the -// scope to read under, the tool-call facets to overlay, and the turn's own probe, history -// flag and citation port. The framework invokes the search in two shapes — a tool call -// carrying arguments, and a prefetch carrying only a session — and both bind those shapes -// to these values before calling here, so this core never reads the flow. -internal static class KnowledgeSearch +namespace AgentCore.Application.Knowledge { - /// Searches with an explicit scope, facets and turn. - internal delegate Task> Core( - string query, - IReadOnlyDictionary? facets, - TurnInvocation? turn, - CancellationToken cancellationToken); - - /// The scope an agent that declares scoped: false searches under. - internal static readonly KnowledgeScope WholeCorpus = - new() { Facets = new Dictionary(StringComparer.Ordinal) }; - - /// Binds the core to one agent's port, wiring and loggers. - internal static Core Bind(KnowledgeBinding binding) + // One search against the store with everything the turn hands it, as explicit values: the + // scope to read under, the tool-call facets to overlay, and the turn's own probe, history + // flag and citation port. The framework invokes the search in two shapes — a tool call + // carrying arguments, and a prefetch carrying only a session — and both bind those shapes + // to these values before calling here, so this core never reads the flow. + internal static class KnowledgeSearch { - ArgumentNullException.ThrowIfNull(binding); - - return (query, facets, turn, cancellationToken) => RunAsync(binding, query, facets, turn, cancellationToken); - } - - private static async Task> RunAsync( - KnowledgeBinding binding, - string query, - IReadOnlyDictionary? facets, - TurnInvocation? turn, - CancellationToken cancellationToken) - { - var (port, knowledge, agent, citations, logger) = binding; + /// Searches with an explicit scope, facets and turn. + internal delegate Task> Core( + string query, + IReadOnlyDictionary? facets, + TurnInvocation? turn, + CancellationToken cancellationToken); + + /// The scope an agent that declares scoped: false searches under. + internal static readonly KnowledgeScope WholeCorpus = + new() { Facets = new Dictionary(StringComparer.Ordinal) }; + + /// Binds the core to one agent's port, wiring and loggers. + internal static Core Bind(KnowledgeBinding binding) + { + ArgumentNullException.ThrowIfNull(binding); - // No scope filters nothing, so it is the absent scope in disguise. The shared store - // can only fail closed when EVERY agent is scoped, so in a mixed deployment this is - // the only check standing between a scoped agent and every customer's cards. A null - // turn — a framework-driven sub-run (graph node, background child) the loop never - // invoked — searches the whole corpus unscoped and names NoScope scoped: loud, never - // a leak. - var composed = knowledge.Scoped ? turn?.Knowledge : WholeCorpus; + return (query, facets, turn, cancellationToken) => RunAsync(binding, query, facets, turn, cancellationToken); + } - if (knowledge.Scoped && composed is not { Facets.Count: > 0 }) + private static async Task> RunAsync( + KnowledgeBinding binding, + string query, + IReadOnlyDictionary? facets, + TurnInvocation? turn, + CancellationToken cancellationToken) { - return [KnowledgeNotices.Of(KnowledgeNotices.NoScope)]; - } + (IKnowledgeRetrievalPort? port, ResolvedKnowledge? knowledge, string? agent, IKnowledgeCitationFormatter? citations, ILogger? logger) = binding; - var scope = composed ?? WholeCorpus; + // No scope filters nothing, so it is the absent scope in disguise. The shared store + // can only fail closed when EVERY agent is scoped, so in a mixed deployment this is + // the only check standing between a scoped agent and every customer's cards. A null + // turn — a framework-driven sub-run (graph node, background child) the loop never + // invoked — searches the whole corpus unscoped and names NoScope scoped: loud, never + // a leak. + KnowledgeScope? composed = knowledge.Scoped ? turn?.Knowledge : WholeCorpus; - var (narrowed, byTool) = ToolFacetOverlay.Apply(scope, facets); + if (knowledge.Scoped && composed is not { Facets.Count: > 0 }) + { + return [KnowledgeNotices.Of(KnowledgeNotices.NoScope)]; + } - var started = Stopwatch.GetTimestamp(); + KnowledgeScope scope = composed ?? WholeCorpus; - double? searched = null; - var under = narrowed; + (KnowledgeScope? narrowed, bool byTool) = ToolFacetOverlay.Apply(scope, facets); - try - { - var (cards, latency) = await Under(narrowed).ConfigureAwait(false); - searched = latency; + long started = Stopwatch.GetTimestamp(); - if (cards.Count == 0 && byTool) + double? searched = null; + KnowledgeScope under = narrowed; + + try { - under = scope; - (cards, _) = await Under(scope).ConfigureAwait(false); + (IReadOnlyList? cards, double latency) = await Under(narrowed).ConfigureAwait(false); + searched = latency; + + if (cards.Count == 0 && byTool) + { + under = scope; + (cards, _) = await Under(scope).ConfigureAwait(false); + } + + if (cards.Count == 0 + && knowledge.Mode == KnowledgeMode.Tool + && under.Facets.Count > 0) + { + return await KnowledgeProbe + .RunAsync(binding, under, query, turn?.Clarifications, turn?.CarriesHistory ?? false, cancellationToken) + .ConfigureAwait(false); + } + + List shown = Kept(cards, knowledge); + Cite(shown, knowledge, citations, turn?.Sources); + + return Map(shown, knowledge, citations); } - - if (cards.Count == 0 - && knowledge.Mode == KnowledgeMode.Tool - && under.Facets.Count > 0) + catch (Exception failure) when (!KnowledgeCancellation.ByCaller(failure, cancellationToken)) { - return await KnowledgeProbe - .RunAsync(binding, under, query, turn?.Clarifications, turn?.CarriesHistory ?? false, cancellationToken) - .ConfigureAwait(false); + double latency = searched ?? Stopwatch.GetElapsedTime(started).TotalMilliseconds; + KnowledgeAuditRecord.LogView record = KnowledgeSearchRecord + .Of(agent, knowledge, query, under, [], latency, failure) + .ForLog(); + + Log.KnowledgeRetrievalFailed(logger, agent, record, failure); + + return [KnowledgeNotices.Of(KnowledgeNotices.Unreachable)]; } - var shown = Kept(cards, knowledge); - Cite(shown, knowledge, citations, turn?.Sources); + async Task<(IReadOnlyList Cards, double LatencyMs)> Under(KnowledgeScope open) + { + IReadOnlyList cards = await port.SearchAsync(query, open, cancellationToken).ConfigureAwait(false); - return Map(shown, knowledge, citations); - } - catch (Exception failure) when (!KnowledgeCancellation.ByCaller(failure, cancellationToken)) - { - var latency = searched ?? Stopwatch.GetElapsedTime(started).TotalMilliseconds; - var record = KnowledgeSearchRecord - .Of(agent, knowledge, query, under, [], latency, failure) - .ForLog(); + double latency = Stopwatch.GetElapsedTime(started).TotalMilliseconds; + + if (logger.IsEnabled(LogLevel.Debug)) + { + KnowledgeAuditRecord.LogView record = KnowledgeSearchRecord + .Of(agent, knowledge, query, open, cards, latency, failure: null) + .ForLog(); - Log.KnowledgeRetrievalFailed(logger, agent, record, failure); + Log.KnowledgeRetrieved(logger, agent, cards.Count, record); + } - return [KnowledgeNotices.Of(KnowledgeNotices.Unreachable)]; + return (cards, latency); + } } - async Task<(IReadOnlyList Cards, double LatencyMs)> Under(KnowledgeScope open) + /// Cuts one search down to the agent's limit:. + /// What the store returned, best first, links last. + /// The agent's resolved knowledge: block. + /// The cards this agent is shown. + private static List Kept(IReadOnlyList cards, ResolvedKnowledge knowledge) { - var cards = await port.SearchAsync(query, open, cancellationToken).ConfigureAwait(false); - - var latency = Stopwatch.GetElapsedTime(started).TotalMilliseconds; + List kept = []; + int ranked = 0; - if (logger.IsEnabled(LogLevel.Debug)) + foreach (KnowledgeCard card in cards) { - var record = KnowledgeSearchRecord - .Of(agent, knowledge, query, open, cards, latency, failure: null) - .ForLog(); + if (!card.ViaLink && ranked++ >= knowledge.Limit) + { + continue; + } - Log.KnowledgeRetrieved(logger, agent, cards.Count, record); + kept.Add(card); } - return (cards, latency); + return kept; } - } - - /// Cuts one search down to the agent's limit:. - /// What the store returned, best first, links last. - /// The agent's resolved knowledge: block. - /// The cards this agent is shown. - private static List Kept(IReadOnlyList cards, ResolvedKnowledge knowledge) - { - List kept = []; - var ranked = 0; - foreach (var card in cards) + /// Cites what this search read, for the caller's screen. + /// The cards the agent is actually shown, after cuts the search down to the agent's limit: — not everything the store returned. + /// The agent's resolved knowledge: block. + /// The wording providers.knowledge.citation named. + /// What the turn cites into, or outside a turn. + private static void Cite( + IReadOnlyList cards, + ResolvedKnowledge knowledge, + IKnowledgeCitationFormatter citations, + TurnSources? port) { - if (!card.ViaLink && ranked++ >= knowledge.Limit) + if (!knowledge.Citations || port is null) { - continue; + return; } - kept.Add(card); + foreach (KnowledgeCard card in cards) + { + if (KnowledgeSourceMapper.ToSource(card, citations) is { } source) + { + port.Publish(source); + } + } } - return kept; - } - - /// Cites what this search read, for the caller's screen. - /// The cards the agent is actually shown, after cuts the search down to the agent's limit: — not everything the store returned. - /// The agent's resolved knowledge: block. - /// The wording providers.knowledge.citation named. - /// What the turn cites into, or outside a turn. - private static void Cite( - IReadOnlyList cards, - ResolvedKnowledge knowledge, - IKnowledgeCitationFormatter citations, - TurnSources? port) - { - if (!knowledge.Citations || port is null) + /// Maps the cards this agent is shown into what the framework injects. + /// The cards already cut down to the agent's limit:. + /// The agent's resolved knowledge: block. + /// The wording each card's source label is written in. + /// The results the framework injects. + private static List Map( + IReadOnlyList cards, + ResolvedKnowledge knowledge, + IKnowledgeCitationFormatter citations) { - return; - } + List mapped = []; - foreach (var card in cards) - { - if (KnowledgeSourceMapper.ToSource(card, citations) is { } source) + foreach (KnowledgeCard card in cards) { - port.Publish(source); + mapped.Add(KnowledgeCardMapper.ToResult(card, knowledge.Citations, citations)); } - } - } - /// Maps the cards this agent is shown into what the framework injects. - /// The cards already cut down to the agent's limit:. - /// The agent's resolved knowledge: block. - /// The wording each card's source label is written in. - /// The results the framework injects. - private static List Map( - IReadOnlyList cards, - ResolvedKnowledge knowledge, - IKnowledgeCitationFormatter citations) - { - List mapped = []; - - foreach (var card in cards) - { - mapped.Add(KnowledgeCardMapper.ToResult(card, knowledge.Citations, citations)); + return mapped; } - - return mapped; } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs b/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs index 512f0663..3bdf77df 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs @@ -1,36 +1,39 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Reads one finished store call into the record an operator debugs an outage from. -/// -internal static class KnowledgeSearchRecord +namespace AgentCore.Application.Knowledge { - /// Builds the record. - /// The id of the agent that asked. - /// The agent's resolved knowledge: block. - /// The search text the framework composed. - /// The scope the store call ran under. - /// What the store returned, or empty when it threw. - /// How long that one store call took, in milliseconds. - /// What the port threw, or when it answered. - /// The record. - internal static KnowledgeAuditRecord Of( - string agent, - ResolvedKnowledge knowledge, - string query, - KnowledgeScope? scope, - IReadOnlyList cards, - double latencyMs, - Exception? failure) - => KnowledgeAuditRecord.For( - agent, - knowledge.Mode, - query, - scope, - cards, - latencyMs, - failure); + /// + /// Reads one finished store call into the record an operator debugs an outage from. + /// + internal static class KnowledgeSearchRecord + { + /// Builds the record. + /// The id of the agent that asked. + /// The agent's resolved knowledge: block. + /// The search text the framework composed. + /// The scope the store call ran under. + /// What the store returned, or empty when it threw. + /// How long that one store call took, in milliseconds. + /// What the port threw, or when it answered. + /// The record. + internal static KnowledgeAuditRecord Of( + string agent, + ResolvedKnowledge knowledge, + string query, + KnowledgeScope? scope, + IReadOnlyList cards, + double latencyMs, + Exception? failure) + { + return KnowledgeAuditRecord.For( + agent, + knowledge.Mode, + query, + scope, + cards, + latencyMs, + failure); + } + } } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeSourceMapper.cs b/src/AgentCore.Application/Knowledge/KnowledgeSourceMapper.cs index abf2e325..859e2cf3 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeSourceMapper.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeSourceMapper.cs @@ -1,40 +1,38 @@ using AgentCore.Domain.Knowledge; using AgentCore.Domain.Sources; -namespace AgentCore.Application.Knowledge; - -/// -/// Turns a card into the chip the caller sees, using the same label the model was shown. -/// -internal static class KnowledgeSourceMapper +namespace AgentCore.Application.Knowledge { - /// What says for a card. A wire value. - internal const string KnowledgeOrigin = "knowledge"; - - /// Maps one card, or cites nothing for it. - /// The card the store returned. - /// The wording providers.knowledge.citation named. - /// The source, or when the formatter cites nothing. - /// A required argument is . - internal static SourceReference? ToSource(KnowledgeCard card, IKnowledgeCitationFormatter formatter) + /// + /// Turns a card into the chip the caller sees, using the same label the model was shown. + /// + internal static class KnowledgeSourceMapper { - ArgumentNullException.ThrowIfNull(card); - ArgumentNullException.ThrowIfNull(formatter); + /// What says for a card. A wire value. + internal const string KnowledgeOrigin = "knowledge"; - var label = formatter.Format(card); - - if (label is not { Length: > 0 } || label.Trim().Length == 0) + /// Maps one card, or cites nothing for it. + /// The card the store returned. + /// The wording providers.knowledge.citation named. + /// The source, or when the formatter cites nothing. + /// A required argument is . + internal static SourceReference? ToSource(KnowledgeCard card, IKnowledgeCitationFormatter formatter) { - return null; - } + ArgumentNullException.ThrowIfNull(card); + ArgumentNullException.ThrowIfNull(formatter); - return new SourceReference - { - SourceId = card.CardId, - Kind = SourceKind.Document, - Title = label, - Origin = KnowledgeOrigin, - Locator = card.SourceLocator, - }; + string? label = formatter.Format(card); + + return label is not { Length: > 0 } || label.Trim().Length == 0 + ? null + : new SourceReference + { + SourceId = card.CardId, + Kind = SourceKind.Document, + Title = label, + Origin = KnowledgeOrigin, + Locator = card.SourceLocator, + }; + } } } diff --git a/src/AgentCore.Application/Knowledge/NoQueryAnalyzer.cs b/src/AgentCore.Application/Knowledge/NoQueryAnalyzer.cs index ac4f9c3d..d1ce68ac 100644 --- a/src/AgentCore.Application/Knowledge/NoQueryAnalyzer.cs +++ b/src/AgentCore.Application/Knowledge/NoQueryAnalyzer.cs @@ -1,20 +1,21 @@ -namespace AgentCore.Application.Knowledge; - -/// Requires nothing, so vector similarity alone decides. -public sealed class NoQueryAnalyzer : IKnowledgeQueryAnalyzer +namespace AgentCore.Application.Knowledge { - /// The name providers.knowledge.analyzer selects this by. - public const string AnalyzerName = "none"; + /// Requires nothing, so vector similarity alone decides. + public sealed class NoQueryAnalyzer : IKnowledgeQueryAnalyzer + { + /// The name providers.knowledge.analyzer selects this by. + public const string AnalyzerName = "none"; - /// - public string Name => AnalyzerName; + /// + public string Name => AnalyzerName; - /// - /// is . - public IReadOnlyList RequiredTerms(string query) - { - ArgumentNullException.ThrowIfNull(query); + /// + /// is . + public IReadOnlyList RequiredTerms(string query) + { + ArgumentNullException.ThrowIfNull(query); - return []; + return []; + } } } diff --git a/src/AgentCore.Application/Knowledge/ProbeWiring.cs b/src/AgentCore.Application/Knowledge/ProbeWiring.cs index 096ecdd4..edc451cf 100644 --- a/src/AgentCore.Application/Knowledge/ProbeWiring.cs +++ b/src/AgentCore.Application/Knowledge/ProbeWiring.cs @@ -2,31 +2,34 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Knowledge; - -/// The ambiguity wiring the probe runs on, with every part it needs present. -/// How the search asks the caller which value they meant. -/// The payload value that satisfies any scope on a wildcard facet. -/// The facet keys widens. -/// The payload path each facet key becomes. -/// The fromState slots, in declaration order. -/// Each slot's description, keyed by slot name. -internal sealed record ProbeWiring( - KnowledgeAmbiguityConfiguration Ambiguity, - string WildcardValue, - IReadOnlyList WildcardFacets, - ScopeTemplate Template, - IReadOnlyList FromState, - IReadOnlyDictionary SlotDescriptions) +namespace AgentCore.Application.Knowledge { - /// Reads the probe's wiring off the document's, or answers when the probe cannot run. - /// - /// K19: with no ambiguity: configured (and so no wildcard, since the validator requires one - /// alongside the other) there is nothing for the probe to drop, and behaviour stays byte-identical - /// to the wildcard plan's own "holds nothing" notice. - /// - public static ProbeWiring? From(ResolvedClarification wiring) - => wiring is { Ambiguity: { } ambiguity, WildcardValue: { } wildcardValue, WildcardFacets: { Count: > 0 } wildcardFacets, Template: { } template } - ? new(ambiguity, wildcardValue, wildcardFacets, template, wiring.FromState, wiring.SlotDescriptions) - : null; + /// The ambiguity wiring the probe runs on, with every part it needs present. + /// How the search asks the caller which value they meant. + /// The payload value that satisfies any scope on a wildcard facet. + /// The facet keys widens. + /// The payload path each facet key becomes. + /// The fromState slots, in declaration order. + /// Each slot's description, keyed by slot name. + internal sealed record ProbeWiring( + KnowledgeAmbiguityConfiguration Ambiguity, + string WildcardValue, + IReadOnlyList WildcardFacets, + ScopeTemplate Template, + IReadOnlyList FromState, + IReadOnlyDictionary SlotDescriptions) + { + /// Reads the probe's wiring off the document's, or answers when the probe cannot run. + /// + /// K19: with no ambiguity: configured (and so no wildcard, since the validator requires one + /// alongside the other) there is nothing for the probe to drop, and behaviour stays byte-identical + /// to the wildcard plan's own "holds nothing" notice. + /// + public static ProbeWiring? From(ResolvedClarification wiring) + { + return wiring is { Ambiguity: { } ambiguity, WildcardValue: { } wildcardValue, WildcardFacets: { Count: > 0 } wildcardFacets, Template: { } template } + ? new(ambiguity, wildcardValue, wildcardFacets, template, wiring.FromState, wiring.SlotDescriptions) + : null; + } + } } diff --git a/src/AgentCore.Application/Knowledge/SourceLocatorCitationFormatter.cs b/src/AgentCore.Application/Knowledge/SourceLocatorCitationFormatter.cs index ac1dc031..7fd89b01 100644 --- a/src/AgentCore.Application/Knowledge/SourceLocatorCitationFormatter.cs +++ b/src/AgentCore.Application/Knowledge/SourceLocatorCitationFormatter.cs @@ -1,42 +1,39 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Writes the source and the locator, joined by a comma: <source>, <locator>. -/// -/// -/// The shipped formatter, and the one providers.knowledge.citation takes when a document -/// names none. It reads only the two roles fields.source and fields.locator map, so a -/// collection that maps neither cites nothing rather than citing something wrong. -/// -public sealed class SourceLocatorCitationFormatter : IKnowledgeCitationFormatter +namespace AgentCore.Application.Knowledge { - /// The name providers.knowledge.citation selects this by. - public const string FormatterName = "source-locator"; - - /// - public string Name => FormatterName; - - /// - /// is . - public string? Format(KnowledgeCard card) + /// + /// Writes the source and the locator, joined by a comma: <source>, <locator>. + /// + /// + /// The shipped formatter, and the one providers.knowledge.citation takes when a document + /// names none. It reads only the two roles fields.source and fields.locator map, so a + /// collection that maps neither cites nothing rather than citing something wrong. + /// + public sealed class SourceLocatorCitationFormatter : IKnowledgeCitationFormatter { - ArgumentNullException.ThrowIfNull(card); + /// The name providers.knowledge.citation selects this by. + public const string FormatterName = "source-locator"; - var hasRef = card.SourceRef.Length > 0; - var hasLocator = card.SourceLocator.Length > 0; + /// + public string Name => FormatterName; - if (hasRef && hasLocator) + /// + /// is . + public string? Format(KnowledgeCard card) { - return $"{card.SourceRef}, {card.SourceLocator}"; + ArgumentNullException.ThrowIfNull(card); + + bool hasRef = card.SourceRef.Length > 0; + bool hasLocator = card.SourceLocator.Length > 0; + + return (hasRef, hasLocator) switch + { + (true, true) => $"{card.SourceRef}, {card.SourceLocator}", + (true, false) => card.SourceRef, + (false, true) => card.SourceLocator, + (false, false) => null, + }; } - - if (hasRef) - { - return card.SourceRef; - } - - return hasLocator ? card.SourceLocator : null; } } diff --git a/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs b/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs index ab3fe317..fd782bed 100644 --- a/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs +++ b/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs @@ -3,85 +3,86 @@ using AgentCore.Application.State; using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Turns what the extractor has learned into the scope one turn searches under. -/// -internal static class StateKnowledgeScope +namespace AgentCore.Application.Knowledge { - /// Composes the turn's scope from the host's scope and the conversation's state. - /// The state of the conversation, as it stands at the start of this turn. - /// The document's providers.knowledge.scope block, or null. - /// What the host set for this conversation, or null when it set nothing. - /// The scope, or unchanged when this document composes none. - internal static KnowledgeScope? Compose( - StateDocument state, KnowledgeScopeConfiguration? scope, KnowledgeScope? hostScope) + /// + /// Turns what the extractor has learned into the scope one turn searches under. + /// + internal static class StateKnowledgeScope { - ArgumentNullException.ThrowIfNull(state); - - // fromState without wildcard is refused at boot. wildcard without fromState is not: a - // deployment may resolve its own facets and want only the wildcard's widening. Either way, - // with nothing to build from, an unconfigured document composes nothing and the host's own - // scope — including its absence, which still fails closed — is what the turn sees. - if (scope?.Wildcard is not { } wildcard || scope.FromState.Count == 0) + /// Composes the turn's scope from the host's scope and the conversation's state. + /// The state of the conversation, as it stands at the start of this turn. + /// The document's providers.knowledge.scope block, or null. + /// What the host set for this conversation, or null when it set nothing. + /// The scope, or unchanged when this document composes none. + internal static KnowledgeScope? Compose( + StateDocument state, KnowledgeScopeConfiguration? scope, KnowledgeScope? hostScope) { - return hostScope; - } + ArgumentNullException.ThrowIfNull(state); - Dictionary facets = new(StringComparer.Ordinal); - Dictionary origins = new(StringComparer.Ordinal); - - if (hostScope is not null) - { - foreach (var (key, value) in hostScope.Facets) + // fromState without wildcard is refused at boot. wildcard without fromState is not: a + // deployment may resolve its own facets and want only the wildcard's widening. Either way, + // with nothing to build from, an unconfigured document composes nothing and the host's own + // scope — including its absence, which still fails closed — is what the turn sees. + if (scope?.Wildcard is not { } wildcard || scope.FromState.Count == 0) { - facets[key] = value; - origins[key] = KnowledgeFacetOrigin.Host; + return hostScope; } - } - foreach (var slot in scope.FromState) - { - if (facets.ContainsKey(slot)) - { - continue; - } + Dictionary facets = new(StringComparer.Ordinal); + Dictionary origins = new(StringComparer.Ordinal); - // An unknown key holds the wildcard rather than being left out: an absent key puts no - // condition on that facet, which admits every value of it. - if (Known(state, slot) is { } known) + if (hostScope is not null) { - facets[slot] = known; - origins[slot] = KnowledgeFacetOrigin.Extractor; + foreach ((string? key, string? value) in hostScope.Facets) + { + facets[key] = value; + origins[key] = KnowledgeFacetOrigin.Host; + } } - else + + foreach (string slot in scope.FromState) { - facets[slot] = wildcard.Value; - origins[slot] = KnowledgeFacetOrigin.Wildcard; + if (facets.ContainsKey(slot)) + { + continue; + } + + // An unknown key holds the wildcard rather than being left out: an absent key puts no + // condition on that facet, which admits every value of it. + if (Known(state, slot) is { } known) + { + facets[slot] = known; + origins[slot] = KnowledgeFacetOrigin.Extractor; + } + else + { + facets[slot] = wildcard.Value; + origins[slot] = KnowledgeFacetOrigin.Wildcard; + } } - } - return new KnowledgeScope { Facets = facets, Origins = origins }; - } + return new KnowledgeScope { Facets = facets, Origins = origins }; + } - /// Reads one slot, or null when no writer has filled it with a usable value. - /// - /// answers with the declared default for an unfilled slot, so - /// the emptiness check has to come first. It reports an undeclared name as filled, which is why - /// the value is checked too. - /// - private static string? Known(StateDocument state, string slot) - { - if (state.IsUnfilled(slot)) + /// Reads one slot, or null when no writer has filled it with a usable value. + /// + /// answers with the declared default for an unfilled slot, so + /// the emptiness check has to come first. It reports an undeclared name as filled, which is why + /// the value is checked too. + /// + private static string? Known(StateDocument state, string slot) { - return null; - } + if (state.IsUnfilled(slot)) + { + return null; + } - return state.Read(slot) is JsonValue value - && value.TryGetValue(out string? text) - && !string.IsNullOrWhiteSpace(text) - ? text - : null; + return state.Read(slot) is JsonValue value + && value.TryGetValue(out string? text) + && !string.IsNullOrWhiteSpace(text) + ? text + : null; + } } } diff --git a/src/AgentCore.Application/Knowledge/ToolFacetOverlay.cs b/src/AgentCore.Application/Knowledge/ToolFacetOverlay.cs index 471fc02e..ab3c0c81 100644 --- a/src/AgentCore.Application/Knowledge/ToolFacetOverlay.cs +++ b/src/AgentCore.Application/Knowledge/ToolFacetOverlay.cs @@ -1,49 +1,50 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Knowledge; - -/// -/// Lays the facets a tool argument carried over the scope the turn composed. -/// -internal static class ToolFacetOverlay +namespace AgentCore.Application.Knowledge { - /// Writes the named facets into the scope, where the turn left room for them. - /// The scope the search would otherwise run under. - /// What the argument carried, or when it carried nothing. - /// - /// The scope to search under, and when it differs from - /// . A caller that gets holds both, so dropping - /// these facets later is reopening the one it came in with rather than unpicking this one. - /// - internal static (KnowledgeScope Scope, bool Narrowed) Apply( - KnowledgeScope scope, IReadOnlyDictionary? named) + /// + /// Lays the facets a tool argument carried over the scope the turn composed. + /// + internal static class ToolFacetOverlay { - ArgumentNullException.ThrowIfNull(scope); - - if (named is not { Count: > 0 }) + /// Writes the named facets into the scope, where the turn left room for them. + /// The scope the search would otherwise run under. + /// What the argument carried, or when it carried nothing. + /// + /// The scope to search under, and when it differs from + /// . A caller that gets holds both, so dropping + /// these facets later is reopening the one it came in with rather than unpicking this one. + /// + internal static (KnowledgeScope Scope, bool Narrowed) Apply( + KnowledgeScope scope, IReadOnlyDictionary? named) { - return (scope, false); - } + ArgumentNullException.ThrowIfNull(scope); - Dictionary facets = new(scope.Facets, StringComparer.Ordinal); - Dictionary origins = new(scope.Origins, StringComparer.Ordinal); - var wrote = false; + if (named is not { Count: > 0 }) + { + return (scope, false); + } - foreach (var (key, value) in named) - { - if (scope.Origins.TryGetValue(key, out var origin) - && origin is not KnowledgeFacetOrigin.Wildcard) + Dictionary facets = new(scope.Facets, StringComparer.Ordinal); + Dictionary origins = new(scope.Origins, StringComparer.Ordinal); + bool wrote = false; + + foreach ((string? key, string? value) in named) { - continue; + if (scope.Origins.TryGetValue(key, out KnowledgeFacetOrigin origin) + && origin is not KnowledgeFacetOrigin.Wildcard) + { + continue; + } + + facets[key] = value; + origins[key] = KnowledgeFacetOrigin.Tool; + wrote = true; } - facets[key] = value; - origins[key] = KnowledgeFacetOrigin.Tool; - wrote = true; + return wrote + ? (new KnowledgeScope { Facets = facets, Origins = origins }, true) + : (scope, false); } - - return wrote - ? (new KnowledgeScope { Facets = facets, Origins = origins }, true) - : (scope, false); } } diff --git a/src/AgentCore.Application/Llm/ChatRequestProperties.cs b/src/AgentCore.Application/Llm/ChatRequestProperties.cs index 99fd9ca3..03c3dff0 100644 --- a/src/AgentCore.Application/Llm/ChatRequestProperties.cs +++ b/src/AgentCore.Application/Llm/ChatRequestProperties.cs @@ -1,16 +1,17 @@ -namespace AgentCore.Application.Llm; - -/// -/// The keys AgentCore writes on ChatOptions.AdditionalProperties for a vendor adapter to -/// read. The runtime knows the conversation; the adapter knows the vendor's wire field. These -/// keys are the seam between the two. -/// -public static class ChatRequestProperties +namespace AgentCore.Application.Llm { /// - /// The id of the conversation this request belongs to, as a . An adapter - /// hands it to the vendor as the prompt cache key, so every turn of one conversation routes to - /// the same cache. Absent on a request that runs outside a conversation turn. + /// The keys AgentCore writes on ChatOptions.AdditionalProperties for a vendor adapter to + /// read. The runtime knows the conversation; the adapter knows the vendor's wire field. These + /// keys are the seam between the two. /// - public const string ConversationId = "urn:agentcore:conversation-id"; + public static class ChatRequestProperties + { + /// + /// The id of the conversation this request belongs to, as a . An adapter + /// hands it to the vendor as the prompt cache key, so every turn of one conversation routes to + /// the same cache. Absent on a request that runs outside a conversation turn. + /// + public const string ConversationId = "urn:agentcore:conversation-id"; + } } diff --git a/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs b/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs index af8e0863..9b6dd066 100644 --- a/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs +++ b/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs @@ -6,195 +6,195 @@ using AgentCore.Application.Providers; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Llm; - -/// -/// The one a config-driven host binds. It routes each -/// providers.llm[] entry to the whose kind matches. -/// -public sealed class CompositeChatClientFactory : IChatClientFactory, IDisposable +namespace AgentCore.Application.Llm { - private readonly Dictionary _entries = new(StringComparer.Ordinal); - - private readonly Dictionary _adapters = new(StringComparer.Ordinal); + /// + /// The one a config-driven host binds. It routes each + /// providers.llm[] entry to the whose kind matches. + /// + public sealed class CompositeChatClientFactory : IChatClientFactory, IDisposable + { + private readonly Dictionary _entries = new(StringComparer.Ordinal); - private readonly Dictionary _vendor = new(StringComparer.Ordinal); + private readonly Dictionary _adapters = new(StringComparer.Ordinal); - private readonly ConcurrentDictionary _shaped = new(StringComparer.Ordinal); + private readonly Dictionary _vendor = new(StringComparer.Ordinal); - private LlmProviderConfiguration? _default; + private readonly ConcurrentDictionary _shaped = new(StringComparer.Ordinal); - private int _disposed; + private LlmProviderConfiguration? _default; - private CompositeChatClientFactory() - { - } - - /// Builds the factory: one client for each providers.llm[] entry, now. - /// The loaded document. - /// The chain each adapter resolves its credential through, or . - /// The adapters the host registers, one for each vendor it supports. - /// Cancels the build. - /// The factory. - /// - /// One entry names a kind no adapter serves, or two entries answer to the same as - /// name. - /// - public static async ValueTask CreateAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort? secrets, - IReadOnlyList adapters, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(adapters); + private int _disposed; - CompositeChatClientFactory factory = new(); + private CompositeChatClientFactory() + { + } - var llm = configuration.Providers?.Llm ?? []; - for (var index = 0; index < llm.Count; index++) + /// Builds the factory: one client for each providers.llm[] entry, now. + /// The loaded document. + /// The chain each adapter resolves its credential through, or . + /// The adapters the host registers, one for each vendor it supports. + /// Cancels the build. + /// The factory. + /// + /// One entry names a kind no adapter serves, or two entries answer to the same as + /// name. + /// + public static async ValueTask CreateAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort? secrets, + IReadOnlyList adapters, + CancellationToken cancellationToken = default) { - var entry = llm[index]; - var pointer = ConfigurationError.AppendPointer("/providers/llm", index); + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(adapters); - var seam = new VendorSeam( - $"providers.llm entry '{entry.As}'", - ConfigurationError.AppendPointer(pointer, "kind"), - "options.UseChatClients(...)"); - var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, seam); + CompositeChatClientFactory factory = new(); - if (!factory._entries.TryAdd(entry.As, entry)) + IReadOnlyList llm = configuration.Providers?.Llm ?? []; + for (int index = 0; index < llm.Count; index++) { - throw Fail( - ConfigurationError.AppendPointer(pointer, "as"), - $"two entries answer to the name '{entry.As}', so a model reference names two models."); - } + LlmProviderConfiguration entry = llm[index]; + string pointer = ConfigurationError.AppendPointer("/providers/llm", index); - factory._adapters[entry.As] = adapter; - - factory._vendor[entry.As] = await adapter - .CreateClientAsync(entry, secrets, cancellationToken) - .ConfigureAwait(false); + VendorSeam seam = new( + $"providers.llm entry '{entry.As}'", + ConfigurationError.AppendPointer(pointer, "kind"), + "options.UseChatClients(...)"); + IChatClientAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, seam); - factory._default ??= entry; - } + if (!factory._entries.TryAdd(entry.As, entry)) + { + throw Fail( + ConfigurationError.AppendPointer(pointer, "as"), + $"two entries answer to the name '{entry.As}', so a model reference names two models."); + } - return factory; - } + factory._adapters[entry.As] = adapter; - /// Gets the client one model reference names. - /// The reference, or for the first declared entry. - /// The client. The caller never disposes it, because this factory owns it. - /// - /// The reference names an as value providers.llm does not declare, or the document - /// declares no model at all. - /// - public IChatClient GetChatClient(ModelReference? model) - { - ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + factory._vendor[entry.As] = await adapter + .CreateClientAsync(entry, secrets, cancellationToken) + .ConfigureAwait(false); - var entry = Resolve(model); - if (model?.Temperature is not { } temperature) - { - return _vendor[entry.As]; + factory._default ??= entry; + } + + return factory; } - var key = entry.As + "|" + temperature.ToString("R", CultureInfo.InvariantCulture); + /// Gets the client one model reference names. + /// The reference, or for the first declared entry. + /// The client. The caller never disposes it, because this factory owns it. + /// + /// The reference names an as value providers.llm does not declare, or the document + /// declares no model at all. + /// + public IChatClient GetChatClient(ModelReference? model) + { + ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); - return _shaped.GetOrAdd( - key, - _ => _vendor[entry.As] - .AsBuilder() - .ConfigureOptions(options => options.Temperature ??= (float)temperature) - .Build()); - } + LlmProviderConfiguration entry = Resolve(model); + if (model?.Temperature is not { } temperature) + { + return _vendor[entry.As]; + } - /// - public AITool? ResolveHostedTool(AITool marker, ModelReference? model) - { - ArgumentNullException.ThrowIfNull(marker); - ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + string key = entry.As + "|" + temperature.ToString("R", CultureInfo.InvariantCulture); - LlmProviderConfiguration? entry; - if (model is null) - { - entry = _default; + return _shaped.GetOrAdd( + key, + _ => _vendor[entry.As] + .AsBuilder() + .ConfigureOptions(options => options.Temperature ??= (float)temperature) + .Build()); } - else + + /// + public AITool? ResolveHostedTool(AITool marker, ModelReference? model) { - _entries.TryGetValue(model.Ref, out entry); + ArgumentNullException.ThrowIfNull(marker); + ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + + LlmProviderConfiguration? entry; + if (model is null) + { + entry = _default; + } + else + { + _ = _entries.TryGetValue(model.Ref, out entry); + } + + return entry is null || !_adapters.TryGetValue(entry.As, out IChatClientAdapter? adapter) ? null : adapter.ResolveHostedTool(marker, entry); } - if (entry is null || !_adapters.TryGetValue(entry.As, out var adapter)) + /// + public int? GetContextWindow(ModelReference? model) { - return null; + ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + + LlmProviderConfiguration entry = Resolve(model); + return _adapters.TryGetValue(entry.As, out IChatClientAdapter? adapter) ? adapter.GetContextWindow(entry) : null; } - return adapter.ResolveHostedTool(marker, entry); - } + /// Releases every client the adapters built. + public void Dispose() + { + if (Interlocked.Exchange(ref _disposed, 1) == 1) + { + return; + } - /// - public int? GetContextWindow(ModelReference? model) - { - ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + foreach (IChatClient client in _vendor.Values) + { + client.Dispose(); + } - var entry = Resolve(model); - return _adapters.TryGetValue(entry.As, out var adapter) ? adapter.GetContextWindow(entry) : null; - } + _shaped.Clear(); + _vendor.Clear(); + } - /// Releases every client the adapters built. - public void Dispose() - { - if (Interlocked.Exchange(ref _disposed, 1) == 1) + /// Finds the entry one reference points at. + /// The reference, or . + /// The entry. + private LlmProviderConfiguration Resolve(ModelReference? model) { - return; + if (model is null) + { + // An agent that inherits nothing takes the first declared model, which is the one the + // document writes for the path that runs most. + return _default ?? throw Fail( + "/providers/llm", + "the document declares no model, so nothing answers a reference that names none."); + } + + return _entries.TryGetValue(model.Ref, out LlmProviderConfiguration? entry) + ? entry + : throw Fail( + "/providers/llm", + $"the reference '{model.Ref}' names no entry of providers.llm. The document declares " + + $"{Declared()}."); } - foreach (var client in _vendor.Values) + /// Writes the declared names, so a failure names what the document does hold. + /// The names, or a phrase for an empty section. + private string Declared() { - client.Dispose(); + return _entries.Count == 0 ? "no model" : string.Join(", ", _entries.Keys.Select(name => "'" + name + "'")); } - _shaped.Clear(); - _vendor.Clear(); - } - - /// Finds the entry one reference points at. - /// The reference, or . - /// The entry. - private LlmProviderConfiguration Resolve(ModelReference? model) - { - if (model is null) + /// Builds the one exception every failure of this factory uses. + /// The JSON Pointer into the document. + /// What is wrong. + /// The exception. + private static ConfigurationLoadException Fail(string pointer, string message) { - // An agent that inherits nothing takes the first declared model, which is the one the - // document writes for the path that runs most. - return _default ?? throw Fail( - "/providers/llm", - "the document declares no model, so nothing answers a reference that names none."); + return new(new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.ReferenceResolution, + }); } - - return _entries.TryGetValue(model.Ref, out var entry) - ? entry - : throw Fail( - "/providers/llm", - $"the reference '{model.Ref}' names no entry of providers.llm. The document declares " - + $"{Declared()}."); } - - /// Writes the declared names, so a failure names what the document does hold. - /// The names, or a phrase for an empty section. - private string Declared() - => _entries.Count == 0 ? "no model" : string.Join(", ", _entries.Keys.Select(name => "'" + name + "'")); - - /// Builds the one exception every failure of this factory uses. - /// The JSON Pointer into the document. - /// What is wrong. - /// The exception. - private static ConfigurationLoadException Fail(string pointer, string message) - => new(new ConfigurationError - { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.ReferenceResolution, - }); } diff --git a/src/AgentCore.Application/Llm/ConversationRequestStamp.cs b/src/AgentCore.Application/Llm/ConversationRequestStamp.cs index 1b9ebba9..0f691f08 100644 --- a/src/AgentCore.Application/Llm/ConversationRequestStamp.cs +++ b/src/AgentCore.Application/Llm/ConversationRequestStamp.cs @@ -1,22 +1,23 @@ using AgentCore.Application.Runtime; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Llm; - -/// -/// Copies the running turn's conversation id onto the request, under -/// , where a vendor adapter can read it. -/// -internal static class ConversationRequestStamp +namespace AgentCore.Application.Llm { - internal static void Apply(ChatOptions options) + /// + /// Copies the running turn's conversation id onto the request, under + /// , where a vendor adapter can read it. + /// + internal static class ConversationRequestStamp { - ArgumentNullException.ThrowIfNull(options); - - if (TurnInvocation.From(options) is { ConversationId: { Length: > 0 } conversationId }) + internal static void Apply(ChatOptions options) { - options.AdditionalProperties ??= []; - options.AdditionalProperties[ChatRequestProperties.ConversationId] = conversationId; + ArgumentNullException.ThrowIfNull(options); + + if (TurnInvocation.From(options) is { ConversationId: { Length: > 0 } conversationId }) + { + options.AdditionalProperties ??= []; + options.AdditionalProperties[ChatRequestProperties.ConversationId] = conversationId; + } } } } diff --git a/src/AgentCore.Application/Policy/StagePolicy.cs b/src/AgentCore.Application/Policy/StagePolicy.cs index 994139cd..d1dd913a 100644 --- a/src/AgentCore.Application/Policy/StagePolicy.cs +++ b/src/AgentCore.Application/Policy/StagePolicy.cs @@ -4,148 +4,145 @@ using Stateless; using Stateless.Graph; -namespace AgentCore.Application.Policy; - -/// -/// The stage machine of row 2 of the compile table, over string stages. -/// -public sealed class StagePolicy +namespace AgentCore.Application.Policy { - /// The one trigger. A turn ends, and the machine picks the next stage. - public const string TurnEndedTrigger = "TurnEnded"; - - private readonly PolicyConfiguration _policy; - - private readonly Dictionary _stages; - - private readonly StateMachine _machine; - - private readonly StateMachine.TriggerWithParameters> _turnEnded; + /// + /// The stage machine of row 2 of the compile table, over string stages. + /// + public sealed class StagePolicy + { + /// The one trigger. A turn ends, and the machine picks the next stage. + public const string TurnEndedTrigger = "TurnEnded"; + private readonly Dictionary _stages; - private string _stage; + private readonly StateMachine _machine; - /// Builds the machine one entry's policy: block declares. - /// The entry's policy: block. - /// The evaluator that runs each exit guard. - /// The initial stage is not declared. - public StagePolicy(PolicyConfiguration policy, IGuardEvaluator guards) - { - ArgumentNullException.ThrowIfNull(policy); - ArgumentNullException.ThrowIfNull(guards); + private readonly StateMachine.TriggerWithParameters> _turnEnded; - _policy = policy; - _stages = new Dictionary(StringComparer.Ordinal); - foreach (var stage in policy.Stages) + /// Builds the machine one entry's policy: block declares. + /// The entry's policy: block. + /// The evaluator that runs each exit guard. + /// The initial stage is not declared. + public StagePolicy(PolicyConfiguration policy, IGuardEvaluator guards) { - _stages[stage.Id] = stage; - } + ArgumentNullException.ThrowIfNull(policy); + ArgumentNullException.ThrowIfNull(guards); - if (!_stages.ContainsKey(policy.Initial)) - { - throw new ArgumentException( - $"The initial stage '{policy.Initial}' is not declared in policy.stages.", nameof(policy)); - } + Configuration = policy; + _stages = new Dictionary(StringComparer.Ordinal); + foreach (StageConfiguration stage in policy.Stages) + { + _stages[stage.Id] = stage; + } - _stage = policy.Initial; + if (!_stages.ContainsKey(policy.Initial)) + { + throw new ArgumentException( + $"The initial stage '{policy.Initial}' is not declared in policy.stages.", nameof(policy)); + } - _machine = new StateMachine(() => _stage, stage => _stage = stage); + Stage = policy.Initial; - _turnEnded = _machine.SetTriggerParameters>(TurnEndedTrigger); + _machine = new StateMachine(() => Stage, stage => Stage = stage); - // No guard matched means the caller has not given us enough to move on. Staying is correct, - // unless the stage asked for the opposite with onNoMatch: error. - _machine.OnUnhandledTrigger((stage, _) => - { - if (_stages.TryGetValue(stage, out var declared) && declared.OnNoMatch == StageNoMatch.Error) + _turnEnded = _machine.SetTriggerParameters>(TurnEndedTrigger); + + // No guard matched means the caller has not given us enough to move on. Staying is correct, + // unless the stage asked for the opposite with onNoMatch: error. + _machine.OnUnhandledTrigger((stage, _) => + { + if (_stages.TryGetValue(stage, out StageConfiguration? declared) && declared.OnNoMatch == StageNoMatch.Error) + { + throw new InvalidOperationException( + $"No exit guard of the stage '{stage}' is true, and the stage sets onNoMatch: error."); + } + }); + + foreach (StageConfiguration stage in policy.Stages) { - throw new InvalidOperationException( - $"No exit guard of the stage '{stage}' is true, and the stage sets onNoMatch: error."); + Configure(stage, guards); } - }); - - foreach (var stage in policy.Stages) - { - Configure(stage, guards); } - } - /// Gets the entry's policy: block this machine was built from. - public PolicyConfiguration Configuration => _policy; + /// Gets the entry's policy: block this machine was built from. + public PolicyConfiguration Configuration { get; } - /// Gets the id of the stage the machine holds. - public string Stage => _stage; + /// Gets the id of the stage the machine holds. + public string Stage { get; private set; } - /// Gets the stage the machine holds. - public StageConfiguration CurrentStage => _stages[_machine.State]; + /// Gets the stage the machine holds. + public StageConfiguration CurrentStage => _stages[_machine.State]; - /// Gets whether the stage the machine holds ends the conversation. - public bool IsTerminal => CurrentStage.Terminal; + /// Gets whether the stage the machine holds ends the conversation. + public bool IsTerminal => CurrentStage.Terminal; - /// Gets the id of the agent that speaks in the stage the machine holds. - public string? CurrentAgentId => CurrentStage.Agent; + /// Gets the id of the agent that speaks in the stage the machine holds. + public string? CurrentAgentId => CurrentStage.Agent; - /// Reports whether this policy declares a stage. - public bool Declares(string stage) - { - ArgumentNullException.ThrowIfNull(stage); - return _stages.ContainsKey(stage); - } - - /// Puts the machine back in the stage a previous session of this conversation left it in. - internal void RestoreStage(string stage) - { - ArgumentNullException.ThrowIfNull(stage); - - if (!_stages.ContainsKey(stage)) + /// Reports whether this policy declares a stage. + public bool Declares(string stage) { - throw new ArgumentException( - $"The stage '{stage}' is not declared in policy.stages.", nameof(stage)); + ArgumentNullException.ThrowIfNull(stage); + return _stages.ContainsKey(stage); } - _stage = stage; - } + /// Puts the machine back in the stage a previous session of this conversation left it in. + internal void RestoreStage(string stage) + { + ArgumentNullException.ThrowIfNull(stage); - /// Ends a turn, and picks the stage of the next turn. - public string Advance(IReadOnlyDictionary state) - { - ArgumentNullException.ThrowIfNull(state); + if (!_stages.ContainsKey(stage)) + { + throw new ArgumentException( + $"The stage '{stage}' is not declared in policy.stages.", nameof(stage)); + } - _machine.Fire(_turnEnded, state); - return _machine.State; - } + Stage = stage; + } - /// Renders the live machine as a mermaid diagram. There is no second source of truth. - /// The mermaid text, with each guard name printed next to its edge. - public string ToMermaid() => MermaidGraph.Format(_machine.GetInfo()); + /// Ends a turn, and picks the stage of the next turn. + public string Advance(IReadOnlyDictionary state) + { + ArgumentNullException.ThrowIfNull(state); - /// Renders the live machine as a DOT diagram. - /// The DOT text. - public string ToDot() => UmlDotGraph.Format(_machine.GetInfo()); + _machine.Fire(_turnEnded, state); + return _machine.State; + } - private void Configure(StageConfiguration stage, IGuardEvaluator guards) - { - var configured = _machine.Configure(stage.Id); + /// Renders the live machine as a mermaid diagram. There is no second source of truth. + /// The mermaid text, with each guard name printed next to its edge. + public string ToMermaid() + { + return MermaidGraph.Format(_machine.GetInfo()); + } - // One unconditional exit needs no guard at all, and the diagram reads better without one. - if (stage.To.Count == 1 && stage.To[0].When is null) + /// Renders the live machine as a DOT diagram. + /// The DOT text. + public string ToDot() { - configured.Permit(TurnEndedTrigger, stage.To[0].Stage); - return; + return UmlDotGraph.Format(_machine.GetInfo()); } - foreach (var exit in stage.To) + private void Configure(StageConfiguration stage, IGuardEvaluator guards) { - if (exit.When is { } guard) + StateMachine.StateConfiguration configured = _machine.Configure(stage.Id); + + // One unconditional exit needs no guard at all, and the diagram reads better without one. + if (stage.To.Count == 1 && stage.To[0].When is null) { - configured.PermitIf( - _turnEnded, - exit.Stage, - state => guards.Evaluate(guard, state), - guard.ToString()); + _ = configured.Permit(TurnEndedTrigger, stage.To[0].Stage); + return; } - else + + foreach (StageTransition exit in stage.To) { - configured.PermitIf(_turnEnded, exit.Stage, static _ => true, "always"); + _ = exit.When is { } guard + ? configured.PermitIf( + _turnEnded, + exit.Stage, + state => guards.Evaluate(guard, state), + guard.ToString()) + : configured.PermitIf(_turnEnded, exit.Stage, static _ => true, "always"); } } } diff --git a/src/AgentCore.Application/Ports/IAuditSinkAdapter.cs b/src/AgentCore.Application/Ports/IAuditSinkAdapter.cs index 41b38db2..22c1404c 100644 --- a/src/AgentCore.Application/Ports/IAuditSinkAdapter.cs +++ b/src/AgentCore.Application/Ports/IAuditSinkAdapter.cs @@ -1,23 +1,23 @@ -using AgentCore.Application.Audit.Memory; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Ports; - -/// -/// Opens the audit store behind one providers.audit value. -/// -public interface IAuditSinkAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Opens the store this vendor writes to, and hands it over. - /// The providers.audit block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the open. - /// - /// The raw store. The caller wraps it in and owns it for the - /// life of the process, so this returns no queue and starts no background writer. - /// - ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + /// + /// Opens the audit store behind one providers.audit value. + /// + public interface IAuditSinkAdapter : IVendorAdapter + { + /// Opens the store this vendor writes to, and hands it over. + /// The providers.audit block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the open. + /// + /// The raw store. The caller wraps it in and owns it for the + /// life of the process, so this returns no queue and starts no background writer. + /// + ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IAuditSinkPort.cs b/src/AgentCore.Application/Ports/IAuditSinkPort.cs index aa460670..3516c735 100644 --- a/src/AgentCore.Application/Ports/IAuditSinkPort.cs +++ b/src/AgentCore.Application/Ports/IAuditSinkPort.cs @@ -1,42 +1,43 @@ using AgentCore.Domain.Audit; -namespace AgentCore.Application.Ports; - -/// -/// Writes append-only, hash-chained audit events. It never sits on the turn. -/// -public interface IAuditSinkPort +namespace AgentCore.Application.Ports { - /// Accepts one event for the chain. - /// The event to append. Nothing edits it afterwards. - /// Cancels the enqueue, and never the write behind it. - /// - /// A task that completes when the sink has accepted the event. The row is not durable yet. - /// - ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default); - - /// Accepts a run of events for the chain, in the order they are given. - /// The events to append. Nothing edits them afterwards. - /// Cancels the enqueue, and never the writes behind it. - /// - /// A task that completes when the sink has accepted every event. The rows are not durable yet. - /// - /// is . - ValueTask AppendManyAsync( - IReadOnlyList auditEvents, - CancellationToken cancellationToken = default) + /// + /// Writes append-only, hash-chained audit events. It never sits on the turn. + /// + public interface IAuditSinkPort { - ArgumentNullException.ThrowIfNull(auditEvents); - return AppendEachAsync(this, auditEvents, cancellationToken); + /// Accepts one event for the chain. + /// The event to append. Nothing edits it afterwards. + /// Cancels the enqueue, and never the write behind it. + /// + /// A task that completes when the sink has accepted the event. The row is not durable yet. + /// + ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default); - static async ValueTask AppendEachAsync( - IAuditSinkPort sink, + /// Accepts a run of events for the chain, in the order they are given. + /// The events to append. Nothing edits them afterwards. + /// Cancels the enqueue, and never the writes behind it. + /// + /// A task that completes when the sink has accepted every event. The rows are not durable yet. + /// + /// is . + ValueTask AppendManyAsync( IReadOnlyList auditEvents, - CancellationToken cancellationToken) + CancellationToken cancellationToken = default) { - foreach (AuditEvent auditEvent in auditEvents) + ArgumentNullException.ThrowIfNull(auditEvents); + return AppendEachAsync(this, auditEvents, cancellationToken); + + static async ValueTask AppendEachAsync( + IAuditSinkPort sink, + IReadOnlyList auditEvents, + CancellationToken cancellationToken) { - await sink.AppendAsync(auditEvent, cancellationToken).ConfigureAwait(false); + foreach (AuditEvent auditEvent in auditEvents) + { + await sink.AppendAsync(auditEvent, cancellationToken).ConfigureAwait(false); + } } } } diff --git a/src/AgentCore.Application/Ports/IBlobStore.cs b/src/AgentCore.Application/Ports/IBlobStore.cs index 51d56803..a422fc8b 100644 --- a/src/AgentCore.Application/Ports/IBlobStore.cs +++ b/src/AgentCore.Application/Ports/IBlobStore.cs @@ -1,41 +1,42 @@ using AgentCore.Application.Blobs; -namespace AgentCore.Application.Ports; - -/// -/// Durable bytes an owner wrote, keyed by owner and name. -/// -public interface IBlobStore +namespace AgentCore.Application.Ports { - /// Writes one blob. The same owner and name replaces the earlier blob. - /// What to store. The stream is read once, from its current position. - /// Cancels the write. - /// What was stored. - ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default); + /// + /// Durable bytes an owner wrote, keyed by owner and name. + /// + public interface IBlobStore + { + /// Writes one blob. The same owner and name replaces the earlier blob. + /// What to store. The stream is read once, from its current position. + /// Cancels the write. + /// What was stored. + ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default); - /// Opens one blob for reading. - /// Who wrote it. - /// The name it was written under. - /// Cancels the open. - /// The blob, or when no such blob exists. The caller disposes it. - ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default); + /// Opens one blob for reading. + /// Who wrote it. + /// The name it was written under. + /// Cancels the open. + /// The blob, or when no such blob exists. The caller disposes it. + ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default); - /// Reads one blob's facts without its bytes. - /// Who wrote it. - /// The name it was written under. - /// Cancels the read. - /// The blob, or when no such blob exists. - ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default); + /// Reads one blob's facts without its bytes. + /// Who wrote it. + /// The name it was written under. + /// Cancels the read. + /// The blob, or when no such blob exists. + ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default); - /// Makes a URL a browser can fetch the blob from, with no other credential. - /// The blob to link. Its media type decides whether the browser shows it or saves it. - /// How long the URL works. is the usual value. - /// Cancels the signing. - /// The URL, or when this store has no web door of its own. - ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default); + /// Makes a URL a browser can fetch the blob from, with no other credential. + /// The blob to link. Its media type decides whether the browser shows it or saves it. + /// How long the URL works. is the usual value. + /// Cancels the signing. + /// The URL, or when this store has no web door of its own. + ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default); - /// Deletes every blob an owner wrote. Nothing to delete is not an error. - /// Whose blobs to delete. - /// Cancels the delete. - ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default); + /// Deletes every blob an owner wrote. Nothing to delete is not an error. + /// Whose blobs to delete. + /// Cancels the delete. + ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IBlobStoreAdapter.cs b/src/AgentCore.Application/Ports/IBlobStoreAdapter.cs index de98c69f..b5ab6015 100644 --- a/src/AgentCore.Application/Ports/IBlobStoreAdapter.cs +++ b/src/AgentCore.Application/Ports/IBlobStoreAdapter.cs @@ -1,18 +1,19 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Ports; - -/// -/// Opens the blob store behind one providers.blobs value. -/// -public interface IBlobStoreAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Opens the store this vendor writes to, and hands it over. - /// The providers.blobs block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the open. - ValueTask OpenAsync( - BlobProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + /// + /// Opens the blob store behind one providers.blobs value. + /// + public interface IBlobStoreAdapter : IVendorAdapter + { + /// Opens the store this vendor writes to, and hands it over. + /// The providers.blobs block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the open. + ValueTask OpenAsync( + BlobProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IChatClientAdapter.cs b/src/AgentCore.Application/Ports/IChatClientAdapter.cs index a630e126..b38f9165 100644 --- a/src/AgentCore.Application/Ports/IChatClientAdapter.cs +++ b/src/AgentCore.Application/Ports/IChatClientAdapter.cs @@ -1,35 +1,42 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// -/// Builds the vendor client behind one providers.llm[].kind value. -/// -public interface IChatClientAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Builds the vendor client of one entry. - /// The providers.llm[] entry, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the build. - /// The client. The composite owns and disposes it; the adapter never does. - ValueTask CreateClientAsync( - LlmProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + /// + /// Builds the vendor client behind one providers.llm[].kind value. + /// + public interface IChatClientAdapter : IVendorAdapter + { + /// Builds the vendor client of one entry. + /// The providers.llm[] entry, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the build. + /// The client. The composite owns and disposes it; the adapter never does. + ValueTask CreateClientAsync( + LlmProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); - /// Resolves a hosted tool marker for one entry, tuning it for this vendor. - /// The marker the document declared, such as a hosted search or code execution tool. - /// The providers.llm[] entry this adapter serves. - /// The tool to hand the model, or when this vendor does not run it. - AITool? ResolveHostedTool(AITool marker, LlmProviderConfiguration entry) => null; + /// Resolves a hosted tool marker for one entry, tuning it for this vendor. + /// The marker the document declared, such as a hosted search or code execution tool. + /// The providers.llm[] entry this adapter serves. + /// The tool to hand the model, or when this vendor does not run it. + AITool? ResolveHostedTool(AITool marker, LlmProviderConfiguration entry) + { + return null; + } - /// Reports the model's context window, in tokens. - /// The providers.llm[] entry this adapter serves. - /// - /// The window in tokens, or when this adapter does not know the model. - /// Compaction is always on, so the compiler refuses an agent whose model answers - /// . - /// - int? GetContextWindow(LlmProviderConfiguration entry) => null; + /// Reports the model's context window, in tokens. + /// The providers.llm[] entry this adapter serves. + /// + /// The window in tokens, or when this adapter does not know the model. + /// Compaction is always on, so the compiler refuses an agent whose model answers + /// . + /// + int? GetContextWindow(LlmProviderConfiguration entry) + { + return null; + } + } } diff --git a/src/AgentCore.Application/Ports/IChatClientFactory.cs b/src/AgentCore.Application/Ports/IChatClientFactory.cs index dda0d7f6..23c72034 100644 --- a/src/AgentCore.Application/Ports/IChatClientFactory.cs +++ b/src/AgentCore.Application/Ports/IChatClientFactory.cs @@ -1,34 +1,38 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// -/// Resolves a { ref: reply } model reference to a chat client. -/// -public interface IChatClientFactory +namespace AgentCore.Application.Ports { - /// Gets the chat client one model reference names. - /// - /// The reference, or when the agent inherits nothing and the factory - /// picks its own default. - /// - /// The chat client. The compiler never disposes it. - IChatClient GetChatClient(ModelReference? model); + /// + /// Resolves a { ref: reply } model reference to a chat client. + /// + public interface IChatClientFactory + { + /// Gets the chat client one model reference names. + /// + /// The reference, or when the agent inherits nothing and the factory + /// picks its own default. + /// + /// The chat client. The compiler never disposes it. + IChatClient GetChatClient(ModelReference? model); - /// Resolves a hosted tool marker for one model reference. - /// The marker the document declared. - /// The reference, or for the factory's default entry. - /// The tool to hand the model, or when the vendor behind it does not run it. - AITool? ResolveHostedTool(AITool marker, ModelReference? model) => null; + /// Resolves a hosted tool marker for one model reference. + /// The marker the document declared. + /// The reference, or for the factory's default entry. + /// The tool to hand the model, or when the vendor behind it does not run it. + AITool? ResolveHostedTool(AITool marker, ModelReference? model) + { + return null; + } - /// Reports the context window of the model one reference names, in tokens. - /// - /// The reference, or for the factory's default entry. - /// - /// - /// The window in tokens, or when the adapter behind that entry does not - /// know the model. - /// - int? GetContextWindow(ModelReference? model); + /// Reports the context window of the model one reference names, in tokens. + /// + /// The reference, or for the factory's default entry. + /// + /// + /// The window in tokens, or when the adapter behind that entry does not + /// know the model. + /// + int? GetContextWindow(ModelReference? model); + } } diff --git a/src/AgentCore.Application/Ports/IConversationAdapter.cs b/src/AgentCore.Application/Ports/IConversationAdapter.cs index 89cc6e18..6a6522b7 100644 --- a/src/AgentCore.Application/Ports/IConversationAdapter.cs +++ b/src/AgentCore.Application/Ports/IConversationAdapter.cs @@ -1,41 +1,42 @@ -namespace AgentCore.Application.Ports; - -/// -/// Names the vendor behind one providers.conversation value: who carries the conversation. -/// -/// -/// -/// This is the selection face, and it is all the core can see. The routing face -/// lives in AgentCore.AspNetCore as IConversationTransportAdapter, because it names -/// IEndpointRouteBuilder and this assembly references no ASP.NET Core package. -/// -/// -/// A vendor this process dials out to implements this and stops. It has no inbound URL, so -/// it is never forced to grow a routing member it would have to throw from. -/// -/// -public interface IConversationAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { /// - /// Gets whether this transport's frames already carry text. + /// Names the vendor behind one providers.conversation value: who carries the conversation. /// /// /// - /// means the vendor performs recognition and synthesis itself — the - /// Telnyx Conversation Relay does — so both speech roles, - /// providers.speech.stt.kind and providers.speech.tts.kind, must name that same - /// vendor, and enforces it. + /// This is the selection face, and it is all the core can see. The routing face + /// lives in AgentCore.AspNetCore as IConversationTransportAdapter, because it names + /// IEndpointRouteBuilder and this assembly references no ASP.NET Core package. /// /// - /// means the frames carry audio and a separate speech vendor turns it - /// into text. That adapter runs recognition and synthesis inside itself: audio never leaves it, - /// so no audio type enters this assembly either way. - /// - /// - /// This is declared here rather than written in the document. A payload: text - /// field beside kind could only agree with the vendor or lie about it, and an adapter - /// cannot be wrong about its own wire. + /// A vendor this process dials out to implements this and stops. It has no inbound URL, so + /// it is never forced to grow a routing member it would have to throw from. /// /// - bool CarriesText { get; } + public interface IConversationAdapter : IVendorAdapter + { + /// + /// Gets whether this transport's frames already carry text. + /// + /// + /// + /// means the vendor performs recognition and synthesis itself — the + /// Telnyx Conversation Relay does — so both speech roles, + /// providers.speech.stt.kind and providers.speech.tts.kind, must name that same + /// vendor, and enforces it. + /// + /// + /// means the frames carry audio and a separate speech vendor turns it + /// into text. That adapter runs recognition and synthesis inside itself: audio never leaves it, + /// so no audio type enters this assembly either way. + /// + /// + /// This is declared here rather than written in the document. A payload: text + /// field beside kind could only agree with the vendor or lie about it, and an adapter + /// cannot be wrong about its own wire. + /// + /// + bool CarriesText { get; } + } } diff --git a/src/AgentCore.Application/Ports/IConversationChannelFactory.cs b/src/AgentCore.Application/Ports/IConversationChannelFactory.cs index 5df60f74..3d98d68c 100644 --- a/src/AgentCore.Application/Ports/IConversationChannelFactory.cs +++ b/src/AgentCore.Application/Ports/IConversationChannelFactory.cs @@ -1,13 +1,14 @@ using AgentCore.Application.Conversation; -namespace AgentCore.Application.Ports; - -/// Opens the channel for one conversation. -public interface IConversationChannelFactory +namespace AgentCore.Application.Ports { - /// Opens both halves of one conversation. - /// What the conversation is. - /// Abandons the attempt. - /// The pair. The caller disposes it when the conversation ends. - ValueTask OpenAsync(ConversationChannelContext context, CancellationToken cancellationToken = default); + /// Opens the channel for one conversation. + public interface IConversationChannelFactory + { + /// Opens both halves of one conversation. + /// What the conversation is. + /// Abandons the attempt. + /// The pair. The caller disposes it when the conversation ends. + ValueTask OpenAsync(ConversationChannelContext context, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IConversationInputPort.cs b/src/AgentCore.Application/Ports/IConversationInputPort.cs index a68a8b8c..c8e9ef5b 100644 --- a/src/AgentCore.Application/Ports/IConversationInputPort.cs +++ b/src/AgentCore.Application/Ports/IConversationInputPort.cs @@ -1,61 +1,62 @@ using AgentCore.Application.Conversation; -namespace AgentCore.Application.Ports; - -/// -/// What the caller did, for one conversation, as one ordered stream. -/// -/// -/// -/// One instance serves one conversation and is disposed with it. That is unlike every other port in this -/// folder, which is bound once for the process, and it is why this one is -/// . -/// -/// -/// A barge-in arrives here, on the inbound stream, and not on -/// . It is an event the caller caused, and the order between "the -/// caller cut in" and "the caller then said this" is what a turn loop must never get wrong. One -/// ordered stream keeps that ordering inside the adapter, which is the only place that has the -/// information to settle it. -/// -/// -/// This port always carries text, whatever the wire carries. A bundled transport such as -/// the Telnyx Conversation Relay receives text frames and passes them straight through. A -/// transport whose socket carries audio runs recognition inside its own adapter and emits text -/// here. Audio stops at the adapter's edge and never enters this assembly, which is D28 and -/// section 11 item 6c. That is also why this port is named for the conversation and not for speech: -/// names the vendor behind each speech role — one vendor, or two — -/// and this does not. -/// -/// -public interface IConversationInputPort : IAsyncDisposable +namespace AgentCore.Application.Ports { - /// Reads what the caller does, until the conversation ends. - /// - /// Abandons the read. Cancelling it throws, and never ends the stream quietly — see the remarks. - /// - /// Every inbound event of the conversation, in order. + /// + /// What the caller did, for one conversation, as one ordered stream. + /// /// /// - /// One consumer only. This method may not be called a second time on one instance, and - /// a second call throws. is a factory rather than a stream, - /// so nothing in the type itself stops two enumerators from being taken over one socket, and - /// two consumers of one socket would each see half the conversation. + /// One instance serves one conversation and is disposed with it. That is unlike every other port in this + /// folder, which is bound once for the process, and it is why this one is + /// . + /// + /// + /// A barge-in arrives here, on the inbound stream, and not on + /// . It is an event the caller caused, and the order between "the + /// caller cut in" and "the caller then said this" is what a turn loop must never get wrong. One + /// ordered stream keeps that ordering inside the adapter, which is the only place that has the + /// information to settle it. /// /// - /// The conversation ending and the read being cancelled are two different endings, and every - /// implementation must tell them apart the same way. The conversation ending — the caller hung up, - /// the transport went away, the vendor closed the socket — completes the stream normally, and - /// that is the ordinary end of an await foreach over it. Cancelling - /// throws instead, - /// as any cancelled await does. A consumer therefore reads "the loop ended" as "the conversation is - /// over" and needs no flag to ask which happened, and an implementation may not swallow its - /// consumer's own cancellation into a clean ending: a test double that throws where the real - /// port completes, or the reverse, is a difference the whole point of this port is that nobody - /// above it can see. + /// This port always carries text, whatever the wire carries. A bundled transport such as + /// the Telnyx Conversation Relay receives text frames and passes them straight through. A + /// transport whose socket carries audio runs recognition inside its own adapter and emits text + /// here. Audio stops at the adapter's edge and never enters this assembly, which is D28 and + /// section 11 item 6c. That is also why this port is named for the conversation and not for speech: + /// names the vendor behind each speech role — one vendor, or two — + /// and this does not. /// /// - /// This port is already being read. - /// was cancelled. - IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default); + public interface IConversationInputPort : IAsyncDisposable + { + /// Reads what the caller does, until the conversation ends. + /// + /// Abandons the read. Cancelling it throws, and never ends the stream quietly — see the remarks. + /// + /// Every inbound event of the conversation, in order. + /// + /// + /// One consumer only. This method may not be called a second time on one instance, and + /// a second call throws. is a factory rather than a stream, + /// so nothing in the type itself stops two enumerators from being taken over one socket, and + /// two consumers of one socket would each see half the conversation. + /// + /// + /// The conversation ending and the read being cancelled are two different endings, and every + /// implementation must tell them apart the same way. The conversation ending — the caller hung up, + /// the transport went away, the vendor closed the socket — completes the stream normally, and + /// that is the ordinary end of an await foreach over it. Cancelling + /// throws instead, + /// as any cancelled await does. A consumer therefore reads "the loop ended" as "the conversation is + /// over" and needs no flag to ask which happened, and an implementation may not swallow its + /// consumer's own cancellation into a clean ending: a test double that throws where the real + /// port completes, or the reverse, is a difference the whole point of this port is that nobody + /// above it can see. + /// + /// + /// This port is already being read. + /// was cancelled. + IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IConversationObserver.cs b/src/AgentCore.Application/Ports/IConversationObserver.cs index 059da490..281ca304 100644 --- a/src/AgentCore.Application/Ports/IConversationObserver.cs +++ b/src/AgentCore.Application/Ports/IConversationObserver.cs @@ -1,47 +1,48 @@ using AgentCore.Application.Runtime; -namespace AgentCore.Application.Ports; - -/// -/// Reads the facts of a conversation as the turn loop raises them. It never sits on the turn. -/// -/// -/// -/// This is the one seam between the turn loop and everything that watches it. The audit chain of D23, -/// the counters of section 8.6, and the "log once" rows of section 8.7 are three implementations of -/// this port, and knows none of them: it raises a -/// and moves on. -/// -/// -/// The contract of applies here in full, and for the same measurement. -/// Section 7 puts a durable insert at 13 ms at p50 and 32 ms at p99, against 91 nanoseconds to -/// enqueue, so an observer completes when it has ACCEPTED the fact and never when it has stored it. -/// An implementation that awaits a database, an HTTP call, or a disk inside -/// has broken the contract, and the turn loop pays for it. -/// -/// -/// The dispatcher behind this port never lets an observer end a turn: a fault is logged once and -/// swallowed, and an observer that does not complete at once is observed off-turn. An implementation -/// may therefore throw, and nothing that throws is retried. Observers of one conversation are also invoked in -/// the order the conversation raised the facts, so a late fact never overtakes an earlier one. -/// -/// -/// One instance serves every conversation, because a names its own conversation. Nothing here -/// is per conversation, and an implementation that holds per-call state must key it by -/// . -/// -/// -public interface IConversationObserver +namespace AgentCore.Application.Ports { - /// Takes one fact about a conversation. - /// What happened. Nothing edits it afterwards. - /// - /// Cancels the acceptance, and never the work behind it. The dispatcher passes - /// : the record belongs to the conversation, and not to a turn the - /// caller may have cancelled. - /// - /// - /// A task that completes when the observer has accepted the fact. It is not stored yet. - /// - ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken); + /// + /// Reads the facts of a conversation as the turn loop raises them. It never sits on the turn. + /// + /// + /// + /// This is the one seam between the turn loop and everything that watches it. The audit chain of D23, + /// the counters of section 8.6, and the "log once" rows of section 8.7 are three implementations of + /// this port, and knows none of them: it raises a + /// and moves on. + /// + /// + /// The contract of applies here in full, and for the same measurement. + /// Section 7 puts a durable insert at 13 ms at p50 and 32 ms at p99, against 91 nanoseconds to + /// enqueue, so an observer completes when it has ACCEPTED the fact and never when it has stored it. + /// An implementation that awaits a database, an HTTP call, or a disk inside + /// has broken the contract, and the turn loop pays for it. + /// + /// + /// The dispatcher behind this port never lets an observer end a turn: a fault is logged once and + /// swallowed, and an observer that does not complete at once is observed off-turn. An implementation + /// may therefore throw, and nothing that throws is retried. Observers of one conversation are also invoked in + /// the order the conversation raised the facts, so a late fact never overtakes an earlier one. + /// + /// + /// One instance serves every conversation, because a names its own conversation. Nothing here + /// is per conversation, and an implementation that holds per-call state must key it by + /// . + /// + /// + public interface IConversationObserver + { + /// Takes one fact about a conversation. + /// What happened. Nothing edits it afterwards. + /// + /// Cancels the acceptance, and never the work behind it. The dispatcher passes + /// : the record belongs to the conversation, and not to a turn the + /// caller may have cancelled. + /// + /// + /// A task that completes when the observer has accepted the fact. It is not stored yet. + /// + ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken); + } } diff --git a/src/AgentCore.Application/Ports/IConversationOutputPort.cs b/src/AgentCore.Application/Ports/IConversationOutputPort.cs index 5b6dbeb4..4b1ffaaa 100644 --- a/src/AgentCore.Application/Ports/IConversationOutputPort.cs +++ b/src/AgentCore.Application/Ports/IConversationOutputPort.cs @@ -1,45 +1,46 @@ using AgentCore.Application.Conversation; -namespace AgentCore.Application.Ports; - -/// -/// What the agent says, for one conversation. -/// -/// -/// -/// One instance serves one conversation and is disposed with it, as is. -/// -/// -/// Three methods and no events. Every studied voice framework gives its speaking side a method -/// and never a callback the core subscribes to, and the rule is worth more in C# than in the -/// languages they are written in: an event promises no ordering across threads. -/// -/// -public interface IConversationOutputPort : IAsyncDisposable +namespace AgentCore.Application.Ports { - /// Speaks one fragment of the reply. - /// The text to speak. Never empty. - /// Stops waiting for room to send. + /// + /// What the agent says, for one conversation. + /// /// - /// One fragment, never a buffered sentence. A synthesizer that paces its own audio starts - /// speaking before the model finishes the reply, and buffering to a sentence would add the - /// whole first sentence to the time before the caller hears anything. + /// + /// One instance serves one conversation and is disposed with it, as is. + /// + /// + /// Three methods and no events. Every studied voice framework gives its speaking side a method + /// and never a callback the core subscribes to, and the rule is worth more in C# than in the + /// languages they are written in: an event promises no ordering across threads. + /// /// - ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default); + public interface IConversationOutputPort : IAsyncDisposable + { + /// Speaks one fragment of the reply. + /// The text to speak. Never empty. + /// Stops waiting for room to send. + /// + /// One fragment, never a buffered sentence. A synthesizer that paces its own audio starts + /// speaking before the model finishes the reply, and buffering to a sentence would add the + /// whole first sentence to the time before the caller hears anything. + /// + ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default); - /// Closes one reply, so the synthesizer knows no more is coming. - /// Stops waiting for room to send. - ValueTask CompleteAsync(CancellationToken cancellationToken = default); + /// Closes one reply, so the synthesizer knows no more is coming. + /// Stops waiting for room to send. + ValueTask CompleteAsync(CancellationToken cancellationToken = default); - /// Starts stopping the reply, and drops whatever has not been spoken. - /// Stops waiting on the transport. - /// - /// This does not return the cut point, and the two are not simultaneous. The settled - /// answer — what the caller heard, and for how long — arrives afterwards as a - /// on the input stream. A vendor that reports the cut itself - /// settles at once. One built from a separate synthesizer must wait for its own audio to - /// finish draining first, and every implementation of that wait carries a deadline: two - /// seconds is the budget, after which the reply counts as fully heard. - /// - ValueTask StopAsync(CancellationToken cancellationToken = default); + /// Starts stopping the reply, and drops whatever has not been spoken. + /// Stops waiting on the transport. + /// + /// This does not return the cut point, and the two are not simultaneous. The settled + /// answer — what the caller heard, and for how long — arrives afterwards as a + /// on the input stream. A vendor that reports the cut itself + /// settles at once. One built from a separate synthesizer must wait for its own audio to + /// finish draining first, and every implementation of that wait carries a deadline: two + /// seconds is the budget, after which the reply counts as fully heard. + /// + ValueTask StopAsync(CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IConversationPort.cs b/src/AgentCore.Application/Ports/IConversationPort.cs index b2b0b11c..5c0ab7a6 100644 --- a/src/AgentCore.Application/Ports/IConversationPort.cs +++ b/src/AgentCore.Application/Ports/IConversationPort.cs @@ -2,100 +2,101 @@ using AgentCore.Domain.Knowledge; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// -/// The inbound seam of one conversation: start or continue a turn, stream the reply, cancel it. -/// -public interface IConversationPort +namespace AgentCore.Application.Ports { - /// Gets the id of the conversation. - string ConversationId { get; } + /// + /// The inbound seam of one conversation: start or continue a turn, stream the reply, cancel it. + /// + public interface IConversationPort + { + /// Gets the id of the conversation. + string ConversationId { get; } - /// Gets the stage the machine holds. It is empty when the document declares no policy. - string Stage { get; } + /// Gets the stage the machine holds. It is empty when the document declares no policy. + string Stage { get; } - /// Gets whether the conversation reached a terminal stage. A document with no policy never does. - bool IsComplete { get; } + /// Gets whether the conversation reached a terminal stage. A document with no policy never does. + bool IsComplete { get; } - /// Gets or sets the knowledge scope the host opened for this conversation, or null for none. - /// Set it before the run: every turn composes its own scope from it. It outlives turns by construction — one conversation hears one customer. - KnowledgeScope? Scope { get; set; } + /// Gets or sets the knowledge scope the host opened for this conversation, or null for none. + /// Set it before the run: every turn composes its own scope from it. It outlives turns by construction — one conversation hears one customer. + KnowledgeScope? Scope { get; set; } - /// Gets the turn that finished last, or before the first turn ends. - TurnResult? LastTurn { get; } + /// Gets the turn that finished last, or before the first turn ends. + TurnResult? LastTurn { get; } - /// Runs one turn end to end, and returns what it did. - /// What the caller said. - /// Cancels the model calls. - /// The finished turn. It always carries a spoken line. - /// - /// The conversation already ended, or another turn of this conversation is still running. - /// - Task RunTurnAsync(string userInput, CancellationToken cancellationToken = default); + /// Runs one turn end to end, and returns what it did. + /// What the caller said. + /// Cancels the model calls. + /// The finished turn. It always carries a spoken line. + /// + /// The conversation already ended, or another turn of this conversation is still running. + /// + Task RunTurnAsync(string userInput, CancellationToken cancellationToken = default); - /// Runs one turn end to end from a message the caller built, and returns what it did. - /// What the caller said or answered: words, an approval answer, or both. - /// Cancels the model calls. - /// The finished turn. Its reply is empty while approval requests are pending. - /// - /// The conversation already ended, or another turn of this conversation is still running. - /// - Task RunTurnMessageAsync(ChatMessage userInput, CancellationToken cancellationToken); + /// Runs one turn end to end from a message the caller built, and returns what it did. + /// What the caller said or answered: words, an approval answer, or both. + /// Cancels the model calls. + /// The finished turn. Its reply is empty while approval requests are pending. + /// + /// The conversation already ended, or another turn of this conversation is still running. + /// + Task RunTurnMessageAsync(ChatMessage userInput, CancellationToken cancellationToken); - /// Runs one turn and streams the reply as it arrives. - /// What the caller said. - /// Cancels the model calls. - /// The reply, one update at a time. Every update carries content. - /// - /// The turn finishes when the enumeration finishes, and holds it after - /// that. The stream carries no lifecycle update: section 8.6 measured seven of those in one - /// 40-fragment reply, and an adapter must not have to filter them again. - /// - /// - /// The conversation already ended, or another turn of this conversation is still running. - /// - IAsyncEnumerable RunTurnStreamingAsync( - string userInput, - CancellationToken cancellationToken = default); + /// Runs one turn and streams the reply as it arrives. + /// What the caller said. + /// Cancels the model calls. + /// The reply, one update at a time. Every update carries content. + /// + /// The turn finishes when the enumeration finishes, and holds it after + /// that. The stream carries no lifecycle update: section 8.6 measured seven of those in one + /// 40-fragment reply, and an adapter must not have to filter them again. + /// + /// + /// The conversation already ended, or another turn of this conversation is still running. + /// + IAsyncEnumerable RunTurnStreamingAsync( + string userInput, + CancellationToken cancellationToken = default); - /// Runs one turn from a message the caller built and streams the reply as it arrives. - /// What the caller said or answered: words, an approval answer, or both. - /// Cancels the model calls. - /// The reply, one update at a time. Every update carries content. - /// - /// The conversation already ended, or another turn of this conversation is still running. - /// - IAsyncEnumerable RunTurnMessageStreamingAsync( - ChatMessage userInput, - CancellationToken cancellationToken); + /// Runs one turn from a message the caller built and streams the reply as it arrives. + /// What the caller said or answered: words, an approval answer, or both. + /// Cancels the model calls. + /// The reply, one update at a time. Every update carries content. + /// + /// The conversation already ended, or another turn of this conversation is still running. + /// + IAsyncEnumerable RunTurnMessageStreamingAsync( + ChatMessage userInput, + CancellationToken cancellationToken); - /// Ends the running turn where the caller cut the reply off. - /// The text the caller actually heard. - /// How much of the reply played, as the relay reported it. - /// - /// Whether the turn running now is the turn the caller was hearing. An adapter that paces no - /// audio of its own leaves this at and lets the implementation decide. - /// - /// - /// when the barge-in was recorded, either against the running turn or - /// against the turn that finished last, and when there was nothing to - /// record it against. - /// - /// - /// - /// Item 6a of section 11 asks the record to hold what the caller heard, not what the model - /// produced. Section 7.1 reports both values on the interrupt frame, at 1 ms, so an - /// adapter passes them through and never computes them. Item 6c forbids the estimator that would - /// otherwise stand here. - /// - /// - /// carries one domain fact and no frame schema, so D8 holds. - /// A vendor that paces the audio itself is still speaking one turn while the next one already - /// runs — a held prompt starts it inside the finished turn's own ending — and only that adapter - /// can tell the two apart. It answers there, and the turn the caller was - /// actually hearing is the one the record corrects. - /// - /// - bool Interrupt(string utteranceUntilInterrupt, TimeSpan durationUntilInterrupt, bool cutsRunningTurn = true); + /// Ends the running turn where the caller cut the reply off. + /// The text the caller actually heard. + /// How much of the reply played, as the relay reported it. + /// + /// Whether the turn running now is the turn the caller was hearing. An adapter that paces no + /// audio of its own leaves this at and lets the implementation decide. + /// + /// + /// when the barge-in was recorded, either against the running turn or + /// against the turn that finished last, and when there was nothing to + /// record it against. + /// + /// + /// + /// Item 6a of section 11 asks the record to hold what the caller heard, not what the model + /// produced. Section 7.1 reports both values on the interrupt frame, at 1 ms, so an + /// adapter passes them through and never computes them. Item 6c forbids the estimator that would + /// otherwise stand here. + /// + /// + /// carries one domain fact and no frame schema, so D8 holds. + /// A vendor that paces the audio itself is still speaking one turn while the next one already + /// runs — a held prompt starts it inside the finished turn's own ending — and only that adapter + /// can tell the two apart. It answers there, and the turn the caller was + /// actually hearing is the one the record corrects. + /// + /// + bool Interrupt(string utteranceUntilInterrupt, TimeSpan durationUntilInterrupt, bool cutsRunningTurn = true); + } } diff --git a/src/AgentCore.Application/Ports/IConversationSessionFactory.cs b/src/AgentCore.Application/Ports/IConversationSessionFactory.cs index 34b0dc46..6abcbb01 100644 --- a/src/AgentCore.Application/Ports/IConversationSessionFactory.cs +++ b/src/AgentCore.Application/Ports/IConversationSessionFactory.cs @@ -1,13 +1,14 @@ using AgentCore.Application.Conversation; using AgentCore.Application.Runtime; -namespace AgentCore.Application.Ports; - -/// -/// Creates one session for one conversation. -/// -public interface IConversationSessionFactory +namespace AgentCore.Application.Ports { - /// Creates the session of one conversation. - ConversationSession Create(string? conversationId = null, ConversationSessionState? state = null); + /// + /// Creates one session for one conversation. + /// + public interface IConversationSessionFactory + { + /// Creates the session of one conversation. + ConversationSession Create(string? conversationId = null, ConversationSessionState? state = null); + } } diff --git a/src/AgentCore.Application/Ports/IConversationSessionRegistry.cs b/src/AgentCore.Application/Ports/IConversationSessionRegistry.cs index 993ba50c..8b5d2e00 100644 --- a/src/AgentCore.Application/Ports/IConversationSessionRegistry.cs +++ b/src/AgentCore.Application/Ports/IConversationSessionRegistry.cs @@ -1,16 +1,17 @@ -namespace AgentCore.Application.Ports; - -/// -/// Finds the session store of one entry. -/// -public interface IConversationSessionRegistry +namespace AgentCore.Application.Ports { - /// Gets the names of the entries the document declares. - IReadOnlyCollection Entries { get; } + /// + /// Finds the session store of one entry. + /// + public interface IConversationSessionRegistry + { + /// Gets the names of the entries the document declares. + IReadOnlyCollection Entries { get; } - /// Reads one entry's session store. - /// The entry key, as the document declares it. - /// The store for that entry. - /// The entry is not declared. - IConversationSessions ForSessions(string entry); + /// Reads one entry's session store. + /// The entry key, as the document declares it. + /// The store for that entry. + /// The entry is not declared. + IConversationSessions ForSessions(string entry); + } } diff --git a/src/AgentCore.Application/Ports/IConversationSessions.cs b/src/AgentCore.Application/Ports/IConversationSessions.cs index 94e70343..950b6798 100644 --- a/src/AgentCore.Application/Ports/IConversationSessions.cs +++ b/src/AgentCore.Application/Ports/IConversationSessions.cs @@ -1,46 +1,47 @@ using AgentCore.Application.Runtime; -namespace AgentCore.Application.Ports; - -/// -/// Owns the session of a conversation for as long as the conversation needs it. -/// -/// -/// A conversation runs over many turns and one request carries one turn, so something has to hold the -/// session in between. This is that seam, and it owns the whole life of the session rather than -/// only the holding: a caller asks for the session of a conversation and never builds one itself. -/// -public interface IConversationSessions +namespace AgentCore.Application.Ports { - /// Opens the session of one conversation. - /// The id the host gives the conversation, or to be given one. - /// Cancels the open. - /// The session, ready for its first turn. - ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default); - - /// Reads the session of one conversation, and marks the conversation as still live. - /// The id the request named. It is the . - /// Cancels the read. - /// The session, or when this holds no such conversation. + /// + /// Owns the session of a conversation for as long as the conversation needs it. + /// /// - /// A read is the only signal an implementation gets that a conversation is still being had, so an - /// implementation that expires an idle session must restart that session's clock here. A caller - /// that already holds the session for the whole conversation — the relay socket does — must therefore - /// still read it back on each turn, or its own conversation is the one that expires. + /// A conversation runs over many turns and one request carries one turn, so something has to hold the + /// session in between. This is that seam, and it owns the whole life of the session rather than + /// only the holding: a caller asks for the session of a conversation and never builds one itself. /// - ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default); + public interface IConversationSessions + { + /// Opens the session of one conversation. + /// The id the host gives the conversation, or to be given one. + /// Cancels the open. + /// The session, ready for its first turn. + ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default); - /// Ends one conversation: waits for the words it still owes store 1, then drops it. - /// The id of the conversation that ended. - /// Cancels the close. - /// A task that completes once the session is gone and its writes are done. - /// - /// The order is the contract. A turn queues its rows and speaks, so a conversation can end with its last - /// turn still in flight, and the session is the only thing that can wait for those writes — once - /// it is dropped nothing can, and the durable record loses the turn the caller just had with no - /// error anywhere to say so. Every way a session ends comes through here, expiry included, so - /// no path can be written that skips the wait. An implementation must also dispose the session: - /// it owns processes (a conversation's shell: executors) that a dropped reference would leak. - /// - ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default); + /// Reads the session of one conversation, and marks the conversation as still live. + /// The id the request named. It is the . + /// Cancels the read. + /// The session, or when this holds no such conversation. + /// + /// A read is the only signal an implementation gets that a conversation is still being had, so an + /// implementation that expires an idle session must restart that session's clock here. A caller + /// that already holds the session for the whole conversation — the relay socket does — must therefore + /// still read it back on each turn, or its own conversation is the one that expires. + /// + ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default); + + /// Ends one conversation: waits for the words it still owes store 1, then drops it. + /// The id of the conversation that ended. + /// Cancels the close. + /// A task that completes once the session is gone and its writes are done. + /// + /// The order is the contract. A turn queues its rows and speaks, so a conversation can end with its last + /// turn still in flight, and the session is the only thing that can wait for those writes — once + /// it is dropped nothing can, and the durable record loses the turn the caller just had with no + /// error anywhere to say so. Every way a session ends comes through here, expiry included, so + /// no path can be written that skips the wait. An implementation must also dispose the session: + /// it owns processes (a conversation's shell: executors) that a dropped reference would leak. + /// + ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IConversationStore.cs b/src/AgentCore.Application/Ports/IConversationStore.cs index 5a272a67..6fa76ca0 100644 --- a/src/AgentCore.Application/Ports/IConversationStore.cs +++ b/src/AgentCore.Application/Ports/IConversationStore.cs @@ -3,245 +3,246 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// Where store 0 keeps what a conversation is, apart from its words. -public interface IConversationStore +namespace AgentCore.Application.Ports { - /// Makes the conversation's row, or returns the one already there. - /// The conversation to record. - /// Cancels the write. - /// The row, whether this conversation made it or found it. - ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default); - - /// Reads one conversation's row. - /// The conversation to read. - /// Cancels the read. - /// The row, or when store 0 holds none. - ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default); - - /// Lists one principal's conversations, most recently active first. - /// The opaque key to list by. - /// A cursor from an earlier page, or for the first. - /// How many rows this page may hold. - /// The one status to return, or for every status. - /// Cancels the read. - /// The page, and a cursor when a following page exists. - ValueTask ListAsync( - string principalKey, - string? after, - int limit, - ConversationStatus? status = null, - CancellationToken cancellationToken = default); - - /// Sets a conversation's title. - /// The conversation to rename. - /// What to show in a list. - /// Cancels the write. - ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default); - - /// Archives a conversation, or brings it back. - /// The conversation to move. - /// Where to move it. - /// Cancels the write. - ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default); - - /// Replaces a conversation's consumer-owned fields. - /// The conversation to write. - /// The fields, or to clear them. - /// Cancels the write. - ValueTask SetCustomAsync(string conversationId, JsonElement? custom, CancellationToken cancellationToken = default); - - /// Replaces a conversation's consumer-owned id. - /// The conversation to write. - /// The consumer's own id for the conversation, or to clear it. - /// Cancels the write. - ValueTask SetExternalIdAsync(string conversationId, string? externalId, CancellationToken cancellationToken = default); - - /// Erases the conversation's row and every attachment to it. - /// The conversation to erase. - /// Cancels the delete. - ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default); - - /// Writes a turn's new messages, and the state the session holds after them. - /// The conversation every message in belongs to. - /// The rows to write, oldest first. - /// - /// What the session holds after this turn, or to leave the stored state - /// alone. It rides with the words on purpose: a crash between the two would leave the stage - /// behind the words it belongs to. For the same reason, a non- state is - /// silently dropped when is empty: an empty turn writes no words for - /// it to ride with, so there is nothing to write it beside. - /// - /// Cancels the write. - /// - /// The rows as written, in the order given, each with its ordinal and its turn index. - /// - /// - /// The store numbers every row from the conversation's own counter, in one atomic step, so two writers on - /// two machines never collide on an ordinal — one from the conversation's live session, the other from a - /// host appending outside any turn. - /// - /// - /// The conversation named by does not exist. A row is never written against a - /// conversation that has no row of its own. - /// - ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default); - - /// - /// Appends one message to a conversation from outside any turn. The store numbers the row and stamps it - /// with the turn the conversation takes next. Works whether or not a session for the conversation is live. - /// - /// The conversation to append to. - /// The message to append. - /// Cancels the write. - /// The row as written: its ordinal, its turn index, and its id. - async ValueTask AppendMessageAsync( - string conversationId, - ChatMessage message, - CancellationToken cancellationToken = default) + /// Where store 0 keeps what a conversation is, apart from its words. + public interface IConversationStore { - ArgumentNullException.ThrowIfNull(message); - - var messageId = string.IsNullOrEmpty(message.MessageId) ? ConversationMessageIds.New() : message.MessageId; - ConversationMessageDraft draft = new(TurnIndex: null, message, messageId); - - var rows = await AppendAsync(conversationId, [draft], state: null, cancellationToken).ConfigureAwait(false); - return rows[0]; + /// Makes the conversation's row, or returns the one already there. + /// The conversation to record. + /// Cancels the write. + /// The row, whether this conversation made it or found it. + ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default); + + /// Reads one conversation's row. + /// The conversation to read. + /// Cancels the read. + /// The row, or when store 0 holds none. + ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default); + + /// Lists one principal's conversations, most recently active first. + /// The opaque key to list by. + /// A cursor from an earlier page, or for the first. + /// How many rows this page may hold. + /// The one status to return, or for every status. + /// Cancels the read. + /// The page, and a cursor when a following page exists. + ValueTask ListAsync( + string principalKey, + string? after, + int limit, + ConversationStatus? status = null, + CancellationToken cancellationToken = default); + + /// Sets a conversation's title. + /// The conversation to rename. + /// What to show in a list. + /// Cancels the write. + ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default); + + /// Archives a conversation, or brings it back. + /// The conversation to move. + /// Where to move it. + /// Cancels the write. + ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default); + + /// Replaces a conversation's consumer-owned fields. + /// The conversation to write. + /// The fields, or to clear them. + /// Cancels the write. + ValueTask SetCustomAsync(string conversationId, JsonElement? custom, CancellationToken cancellationToken = default); + + /// Replaces a conversation's consumer-owned id. + /// The conversation to write. + /// The consumer's own id for the conversation, or to clear it. + /// Cancels the write. + ValueTask SetExternalIdAsync(string conversationId, string? externalId, CancellationToken cancellationToken = default); + + /// Erases the conversation's row and every attachment to it. + /// The conversation to erase. + /// Cancels the delete. + ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default); + + /// Writes a turn's new messages, and the state the session holds after them. + /// The conversation every message in belongs to. + /// The rows to write, oldest first. + /// + /// What the session holds after this turn, or to leave the stored state + /// alone. It rides with the words on purpose: a crash between the two would leave the stage + /// behind the words it belongs to. For the same reason, a non- state is + /// silently dropped when is empty: an empty turn writes no words for + /// it to ride with, so there is nothing to write it beside. + /// + /// Cancels the write. + /// + /// The rows as written, in the order given, each with its ordinal and its turn index. + /// + /// + /// The store numbers every row from the conversation's own counter, in one atomic step, so two writers on + /// two machines never collide on an ordinal — one from the conversation's live session, the other from a + /// host appending outside any turn. + /// + /// + /// The conversation named by does not exist. A row is never written against a + /// conversation that has no row of its own. + /// + ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default); + + /// + /// Appends one message to a conversation from outside any turn. The store numbers the row and stamps it + /// with the turn the conversation takes next. Works whether or not a session for the conversation is live. + /// + /// The conversation to append to. + /// The message to append. + /// Cancels the write. + /// The row as written: its ordinal, its turn index, and its id. + async ValueTask AppendMessageAsync( + string conversationId, + ChatMessage message, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(message); + + string messageId = string.IsNullOrEmpty(message.MessageId) ? ConversationMessageIds.New() : message.MessageId; + ConversationMessageDraft draft = new(TurnIndex: null, message, messageId); + + IReadOnlyList rows = await AppendAsync(conversationId, [draft], state: null, cancellationToken).ConfigureAwait(false); + return rows[0]; + } + + /// Rewrites one already-written message in place, on a barge-in. + /// The conversation the message belongs to. + /// + /// The message to rewrite, by name rather than by ordinal: the session's in-memory ordinal is + /// still provisional while a turn runs, but the message id is fixed the moment the row is cut. + /// + /// What the caller actually heard. + /// Cancels the write. + ValueTask RewriteAsync( + string conversationId, + string messageId, + ChatMessage content, + CancellationToken cancellationToken = default); + + /// + /// Reads a conversation's words as its session opens them: the newest summary row, and every row + /// above what it covers. The rows a summary stands in for are not read. With no summary, every row. + /// This is the one read that returns a summary row. + /// + /// The conversation to read. + /// Cancels the read. + /// The rows, oldest ordinal first. The summary sits at its own ordinal, above the rows it covers. + ValueTask> ReadForSessionAsync( + string conversationId, + CancellationToken cancellationToken = default); + + /// Reads the newest turns of a conversation before a given one, oldest message first. Summary rows are left out. + /// The conversation to read. + /// Which turns: how many, and before which. + /// Cancels the read. + /// Every message of those turns, or an empty list when none fall in the window. + ValueTask> ReadWindowAsync( + string conversationId, + TranscriptWindow window, + CancellationToken cancellationToken = default); + + /// Finds the ordinal of one message somebody said. Summary rows are not found. + /// The conversation to search. + /// The message to find. + /// Cancels the read. + /// The ordinal, or when the conversation holds no such message. + ValueTask OrdinalOfAsync( + string conversationId, + string messageId, + CancellationToken cancellationToken = default); + + /// + /// Withdraws the tail of a conversation's words, from one ordinal onward. A summary row goes + /// only when the cut reaches a row it covers: written after the rows it stands for, its own + /// ordinal says nothing about where the cut falls. + /// + /// The conversation to cut. + /// The first ordinal to remove. It goes too. + /// Cancels the delete. + /// How many rows went, and the span of turns they belonged to. + ValueTask TruncateAsync( + string conversationId, + int fromOrdinal, + CancellationToken cancellationToken = default); + + /// Erases one conversation's words, and leaves its row in the listing. + /// The conversation to quieten. + /// Cancels the delete. + /// How many messages went. + ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default); + + /// Deletes every conversation whose last activity is older than the retention window. + /// + /// How long a conversation is kept, measured from its most recent message, or from when it was made when + /// it holds none. The window belongs to a deployment: it is not a schema key, and nothing here + /// defaults it. + /// + /// + /// How many conversations one transaction may delete. The sweep loops until a batch deletes nothing, so + /// this bounds one transaction and never the work. + /// + /// Cancels the sweep between batches, and inside one. + /// How many conversations went, over every batch. + ValueTask SweepAsync( + TimeSpan retention, + int batchSize = 500, + CancellationToken cancellationToken = default); + + /// Gives a principal a claim on a conversation. + /// The conversation to claim. + /// The opaque key that claims it. + /// What the key is to this conversation. AgentCore assigns its values no meaning. + /// Cancels the write. + ValueTask AttachPrincipalAsync( + string conversationId, + string principalKey, + string role, + CancellationToken cancellationToken = default); + + /// Takes a principal's claim off a conversation. + /// The conversation to unclaim. + /// The key to remove. + /// Cancels the delete. + ValueTask DetachPrincipalAsync( + string conversationId, + string principalKey, + CancellationToken cancellationToken = default); + + /// Files one session envelope under one continuation id, replacing any envelope already there. + /// The continuation id: a conversation id or a response id. + /// The serialized session, as the agent wrote it. + /// Cancels the write. + /// + /// The continuation names a conversation whose words live in store 1, so the map lives in this store: + /// a resume must never find the key without the words. + /// + ValueTask SaveContinuationAsync( + string continuationId, + JsonElement envelope, + CancellationToken cancellationToken = default); + + /// Reads the envelope one continuation id names. + /// The continuation id to look up. + /// Cancels the read. + /// The envelope, or when nothing is filed under that id. + ValueTask GetContinuationAsync( + string continuationId, + CancellationToken cancellationToken = default); + + /// Withdraws whatever one continuation id names, if anything. + /// The continuation id to forget. + /// Cancels the delete. + ValueTask DeleteContinuationAsync( + string continuationId, + CancellationToken cancellationToken = default); } - - /// Rewrites one already-written message in place, on a barge-in. - /// The conversation the message belongs to. - /// - /// The message to rewrite, by name rather than by ordinal: the session's in-memory ordinal is - /// still provisional while a turn runs, but the message id is fixed the moment the row is cut. - /// - /// What the caller actually heard. - /// Cancels the write. - ValueTask RewriteAsync( - string conversationId, - string messageId, - ChatMessage content, - CancellationToken cancellationToken = default); - - /// - /// Reads a conversation's words as its session opens them: the newest summary row, and every row - /// above what it covers. The rows a summary stands in for are not read. With no summary, every row. - /// This is the one read that returns a summary row. - /// - /// The conversation to read. - /// Cancels the read. - /// The rows, oldest ordinal first. The summary sits at its own ordinal, above the rows it covers. - ValueTask> ReadForSessionAsync( - string conversationId, - CancellationToken cancellationToken = default); - - /// Reads the newest turns of a conversation before a given one, oldest message first. Summary rows are left out. - /// The conversation to read. - /// Which turns: how many, and before which. - /// Cancels the read. - /// Every message of those turns, or an empty list when none fall in the window. - ValueTask> ReadWindowAsync( - string conversationId, - TranscriptWindow window, - CancellationToken cancellationToken = default); - - /// Finds the ordinal of one message somebody said. Summary rows are not found. - /// The conversation to search. - /// The message to find. - /// Cancels the read. - /// The ordinal, or when the conversation holds no such message. - ValueTask OrdinalOfAsync( - string conversationId, - string messageId, - CancellationToken cancellationToken = default); - - /// - /// Withdraws the tail of a conversation's words, from one ordinal onward. A summary row goes - /// only when the cut reaches a row it covers: written after the rows it stands for, its own - /// ordinal says nothing about where the cut falls. - /// - /// The conversation to cut. - /// The first ordinal to remove. It goes too. - /// Cancels the delete. - /// How many rows went, and the span of turns they belonged to. - ValueTask TruncateAsync( - string conversationId, - int fromOrdinal, - CancellationToken cancellationToken = default); - - /// Erases one conversation's words, and leaves its row in the listing. - /// The conversation to quieten. - /// Cancels the delete. - /// How many messages went. - ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default); - - /// Deletes every conversation whose last activity is older than the retention window. - /// - /// How long a conversation is kept, measured from its most recent message, or from when it was made when - /// it holds none. The window belongs to a deployment: it is not a schema key, and nothing here - /// defaults it. - /// - /// - /// How many conversations one transaction may delete. The sweep loops until a batch deletes nothing, so - /// this bounds one transaction and never the work. - /// - /// Cancels the sweep between batches, and inside one. - /// How many conversations went, over every batch. - ValueTask SweepAsync( - TimeSpan retention, - int batchSize = 500, - CancellationToken cancellationToken = default); - - /// Gives a principal a claim on a conversation. - /// The conversation to claim. - /// The opaque key that claims it. - /// What the key is to this conversation. AgentCore assigns its values no meaning. - /// Cancels the write. - ValueTask AttachPrincipalAsync( - string conversationId, - string principalKey, - string role, - CancellationToken cancellationToken = default); - - /// Takes a principal's claim off a conversation. - /// The conversation to unclaim. - /// The key to remove. - /// Cancels the delete. - ValueTask DetachPrincipalAsync( - string conversationId, - string principalKey, - CancellationToken cancellationToken = default); - - /// Files one session envelope under one continuation id, replacing any envelope already there. - /// The continuation id: a conversation id or a response id. - /// The serialized session, as the agent wrote it. - /// Cancels the write. - /// - /// The continuation names a conversation whose words live in store 1, so the map lives in this store: - /// a resume must never find the key without the words. - /// - ValueTask SaveContinuationAsync( - string continuationId, - JsonElement envelope, - CancellationToken cancellationToken = default); - - /// Reads the envelope one continuation id names. - /// The continuation id to look up. - /// Cancels the read. - /// The envelope, or when nothing is filed under that id. - ValueTask GetContinuationAsync( - string continuationId, - CancellationToken cancellationToken = default); - - /// Withdraws whatever one continuation id names, if anything. - /// The continuation id to forget. - /// Cancels the delete. - ValueTask DeleteContinuationAsync( - string continuationId, - CancellationToken cancellationToken = default); } diff --git a/src/AgentCore.Application/Ports/IConversationStoreAdapter.cs b/src/AgentCore.Application/Ports/IConversationStoreAdapter.cs index 4a25c965..df1007dc 100644 --- a/src/AgentCore.Application/Ports/IConversationStoreAdapter.cs +++ b/src/AgentCore.Application/Ports/IConversationStoreAdapter.cs @@ -1,18 +1,19 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Ports; - -/// -/// Opens the store 0 backing behind one providers.conversations value. -/// -public interface IConversationStoreAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Opens the store this vendor writes to, and hands it over. - /// The providers.conversations block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the open. - ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + /// + /// Opens the store 0 backing behind one providers.conversations value. + /// + public interface IConversationStoreAdapter : IVendorAdapter + { + /// Opens the store this vendor writes to, and hands it over. + /// The providers.conversations block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the open. + ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IConversationTitler.cs b/src/AgentCore.Application/Ports/IConversationTitler.cs index 4ca049ff..004eb73d 100644 --- a/src/AgentCore.Application/Ports/IConversationTitler.cs +++ b/src/AgentCore.Application/Ports/IConversationTitler.cs @@ -1,23 +1,24 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// Makes a conversation's title from its words. -public interface IConversationTitler +namespace AgentCore.Application.Ports { - /// Generates one conversation's title, streaming it as it arrives. - /// The conversation to title. - /// Stops the generation. - /// The title in pieces, in order. - IAsyncEnumerable GenerateAsync(string conversationId, CancellationToken cancellationToken = default); + /// Makes a conversation's title from its words. + public interface IConversationTitler + { + /// Generates one conversation's title, streaming it as it arrives. + /// The conversation to title. + /// Stops the generation. + /// The title in pieces, in order. + IAsyncEnumerable GenerateAsync(string conversationId, CancellationToken cancellationToken = default); - // A turn reaches store 1 only once it has finished, so a browser naming a conversation the - // moment it starts finds nothing there to read. It hands over what it is showing instead. - /// Generates one conversation's title from messages the caller holds, streaming it as it arrives. - /// The conversation to title. Its stored messages are not read. - /// The messages to name, with their roles. Empty leaves the conversation unnamed. - /// Stops the generation. - /// The title in pieces, in order. - IAsyncEnumerable GenerateFromAsync( - string conversationId, IReadOnlyList messages, CancellationToken cancellationToken = default); + // A turn reaches store 1 only once it has finished, so a browser naming a conversation the + // moment it starts finds nothing there to read. It hands over what it is showing instead. + /// Generates one conversation's title from messages the caller holds, streaming it as it arrives. + /// The conversation to title. Its stored messages are not read. + /// The messages to name, with their roles. Empty leaves the conversation unnamed. + /// Stops the generation. + /// The title in pieces, in order. + IAsyncEnumerable GenerateFromAsync( + string conversationId, IReadOnlyList messages, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IConversations.cs b/src/AgentCore.Application/Ports/IConversations.cs index 0931d624..d8648a48 100644 --- a/src/AgentCore.Application/Ports/IConversations.cs +++ b/src/AgentCore.Application/Ports/IConversations.cs @@ -3,67 +3,68 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// -/// The door a host or a consumer reads and writes stored conversations through: rows, words, and the -/// files a conversation published, together. Words are read a window of turns at a time and never -/// whole: a consumer that could read a whole conversation would, and a long one is a slow query and a -/// large body every time. What the turn loop and the sweeper need beyond this stays on -/// , which is the adapter seam and not a consumer surface. -/// -public interface IConversations +namespace AgentCore.Application.Ports { - /// - ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default); + /// + /// The door a host or a consumer reads and writes stored conversations through: rows, words, and the + /// files a conversation published, together. Words are read a window of turns at a time and never + /// whole: a consumer that could read a whole conversation would, and a long one is a slow query and a + /// large body every time. What the turn loop and the sweeper need beyond this stays on + /// , which is the adapter seam and not a consumer surface. + /// + public interface IConversations + { + /// + ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default); - /// - ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default); + /// + ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default); - /// Reads one window of a conversation: its row, the newest turns before a given one, and a link to every file those turns kept. - /// The conversation to read. - /// Which turns: how many, and before which. - /// Cancels the read. - /// - /// The window, with set when an older one may exist, or - /// when the store holds no conversation under that id. - /// - ValueTask LoadWindowAsync(string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default); + /// Reads one window of a conversation: its row, the newest turns before a given one, and a link to every file those turns kept. + /// The conversation to read. + /// Which turns: how many, and before which. + /// Cancels the read. + /// + /// The window, with set when an older one may exist, or + /// when the store holds no conversation under that id. + /// + ValueTask LoadWindowAsync(string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default); - /// - ValueTask ListAsync( - string principalKey, - string? after, - int limit, - ConversationStatus? status = null, - CancellationToken cancellationToken = default); + /// + ValueTask ListAsync( + string principalKey, + string? after, + int limit, + ConversationStatus? status = null, + CancellationToken cancellationToken = default); - /// - ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default); + /// + ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default); - /// - ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default); + /// + ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default); - /// - ValueTask SetCustomAsync(string conversationId, JsonElement? custom, CancellationToken cancellationToken = default); + /// + ValueTask SetCustomAsync(string conversationId, JsonElement? custom, CancellationToken cancellationToken = default); - /// - ValueTask SetExternalIdAsync(string conversationId, string? externalId, CancellationToken cancellationToken = default); + /// + ValueTask SetExternalIdAsync(string conversationId, string? externalId, CancellationToken cancellationToken = default); - /// Deletes the conversation: its row, its words, its claims, and every file it kept. - /// The conversation to delete. - /// Cancels the delete. - ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default); + /// Deletes the conversation: its row, its words, its claims, and every file it kept. + /// The conversation to delete. + /// Cancels the delete. + ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default); - /// - ValueTask AppendMessageAsync(string conversationId, ChatMessage message, CancellationToken cancellationToken = default); + /// + ValueTask AppendMessageAsync(string conversationId, ChatMessage message, CancellationToken cancellationToken = default); - /// - ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default); + /// + ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default); - /// - ValueTask AttachPrincipalAsync(string conversationId, string principalKey, string role, CancellationToken cancellationToken = default); + /// + ValueTask AttachPrincipalAsync(string conversationId, string principalKey, string role, CancellationToken cancellationToken = default); - /// - ValueTask DetachPrincipalAsync(string conversationId, string principalKey, CancellationToken cancellationToken = default); + /// + ValueTask DetachPrincipalAsync(string conversationId, string principalKey, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IEmbeddingGeneratorAdapter.cs b/src/AgentCore.Application/Ports/IEmbeddingGeneratorAdapter.cs index 114803c5..a5bc62cc 100644 --- a/src/AgentCore.Application/Ports/IEmbeddingGeneratorAdapter.cs +++ b/src/AgentCore.Application/Ports/IEmbeddingGeneratorAdapter.cs @@ -1,19 +1,20 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// -/// Builds the embedding generator behind one providers.embeddings.kind value. -/// -public interface IEmbeddingGeneratorAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Builds the vendor generator. - /// The providers.embeddings block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the build. - ValueTask>> CreateGeneratorAsync( - EmbeddingProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + /// + /// Builds the embedding generator behind one providers.embeddings.kind value. + /// + public interface IEmbeddingGeneratorAdapter : IVendorAdapter + { + /// Builds the vendor generator. + /// The providers.embeddings block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the build. + ValueTask>> CreateGeneratorAsync( + EmbeddingProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IEvaluationScorePublisher.cs b/src/AgentCore.Application/Ports/IEvaluationScorePublisher.cs index bc52006c..f92f0e68 100644 --- a/src/AgentCore.Application/Ports/IEvaluationScorePublisher.cs +++ b/src/AgentCore.Application/Ports/IEvaluationScorePublisher.cs @@ -1,36 +1,37 @@ using AgentCore.Application.Evaluation; -namespace AgentCore.Application.Ports; - -/// -/// The seam that carries a finished evaluation out of the library. -/// -/// -/// -/// An evaluation ends in a score, and the score has to reach something the host owns: a log, a -/// meter, or the audit chain. This is that one seam, so the library never learns which of those it -/// is. -/// -/// -/// A publisher runs after a turn, never inside one. Decision D9 says a judge must never block a -/// turn, and triage row T18 defers the online path, so an implementation that waits is still correct -/// here and would not be correct on the turn loop. -/// -/// -/// Microsoft.Extensions.AI.Evaluation.Reporting already fills this role: a -/// ScenarioRunResult from ReportingConfiguration.CreateScenarioRunAsync carries the -/// turn identity — ExecutionName, ScenarioName, IterationName — that this seam -/// says belongs to the host, and the host supplies the destination by implementing the library's -/// IEvaluationResultStore rather than this interface. When T18 opens, prefer taking an -/// injected ReportingConfiguration over implementing this port; the offline golden set under -/// tests/AgentCore.Evals already reaches DiskBasedReportingConfiguration this way. -/// -/// -public interface IEvaluationScorePublisher +namespace AgentCore.Application.Ports { - /// Publishes one finished evaluation. - /// The evaluator name and the metrics it produced. - /// Cancels the publish. - /// A task that completes when the score leaves the library. - ValueTask PublishAsync(EvaluationScore score, CancellationToken cancellationToken = default); + /// + /// The seam that carries a finished evaluation out of the library. + /// + /// + /// + /// An evaluation ends in a score, and the score has to reach something the host owns: a log, a + /// meter, or the audit chain. This is that one seam, so the library never learns which of those it + /// is. + /// + /// + /// A publisher runs after a turn, never inside one. Decision D9 says a judge must never block a + /// turn, and triage row T18 defers the online path, so an implementation that waits is still correct + /// here and would not be correct on the turn loop. + /// + /// + /// Microsoft.Extensions.AI.Evaluation.Reporting already fills this role: a + /// ScenarioRunResult from ReportingConfiguration.CreateScenarioRunAsync carries the + /// turn identity — ExecutionName, ScenarioName, IterationName — that this seam + /// says belongs to the host, and the host supplies the destination by implementing the library's + /// IEvaluationResultStore rather than this interface. When T18 opens, prefer taking an + /// injected ReportingConfiguration over implementing this port; the offline golden set under + /// tests/AgentCore.Evals already reaches DiskBasedReportingConfiguration this way. + /// + /// + public interface IEvaluationScorePublisher + { + /// Publishes one finished evaluation. + /// The evaluator name and the metrics it produced. + /// Cancels the publish. + /// A task that completes when the score leaves the library. + ValueTask PublishAsync(EvaluationScore score, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs b/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs index 18b73b69..7f954051 100644 --- a/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs +++ b/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs @@ -1,28 +1,29 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Ports; - -/// -/// Reads whole cards by one exact facet value. -/// -/// -/// This is the keyword half of the knowledge base, beside 's -/// similarity half. A value a caller can name exactly — a model year, a section, a brand — is not -/// something ranking answers well: two adjacent years read as near-identical to an embedding, and -/// the wrong one wins. A store that cannot filter does not implement this interface, and a caller -/// asks for it through . -/// -public interface IKnowledgeFacetReadPort +namespace AgentCore.Application.Ports { - /// Reads the cards carrying one value at one payload path. - /// The payload path, already resolved from scope.template. - /// The value the cards must carry at that path, matched exactly. - /// The most cards to return. - /// Cancels the read. - /// The cards, in no defined order. Empty when nothing carries the value, which is not an error. - ValueTask> ReadByFacetAsync( - string path, - string value, - int limit, - CancellationToken cancellationToken = default); + /// + /// Reads whole cards by one exact facet value. + /// + /// + /// This is the keyword half of the knowledge base, beside 's + /// similarity half. A value a caller can name exactly — a model year, a section, a brand — is not + /// something ranking answers well: two adjacent years read as near-identical to an embedding, and + /// the wrong one wins. A store that cannot filter does not implement this interface, and a caller + /// asks for it through . + /// + public interface IKnowledgeFacetReadPort + { + /// Reads the cards carrying one value at one payload path. + /// The payload path, already resolved from scope.template. + /// The value the cards must carry at that path, matched exactly. + /// The most cards to return. + /// Cancels the read. + /// The cards, in no defined order. Empty when nothing carries the value, which is not an error. + ValueTask> ReadByFacetAsync( + string path, + string value, + int limit, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs b/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs index ef8988c1..043d580d 100644 --- a/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs +++ b/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs @@ -1,43 +1,44 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Ports; - -/// -/// The whole knowledge base, behind one method — and a way to ask for the rest. -/// -/// -/// Search is the one thing every store owes. Everything beyond it — reading whole cards by an -/// exact facet value, say — is a capability a store may or may not have, and it lives on its own -/// interface that only a store able to serve it implements. A caller asks for one through -/// . -/// -public interface IKnowledgeRetrievalPort +namespace AgentCore.Application.Ports { - /// Finds the cards that answer one query. - /// What the caller asked, in their own words. - /// Cancels the search. - /// What the caller may see, or when the caller is unscoped. - /// The cards, best first. It is empty when nothing clears the score floor. - ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default); - - /// Asks this store for a capability it may also serve. - /// The capability being asked for, such as . - /// Names one of several, when a store serves more than one. Most serve none. - /// The capability, or when this store does not serve it. + /// + /// The whole knowledge base, behind one method — and a way to ask for the rest. + /// /// - /// The default answers for a store that is whatever it implements, which is every store that - /// wraps nothing. A store that wraps another overrides this and forwards what it cannot answer, - /// which is the whole reason this is a method and not a cast: a wrapper does not implement what - /// it wraps, so is loses the inner store's capabilities and this does not. + /// Search is the one thing every store owes. Everything beyond it — reading whole cards by an + /// exact facet value, say — is a capability a store may or may not have, and it lives on its own + /// interface that only a store able to serve it implements. A caller asks for one through + /// . /// - /// is . - object? GetService(Type serviceType, object? serviceKey = null) + public interface IKnowledgeRetrievalPort { - ArgumentNullException.ThrowIfNull(serviceType); + /// Finds the cards that answer one query. + /// What the caller asked, in their own words. + /// Cancels the search. + /// What the caller may see, or when the caller is unscoped. + /// The cards, best first. It is empty when nothing clears the score floor. + ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default); + + /// Asks this store for a capability it may also serve. + /// The capability being asked for, such as . + /// Names one of several, when a store serves more than one. Most serve none. + /// The capability, or when this store does not serve it. + /// + /// The default answers for a store that is whatever it implements, which is every store that + /// wraps nothing. A store that wraps another overrides this and forwards what it cannot answer, + /// which is the whole reason this is a method and not a cast: a wrapper does not implement what + /// it wraps, so is loses the inner store's capabilities and this does not. + /// + /// is . + object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } } } diff --git a/src/AgentCore.Application/Ports/IKnowledgeStoreAdapter.cs b/src/AgentCore.Application/Ports/IKnowledgeStoreAdapter.cs index c66821f2..e9f12a15 100644 --- a/src/AgentCore.Application/Ports/IKnowledgeStoreAdapter.cs +++ b/src/AgentCore.Application/Ports/IKnowledgeStoreAdapter.cs @@ -1,42 +1,43 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Ports; - -/// -/// Builds the knowledge port behind one providers.knowledge.kind value. -/// -public interface IKnowledgeStoreAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Gets whether this adapter answers . - bool CanServeSearch { get; } + /// + /// Builds the knowledge port behind one providers.knowledge.kind value. + /// + public interface IKnowledgeStoreAdapter : IVendorAdapter + { + /// Gets whether this adapter answers . + bool CanServeSearch { get; } - /// Gets whether this adapter can confine a search to a KnowledgeScope. - bool CanScope { get; } + /// Gets whether this adapter can confine a search to a KnowledgeScope. + bool CanScope { get; } - /// Builds the knowledge base. - /// The providers.knowledge block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// - /// The generator providers.embeddings built, or when the document - /// names none. An adapter that ranks by vector fails the build on , by - /// name; an adapter that ranks without vectors ignores it. - /// - /// - /// Whether every agent reading this store declares scoped: true. The store is shared - /// across every agent that reads it, so an adapter that fails closed with no - /// KnowledgeScope passed is only correct when ALL of them want scoping -- one store cannot - /// enforce a scope for one agent while staying open for another. A mixed deployment passes - /// here, and the per-agent gate then lives in the caller instead of the - /// store. - /// - /// Cancels the build. - /// The port. The host owns it for the life of the process. - /// is . - ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default); + /// Builds the knowledge base. + /// The providers.knowledge block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// + /// The generator providers.embeddings built, or when the document + /// names none. An adapter that ranks by vector fails the build on , by + /// name; an adapter that ranks without vectors ignores it. + /// + /// + /// Whether every agent reading this store declares scoped: true. The store is shared + /// across every agent that reads it, so an adapter that fails closed with no + /// KnowledgeScope passed is only correct when ALL of them want scoping -- one store cannot + /// enforce a scope for one agent while staying open for another. A mixed deployment passes + /// here, and the per-agent gate then lives in the caller instead of the + /// store. + /// + /// Cancels the build. + /// The port. The host owns it for the life of the process. + /// is . + ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IModerationAdapter.cs b/src/AgentCore.Application/Ports/IModerationAdapter.cs index 6078bc9a..3d8d1fad 100644 --- a/src/AgentCore.Application/Ports/IModerationAdapter.cs +++ b/src/AgentCore.Application/Ports/IModerationAdapter.cs @@ -1,50 +1,51 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Ports; - -/// -/// Builds the moderation evaluator behind one providers.moderation value. -/// -/// -/// -/// This is the moderation mirror of and -/// . The document names a vendor and the host registers one -/// adapter for each vendor it supports, so a document that changes moderation vendors changes no -/// code. -/// -/// -/// D13 makes the moderation port and refuses a second one, so this -/// interface builds an rather than wrapping it. It is a factory, and never -/// a port that a turn conversations. D13 also promises that replacing OpenAI with a self-hosted classifier -/// is a one-file change: that file is the adapter, and this is the seam it plugs into. -/// -/// -/// An adapter owns its vendor only: the endpoint, the credential, and the shape of the reply. -/// Everything vendor-neutral — reading the verdict, refusing the turn, and writing -/// prompt.flagged — lives above it, so no adapter repeats it. -/// -/// -/// A host that registers no adapter, or a document that names no providers.moderation, -/// moderates nothing. Every turn then reaches the model. That is the deliberate default: moderation -/// needs a vendor account, and a library that refused to start without one could not be used in a -/// test. -/// -/// -public interface IModerationAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Builds the evaluator that reads text through this vendor's endpoint. - /// The providers.moderation block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the build. - /// The evaluator. The host owns it for the life of the process. + /// + /// Builds the moderation evaluator behind one providers.moderation value. + /// /// - /// This runs once, while the host starts. A missing credential therefore stops the host and never - /// a conversation, which is what item 9 of section 11 asks for. It opens no socket, so a host with no - /// route to the vendor still starts. + /// + /// This is the moderation mirror of and + /// . The document names a vendor and the host registers one + /// adapter for each vendor it supports, so a document that changes moderation vendors changes no + /// code. + /// + /// + /// D13 makes the moderation port and refuses a second one, so this + /// interface builds an rather than wrapping it. It is a factory, and never + /// a port that a turn conversations. D13 also promises that replacing OpenAI with a self-hosted classifier + /// is a one-file change: that file is the adapter, and this is the seam it plugs into. + /// + /// + /// An adapter owns its vendor only: the endpoint, the credential, and the shape of the reply. + /// Everything vendor-neutral — reading the verdict, refusing the turn, and writing + /// prompt.flagged — lives above it, so no adapter repeats it. + /// + /// + /// A host that registers no adapter, or a document that names no providers.moderation, + /// moderates nothing. Every turn then reaches the model. That is the deliberate default: moderation + /// needs a vendor account, and a library that refused to start without one could not be used in a + /// test. + /// /// - ValueTask CreateAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + public interface IModerationAdapter : IVendorAdapter + { + /// Builds the evaluator that reads text through this vendor's endpoint. + /// The providers.moderation block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the build. + /// The evaluator. The host owns it for the life of the process. + /// + /// This runs once, while the host starts. A missing credential therefore stops the host and never + /// a conversation, which is what item 9 of section 11 asks for. It opens no socket, so a host with no + /// route to the vendor still starts. + /// + ValueTask CreateAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IRenderPort.cs b/src/AgentCore.Application/Ports/IRenderPort.cs index d281da32..b8cd0bcf 100644 --- a/src/AgentCore.Application/Ports/IRenderPort.cs +++ b/src/AgentCore.Application/Ports/IRenderPort.cs @@ -1,10 +1,11 @@ -namespace AgentCore.Application.Ports; - -/// -/// Carries one thing the caller should see from the tool that produced it to the host that shows it. -/// -public interface IRenderPort +namespace AgentCore.Application.Ports { - /// Sends one thing to be shown to the caller of the running conversation. - void Publish(string name, string renderId, object data, bool transient = false); + /// + /// Carries one thing the caller should see from the tool that produced it to the host that shows it. + /// + public interface IRenderPort + { + /// Sends one thing to be shown to the caller of the running conversation. + void Publish(string name, string renderId, object data, bool transient = false); + } } diff --git a/src/AgentCore.Application/Ports/ISecretResolverPort.cs b/src/AgentCore.Application/Ports/ISecretResolverPort.cs index 35fecc7f..0634f07f 100644 --- a/src/AgentCore.Application/Ports/ISecretResolverPort.cs +++ b/src/AgentCore.Application/Ports/ISecretResolverPort.cs @@ -1,32 +1,33 @@ using AgentCore.Application.Secrets; -namespace AgentCore.Application.Ports; - -/// -/// Reads the value behind one ${secret:name} reference. -/// -/// -/// -/// The parser keeps a reference and never a value, so something has to turn the name into the value. -/// This port does that, and AgentCore calls it at startup and not on a tool call: -/// walks the loaded document once, resolves every name it -/// finds, and hands the values to the tool factory. A tool call reads -/// and never this port. -/// -/// -/// An adapter answers when it does not hold the name, so a chain can try the -/// next link. It may still throw when it holds the name and cannot read it, because a store that is -/// present and broken is a startup failure and never a miss. -/// -/// -/// The value is a secret. An adapter never logs it, and never writes it into an exception message. -/// -/// -public interface ISecretResolverPort +namespace AgentCore.Application.Ports { - /// Reads the value of one secret. - /// The name between the colon and the closing brace. - /// Cancels the read. - /// The value, or when this resolver does not hold the name. - ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default); + /// + /// Reads the value behind one ${secret:name} reference. + /// + /// + /// + /// The parser keeps a reference and never a value, so something has to turn the name into the value. + /// This port does that, and AgentCore calls it at startup and not on a tool call: + /// walks the loaded document once, resolves every name it + /// finds, and hands the values to the tool factory. A tool call reads + /// and never this port. + /// + /// + /// An adapter answers when it does not hold the name, so a chain can try the + /// next link. It may still throw when it holds the name and cannot read it, because a store that is + /// present and broken is a startup failure and never a miss. + /// + /// + /// The value is a secret. An adapter never logs it, and never writes it into an exception message. + /// + /// + public interface ISecretResolverPort + { + /// Reads the value of one secret. + /// The name between the colon and the closing brace. + /// Cancels the read. + /// The value, or when this resolver does not hold the name. + ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/ISourcePort.cs b/src/AgentCore.Application/Ports/ISourcePort.cs index b9c62c20..e313e37b 100644 --- a/src/AgentCore.Application/Ports/ISourcePort.cs +++ b/src/AgentCore.Application/Ports/ISourcePort.cs @@ -1,13 +1,14 @@ using AgentCore.Domain.Sources; -namespace AgentCore.Application.Ports; - -/// -/// Carries where an answer came from, from whatever produced it to the host that shows it. -/// -public interface ISourcePort +namespace AgentCore.Application.Ports { - /// Cites one source for the running conversation. - /// Where the answer came from. - void Publish(SourceReference source); + /// + /// Carries where an answer came from, from whatever produced it to the host that shows it. + /// + public interface ISourcePort + { + /// Cites one source for the running conversation. + /// Where the answer came from. + void Publish(SourceReference source); + } } diff --git a/src/AgentCore.Application/Ports/ISpeechAdapter.cs b/src/AgentCore.Application/Ports/ISpeechAdapter.cs index 116406c9..39563412 100644 --- a/src/AgentCore.Application/Ports/ISpeechAdapter.cs +++ b/src/AgentCore.Application/Ports/ISpeechAdapter.cs @@ -1,49 +1,50 @@ -namespace AgentCore.Application.Ports; - -/// -/// Names the vendor behind one speech role's kind, stt or tts. -/// -/// -/// -/// This is the speech mirror of , , -/// , and , and it takes the same shape: -/// the host lists the vendors it supports once, providers.speech names which one the -/// document means for each role — stt is recognition and tts is synthesis — and a -/// document that changes vendors changes no code. -/// -/// -/// It declares no member of its own, so it carries a and -/// nothing else, on purpose. D15 makes every public member -/// a permanent obligation, so a member is added when a caller exists for it and not before. The only -/// vendor this solution ships is a bundled transport — the Telnyx Conversation Relay — and a relay -/// conversation is born from a socket the host already accepted: there is nothing for the adapter to create at -/// selection time, because the frames arriving on that socket are the channel. A create method here -/// today would be a signature no caller passes through and every future vendor must still honour. The -/// first split vendor, whose speech is a separate service the process must dial, is the caller that -/// earns the creation surface, and it adds it then. -/// -/// -/// So each role's kind is a naming field, not a selecting one: it answers "which -/// vendor did the document mean", and nothing here turns that answer into a constructed adapter. -/// is what reads the names today, and only to check them -/// against providers.conversation.kind — because a transport whose frames already carry text, such as -/// the relay this solution ships, is itself the recognizer and the synthesizer, so once the names -/// agree there is nothing left to build. stays the seam's -/// per-conversation face: it answers "open both halves of this one conversation", opened once for every conversation -/// rather than once while the host starts. -/// -/// -/// providers.conversation and providers.speech are required of one another. The schema -/// writes required: ["conversation", "speech"] on the providers object, so a document that -/// writes a providers section at all writes both, and AddAgentCoreAsync refuses a -/// configuration that registered a conversation transport and named no speech vendor. A transport whose -/// frames already carry text must further be named by both speech roles, because such a -/// vendor performs recognition and synthesis itself and a document naming it for the pipe and -/// something else for the ears or the mouth describes a deployment that cannot exist. -/// is what enforces that, while the host starts and before any -/// route is mapped, because the agreement is a fact about the document rather than about a route. -/// -/// -public interface ISpeechAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { + /// + /// Names the vendor behind one speech role's kind, stt or tts. + /// + /// + /// + /// This is the speech mirror of , , + /// , and , and it takes the same shape: + /// the host lists the vendors it supports once, providers.speech names which one the + /// document means for each role — stt is recognition and tts is synthesis — and a + /// document that changes vendors changes no code. + /// + /// + /// It declares no member of its own, so it carries a and + /// nothing else, on purpose. D15 makes every public member + /// a permanent obligation, so a member is added when a caller exists for it and not before. The only + /// vendor this solution ships is a bundled transport — the Telnyx Conversation Relay — and a relay + /// conversation is born from a socket the host already accepted: there is nothing for the adapter to create at + /// selection time, because the frames arriving on that socket are the channel. A create method here + /// today would be a signature no caller passes through and every future vendor must still honour. The + /// first split vendor, whose speech is a separate service the process must dial, is the caller that + /// earns the creation surface, and it adds it then. + /// + /// + /// So each role's kind is a naming field, not a selecting one: it answers "which + /// vendor did the document mean", and nothing here turns that answer into a constructed adapter. + /// is what reads the names today, and only to check them + /// against providers.conversation.kind — because a transport whose frames already carry text, such as + /// the relay this solution ships, is itself the recognizer and the synthesizer, so once the names + /// agree there is nothing left to build. stays the seam's + /// per-conversation face: it answers "open both halves of this one conversation", opened once for every conversation + /// rather than once while the host starts. + /// + /// + /// providers.conversation and providers.speech are required of one another. The schema + /// writes required: ["conversation", "speech"] on the providers object, so a document that + /// writes a providers section at all writes both, and AddAgentCoreAsync refuses a + /// configuration that registered a conversation transport and named no speech vendor. A transport whose + /// frames already carry text must further be named by both speech roles, because such a + /// vendor performs recognition and synthesis itself and a document naming it for the pipe and + /// something else for the ears or the mouth describes a deployment that cannot exist. + /// is what enforces that, while the host starts and before any + /// route is mapped, because the agreement is a fact about the document rather than about a route. + /// + /// + public interface ISpeechAdapter : IVendorAdapter + { + } } diff --git a/src/AgentCore.Application/Ports/ITelemetryAdapter.cs b/src/AgentCore.Application/Ports/ITelemetryAdapter.cs index 299e1958..c65edbe8 100644 --- a/src/AgentCore.Application/Ports/ITelemetryAdapter.cs +++ b/src/AgentCore.Application/Ports/ITelemetryAdapter.cs @@ -1,45 +1,46 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Ports; - -/// -/// Starts the telemetry export behind one providers.telemetry value. -/// -/// -/// -/// This is the telemetry mirror of , -/// , and , and it takes the same -/// shape: the host lists the vendors it supports once, providers.telemetry.kind picks one, and -/// a document that changes vendors changes no code. -/// -/// -/// D26 sends every signal to Grafana Cloud over OTLP, and the adapter for it lives in -/// AgentCore.Infrastructure with the exporter package behind it. Nothing in this project knows -/// OTLP exists, so a deployment that exports somewhere else writes one file and changes one line of -/// its document. -/// -/// -/// A document that names no providers.telemetry exports nothing. Spans and -/// measurements are still written to the ActivitySource and Meter the library owns, -/// where they cost almost nothing with no listener attached, and log lines go wherever the host -/// already sends them. That is the deliberate default: telemetry needs a vendor account, and a -/// library that refused to start without one could not be used in a test. -/// -/// -public interface ITelemetryAdapter : IVendorAdapter +namespace AgentCore.Application.Ports { - /// Starts the export this vendor needs, and holds it. - /// The providers.telemetry block, whose kind named this adapter. - /// The chain a credential resolves through, or . - /// Cancels the start. - /// The running session. The host owns it for the life of the process. + /// + /// Starts the telemetry export behind one providers.telemetry value. + /// /// - /// This runs once, while the host starts. A missing credential therefore stops the host and never - /// a conversation, which is what item 9 of section 11 asks for. It opens no socket: an exporter connects - /// when it first has something to send, so a host with no route to the collector still starts. + /// + /// This is the telemetry mirror of , + /// , and , and it takes the same + /// shape: the host lists the vendors it supports once, providers.telemetry.kind picks one, and + /// a document that changes vendors changes no code. + /// + /// + /// D26 sends every signal to Grafana Cloud over OTLP, and the adapter for it lives in + /// AgentCore.Infrastructure with the exporter package behind it. Nothing in this project knows + /// OTLP exists, so a deployment that exports somewhere else writes one file and changes one line of + /// its document. + /// + /// + /// A document that names no providers.telemetry exports nothing. Spans and + /// measurements are still written to the ActivitySource and Meter the library owns, + /// where they cost almost nothing with no listener attached, and log lines go wherever the host + /// already sends them. That is the deliberate default: telemetry needs a vendor account, and a + /// library that refused to start without one could not be used in a test. + /// /// - ValueTask StartAsync( - TelemetryProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default); + public interface ITelemetryAdapter : IVendorAdapter + { + /// Starts the export this vendor needs, and holds it. + /// The providers.telemetry block, whose kind named this adapter. + /// The chain a credential resolves through, or . + /// Cancels the start. + /// The running session. The host owns it for the life of the process. + /// + /// This runs once, while the host starts. A missing credential therefore stops the host and never + /// a conversation, which is what item 9 of section 11 asks for. It opens no socket: an exporter connects + /// when it first has something to send, so a host with no route to the collector still starts. + /// + ValueTask StartAsync( + TelemetryProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/ITelemetrySession.cs b/src/AgentCore.Application/Ports/ITelemetrySession.cs index 373a6ab2..6728b5e7 100644 --- a/src/AgentCore.Application/Ports/ITelemetrySession.cs +++ b/src/AgentCore.Application/Ports/ITelemetrySession.cs @@ -1,12 +1,13 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Ports; - -/// -/// A running telemetry export, held for the life of the process and shut down with it. -/// -public interface ITelemetrySession : IAsyncDisposable +namespace AgentCore.Application.Ports { - /// Gets the provider that exports log lines, or when none does. - ILoggerProvider? Logs { get; } + /// + /// A running telemetry export, held for the life of the process and shut down with it. + /// + public interface ITelemetrySession : IAsyncDisposable + { + /// Gets the provider that exports log lines, or when none does. + ILoggerProvider? Logs { get; } + } } diff --git a/src/AgentCore.Application/Ports/IToolSource.cs b/src/AgentCore.Application/Ports/IToolSource.cs index 863e7d88..402a2129 100644 --- a/src/AgentCore.Application/Ports/IToolSource.cs +++ b/src/AgentCore.Application/Ports/IToolSource.cs @@ -1,16 +1,17 @@ using AgentCore.Application.Tools.Registry; -namespace AgentCore.Application.Ports; - -/// -/// One place tools come from. -/// -public interface IToolSource +namespace AgentCore.Application.Ports { - /// Names every tool this source serves. - /// The document, and what a source resolves against. - /// Cancels the discovery. - /// One registration for each tool, in any order. - ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default); + /// + /// One place tools come from. + /// + public interface IToolSource + { + /// Names every tool this source serves. + /// The document, and what a source resolves against. + /// Cancels the discovery. + /// One registration for each tool, in any order. + ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default); + } } diff --git a/src/AgentCore.Application/Ports/IVendorAdapter.cs b/src/AgentCore.Application/Ports/IVendorAdapter.cs index 3fc69b95..97c9b954 100644 --- a/src/AgentCore.Application/Ports/IVendorAdapter.cs +++ b/src/AgentCore.Application/Ports/IVendorAdapter.cs @@ -1,24 +1,25 @@ -namespace AgentCore.Application.Ports; - -/// -/// One vendor a kind in the configuration document can name. -/// -/// -/// -/// Every vendor seam in the solution answers the same question — the document wrote a -/// kind, and one of the adapters the host registered serves it. Before this base existed, -/// each of the five seams carried its own copy of that lookup. They now share -/// , and this is the only member it needs. -/// -/// -/// The name is IVendorAdapter and not IAdapter on purpose: what these have in -/// common is not that they adapt something, but that each one is a vendor selected by a name a -/// human wrote in a document. -/// -/// -public interface IVendorAdapter +namespace AgentCore.Application.Ports { - /// Gets the one kind value this adapter serves, such as telnyx-relay. - /// A vendor name is written by a human, so it matches without regard to case. - string Kind { get; } + /// + /// One vendor a kind in the configuration document can name. + /// + /// + /// + /// Every vendor seam in the solution answers the same question — the document wrote a + /// kind, and one of the adapters the host registered serves it. Before this base existed, + /// each of the five seams carried its own copy of that lookup. They now share + /// , and this is the only member it needs. + /// + /// + /// The name is IVendorAdapter and not IAdapter on purpose: what these have in + /// common is not that they adapt something, but that each one is a vendor selected by a name a + /// human wrote in a document. + /// + /// + public interface IVendorAdapter + { + /// Gets the one kind value this adapter serves, such as telnyx-relay. + /// A vendor name is written by a human, so it matches without regard to case. + string Kind { get; } + } } diff --git a/src/AgentCore.Application/Providers/VendorAdapterSelector.cs b/src/AgentCore.Application/Providers/VendorAdapterSelector.cs index 467daef6..ae4c777b 100644 --- a/src/AgentCore.Application/Providers/VendorAdapterSelector.cs +++ b/src/AgentCore.Application/Providers/VendorAdapterSelector.cs @@ -1,100 +1,105 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Ports; -namespace AgentCore.Application.Providers; - -/// -/// Picks the one adapter a kind in the document names, for any vendor seam. -/// -/// -/// -/// Every seam — chat clients, knowledge, moderation, telemetry, speech, and the conversation transport — -/// asked the same question and, before this type, each carried its own copy of the answer. The -/// copies had drifted: four failed when two adapters answered to one kind, and the chat client one -/// silently kept whichever the host listed last. -/// -/// -/// Two adapters for one kind fail the start, in every seam. A host that registers two -/// vendors for openai has a bug, and the alternative is a deployment that runs whichever -/// adapter happened to be listed last. A host that genuinely wants two behaviours gives them two -/// kinds in the document. -/// -/// -public static class VendorAdapterSelector +namespace AgentCore.Application.Providers { - /// Picks the adapter that serves one kind. - /// The adapter interface of one seam. - /// The kind the document wrote. - /// The vendors this host registered for that seam. - /// What this seam conversations itself, for the failure messages. - /// The one adapter serving . - /// The adapters are . - /// - /// No adapter serves the kind, or two of them do. - /// - public static TAdapter Select( - string kind, - IReadOnlyList adapters, - VendorSeam seam) - where TAdapter : IVendorAdapter + /// + /// Picks the one adapter a kind in the document names, for any vendor seam. + /// + /// + /// + /// Every seam — chat clients, knowledge, moderation, telemetry, speech, and the conversation transport — + /// asked the same question and, before this type, each carried its own copy of the answer. The + /// copies had drifted: four failed when two adapters answered to one kind, and the chat client one + /// silently kept whichever the host listed last. + /// + /// + /// Two adapters for one kind fail the start, in every seam. A host that registers two + /// vendors for openai has a bug, and the alternative is a deployment that runs whichever + /// adapter happened to be listed last. A host that genuinely wants two behaviours gives them two + /// kinds in the document. + /// + /// + public static class VendorAdapterSelector { - ArgumentNullException.ThrowIfNull(kind); - ArgumentNullException.ThrowIfNull(adapters); - - // The kind is a vendor name, and a vendor name is written by a human. It matches without - // regard to case, and every other name in the document stays ordinal. - Dictionary> byKind = new(StringComparer.OrdinalIgnoreCase); - foreach (var adapter in adapters) + /// Picks the adapter that serves one kind. + /// The adapter interface of one seam. + /// The kind the document wrote. + /// The vendors this host registered for that seam. + /// What this seam conversations itself, for the failure messages. + /// The one adapter serving . + /// The adapters are . + /// + /// No adapter serves the kind, or two of them do. + /// + public static TAdapter Select( + string kind, + IReadOnlyList adapters, + VendorSeam seam) + where TAdapter : IVendorAdapter { - if (!byKind.TryGetValue(adapter.Kind, out var same)) + ArgumentNullException.ThrowIfNull(kind); + ArgumentNullException.ThrowIfNull(adapters); + + // The kind is a vendor name, and a vendor name is written by a human. It matches without + // regard to case, and every other name in the document stays ordinal. + Dictionary> byKind = new(StringComparer.OrdinalIgnoreCase); + foreach (TAdapter adapter in adapters) { - same = []; - byKind[adapter.Kind] = same; + if (!byKind.TryGetValue(adapter.Kind, out List? same)) + { + same = []; + byKind[adapter.Kind] = same; + } + + same.Add(adapter); } - same.Add(adapter); + if (!byKind.TryGetValue(kind, out List? matching)) + { + throw Fail( + seam, + $"{seam.DocumentPath} is kind: {kind}, and this host registers " + + Registered(byKind, seam)); + } + + if (matching.Count > 1) + { + throw Fail( + seam, + $"two adapters answer to the kind '{kind}', so {seam.DocumentPath} names two " + + $"{seam.Plural}. Register one adapter for each kind."); + } + + return matching[0]; } - if (!byKind.TryGetValue(kind, out var matching)) + /// Writes what the host does register, and the move that would fix the document. + /// + /// A host that registered nothing has no kind to offer the reader instead, so that message names + /// the conversation itself — the shape AddAgentCoreAsync already uses when it names + /// options.UseChatClients(...) to a host that bound no chat client adapter. A host that + /// registered some other vendor is told to add one for this kind, because the list it just read + /// is the rest of the answer. + /// + private static string Registered(Dictionary> byKind, VendorSeam seam) + where TAdapter : IVendorAdapter { - throw Fail( - seam, - $"{seam.DocumentPath} is kind: {kind}, and this host registers " - + Registered(byKind, seam)); + return byKind.Count == 0 + ? $"no adapter. Conversation {seam.RegistrationHint}, or change the document." + : string.Join(", ", byKind.Keys.Select(k => "'" + k + "'")) + + ". Register an adapter for that kind, or change the document."; } - if (matching.Count > 1) + /// Builds the one exception every failure of this selector uses. + private static ConfigurationLoadException Fail(VendorSeam seam, string message) { - throw Fail( - seam, - $"two adapters answer to the kind '{kind}', so {seam.DocumentPath} names two " - + $"{seam.Plural}. Register one adapter for each kind."); + return new(new ConfigurationError + { + Pointer = seam.Pointer, + Message = message, + Check = ConfigurationCheck.ReferenceResolution, + }); } - - return matching[0]; } - - /// Writes what the host does register, and the move that would fix the document. - /// - /// A host that registered nothing has no kind to offer the reader instead, so that message names - /// the conversation itself — the shape AddAgentCoreAsync already uses when it names - /// options.UseChatClients(...) to a host that bound no chat client adapter. A host that - /// registered some other vendor is told to add one for this kind, because the list it just read - /// is the rest of the answer. - /// - private static string Registered(Dictionary> byKind, VendorSeam seam) - where TAdapter : IVendorAdapter - => byKind.Count == 0 - ? $"no adapter. Conversation {seam.RegistrationHint}, or change the document." - : string.Join(", ", byKind.Keys.Select(k => "'" + k + "'")) - + ". Register an adapter for that kind, or change the document."; - - /// Builds the one exception every failure of this selector uses. - private static ConfigurationLoadException Fail(VendorSeam seam, string message) - => new(new ConfigurationError - { - Pointer = seam.Pointer, - Message = message, - Check = ConfigurationCheck.ReferenceResolution, - }); } diff --git a/src/AgentCore.Application/Providers/VendorSeam.cs b/src/AgentCore.Application/Providers/VendorSeam.cs index f86cd549..012e5a9b 100644 --- a/src/AgentCore.Application/Providers/VendorSeam.cs +++ b/src/AgentCore.Application/Providers/VendorSeam.cs @@ -1,38 +1,39 @@ -namespace AgentCore.Application.Providers; - -/// -/// What one vendor seam conversations itself, so a shared selector can write its failures. -/// -/// -/// The dotted path a reader would find in the document, such as providers.speech. -/// -/// -/// The JSON pointer the failure carries, such as /providers/telemetry/kind. This is what a -/// tool uses to underline the offending line, so it must address the kind itself. -/// -/// -/// The call a host makes to register a vendor for this seam, such as options.UseSpeech(...). -/// A host that registered nothing has no kind to be offered instead, so the failure names the conversation -/// to make rather than an empty list. -/// -/// -/// The plural noun this seam conversations two of its vendors, such as stores. It exists so one -/// selector can preserve four seams' wording: knowledge writes stores, telemetry writes -/// collectors, moderation writes endpoints, and speech writes vendors. A seam -/// that names none through the three-argument constructor gets vendors. -/// -public readonly record struct VendorSeam( - string DocumentPath, - string Pointer, - string RegistrationHint, - string Plural) +namespace AgentCore.Application.Providers { - /// Names a seam whose plural noun is the default vendors. - /// The dotted path a reader would find in the document. - /// The JSON pointer the failure carries. - /// The call a host makes to register a vendor for this seam. - public VendorSeam(string documentPath, string pointer, string registrationHint) - : this(documentPath, pointer, registrationHint, "vendors") + /// + /// What one vendor seam conversations itself, so a shared selector can write its failures. + /// + /// + /// The dotted path a reader would find in the document, such as providers.speech. + /// + /// + /// The JSON pointer the failure carries, such as /providers/telemetry/kind. This is what a + /// tool uses to underline the offending line, so it must address the kind itself. + /// + /// + /// The call a host makes to register a vendor for this seam, such as options.UseSpeech(...). + /// A host that registered nothing has no kind to be offered instead, so the failure names the conversation + /// to make rather than an empty list. + /// + /// + /// The plural noun this seam conversations two of its vendors, such as stores. It exists so one + /// selector can preserve four seams' wording: knowledge writes stores, telemetry writes + /// collectors, moderation writes endpoints, and speech writes vendors. A seam + /// that names none through the three-argument constructor gets vendors. + /// + public readonly record struct VendorSeam( + string DocumentPath, + string Pointer, + string RegistrationHint, + string Plural) { + /// Names a seam whose plural noun is the default vendors. + /// The dotted path a reader would find in the document. + /// The JSON pointer the failure carries. + /// The call a host makes to register a vendor for this seam. + public VendorSeam(string documentPath, string pointer, string registrationHint) + : this(documentPath, pointer, registrationHint, "vendors") + { + } } } diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index bc66479b..5ff23ea7 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -1153,7 +1153,7 @@ AgentCore.Application.Providers.VendorSeam.VendorSeam(string! DocumentPath, stri AgentCore.Application.Providers.VendorSeam.VendorSeam(string! documentPath, string! pointer, string! registrationHint) -> void AgentCore.Application.Runtime.AgentCoreAgent AgentCore.Application.Runtime.AgentCoreAgent.AgentCoreAgent(AgentCore.Application.Ports.IConversationSessionFactory! sessions, string! entryName, string? description = null) -> void -AgentCore.Application.Runtime.AgentCoreAgent.CreateSessionAsync(string! conversationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Runtime.AgentCoreAgent.CreateSessionAsync(string! conversationId) -> System.Threading.Tasks.ValueTask AgentCore.Application.Runtime.AgentCoreAgent.EntryName.get -> string! AgentCore.Application.Runtime.ConversationEvent AgentCore.Application.Runtime.ConversationEvent.$() -> AgentCore.Application.Runtime.ConversationEvent! diff --git a/src/AgentCore.Application/Runtime/AgentCoreAgent.cs b/src/AgentCore.Application/Runtime/AgentCoreAgent.cs index 7a7e5ba9..1fbc2e8b 100644 --- a/src/AgentCore.Application/Runtime/AgentCoreAgent.cs +++ b/src/AgentCore.Application/Runtime/AgentCoreAgent.cs @@ -4,338 +4,347 @@ using System.Text.Json; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; +using AgentCore.Domain; -namespace AgentCore.Application.Runtime; - -/// -/// The whole turn loop of this library, behind the framework's own agent abstraction. -/// -/// -/// -/// is the turn loop — moderation, the stage machine, the writers, the audit -/// chain, barge-in — and its seam is , which only this library's -/// own adapters read. This shim puts the same loop behind , the seam the wider -/// ecosystem reads: anything that drives an AIAgent — the framework's protocol hosts (A2A, -/// AG-UI, the OpenAI-compatible endpoints, all prerelease as of Microsoft.Agents.AI 1.17.0), -/// AsAIFunction(), an evaluation harness — can drive a conversation without learning one AgentCore -/// type beyond this one. -/// -/// -/// One is one conversation. -/// starts the conversation, and every run with that session is one turn of it. The session wraps the -/// , and a host that needs the parts of the loop the AIAgent surface -/// does not carry — , -/// , the stage, -/// the transcript — asks the session for it: session.GetService<ConversationSession>(). -/// -/// -/// The session owns the transcript, so a run takes one user message and not a history. The -/// run reads the text of the LAST user message and ignores everything in front of it, which is the -/// same rule the /v1/responses endpoint applies to its input: an earlier message -/// of the conversation is already in the session. A host must not replay history here — replaying it would -/// put every turn in the transcript twice. -/// -/// -/// is accepted and ignored. The compiled document owns the model, the -/// tools, and the response shape, and the framework's contract lets an implementation ignore options -/// it cannot honor. -/// -/// -/// This agent is a process singleton, like the compiled agent it runs: everything per conversation lives in -/// the session. It holds no lock and no state of its own, so 26 concurrent conversations are 26 sessions -/// over one instance. -/// -/// -public sealed class AgentCoreAgent : AIAgent +namespace AgentCore.Application.Runtime { - private readonly IConversationSessionFactory _sessions; - - private readonly string? _description; - - /// Creates the shim over one compiled entry's turn loop. - /// The factory that starts one for each conversation. - /// The entry this agent serves. Reported as . - /// The description the agent reports, or . - /// is . - /// is null or empty. - public AgentCoreAgent(IConversationSessionFactory sessions, string entryName, string? description = null) - { - ArgumentNullException.ThrowIfNull(sessions); - ArgumentException.ThrowIfNullOrEmpty(entryName); - - _sessions = sessions; - EntryName = entryName; - _description = description; - } - - /// Gets the entry this agent serves. - public string EntryName { get; } - - /// - public override string? Name => EntryName; - - /// - public override string? Description => _description; - - /// Starts one conversation under the id the host names. - /// The id the host gives the conversation. The vendor's conversation id belongs here. - /// Unused. The signature mirrors the framework's. - /// The session of the new conversation, with no turn run yet. - /// - /// makes an id up, exactly as - /// does when it is handed none. A voice host has the - /// vendor's conversation id before the first turn, and the audit chain of the conversation should carry it, so - /// this overload exists for the same reason ChatClientAgent.CreateSessionAsync(string) - /// does. - /// - /// is null or empty. - public ValueTask CreateSessionAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrEmpty(conversationId); - return new(new AgentCoreAgentSession(_sessions.Create(conversationId))); - } - - /// - protected override ValueTask CreateSessionCoreAsync(CancellationToken cancellationToken = default) - => new(new AgentCoreAgentSession(_sessions.Create())); - - /// + /// + /// The whole turn loop of this library, behind the framework's own agent abstraction. + /// /// /// - /// What travels is the conversation's id and what its session alone holds: the stage, whether the - /// machine finished, and the slots the writers filled. That is a - /// under the id it belongs to — the same pairing ChatClientAgentSession writes as - /// { conversationId, stateBag }, and for the same reason. State that travelled without - /// its id would come back on a conversation that has none of its words behind it. + /// is the turn loop — moderation, the stage machine, the writers, the audit + /// chain, barge-in — and its seam is , which only this library's + /// own adapters read. This shim puts the same loop behind , the seam the wider + /// ecosystem reads: anything that drives an AIAgent — the framework's protocol hosts (A2A, + /// AG-UI, the OpenAI-compatible endpoints, all prerelease as of Microsoft.Agents.AI 1.17.0), + /// AsAIFunction(), an evaluation harness — can drive a conversation without learning one AgentCore + /// type beyond this one. /// /// - /// The words are not here. They are store 1, which is durable already, so a checkpoint - /// that carried them would give one conversation two records and one chance to disagree. The - /// price is that this is a key and not a copy: a host moving a session between processes still - /// needs the shared store behind it, or the revived conversation answers with an empty transcript. + /// One is one conversation. + /// starts the conversation, and every run with that session is one turn of it. The session wraps the + /// , and a host that needs the parts of the loop the AIAgent surface + /// does not carry — , + /// , the stage, + /// the transcript — asks the session for it: session.GetService<ConversationSession>(). /// /// - /// This blob is not store 0's. A host's reach - /// the nested state member too, not the envelope alone, so that member is encoded to the - /// host's rules and not to , which every store agrees on. It - /// is harmless while the member stays inside the envelope, because this seam and its reader are - /// symmetric. Lifting it out and writing it to store 0 is what would not be. - /// - /// - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - { - // Refused, where a run answers a null session by making one. The fabricated conversation is the - // framework's one-shot shape for a RUN — one turn of a conversation nothing continues — and there is - // no such thing as a one-shot serialize: what it would write is an envelope naming a fresh - // random id beside an empty state, and a host would keep that as its checkpoint and never - // learn it points at nothing. The parameter is not nullable, so this only catches a caller - // that went around the type. - ArgumentNullException.ThrowIfNull(session); - var conversation = Resolve(session); - - return new(JsonSerializer.SerializeToElement( - new SerializedSession(conversation.ConversationId, conversation.Snapshot(), EntryName), - jsonSerializerOptions ?? ConversationStateJson.Options)); - } - - /// - /// - /// - /// Reads back what wrote — see its remarks for what the - /// blob does and does not carry. It is host-facing, so what arrives is not necessarily anything - /// this library wrote, and it stays lenient about that: a blob that names no conversation gets a new id, - /// exactly as does, and state the - /// document no longer allows is dropped slot by slot with a diagnostic rather than refusing the - /// conversation. That second contract is 's and this method does not - /// double it. + /// The session owns the transcript, so a run takes one user message and not a history. The + /// run reads the text of the LAST user message and ignores everything in front of it, which is the + /// same rule the /v1/responses endpoint applies to its input: an earlier message + /// of the conversation is already in the session. A host must not replay history here — replaying it would + /// put every turn in the transcript twice. /// /// - /// The one blob it refuses carries neither member. That is not a validation layer over - /// but a guard against one specific confusion this library - /// creates itself: a bare is the literal value in store 0's - /// conversation.state column, so a host reaching for "the state of this conversation" reaches for the - /// wrong one of two shapes. Read as an envelope it names no conversation and holds no state, and the - /// failure is silent and total — a new random id, and the transcript orphaned behind it. - /// can never write that blob, so refusing it costs the - /// lenient path nothing. + /// is accepted and ignored. The compiled document owns the model, the + /// tools, and the response shape, and the framework's contract lets an implementation ignore options + /// it cannot honor. /// /// - /// Store 0 outranks what arrives here. The state travels with the conversation's id, and the - /// first turn of the revived conversation reads store 0 under that id; where store 0 holds state of its - /// own it wins outright, because its blob rides the same batch as the words. So this decides - /// only a conversation store 0 does not know, or knows without state. See - /// . + /// This agent is a process singleton, like the compiled agent it runs: everything per conversation lives in + /// the session. It holds no lock and no state of its own, so 26 concurrent conversations are 26 sessions + /// over one instance. /// /// - /// - /// names no conversation and holds no state. - /// - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) + public sealed class AgentCoreAgent : AIAgent { - var stored = serializedState.Deserialize( - jsonSerializerOptions ?? ConversationStateJson.Options); + private readonly IConversationSessionFactory _sessions; + + private readonly string? _description; - if (stored is null or { ConversationId: null, State: null }) + /// Creates the shim over one compiled entry's turn loop. + /// The factory that starts one for each conversation. + /// The entry this agent serves. Reported as . + /// The description the agent reports, or . + /// is . + /// is null or empty. + public AgentCoreAgent(IConversationSessionFactory sessions, string entryName, string? description = null) { - throw new ArgumentException( - "The serialized session names no conversation and holds no state, so it is not one this " - + "agent wrote. It expects { conversationId, state } — the conversation's id beside its state. A " - + "bare ConversationSessionState, the value store 0 keeps in conversation.state, is the other shape " - + "and reading it as this one would lose the conversation's transcript.", - nameof(serializedState)); + ArgumentNullException.ThrowIfNull(sessions); + ArgumentException.ThrowIfNullOrEmpty(entryName); + + _sessions = sessions; + EntryName = entryName; + _description = description; } - if (stored.Entry is { Length: > 0 } entry && !string.Equals(entry, EntryName, StringComparison.Ordinal)) + /// Gets the entry this agent serves. + public string EntryName { get; } + + /// + public override string? Name => EntryName; + + /// + public override string? Description => _description; + + /// Starts one conversation under the id the host names. + /// The id the host gives the conversation. The vendor's conversation id belongs here. + /// The session of the new conversation, with no turn run yet. + /// + /// makes an id up, exactly as + /// does when it is handed none. A voice host has the + /// vendor's conversation id before the first turn, and the audit chain of the conversation should carry it, so + /// this overload exists for the same reason ChatClientAgent.CreateSessionAsync(string) + /// does. + /// + /// is null or empty. + public ValueTask CreateSessionAsync(string conversationId) { - throw new InvalidOperationException( - $"The session names entry '{stored.Entry}' and this agent serves entry '{EntryName}'."); + ArgumentException.ThrowIfNullOrEmpty(conversationId); + return new(new AgentCoreAgentSession(_sessions.Create(conversationId))); } - return new(new AgentCoreAgentSession(_sessions.Create(stored.ConversationId, stored.State))); - } + /// + protected override ValueTask CreateSessionCoreAsync(CancellationToken cancellationToken = default) + { + return new(new AgentCoreAgentSession(_sessions.Create())); + } - /// - protected override async Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + /// + /// + /// + /// What travels is the conversation's id and what its session alone holds: the stage, whether the + /// machine finished, and the slots the writers filled. That is a + /// under the id it belongs to — the same pairing ChatClientAgentSession writes as + /// { conversationId, stateBag }, and for the same reason. State that travelled without + /// its id would come back on a conversation that has none of its words behind it. + /// + /// + /// The words are not here. They are store 1, which is durable already, so a checkpoint + /// that carried them would give one conversation two records and one chance to disagree. The + /// price is that this is a key and not a copy: a host moving a session between processes still + /// needs the shared store behind it, or the revived conversation answers with an empty transcript. + /// + /// + /// This blob is not store 0's. A host's reach + /// the nested state member too, not the envelope alone, so that member is encoded to the + /// host's rules and not to , which every store agrees on. It + /// is harmless while the member stays inside the envelope, because this seam and its reader are + /// symmetric. Lifting it out and writing it to store 0 is what would not be. + /// + /// + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + // Refused, where a run answers a null session by making one. The fabricated conversation is the + // framework's one-shot shape for a RUN — one turn of a conversation nothing continues — and there is + // no such thing as a one-shot serialize: what it would write is an envelope naming a fresh + // random id beside an empty state, and a host would keep that as its checkpoint and never + // learn it points at nothing. The parameter is not nullable, so this only catches a caller + // that went around the type. + ArgumentNullException.ThrowIfNull(session); + ConversationSession conversation = Resolve(session); - var conversation = Resolve(session); - var turn = await conversation.RunTurnMessageAsync(UserMessage(messages), cancellationToken).ConfigureAwait(false); + return new(JsonSerializer.SerializeToElement( + new SerializedSession(conversation.ConversationId, conversation.Snapshot(), EntryName), + jsonSerializerOptions ?? ConversationStateJson.Options)); + } - return new AgentResponse(new ChatMessage(ChatRole.Assistant, turn.ReplyText)) + /// + /// + /// + /// Reads back what wrote — see its remarks for what the + /// blob does and does not carry. It is host-facing, so what arrives is not necessarily anything + /// this library wrote, and it stays lenient about that: a blob that names no conversation gets a new id, + /// exactly as does, and state the + /// document no longer allows is dropped slot by slot with a diagnostic rather than refusing the + /// conversation. That second contract is 's and this method does not + /// double it. + /// + /// + /// The one blob it refuses carries neither member. That is not a validation layer over + /// but a guard against one specific confusion this library + /// creates itself: a bare is the literal value in store 0's + /// conversation.state column, so a host reaching for "the state of this conversation" reaches for the + /// wrong one of two shapes. Read as an envelope it names no conversation and holds no state, and the + /// failure is silent and total — a new random id, and the transcript orphaned behind it. + /// can never write that blob, so refusing it costs the + /// lenient path nothing. + /// + /// + /// Store 0 outranks what arrives here. The state travels with the conversation's id, and the + /// first turn of the revived conversation reads store 0 under that id; where store 0 holds state of its + /// own it wins outright, because its blob rides the same batch as the words. So this decides + /// only a conversation store 0 does not know, or knows without state. See + /// . + /// + /// + /// + /// names no conversation and holds no state. + /// + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) { - AgentId = Id, - ResponseId = Guid.NewGuid().ToString("N"), - CreatedAt = turn.EndedAt, - }; - } + SerializedSession? stored = serializedState.Deserialize( + jsonSerializerOptions ?? ConversationStateJson.Options); - /// - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + if (stored is null or { ConversationId: null, State: null }) + { + throw new ArgumentException( + "The serialized session names no conversation and holds no state, so it is not one this " + + "agent wrote. It expects { conversationId, state } — the conversation's id beside its state. A " + + "bare ConversationSessionState, the value store 0 keeps in conversation.state, is the other shape " + + "and reading it as this one would lose the conversation's transcript.", + nameof(serializedState)); + } - return RunCoreStreamingCoreAsync(messages, session, cancellationToken); - } + if (stored.Entry is { Length: > 0 } entry && !string.Equals(entry, EntryName, StringComparison.Ordinal)) + { + throw new InvalidOperationException( + $"The session names entry '{stored.Entry}' and this agent serves entry '{EntryName}'."); + } - /// Streams one turn of the resolved conversation, wrapping each update with this agent's id. - private async IAsyncEnumerable RunCoreStreamingCoreAsync( - IEnumerable messages, - AgentSession? session, - [EnumeratorCancellation] CancellationToken cancellationToken) - { - var conversation = Resolve(session); + return new(new AgentCoreAgentSession(_sessions.Create(stored.ConversationId, stored.State))); + } - // The stream is already filtered: ConversationSession drops the lifecycle updates, so every update - // here carries content. The wrap changes the type and nothing else. - await foreach (var update in conversation.RunTurnMessageStreamingAsync(UserMessage(messages), cancellationToken) - .ConfigureAwait(false)) + /// + protected override async Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) { - yield return new AgentResponseUpdate(update) { AgentId = Id }; + ArgumentNullException.ThrowIfNull(messages); + + ConversationSession conversation = Resolve(session); + TurnResult turn = await conversation.RunTurnMessageAsync(UserMessage(messages), cancellationToken).ConfigureAwait(false); + + return new AgentResponse(new ChatMessage(ChatRole.Assistant, turn.ReplyText)) + { + AgentId = Id, + ResponseId = Guid.NewGuid().ToString("N"), + CreatedAt = turn.EndedAt, + }; } - } - /// Finds the conversation a run belongs to. - /// The session the caller passed, or . - /// The conversation to run the turn on. - /// - /// A session is the framework's one-shot shape — ChatClientAgent - /// answers it with a session it throws away — so it runs one turn of a conversation nothing can continue. - /// A session another agent created is refused, in the framework's own words: every - /// AIAgent implementation measured (ChatClientAgent, the workflow host) refuses a foreign - /// session rather than guessing at its state. - /// - /// belongs to another agent type. - private ConversationSession Resolve(AgentSession? session) => session switch - { - null => _sessions.Create(), - AgentCoreAgentSession own => own.Conversation, - _ => throw new ArgumentException( - $"Incompatible session type: {session.GetType()} (expecting {typeof(AgentCoreAgentSession)}). " - + "Only a session this agent created can carry one of its conversations.", - nameof(session)), - }; + /// + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - /// Reads what the caller said or answered out of the run's messages. - /// The messages the caller passed to the run. - /// The last user message that carries words or an approval answer. - /// - /// The same rule the /v1/responses endpoint applies: the session owns the - /// transcript, so an earlier message of the conversation is already in the session, and only the last - /// user message is new. See the remarks on . - /// - /// No user message carries words or an answer, so there is no turn to run. - private static ChatMessage UserMessage(IEnumerable messages) - { - ChatMessage? picked = null; - foreach (var message in messages) + return RunCoreStreamingCoreAsync(messages, session, cancellationToken); + } + + /// Streams one turn of the resolved conversation, wrapping each update with this agent's id. + private async IAsyncEnumerable RunCoreStreamingCoreAsync( + IEnumerable messages, + AgentSession? session, + [EnumeratorCancellation] CancellationToken cancellationToken) { - if (message.Role == ChatRole.User - && (message.Text is { Length: > 0 } - || message.Contents.OfType().Any())) + ConversationSession conversation = Resolve(session); + + // The stream is already filtered: ConversationSession drops the lifecycle updates, so every update + // here carries content. The wrap changes the type and nothing else. + await foreach (ChatResponseUpdate? update in conversation.RunTurnMessageStreamingAsync(UserMessage(messages), cancellationToken) + .ConfigureAwait(false)) { - picked = message; + yield return new AgentResponseUpdate(update) { AgentId = Id }; } } - return picked ?? throw new ArgumentException( - "The run carries no user message with words or an approval answer, so there is no turn " - + "to run. The session owns the transcript: pass what the caller just said, not a history.", - nameof(messages)); - } + /// Finds the conversation a run belongs to. + /// The session the caller passed, or . + /// The conversation to run the turn on. + /// + /// A session is the framework's one-shot shape — ChatClientAgent + /// answers it with a session it throws away — so it runs one turn of a conversation nothing can continue. + /// A session another agent created is refused, in the framework's own words: every + /// AIAgent implementation measured (ChatClientAgent, the workflow host) refuses a foreign + /// session rather than guessing at its state. + /// + /// belongs to another agent type. + private ConversationSession Resolve(AgentSession? session) + { + return session switch + { + null => _sessions.Create(), + AgentCoreAgentSession own => own.Conversation, + _ => throw new ArgumentException( + $"Incompatible session type: {session.GetType()} (expecting {typeof(AgentCoreAgentSession)}). " + + "Only a session this agent created can carry one of its conversations.", + nameof(session)), + }; + } - /// One serialized session: the conversation it is, the entry it belongs to, and the state it held. - /// The id of the conversation. Store 1 is keyed by it, so it is the half that finds the words. - /// What the session alone held, or when the blob named none. - /// The entry that wrote the blob. A key minted by one entry never reads on another. - /// - /// A separate shape from on purpose. That one is the value store 0 - /// writes under a conversation_id column, so putting the id inside it would give one fact two - /// homes; here there is no column, so the envelope carries the key beside the value instead. - /// Internal because it is a wire shape and not a promise: D15 makes every public type permanent. - /// - internal sealed record SerializedSession(string? ConversationId, ConversationSessionState? State, string? Entry); + /// Reads what the caller said or answered out of the run's messages. + /// The messages the caller passed to the run. + /// The last user message that carries words or an approval answer. + /// + /// The same rule the /v1/responses endpoint applies: the session owns the + /// transcript, so an earlier message of the conversation is already in the session, and only the last + /// user message is new. See the remarks on . + /// + /// No user message carries words or an answer, so there is no turn to run. + private static ChatMessage UserMessage(IEnumerable messages) + { + ChatMessage? picked = null; + foreach (ChatMessage message in messages) + { + if (message.Role == ChatRole.User + && (message.Text is { Length: > 0 } + || message.Contents.OfType().Any())) + { + picked = message; + } + } - /// One conversation, as the framework sees it. - /// - /// It stays internal: a host reaches the call through GetService<ConversationSession>() on - /// the base, and D15 makes every public type a permanent promise this - /// wrapper does not need to be. - /// - internal sealed class AgentCoreAgentSession : AgentSession - { - internal AgentCoreAgentSession(ConversationSession conversation) => Conversation = conversation; + return picked ?? throw new ArgumentException( + "The run carries no user message with words or an approval answer, so there is no turn " + + "to run. The session owns the transcript: pass what the caller just said, not a history.", + nameof(messages)); + } - /// Gets the conversation this session carries. - internal ConversationSession Conversation { get; } + /// One serialized session: the conversation it is, the entry it belongs to, and the state it held. + /// The id of the conversation. Store 1 is keyed by it, so it is the half that finds the words. + /// What the session alone held, or when the blob named none. + /// The entry that wrote the blob. A key minted by one entry never reads on another. + /// + /// A separate shape from on purpose. That one is the value store 0 + /// writes under a conversation_id column, so putting the id inside it would give one fact two + /// homes; here there is no column, so the envelope carries the key beside the value instead. + /// Internal because it is a wire shape and not a promise: D15 makes every public type permanent. + /// + internal sealed record SerializedSession(string? ConversationId, ConversationSessionState? State, string? Entry); - /// + /// One conversation, as the framework sees it. /// - /// Answers the (and its - /// seam), so a host holding only the framework types reaches barge-in, the stage, and the - /// transcript without a cast. + /// It stays internal: a host reaches the call through GetService<ConversationSession>() on + /// the base, and D15 makes every public type a permanent promise this + /// wrapper does not need to be. /// - public override object? GetService(Type serviceType, object? serviceKey = null) + internal sealed class AgentCoreAgentSession : AgentSession { - ArgumentNullException.ThrowIfNull(serviceType); + internal AgentCoreAgentSession(ConversationSession conversation) + { + Conversation = conversation; + } + + /// Gets the conversation this session carries. + internal ConversationSession Conversation { get; } - return serviceKey is null && serviceType.IsInstanceOfType(Conversation) - ? Conversation - : base.GetService(serviceType, serviceKey); + /// + /// + /// Answers the (and its + /// seam), so a host holding only the framework types reaches barge-in, the stage, and the + /// transcript without a cast. + /// + public override object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + + return serviceKey is null && serviceType.IsInstanceOfType(Conversation) + ? Conversation + : base.GetService(serviceType, serviceKey); + } } } } diff --git a/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs b/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs index 0b162e3d..0f897ae1 100644 --- a/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs +++ b/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs @@ -6,206 +6,214 @@ using System.Collections.Concurrent; using AgentCore.Application.Runtime.Turn; -namespace AgentCore.Application.Runtime; - -/// One tool call that did not run to completion, as the function-invocation loop saw it. -internal sealed record ToolFailure -{ - /// Gets the name the MODEL called. - - public required string ToolName { get; init; } - - /// Gets the id the model gave this one call. - public required string ToolCallId { get; init; } - - /// Gets which of the two ways a tool call fails this one was. - public required ToolFailureKind Kind { get; init; } - - /// Gets what went wrong, in one sentence. It never holds a secret value. - public required string Message { get; init; } -} - -/// -/// The function-invocation loop of Microsoft.Extensions.AI, with every tool call that did not -/// run to completion reported to the call that made it, and the tool error policy applied to every -/// call this loop makes. -/// -internal sealed class AuditingFunctionInvokingChatClient : FunctionInvokingChatClient +namespace AgentCore.Application.Runtime { - // Drain state per open tool call, keyed by the model's own call id. The round that ends a - // turn never reaches CreateResponseMessages, so a final round's entries are swept at turn - // end through Release; every other entry is consumed where it drains. - private readonly ConcurrentDictionary _drains = new(StringComparer.Ordinal); - - private sealed record Drain( - IReadOnlyList Attachments, - Action? OnToolFailure, - bool Nested) + /// One tool call that did not run to completion, as the function-invocation loop saw it. + internal sealed record ToolFailure { - /// Takes what one call produced, kind by kind, in the turn's own order. - public IEnumerable TakeFor(string callId) - => Attachments.SelectMany(kind => kind.TakeFor(callId)); - } + /// Gets the name the MODEL called. - /// Creates the client. - /// The model this loop sends its rounds to. - internal AuditingFunctionInvokingChatClient(IChatClient innerClient) - : base(innerClient) - { - } + public required string ToolName { get; init; } - /// Drops drain state for calls whose round never drained, at turn end. - /// Every tool call id the turn recorded. - internal void Release(IReadOnlyList callIds) - { - ArgumentNullException.ThrowIfNull(callIds); + /// Gets the id the model gave this one call. + public required string ToolCallId { get; init; } - foreach (var callId in callIds) - { - _drains.TryRemove(callId, out _); - } + /// Gets which of the two ways a tool call fails this one was. + public required ToolFailureKind Kind { get; init; } + + /// Gets what went wrong, in one sentence. It never holds a secret value. + public required string Message { get; init; } } /// - /// Runs one tool, turns a fault the model can answer into the error result it reads, and reports - /// and rethrows a fault beyond the model. + /// The function-invocation loop of Microsoft.Extensions.AI, with every tool call that did not + /// run to completion reported to the call that made it, and the tool error policy applied to every + /// call this loop makes. /// - protected override async ValueTask InvokeFunctionAsync( - FunctionInvocationContext context, - CancellationToken cancellationToken) + internal sealed class AuditingFunctionInvokingChatClient : FunctionInvokingChatClient { - ArgumentNullException.ThrowIfNull(context); - - var callId = context.CallContent.CallId; - - // The turn arrives on the run's own options — filed there by the loop for the outer - // run and by the delegating bridge for a nested one, one value per run, so concurrent - // runs never share it. A call with no turn runs bare, exactly as the null branch did - // before. Nested runs arrive already stripped per K42 with the outermost call id kept, - // so nothing here recomputes either. - TurnInvocation? invocation = null; - bool nested = false; - - if (context.Options?.AdditionalProperties?.TryGetValue(TurnInvocation.ArgumentsKey, out var top) == true - && top is TurnInvocation own) + // Drain state per open tool call, keyed by the model's own call id. The round that ends a + // turn never reaches CreateResponseMessages, so a final round's entries are swept at turn + // end through Release; every other entry is consumed where it drains. + private readonly ConcurrentDictionary _drains = new(StringComparer.Ordinal); + + private sealed record Drain( + IReadOnlyList Attachments, + Action? OnToolFailure, + bool Nested) { - invocation = own with { OuterCallId = own.OuterCallId ?? callId }; - nested = own.Nested; + /// Takes what one call produced, kind by kind, in the turn's own order. + public IEnumerable TakeFor(string callId) + { + return Attachments.SelectMany(kind => kind.TakeFor(callId)); + } } - if (invocation is not null) + /// Creates the client. + /// The model this loop sends its rounds to. + internal AuditingFunctionInvokingChatClient(IChatClient innerClient) + : base(innerClient) { - // Snapshot the turn once per tool call and file it beside the call's arguments, so tools - // declare what they need as parameters. - invocation.FileIn(context.Arguments); - _drains[callId] = new Drain(invocation.Attachments(), invocation.OnToolFailure, nested); - invocation.Results?.NoteCall(callId, Release); } - using var outerCall = invocation is not null && !nested - ? OuterCall.Open(_drains[callId].Attachments, invocation.OuterCallId ?? callId) - : null; - - try + /// Drops drain state for calls whose round never drained, at turn end. + /// Every tool call id the turn recorded. + internal void Release(IReadOnlyList callIds) { - var result = await base.InvokeFunctionAsync(context, cancellationToken).ConfigureAwait(false); + ArgumentNullException.ThrowIfNull(callIds); - if (!nested) + foreach (string callId in callIds) { - invocation?.Results?.Record(context.Function.Name, result); + _ = _drains.TryRemove(callId, out _); } - - return result; } - catch (Exception failure) when (!IsCallerCancellation(failure, cancellationToken) - && !IsBeyondTheModel(failure)) - { - return ToolErrorResult.Create(context.Function.Name, failure.GetType().Name + ": " + failure.Message); - } - catch (Exception failure) when (!IsCallerCancellation(failure, cancellationToken)) + + /// + /// Runs one tool, turns a fault the model can answer into the error result it reads, and reports + /// and rethrows a fault beyond the model. + /// + protected override async ValueTask InvokeFunctionAsync( + FunctionInvocationContext context, + CancellationToken cancellationToken) { - invocation?.OnToolFailure?.Invoke(new ToolFailure - { - ToolName = context.CallContent.Name, - ToolCallId = context.CallContent.CallId, - Kind = ToolFailureKind.Faulted, - Message = failure.GetType().Name + ": " + failure.Message, - }); + ArgumentNullException.ThrowIfNull(context); - throw; - } - } + string callId = context.CallContent.CallId; - /// Reports whether a fault is one the model cannot possibly answer. - private static bool IsBeyondTheModel(Exception failure) => failure switch - { - // A path the model named that is not there IS answerable: it picks another one. These two - // come first, because both derive from IOException and the arm below would otherwise swallow - // them. A knowledge tool that reads a document the model chose lands here. - FileNotFoundException or DirectoryNotFoundException => false, + // The turn arrives on the run's own options — filed there by the loop for the outer + // run and by the delegating bridge for a nested one, one value per run, so concurrent + // runs never share it. A call with no turn runs bare, exactly as the null branch did + // before. Nested runs arrive already stripped per K42 with the outermost call id kept, + // so nothing here recomputes either. + TurnInvocation? invocation = null; + bool nested = false; - // The host is not resolvable, the connection was refused, or it dropped mid-body. HttpTool - // answers a status code with Failed() itself, so this type only ever reaches here as - // transport. No set of arguments reaches a host that is not answering. - HttpRequestException or SocketException => true, + if (context.Options?.AdditionalProperties?.TryGetValue(TurnInvocation.ArgumentsKey, out object? top) == true + && top is TurnInvocation own) + { + invocation = own with { OuterCallId = own.OuterCallId ?? callId }; + nested = own.Nested; + } - // A pipe, a socket, or a file handle that faulted below the tool. The two "not there" cases - // were already taken above, so what is left is the medium and not the name. - IOException => true, + if (invocation is not null) + { + // Snapshot the turn once per tool call and file it beside the call's arguments, so tools + // declare what they need as parameters. + _ = invocation.FileIn(context.Arguments); + _drains[callId] = new Drain(invocation.Attachments(), invocation.OnToolFailure, nested); + invocation.Results?.NoteCall(callId, Release); + } - // Nothing answered inside the deadline. A second attempt with different arguments waits the - // same amount of time and the caller is on the telephone. - TimeoutException => true, + using OuterCall? outerCall = invocation is not null && !nested + ? OuterCall.Open(_drains[callId].Attachments, invocation.OuterCallId ?? callId) + : null; - // The credential was refused, or the process may not read what it was told to read. Neither - // is a fact the model holds, and retrying a rejected token only rate-limits us. - UnauthorizedAccessException or AuthenticationException => true, + try + { + object? result = await base.InvokeFunctionAsync(context, cancellationToken).ConfigureAwait(false); - // The caller's own cancellation never reaches here — the first catch filter tests the token - // first — so what is left is somebody else's deadline. HttpClient reports its own that way: a - // TaskCanceledException wrapping a TimeoutException, on a token nobody cancelled. - OperationCanceledException => true, + if (!nested) + { + invocation?.Results?.Record(context.Function.Name, result); + } - _ => false, - }; + return result; + } + catch (Exception failure) when (!IsCallerCancellation(failure, cancellationToken) + && !IsBeyondTheModel(failure)) + { + return ToolErrorResult.Create(context.Function.Name, failure.GetType().Name + ": " + failure.Message); + } + catch (Exception failure) when (!IsCallerCancellation(failure, cancellationToken)) + { + invocation?.OnToolFailure?.Invoke(new ToolFailure + { + ToolName = context.CallContent.Name, + ToolCallId = context.CallContent.CallId, + Kind = ToolFailureKind.Faulted, + Message = failure.GetType().Name + ": " + failure.Message, + }); - /// Reports whether a fault is the caller hanging up rather than the tool failing. - private static bool IsCallerCancellation(Exception failure, CancellationToken cancellationToken) - => failure is OperationCanceledException && cancellationToken.IsCancellationRequested; + throw; + } + } - /// - /// Builds the messages the model reads, reports every tool it could not find, and attaches - /// whatever this turn drew, cited, or published to the tool-result message it belongs to. - /// - protected override IList CreateResponseMessages(ReadOnlySpan results) - { - var messages = base.CreateResponseMessages(results); + /// Reports whether a fault is one the model cannot possibly answer. + private static bool IsBeyondTheModel(Exception failure) + { + return failure switch + { + // A path the model named that is not there IS answerable: it picks another one. These two + // come first, because both derive from IOException and the arm below would otherwise swallow + // them. A knowledge tool that reads a document the model chose lands here. + FileNotFoundException or DirectoryNotFoundException => false, + + // The host is not resolvable, the connection was refused, or it dropped mid-body. HttpTool + // answers a status code with Failed() itself, so this type only ever reaches here as + // transport. No set of arguments reaches a host that is not answering. + HttpRequestException or SocketException => true, + + // A pipe, a socket, or a file handle that faulted below the tool. The two "not there" cases + // were already taken above, so what is left is the medium and not the name. + IOException => true, + + // Nothing answered inside the deadline. A second attempt with different arguments waits the + // same amount of time and the caller is on the telephone. + TimeoutException => true, + + // The credential was refused, or the process may not read what it was told to read. Neither + // is a fact the model holds, and retrying a rejected token only rate-limits us. + UnauthorizedAccessException or AuthenticationException => true, + + // The caller's own cancellation never reaches here — the first catch filter tests the token + // first — so what is left is somebody else's deadline. HttpClient reports its own that way: a + // TaskCanceledException wrapping a TimeoutException, on a token nobody cancelled. + OperationCanceledException => true, + + _ => false, + }; + } - foreach (var message in messages) + /// Reports whether a fault is the caller hanging up rather than the tool failing. + private static bool IsCallerCancellation(Exception failure, CancellationToken cancellationToken) { - Attach(message.Contents); + return failure is OperationCanceledException && cancellationToken.IsCancellationRequested; } - return messages; - } + /// + /// Builds the messages the model reads, reports every tool it could not find, and attaches + /// whatever this turn drew, cited, or published to the tool-result message it belongs to. + /// + protected override IList CreateResponseMessages(ReadOnlySpan results) + { + IList messages = base.CreateResponseMessages(results); - /// Appends what each tool result in one message drew, cited, or published. - private void Attach(IList contents) - { - // Materialised before the loop below adds to the very list this reads: Contents is a - // List underneath, and its enumerator throws on the next MoveNext once - // anything has been appended, even where nothing further was left to enumerate. - foreach (var callId in contents.OfType().Select(r => r.CallId).ToList()) + foreach (ChatMessage message in messages) + { + Attach(message.Contents); + } + + return messages; + } + + /// Appends what each tool result in one message drew, cited, or published. + private void Attach(IList contents) { - // A nested loop's calls drain nothing: their ids were registered under the - // stripped copy, so removing the entry without draining keeps the outer drain - // from attaching a nested drawing to a message that never reaches the caller. - // Only the outermost loop's own calls attach what they drew or cited. - if (_drains.TryRemove(callId, out var drain) && !drain.Nested) + // Materialised before the loop below adds to the very list this reads: Contents is a + // List underneath, and its enumerator throws on the next MoveNext once + // anything has been appended, even where nothing further was left to enumerate. + foreach (string? callId in contents.OfType().Select(r => r.CallId).ToList()) { - foreach (var attached in drain.TakeFor(callId)) + // A nested loop's calls drain nothing: their ids were registered under the + // stripped copy, so removing the entry without draining keeps the outer drain + // from attaching a nested drawing to a message that never reaches the caller. + // Only the outermost loop's own calls attach what they drew or cited. + if (_drains.TryRemove(callId, out Drain? drain) && !drain.Nested) { - contents.Add(attached); + foreach (AIContent attached in drain.TakeFor(callId)) + { + contents.Add(attached); + } } } } diff --git a/src/AgentCore.Application/Runtime/ClarificationText.cs b/src/AgentCore.Application/Runtime/ClarificationText.cs index 0249506a..1f8af618 100644 --- a/src/AgentCore.Application/Runtime/ClarificationText.cs +++ b/src/AgentCore.Application/Runtime/ClarificationText.cs @@ -1,58 +1,59 @@ -namespace AgentCore.Application.Runtime; - -/// -/// The sentence §8 specifies for the knowledge probe's note. It rides an empty search result, so it -/// may say plainly that the answer is not yet known. -/// -internal static class ClarificationText +namespace AgentCore.Application.Runtime { - /// Reads the wording a slot is described by. - /// The slot's name. - /// Each slot's configured description, by name. - /// - /// The configured description, or the slot's own name when the document describes it with - /// nothing else. - /// - internal static string DescriptionOf(string slot, IReadOnlyDictionary descriptions) + /// + /// The sentence §8 specifies for the knowledge probe's note. It rides an empty search result, so it + /// may say plainly that the answer is not yet known. + /// + internal static class ClarificationText { - ArgumentNullException.ThrowIfNull(slot); - ArgumentNullException.ThrowIfNull(descriptions); - - return descriptions.TryGetValue(slot, out var configured) && !string.IsNullOrEmpty(configured) - ? configured - : slot; - } + /// Reads the wording a slot is described by. + /// The slot's name. + /// Each slot's configured description, by name. + /// + /// The configured description, or the slot's own name when the document describes it with + /// nothing else. + /// + internal static string DescriptionOf(string slot, IReadOnlyDictionary descriptions) + { + ArgumentNullException.ThrowIfNull(slot); + ArgumentNullException.ThrowIfNull(descriptions); - /// Renders the probe's note, as a search result. - /// - /// The slot's description, or the slot name when the caller has none — used as an - /// apposition, because a deployer's description is a whole sentence. - /// - /// The slot's pending candidate set. - /// Above this many candidates, the list is omitted. - /// The sentence. - internal static string Note(string description, IReadOnlyList candidates, int maxCandidates) - { - ArgumentNullException.ThrowIfNull(description); - ArgumentNullException.ThrowIfNull(candidates); + return descriptions.TryGetValue(slot, out string? configured) && !string.IsNullOrEmpty(configured) + ? configured + : slot; + } - if (candidates.Count == 1) + /// Renders the probe's note, as a search result. + /// + /// The slot's description, or the slot name when the caller has none — used as an + /// apposition, because a deployer's description is a whole sentence. + /// + /// The slot's pending candidate set. + /// Above this many candidates, the list is omitted. + /// The sentence. + internal static string Note(string description, IReadOnlyList candidates, int maxCandidates) { - return "One thing decides the answer here and is not yet confirmed: " - + $"{description} Everything found is for {candidates[0]}. Ask the caller whether that is " - + "what they have before answering from the knowledge base about it."; - } + ArgumentNullException.ThrowIfNull(description); + ArgumentNullException.ThrowIfNull(candidates); - const string decides = "One thing decides the answer here and is not yet known"; + if (candidates.Count == 1) + { + return "One thing decides the answer here and is not yet confirmed: " + + $"{description} Everything found is for {candidates[0]}. Ask the caller whether that is " + + "what they have before answering from the knowledge base about it."; + } - if (candidates.Count > maxCandidates) - { - // "which" needs the list as its antecedent, so the over-cap form drops it. - return $"{decides}: {description} Ask the caller, and do not answer from the knowledge base " - + "about it until they say."; - } + const string decides = "One thing decides the answer here and is not yet known"; - return $"{decides}: {description} It could be: {string.Join(", ", candidates)}. Ask the caller " - + "which, and do not answer from the knowledge base about it until they say."; + if (candidates.Count > maxCandidates) + { + // "which" needs the list as its antecedent, so the over-cap form drops it. + return $"{decides}: {description} Ask the caller, and do not answer from the knowledge base " + + "about it until they say."; + } + + return $"{decides}: {description} It could be: {string.Join(", ", candidates)}. Ask the caller " + + "which, and do not answer from the knowledge base about it until they say."; + } } } diff --git a/src/AgentCore.Application/Runtime/Clarifications.cs b/src/AgentCore.Application/Runtime/Clarifications.cs index 4c7a630e..6f670f68 100644 --- a/src/AgentCore.Application/Runtime/Clarifications.cs +++ b/src/AgentCore.Application/Runtime/Clarifications.cs @@ -1,306 +1,320 @@ using AgentCore.Application.Conversation; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime; - -/// -/// One conversation's memory of what the knowledge probe has asked and named, and the per-turn latch that -/// lets several search-tool calls in one turn share a single probe (K36, K43). -/// -internal sealed class Clarifications +namespace AgentCore.Application.Runtime { - private readonly Lock _gate = new(); - - private readonly Dictionary _slots = new(StringComparer.Ordinal); + /// + /// One conversation's memory of what the knowledge probe has asked and named, and the per-turn latch that + /// lets several search-tool calls in one turn share a single probe (K36, K43). + /// + internal sealed class Clarifications + { + private readonly Lock _gate = new(); - private Probe? _probe; + private readonly Dictionary _slots = new(StringComparer.Ordinal); - /// Reads a consistent snapshot of one slot's two fields, as of one lock acquisition. - /// The slot's name. - /// - /// The snapshot. Every field in it was read under the same lock acquisition, so a concurrent - /// is either fully before it or fully after it — never half of one and half - /// of the other. - /// - internal SlotSnapshot Read(string name) - { - ArgumentNullException.ThrowIfNull(name); + private Probe? _probe; - lock (_gate) + /// Reads a consistent snapshot of one slot's two fields, as of one lock acquisition. + /// The slot's name. + /// + /// The snapshot. Every field in it was read under the same lock acquisition, so a concurrent + /// is either fully before it or fully after it — never half of one and half + /// of the other. + /// + internal SlotSnapshot Read(string name) { - return Snapshot(GetOrAdd(name)); - } - } + ArgumentNullException.ThrowIfNull(name); - /// - /// Runs a compound transition on one slot as a single atomic step: one lock acquisition covers - /// every field touches, so a reader's can never - /// observe the slot mid-transition. - /// - /// The slot's name. - /// - /// What to change. Runs while this object's lock is held — keep it free of anything that could - /// itself try to take the lock (including a call back into or - /// ), or of anything slow, since every other slot is blocked for as long - /// as this runs. - /// - internal void Update(string name, Action mutate) - { - ArgumentNullException.ThrowIfNull(name); - ArgumentNullException.ThrowIfNull(mutate); + lock (_gate) + { + return Snapshot(GetOrAdd(name)); + } + } - lock (_gate) + /// + /// Runs a compound transition on one slot as a single atomic step: one lock acquisition covers + /// every field touches, so a reader's can never + /// observe the slot mid-transition. + /// + /// The slot's name. + /// + /// What to change. Runs while this object's lock is held — keep it free of anything that could + /// itself try to take the lock (including a call back into or + /// ), or of anything slow, since every other slot is blocked for as long + /// as this runs. + /// + internal void Update(string name, Action mutate) { - mutate(GetOrAdd(name)); + ArgumentNullException.ThrowIfNull(name); + ArgumentNullException.ThrowIfNull(mutate); + + lock (_gate) + { + mutate(GetOrAdd(name)); + } } - } - /// - /// Claims this turn's one probe search. Several search-tool calls in one turn, or several graph - /// participants sharing this conversation, race here, and exactly one wins. - /// - /// - /// The turn's probe. is true for the one caller that must run the search - /// and then report through or , and false for - /// every other caller this turn, which replays the winner's outcome through - /// instead. The handle names the turn's own payload, so a conversation - /// that outlives its turn publishes to a latch nothing is waiting on rather than to the next - /// turn's. A winner must resolve the latch on every path out, including a throw, or the turn's - /// other callers wait out their full margin for an outcome that is never coming. - /// - internal Probe ClaimProbe() - { - lock (_gate) + /// + /// Claims this turn's one probe search. Several search-tool calls in one turn, or several graph + /// participants sharing this conversation, race here, and exactly one wins. + /// + /// + /// The turn's probe. is true for the one caller that must run the search + /// and then report through or , and false for + /// every other caller this turn, which replays the winner's outcome through + /// instead. The handle names the turn's own payload, so a conversation + /// that outlives its turn publishes to a latch nothing is waiting on rather than to the next + /// turn's. A winner must resolve the latch on every path out, including a throw, or the turn's + /// other callers wait out their full margin for an outcome that is never coming. + /// + internal Probe ClaimProbe() { - if (_probe is { } claimed) + lock (_gate) { - return claimed.AsLoser(); - } + if (_probe is { } claimed) + { + return claimed.AsLoser(); + } - _probe = new Probe( - new TaskCompletionSource>( - TaskCreationOptions.RunContinuationsAsynchronously), - won: true); + _probe = new Probe( + new TaskCompletionSource>( + TaskCreationOptions.RunContinuationsAsynchronously), + won: true); - return _probe; + return _probe; + } } - } - /// - /// Opens a new turn: drops the turn's probe latch, so a fresh turn claims and replays its own - /// probe rather than the turn before it. - /// - /// - /// Must run exactly once per turn, from ConversationTurnRunner.BeginTurn and nowhere else. - /// - internal void BeginTurn() - { - lock (_gate) + /// + /// Opens a new turn: drops the turn's probe latch, so a fresh turn claims and replays its own + /// probe rather than the turn before it. + /// + /// + /// Must run exactly once per turn, from ConversationTurnRunner.BeginTurn and nowhere else. + /// + internal void BeginTurn() { - _probe = null; + lock (_gate) + { + _probe = null; + } } - } - /// - /// Takes back what an edit-and-resend withdrew: every slot's record of what was last named to - /// the caller. The ask counter is left alone — the caller heard what they heard, and clearing it - /// would let the withdrawn segment buy a fresh maxAsks budget. - /// - internal void Withdraw() - { - lock (_gate) + /// + /// Takes back what an edit-and-resend withdrew: every slot's record of what was last named to + /// the caller. The ask counter is left alone — the caller heard what they heard, and clearing it + /// would let the withdrawn segment buy a fresh maxAsks budget. + /// + internal void Withdraw() { - foreach (var state in _slots.Values) + lock (_gate) { - state.LastNamed = LastNamed.None; + foreach (SlotState state in _slots.Values) + { + state.LastNamed = LastNamed.None; + } } } - } - /// Reads what every slot has spent of its ask budget, for the conversation's stored state. - /// - /// One entry per slot that has spent anything. A slot that has never been asked about is left - /// out, so a conversation that reached no ambiguity stores nothing. - /// - internal IReadOnlyDictionary Spent() - { - lock (_gate) + /// Reads what every slot has spent of its ask budget, for the conversation's stored state. + /// + /// One entry per slot that has spent anything. A slot that has never been asked about is left + /// out, so a conversation that reached no ambiguity stores nothing. + /// + internal IReadOnlyDictionary Spent() { - Dictionary spent = new(StringComparer.Ordinal); - - foreach (var (name, state) in _slots) + lock (_gate) { - if (state.ProbeAsks == 0) + Dictionary spent = new(StringComparer.Ordinal); + + foreach ((string? name, SlotState? state) in _slots) { - continue; + if (state.ProbeAsks == 0) + { + continue; + } + + spent[name] = new ConversationClarificationState { ProbeAsks = state.ProbeAsks }; } - spent[name] = new ConversationClarificationState { ProbeAsks = state.ProbeAsks }; + return spent; } - - return spent; } - } - /// Puts back what an earlier session of this conversation spent of its ask budget. - /// What read from that session. - /// - /// The record of what was last named is deliberately not restored: it belongs to a turn the - /// reconnected caller is no longer in. Only the budget has to survive, and for the reason - /// gives — a caller who drops and comes back must not buy a fresh - /// maxAsks and hear the same question all over again. - /// - internal void RestoreSpent(IReadOnlyDictionary spent) - { - ArgumentNullException.ThrowIfNull(spent); + /// Puts back what an earlier session of this conversation spent of its ask budget. + /// What read from that session. + /// + /// The record of what was last named is deliberately not restored: it belongs to a turn the + /// reconnected caller is no longer in. Only the budget has to survive, and for the reason + /// gives — a caller who drops and comes back must not buy a fresh + /// maxAsks and hear the same question all over again. + /// + internal void RestoreSpent(IReadOnlyDictionary spent) + { + ArgumentNullException.ThrowIfNull(spent); - lock (_gate) + lock (_gate) + { + foreach ((string? name, ConversationClarificationState? stored) in spent) + { + GetOrAdd(name).ProbeAsks = stored.ProbeAsks; + } + } + } + + /// Reads or creates one slot's state. Callers must already hold . + private SlotState GetOrAdd(string name) { - foreach (var (name, stored) in spent) + if (!_slots.TryGetValue(name, out SlotState? state)) { - GetOrAdd(name).ProbeAsks = stored.ProbeAsks; + state = new SlotState(); + _slots.Add(name, state); } + + return state; } - } - /// Reads or creates one slot's state. Callers must already hold . - private SlotState GetOrAdd(string name) - { - if (!_slots.TryGetValue(name, out var state)) + private static SlotSnapshot Snapshot(SlotState state) { - state = new SlotState(); - _slots.Add(name, state); + return new(state.LastNamed, state.ProbeAsks); } - return state; - } + /// What decided the wildcard a slot's last named record holds. + internal enum LastNamedKind + { + /// Nothing has been named to the caller for this slot. + None, - private static SlotSnapshot Snapshot(SlotState state) => new(state.LastNamed, state.ProbeAsks); + /// The exact candidate set last named. + Set, - /// What decided the wildcard a slot's last named record holds. - internal enum LastNamedKind - { - /// Nothing has been named to the caller for this slot. - None, + /// The candidate set was above maxCandidates, so no list was ever spoken. + TooMany, + } - /// The exact candidate set last named. - Set, + /// + /// One turn's probe latch, held by the caller that claimed it. + /// + /// + /// The payload travels on the handle rather than being looked up again on publish, so a search + /// that outlives its turn — an abandoned tool task, a cancellation callback that runs late — + /// resolves the latch of the turn it belongs to and cannot touch the one the next turn opened. + /// + internal sealed class Probe + { + private readonly TaskCompletionSource> _payload; - /// The candidate set was above maxCandidates, so no list was ever spoken. - TooMany, - } + internal Probe( + TaskCompletionSource> payload, bool won) + { + _payload = payload; + Won = won; + } - /// - /// One turn's probe latch, held by the caller that claimed it. - /// - /// - /// The payload travels on the handle rather than being looked up again on publish, so a search - /// that outlives its turn — an abandoned tool task, a cancellation callback that runs late — - /// resolves the latch of the turn it belongs to and cannot touch the one the next turn opened. - /// - internal sealed class Probe - { - private readonly TaskCompletionSource> _payload; + /// Whether this caller is the one that must run the search and publish its outcome. + internal bool Won { get; } - internal Probe( - TaskCompletionSource> payload, bool won) - { - _payload = payload; - Won = won; - } + /// Publishes the winner's probe result for every waiting caller to replay. + /// What the probe's search returned. + internal void Publish(IReadOnlyList cards) + { + ArgumentNullException.ThrowIfNull(cards); - /// Whether this caller is the one that must run the search and publish its outcome. - internal bool Won { get; } + _ = _payload.TrySetResult(cards); + } - /// Publishes the winner's probe result for every waiting caller to replay. - /// What the probe's search returned. - internal void Publish(IReadOnlyList cards) - { - ArgumentNullException.ThrowIfNull(cards); + /// + /// Fails the outcome so every waiting caller wakes rather than burning its full wait margin on + /// a probe that will never answer. The latch stays claimed: nothing was asked and nothing was + /// learned, so this turn must not run a second probe search over it. Safe to call after + /// , which is what lets a winner arm this as its unconditional way out. + /// + internal void Fail() + { + _ = _payload.TrySetCanceled(); + } - _payload.TrySetResult(cards); + /// Waits for the turn's probe winner to publish an outcome. + /// How long to wait beyond the winner's own probe deadline. + /// Cancels the wait. + /// What the winner's search found. + /// + /// The winner's probe was failed by , or was. + /// + /// Nobody published an outcome within . + internal Task> WaitAsync( + TimeSpan timeout, CancellationToken cancellationToken) + { + return _payload.Task.WaitAsync(timeout, cancellationToken); + } + + /// The same latch, handed to a caller that did not claim it. + internal Probe AsLoser() + { + return new(_payload, won: false); + } } - /// - /// Fails the outcome so every waiting caller wakes rather than burning its full wait margin on - /// a probe that will never answer. The latch stays claimed: nothing was asked and nothing was - /// learned, so this turn must not run a second probe search over it. Safe to call after - /// , which is what lets a winner arm this as its unconditional way out. - /// - internal void Fail() => _payload.TrySetCanceled(); - - /// Waits for the turn's probe winner to publish an outcome. - /// How long to wait beyond the winner's own probe deadline. - /// Cancels the wait. - /// What the winner's search found. - /// - /// The winner's probe was failed by , or was. - /// - /// Nobody published an outcome within . - internal Task> WaitAsync( - TimeSpan timeout, CancellationToken cancellationToken) - => _payload.Task.WaitAsync(timeout, cancellationToken); - - /// The same latch, handed to a caller that did not claim it. - internal Probe AsLoser() => new(_payload, won: false); - } + /// One slot's record of what was last named to the caller (K37). + internal readonly record struct LastNamed(LastNamedKind Kind, IReadOnlySet? Values) + { + /// Nothing has been named yet. + internal static readonly LastNamed None = new(LastNamedKind.None, null); - /// One slot's record of what was last named to the caller (K37). - internal readonly record struct LastNamed(LastNamedKind Kind, IReadOnlySet? Values) - { - /// Nothing has been named yet. - internal static readonly LastNamed None = new(LastNamedKind.None, null); + /// The candidate set was above maxCandidates; no list was spoken. + internal static readonly LastNamed TooMany = new(LastNamedKind.TooMany, null); - /// The candidate set was above maxCandidates; no list was spoken. - internal static readonly LastNamed TooMany = new(LastNamedKind.TooMany, null); + /// Records the exact set that was named. + internal static LastNamed Of(IReadOnlySet values) + { + ArgumentNullException.ThrowIfNull(values); + return new LastNamed(LastNamedKind.Set, values); + } - /// Records the exact set that was named. - internal static LastNamed Of(IReadOnlySet values) - { - ArgumentNullException.ThrowIfNull(values); - return new LastNamed(LastNamedKind.Set, values); - } + /// What the probe would record for one candidate set (K37). + /// The candidates the probe is about to name. + /// The document's maxCandidates. + /// + /// when the set is over the cap, so no list is spoken; otherwise the + /// exact set, under the ordinal comparer relies on. + /// + internal static LastNamed For(IReadOnlyCollection candidates, int maxCandidates) + { + ArgumentNullException.ThrowIfNull(candidates); - /// What the probe would record for one candidate set (K37). - /// The candidates the probe is about to name. - /// The document's maxCandidates. - /// - /// when the set is over the cap, so no list is spoken; otherwise the - /// exact set, under the ordinal comparer relies on. - /// - internal static LastNamed For(IReadOnlyCollection candidates, int maxCandidates) - { - ArgumentNullException.ThrowIfNull(candidates); + return candidates.Count > maxCandidates + ? TooMany + : Of(new HashSet(candidates, StringComparer.Ordinal)); + } - return candidates.Count > maxCandidates - ? TooMany - : Of(new HashSet(candidates, StringComparer.Ordinal)); + /// + /// Whether this record names the same thing as . Two too-many + /// records match regardless of their underlying sets: a list neither ever spoke cannot be + /// compared, and two different over-maxCandidates sets are meant to read as the + /// identical question (K34). + /// + /// The record to compare against. + /// when the caller would hear the same question twice. + internal bool Names(LastNamed other) + { + return Kind == other.Kind && (Kind != LastNamedKind.Set || Values!.SetEquals(other.Values!)); + } } + /// A consistent, point-in-time copy of one slot's two fields (see ). + internal readonly record struct SlotSnapshot(LastNamed LastNamed, int ProbeAsks); + /// - /// Whether this record names the same thing as . Two too-many - /// records match regardless of their underlying sets: a list neither ever spoke cannot be - /// compared, and two different over-maxCandidates sets are meant to read as the - /// identical question (K34). + /// One slot's mutable ambiguity state. Read through and written through + /// — never directly, except from inside an callback, + /// which already holds the lock. /// - /// The record to compare against. - /// when the caller would hear the same question twice. - internal bool Names(LastNamed other) - => Kind == other.Kind && (Kind != LastNamedKind.Set || Values!.SetEquals(other.Values!)); - } - - /// A consistent, point-in-time copy of one slot's two fields (see ). - internal readonly record struct SlotSnapshot(LastNamed LastNamed, int ProbeAsks); - - /// - /// One slot's mutable ambiguity state. Read through and written through - /// — never directly, except from inside an callback, - /// which already holds the lock. - /// - internal sealed class SlotState - { - internal LastNamed LastNamed = LastNamed.None; + internal sealed class SlotState + { + internal LastNamed LastNamed = LastNamed.None; - internal int ProbeAsks; + internal int ProbeAsks; + } } } diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs index b0d1b376..729ce552 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs @@ -1,17 +1,18 @@ -namespace AgentCore.Application.Runtime.Compaction; - -/// The fixed constants of the one compaction every agent runs. See D7, D9, D15. -internal static class CompactionDefaults +namespace AgentCore.Application.Runtime.Compaction { - /// Groups for the summary, turns for the cap. The newest ones a stage never touches. - public const int Keep = 4; + /// The fixed constants of the one compaction every agent runs. See D7, D9, D15. + internal static class CompactionDefaults + { + /// Groups for the summary, turns for the cap. The newest ones a stage never touches. + public const int Keep = 4; - /// Characters. What a capped tool result keeps. - public const int CapResultChars = 200; + /// Characters. What a capped tool result keeps. + public const int CapResultChars = 200; - /// Fraction of the model's context window at which compaction fires. - public const double FireFraction = 0.75; + /// Fraction of the model's context window at which compaction fires. + public const double FireFraction = 0.75; - /// Fraction of the model's context window the summary stops at. - public const double TargetFraction = 0.5; + /// Fraction of the model's context window the summary stops at. + public const double TargetFraction = 0.5; + } } diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs index 6226ea8e..238e88a8 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs @@ -1,13 +1,14 @@ using Microsoft.Agents.AI.Compaction; -namespace AgentCore.Application.Runtime.Compaction; - -/// -/// What the two compaction providers of an agent are built from. They run one after the other in -/// the agent's provider chain: the cap first, so the summary reads short results and counts them. -/// -/// Cuts old tool results. No model call. -/// The strategy runs. One model call, its output stored as a row. +namespace AgentCore.Application.Runtime.Compaction +{ + /// + /// What the two compaction providers of an agent are built from. They run one after the other in + /// the agent's provider chain: the cap first, so the summary reads short results and counts them. + /// + /// Cuts old tool results. No model call. + /// The strategy runs. One model call, its output stored as a row. #pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -internal sealed record CompactionStages(ToolResultCapProvider Cap, CompactionStrategy Summary); + internal sealed record CompactionStages(ToolResultCapProvider Cap, CompactionStrategy Summary); #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs index eb0410fa..b3386163 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs @@ -3,58 +3,59 @@ using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Compaction; - -/// -/// Builds the one fixed compaction every agent runs: cap old tool results, then summarise the -/// rest, sized off the model's own context window (D7, D9). The trigger-taking overload lets a -/// test size the same pair to fire on a handful of fixture messages. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -internal static class CompactionStrategyFactory +namespace AgentCore.Application.Runtime.Compaction { - /// Builds the stages off the window fractions. - /// The chat client the summary stage calls. This is the agent's own reply model. - /// The reply model's context window, in tokens. - /// A and a , on the same trigger. - /// is not positive. - public static CompactionStages Create(IChatClient summariser, int contextWindow) + /// + /// Builds the one fixed compaction every agent runs: cap old tool results, then summarise the + /// rest, sized off the model's own context window (D7, D9). The trigger-taking overload lets a + /// test size the same pair to fire on a handful of fixture messages. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + internal static class CompactionStrategyFactory { - ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(contextWindow, 0); + /// Builds the stages off the window fractions. + /// The chat client the summary stage calls. This is the agent's own reply model. + /// The reply model's context window, in tokens. + /// A and a , on the same trigger. + /// is not positive. + public static CompactionStages Create(IChatClient summariser, int contextWindow) + { + ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(contextWindow, 0); - return Create( - summariser, - CompactionTriggers.TokensExceed((int)(contextWindow * CompactionDefaults.FireFraction)), - CompactionTriggers.TokensBelow((int)(contextWindow * CompactionDefaults.TargetFraction))); - } + return Create( + summariser, + CompactionTriggers.TokensExceed((int)(contextWindow * CompactionDefaults.FireFraction)), + CompactionTriggers.TokensBelow((int)(contextWindow * CompactionDefaults.TargetFraction))); + } - /// Builds the stages off explicit triggers. A test passes Always and Never here. - /// The chat client the summary stage calls. - /// When a stage applies, judged over everything bound for the model. - /// Where the summary stops. Only the summary stage reads this. - /// A and a , on the same trigger. - public static CompactionStages Create(IChatClient summariser, CompactionTrigger fire, CompactionTrigger target) - { - ArgumentNullException.ThrowIfNull(summariser); - ArgumentNullException.ThrowIfNull(fire); - ArgumentNullException.ThrowIfNull(target); + /// Builds the stages off explicit triggers. A test passes Always and Never here. + /// The chat client the summary stage calls. + /// When a stage applies, judged over everything bound for the model. + /// Where the summary stops. Only the summary stage reads this. + /// A and a , on the same trigger. + public static CompactionStages Create(IChatClient summariser, CompactionTrigger fire, CompactionTrigger target) + { + ArgumentNullException.ThrowIfNull(summariser); + ArgumentNullException.ThrowIfNull(fire); + ArgumentNullException.ThrowIfNull(target); - return new CompactionStages( - new ToolResultCapProvider(fire, CompactionDefaults.Keep, CompactionDefaults.CapResultChars), - new SummarizationCompactionStrategy(summariser, fire, CompactionDefaults.Keep, target: target)); - } + return new CompactionStages( + new ToolResultCapProvider(fire, CompactionDefaults.Keep, CompactionDefaults.CapResultChars), + new SummarizationCompactionStrategy(summariser, fire, CompactionDefaults.Keep, target: target)); + } - /// Builds the providers in chain order: the cap always runs, the summary needs history to persist its row. - /// The cap provider and the strategy the summary provider runs. - /// Store 1, or when the session carries no history. - /// The cap, then the summary when there is somewhere to write it. - public static AIContextProvider[] BuildProviders(CompactionStages stages, AgentCoreChatHistoryProvider? history) - { - ArgumentNullException.ThrowIfNull(stages); + /// Builds the providers in chain order: the cap always runs, the summary needs history to persist its row. + /// The cap provider and the strategy the summary provider runs. + /// Store 1, or when the session carries no history. + /// The cap, then the summary when there is somewhere to write it. + public static AIContextProvider[] BuildProviders(CompactionStages stages, AgentCoreChatHistoryProvider? history) + { + ArgumentNullException.ThrowIfNull(stages); - return history is null - ? [stages.Cap] - : [stages.Cap, new SummaryRowProvider(history, stages.Summary)]; + return history is null + ? [stages.Cap] + : [stages.Cap, new SummaryRowProvider(history, stages.Summary)]; + } } -} #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Runtime/Compaction/ReaderContentFilterProvider.cs b/src/AgentCore.Application/Runtime/Compaction/ReaderContentFilterProvider.cs index 7a0aa99e..a7923f37 100644 --- a/src/AgentCore.Application/Runtime/Compaction/ReaderContentFilterProvider.cs +++ b/src/AgentCore.Application/Runtime/Compaction/ReaderContentFilterProvider.cs @@ -1,30 +1,28 @@ using AgentCore.Application.Transcript; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Compaction; - -/// -/// Removes reader content () from the messages bound for the model. -/// -internal sealed class ReaderContentFilterProvider : AIContextProvider +namespace AgentCore.Application.Runtime.Compaction { - /// - protected override ValueTask InvokingCoreAsync( - InvokingContext context, CancellationToken cancellationToken = default) + /// + /// Removes reader content () from the messages bound for the model. + /// + internal sealed class ReaderContentFilterProvider : AIContextProvider { - ArgumentNullException.ThrowIfNull(context); - - var input = context.AIContext; - if (input.Messages is null) + /// + protected override ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) { - return new(input); - } + ArgumentNullException.ThrowIfNull(context); - return new(new AIContext - { - Instructions = input.Instructions, - Messages = ReaderContent.Strip(input.Messages).ToList(), - Tools = input.Tools, - }); + AIContext input = context.AIContext; + return input.Messages is null + ? new(input) + : new(new AIContext + { + Instructions = input.Instructions, + Messages = ReaderContent.Strip(input.Messages).ToList(), + Tools = input.Tools, + }); + } } } diff --git a/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs b/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs index 376f0957..b2ae1a05 100644 --- a/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs +++ b/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs @@ -4,148 +4,147 @@ using Microsoft.Agents.AI; using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Runtime.Compaction; - -/// -/// The persisted half of compaction. Runs in the provider chain after the tool-result cap, over the -/// rows before the newest turn, and hands the model the strategy's output: one summary message, then -/// the rows it kept. The summary lands in the transcript as a row that covers the rows it replaced -/// () before the request goes out, so the next -/// session opens on it and the summariser is never asked about those rows again. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -internal sealed class SummaryRowProvider : AIContextProvider +namespace AgentCore.Application.Runtime.Compaction { - private readonly AgentCoreChatHistoryProvider _history; - - private readonly CompactionStrategy _summary; - - /// Store 1, which says what a compaction may cover and takes the row. - /// The strategy that replaces the oldest messages with one summary. One model call. - public SummaryRowProvider(AgentCoreChatHistoryProvider history, CompactionStrategy summary) + /// + /// The persisted half of compaction. Runs in the provider chain after the tool-result cap, over the + /// rows before the newest turn, and hands the model the strategy's output: one summary message, then + /// the rows it kept. The summary lands in the transcript as a row that covers the rows it replaced + /// () before the request goes out, so the next + /// session opens on it and the summariser is never asked about those rows again. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + internal sealed class SummaryRowProvider : AIContextProvider { - ArgumentNullException.ThrowIfNull(history); - ArgumentNullException.ThrowIfNull(summary); - - _history = history; - _summary = summary; - } + private readonly AgentCoreChatHistoryProvider _history; - /// - protected override async ValueTask InvokingCoreAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); + private readonly CompactionStrategy _summary; - var input = context.AIContext; - if (input.Messages is null || context.Session is not { } session || _history.Floor(session) is not { } floor) + /// Store 1, which says what a compaction may cover and takes the row. + /// The strategy that replaces the oldest messages with one summary. One model call. + public SummaryRowProvider(AgentCoreChatHistoryProvider history, CompactionStrategy summary) { - return input; - } + ArgumentNullException.ThrowIfNull(history); + ArgumentNullException.ThrowIfNull(summary); - var messages = input.Messages as IReadOnlyList ?? input.Messages.ToList(); - if (!Leads(floor.Messages, messages)) - { - return input; + _history = history; + _summary = summary; } - var turn = TurnRegistry.For(session); - var logger = turn?.Logger ?? NullLogger.Instance; - - // The stages before this one strip and cap by making new instances, so the view the - // strategy runs over is the model-bound prefix, not the floor's own messages; the floor - // lines up with it by index and lends it the ordinals. - var view = messages.Take(floor.Messages.Count).ToList(); - - try + /// + protected override async ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) { - var output = (await CompactionProvider.CompactAsync(_summary, view, logger, cancellationToken).ConfigureAwait(false)).ToList(); + ArgumentNullException.ThrowIfNull(context); - if (output.Count == view.Count && output.Zip(view).All(pair => ReferenceEquals(pair.First, pair.Second))) + AIContext input = context.AIContext; + if (input.Messages is null || context.Session is not { } session || _history.Floor(session) is not { } floor) { return input; } - if (Kept(view, output) is not { } kept) + IReadOnlyList messages = input.Messages as IReadOnlyList ?? [.. input.Messages]; + if (!Leads(floor.Messages, messages)) { - if (turn is not null) - { - Log.TranscriptCompactionUnsupported(logger, turn.ConversationId, turn.TurnIndex); - } - return input; } - var coversUpTo = floor.Messages[kept - 1].LastOrdinal; - if (coversUpTo <= floor.CoversUpTo || !_history.Compact(session, output[0], coversUpTo, floor.Revision)) - { - return input; - } + TurnInvocation? turn = TurnRegistry.For(session); + ILogger logger = turn?.Logger ?? NullLogger.Instance; + + // The stages before this one strip and cap by making new instances, so the view the + // strategy runs over is the model-bound prefix, not the floor's own messages; the floor + // lines up with it by index and lends it the ordinals. + List view = [.. messages.Take(floor.Messages.Count)]; - return new AIContext + try { - Instructions = input.Instructions, - Messages = [output[0], .. messages.Skip(kept)], - Tools = input.Tools, - }; - } + List output = [.. await CompactionProvider.CompactAsync(_summary, view, logger, cancellationToken).ConfigureAwait(false)]; + + if (output.Count == view.Count && output.Zip(view).All(pair => ReferenceEquals(pair.First, pair.Second))) + { + return input; + } + + if (Kept(view, output) is not { } kept) + { + if (turn is not null) + { + Log.TranscriptCompactionUnsupported(logger, turn.ConversationId, turn.TurnIndex); + } + + return input; + } + + int coversUpTo = floor.Messages[kept - 1].LastOrdinal; + return coversUpTo <= floor.CoversUpTo || !_history.Compact(session, output[0], coversUpTo, floor.Revision) + ? input + : new AIContext + { + Instructions = input.Instructions, + Messages = [output[0], .. messages.Skip(kept)], + Tools = input.Tools, + }; + } #pragma warning disable CA1031 // A strategy that throws never ends a conversation: the session keeps the view it had. - catch (Exception exception) when (exception is not OperationCanceledException) + catch (Exception exception) when (exception is not OperationCanceledException) #pragma warning restore CA1031 - { - if (turn is not null) { - Log.TranscriptCompactionFailed(logger, turn.ConversationId, turn.TurnIndex, exception); - } - - return input; - } - } + if (turn is not null) + { + Log.TranscriptCompactionFailed(logger, turn.ConversationId, turn.TurnIndex, exception); + } - /// Whether the floor's rows lead the model-bound list, id for id. - private static bool Leads(IReadOnlyList floor, IReadOnlyList messages) - { - if (floor.Count > messages.Count) - { - return false; + return input; + } } - for (var index = 0; index < floor.Count; index++) + /// Whether the floor's rows lead the model-bound list, id for id. + private static bool Leads(IReadOnlyList floor, IReadOnlyList messages) { - if (!string.Equals(floor[index].Message.MessageId, messages[index].MessageId, StringComparison.Ordinal)) + if (floor.Count > messages.Count) { return false; } - } - return true; - } + for (int index = 0; index < floor.Count; index++) + { + if (!string.Equals(floor[index].Message.MessageId, messages[index].MessageId, StringComparison.Ordinal)) + { + return false; + } + } - /// - /// Reads the strategy's output as one new message over a prefix of the view, and names where the - /// kept tail starts. The output must be one new message, then the view from that index on, the - /// very instances in order; anything else is not a shape one summary row can stand for. - /// - /// The index of the first kept message, or . The view's count when nothing was kept. - private static int? Kept(List view, List output) - { - if (output.Count == 0 || output.Count > view.Count || view.Any(message => ReferenceEquals(message, output[0]))) - { - return null; + return true; } - var kept = view.Count - (output.Count - 1); - for (var index = 1; index < output.Count; index++) + /// + /// Reads the strategy's output as one new message over a prefix of the view, and names where the + /// kept tail starts. The output must be one new message, then the view from that index on, the + /// very instances in order; anything else is not a shape one summary row can stand for. + /// + /// The index of the first kept message, or . The view's count when nothing was kept. + private static int? Kept(List view, List output) { - if (!ReferenceEquals(output[index], view[kept + index - 1])) + if (output.Count == 0 || output.Count > view.Count || view.Any(message => ReferenceEquals(message, output[0]))) { return null; } - } - return kept; + int kept = view.Count - (output.Count - 1); + for (int index = 1; index < output.Count; index++) + { + if (!ReferenceEquals(output[index], view[kept + index - 1])) + { + return null; + } + } + + return kept; + } } -} #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs b/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs index 960334da..0a46d94b 100644 --- a/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs +++ b/src/AgentCore.Application/Runtime/Compaction/ToolResultCapProvider.cs @@ -2,119 +2,121 @@ using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Compaction; - -/// -/// The cheap half of compaction: once the words bound for the model pass the trigger, every tool -/// result older than the newest turns is cut to a fixed length. One message in, one message out, -/// same id, so the row numbers the summary stage reads survive. Nothing is stored; the cut is -/// re-made from the rows every turn, and it is the same cut every turn, so the prompt prefix the -/// model's cache keys on does not move. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -internal sealed class ToolResultCapProvider : AIContextProvider +namespace AgentCore.Application.Runtime.Compaction { - private const char Cut = '…'; - - private readonly CompactionTrigger _trigger; - - private readonly int _keepTurns; - - private readonly int _maxResultChars; - - /// When the cap applies, judged over everything bound for the model. - /// Turns. The newest turns whose results stay whole. A turn starts at a user message. - /// Characters. What a capped result keeps. - public ToolResultCapProvider(CompactionTrigger trigger, int keepTurns, int maxResultChars) + /// + /// The cheap half of compaction: once the words bound for the model pass the trigger, every tool + /// result older than the newest turns is cut to a fixed length. One message in, one message out, + /// same id, so the row numbers the summary stage reads survive. Nothing is stored; the cut is + /// re-made from the rows every turn, and it is the same cut every turn, so the prompt prefix the + /// model's cache keys on does not move. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + internal sealed class ToolResultCapProvider : AIContextProvider { - ArgumentNullException.ThrowIfNull(trigger); - ArgumentOutOfRangeException.ThrowIfNegative(keepTurns); - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxResultChars); + private const char Cut = '…'; - _trigger = trigger; - _keepTurns = keepTurns; - _maxResultChars = maxResultChars; - } + private readonly CompactionTrigger _trigger; - /// - protected override ValueTask InvokingCoreAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); + private readonly int _keepTurns; - var input = context.AIContext; - if (input.Messages is null) - { - return new(input); - } + private readonly int _maxResultChars; - var messages = input.Messages as IReadOnlyList ?? input.Messages.ToList(); - if (!_trigger(Measure(messages))) + /// When the cap applies, judged over everything bound for the model. + /// Turns. The newest turns whose results stay whole. A turn starts at a user message. + /// Characters. What a capped result keeps. + public ToolResultCapProvider(CompactionTrigger trigger, int keepTurns, int maxResultChars) { - return new(input); + ArgumentNullException.ThrowIfNull(trigger); + ArgumentOutOfRangeException.ThrowIfNegative(keepTurns); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxResultChars); + + _trigger = trigger; + _keepTurns = keepTurns; + _maxResultChars = maxResultChars; } - var capped = new List(messages.Count); - var kept = KeptFrom(messages); - for (var index = 0; index < messages.Count; index++) + /// + protected override ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) { - capped.Add(index < kept ? Cap(messages[index]) : messages[index]); + ArgumentNullException.ThrowIfNull(context); + + AIContext input = context.AIContext; + if (input.Messages is null) + { + return new(input); + } + + IReadOnlyList messages = input.Messages as IReadOnlyList ?? [.. input.Messages]; + if (!_trigger(Measure(messages))) + { + return new(input); + } + + List capped = new(messages.Count); + int kept = KeptFrom(messages); + for (int index = 0; index < messages.Count; index++) + { + capped.Add(index < kept ? Cap(messages[index]) : messages[index]); + } + + return new(new AIContext + { + Instructions = input.Instructions, + Messages = capped, + Tools = input.Tools, + }); } - return new(new AIContext + /// + /// One group holding every message is enough for the token triggers, and it makes this stage + /// and the summary stage count the same way. + /// + private static CompactionMessageIndex Measure(IReadOnlyList messages) { - Instructions = input.Instructions, - Messages = capped, - Tools = input.Tools, - }); - } - - /// - /// One group holding every message is enough for the token triggers, and it makes this stage - /// and the summary stage count the same way. - /// - private static CompactionMessageIndex Measure(IReadOnlyList messages) - { - CompactionMessageIndex index = new([]); - index.AddGroup(CompactionGroupKind.User, messages); - return index; - } + CompactionMessageIndex index = new([]); + _ = index.AddGroup(CompactionGroupKind.User, messages); + return index; + } - /// The index of the first message of the newest kept turn, or the count when none is kept. - private int KeptFrom(IReadOnlyList messages) - { - var turns = 0; - for (var index = messages.Count - 1; index >= 0; index--) + /// The index of the first message of the newest kept turn, or the count when none is kept. + private int KeptFrom(IReadOnlyList messages) { - if (messages[index].Role == ChatRole.User && ++turns == _keepTurns) + int turns = 0; + for (int index = messages.Count - 1; index >= 0; index--) { - return index; + if (messages[index].Role == ChatRole.User && ++turns == _keepTurns) + { + return index; + } } + + return _keepTurns == 0 ? messages.Count : 0; } - return _keepTurns == 0 ? messages.Count : 0; - } + private ChatMessage Cap(ChatMessage message) + { + return message.Role != ChatRole.Tool || !message.Contents.OfType().Any(Long) + ? message + : new ChatMessage(message.Role, [.. message.Contents.Select(content => content is FunctionResultContent result && Long(result) ? Cap(result) : content)]) + { + AuthorName = message.AuthorName, + MessageId = message.MessageId, + CreatedAt = message.CreatedAt, + AdditionalProperties = message.AdditionalProperties, + }; + } - private ChatMessage Cap(ChatMessage message) - { - if (message.Role != ChatRole.Tool || !message.Contents.OfType().Any(Long)) + private FunctionResultContent Cap(FunctionResultContent result) { - return message; + return new(result.CallId, result.Result!.ToString()![.._maxResultChars] + Cut); } - return new ChatMessage(message.Role, message.Contents.Select(content => content is FunctionResultContent result && Long(result) ? Cap(result) : content).ToList()) + private bool Long(FunctionResultContent result) { - AuthorName = message.AuthorName, - MessageId = message.MessageId, - CreatedAt = message.CreatedAt, - AdditionalProperties = message.AdditionalProperties, - }; + return result.Result?.ToString() is { } text && text.Length > _maxResultChars; + } } - - private FunctionResultContent Cap(FunctionResultContent result) - => new(result.CallId, result.Result!.ToString()![.._maxResultChars] + Cut); - - private bool Long(FunctionResultContent result) - => result.Result?.ToString() is { } text && text.Length > _maxResultChars; -} #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Runtime/ConversationEvent.cs b/src/AgentCore.Application/Runtime/ConversationEvent.cs index f98f79a4..13184037 100644 --- a/src/AgentCore.Application/Runtime/ConversationEvent.cs +++ b/src/AgentCore.Application/Runtime/ConversationEvent.cs @@ -1,39 +1,40 @@ using System.Collections.ObjectModel; -namespace AgentCore.Application.Runtime; - -/// -/// One fact about a conversation, as the turn loop saw it. Nothing edits it afterwards. -/// -public sealed record ConversationEvent +namespace AgentCore.Application.Runtime { - /// Gets the id of the conversation the fact belongs to. - public required string ConversationId { get; init; } - - /// Gets what happened. - public required ConversationEventKind Kind { get; init; } - - /// Gets the moment it happened, read from the clock of the session. - public required DateTimeOffset OccurredAt { get; init; } - /// - /// Gets the identity of this fact, or for a diagnostic-only event, which - /// no audit row records. + /// One fact about a conversation, as the turn loop saw it. Nothing edits it afterwards. /// - public Guid? EventId { get; init; } - - /// - /// Gets the zero-based index of the turn the fact belongs to, or for a - /// fact about the conversation itself. - /// - public int? TurnIndex { get; init; } - - /// - /// Gets the of the earlier fact this one corrects, or - /// when it corrects nothing. - /// - public Guid? AmendsEventId { get; init; } - - /// Gets the detail of the fact, keyed by name. It is empty when the kind needs none. - public IReadOnlyDictionary Payload { get; init; } = ReadOnlyDictionary.Empty; + public sealed record ConversationEvent + { + /// Gets the id of the conversation the fact belongs to. + public required string ConversationId { get; init; } + + /// Gets what happened. + public required ConversationEventKind Kind { get; init; } + + /// Gets the moment it happened, read from the clock of the session. + public required DateTimeOffset OccurredAt { get; init; } + + /// + /// Gets the identity of this fact, or for a diagnostic-only event, which + /// no audit row records. + /// + public Guid? EventId { get; init; } + + /// + /// Gets the zero-based index of the turn the fact belongs to, or for a + /// fact about the conversation itself. + /// + public int? TurnIndex { get; init; } + + /// + /// Gets the of the earlier fact this one corrects, or + /// when it corrects nothing. + /// + public Guid? AmendsEventId { get; init; } + + /// Gets the detail of the fact, keyed by name. It is empty when the kind needs none. + public IReadOnlyDictionary Payload { get; init; } = ReadOnlyDictionary.Empty; + } } diff --git a/src/AgentCore.Application/Runtime/ConversationEventChain.cs b/src/AgentCore.Application/Runtime/ConversationEventChain.cs index 49d22574..8ae80277 100644 --- a/src/AgentCore.Application/Runtime/ConversationEventChain.cs +++ b/src/AgentCore.Application/Runtime/ConversationEventChain.cs @@ -2,255 +2,268 @@ using AgentCore.Domain; using AgentCore.Domain.Audit; -namespace AgentCore.Application.Runtime; - -/// -/// The event chain of one conversation. It gives every fact its identity, hands it to the observers, and -/// closes the chain once. -/// -internal sealed class ConversationEventChain +namespace AgentCore.Application.Runtime { - private readonly string _conversationId; - - private readonly ConversationObserverDispatcher _observers; + /// + /// The event chain of one conversation. It gives every fact its identity, hands it to the observers, and + /// closes the chain once. + /// + internal sealed class ConversationEventChain + { + private readonly string _conversationId; - private readonly TimeProvider _time; + private readonly ConversationObserverDispatcher _observers; - private int _ended; + private readonly TimeProvider _time; - internal ConversationEventChain(string conversationId, ConversationObserverDispatcher observers, TimeProvider time) - { - _conversationId = conversationId; - _observers = observers; - _time = time; - } + private int _ended; - /// Gets whether the chain already closed. Nothing may be appended behind conversation.ended. - internal bool HasEnded => Volatile.Read(ref _ended) == 1; - - /// Raises one durable fact of this conversation, and gives it its identity. - internal Guid Raise( - ConversationEventKind kind, - DateTimeOffset occurredAt, - int? turnIndex, - Guid? amends = null, - IReadOnlyDictionary? payload = null) - { - var eventId = Guid.CreateVersion7(); + internal ConversationEventChain(string conversationId, ConversationObserverDispatcher observers, TimeProvider time) + { + _conversationId = conversationId; + _observers = observers; + _time = time; + } - Dispatch(kind, occurredAt, turnIndex, eventId, amends, payload); + /// Gets whether the chain already closed. Nothing may be appended behind conversation.ended. + internal bool HasEnded => Volatile.Read(ref _ended) == 1; - return eventId; - } + /// Raises one durable fact of this conversation, and gives it its identity. + internal Guid Raise( + ConversationEventKind kind, + DateTimeOffset occurredAt, + int? turnIndex, + Guid? amends = null, + IReadOnlyDictionary? payload = null) + { + Guid eventId = Guid.CreateVersion7(); - /// Raises one fact that is counted and logged and stored nowhere. - /// What happened. The chain of D23 holds no row for it. - /// When it happened. - /// The turn it belongs to. - /// The detail the fact carries. - internal void RaiseDiagnostic( - ConversationEventKind kind, - DateTimeOffset occurredAt, - int? turnIndex, - IReadOnlyDictionary? payload = null) - => Dispatch(kind, occurredAt, turnIndex, eventId: null, amends: null, payload); + Dispatch(kind, occurredAt, turnIndex, eventId, amends, payload); - /// Closes the chain of this conversation, once. - /// Why the conversation ended. - /// The moment it ended. - /// The stage the machine stopped in, or . - /// when this conversation wrote the event, and when it already had. - internal bool EndConversation(ConversationEndReason reason, DateTimeOffset endedAt, string? terminalStage = null) - { - // The token is read first, so a value outside the closed set writes no event at all. - var token = ConversationEndReasons.ToToken(reason); + return eventId; + } - if (Interlocked.Exchange(ref _ended, 1) == 1) + /// Raises one fact that is counted and logged and stored nowhere. + /// What happened. The chain of D23 holds no row for it. + /// When it happened. + /// The turn it belongs to. + /// The detail the fact carries. + internal void RaiseDiagnostic( + ConversationEventKind kind, + DateTimeOffset occurredAt, + int? turnIndex, + IReadOnlyDictionary? payload = null) { - return false; + Dispatch(kind, occurredAt, turnIndex, eventId: null, amends: null, payload); } - Dictionary payload = new(StringComparer.Ordinal) + /// Closes the chain of this conversation, once. + /// Why the conversation ended. + /// The moment it ended. + /// The stage the machine stopped in, or . + /// when this conversation wrote the event, and when it already had. + internal bool EndConversation(ConversationEndReason reason, DateTimeOffset endedAt, string? terminalStage = null) { - [AuditPayloadKeys.EndReason] = token, - }; + // The token is read first, so a value outside the closed set writes no event at all. + string token = ConversationEndReasons.ToToken(reason); - if (terminalStage is { Length: > 0 }) - { - payload[AuditPayloadKeys.StageAfter] = terminalStage; - } + if (Interlocked.Exchange(ref _ended, 1) == 1) + { + return false; + } + + Dictionary payload = new(StringComparer.Ordinal) + { + [AuditPayloadKeys.EndReason] = token, + }; - _ = Raise(ConversationEventKind.ConversationEnded, endedAt, turnIndex: null, payload: payload); + if (terminalStage is { Length: > 0 }) + { + payload[AuditPayloadKeys.StageAfter] = terminalStage; + } - return true; - } + _ = Raise(ConversationEventKind.ConversationEnded, endedAt, turnIndex: null, payload: payload); - /// Raises the durable facts of one finished turn, in the order they happened. - /// The turn that just spoke: its index, stages, the text the caller heard, when it ended, and how far it played. - /// The whole reply the model produced. - /// The message of the fault, or . - /// - /// The identity of the turn.completed fact, so a barge-in that arrives after this turn - /// already ended can name it through . - /// - internal Guid WriteTurnEvents(TurnResult result, string spokenReply, string? toolFault) - { - var (turnIndex, endedAt) = (result.TurnIndex, result.EndedAt); + return true; + } - if (toolFault is not null) + /// Raises the durable facts of one finished turn, in the order they happened. + /// The turn that just spoke: its index, stages, the text the caller heard, when it ended, and how far it played. + /// The whole reply the model produced. + /// The message of the fault, or . + /// + /// The identity of the turn.completed fact, so a barge-in that arrives after this turn + /// already ended can name it through . + /// + internal Guid WriteTurnEvents(TurnResult result, string spokenReply, string? toolFault) { - _ = Raise( - ConversationEventKind.ToolFailed, + (int turnIndex, DateTimeOffset endedAt) = (result.TurnIndex, result.EndedAt); + + if (toolFault is not null) + { + _ = Raise( + ConversationEventKind.ToolFailed, + endedAt, + turnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ToolError] = toolFault, + }); + } + + Guid completed = Raise( + ConversationEventKind.TurnCompleted, endedAt, turnIndex, payload: new Dictionary(StringComparer.Ordinal) { - [AuditPayloadKeys.ToolError] = toolFault, + [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(spokenReply).Value, + [AuditPayloadKeys.StageBefore] = result.StageBefore, + [AuditPayloadKeys.StageAfter] = result.StageAfter, }); - } - var completed = Raise( - ConversationEventKind.TurnCompleted, - endedAt, - turnIndex, - payload: new Dictionary(StringComparer.Ordinal) + if (result.InterruptedAfter is { } played) { - [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(spokenReply).Value, - [AuditPayloadKeys.StageBefore] = result.StageBefore, - [AuditPayloadKeys.StageAfter] = result.StageAfter, - }); + RaiseReplyInterrupted(turnIndex, endedAt, completed, result.ReplyText, played); + } - if (result.InterruptedAfter is { } played) - { - RaiseReplyInterrupted(turnIndex, endedAt, completed, result.ReplyText, played); + return completed; } - return completed; - } + /// Raises the amendment pair's second half: the barge-in that corrects one turn. + /// The turn whose reply was cut. + /// When the cut was recorded. + /// The identity of the turn.completed fact it corrects. + /// The text the caller actually heard. + /// How much of the reply played, as the relay reported it. + internal void RaiseReplyInterrupted( + int turnIndex, + DateTimeOffset occurredAt, + Guid amendsEventId, + string heard, + TimeSpan played) + { + _ = Raise( + ConversationEventKind.ReplyInterrupted, + occurredAt, + turnIndex, + amends: amendsEventId, + payload: new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText(heard).Value, + [AuditPayloadKeys.DurationUntilInterruptMs] = + ((long)played.TotalMilliseconds).ToString(CultureInfo.InvariantCulture), + }); + } - /// Raises the amendment pair's second half: the barge-in that corrects one turn. - /// The turn whose reply was cut. - /// When the cut was recorded. - /// The identity of the turn.completed fact it corrects. - /// The text the caller actually heard. - /// How much of the reply played, as the relay reported it. - internal void RaiseReplyInterrupted( - int turnIndex, - DateTimeOffset occurredAt, - Guid amendsEventId, - string heard, - TimeSpan played) - => _ = Raise( - ConversationEventKind.ReplyInterrupted, - occurredAt, - turnIndex, - amends: amendsEventId, - payload: new Dictionary(StringComparer.Ordinal) + /// Raises the moderation facts of one turn, before the turn's own events. + /// The turn that just ran. + /// What the layers reported, or . + internal void RaiseModeration(int turnIndex, TurnDisposition? disposition) + { + switch (disposition?.Moderation) { - [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText(heard).Value, - [AuditPayloadKeys.DurationUntilInterruptMs] = - ((long)played.TotalMilliseconds).ToString(CultureInfo.InvariantCulture), - }); + case ModerationOutcome.Flagged: + _ = Raise( + ConversationEventKind.PromptFlagged, + _time.GetUtcNow(), + turnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ModerationCategories] = disposition.FlaggedCategories ?? string.Empty, + }); + break; - /// Raises the moderation facts of one turn, before the turn's own events. - /// The turn that just ran. - /// What the layers reported, or . - internal void RaiseModeration(int turnIndex, TurnDisposition? disposition) - { - switch (disposition?.Moderation) - { - case ModerationOutcome.Flagged: - _ = Raise( - ConversationEventKind.PromptFlagged, - _time.GetUtcNow(), - turnIndex, - payload: new Dictionary(StringComparer.Ordinal) - { - [AuditPayloadKeys.ModerationCategories] = disposition.FlaggedCategories ?? string.Empty, - }); - break; + case ModerationOutcome.Unavailable: + RaiseDiagnostic( + ConversationEventKind.ModerationUnavailable, + _time.GetUtcNow(), + turnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [ConversationEventPayloadKeys.Reason] = + disposition.ModerationReason ?? ConversationSession.ModerationFaultedReason, + }); + break; - case ModerationOutcome.Unavailable: - RaiseDiagnostic( - ConversationEventKind.ModerationUnavailable, - _time.GetUtcNow(), - turnIndex, - payload: new Dictionary(StringComparer.Ordinal) - { - [ConversationEventPayloadKeys.Reason] = - disposition.ModerationReason ?? ConversationSession.ModerationFaultedReason, - }); - break; + case ModerationOutcome.Clean: + RaiseDiagnostic(ConversationEventKind.ModerationClean, _time.GetUtcNow(), turnIndex); + break; - case ModerationOutcome.Clean: - RaiseDiagnostic(ConversationEventKind.ModerationClean, _time.GetUtcNow(), turnIndex); - break; + default: + break; + } + } - default: - break; + /// Raises the fact of one tool call that did not run to completion. + /// The turn the conversation belongs to. + /// What the function-invocation loop saw. + internal void RaiseToolFailure(int turnIndex, ToolFailure failure) + { + _ = Raise( + ConversationEventKind.ToolFailed, + _time.GetUtcNow(), + turnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ToolName] = failure.ToolName, + [AuditPayloadKeys.ToolCallId] = failure.ToolCallId, + [AuditPayloadKeys.ToolFailureKind] = ToolFailureKinds.ToToken(failure.Kind), + [AuditPayloadKeys.ToolError] = failure.Message, + }); } - } - /// Raises the fact of one tool call that did not run to completion. - /// The turn the conversation belongs to. - /// What the function-invocation loop saw. - internal void RaiseToolFailure(int turnIndex, ToolFailure failure) - => _ = Raise( - ConversationEventKind.ToolFailed, - _time.GetUtcNow(), - turnIndex, - payload: new Dictionary(StringComparer.Ordinal) - { - [AuditPayloadKeys.ToolName] = failure.ToolName, - [AuditPayloadKeys.ToolCallId] = failure.ToolCallId, - [AuditPayloadKeys.ToolFailureKind] = ToolFailureKinds.ToToken(failure.Kind), - [AuditPayloadKeys.ToolError] = failure.Message, - }); + /// Raises the fact of one store 1 write the backing store refused. + internal void RaiseDroppedTranscriptWrite(int turnIndex, Exception exception) + { + RaiseDiagnostic( + ConversationEventKind.TranscriptWriteFailed, + _time.GetUtcNow(), + turnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [ConversationEventPayloadKeys.Reason] = $"{exception.GetType().Name}: {exception.Message}", + }); + } - /// Raises the fact of one store 1 write the backing store refused. - internal void RaiseDroppedTranscriptWrite(int turnIndex, Exception exception) - => RaiseDiagnostic( - ConversationEventKind.TranscriptWriteFailed, - _time.GetUtcNow(), - turnIndex, - payload: new Dictionary(StringComparer.Ordinal) - { - [ConversationEventPayloadKeys.Reason] = $"{exception.GetType().Name}: {exception.Message}", - }); + /// Raises the fact of one store 1 read that failed as a turn opened. + internal void RaiseFailedTranscriptResync(int turnIndex, Exception exception) + { + RaiseDiagnostic( + ConversationEventKind.TranscriptResyncFailed, + _time.GetUtcNow(), + turnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [ConversationEventPayloadKeys.Reason] = $"{exception.GetType().Name}: {exception.Message}", + }); + } - /// Raises the fact of one store 1 read that failed as a turn opened. - internal void RaiseFailedTranscriptResync(int turnIndex, Exception exception) - => RaiseDiagnostic( - ConversationEventKind.TranscriptResyncFailed, - _time.GetUtcNow(), - turnIndex, - payload: new Dictionary(StringComparer.Ordinal) + /// Hands one fact to everything watching the conversation, and never waits for it. + /// What happened. + /// When it happened. + /// The turn it belongs to, or . + /// The identity it took, or when it took none. + /// The identity it corrects, or . + /// The detail it carries. + private void Dispatch( + ConversationEventKind kind, + DateTimeOffset occurredAt, + int? turnIndex, + Guid? eventId, + Guid? amends, + IReadOnlyDictionary? payload) + { + _observers.Dispatch(new ConversationEvent { - [ConversationEventPayloadKeys.Reason] = $"{exception.GetType().Name}: {exception.Message}", + ConversationId = _conversationId, + Kind = kind, + OccurredAt = occurredAt, + EventId = eventId, + TurnIndex = turnIndex, + AmendsEventId = amends, + Payload = payload ?? new Dictionary(StringComparer.Ordinal), }); - - /// Hands one fact to everything watching the conversation, and never waits for it. - /// What happened. - /// When it happened. - /// The turn it belongs to, or . - /// The identity it took, or when it took none. - /// The identity it corrects, or . - /// The detail it carries. - private void Dispatch( - ConversationEventKind kind, - DateTimeOffset occurredAt, - int? turnIndex, - Guid? eventId, - Guid? amends, - IReadOnlyDictionary? payload) - => _observers.Dispatch(new ConversationEvent - { - ConversationId = _conversationId, - Kind = kind, - OccurredAt = occurredAt, - EventId = eventId, - TurnIndex = turnIndex, - AmendsEventId = amends, - Payload = payload ?? new Dictionary(StringComparer.Ordinal), - }); + } + } } diff --git a/src/AgentCore.Application/Runtime/ConversationEventKind.cs b/src/AgentCore.Application/Runtime/ConversationEventKind.cs index c4cbc87d..98a997a3 100644 --- a/src/AgentCore.Application/Runtime/ConversationEventKind.cs +++ b/src/AgentCore.Application/Runtime/ConversationEventKind.cs @@ -1,52 +1,53 @@ -namespace AgentCore.Application.Runtime; - -/// -/// The closed set of facts one conversation raises to its observers. -/// -public enum ConversationEventKind +namespace AgentCore.Application.Runtime { - /// A session of the conversation started. It is the first fact of every session. - ConversationStarted = 0, + /// + /// The closed set of facts one conversation raises to its observers. + /// + public enum ConversationEventKind + { + /// A session of the conversation started. It is the first fact of every session. + ConversationStarted = 0, - /// Moderation flagged what the CALLER said, so the agent refused to answer that turn. - PromptFlagged = 1, + /// Moderation flagged what the CALLER said, so the agent refused to answer that turn. + PromptFlagged = 1, - /// The moderation endpoint did not answer in time, or it faulted, so the turn ran unchecked. - ModerationUnavailable = 2, + /// The moderation endpoint did not answer in time, or it faulted, so the turn ran unchecked. + ModerationUnavailable = 2, - /// The moderation endpoint answered, and it flagged nothing. - ModerationClean = 3, + /// The moderation endpoint answered, and it flagged nothing. + ModerationClean = 3, - /// A tool failed its whole retry budget, and the turn spoke the fallback instead. - ToolFailed = 4, + /// A tool failed its whole retry budget, and the turn spoke the fallback instead. + ToolFailed = 4, - /// The run returned quietly with no text, so the turn spoke the fallback. - EmptyReply = 5, + /// The run returned quietly with no text, so the turn spoke the fallback. + EmptyReply = 5, - /// The extractor returned an invalid object, so the slots stayed unchanged. - ExtractionFailed = 6, + /// The extractor returned an invalid object, so the slots stayed unchanged. + ExtractionFailed = 6, - /// One turn ran to the end, and the caller heard the whole reply. - TurnCompleted = 7, + /// One turn ran to the end, and the caller heard the whole reply. + TurnCompleted = 7, - /// The caller spoke over a reply, so the reply stopped early. - ReplyInterrupted = 8, + /// The caller spoke over a reply, so the reply stopped early. + ReplyInterrupted = 8, - /// A caller sent an earlier message again, so the turns after it were withdrawn. - TurnSuperseded = 12, + /// A caller sent an earlier message again, so the turns after it were withdrawn. + TurnSuperseded = 12, - /// A store 1 write was refused, so the durable copy of some words was lost. - TranscriptWriteFailed = 10, + /// A store 1 write was refused, so the durable copy of some words was lost. + TranscriptWriteFailed = 10, - /// The host ended the conversation. It is the last fact of the session that ended it. - ConversationEnded = 9, + /// The host ended the conversation. It is the last fact of the session that ended it. + ConversationEnded = 9, - /// A resumed conversation could not restore part of its stored state: the document changed under it. - StateRestorePartial = 11, + /// A resumed conversation could not restore part of its stored state: the document changed under it. + StateRestorePartial = 11, - /// - /// Store 1 could not be read as a turn opened, so the turn ran on the words the session already - /// held. A message appended outside a turn since the last read is not among them. - /// - TranscriptResyncFailed = 13, + /// + /// Store 1 could not be read as a turn opened, so the turn ran on the words the session already + /// held. A message appended outside a turn since the last read is not among them. + /// + TranscriptResyncFailed = 13, + } } diff --git a/src/AgentCore.Application/Runtime/ConversationEventKinds.cs b/src/AgentCore.Application/Runtime/ConversationEventKinds.cs index bed7adb6..b971c28d 100644 --- a/src/AgentCore.Application/Runtime/ConversationEventKinds.cs +++ b/src/AgentCore.Application/Runtime/ConversationEventKinds.cs @@ -1,53 +1,60 @@ +using System.Collections.Frozen; using AgentCore.Domain.Audit; -namespace AgentCore.Application.Runtime; - -/// -/// What one is to the audit vocabulary, in one place. -/// -internal static class ConversationEventKinds +namespace AgentCore.Application.Runtime { /// - /// Reads the audit kind one conversation event maps to, when the chain stores it at all. + /// What one is to the audit vocabulary, in one place. /// - public static bool TryGetAuditKind(ConversationEventKind kind, out AuditEventKind auditKind) + internal static class ConversationEventKinds { - switch (kind) - { - case ConversationEventKind.ConversationStarted: auditKind = AuditEventKind.ConversationStarted; return true; - case ConversationEventKind.PromptFlagged: auditKind = AuditEventKind.PromptFlagged; return true; - case ConversationEventKind.ToolFailed: auditKind = AuditEventKind.ToolFailed; return true; - case ConversationEventKind.TurnCompleted: auditKind = AuditEventKind.TurnCompleted; return true; - case ConversationEventKind.ReplyInterrupted: auditKind = AuditEventKind.ReplyInterrupted; return true; - case ConversationEventKind.ConversationEnded: auditKind = AuditEventKind.ConversationEnded; return true; - case ConversationEventKind.TurnSuperseded: auditKind = AuditEventKind.TurnSuperseded; return true; - default: auditKind = default; return false; - } - } + /// The seven kinds the chain stores, and the audit kind each one is stored as. + private static readonly FrozenDictionary AuditKinds = + new Dictionary + { + [ConversationEventKind.ConversationStarted] = AuditEventKind.ConversationStarted, + [ConversationEventKind.PromptFlagged] = AuditEventKind.PromptFlagged, + [ConversationEventKind.ToolFailed] = AuditEventKind.ToolFailed, + [ConversationEventKind.TurnCompleted] = AuditEventKind.TurnCompleted, + [ConversationEventKind.ReplyInterrupted] = AuditEventKind.ReplyInterrupted, + [ConversationEventKind.ConversationEnded] = AuditEventKind.ConversationEnded, + [ConversationEventKind.TurnSuperseded] = AuditEventKind.TurnSuperseded, + }.ToFrozenDictionary(); - /// - /// Names one kind for a log line. - /// - public static string ToToken(ConversationEventKind kind) - { - if (TryGetAuditKind(kind, out AuditEventKind auditKind)) + /// + /// Reads the audit kind one conversation event maps to, when the chain stores it at all. + /// + public static bool TryGetAuditKind(ConversationEventKind kind, out AuditEventKind auditKind) { - return AuditEventKinds.ToToken(auditKind); + return AuditKinds.TryGetValue(kind, out auditKind); } - return kind switch + /// + /// Names one kind for a log line. + /// + public static string ToToken(ConversationEventKind kind) { - ConversationEventKind.ModerationUnavailable => "moderation.unavailable", - ConversationEventKind.ModerationClean => "moderation.clean", - ConversationEventKind.EmptyReply => "reply.empty", - ConversationEventKind.ExtractionFailed => "extraction.failed", - ConversationEventKind.TranscriptWriteFailed => "transcript.write.failed", - ConversationEventKind.StateRestorePartial => "state.restore.partial", - ConversationEventKind.TranscriptResyncFailed => "transcript.resync.failed", + return kind switch + { + ConversationEventKind.ConversationStarted => AuditEventKinds.ToToken(AuditEventKind.ConversationStarted), + ConversationEventKind.PromptFlagged => AuditEventKinds.ToToken(AuditEventKind.PromptFlagged), + ConversationEventKind.ToolFailed => AuditEventKinds.ToToken(AuditEventKind.ToolFailed), + ConversationEventKind.TurnCompleted => AuditEventKinds.ToToken(AuditEventKind.TurnCompleted), + ConversationEventKind.ReplyInterrupted => AuditEventKinds.ToToken(AuditEventKind.ReplyInterrupted), + ConversationEventKind.ConversationEnded => AuditEventKinds.ToToken(AuditEventKind.ConversationEnded), + ConversationEventKind.TurnSuperseded => AuditEventKinds.ToToken(AuditEventKind.TurnSuperseded), + ConversationEventKind.ModerationUnavailable => "moderation.unavailable", + ConversationEventKind.ModerationClean => "moderation.clean", + ConversationEventKind.EmptyReply => "reply.empty", + ConversationEventKind.ExtractionFailed => "extraction.failed", + ConversationEventKind.TranscriptWriteFailed => "transcript.write.failed", + ConversationEventKind.StateRestorePartial => "state.restore.partial", + ConversationEventKind.TranscriptResyncFailed => "transcript.resync.failed", - // A kind outside the closed set must not cost the report the fault it is carrying, so this - // names the value instead of throwing over it. - _ => kind.ToString(), - }; + // A kind outside the closed set must not cost the report the fault it is carrying, so this + // names the value instead of throwing over it. + _ => kind.ToString(), + }; + } } } diff --git a/src/AgentCore.Application/Runtime/ConversationEventPayloadKeys.cs b/src/AgentCore.Application/Runtime/ConversationEventPayloadKeys.cs index 6544c451..31529845 100644 --- a/src/AgentCore.Application/Runtime/ConversationEventPayloadKeys.cs +++ b/src/AgentCore.Application/Runtime/ConversationEventPayloadKeys.cs @@ -1,14 +1,13 @@ -using AgentCore.Domain.Audit; - -namespace AgentCore.Application.Runtime; - -/// -/// The payload keys a diagnostic-only carries. -/// -internal static class ConversationEventPayloadKeys +namespace AgentCore.Application.Runtime { /// - /// Why a diagnostic-only event happened, in the words the turn loop used. + /// The payload keys a diagnostic-only carries. /// - public const string Reason = "reason"; + internal static class ConversationEventPayloadKeys + { + /// + /// Why a diagnostic-only event happened, in the words the turn loop used. + /// + public const string Reason = "reason"; + } } diff --git a/src/AgentCore.Application/Runtime/ConversationInterruptionTracker.cs b/src/AgentCore.Application/Runtime/ConversationInterruptionTracker.cs new file mode 100644 index 00000000..8850de72 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationInterruptionTracker.cs @@ -0,0 +1,179 @@ +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationInterruptionTracker + { + private readonly ConversationSession _session; + + // One session runs one turn at a time. Lives here, with the rest of the live run, so the + // guard and the release travel together; BeginTurn enters through TryEnterTurn. + private int _running; + + // Whether the running turn has already handed the host something to speak. One rule for both + // run shapes: a run that has handed the host nothing cannot be the turn the caller was hearing. + private volatile bool _runIsAudible; + + /// + /// Whether the running turn has handed the host something to speak. + /// + internal bool RunIsAudible { get => _runIsAudible; set => _runIsAudible = value; } + + internal ConversationInterruptionTracker(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// + /// Ends the running turn where the caller cut the reply off. + /// + /// The text the caller actually heard. + /// How much of the reply played, as the relay reported it. + /// + /// Whether the turn running now is the turn the caller was hearing. An adapter that tracks which + /// turn's output actually reached the vendor answers that question itself and says so here; + /// sends the frame straight to the amendment path, whatever the running + /// turn has produced. The default is , which leaves the decision to this + /// session alone, and that is the right answer for a caller that speaks over a reply it is + /// itself streaming. + /// + /// + /// when this conversation recorded the barge-in, either by ending the running + /// turn or by amending the turn that finished last, and when there was + /// nothing to record it against. + /// + /// + /// is negative. + /// + internal bool Interrupt( + string utteranceUntilInterrupt, + TimeSpan durationUntilInterrupt, + bool cutsRunningTurn = true) + { + ArgumentNullException.ThrowIfNull(utteranceUntilInterrupt); + ArgumentOutOfRangeException.ThrowIfLessThan(durationUntilInterrupt, TimeSpan.Zero); + + lock (_session.InterruptLock) + { + // Both conditions, and in this order. The adapter's answer only ever removes the + // in-flight path: an adapter that knows the caller was hearing an earlier turn skips it + // outright, and one that says nothing leaves this session's own audibility test to + // decide. + if (cutsRunningTurn && _session.RunCancellation is { } cancellation && RunIsAudible) + { + _session.Interruption = new Interruption(utteranceUntilInterrupt, durationUntilInterrupt); + cancellation.Cancel(); + return true; + } + + return AmendLastTurn(new Interruption(utteranceUntilInterrupt, durationUntilInterrupt)); + } + } + + /// + /// Opens the window in which reaches this turn. + /// + /// The token of the host. + /// The source the run reads. The caller ends it with . + internal CancellationTokenSource StartRun(CancellationToken cancellationToken) + { + CancellationTokenSource cancellation = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + + lock (_session.InterruptLock) + { + _session.Interruption = null; + _session.RunCancellation = cancellation; + _runIsAudible = false; + } + + return cancellation; + } + + /// Takes the turn slot, unless a turn of this conversation is still running. + /// when another turn holds the slot. + internal bool TryEnterTurn() + { + return Interlocked.Exchange(ref _running, 1) == 0; + } + + /// Frees the turn slot after a turn refused to start left it taken. + internal void ReleaseTurn() + { + Volatile.Write(ref _running, 0); + } + + /// + /// Closes the window, and frees the session for the next turn. + /// + /// The source returned. + internal void EndRun(CancellationTokenSource cancellation) + { + // The field drops first. A frame that arrives now meets no source to cancel, so it reaches + // the amendment path rather than a disposed one. + lock (_session.InterruptLock) + { + _session.RunCancellation = null; + _runIsAudible = false; + } + + cancellation.Dispose(); + Volatile.Write(ref _running, 0); + } + + /// + /// Records a barge-in against the turn that finished last, and corrects its record. + /// + /// What the relay reported: the heard text and the played duration. + /// + /// when the turn was amended, and when there was + /// no turn to amend. + /// + internal bool AmendLastTurn(Interruption cut) + { + // The chain has already closed, so nothing may be appended behind conversation.ended. + if (_session.Events.HasEnded + || _session.AmendableEventId is not { } completedEventId + || _session.LastTurn is not { InterruptedAfter: null } finished + || _session.Ledger.Session() is not { } session) + { + return false; + } + + string heard = cut.HeardText.Trim(); + + // Store 1 keeps the reply row and rewrites its words, rather than replacing the turn's + // messages. The turn it corrects ran to its end, so every tool call it made is already + // paired and there is nothing unfinished to strip out. + // + // The cut always lands today: a turn is amendable only when it completed with words, and a + // turn that completed with words left a reply row holding them. The answer is still read, + // because the row below names a HASH of those words — a chain that proves words store 1 + // does not hold proves nothing, so no cut means no amendment. + if (!_session.History.TruncateLastReply(session, heard, cut.PlayedDuration)) + { + return false; + } + + _session.LastTurn = finished with { ReplyText = heard, InterruptedAfter = cut.PlayedDuration }; + + _session.Events.RaiseReplyInterrupted( + finished.TurnIndex, _session.Time.GetUtcNow(), completedEventId, heard, cut.PlayedDuration); + + return true; + } + + /// Reads the interruption the relay reported for the running turn. + /// The record, or when the caller did not interrupt. + internal Interruption? CurrentInterruption() + { + lock (_session.InterruptLock) + { + return _session.Interruption; + } + } + + /// What the relay reported when the caller spoke over the reply. + /// The text the caller actually heard. + /// How much of the reply played, at 1 ms. + internal sealed record Interruption(string HeardText, TimeSpan PlayedDuration); + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationObserverDispatcher.cs b/src/AgentCore.Application/Runtime/ConversationObserverDispatcher.cs index 83dd188a..fbbebe89 100644 --- a/src/AgentCore.Application/Runtime/ConversationObserverDispatcher.cs +++ b/src/AgentCore.Application/Runtime/ConversationObserverDispatcher.cs @@ -3,206 +3,207 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Runtime; - -/// -/// Hands each fact of a conversation to every observer, in order, and never waits for one. -/// -/// -/// -/// The "never sit on the turn" rule of lives here, once, for every -/// observer. Section 7 measures a durable insert at 13 ms at p50 and 32 ms at p99, against 91 -/// nanoseconds to enqueue, so an observer that completes synchronously costs the caller the enqueue -/// and nothing else, and an observer that does not is observed on a separate task. The reply leaves -/// while the row is still being written. -/// -/// -/// Nothing here propagates. An observer records the conversation and is never a part of it, so one that -/// throws is logged once and the turn goes on. That holds for a fault raised before the first await -/// and for a fault raised long after the turn ended, and it holds for each observer separately: a -/// refusing sink does not cost the counters or the log their reading of the same fact. -/// -/// -/// Order is a guarantee, and it is a guarantee per observer. A bare fire-and-forget task per -/// event lets two slow deliveries land out of order, and an audit chain whose events arrive shuffled -/// is not a record of the conversation. Every observer therefore has a tail of its own in -/// , and a dispatch chains onto that observer's tail under : -/// the facts of one dispatcher reach ONE observer in the order the conversation produced them, however long -/// any one of them takes. That is the whole of what the chain of D23 asks for. -/// -/// -/// It is deliberately not one guarantee across observers. A single shared tail would queue every -/// later counter and every later log line behind a sink still writing an earlier row, so the two -/// fast readings would pay the slow one's price on every event after it, for the rest of the conversation. -/// With a tail each, a slow observer delays only itself, and telemetry and logging keep their old -/// synchronous cost whatever the sink is doing. -/// -/// -/// The lock is held across the synchronous head of every delivery, which is what makes the fast path -/// and the queue one decision rather than a race between two threads. That window is the work an -/// observer does before its first await, and the port already forbids that work from blocking: a -/// counter, a log line, and an enqueue all fit inside it. It is also what fixes the order of those -/// heads, so every observer is still offered a fact in the order the observers were registered. -/// -/// -/// The fast path keeps the old cost exactly. An observer that owes nothing runs on the caller's -/// thread up to its first incomplete await, and a dispatch in which every observer completes -/// synchronously allocates no continuation and touches nothing after the lock. This is what the whole -/// turn loop does when the sink is a queue, which is the shape D23 asks for. -/// -/// -/// One dispatcher belongs to one conversation, because the ordering guarantee is per dispatcher and a shared -/// instance would make every conversation queue behind every other. The observers behind it are shared, and -/// they hold no per-call state. -/// -/// -internal sealed class ConversationObserverDispatcher +namespace AgentCore.Application.Runtime { - private readonly IConversationObserver[] _observers; - private readonly ILogger _logger; - private readonly Lock _gate = new(); - /// - /// The delivery each observer's later events queue behind, indexed alongside - /// . An entry is while that observer owes nothing, - /// which is the fast path. None of these tasks ever faults. + /// Hands each fact of a conversation to every observer, in order, and never waits for one. /// - private readonly Task?[] _tails; - - /// Creates the dispatcher of one conversation. - /// - /// Everything that watches the conversation. Each one takes every fact, in the order they are given here. - /// An empty set is legal, and it makes every dispatch a no-op. - /// - /// - /// The logger an observer's fault is reported to, or for - /// . The library never throws for want of one. - /// - public ConversationObserverDispatcher(IEnumerable observers, ILogger? logger = null) - { - ArgumentNullException.ThrowIfNull(observers); - - _observers = [.. observers]; - _tails = new Task?[_observers.Length]; - _logger = logger ?? NullLogger.Instance; - } - - /// Gets the number of observers watching the conversation. - public int Count => _observers.Length; - - /// Hands one fact to every observer, and never waits for them. - /// What happened. - /// is . /// - /// It returns as soon as the observers have accepted the fact, which for a well-behaved observer - /// is before it returns at all. Nothing an observer does can make this method throw or block. + /// + /// The "never sit on the turn" rule of lives here, once, for every + /// observer. Section 7 measures a durable insert at 13 ms at p50 and 32 ms at p99, against 91 + /// nanoseconds to enqueue, so an observer that completes synchronously costs the caller the enqueue + /// and nothing else, and an observer that does not is observed on a separate task. The reply leaves + /// while the row is still being written. + /// + /// + /// Nothing here propagates. An observer records the conversation and is never a part of it, so one that + /// throws is logged once and the turn goes on. That holds for a fault raised before the first await + /// and for a fault raised long after the turn ended, and it holds for each observer separately: a + /// refusing sink does not cost the counters or the log their reading of the same fact. + /// + /// + /// Order is a guarantee, and it is a guarantee per observer. A bare fire-and-forget task per + /// event lets two slow deliveries land out of order, and an audit chain whose events arrive shuffled + /// is not a record of the conversation. Every observer therefore has a tail of its own in + /// , and a dispatch chains onto that observer's tail under : + /// the facts of one dispatcher reach ONE observer in the order the conversation produced them, however long + /// any one of them takes. That is the whole of what the chain of D23 asks for. + /// + /// + /// It is deliberately not one guarantee across observers. A single shared tail would queue every + /// later counter and every later log line behind a sink still writing an earlier row, so the two + /// fast readings would pay the slow one's price on every event after it, for the rest of the conversation. + /// With a tail each, a slow observer delays only itself, and telemetry and logging keep their old + /// synchronous cost whatever the sink is doing. + /// + /// + /// The lock is held across the synchronous head of every delivery, which is what makes the fast path + /// and the queue one decision rather than a race between two threads. That window is the work an + /// observer does before its first await, and the port already forbids that work from blocking: a + /// counter, a log line, and an enqueue all fit inside it. It is also what fixes the order of those + /// heads, so every observer is still offered a fact in the order the observers were registered. + /// + /// + /// The fast path keeps the old cost exactly. An observer that owes nothing runs on the caller's + /// thread up to its first incomplete await, and a dispatch in which every observer completes + /// synchronously allocates no continuation and touches nothing after the lock. This is what the whole + /// turn loop does when the sink is a queue, which is the shape D23 asks for. + /// + /// + /// One dispatcher belongs to one conversation, because the ordering guarantee is per dispatcher and a shared + /// instance would make every conversation queue behind every other. The observers behind it are shared, and + /// they hold no per-call state. + /// /// - public void Dispatch(ConversationEvent conversationEvent) + internal sealed class ConversationObserverDispatcher { - ArgumentNullException.ThrowIfNull(conversationEvent); - - if (_observers.Length == 0) + private readonly IConversationObserver[] _observers; + private readonly ILogger _logger; + private readonly Lock _gate = new(); + + /// + /// The delivery each observer's later events queue behind, indexed alongside + /// . An entry is while that observer owes nothing, + /// which is the fast path. None of these tasks ever faults. + /// + private readonly Task?[] _tails; + + /// Creates the dispatcher of one conversation. + /// + /// Everything that watches the conversation. Each one takes every fact, in the order they are given here. + /// An empty set is legal, and it makes every dispatch a no-op. + /// + /// + /// The logger an observer's fault is reported to, or for + /// . The library never throws for want of one. + /// + public ConversationObserverDispatcher(IEnumerable observers, ILogger? logger = null) { - return; + ArgumentNullException.ThrowIfNull(observers); + + _observers = [.. observers]; + _tails = new Task?[_observers.Length]; + _logger = logger ?? NullLogger.Instance; } - lock (_gate) + /// Gets the number of observers watching the conversation. + public int Count => _observers.Length; + + /// Hands one fact to every observer, and never waits for them. + /// What happened. + /// is . + /// + /// It returns as soon as the observers have accepted the fact, which for a well-behaved observer + /// is before it returns at all. Nothing an observer does can make this method throw or block. + /// + public void Dispatch(ConversationEvent conversationEvent) { - // The observers are offered the fact one after another rather than all at once, so the - // order they were registered in is the order they read the conversation in. - for (int index = 0; index < _observers.Length; index++) + ArgumentNullException.ThrowIfNull(conversationEvent); + + if (_observers.Length == 0) { - Task? tail = _tails[index]; + return; + } - // This observer owes nothing, so the fact runs here and now, on the caller's thread, - // up to its first await if it has one. Order is kept for free: there is nothing left - // for it to follow. - if (tail is null || tail.IsCompleted) + lock (_gate) + { + // The observers are offered the fact one after another rather than all at once, so the + // order they were registered in is the order they read the conversation in. + for (int index = 0; index < _observers.Length; index++) { - Task delivery = DeliverAsync(_observers[index], conversationEvent); - _tails[index] = delivery.IsCompleted ? null : delivery; - continue; + Task? tail = _tails[index]; + + // This observer owes nothing, so the fact runs here and now, on the caller's thread, + // up to its first await if it has one. Order is kept for free: there is nothing left + // for it to follow. + if (tail is null || tail.IsCompleted) + { + Task delivery = DeliverAsync(_observers[index], conversationEvent); + _tails[index] = delivery.IsCompleted ? null : delivery; + continue; + } + + // An earlier fact is still open at THIS observer. This one waits behind it, so that + // observer never sees the turns of a conversation out of the order the conversation ran them — and + // every other observer still reads this fact now, whatever the slow one is doing. + _tails[index] = ContinueAsync(tail, _observers[index], conversationEvent); } - - // An earlier fact is still open at THIS observer. This one waits behind it, so that - // observer never sees the turns of a conversation out of the order the conversation ran them — and - // every other observer still reads this fact now, whatever the slow one is doing. - _tails[index] = ContinueAsync(tail, _observers[index], conversationEvent); } } - } - /// Waits for the earlier fact of one observer, then delivers this one to it. - /// The delivery of that observer already outstanding. - /// The observer both facts belong to. - /// The fact queued behind the earlier one. - /// A task that always completes, and never faults. - private async Task ContinueAsync(Task previous, IConversationObserver observer, ConversationEvent conversationEvent) - { - try + /// Waits for the earlier fact of one observer, then delivers this one to it. + /// The delivery of that observer already outstanding. + /// The observer both facts belong to. + /// The fact queued behind the earlier one. + /// A task that always completes, and never faults. + private async Task ContinueAsync(Task previous, IConversationObserver observer, ConversationEvent conversationEvent) { - await previous.ConfigureAwait(false); - } + try + { + await previous.ConfigureAwait(false); + } #pragma warning disable CA1031 // A delivery reports its own faults, and a broken one must not stop the next fact. - catch (Exception) + catch (Exception) #pragma warning restore CA1031 - { - // DeliverAsync swallows everything an observer raises and everything the report of that - // raises, so nothing is expected here. It is caught all the same, because the fact behind - // this one is owed to the observer whatever happened to the fact before it. - } + { + // DeliverAsync swallows everything an observer raises and everything the report of that + // raises, so nothing is expected here. It is caught all the same, because the fact behind + // this one is owed to the observer whatever happened to the fact before it. + } - await DeliverAsync(observer, conversationEvent).ConfigureAwait(false); - } + await DeliverAsync(observer, conversationEvent).ConfigureAwait(false); + } - /// Offers one fact to one observer. - /// The observer the fact is owed to. - /// What happened. - /// A task that always completes, and never faults. - /// - /// A slow observer delays only the later facts of its own tail, off the turn, where the cost is - /// nobody's. - /// - private async Task DeliverAsync(IConversationObserver observer, ConversationEvent conversationEvent) - { - try + /// Offers one fact to one observer. + /// The observer the fact is owed to. + /// What happened. + /// A task that always completes, and never faults. + /// + /// A slow observer delays only the later facts of its own tail, off the turn, where the cost is + /// nobody's. + /// + private async Task DeliverAsync(IConversationObserver observer, ConversationEvent conversationEvent) { - // CancellationToken.None: the record belongs to the conversation, not to the turn the caller may - // have cancelled. - ValueTask pending = observer.OnConversationEventAsync(conversationEvent, CancellationToken.None); - if (pending.IsCompletedSuccessfully) + try { - return; - } + // CancellationToken.None: the record belongs to the conversation, not to the turn the caller may + // have cancelled. + ValueTask pending = observer.OnConversationEventAsync(conversationEvent, CancellationToken.None); + if (pending.IsCompletedSuccessfully) + { + return; + } - await pending.ConfigureAwait(false); - } + await pending.ConfigureAwait(false); + } #pragma warning disable CA1031 // An observer records the conversation and is never a part of it. - catch (Exception exception) + catch (Exception exception) #pragma warning restore CA1031 - { - Report(conversationEvent, exception); + { + Report(conversationEvent, exception); + } } - } - /// Writes the one line an observer's fault is worth, and never throws. - /// The fact the observer refused. - /// The cause. - private void Report(ConversationEvent conversationEvent, Exception exception) - { - try + /// Writes the one line an observer's fault is worth, and never throws. + /// The fact the observer refused. + /// The cause. + private void Report(ConversationEvent conversationEvent, Exception exception) { - // The token is read from ConversationEventKinds, which is also what AuditConversationObserver and - // TelemetryConversationObserver ask about a kind. One mapping, so a line and a row never - // disagree about what the observer refused. - Log.AuditAppendFailed(_logger, conversationEvent.ConversationId, ConversationEventKinds.ToToken(conversationEvent.Kind), exception); - } + try + { + // The token is read from ConversationEventKinds, which is also what AuditConversationObserver and + // TelemetryConversationObserver ask about a kind. One mapping, so a line and a row never + // disagree about what the observer refused. + Log.AuditAppendFailed(_logger, conversationEvent.ConversationId, ConversationEventKinds.ToToken(conversationEvent.Kind), exception); + } #pragma warning disable CA1031 // A logger that refuses the report is still not a part of the conversation. - catch (Exception) + catch (Exception) #pragma warning restore CA1031 - { - // The report itself failed, and there is nowhere left to report that. A delivery that - // never faults is what the rest of this class promises, so the promise is kept here. + { + // The report itself failed, and there is nowhere left to report that. A delivery that + // never faults is what the rest of this class promises, so the promise is kept here. + } } } } diff --git a/src/AgentCore.Application/Runtime/ConversationObservers.cs b/src/AgentCore.Application/Runtime/ConversationObservers.cs index 3aa205dc..4000bc08 100644 --- a/src/AgentCore.Application/Runtime/ConversationObservers.cs +++ b/src/AgentCore.Application/Runtime/ConversationObservers.cs @@ -3,81 +3,82 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime; - -/// -/// Assembles the readings of one conversation, in the order every conversation then pays for. -/// -/// -/// -/// The composition root resolves an — always one, since -/// providers.audit falls back to the in-process memory kind — and an -/// , and knows nothing of . This is what turns them -/// into the telemetry, logging, and audit readings of one fact. It is composition, so it belongs to -/// the composition root and not to : the factory is handed the -/// finished list and holds no opinion about what is in it. -/// -/// -/// The observers it builds are shared and hold no per-call state, so one list serves every conversation. -/// The ordering guarantee is not here either — each session gets a -/// of its own, because that guarantee is per instance and a -/// shared one would make every conversation queue behind every other. -/// -/// -public static class ConversationObservers +namespace AgentCore.Application.Runtime { - /// Builds the list one host's bindings ask for. - /// - /// The sink the chain of D23 is appended to. There is always one: the composition root reads - /// providers.audit, which names the in-process memory kind when the document names - /// no vendor, so a host that configures nothing still hands a real sink down rather than a hole. - /// One sink serves every conversation, because a session names itself on every event. - /// - /// - /// The logger the three "log once" rows of section 8.7 write to, or for a - /// logger that writes nowhere. The library never throws for want of one. - /// - /// - /// The host's own readings of a conversation, or for a host that adds none. - /// - /// The readings, in the order the dispatcher offers each fact to them. - /// is . - public static IReadOnlyList Standard( - IAuditSinkPort auditSink, - ILogger? logger, - IEnumerable? hostObservers = null) + /// + /// Assembles the readings of one conversation, in the order every conversation then pays for. + /// + /// + /// + /// The composition root resolves an — always one, since + /// providers.audit falls back to the in-process memory kind — and an + /// , and knows nothing of . This is what turns them + /// into the telemetry, logging, and audit readings of one fact. It is composition, so it belongs to + /// the composition root and not to : the factory is handed the + /// finished list and holds no opinion about what is in it. + /// + /// + /// The observers it builds are shared and hold no per-call state, so one list serves every conversation. + /// The ordering guarantee is not here either — each session gets a + /// of its own, because that guarantee is per instance and a + /// shared one would make every conversation queue behind every other. + /// + /// + public static class ConversationObservers { - ArgumentNullException.ThrowIfNull(auditSink); + /// Builds the list one host's bindings ask for. + /// + /// The sink the chain of D23 is appended to. There is always one: the composition root reads + /// providers.audit, which names the in-process memory kind when the document names + /// no vendor, so a host that configures nothing still hands a real sink down rather than a hole. + /// One sink serves every conversation, because a session names itself on every event. + /// + /// + /// The logger the three "log once" rows of section 8.7 write to, or for a + /// logger that writes nowhere. The library never throws for want of one. + /// + /// + /// The host's own readings of a conversation, or for a host that adds none. + /// + /// The readings, in the order the dispatcher offers each fact to them. + /// is . + public static IReadOnlyList Standard( + IAuditSinkPort auditSink, + ILogger? logger, + IEnumerable? hostObservers = null) + { + ArgumentNullException.ThrowIfNull(auditSink); - // The sink goes LAST. The dispatcher offers one fact to each observer in turn, in - // this order, and that order is what a reading of the same fact costs the turn: the counters - // of section 8.6 and the rows of section 8.7 are taken above the enqueue, exactly as the old - // turn loop took them. The counter and the line always answer at once; a sink is the one that - // may not, and a durable insert is measured at 13 ms p50 and 32 ms p99 in section 7. - // - // What the order no longer decides is what a LATER fact costs. Each observer has a tail of - // its own inside the dispatcher, so a sink still writing an earlier row holds up nothing but - // its own next row: telemetry and logging keep their old synchronous cost on every event - // whatever the sink is doing, and the remarks on TelemetryConversationObserver still hold that a kind - // is counted whatever the sink then does with it. Order is guaranteed per observer, which is - // all the chain of D23 needs, and the slow one pays for itself alone, off the turn. - // - // All three readings are unconditional. The counters of section 8.6 and the rows of section - // 8.7 are this library's own and no host opts out of them, and the audit reading is now in - // the same position: the composition root resolves providers.audit into a sink for every - // host, falling back to the in-process memory kind when the document names no vendor, so - // there is no longer a "bound nothing" shape for this list to have. The chain of D23 is - // therefore written on every conversation, and a host that wants it durable changes where it goes, - // not whether it is taken. - IConversationObserver[] library = - [new TelemetryConversationObserver(), new LoggingConversationObserver(logger), new AuditConversationObserver(auditSink)]; + // The sink goes LAST. The dispatcher offers one fact to each observer in turn, in + // this order, and that order is what a reading of the same fact costs the turn: the counters + // of section 8.6 and the rows of section 8.7 are taken above the enqueue, exactly as the old + // turn loop took them. The counter and the line always answer at once; a sink is the one that + // may not, and a durable insert is measured at 13 ms p50 and 32 ms p99 in section 7. + // + // What the order no longer decides is what a LATER fact costs. Each observer has a tail of + // its own inside the dispatcher, so a sink still writing an earlier row holds up nothing but + // its own next row: telemetry and logging keep their old synchronous cost on every event + // whatever the sink is doing, and the remarks on TelemetryConversationObserver still hold that a kind + // is counted whatever the sink then does with it. Order is guaranteed per observer, which is + // all the chain of D23 needs, and the slow one pays for itself alone, off the turn. + // + // All three readings are unconditional. The counters of section 8.6 and the rows of section + // 8.7 are this library's own and no host opts out of them, and the audit reading is now in + // the same position: the composition root resolves providers.audit into a sink for every + // host, falling back to the in-process memory kind when the document names no vendor, so + // there is no longer a "bound nothing" shape for this list to have. The chain of D23 is + // therefore written on every conversation, and a host that wants it durable changes where it goes, + // not whether it is taken. + IConversationObserver[] library = + [new TelemetryConversationObserver(), new LoggingConversationObserver(logger), new AuditConversationObserver(auditSink)]; - // The host's own observers go after all three. An observer bound through - // AgentCoreOptions.UseObservers is code this library did not write and cannot measure, and - // the head of a delivery — the work before the first await — is the one part every observer - // still runs one after another. Putting the host last is what keeps the counters, the rows, - // and the enqueue at exactly the cost they had before any host bound anything. Past that head - // the order buys nothing and costs nothing: each observer has a tail of its own. - return hostObservers is null ? library : [.. library, .. hostObservers]; + // The host's own observers go after all three. An observer bound through + // AgentCoreOptions.UseObservers is code this library did not write and cannot measure, and + // the head of a delivery — the work before the first await — is the one part every observer + // still runs one after another. Putting the host last is what keeps the counters, the rows, + // and the enqueue at exactly the cost they had before any host bound anything. Past that head + // the order buys nothing and costs nothing: each observer has a tail of its own. + return hostObservers is null ? library : [.. library, .. hostObservers]; + } } } diff --git a/src/AgentCore.Application/Runtime/ConversationSession.cs b/src/AgentCore.Application/Runtime/ConversationSession.cs index c2c09531..e8bd18ed 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession.cs @@ -16,418 +16,423 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Runtime; - -/// -/// The turn loop of one conversation. It owns the state, the stage machine, and the transcript. -/// -public sealed class ConversationSession : IConversationPort, IAsyncDisposable +namespace AgentCore.Application.Runtime { /// - /// The line the caller hears when a turn fails and the document names none. - /// - public const string FallbackReply = AgentCoreConfiguration.DefaultFallbackReply; - - /// - /// The reason a turn that produced no text reports. - /// - public const string EmptyReplyReason = "the run returned an empty reply, so the turn spoke the fallback."; - - /// - /// The reason a turn that lost its tool budget reports, before the message of the fault. - /// - public const string ToolFailureReason = "a tool failed four times in a row, so the turn spoke the fallback."; - - /// - /// The failure the turn records when the completion work passes its deadline. - /// - internal const string ExtractionTimedOutReason = "the turn completion passed its deadline."; - - /// - /// What the log records when the moderation endpoint runs out of time. - /// - internal const string ModerationTimedOutReason = "the moderation endpoint passed its deadline."; - - /// - /// What the log records when the moderation endpoint throws. - /// - internal const string ModerationFaultedReason = "the moderation endpoint threw."; - - /// - /// How long the work after the reply may take before it is abandoned. + /// The turn loop of one conversation. It owns the state, the stage machine, and the transcript. /// - internal static readonly TimeSpan TurnCompletionTimeout = TimeSpan.FromSeconds(5); - - private readonly CompiledAgent _compiled; - - private readonly StagePolicy? _policy; - - private readonly StateExtractor? _extractor; - - private readonly CounterStateWriter _counters; - - private readonly TimeProvider _time; + public sealed class ConversationSession : IConversationPort, IAsyncDisposable + { + /// + /// The line the caller hears when a turn fails and the document names none. + /// + public const string FallbackReply = AgentCoreConfiguration.DefaultFallbackReply; - private readonly ConversationEventChain _events; + /// + /// The reason a turn that produced no text reports. + /// + public const string EmptyReplyReason = "the run returned an empty reply, so the turn spoke the fallback."; - private readonly DateTimeOffset _startedAt; + /// + /// The reason a turn that lost its tool budget reports, before the message of the fault. + /// + public const string ToolFailureReason = "a tool failed four times in a row, so the turn spoke the fallback."; - private readonly AgentCoreChatHistoryProvider _history; + /// + /// The failure the turn records when the completion work passes its deadline. + /// + internal const string ExtractionTimedOutReason = "the turn completion passed its deadline."; - private readonly bool _sessionCarriesHistory; + /// + /// What the log records when the moderation endpoint runs out of time. + /// + internal const string ModerationTimedOutReason = "the moderation endpoint passed its deadline."; - private readonly ILogger _logger; + /// + /// What the log records when the moderation endpoint throws. + /// + internal const string ModerationFaultedReason = "the moderation endpoint threw."; - private readonly Lock _interruptLock = new(); + /// + /// How long the work after the reply may take before it is abandoned. + /// + internal static readonly TimeSpan TurnCompletionTimeout = TimeSpan.FromSeconds(5); - private readonly Clarifications _clarifications = new(); + // Phase 1 seam: one live-state owner, verb-split operators. The helpers below hold this + // session and operate on the same fields under the same lock; only ownership of the verbs + // moved, so every commit protocol is byte-identical to the single-file shape. + internal StagePolicy? Policy { get; } - private readonly ConversationWorkspace? _workspace; + internal StateExtractor? Extractor { get; } - private readonly ConversationShells? _shells; + internal CounterStateWriter Counters { get; } - // Phase 1 seam: one live-state owner, verb-split operators. The helpers below hold this - // session and operate on the same fields under the same lock; only ownership of the verbs - // moved, so every commit protocol is byte-identical to the single-file shape. - internal StagePolicy? Policy => _policy; + internal TimeProvider Time { get; } - internal StateExtractor? Extractor => _extractor; + internal ConversationEventChain Events { get; } - internal CounterStateWriter Counters => _counters; + internal DateTimeOffset StartedAt { get; } - internal TimeProvider Time => _time; + internal AgentCoreChatHistoryProvider History { get; } - internal ConversationEventChain Events => _events; + internal bool SessionCarriesHistory { get; } - internal DateTimeOffset StartedAt => _startedAt; + internal ILogger Logger { get; } - internal AgentCoreChatHistoryProvider History => _history; + internal Lock InterruptLock { get; } = new(); - internal bool SessionCarriesHistory => _sessionCarriesHistory; + internal ConversationShells? Shells { get; } - internal ILogger Logger => _logger; + internal ConversationWorkspace? WorkspaceRoot { get; } - internal Lock InterruptLock => _interruptLock; + internal AgentSession? AgentSession { get; set; } - internal ConversationShells? Shells => _shells; + /// + /// The conversation's shared workflow session on a graph row whose document declares a harness + /// switch. MAF restores the participants' provider state from its checkpoints on every + /// turn; any other conversation runs every turn fresh and leaves this . + /// + internal AgentSession? GraphSession { get; set; } - internal ConversationWorkspace? WorkspaceRoot => _workspace; + /// + /// The last serialization of , read back at resume. Refreshed + /// at every turn end; a host snapshotting mid-turn gets the last turn boundary. + /// + internal JsonElement? GraphBlob { get; set; } - internal AgentSession? AgentSession { get; set; } + internal CancellationTokenSource? RunCancellation { get; set; } - /// - /// The conversation's shared workflow session on a graph row whose document declares a harness - /// switch. MAF restores the participants' provider state from its checkpoints on every - /// turn; any other conversation runs every turn fresh and leaves this . - /// - internal AgentSession? GraphSession { get; set; } - - /// - /// The last serialization of , read back at resume. Refreshed - /// at every turn end; a host snapshotting mid-turn gets the last turn boundary. - /// - internal JsonElement? GraphBlob { get; set; } + internal ConversationInterruptionTracker.Interruption? Interruption { get; set; } - internal CancellationTokenSource? RunCancellation { get; set; } + internal Guid? AmendableEventId { get; set; } - internal ConversationInterruptionTracker.Interruption? Interruption { get; set; } + internal ConversationSessionState? Checkpoint { get; set; } - internal Guid? AmendableEventId { get; set; } + internal Clarifications Clarifications { get; } = new(); - internal ConversationSessionState? Checkpoint { get; set; } - - internal Clarifications Clarifications => _clarifications; + internal ConversationTurnRunner Runner { get; } - internal ConversationTurnRunner Runner { get; } + internal ConversationTurnStream Stream { get; } - internal ConversationTurnStream Stream { get; } + internal ConversationTurnCompletion Completion { get; } - internal ConversationTurnCompletion Completion { get; } + internal ConversationTurnWriters Writers { get; } - internal ConversationTurnWriters Writers { get; } + internal ConversationInterruptionTracker Interruptions { get; } - internal ConversationInterruptionTracker Interruptions { get; } - - internal ConversationTranscriptLedger Ledger { get; } + internal ConversationTranscriptLedger Ledger { get; } - internal ConversationSessionStateStore States { get; } - - internal ConversationSessionLifetime Lifetime { get; } + internal ConversationSessionStateStore States { get; } - /// - /// Creates the session of one conversation. - /// - internal ConversationSession( - string conversationId, - ConversationSessionSeams seams, - ConversationObserverDispatcher? observers = null, - ConversationWorkspace? workspace = null) - { - ArgumentException.ThrowIfNullOrEmpty(conversationId); - ArgumentNullException.ThrowIfNull(seams); + internal ConversationSessionLifetime Lifetime { get; } - var (compiled, guards, extractor, timeProvider, logger) = seams; + /// + /// Creates the session of one conversation. + /// + internal ConversationSession( + string conversationId, + ConversationSessionSeams seams, + ConversationObserverDispatcher? observers = null, + ConversationWorkspace? workspace = null) + { + ArgumentException.ThrowIfNullOrEmpty(conversationId); + ArgumentNullException.ThrowIfNull(seams); - ConversationId = conversationId; + (CompiledAgent? compiled, IGuardEvaluator? guards, StateExtractor? extractor, TimeProvider? timeProvider, ILogger? logger) = seams; - _logger = logger ?? NullLogger.Instance; + ConversationId = conversationId; - _workspace = workspace; + Logger = logger ?? NullLogger.Instance; - _shells = workspace is null ? null : new ConversationShells(workspace.Path, _logger); + WorkspaceRoot = workspace; - _compiled = compiled; + Shells = workspace is null ? null : new ConversationShells(workspace.Path, Logger); - _history = compiled.History; + Compiled = compiled; - _sessionCarriesHistory = compiled.SessionCarriesHistory; + History = compiled.History; - _extractor = extractor; + SessionCarriesHistory = compiled.SessionCarriesHistory; - _counters = new CounterStateWriter(guards); + Extractor = extractor; - _time = timeProvider; + Counters = new CounterStateWriter(guards); - // The seam is optional and it has a working default. A host that binds nothing to watch the - // conversation still answers it, and the library never throws for want of an observer. - _events = new ConversationEventChain(conversationId, observers ?? new ConversationObserverDispatcher([]), timeProvider); + Time = timeProvider; - _startedAt = timeProvider.GetUtcNow(); + // The seam is optional and it has a working default. A host that binds nothing to watch the + // conversation still answers it, and the library never throws for want of an observer. + Events = new ConversationEventChain(conversationId, observers ?? new ConversationObserverDispatcher([]), timeProvider); - // An entry with no policy: has no stage machine. The single-agent row and both graph rows - // read that way, and neither of them ever ends a conversation by itself. - _policy = compiled.Policy is null ? null : compiled.CreatePolicy(guards); + StartedAt = timeProvider.GetUtcNow(); - State = new StateDocument(compiled.Configuration, _policy?.Stage); + // An entry with no policy: has no stage machine. The single-agent row and both graph rows + // read that way, and neither of them ever ends a conversation by itself. + Policy = compiled.Policy is null ? null : compiled.CreatePolicy(guards); - // The writers run in a fixed order, and this is its only record: const slots land before - // any turn, then each turn applies tool results, the extractor, the clock fields and the - // counters, in CompleteTurnAsync. Guards read the finished document, so the order is - // load-bearing. - ConstStateWriter.Apply(State); + State = new StateDocument(compiled.Configuration, Policy?.Stage); - // The first fact of this SESSION, and not necessarily of the conversation: a resumed conversation raises a - // second one, behind the turns of the session before it. Nothing allocates a position here - // any more — store 3 assigns the sequence — so a second one collides with nothing, and it is - // raised rather than suppressed because a session picking the conversation up is a fact that - // happened and the chain is where facts that happened go. Suppressing it is also not - // available from here: knowing whether the conversation already has words needs the store read that - // only OpenSessionAsync can do, and moving the raise there would let a conversation opened, never - // spoken to, and then ended through EndConversation write a conversation.ended with no conversation.started in front - // of it. - _ = _events.Raise(ConversationEventKind.ConversationStarted, _startedAt, turnIndex: null); + // The writers run in a fixed order, and this is its only record: const slots land before + // any turn, then each turn applies tool results, the extractor, the clock fields and the + // counters, in CompleteTurnAsync. Guards read the finished document, so the order is + // load-bearing. + _ = ConstStateWriter.Apply(State); - Runner = new ConversationTurnRunner(this); - Stream = new ConversationTurnStream(this); - Completion = new ConversationTurnCompletion(this); - Writers = new ConversationTurnWriters(this); - Interruptions = new ConversationInterruptionTracker(this); - Ledger = new ConversationTranscriptLedger(this); - States = new ConversationSessionStateStore(this); - Lifetime = new ConversationSessionLifetime(this); + // The first fact of this SESSION, and not necessarily of the conversation: a resumed conversation raises a + // second one, behind the turns of the session before it. Nothing allocates a position here + // any more — store 3 assigns the sequence — so a second one collides with nothing, and it is + // raised rather than suppressed because a session picking the conversation up is a fact that + // happened and the chain is where facts that happened go. Suppressing it is also not + // available from here: knowing whether the conversation already has words needs the store read that + // only OpenSessionAsync can do, and moving the raise there would let a conversation opened, never + // spoken to, and then ended through EndConversation write a conversation.ended with no conversation.started in front + // of it. + _ = Events.Raise(ConversationEventKind.ConversationStarted, StartedAt, turnIndex: null); + + Runner = new ConversationTurnRunner(this); + Stream = new ConversationTurnStream(this); + Completion = new ConversationTurnCompletion(this); + Writers = new ConversationTurnWriters(this); + Interruptions = new ConversationInterruptionTracker(this); + Ledger = new ConversationTranscriptLedger(this); + States = new ConversationSessionStateStore(this); + Lifetime = new ConversationSessionLifetime(this); + } + + /// + /// Gets the id of the conversation. + /// + public string ConversationId { get; } + + /// + /// Gets the folder this conversation owns on disk, or when the host bound no + /// workspace root. The folder is deleted when the conversation ends. + /// + public string? Workspace => WorkspaceRoot?.Path; + + /// + /// Gets the stage the machine holds. It is empty when the entry declares no policy. + /// + public string Stage => State.Stage; + + /// + /// Gets whether the conversation reached a terminal stage. An entry with no policy never does. + /// + public bool IsComplete { get; internal set; } + + /// + /// Gets the state of this conversation. Every guard and every increment rule reads it. + /// + public StateDocument State { get; } + + /// + /// Gets or sets the knowledge scope the host opened for this conversation, or null for none. Set it + /// before the run; every turn composes its own scope from it. + /// + public KnowledgeScope? Scope { get; set; } + + /// + /// Gets the conversation, oldest first. Every stage of the conversation reads it. + /// + public IReadOnlyList Transcript + => Ledger.Session() is { } session ? History.Read(session) : []; + + /// + /// Gets the turn that finished last, or before the first turn ends. + /// + public TurnResult? LastTurn { get; internal set; } + + /// + /// Gets the name the last written message was stored under, for a caller to hang an edit off. + /// + public string? LastReplyMessageId { get; internal set; } + + /// + /// Gets the compiled agent this session runs. Every conversation shares it. + /// + public CompiledAgent Compiled { get; } + + /// + /// Whether this conversation keeps one workflow session across turns: a graph row whose document + /// declares a harness switch. Everything else either carries history on a long-lived + /// session already (rows 1 and 2) or keeps no provider state at all. + /// + internal bool ReusesGraphSession => !SessionCarriesHistory && Compiled.HarnessStateKeys.Count > 0; + + /// + /// Gives the runs this conversation delegates through one tool a set of tools of their own. + /// + public void SetDelegatedTools(string delegatingToolId, IReadOnlyList tools) + { + Runner.SetDelegatedTools(delegatingToolId, tools); + } + + /// + /// Gives this conversation the screen its tools draw on, or takes it away. + /// + public void SetHasScreen(bool hasScreen) + { + Runner.SetHasScreen(hasScreen); + } + + /// + /// Runs one turn end to end, and returns what it did. + /// + public Task RunTurnAsync(string userInput, CancellationToken cancellationToken = default) + { + return RunTurnAtOriginAsync(userInput, origin: null, cancellationToken); + } + + /// + /// Runs one turn end to end from a message the caller built, and returns what it did. + /// + public Task RunTurnMessageAsync(ChatMessage userInput, CancellationToken cancellationToken) + { + return RunTurnMessageAtOriginAsync(userInput, origin: null, cancellationToken); + } + + /// + /// Runs one turn that knows where it sits in the conversation the caller can see. + /// + public Task RunTurnAtOriginAsync( + string userInput, ConversationTurnOrigin? origin, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(userInput); + + return Runner.RunTurnCoreAsync(new ChatMessage(ChatRole.User, userInput), origin, cancellationToken); + } + + /// + /// Runs one turn from a message the caller built, that knows where it sits in the conversation + /// the caller can see. + /// + public Task RunTurnMessageAtOriginAsync( + ChatMessage userInput, ConversationTurnOrigin? origin, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(userInput); + + return Runner.RunTurnCoreAsync(userInput, origin, cancellationToken); + } + + /// Runs one turn and streams the reply as it arrives. + /// The reply, one update at a time. Every update carries content. + /// + /// The conversation already reached a terminal stage, another turn of this conversation is still running, or the + /// stage the machine holds names no agent. + /// + public IAsyncEnumerable RunTurnStreamingAsync( + string userInput, CancellationToken cancellationToken = default) + { + return RunTurnStreamingAtOriginAsync(userInput, origin: null, cancellationToken); + } + + /// Runs one turn from a message the caller built and streams the reply as it arrives. + /// The reply, one update at a time. Every update carries content. + /// + /// The conversation already reached a terminal stage, another turn of this conversation is still running, or the + /// stage the machine holds names no agent. + /// + public IAsyncEnumerable RunTurnMessageStreamingAsync( + ChatMessage userInput, CancellationToken cancellationToken) + { + return RunTurnMessageStreamingAtOriginAsync(userInput, origin: null, cancellationToken); + } + + /// Builds the answer message for one queued approval request of this conversation. + public ChatMessage? TryCreateApprovalAnswer(string requestId, bool approved) + { + return Ledger.TryCreateApprovalAnswer(requestId, approved); + } + + /// Builds the answer message for one queued approval request of a resumed conversation. + /// The id of the pending request this answers. + /// Whether the tool may run. + /// Cancels the resume. + /// The user message carrying the approval response, or when no queued request carries that id. + public async ValueTask TryCreateApprovalAnswerAsync( + string requestId, bool approved, CancellationToken cancellationToken = default) + { + _ = await Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); + return Ledger.TryCreateApprovalAnswer(requestId, approved); + } + + /// + /// Runs one streaming turn that knows where it sits in the conversation the caller can see. + /// + public IAsyncEnumerable RunTurnStreamingAtOriginAsync( + string userInput, + ConversationTurnOrigin? origin, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(userInput); + + return Stream.RunTurnStreamingCoreAsync( + new ChatMessage(ChatRole.User, userInput), origin, cancellationToken); + } + + /// + /// Runs one streaming turn from a message the caller built, that knows where it sits in the + /// conversation the caller can see. + /// + public IAsyncEnumerable RunTurnMessageStreamingAtOriginAsync( + ChatMessage userInput, + ConversationTurnOrigin? origin, + CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(userInput); + + return Stream.RunTurnStreamingCoreAsync(userInput, origin, cancellationToken); + } + + /// + /// Ends the running turn where the caller cut the reply off. + /// + public bool Interrupt( + string utteranceUntilInterrupt, + TimeSpan durationUntilInterrupt, + bool cutsRunningTurn = true) + { + return Interruptions.Interrupt(utteranceUntilInterrupt, durationUntilInterrupt, cutsRunningTurn); + } + + /// Closes the conversation, and writes the last event of its chain. + public bool EndConversation(ConversationEndReason reason) + { + return Lifetime.EndConversation(reason); + } + + /// + /// Disposes this conversation's background sessions and shell executors. Idempotent: a session already + /// disposed, or one that never had either, disposes nothing. + /// + public ValueTask DisposeAsync() + { + return Lifetime.DisposeAsync(); + } + + /// + /// Waits for every store 1 write this conversation has queued. + /// + public Task FlushTranscriptAsync() + { + return Ledger.FlushTranscriptAsync(); + } + + /// + /// Reads the state this conversation would resume from, as it stands right now. The provider state is + /// read off the live bag with no turn lock around it, so a host serializing mid-turn gets the + /// bag as it stands at that instant, not a turn-boundary snapshot. A graph row that reuses + /// its session instead attaches that session's last turn-end serialization. + /// + internal ConversationSessionState Snapshot() + { + return States.Snapshot(); + } + + /// Names the state this conversation resumes from when store 0 holds none of its own. + internal void Resume(ConversationSessionState stored) + { + States.Resume(stored); + } } - - /// - /// Gets the id of the conversation. - /// - public string ConversationId { get; } - - /// - /// Gets the folder this conversation owns on disk, or when the host bound no - /// workspace root. The folder is deleted when the conversation ends. - /// - public string? Workspace => _workspace?.Path; - - /// - /// Gets the stage the machine holds. It is empty when the entry declares no policy. - /// - public string Stage => State.Stage; - - /// - /// Gets whether the conversation reached a terminal stage. An entry with no policy never does. - /// - public bool IsComplete { get; internal set; } - - /// - /// Gets the state of this conversation. Every guard and every increment rule reads it. - /// - public StateDocument State { get; } - - /// - /// Gets or sets the knowledge scope the host opened for this conversation, or null for none. Set it - /// before the run; every turn composes its own scope from it. - /// - public KnowledgeScope? Scope { get; set; } - - /// - /// Gets the conversation, oldest first. Every stage of the conversation reads it. - /// - public IReadOnlyList Transcript - => Ledger.Session() is { } session ? _history.Read(session) : []; - - /// - /// Gets the turn that finished last, or before the first turn ends. - /// - public TurnResult? LastTurn { get; internal set; } - - /// - /// Gets the name the last written message was stored under, for a caller to hang an edit off. - /// - public string? LastReplyMessageId { get; internal set; } - - /// - /// Gets the compiled agent this session runs. Every conversation shares it. - /// - public CompiledAgent Compiled => _compiled; - - /// - /// Whether this conversation keeps one workflow session across turns: a graph row whose document - /// declares a harness switch. Everything else either carries history on a long-lived - /// session already (rows 1 and 2) or keeps no provider state at all. - /// - internal bool ReusesGraphSession => !_sessionCarriesHistory && _compiled.HarnessStateKeys.Count > 0; - - /// - /// Gives the runs this conversation delegates through one tool a set of tools of their own. - /// - public void SetDelegatedTools(string delegatingToolId, IReadOnlyList tools) - => Runner.SetDelegatedTools(delegatingToolId, tools); - - /// - /// Gives this conversation the screen its tools draw on, or takes it away. - /// - public void SetHasScreen(bool hasScreen) => Runner.SetHasScreen(hasScreen); - - /// - /// Runs one turn end to end, and returns what it did. - /// - public Task RunTurnAsync(string userInput, CancellationToken cancellationToken = default) - => RunTurnAtOriginAsync(userInput, origin: null, cancellationToken); - - /// - /// Runs one turn end to end from a message the caller built, and returns what it did. - /// - public Task RunTurnMessageAsync(ChatMessage userInput, CancellationToken cancellationToken) - => RunTurnMessageAtOriginAsync(userInput, origin: null, cancellationToken); - - /// - /// Runs one turn that knows where it sits in the conversation the caller can see. - /// - public Task RunTurnAtOriginAsync( - string userInput, ConversationTurnOrigin? origin, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(userInput); - - return Runner.RunTurnCoreAsync(new ChatMessage(ChatRole.User, userInput), origin, cancellationToken); - } - - /// - /// Runs one turn from a message the caller built, that knows where it sits in the conversation - /// the caller can see. - /// - public Task RunTurnMessageAtOriginAsync( - ChatMessage userInput, ConversationTurnOrigin? origin, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(userInput); - - return Runner.RunTurnCoreAsync(userInput, origin, cancellationToken); - } - - /// Runs one turn and streams the reply as it arrives. - /// The reply, one update at a time. Every update carries content. - /// - /// The conversation already reached a terminal stage, another turn of this conversation is still running, or the - /// stage the machine holds names no agent. - /// - public IAsyncEnumerable RunTurnStreamingAsync( - string userInput, CancellationToken cancellationToken = default) - => RunTurnStreamingAtOriginAsync(userInput, origin: null, cancellationToken); - - /// Runs one turn from a message the caller built and streams the reply as it arrives. - /// The reply, one update at a time. Every update carries content. - /// - /// The conversation already reached a terminal stage, another turn of this conversation is still running, or the - /// stage the machine holds names no agent. - /// - public IAsyncEnumerable RunTurnMessageStreamingAsync( - ChatMessage userInput, CancellationToken cancellationToken) - => RunTurnMessageStreamingAtOriginAsync(userInput, origin: null, cancellationToken); - - /// Builds the answer message for one queued approval request of this conversation. - public ChatMessage? TryCreateApprovalAnswer(string requestId, bool approved) - => Ledger.TryCreateApprovalAnswer(requestId, approved); - - /// Builds the answer message for one queued approval request of a resumed conversation. - /// The id of the pending request this answers. - /// Whether the tool may run. - /// Cancels the resume. - /// The user message carrying the approval response, or when no queued request carries that id. - public async ValueTask TryCreateApprovalAnswerAsync( - string requestId, bool approved, CancellationToken cancellationToken = default) - { - await Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); - return Ledger.TryCreateApprovalAnswer(requestId, approved); - } - - /// - /// Runs one streaming turn that knows where it sits in the conversation the caller can see. - /// - public IAsyncEnumerable RunTurnStreamingAtOriginAsync( - string userInput, - ConversationTurnOrigin? origin, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(userInput); - - return Stream.RunTurnStreamingCoreAsync( - new ChatMessage(ChatRole.User, userInput), origin, cancellationToken); - } - - /// - /// Runs one streaming turn from a message the caller built, that knows where it sits in the - /// conversation the caller can see. - /// - public IAsyncEnumerable RunTurnMessageStreamingAtOriginAsync( - ChatMessage userInput, - ConversationTurnOrigin? origin, - CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(userInput); - - return Stream.RunTurnStreamingCoreAsync(userInput, origin, cancellationToken); - } - - /// - /// Ends the running turn where the caller cut the reply off. - /// - public bool Interrupt( - string utteranceUntilInterrupt, - TimeSpan durationUntilInterrupt, - bool cutsRunningTurn = true) - => Interruptions.Interrupt(utteranceUntilInterrupt, durationUntilInterrupt, cutsRunningTurn); - - /// Closes the conversation, and writes the last event of its chain. - public bool EndConversation(ConversationEndReason reason) => Lifetime.EndConversation(reason); - - /// - /// Disposes this conversation's background sessions and shell executors. Idempotent: a session already - /// disposed, or one that never had either, disposes nothing. - /// - public ValueTask DisposeAsync() => Lifetime.DisposeAsync(); - - /// - /// Waits for every store 1 write this conversation has queued. - /// - public Task FlushTranscriptAsync() => Ledger.FlushTranscriptAsync(); - - /// - /// Reads the state this conversation would resume from, as it stands right now. The provider state is - /// read off the live bag with no turn lock around it, so a host serializing mid-turn gets the - /// bag as it stands at that instant, not a turn-boundary snapshot. A graph row that reuses - /// its session instead attaches that session's last turn-end serialization. - /// - internal ConversationSessionState Snapshot() => States.Snapshot(); - - /// Names the state this conversation resumes from when store 0 holds none of its own. - internal void Resume(ConversationSessionState stored) => States.Resume(stored); } diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationInterruptionTracker.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationInterruptionTracker.cs deleted file mode 100644 index 72992843..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationInterruptionTracker.cs +++ /dev/null @@ -1,172 +0,0 @@ -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationInterruptionTracker -{ - private readonly ConversationSession _session; - - // One session runs one turn at a time. Lives here, with the rest of the live run, so the - // guard and the release travel together; BeginTurn enters through TryEnterTurn. - private int _running; - - // Whether the running turn has already handed the host something to speak. One rule for both - // run shapes: a run that has handed the host nothing cannot be the turn the caller was hearing. - private volatile bool _runIsAudible; - - /// - /// Whether the running turn has handed the host something to speak. - /// - internal bool RunIsAudible { get => _runIsAudible; set => _runIsAudible = value; } - - internal ConversationInterruptionTracker(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// - /// Ends the running turn where the caller cut the reply off. - /// - /// The text the caller actually heard. - /// How much of the reply played, as the relay reported it. - /// - /// Whether the turn running now is the turn the caller was hearing. An adapter that tracks which - /// turn's output actually reached the vendor answers that question itself and says so here; - /// sends the frame straight to the amendment path, whatever the running - /// turn has produced. The default is , which leaves the decision to this - /// session alone, and that is the right answer for a caller that speaks over a reply it is - /// itself streaming. - /// - /// - /// when this conversation recorded the barge-in, either by ending the running - /// turn or by amending the turn that finished last, and when there was - /// nothing to record it against. - /// - /// - /// is negative. - /// - internal bool Interrupt( - string utteranceUntilInterrupt, - TimeSpan durationUntilInterrupt, - bool cutsRunningTurn = true) - { - ArgumentNullException.ThrowIfNull(utteranceUntilInterrupt); - ArgumentOutOfRangeException.ThrowIfLessThan(durationUntilInterrupt, TimeSpan.Zero); - - lock (_session.InterruptLock) - { - // Both conditions, and in this order. The adapter's answer only ever removes the - // in-flight path: an adapter that knows the caller was hearing an earlier turn skips it - // outright, and one that says nothing leaves this session's own audibility test to - // decide. - if (cutsRunningTurn && _session.RunCancellation is { } cancellation && RunIsAudible) - { - _session.Interruption = new Interruption(utteranceUntilInterrupt, durationUntilInterrupt); - cancellation.Cancel(); - return true; - } - - return AmendLastTurn(new Interruption(utteranceUntilInterrupt, durationUntilInterrupt)); - } - } - - /// - /// Opens the window in which reaches this turn. - /// - /// The token of the host. - /// The source the run reads. The caller ends it with . - internal CancellationTokenSource StartRun(CancellationToken cancellationToken) - { - CancellationTokenSource cancellation = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - - lock (_session.InterruptLock) - { - _session.Interruption = null; - _session.RunCancellation = cancellation; - _runIsAudible = false; - } - - return cancellation; - } - - /// Takes the turn slot, unless a turn of this conversation is still running. - /// when another turn holds the slot. - internal bool TryEnterTurn() => Interlocked.Exchange(ref _running, 1) == 0; - - /// Frees the turn slot after a turn refused to start left it taken. - internal void ReleaseTurn() => Volatile.Write(ref _running, 0); - - /// - /// Closes the window, and frees the session for the next turn. - /// - /// The source returned. - internal void EndRun(CancellationTokenSource cancellation) - { - // The field drops first. A frame that arrives now meets no source to cancel, so it reaches - // the amendment path rather than a disposed one. - lock (_session.InterruptLock) - { - _session.RunCancellation = null; - _runIsAudible = false; - } - - cancellation.Dispose(); - Volatile.Write(ref _running, 0); - } - - /// - /// Records a barge-in against the turn that finished last, and corrects its record. - /// - /// What the relay reported: the heard text and the played duration. - /// - /// when the turn was amended, and when there was - /// no turn to amend. - /// - internal bool AmendLastTurn(Interruption cut) - { - // The chain has already closed, so nothing may be appended behind conversation.ended. - if (_session.Events.HasEnded - || _session.AmendableEventId is not { } completedEventId - || _session.LastTurn is not { InterruptedAfter: null } finished - || _session.Ledger.Session() is not { } session) - { - return false; - } - - var heard = cut.HeardText.Trim(); - - // Store 1 keeps the reply row and rewrites its words, rather than replacing the turn's - // messages. The turn it corrects ran to its end, so every tool call it made is already - // paired and there is nothing unfinished to strip out. - // - // The cut always lands today: a turn is amendable only when it completed with words, and a - // turn that completed with words left a reply row holding them. The answer is still read, - // because the row below names a HASH of those words — a chain that proves words store 1 - // does not hold proves nothing, so no cut means no amendment. - if (!_session.History.TruncateLastReply(session, heard, cut.PlayedDuration)) - { - return false; - } - - _session.LastTurn = finished with { ReplyText = heard, InterruptedAfter = cut.PlayedDuration }; - - _session.Events.RaiseReplyInterrupted( - finished.TurnIndex, _session.Time.GetUtcNow(), completedEventId, heard, cut.PlayedDuration); - - return true; - } - - /// Reads the interruption the relay reported for the running turn. - /// The record, or when the caller did not interrupt. - internal Interruption? CurrentInterruption() - { - lock (_session.InterruptLock) - { - return _session.Interruption; - } - } - - /// What the relay reported when the caller spoke over the reply. - /// The text the caller actually heard. - /// How much of the reply played, at 1 ms. - internal sealed record Interruption(string HeardText, TimeSpan PlayedDuration); -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionLifetime.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionLifetime.cs deleted file mode 100644 index 270b6280..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionLifetime.cs +++ /dev/null @@ -1,79 +0,0 @@ -using AgentCore.Application.Runtime.Harness; -using AgentCore.Domain.Audit; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationSessionLifetime -{ - private readonly ConversationSession _session; - - // The background release runs once per conversation: both DisposeAsync and the turn-end path reach - // it, and a second release would re-cancel children that already went away. - private int _backgroundReleased; - - internal ConversationSessionLifetime(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// Closes the conversation, and writes the last event of its chain. - /// Why the conversation ended, as one member of the closed set. - /// - /// when this conversation wrote the event, and when the - /// conversation had already ended. - /// - /// - /// is not a member of the closed set. - /// - internal bool EndConversation(ConversationEndReason reason) - { - // The event is written before the flag moves. A value outside the closed set therefore ends - // no conversation and writes nothing. - var wrote = _session.Events.EndConversation(reason, _session.Time.GetUtcNow()); - _session.IsComplete = true; - DeleteWorkspace(); - return wrote; - } - - /// - /// Deletes this conversation's workspace, if it has one. Called once the chain has recorded why the - /// conversation ended, from every path that can end it. - /// - internal void DeleteWorkspace() => _session.WorkspaceRoot?.Delete(_session.Logger); - - /// - /// Disposes this conversation's background sessions and shell executors. Idempotent: a session already - /// disposed, or one that never had either, disposes nothing. - /// - internal async ValueTask DisposeAsync() - { - await ReleaseBackgroundSessionsAsync().ConfigureAwait(false); - await DisposeShellsAsync().ConfigureAwait(false); - } - - /// - /// Cancels the background children still running on this conversation's session and releases it, once - /// per conversation. Skipped when the conversation never opened a session or the document names no background - /// children. Release precedes the shells: a child cancelled here may be inside a shell tool. - /// - internal async ValueTask ReleaseBackgroundSessionsAsync() - { - if (Interlocked.Exchange(ref _backgroundReleased, 1) == 1 - || _session.Compiled.BackgroundProviders.Count == 0 - || _session.Ledger.Session() is not { } session) - { - return; - } - - await BackgroundSessionRelease.ReleaseAsync( - _session.Compiled.BackgroundProviders, session, _session.ConversationId, _session.Logger, CancellationToken.None).ConfigureAwait(false); - } - - /// - /// Disposes this conversation's shell executors, if it has any. does not conversation - /// this: a tool that ends the conversation mid-turn still needs the shell for the rest of that turn, so - /// only the turn-end path and tear it down. - /// - internal ValueTask DisposeShellsAsync() => _session.Shells?.DisposeAsync() ?? ValueTask.CompletedTask; -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs deleted file mode 100644 index 30517917..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationSessionStateStore.cs +++ /dev/null @@ -1,132 +0,0 @@ -using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Conversation; -using AgentCore.Application.Runtime.Harness; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationSessionStateStore -{ - private readonly ConversationSession _session; - - internal ConversationSessionStateStore(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// Puts back what a previous session of this conversation had, as far as the document still allows. - internal void Restore(ConversationSessionState stored) - { - if (stored.Version != ConversationSessionState.CurrentVersion) - { - Dropped($"the stored state is version {stored.Version} and this build writes {ConversationSessionState.CurrentVersion}."); - return; - } - - string? refusedStage = null; - - if (_session.Policy is null) - { - if (stored.Stage.Length > 0) - { - refusedStage = $"the entry declares no policy, so the stage '{stored.Stage}' has nowhere to go."; - } - } - else if (!_session.Policy.Declares(stored.Stage)) - { - refusedStage = $"the document no longer declares the stage '{stored.Stage}'."; - } - - if (refusedStage is null) - { - _session.Policy?.RestoreStage(stored.Stage); - - _session.State.Stage = stored.Stage; - - _session.IsComplete = stored.IsComplete; - } - else - { - Dropped(refusedStage); - } - - _session.Clarifications.RestoreSpent(stored.Clarifications); - - foreach (var slot in stored.Slots) - { - if (ReservedStateSlots.Contains(slot.Key)) - { - Dropped($"the slot '{slot.Key}' is reserved, and a reserved slot is never restored."); - - continue; - } - - if (_session.State.TryWrite(slot.Key, slot.Value?.DeepClone())) - { - continue; - } - - Dropped( - _session.State.Configuration.State.ContainsKey(slot.Key) - ? $"the slot '{slot.Key}' no longer takes the value it was stored with." - : $"the document no longer declares the slot '{slot.Key}'."); - } - - void Dropped(string reason) => _session.Events.RaiseDiagnostic( - ConversationEventKind.StateRestorePartial, - _session.Time.GetUtcNow(), - turnIndex: null, - payload: new Dictionary(StringComparer.Ordinal) - { - [ConversationEventPayloadKeys.Reason] = reason, - }); - } - - /// - /// Reads the state this conversation would resume from, as it stands right now. The provider state is - /// read off the live bag with no turn lock around it, so a host serializing mid-turn gets the - /// bag as it stands at that instant, not a turn-boundary snapshot. A graph row that reuses - /// its session instead attaches that session's last turn-end serialization. - /// - internal ConversationSessionState Snapshot() - { - lock (_session.InterruptLock) - { - if (_session.AgentSession is null && _session.Checkpoint is { } held) - { - return held; - } - } - - return new() - { - Stage = _session.State.Stage, - IsComplete = _session.IsComplete, - Slots = _session.State.WrittenSlots(), - NextTurnIndex = _session.State.TurnIndex, - Clarifications = _session.Clarifications.Spent(), - Providers = HarnessSessionState.Capture(_session.AgentSession, _session.Compiled.HarnessStateKeys), - WorkflowState = _session.GraphBlob, - }; - } - - /// Names the state this conversation resumes from when store 0 holds none of its own. - internal void Resume(ConversationSessionState stored) - { - ArgumentNullException.ThrowIfNull(stored); - - lock (_session.InterruptLock) - { - if (_session.AgentSession is not null) - { - throw new InvalidOperationException( - $"The conversation '{_session.ConversationId}' has already run a turn, and a conversation resumes only as its " - + "first turn opens it. Hand the state to the factory that builds the session " - + "instead."); - } - - _session.Checkpoint = stored; - } - } -} - diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs deleted file mode 100644 index 0a1629ba..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTranscriptLedger.cs +++ /dev/null @@ -1,215 +0,0 @@ -using AgentCore.Application.Conversation; -using AgentCore.Application.Diagnostics; -using AgentCore.Application.Runtime.Harness; -using AgentCore.Application.Transcript; -using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationTranscriptLedger -{ - private readonly ConversationSession _session; - - internal ConversationTranscriptLedger(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// - /// Opens the session of this conversation, once, and re-syncs it with store 0 before handing it to every - /// later turn. - /// - /// Cancels the open. - /// The session. - internal async ValueTask OpenSessionAsync(CancellationToken cancellationToken) - { - if (Session() is { } opened) - { - await ResyncTranscriptAsync(opened, cancellationToken).ConfigureAwait(false); - return opened; - } - - var record = await _session.Compiled.ConversationStore.CreateAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); - - ConversationSessionState? checkpoint; - lock (_session.InterruptLock) - { - checkpoint = _session.Checkpoint; - } - - var stored = record.State ?? checkpoint; - - AgentSession session; - if (_session.SessionCarriesHistory) - { - session = stored is { Version: ConversationSessionState.CurrentVersion, Providers.Count: > 0 } - ? await _session.Compiled.TurnAgent.DeserializeSessionAsync( - HarnessSessionState.Wrap(stored.Providers), cancellationToken: cancellationToken).ConfigureAwait(false) - : await _session.Compiled.TurnAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - } - else - { - session = new ConversationHistorySession(); - - if (_session.ReusesGraphSession) - { - _session.GraphSession = stored is { Version: ConversationSessionState.CurrentVersion, WorkflowState: { } blob } - ? await _session.Compiled.TurnAgent.DeserializeSessionAsync(blob, cancellationToken: cancellationToken).ConfigureAwait(false) - : await _session.Compiled.TurnAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - } - } - - IReadOnlyList spoken = record.LastMessageAt is null - ? [] - : await _session.Compiled.ConversationStore.ReadForSessionAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); - - lock (_session.InterruptLock) - { - if (_session.AgentSession is null) - { - _session.AgentSession = session; - - _session.State.TurnIndex = _session.History.BeginConversation( - session, - _session.ConversationId, - spoken, - _session.Events.RaiseDroppedTranscriptWrite, - new TranscriptMarks(record.NextOrdinal, stored?.NextTurnIndex ?? 0)); - - if (stored is { } s) - { - _session.States.Restore(s); - } - } - - return _session.AgentSession; - } - } - - /// - /// Brings the session's words back in line with store 1 before a turn after the first, when and - /// only when someone else wrote to the conversation in between. - /// - /// The session of this conversation. - /// Cancels the reads. - private async ValueTask ResyncTranscriptAsync(AgentSession opened, CancellationToken cancellationToken) - { - await _session.History.DrainAsync(opened).ConfigureAwait(false); - - try - { - var refreshed = await RecordAsync("resync against", cancellationToken).ConfigureAwait(false); - - if (refreshed.NextOrdinal == _session.History.NextOrdinal(opened)) - { - return; - } - - var rows = await _session.Compiled.ConversationStore.ReadForSessionAsync( - _session.ConversationId, cancellationToken).ConfigureAwait(false); - - _session.History.Resync(opened, rows, refreshed.NextOrdinal); - } -#pragma warning disable CA1031 // A store that cannot be read never ends a conversation: the turn runs on the words the session holds. - catch (Exception exception) when (exception is not OperationCanceledException) -#pragma warning restore CA1031 - { - Log.TranscriptResyncFailed(_session.Logger, _session.ConversationId, _session.State.TurnIndex, exception); - _session.Events.RaiseFailedTranscriptResync(_session.State.TurnIndex, exception); - } - } - - /// - /// Cuts an edit that reaches under the summary: the parent is a row the summary stands in for, - /// or the edit takes the whole conversation. The caller asks - /// first and comes here when it says no. - /// - /// The session of this conversation. - /// The message the edit hangs off, or for the whole conversation. - /// Cancels the cut. - /// The turns the cut withdrew, or when nothing went. - internal async ValueTask CutUnderSummaryAsync( - AgentSession opened, string? parentMessageId, CancellationToken cancellationToken) - { - var store = _session.Compiled.ConversationStore; - - await _session.History.DrainAsync(opened).ConfigureAwait(false); - - int from; - if (parentMessageId is null) - { - from = 0; - } - else if (await store.OrdinalOfAsync(_session.ConversationId, parentMessageId, cancellationToken).ConfigureAwait(false) is { } parent) - { - from = parent + 1; - } - else - { - return null; - } - - var cut = await store.TruncateAsync(_session.ConversationId, from, cancellationToken).ConfigureAwait(false); - Log.ConversationTruncated(_session.Logger, _session.ConversationId, from, _session.State.TurnIndex); - - var refreshed = await RecordAsync("edit", cancellationToken).ConfigureAwait(false); - var rows = await store.ReadForSessionAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); - - _session.History.Resync(opened, rows, refreshed.NextOrdinal); - - return cut.Turns; - } - - /// Store 0's record of this conversation, which must exist for a session that already opened it. - /// What the session is about to do with it, for the error. - /// Cancels the read. - private async ValueTask RecordAsync(string purpose, CancellationToken cancellationToken) - => await _session.Compiled.ConversationStore.GetAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false) - ?? throw new InvalidOperationException( - $"Store 0 holds no conversation '{_session.ConversationId}' for its own session to {purpose}."); - - /// - /// Reads the session of this conversation, or null before its first turn opened one. - /// - /// The session. - internal AgentSession? Session() - { - lock (_session.InterruptLock) - { - return _session.AgentSession; - } - } - - /// - /// Waits for every store 1 write this conversation has queued. - /// - /// A task that completes when the words of the conversation are durable. - internal async Task FlushTranscriptAsync() - { - if (Session() is { } session) - { - await _session.History.DrainAsync(session).ConfigureAwait(false); - } - } - - /// Builds the answer message for one queued approval request of this conversation. - /// The id the caller answers. - /// Whether the tool may run. - /// - /// The user message carrying the approval response, or when this conversation - /// queues no request under that id: answered already, another conversation's, or never asked. - /// - internal ChatMessage? TryCreateApprovalAnswer(string requestId, bool approved) - { - ArgumentException.ThrowIfNullOrEmpty(requestId); - - return Session() is { } session - ? PendingApprovalQueue.AnswerFor(session.StateBag.Serialize(), requestId, approved) - : null; - } - - /// The session a graph row's conversation holds, so store 1 has somewhere to live. - private sealed class ConversationHistorySession : AgentSession; -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurn.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurn.cs deleted file mode 100644 index 42a922aa..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurn.cs +++ /dev/null @@ -1,28 +0,0 @@ -using System.Diagnostics; -using AgentCore.Application.Runtime.Turn; -using AgentCore.Domain.Knowledge; -using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -// The turn's working set, carried from preparation through commit. Built once per turn in -// ConversationTurnRunner.BeginTurn for the same reason Activity is: ConversationTurnStream reopens the state -// scope on every step of a streaming turn, and collectors built per step would lose whatever an -// earlier step drew before a later step could attach it to a message. -internal sealed record ConversationTurn( - AIAgent Agent, - AgentSession Session, - List Request, - ChatMessage Spoken, - string? Reminder, - string StageBefore, - int Index, - Activity? Activity, - long StartedAt, - TurnRenders? Renders, - TurnSources Sources, - TurnResults Results, - TurnFiles Files, - KnowledgeScope? Knowledge, - string? MessageId); diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs deleted file mode 100644 index ea591603..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCommit.cs +++ /dev/null @@ -1,82 +0,0 @@ -using AgentCore.Domain; -using AgentCore.Domain.Audit; - -namespace AgentCore.Application.Runtime; - -/// -/// The publish half of a turn: appends the transcript, writes the turn's events, and tears the -/// conversation down when it is over. decides the turn; this commits it. -/// -internal sealed class ConversationTurnCommit -{ - private readonly ConversationSession _session; - - internal ConversationTurnCommit(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - internal TurnResult Publish( - ConversationTurn turn, - ReplyOutcome outcome, - TranscriptEntry addition, - TurnResult result, - ConversationInterruptionTracker.Interruption? interruption) - { - lock (_session.InterruptLock) - { - if (_session.SessionCarriesHistory) - { - _session.LastReplyMessageId = _session.History.AppendTurn( - turn.Session, [turn.Spoken, .. addition.Written], _session.Snapshot(), turn.MessageId); - } - else - { - _session.LastReplyMessageId = _session.History.AppendCallerFacingTurn( - turn.Session, turn.Spoken, addition.Heard, _session.Snapshot(), turn.MessageId); - } - - var completedEventId = _session.Events.WriteTurnEvents(result, outcome.SpokenReply, outcome.ToolFault); - - _session.AmendableEventId = outcome.InterruptedAfter is null ? completedEventId : null; - - _session.LastTurn = result; - - if (interruption is null - && _session.Interruption is { } late - && _session.Interruptions.AmendLastTurn(late) - && _session.LastTurn is { } amended) - { - result = amended; - } - - _session.Interruption = null; - - _session.RunCancellation = null; - - _session.Interruptions.RunIsAudible = false; - } - - return result; - } - - internal async Task EndConversationIfOverAsync(DateTimeOffset endedAt, string stageAfter) - { - if (_session.IsComplete) - { - _session.Events.EndConversation(ConversationEndReason.AgentCompleted, endedAt, stageAfter); - } - - if (!_session.IsComplete && !_session.Events.HasEnded) - { - return; - } - - await _session.Lifetime.ReleaseBackgroundSessionsAsync().ConfigureAwait(false); - - await _session.Lifetime.DisposeShellsAsync().ConfigureAwait(false); - - _session.Lifetime.DeleteWorkspace(); - } -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCompletion.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCompletion.cs deleted file mode 100644 index 73dde7da..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnCompletion.cs +++ /dev/null @@ -1,332 +0,0 @@ -using System.Text.Json; -using AgentCore.Application.Diagnostics; -using AgentCore.Application.Runtime.Turn; -using AgentCore.Domain; -using AgentCore.Domain.Audit; -using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationTurnCompletion -{ - private readonly ConversationSession _session; - - private readonly ConversationTurnCommit _commit; - - internal ConversationTurnCompletion(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - _commit = new ConversationTurnCommit(session); - } - - /// Runs every writer, then lets the machine pick the stage of the next turn. - /// The turn that just spoke. - /// What the agent answered. - /// - /// The message of the fault that threw out of the run, or when nothing - /// threw. Section 8.7, row six. - /// - /// Cancels the extractor call. - /// The finished turn. - /// - /// What and reported about - /// this turn, or when neither layer marked it. A flagged turn skips the - /// extractor: the words moderation flagged are its only input, and a slot filled from them would - /// carry the flagged content into the state document and into every later prompt. Everything else - /// about a refused turn is ordinary, so the refusal enters the transcript, the stage machine - /// advances, and turn.completed proves the refusal under - /// . - /// - internal async Task CompleteTurnAsync( - ConversationTurn turn, - AgentResponse response, - string? toolFault, - TurnDisposition? disposition, - CancellationToken cancellationToken) - { - // Sweep drain state for tool calls whose round never reached the client's drain: the - // round that ends a turn attaches nothing, so turn-scoped records would otherwise - // leave entries sitting on the shared clients. - turn.Results.Sweep(); - - // Calls the model named that no tool answered never reach the invoking client, so no - // per-call state names them. The turn's own record does: every id the model gave minus - // every id a tool ran under. Reported here, at the same turn end that sweeps the drain. - ReportUndeclaredToolCalls(turn, response); - - var interruption = _session.Interruptions.CurrentInterruption(); - - // The moderation facts of this turn, raised before the turn's own events so the flag still - // takes the lower ordinal. The verdict is known before the model runs, which is the one rule - // that separates prompt.flagged from reply.interrupted: it amends nothing. - var refused = disposition?.Moderation is ModerationOutcome.Flagged; - _session.Events.RaiseModeration(turn.Index, disposition); - - var outcome = ResolveReply(turn, response, interruption, disposition, toolFault); - var addition = TranscriptAddition(response, outcome); - - // The per-turn writers run from here, in the order the constructor documents: tool results - // first. - _session.Writers.ApplyToolResults(response.Messages); - - // A refused turn runs no extractor. The words moderation flagged are the extractor's only - // input, so a slot filled from them would carry the flagged content into the state document - // and into every later prompt. The refusal itself says nothing worth extracting either, and - // the extractor costs a model call, so this also spends nothing on a turn nobody answered. - // A pending turn runs none either: the run suspended instead of answering, so there is - // nothing decided to read. - var extractionFailure = refused || outcome.Approvals.Count > 0 - ? null - : await ExtractAsync(turn, response, cancellationToken).ConfigureAwait(false); - - // The clock fields write next. The clock comes from the injected provider, so a test owns - // it. The same read stamps every audit event of this turn. - var endedAt = _session.Time.GetUtcNow(); - _session.State.TurnIndex++; - _session.State.ConversationDurationSeconds = (endedAt - _session.StartedAt).TotalSeconds; - - // The counters write last. - _session.Counters.Apply(_session.State); - - var stageAfter = AdvanceStage(turn); - - TurnResult result = new( - _session.ConversationId, - turn.Index, - turn.StageBefore, - stageAfter, - outcome.Reply, - _session.IsComplete, - extractionFailure, - outcome.Failure, - outcome.InterruptedAfter, - endedAt) - { - Approvals = outcome.Approvals, - }; - - // A graph row that reuses its session persists it here, before the commit below reads - // it into store 0: the next turn resumes from these checkpoints, and a resumed conversation - // rebuilds them. Rows 1 and 2 need nothing — their session outlives the conversation. - if (_session.ReusesGraphSession && _session.GraphSession is { } shared) - { - _session.GraphBlob = await turn.Agent.SerializeSessionAsync(shared, cancellationToken: cancellationToken).ConfigureAwait(false); - } - - result = _commit.Publish(turn, outcome, addition, result, interruption); - - AgentCoreTelemetry.EndTurn( - turn.Activity, - _session.Time.GetElapsedTime(turn.StartedAt), - Outcome(result.Failure, result.InterruptedAfter), - stageAfter, - result.Failure); - - await _commit.EndConversationIfOverAsync(endedAt, stageAfter).ConfigureAwait(false); - - return result; - } - - private ReplyOutcome ResolveReply( - ConversationTurn turn, - AgentResponse response, - ConversationInterruptionTracker.Interruption? interruption, - TurnDisposition? disposition, - string? toolFault) - { - // R1 reaches the turn through the fallback layer, and a fault above every chat client — a - // graph that matched no edge — still reaches the catch in the run methods. Both are the - // same row-six fact. - toolFault ??= disposition is { Fallback: FallbackCause.Faulted, FallbackReason: { } caught } - ? caught - : null; - - var reply = SpokenReply.From(response.Messages); - var spokenReply = reply; - TimeSpan? interruptedAfter = null; - string? failure = toolFault is null ? null : ConversationSession.ToolFailureReason + " " + toolFault; - - // The tool calls still waiting on a human answer. A pending turn is not a failure: the - // run suspended instead of answering, so the empty-reply substitution below is skipped, - // the extractor has nothing decided to read, and the requests ride TurnResult to the host. - var approvals = ApprovalRequestsOf(response); - - if (interruption is { } cut) - { - // Item 6a. The record holds the text the caller heard, not the text the model produced. - // A trailing space is not speech, so it is trimmed: pipecat pins the same rule in its - // aggregator test, where the model sent "Hello " and the record holds "Hello". - reply = cut.HeardText.Trim(); - interruptedAfter = cut.PlayedDuration; - } - else if (approvals.Count == 0 && (failure is not null - || string.IsNullOrWhiteSpace(reply) - || disposition?.Fallback is FallbackCause.EmptyReply)) - { - // Section 8.7, last row. A quiet run is silence on a voice conversation, so an empty reply is a - // failure even though nothing threw. - failure ??= ConversationSession.EmptyReplyReason; - reply = _session.Compiled.FallbackReply; - spokenReply = reply; - } - - // Section 8.7, last row, raised once for the turn. It is diagnostic only, so it takes no - // ordinal and no row records it; the turn.completed event of this same turn carries the - // fallback the caller actually heard. The tool fault of row six is raised in - // WriteTurnEvents instead, because the chain stores that one and its row is stamped with - // the same endedAt every other event of the turn carries. - if (toolFault is null && failure is not null) - { - _session.Events.RaiseDiagnostic(ConversationEventKind.EmptyReply, _session.Time.GetUtcNow(), turn.Index); - } - - return new ReplyOutcome(reply, spokenReply, failure, toolFault, interruptedAfter, approvals); - } - - // Built before the writers run and committed at the end of the turn, in one lock with the rest - // of what a late barge-in may still amend: the transcript span, the ordinal the amendment must - // reference, and LastTurn itself. Nothing in between reads the transcript — the extractor reads - // the finished turn, and the writers read the state document — so building it early and - // committing it once costs nothing. - private TranscriptEntry TranscriptAddition(AgentResponse response, ReplyOutcome outcome) - { - // A barge-in inside the first 100 ms leaves no heard text, and an empty assistant message - // teaches the model nothing. pipecat and livekit both guard this. Both row shapes read this - // one value, so what counts as words the caller heard is decided once. - var heard = outcome.Reply.Length > 0 ? new ChatMessage(ChatRole.Assistant, outcome.Reply) : null; - - // Rows 3 and 4 record the caller-facing turn alone, so `written` stays empty for them: a - // node's tool pair and a node's line to the next node are neither said nor heard, and the - // commit takes the heard reply straight. - if (!_session.SessionCarriesHistory) - { - return new TranscriptEntry(heard, []); - } - - if (outcome.InterruptedAfter is null && outcome.Failure is null) - { - return new TranscriptEntry(heard, [.. response.Messages]); - } - - // The transcript holds what the caller heard. A run that stopped mid-round would - // otherwise leave a tool call with no result behind, and the next turn would send - // it. So the pairs that finished are kept and only an unpaired call is dropped: a - // side effect that ran must stay visible to the next turn. livekit/agents fixed the - // same defect in issue 3702. - List written = [.. TurnMessages.FinishedToolMessages(response.Messages)]; - if (heard is not null) - { - written.Add(heard); - } - - return new TranscriptEntry(heard, written); - } - - // The extractor's deadline is here and not on the whole turn, because the raise of the turn's - // events and the stage advance must always run. - private async Task ExtractAsync(ConversationTurn turn, AgentResponse response, CancellationToken cancellationToken) - { - string? extractionFailure; - - using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - deadline.CancelAfter(ConversationSession.TurnCompletionTimeout); - try - { - extractionFailure = await _session.Writers.ExtractAsync(turn, response, deadline.Token).ConfigureAwait(false); - } - catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) - { - extractionFailure = ConversationSession.ExtractionTimedOutReason; - } - - if (extractionFailure is not null) - { - // Section 8.7, row two: leave the slots unchanged, report once for the turn, and continue - // the conversation. State extraction must never drop a conversation. The reason rides on the event - // because the line an operator reads is the same one the turn loop used to write itself. - _session.Events.RaiseDiagnostic( - ConversationEventKind.ExtractionFailed, - _session.Time.GetUtcNow(), - turn.Index, - payload: new Dictionary(StringComparer.Ordinal) - { - [ConversationEventPayloadKeys.Reason] = extractionFailure, - }); - } - - return extractionFailure; - } - - private string AdvanceStage(ConversationTurn turn) - { - if (_session.Policy is null) - { - return turn.StageBefore; - } - - var stageAfter = _session.Policy.Advance(_session.State.Snapshot()); - _session.State.Stage = stageAfter; - _session.IsComplete = _session.Policy.IsTerminal; - return stageAfter; - } - - /// Reads the closed outcome value of one finished turn. - /// The section 8.7 reason, or . - /// The played duration, or . - /// One of the three values the metric attribute takes. - private static string Outcome(string? failure, TimeSpan? interruptedAfter) => (failure, interruptedAfter) switch - { - (not null, _) => AgentCoreTelemetry.OutcomeFailed, - (_, not null) => AgentCoreTelemetry.OutcomeInterrupted, - _ => AgentCoreTelemetry.OutcomeCompleted, - }; - - /// Reads the approval requests one finished turn still waits on. - /// What the agent answered. - /// One entry per request content, oldest first; empty when the turn asked nothing. - private static List ApprovalRequestsOf(AgentResponse response) - { - List approvals = []; - foreach (var request in response.Messages - .SelectMany(message => message.Contents) - .OfType()) - { - if (request.ToolCall is not FunctionCallContent call) - { - continue; - } - - approvals.Add(new PendingApproval( - request.RequestId, - call.Name, - JsonSerializer.SerializeToElement( - call.Arguments ?? new Dictionary(StringComparer.Ordinal)))); - } - - return approvals; - } - - /// Reports calls the model named that no tool answered. - /// The turn that just ran. - /// What the agent answered. - private void ReportUndeclaredToolCalls(ConversationTurn turn, AgentResponse response) - { - var invoked = new HashSet(turn.Results.CallIds, StringComparer.Ordinal); - - foreach (var call in response.Messages - .SelectMany(message => message.Contents) - .OfType() - .Where(call => !invoked.Contains(call.CallId))) - { - _session.Events.RaiseToolFailure(turn.Index, new ToolFailure - { - ToolName = call.Name, - ToolCallId = call.CallId, - Kind = ToolFailureKind.Undeclared, - Message = $"the model called '{call.Name}', and no such tool is declared.", - }); - } - } -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs deleted file mode 100644 index 82712cbc..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnRunner.cs +++ /dev/null @@ -1,313 +0,0 @@ -using System.Diagnostics; -using System.Globalization; -using AgentCore.Application.Diagnostics; -using AgentCore.Application.Knowledge; -using AgentCore.Application.Runtime.Turn; -using AgentCore.Application.State; -using AgentCore.Domain; -using AgentCore.Domain.Audit; -using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationTurnRunner -{ - private readonly ConversationSession _session; - - private (string ToolId, IReadOnlyList Tools)? _delegatedTools; - - private bool _hasScreen; - - private TimeZoneInfo? _timeZone; - - internal ConversationTurnRunner(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// - /// Gives the runs this conversation delegates through one tool a set of tools of their own. - /// - /// The kind: agent tool whose delegated runs are offered these. - /// The tools. An empty list offers nothing, exactly as never calling this does. - /// An argument is . - internal void SetDelegatedTools(string delegatingToolId, IReadOnlyList tools) - { - ArgumentNullException.ThrowIfNull(delegatingToolId); - ArgumentNullException.ThrowIfNull(tools); - - _delegatedTools = (delegatingToolId, tools); - } - - /// - /// Gives this conversation the screen its tools draw on, or takes it away. - /// - internal void SetHasScreen(bool hasScreen) => _hasScreen = hasScreen; - - /// - /// Tells this conversation which zone the person is in, so the clock line reads their date. - /// - internal void SetTimeZone(TimeZoneInfo zone) => _timeZone = zone; - - /// Runs one turn of the conversation against the session the conversation holds. - /// What the caller said or answered. - /// Where the turn hangs, or null for a caller that does not say. - /// Cancels the turn. - /// What the turn did. - internal async Task RunTurnCoreAsync( - ChatMessage userInput, ConversationTurnOrigin? origin, CancellationToken cancellationToken) - { - var session = await _session.Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); - - await AdmitTurnAsync(session, origin, cancellationToken).ConfigureAwait(false); - var turn = BeginTurn(userInput, session, origin); - - var cancellation = _session.Interruptions.StartRun(cancellationToken); - - try - { - var invocation = TurnInvocationOf(turn); - - var runSession = await OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); - - TurnRegistry.Set(runSession, invocation); - - AgentResponse response; - string? toolFault = null; - - try - { - response = await turn.Agent - .RunAsync( - turn.Request, - runSession, - invocation.RunOptions(), - cancellationToken: cancellation.Token) - .ConfigureAwait(false); - } - catch (Exception exception) when (exception is not OperationCanceledException) - { - toolFault = exception.Message; - response = new AgentResponse(); - } - - return await _session.Completion.CompleteTurnAsync(turn, response, toolFault, ConversationTurnStream.ReadDisposition(response), cancellationToken) - .ConfigureAwait(false); - } - finally - { - _session.Interruptions.EndRun(cancellation); - turn.Activity?.Dispose(); - } - } - - /// - /// Admits one turn: refuses a terminal or running conversation, then withdraws whatever the turn - /// replaces. follows, from the same frame. - /// - /// The session of this conversation. - /// Where the turn hangs, or null for a caller that does not say. - /// Cancels the withdrawal. - internal async ValueTask AdmitTurnAsync(AgentSession session, ConversationTurnOrigin? origin, CancellationToken cancellationToken) - { - if (_session.IsComplete) - { - throw new InvalidOperationException( - $"The conversation '{_session.ConversationId}' reached the terminal stage '{_session.Stage}', so it runs no further turn."); - } - - if (!_session.Interruptions.TryEnterTurn()) - { - throw new InvalidOperationException( - $"A turn of the conversation '{_session.ConversationId}' is still running. One conversation runs one turn at a time."); - } - - try - { - _session.Clarifications.BeginTurn(); - - await WithdrawSupersededAsync(session, origin, cancellationToken).ConfigureAwait(false); - } - catch - { - _session.Interruptions.ReleaseTurn(); - - throw; - } - } - - /// - /// Picks the agent, builds the model input, and takes the turn admitted. - /// Synchronous on purpose: the turn span it opens must be the ambient activity of the caller's - /// frame, and an async method hands no back. - /// - /// What the caller said or answered: words, an approval answer, or both. - /// The session of this conversation. - /// Where the turn hangs, or null for a caller that does not say. - /// Everything the rest of the turn needs. - internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, ConversationTurnOrigin? origin = null) - { - Activity? activity = null; - try - { - var agent = ResolveAgent(); - - var reminder = _session.Policy is null ? null : UnfilledSlotReminder.Build(_session.State, _session.Policy.CurrentStage); - - ChatMessage spoken = userInput; - - _session.History.BeginTurn(session, _session.State.TurnIndex); - - List request; - if (_session.SessionCarriesHistory || _session.ReusesGraphSession) - { - request = [spoken]; - } - else if (TurnMessages.GraphHistory(_session.History.Read(session)) is { } rendered) - { - request = [rendered, spoken]; - } - else - { - request = [spoken]; - } - - activity = AgentCoreTelemetry.StartTurn(_session.ConversationId, _session.State.TurnIndex, _session.State.Stage); - - var knowledge = StateKnowledgeScope.Compose( - _session.State, _session.Compiled.Configuration.Providers?.Knowledge?.Scope, _session.Scope); - - if (knowledge is { Origins.Count: > 0 }) - { - Log.KnowledgeScopeComposed(_session.Logger, _session.ConversationId, _session.State.TurnIndex, knowledge.Origins); - } - - return new ConversationTurn( - agent, - session, - request, - spoken, - reminder, - _session.State.Stage, - _session.State.TurnIndex, - activity, - _session.Time.GetTimestamp(), - _hasScreen ? new TurnRenders() : null, - new TurnSources(), - new TurnResults(), - new TurnFiles(), - knowledge, - origin?.MessageId); - } - catch - { - activity?.Dispose(); - - _session.Interruptions.ReleaseTurn(); - - throw; - } - } - - /// Takes back everything the conversation said after the message this turn hangs off. - internal async ValueTask WithdrawSupersededAsync(AgentSession session, ConversationTurnOrigin? origin, CancellationToken cancellationToken) - { - if (origin is not { NamesParent: true }) - { - return; - } - - var cut = _session.History.CanTruncateFrom(session, origin.ParentMessageId) - ? _session.History.TruncateFrom(session, origin.ParentMessageId) - : await _session.Ledger.CutUnderSummaryAsync(session, origin.ParentMessageId, cancellationToken).ConfigureAwait(false); - - if (cut is not { } withdrawn) - { - return; - } - - _session.Clarifications.Withdraw(); - - _ = _session.Events.Raise( - ConversationEventKind.TurnSuperseded, - _session.Time.GetUtcNow(), - _session.State.TurnIndex, - payload: new Dictionary(StringComparer.Ordinal) - { - [AuditPayloadKeys.WithdrewFromTurnIndex] = - withdrawn.First.ToString(CultureInfo.InvariantCulture), - [AuditPayloadKeys.WithdrewThroughTurnIndex] = - withdrawn.Last.ToString(CultureInfo.InvariantCulture), - }); - } - - /// Picks the agent that speaks this turn. - /// The agent. - internal AIAgent ResolveAgent() - { - if (_session.Policy is null) - { - return _session.Compiled.TurnAgent; - } - - if (_session.Policy.CurrentAgentId is not { Length: > 0 } - || _session.Compiled.TurnAgentForStage(_session.Policy.Stage) is not { } agent) - { - throw new InvalidOperationException( - $"The stage '{_session.Policy.Stage}' of the conversation '{_session.ConversationId}' names no agent, so no turn can run."); - } - - return agent; - } - - /// - /// Reads the session one run is handed. - /// - /// The turn about to run. - /// Cancels the open. - /// The conversation's session on rows 1 and 2, the conversation's shared workflow session on a graph row that reuses one, and a fresh workflow session on any other graph row. - internal async ValueTask OpenRunAsync(ConversationTurn turn, CancellationToken cancellationToken) - { - if (_session.SessionCarriesHistory) - { - return turn.Session; - } - - if (_session.ReusesGraphSession) - { - return _session.GraphSession ??= await turn.Agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - } - - return await turn.Agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - } - - /// Builds the invocation one turn hands its tools. - /// The turn about to run. - /// Everything a tool of this turn may need, as one explicit value. - internal TurnInvocation TurnInvocationOf(ConversationTurn turn) - => new() - { - ConversationId = _session.ConversationId, - TurnIndex = turn.Index, - Stage = turn.StageBefore, - Instructions = turn.Reminder, - TimeZone = _timeZone, - Workspace = _session.Workspace, - Shells = _session.Shells, - Knowledge = turn.Knowledge, - Clarifications = _session.Clarifications, - CarriesHistory = _session.SessionCarriesHistory, - Logger = _session.Logger, - Screen = turn.Renders, - Sources = turn.Sources, - Renders = turn.Renders, - Results = turn.Results, - Files = turn.Files, - OnToolFailure = failure => _session.Events.RaiseToolFailure(turn.Index, failure), - Tools = _delegatedTools?.Tools, - ToolsFor = _delegatedTools?.ToolId, - State = _session.State, - }; -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs deleted file mode 100644 index 58b750f4..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnStream.cs +++ /dev/null @@ -1,152 +0,0 @@ -using System.Runtime.CompilerServices; -using AgentCore.Application.Runtime.Turn; -using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationTurnStream -{ - private readonly ConversationSession _session; - - internal ConversationTurnStream(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// Streams one turn of the conversation against the session the conversation holds. - /// What the caller said or answered. - /// Where the turn hangs, or null for a caller that does not say. - /// Cancels the model calls. - /// The reply, one update at a time. - internal IAsyncEnumerable RunTurnStreamingCoreAsync( - ChatMessage userInput, - ConversationTurnOrigin? origin, - CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(userInput); - - return RunTurnStreamingIteratorAsync(userInput, origin, cancellationToken); - } - - /// Streams one turn. The caller checks the arguments. - private async IAsyncEnumerable RunTurnStreamingIteratorAsync( - ChatMessage userInput, - ConversationTurnOrigin? origin, - [EnumeratorCancellation] CancellationToken cancellationToken) - { - var session = await _session.Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); - - await _session.Runner.AdmitTurnAsync(session, origin, cancellationToken).ConfigureAwait(false); - var turn = _session.Runner.BeginTurn(userInput, session, origin); - - // A streaming turn becomes audible only once it hands the host its first piece of content. - // Until then nothing of it has reached the caller, and a barge-in belongs elsewhere. - var cancellation = _session.Interruptions.StartRun(cancellationToken); - try - { - List updates = []; - string? toolFault = null; - - var invocation = _session.Runner.TurnInvocationOf(turn); - var runSession = await _session.Runner.OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); - - TurnRegistry.Set(runSession, invocation); - - var stream = turn.Agent - .RunStreamingAsync( - turn.Request, - runSession, - invocation.RunOptions(), - cancellationToken: cancellation.Token) - .GetAsyncEnumerator(cancellation.Token); - - try - { - while (true) - { - AgentResponseUpdate update; - - try - { - if (!await stream.MoveNextAsync().ConfigureAwait(false)) - { - break; - } - - update = stream.Current; - } - catch (OperationCanceledException) when (_session.Interruptions.CurrentInterruption() is not null) - { - break; - } - catch (Exception exception) when (exception is not OperationCanceledException) - { - toolFault = exception.Message; - - break; - } - - updates.Add(update); - - var content = update.AsChatResponseUpdate(); - if (TurnMessages.CarriesContent(content) && Speaks(update)) - { - _session.Interruptions.RunIsAudible = true; - - yield return content; - } - } - } - finally - { - await stream.DisposeAsync().ConfigureAwait(false); - } - - _ = await _session.Completion.CompleteTurnAsync( - turn, updates.ToAgentResponse(), toolFault, ReadDisposition(updates), cancellationToken) - .ConfigureAwait(false); - } - finally - { - _session.Interruptions.EndRun(cancellation); - turn.Activity?.Dispose(); - } - } - - /// Reads whether the caller hears the node that produced one update. - /// One update of the run. - /// when the host should speak it. - internal bool Speaks(AgentResponseUpdate update) - => _session.Compiled.SpokenBy is not { } spoken - || (update.AuthorName is { } author && spoken.Contains(author)) - || update.AdditionalProperties?.Contains() is true; - - /// Reads what the turn layers reported about one finished turn. - /// What the agent answered. - /// The disposition, or when no layer marked the turn. - internal static TurnDisposition? ReadDisposition(AgentResponse response) - => response.AdditionalProperties is { } properties - && properties.TryGetValue(out var disposition) - ? disposition - : null; - - /// Reads what the turn layers reported across the updates of one streaming turn. - /// Every update the run produced, in order, before the seam filtered them. - /// The disposition, or when no update carried one. - internal static TurnDisposition? ReadDisposition(List updates) - { - TurnDisposition? found = null; - foreach (var update in updates) - { - if (update.AdditionalProperties is { } properties - && properties.TryGetValue(out var disposition)) - { - found = disposition; - } - } - - return found; - } -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnWriters.cs b/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnWriters.cs deleted file mode 100644 index c4292ca0..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ConversationTurnWriters.cs +++ /dev/null @@ -1,78 +0,0 @@ -using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.State; -using AgentCore.Application.Tools; -using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -internal sealed class ConversationTurnWriters -{ - private readonly ConversationSession _session; - - internal ConversationTurnWriters(ConversationSession session) - { - ArgumentNullException.ThrowIfNull(session); - _session = session; - } - - /// Runs the extractor against the finished turn. - /// The turn that just spoke. - /// What the agent answered. - /// Cancels the model call. - /// The reason the extractor produced nothing, or . - internal async Task ExtractAsync(ConversationTurn turn, AgentResponse response, CancellationToken cancellationToken) - { - if (_session.Extractor is null || _session.Compiled.Configuration.Extractor is not { When: ExtractorTrigger.AfterReply }) - { - return null; - } - - // The extractor reads the finished turn and, in front of it, the last thing the agent said - // before the caller spoke. A caller answering a question — "the ENT one", "yes", "the second - // one" — cannot be read without the question, and the state document cannot carry it because - // nothing was written yet. The rest of the conversation stays out: the document already carries every - // earlier answer. Measured 2026-09-02: with the question in view every such answer resolved, - // and a turn where only the agent had named a machine still filled nothing. - List finished = [turn.Spoken, .. response.Messages]; - if (_session.Transcript.LastOrDefault(message => message.Role == ChatRole.Assistant && message.Text.Length > 0) is { } asked) - { - finished.Insert(0, asked); - } - - // A failed extraction never drops the turn. The result carries the reason instead. - var result = await _session.Extractor.ExtractAsync(_session.State, finished, _session.Clarifications, cancellationToken) - .ConfigureAwait(false); - - return result.Failure; - } - - /// Fills every tool-written slot from the tool results of one turn. - /// The messages the agent produced, oldest first. - internal void ApplyToolResults(IEnumerable messages) - { - // The name a call carries is the declared tool id, because the compile table names every - // function after the tools: entry it built. - ToolCallNames names = new(); - - foreach (var message in messages) - { - foreach (var content in message.Contents) - { - switch (content) - { - case FunctionCallContent conversation: - names.Called(conversation); - break; - - case FunctionResultContent result when names.Of(result) is { } toolId: - ToolStateWriter.Apply(_session.State, toolId, ToolResultJson.ToNode(result.Result)); - break; - - default: - break; - } - } - } - } -} diff --git a/src/AgentCore.Application/Runtime/ConversationSession/ReplyOutcome.cs b/src/AgentCore.Application/Runtime/ConversationSession/ReplyOutcome.cs deleted file mode 100644 index 8349c4b3..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/ReplyOutcome.cs +++ /dev/null @@ -1,18 +0,0 @@ -using AgentCore.Domain; - -namespace AgentCore.Application.Runtime; - -/// What the turn said, what the caller heard, and why they differ if they do. -/// The text the record holds: what the caller heard. -/// The text the model produced, before any barge-in cut it. -/// The section 8.7 reason, or . -/// The row-six fault, from the run or from the fallback layer. -/// The played duration of a cut reply, or . -/// The tool calls still waiting on a human answer. -internal sealed record ReplyOutcome( - string Reply, - string SpokenReply, - string? Failure, - string? ToolFault, - TimeSpan? InterruptedAfter, - List Approvals); diff --git a/src/AgentCore.Application/Runtime/ConversationSession/TranscriptEntry.cs b/src/AgentCore.Application/Runtime/ConversationSession/TranscriptEntry.cs deleted file mode 100644 index 5bd3cb59..00000000 --- a/src/AgentCore.Application/Runtime/ConversationSession/TranscriptEntry.cs +++ /dev/null @@ -1,8 +0,0 @@ -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Runtime; - -/// What this turn adds to the transcript. -/// The assistant message the caller heard, or when nothing was. -/// Every message store 0 appends after the caller's own; empty for rows 3 and 4. -internal sealed record TranscriptEntry(ChatMessage? Heard, List Written); diff --git a/src/AgentCore.Application/Runtime/ConversationSessionFactory.cs b/src/AgentCore.Application/Runtime/ConversationSessionFactory.cs index 3e2f4080..67b40d61 100644 --- a/src/AgentCore.Application/Runtime/ConversationSessionFactory.cs +++ b/src/AgentCore.Application/Runtime/ConversationSessionFactory.cs @@ -6,84 +6,85 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime; - -/// -/// Builds one for each conversation, over one compiled agent. -/// -public sealed class ConversationSessionFactory : IConversationSessionFactory +namespace AgentCore.Application.Runtime { - private readonly ConversationSessionSeams _seams; - - private readonly IConversationObserver[] _observers; - - private readonly string? _workspaceRoot; - /// - /// Creates the factory. When is bound, every conversation this factory - /// builds gets its own folder under it; unbound, a session it builds has no workspace. + /// Builds one for each conversation, over one compiled agent. /// - public ConversationSessionFactory( - CompiledAgent compiled, - IGuardEvaluator guards, - StateExtractor? extractor = null, - TimeProvider? timeProvider = null, - ILogger? logger = null, - IEnumerable? observers = null, - string? workspaceRoot = null) + public sealed class ConversationSessionFactory : IConversationSessionFactory { - ArgumentNullException.ThrowIfNull(compiled); - ArgumentNullException.ThrowIfNull(guards); + private readonly ConversationSessionSeams _seams; - _seams = new ConversationSessionSeams(compiled, guards, extractor, timeProvider ?? TimeProvider.System, logger); - _workspaceRoot = workspaceRoot; + private readonly IConversationObserver[] _observers; - // Copied, not held: the list is the caller's, and a caller that keeps adding to it after this - // must not change what a session already built. The order is the caller's too — see - // ConversationObservers.Standard, which is where the cost of that order is argued. - _observers = observers is null ? [] : [.. observers]; - } + private readonly string? _workspaceRoot; - /// Builds the extractor one document declares. - /// The compiled agent. - /// The seam that resolves extractor.model. - /// The extractor, or when the document declares none. - public static StateExtractor? CreateExtractor(CompiledAgent compiled, IChatClientFactory chatClients) - { - ArgumentNullException.ThrowIfNull(compiled); - ArgumentNullException.ThrowIfNull(chatClients); + /// + /// Creates the factory. When is bound, every conversation this factory + /// builds gets its own folder under it; unbound, a session it builds has no workspace. + /// + public ConversationSessionFactory( + CompiledAgent compiled, + IGuardEvaluator guards, + StateExtractor? extractor = null, + TimeProvider? timeProvider = null, + ILogger? logger = null, + IEnumerable? observers = null, + string? workspaceRoot = null) + { + ArgumentNullException.ThrowIfNull(compiled); + ArgumentNullException.ThrowIfNull(guards); - return compiled.Configuration.Extractor is { } declared - ? new StateExtractor( - compiled.Configuration, - chatClients.GetChatClient(declared.Model) - .AsBuilder() - .UseOpenTelemetry(configure: static client => client.EnableSensitiveData = false) - .Use(static innerClient => new ModelFacingChatClient(innerClient)) - .Build()) - : null; - } + _seams = new ConversationSessionSeams(compiled, guards, extractor, timeProvider ?? TimeProvider.System, logger); + _workspaceRoot = workspaceRoot; - /// - public ConversationSession Create(string? conversationId = null, ConversationSessionState? state = null) - { - var resolvedConversationId = string.IsNullOrWhiteSpace(conversationId) ? Guid.NewGuid().ToString("N") : conversationId; + // Copied, not held: the list is the caller's, and a caller that keeps adding to it after this + // must not change what a session already built. The order is the caller's too — see + // ConversationObservers.Standard, which is where the cost of that order is argued. + _observers = observers is null ? [] : [.. observers]; + } - var workspace = _workspaceRoot is null ? null : ConversationWorkspace.Create(_workspaceRoot, resolvedConversationId); + /// Builds the extractor one document declares. + /// The compiled agent. + /// The seam that resolves extractor.model. + /// The extractor, or when the document declares none. + public static StateExtractor? CreateExtractor(CompiledAgent compiled, IChatClientFactory chatClients) + { + ArgumentNullException.ThrowIfNull(compiled); + ArgumentNullException.ThrowIfNull(chatClients); - ConversationSession session = new( - resolvedConversationId, - _seams, - new ConversationObserverDispatcher(_observers, _seams.Logger), - workspace); + return compiled.Configuration.Extractor is { } declared + ? new StateExtractor( + compiled.Configuration, + chatClients.GetChatClient(declared.Model) + .AsBuilder() + .UseOpenTelemetry(configure: static client => client.EnableSensitiveData = false) + .Use(static innerClient => new ModelFacingChatClient(innerClient)) + .Build()) + : null; + } - // Named, not applied. The session resumes on its first turn, where store 0's own copy - // outranks this one — see the remarks on ConversationSession.Resume. - if (state is not null) + /// + public ConversationSession Create(string? conversationId = null, ConversationSessionState? state = null) { - session.Resume(state); - } + string resolvedConversationId = string.IsNullOrWhiteSpace(conversationId) ? Guid.NewGuid().ToString("N") : conversationId; - return session; + ConversationWorkspace? workspace = _workspaceRoot is null ? null : ConversationWorkspace.Create(_workspaceRoot, resolvedConversationId); + + ConversationSession session = new( + resolvedConversationId, + _seams, + new ConversationObserverDispatcher(_observers, _seams.Logger), + workspace); + + // Named, not applied. The session resumes on its first turn, where store 0's own copy + // outranks this one — see the remarks on ConversationSession.Resume. + if (state is not null) + { + session.Resume(state); + } + + return session; + } } } diff --git a/src/AgentCore.Application/Runtime/ConversationSessionLifetime.cs b/src/AgentCore.Application/Runtime/ConversationSessionLifetime.cs new file mode 100644 index 00000000..37261653 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationSessionLifetime.cs @@ -0,0 +1,86 @@ +using AgentCore.Application.Runtime.Harness; +using AgentCore.Domain.Audit; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationSessionLifetime + { + private readonly ConversationSession _session; + + // The background release runs once per conversation: both DisposeAsync and the turn-end path reach + // it, and a second release would re-cancel children that already went away. + private int _backgroundReleased; + + internal ConversationSessionLifetime(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// Closes the conversation, and writes the last event of its chain. + /// Why the conversation ended, as one member of the closed set. + /// + /// when this conversation wrote the event, and when the + /// conversation had already ended. + /// + /// + /// is not a member of the closed set. + /// + internal bool EndConversation(ConversationEndReason reason) + { + // The event is written before the flag moves. A value outside the closed set therefore ends + // no conversation and writes nothing. + bool wrote = _session.Events.EndConversation(reason, _session.Time.GetUtcNow()); + _session.IsComplete = true; + DeleteWorkspace(); + return wrote; + } + + /// + /// Deletes this conversation's workspace, if it has one. Called once the chain has recorded why the + /// conversation ended, from every path that can end it. + /// + internal void DeleteWorkspace() + { + _session.WorkspaceRoot?.Delete(_session.Logger); + } + + /// + /// Disposes this conversation's background sessions and shell executors. Idempotent: a session already + /// disposed, or one that never had either, disposes nothing. + /// + internal async ValueTask DisposeAsync() + { + await ReleaseBackgroundSessionsAsync().ConfigureAwait(false); + await DisposeShellsAsync().ConfigureAwait(false); + } + + /// + /// Cancels the background children still running on this conversation's session and releases it, once + /// per conversation. Skipped when the conversation never opened a session or the document names no background + /// children. Release precedes the shells: a child cancelled here may be inside a shell tool. + /// + internal async ValueTask ReleaseBackgroundSessionsAsync() + { + if (Interlocked.Exchange(ref _backgroundReleased, 1) == 1 + || _session.Compiled.BackgroundProviders.Count == 0 + || _session.Ledger.Session() is not { } session) + { + return; + } + + await BackgroundSessionRelease.ReleaseAsync( + _session.Compiled.BackgroundProviders, session, _session.ConversationId, _session.Logger, CancellationToken.None).ConfigureAwait(false); + } + + /// + /// Disposes this conversation's shell executors, if it has any. does not conversation + /// this: a tool that ends the conversation mid-turn still needs the shell for the rest of that turn, so + /// only the turn-end path and tear it down. + /// + internal ValueTask DisposeShellsAsync() + { + return _session.Shells?.DisposeAsync() ?? ValueTask.CompletedTask; + } + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationSessionSeams.cs b/src/AgentCore.Application/Runtime/ConversationSessionSeams.cs index 0d211e64..3471278e 100644 --- a/src/AgentCore.Application/Runtime/ConversationSessionSeams.cs +++ b/src/AgentCore.Application/Runtime/ConversationSessionSeams.cs @@ -3,17 +3,18 @@ using AgentCore.Application.State; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime; - -/// What every session one factory builds shares: the entry, and the seams it runs on. -/// The compiled entry every conversation runs. -/// The evaluator that runs each exit guard. -/// The state extractor the document declares, or . -/// The clock every turn reads. -/// Where the session's own log events go, or for none. -internal sealed record ConversationSessionSeams( - CompiledAgent Compiled, - IGuardEvaluator Guards, - StateExtractor? Extractor, - TimeProvider Time, - ILogger? Logger); +namespace AgentCore.Application.Runtime +{ + /// What every session one factory builds shares: the entry, and the seams it runs on. + /// The compiled entry every conversation runs. + /// The evaluator that runs each exit guard. + /// The state extractor the document declares, or . + /// The clock every turn reads. + /// Where the session's own log events go, or for none. + internal sealed record ConversationSessionSeams( + CompiledAgent Compiled, + IGuardEvaluator Guards, + StateExtractor? Extractor, + TimeProvider Time, + ILogger? Logger); +} diff --git a/src/AgentCore.Application/Runtime/ConversationSessionStateStore.cs b/src/AgentCore.Application/Runtime/ConversationSessionStateStore.cs new file mode 100644 index 00000000..2765ab0a --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationSessionStateStore.cs @@ -0,0 +1,137 @@ +using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Conversation; +using AgentCore.Application.Runtime.Harness; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationSessionStateStore + { + private readonly ConversationSession _session; + + internal ConversationSessionStateStore(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// Puts back what a previous session of this conversation had, as far as the document still allows. + internal void Restore(ConversationSessionState stored) + { + if (stored.Version != ConversationSessionState.CurrentVersion) + { + Dropped($"the stored state is version {stored.Version} and this build writes {ConversationSessionState.CurrentVersion}."); + return; + } + + string? refusedStage = null; + + if (_session.Policy is null) + { + if (stored.Stage.Length > 0) + { + refusedStage = $"the entry declares no policy, so the stage '{stored.Stage}' has nowhere to go."; + } + } + else if (!_session.Policy.Declares(stored.Stage)) + { + refusedStage = $"the document no longer declares the stage '{stored.Stage}'."; + } + + if (refusedStage is null) + { + _session.Policy?.RestoreStage(stored.Stage); + + _session.State.Stage = stored.Stage; + + _session.IsComplete = stored.IsComplete; + } + else + { + Dropped(refusedStage); + } + + _session.Clarifications.RestoreSpent(stored.Clarifications); + + foreach (KeyValuePair slot in stored.Slots) + { + if (ReservedStateSlots.Contains(slot.Key)) + { + Dropped($"the slot '{slot.Key}' is reserved, and a reserved slot is never restored."); + + continue; + } + + if (_session.State.TryWrite(slot.Key, slot.Value?.DeepClone())) + { + continue; + } + + Dropped( + _session.State.Configuration.State.ContainsKey(slot.Key) + ? $"the slot '{slot.Key}' no longer takes the value it was stored with." + : $"the document no longer declares the slot '{slot.Key}'."); + } + + void Dropped(string reason) + { + _session.Events.RaiseDiagnostic( + ConversationEventKind.StateRestorePartial, + _session.Time.GetUtcNow(), + turnIndex: null, + payload: new Dictionary(StringComparer.Ordinal) + { + [ConversationEventPayloadKeys.Reason] = reason, + }); + } + } + + /// + /// Reads the state this conversation would resume from, as it stands right now. The provider state is + /// read off the live bag with no turn lock around it, so a host serializing mid-turn gets the + /// bag as it stands at that instant, not a turn-boundary snapshot. A graph row that reuses + /// its session instead attaches that session's last turn-end serialization. + /// + internal ConversationSessionState Snapshot() + { + lock (_session.InterruptLock) + { + if (_session.AgentSession is null && _session.Checkpoint is { } held) + { + return held; + } + } + + return new() + { + Stage = _session.State.Stage, + IsComplete = _session.IsComplete, + Slots = _session.State.WrittenSlots(), + NextTurnIndex = _session.State.TurnIndex, + Clarifications = _session.Clarifications.Spent(), + Providers = HarnessSessionState.Capture(_session.AgentSession, _session.Compiled.HarnessStateKeys), + WorkflowState = _session.GraphBlob, + }; + } + + /// Names the state this conversation resumes from when store 0 holds none of its own. + internal void Resume(ConversationSessionState stored) + { + ArgumentNullException.ThrowIfNull(stored); + + lock (_session.InterruptLock) + { + if (_session.AgentSession is not null) + { + throw new InvalidOperationException( + $"The conversation '{_session.ConversationId}' has already run a turn, and a conversation resumes only as its " + + "first turn opens it. Hand the state to the factory that builds the session " + + "instead."); + } + + _session.Checkpoint = stored; + } + } + } + +} diff --git a/src/AgentCore.Application/Runtime/ConversationTranscriptLedger.cs b/src/AgentCore.Application/Runtime/ConversationTranscriptLedger.cs new file mode 100644 index 00000000..e6e07502 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTranscriptLedger.cs @@ -0,0 +1,219 @@ +using AgentCore.Application.Conversation; +using AgentCore.Application.Diagnostics; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime.Harness; +using AgentCore.Application.Transcript; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationTranscriptLedger + { + private readonly ConversationSession _session; + + internal ConversationTranscriptLedger(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// + /// Opens the session of this conversation, once, and re-syncs it with store 0 before handing it to every + /// later turn. + /// + /// Cancels the open. + /// The session. + internal async ValueTask OpenSessionAsync(CancellationToken cancellationToken) + { + if (Session() is { } opened) + { + await ResyncTranscriptAsync(opened, cancellationToken).ConfigureAwait(false); + return opened; + } + + ConversationRecord record = await _session.Compiled.ConversationStore.CreateAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); + + ConversationSessionState? checkpoint; + lock (_session.InterruptLock) + { + checkpoint = _session.Checkpoint; + } + + ConversationSessionState? stored = record.State ?? checkpoint; + + AgentSession session; + if (_session.SessionCarriesHistory) + { + session = stored is { Version: ConversationSessionState.CurrentVersion, Providers.Count: > 0 } + ? await _session.Compiled.TurnAgent.DeserializeSessionAsync( + HarnessSessionState.Wrap(stored.Providers), cancellationToken: cancellationToken).ConfigureAwait(false) + : await _session.Compiled.TurnAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); + } + else + { + session = new ConversationHistorySession(); + + if (_session.ReusesGraphSession) + { + _session.GraphSession = stored is { Version: ConversationSessionState.CurrentVersion, WorkflowState: { } blob } + ? await _session.Compiled.TurnAgent.DeserializeSessionAsync(blob, cancellationToken: cancellationToken).ConfigureAwait(false) + : await _session.Compiled.TurnAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); + } + } + + IReadOnlyList spoken = record.LastMessageAt is null + ? [] + : await _session.Compiled.ConversationStore.ReadForSessionAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); + + lock (_session.InterruptLock) + { + if (_session.AgentSession is null) + { + _session.AgentSession = session; + + _session.State.TurnIndex = _session.History.BeginConversation( + session, + _session.ConversationId, + spoken, + _session.Events.RaiseDroppedTranscriptWrite, + new TranscriptMarks(record.NextOrdinal, stored?.NextTurnIndex ?? 0)); + + if (stored is { } s) + { + _session.States.Restore(s); + } + } + + return _session.AgentSession; + } + } + + /// + /// Brings the session's words back in line with store 1 before a turn after the first, when and + /// only when someone else wrote to the conversation in between. + /// + /// The session of this conversation. + /// Cancels the reads. + private async ValueTask ResyncTranscriptAsync(AgentSession opened, CancellationToken cancellationToken) + { + await _session.History.DrainAsync(opened).ConfigureAwait(false); + + try + { + ConversationRecord refreshed = await RecordAsync("resync against", cancellationToken).ConfigureAwait(false); + + if (refreshed.NextOrdinal == _session.History.NextOrdinal(opened)) + { + return; + } + + IReadOnlyList rows = await _session.Compiled.ConversationStore.ReadForSessionAsync( + _session.ConversationId, cancellationToken).ConfigureAwait(false); + + _session.History.Resync(opened, rows, refreshed.NextOrdinal); + } +#pragma warning disable CA1031 // A store that cannot be read never ends a conversation: the turn runs on the words the session holds. + catch (Exception exception) when (exception is not OperationCanceledException) +#pragma warning restore CA1031 + { + Log.TranscriptResyncFailed(_session.Logger, _session.ConversationId, _session.State.TurnIndex, exception); + _session.Events.RaiseFailedTranscriptResync(_session.State.TurnIndex, exception); + } + } + + /// + /// Cuts an edit that reaches under the summary: the parent is a row the summary stands in for, + /// or the edit takes the whole conversation. The caller asks + /// first and comes here when it says no. + /// + /// The session of this conversation. + /// The message the edit hangs off, or for the whole conversation. + /// Cancels the cut. + /// The turns the cut withdrew, or when nothing went. + internal async ValueTask CutUnderSummaryAsync( + AgentSession opened, string? parentMessageId, CancellationToken cancellationToken) + { + IConversationStore store = _session.Compiled.ConversationStore; + + await _session.History.DrainAsync(opened).ConfigureAwait(false); + + int from; + if (parentMessageId is null) + { + from = 0; + } + else if (await store.OrdinalOfAsync(_session.ConversationId, parentMessageId, cancellationToken).ConfigureAwait(false) is { } parent) + { + from = parent + 1; + } + else + { + return null; + } + + ConversationCut cut = await store.TruncateAsync(_session.ConversationId, from, cancellationToken).ConfigureAwait(false); + Log.ConversationTruncated(_session.Logger, _session.ConversationId, from, _session.State.TurnIndex); + + ConversationRecord refreshed = await RecordAsync("edit", cancellationToken).ConfigureAwait(false); + IReadOnlyList rows = await store.ReadForSessionAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false); + + _session.History.Resync(opened, rows, refreshed.NextOrdinal); + + return cut.Turns; + } + + /// Store 0's record of this conversation, which must exist for a session that already opened it. + /// What the session is about to do with it, for the error. + /// Cancels the read. + private async ValueTask RecordAsync(string purpose, CancellationToken cancellationToken) + { + return await _session.Compiled.ConversationStore.GetAsync(_session.ConversationId, cancellationToken).ConfigureAwait(false) + ?? throw new InvalidOperationException( + $"Store 0 holds no conversation '{_session.ConversationId}' for its own session to {purpose}."); + } + + /// + /// Reads the session of this conversation, or null before its first turn opened one. + /// + /// The session. + internal AgentSession? Session() + { + lock (_session.InterruptLock) + { + return _session.AgentSession; + } + } + + /// + /// Waits for every store 1 write this conversation has queued. + /// + /// A task that completes when the words of the conversation are durable. + internal async Task FlushTranscriptAsync() + { + if (Session() is { } session) + { + await _session.History.DrainAsync(session).ConfigureAwait(false); + } + } + + /// Builds the answer message for one queued approval request of this conversation. + /// The id the caller answers. + /// Whether the tool may run. + /// + /// The user message carrying the approval response, or when this conversation + /// queues no request under that id: answered already, another conversation's, or never asked. + /// + internal ChatMessage? TryCreateApprovalAnswer(string requestId, bool approved) + { + ArgumentException.ThrowIfNullOrEmpty(requestId); + + return Session() is { } session + ? PendingApprovalQueue.AnswerFor(session.StateBag.Serialize(), requestId, approved) + : null; + } + + /// The session a graph row's conversation holds, so store 1 has somewhere to live. + private sealed class ConversationHistorySession : AgentSession; + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationTurn.cs b/src/AgentCore.Application/Runtime/ConversationTurn.cs new file mode 100644 index 00000000..27a60e96 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTurn.cs @@ -0,0 +1,29 @@ +using System.Diagnostics; +using AgentCore.Application.Runtime.Turn; +using AgentCore.Domain.Knowledge; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + // The turn's working set, carried from preparation through commit. Built once per turn in + // ConversationTurnRunner.BeginTurn for the same reason Activity is: ConversationTurnStream reopens the state + // scope on every step of a streaming turn, and collectors built per step would lose whatever an + // earlier step drew before a later step could attach it to a message. + internal sealed record ConversationTurn( + AIAgent Agent, + AgentSession Session, + List Request, + ChatMessage Spoken, + string? Reminder, + string StageBefore, + int Index, + Activity? Activity, + long StartedAt, + TurnRenders? Renders, + TurnSources Sources, + TurnResults Results, + TurnFiles Files, + KnowledgeScope? Knowledge, + string? MessageId); +} diff --git a/src/AgentCore.Application/Runtime/ConversationTurnCommit.cs b/src/AgentCore.Application/Runtime/ConversationTurnCommit.cs new file mode 100644 index 00000000..f9e03a88 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTurnCommit.cs @@ -0,0 +1,78 @@ +using AgentCore.Domain; +using AgentCore.Domain.Audit; + +namespace AgentCore.Application.Runtime +{ + /// + /// The publish half of a turn: appends the transcript, writes the turn's events, and tears the + /// conversation down when it is over. decides the turn; this commits it. + /// + internal sealed class ConversationTurnCommit + { + private readonly ConversationSession _session; + + internal ConversationTurnCommit(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + internal TurnResult Publish( + ConversationTurn turn, + ReplyOutcome outcome, + TranscriptEntry addition, + TurnResult result, + ConversationInterruptionTracker.Interruption? interruption) + { + lock (_session.InterruptLock) + { + _session.LastReplyMessageId = _session.SessionCarriesHistory + ? _session.History.AppendTurn( + turn.Session, [turn.Spoken, .. addition.Written], _session.Snapshot(), turn.MessageId) + : _session.History.AppendCallerFacingTurn( + turn.Session, turn.Spoken, addition.Heard, _session.Snapshot(), turn.MessageId); + + Guid completedEventId = _session.Events.WriteTurnEvents(result, outcome.SpokenReply, outcome.ToolFault); + + _session.AmendableEventId = outcome.InterruptedAfter is null ? completedEventId : null; + + _session.LastTurn = result; + + if (interruption is null + && _session.Interruption is { } late + && _session.Interruptions.AmendLastTurn(late) + && _session.LastTurn is { } amended) + { + result = amended; + } + + _session.Interruption = null; + + _session.RunCancellation = null; + + _session.Interruptions.RunIsAudible = false; + } + + return result; + } + + internal async Task EndConversationIfOverAsync(DateTimeOffset endedAt, string stageAfter) + { + if (_session.IsComplete) + { + _ = _session.Events.EndConversation(ConversationEndReason.AgentCompleted, endedAt, stageAfter); + } + + if (!_session.IsComplete && !_session.Events.HasEnded) + { + return; + } + + await _session.Lifetime.ReleaseBackgroundSessionsAsync().ConfigureAwait(false); + + await _session.Lifetime.DisposeShellsAsync().ConfigureAwait(false); + + _session.Lifetime.DeleteWorkspace(); + } + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationTurnCompletion.cs b/src/AgentCore.Application/Runtime/ConversationTurnCompletion.cs new file mode 100644 index 00000000..62ce8a8b --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTurnCompletion.cs @@ -0,0 +1,336 @@ +using System.Text.Json; +using AgentCore.Application.Diagnostics; +using AgentCore.Application.Runtime.Turn; +using AgentCore.Domain; +using AgentCore.Domain.Audit; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationTurnCompletion + { + private readonly ConversationSession _session; + + private readonly ConversationTurnCommit _commit; + + internal ConversationTurnCompletion(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + _commit = new ConversationTurnCommit(session); + } + + /// Runs every writer, then lets the machine pick the stage of the next turn. + /// The turn that just spoke. + /// What the agent answered. + /// + /// The message of the fault that threw out of the run, or when nothing + /// threw. Section 8.7, row six. + /// + /// Cancels the extractor call. + /// The finished turn. + /// + /// What and reported about + /// this turn, or when neither layer marked it. A flagged turn skips the + /// extractor: the words moderation flagged are its only input, and a slot filled from them would + /// carry the flagged content into the state document and into every later prompt. Everything else + /// about a refused turn is ordinary, so the refusal enters the transcript, the stage machine + /// advances, and turn.completed proves the refusal under + /// . + /// + internal async Task CompleteTurnAsync( + ConversationTurn turn, + AgentResponse response, + string? toolFault, + TurnDisposition? disposition, + CancellationToken cancellationToken) + { + // Sweep drain state for tool calls whose round never reached the client's drain: the + // round that ends a turn attaches nothing, so turn-scoped records would otherwise + // leave entries sitting on the shared clients. + turn.Results.Sweep(); + + // Calls the model named that no tool answered never reach the invoking client, so no + // per-call state names them. The turn's own record does: every id the model gave minus + // every id a tool ran under. Reported here, at the same turn end that sweeps the drain. + ReportUndeclaredToolCalls(turn, response); + + ConversationInterruptionTracker.Interruption? interruption = _session.Interruptions.CurrentInterruption(); + + // The moderation facts of this turn, raised before the turn's own events so the flag still + // takes the lower ordinal. The verdict is known before the model runs, which is the one rule + // that separates prompt.flagged from reply.interrupted: it amends nothing. + bool refused = disposition?.Moderation is ModerationOutcome.Flagged; + _session.Events.RaiseModeration(turn.Index, disposition); + + ReplyOutcome outcome = ResolveReply(turn, response, interruption, disposition, toolFault); + TranscriptEntry addition = TranscriptAddition(response, outcome); + + // The per-turn writers run from here, in the order the constructor documents: tool results + // first. + _session.Writers.ApplyToolResults(response.Messages); + + // A refused turn runs no extractor. The words moderation flagged are the extractor's only + // input, so a slot filled from them would carry the flagged content into the state document + // and into every later prompt. The refusal itself says nothing worth extracting either, and + // the extractor costs a model call, so this also spends nothing on a turn nobody answered. + // A pending turn runs none either: the run suspended instead of answering, so there is + // nothing decided to read. + string? extractionFailure = refused || outcome.Approvals.Count > 0 + ? null + : await ExtractAsync(turn, response, cancellationToken).ConfigureAwait(false); + + // The clock fields write next. The clock comes from the injected provider, so a test owns + // it. The same read stamps every audit event of this turn. + DateTimeOffset endedAt = _session.Time.GetUtcNow(); + _session.State.TurnIndex++; + _session.State.ConversationDurationSeconds = (endedAt - _session.StartedAt).TotalSeconds; + + // The counters write last. + _ = _session.Counters.Apply(_session.State); + + string stageAfter = AdvanceStage(turn); + + TurnResult result = new( + _session.ConversationId, + turn.Index, + turn.StageBefore, + stageAfter, + outcome.Reply, + _session.IsComplete, + extractionFailure, + outcome.Failure, + outcome.InterruptedAfter, + endedAt) + { + Approvals = outcome.Approvals, + }; + + // A graph row that reuses its session persists it here, before the commit below reads + // it into store 0: the next turn resumes from these checkpoints, and a resumed conversation + // rebuilds them. Rows 1 and 2 need nothing — their session outlives the conversation. + if (_session.ReusesGraphSession && _session.GraphSession is { } shared) + { + _session.GraphBlob = await turn.Agent.SerializeSessionAsync(shared, cancellationToken: cancellationToken).ConfigureAwait(false); + } + + result = _commit.Publish(turn, outcome, addition, result, interruption); + + AgentCoreTelemetry.EndTurn( + turn.Activity, + _session.Time.GetElapsedTime(turn.StartedAt), + Outcome(result.Failure, result.InterruptedAfter), + stageAfter, + result.Failure); + + await _commit.EndConversationIfOverAsync(endedAt, stageAfter).ConfigureAwait(false); + + return result; + } + + private ReplyOutcome ResolveReply( + ConversationTurn turn, + AgentResponse response, + ConversationInterruptionTracker.Interruption? interruption, + TurnDisposition? disposition, + string? toolFault) + { + // R1 reaches the turn through the fallback layer, and a fault above every chat client — a + // graph that matched no edge — still reaches the catch in the run methods. Both are the + // same row-six fact. + toolFault ??= disposition is { Fallback: FallbackCause.Faulted, FallbackReason: { } caught } + ? caught + : null; + + string reply = SpokenReply.From(response.Messages); + string spokenReply = reply; + TimeSpan? interruptedAfter = null; + string? failure = toolFault is null ? null : ConversationSession.ToolFailureReason + " " + toolFault; + + // The tool calls still waiting on a human answer. A pending turn is not a failure: the + // run suspended instead of answering, so the empty-reply substitution below is skipped, + // the extractor has nothing decided to read, and the requests ride TurnResult to the host. + List approvals = ApprovalRequestsOf(response); + + if (interruption is { } cut) + { + // Item 6a. The record holds the text the caller heard, not the text the model produced. + // A trailing space is not speech, so it is trimmed: pipecat pins the same rule in its + // aggregator test, where the model sent "Hello " and the record holds "Hello". + reply = cut.HeardText.Trim(); + interruptedAfter = cut.PlayedDuration; + } + else if (approvals.Count == 0 && (failure is not null + || string.IsNullOrWhiteSpace(reply) + || disposition?.Fallback is FallbackCause.EmptyReply)) + { + // Section 8.7, last row. A quiet run is silence on a voice conversation, so an empty reply is a + // failure even though nothing threw. + failure ??= ConversationSession.EmptyReplyReason; + reply = _session.Compiled.FallbackReply; + spokenReply = reply; + } + + // Section 8.7, last row, raised once for the turn. It is diagnostic only, so it takes no + // ordinal and no row records it; the turn.completed event of this same turn carries the + // fallback the caller actually heard. The tool fault of row six is raised in + // WriteTurnEvents instead, because the chain stores that one and its row is stamped with + // the same endedAt every other event of the turn carries. + if (toolFault is null && failure is not null) + { + _session.Events.RaiseDiagnostic(ConversationEventKind.EmptyReply, _session.Time.GetUtcNow(), turn.Index); + } + + return new ReplyOutcome(reply, spokenReply, failure, toolFault, interruptedAfter, approvals); + } + + // Built before the writers run and committed at the end of the turn, in one lock with the rest + // of what a late barge-in may still amend: the transcript span, the ordinal the amendment must + // reference, and LastTurn itself. Nothing in between reads the transcript — the extractor reads + // the finished turn, and the writers read the state document — so building it early and + // committing it once costs nothing. + private TranscriptEntry TranscriptAddition(AgentResponse response, ReplyOutcome outcome) + { + // A barge-in inside the first 100 ms leaves no heard text, and an empty assistant message + // teaches the model nothing. pipecat and livekit both guard this. Both row shapes read this + // one value, so what counts as words the caller heard is decided once. + ChatMessage? heard = outcome.Reply.Length > 0 ? new ChatMessage(ChatRole.Assistant, outcome.Reply) : null; + + // Rows 3 and 4 record the caller-facing turn alone, so `written` stays empty for them: a + // node's tool pair and a node's line to the next node are neither said nor heard, and the + // commit takes the heard reply straight. + if (!_session.SessionCarriesHistory) + { + return new TranscriptEntry(heard, []); + } + + if (outcome.InterruptedAfter is null && outcome.Failure is null) + { + return new TranscriptEntry(heard, [.. response.Messages]); + } + + // The transcript holds what the caller heard. A run that stopped mid-round would + // otherwise leave a tool call with no result behind, and the next turn would send + // it. So the pairs that finished are kept and only an unpaired call is dropped: a + // side effect that ran must stay visible to the next turn. livekit/agents fixed the + // same defect in issue 3702. + List written = [.. TurnMessages.FinishedToolMessages(response.Messages)]; + if (heard is not null) + { + written.Add(heard); + } + + return new TranscriptEntry(heard, written); + } + + // The extractor's deadline is here and not on the whole turn, because the raise of the turn's + // events and the stage advance must always run. + private async Task ExtractAsync(ConversationTurn turn, AgentResponse response, CancellationToken cancellationToken) + { + string? extractionFailure; + + using CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + deadline.CancelAfter(ConversationSession.TurnCompletionTimeout); + try + { + extractionFailure = await _session.Writers.ExtractAsync(turn, response, deadline.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + { + extractionFailure = ConversationSession.ExtractionTimedOutReason; + } + + if (extractionFailure is not null) + { + // Section 8.7, row two: leave the slots unchanged, report once for the turn, and continue + // the conversation. State extraction must never drop a conversation. The reason rides on the event + // because the line an operator reads is the same one the turn loop used to write itself. + _session.Events.RaiseDiagnostic( + ConversationEventKind.ExtractionFailed, + _session.Time.GetUtcNow(), + turn.Index, + payload: new Dictionary(StringComparer.Ordinal) + { + [ConversationEventPayloadKeys.Reason] = extractionFailure, + }); + } + + return extractionFailure; + } + + private string AdvanceStage(ConversationTurn turn) + { + if (_session.Policy is null) + { + return turn.StageBefore; + } + + string stageAfter = _session.Policy.Advance(_session.State.Snapshot()); + _session.State.Stage = stageAfter; + _session.IsComplete = _session.Policy.IsTerminal; + return stageAfter; + } + + /// Reads the closed outcome value of one finished turn. + /// The section 8.7 reason, or . + /// The played duration, or . + /// One of the three values the metric attribute takes. + private static string Outcome(string? failure, TimeSpan? interruptedAfter) + { + return (failure, interruptedAfter) switch + { + (not null, _) => AgentCoreTelemetry.OutcomeFailed, + (_, not null) => AgentCoreTelemetry.OutcomeInterrupted, + _ => AgentCoreTelemetry.OutcomeCompleted, + }; + } + + /// Reads the approval requests one finished turn still waits on. + /// What the agent answered. + /// One entry per request content, oldest first; empty when the turn asked nothing. + private static List ApprovalRequestsOf(AgentResponse response) + { + List approvals = []; + foreach (ToolApprovalRequestContent request in response.Messages + .SelectMany(message => message.Contents) + .OfType()) + { + if (request.ToolCall is not FunctionCallContent call) + { + continue; + } + + approvals.Add(new PendingApproval( + request.RequestId, + call.Name, + JsonSerializer.SerializeToElement( + call.Arguments ?? new Dictionary(StringComparer.Ordinal)))); + } + + return approvals; + } + + /// Reports calls the model named that no tool answered. + /// The turn that just ran. + /// What the agent answered. + private void ReportUndeclaredToolCalls(ConversationTurn turn, AgentResponse response) + { + HashSet invoked = new(turn.Results.CallIds, StringComparer.Ordinal); + + foreach (FunctionCallContent? call in response.Messages + .SelectMany(message => message.Contents) + .OfType() + .Where(call => !invoked.Contains(call.CallId))) + { + _session.Events.RaiseToolFailure(turn.Index, new ToolFailure + { + ToolName = call.Name, + ToolCallId = call.CallId, + Kind = ToolFailureKind.Undeclared, + Message = $"the model called '{call.Name}', and no such tool is declared.", + }); + } + } + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationTurnOrigin.cs b/src/AgentCore.Application/Runtime/ConversationTurnOrigin.cs index 0b058921..2ee53613 100644 --- a/src/AgentCore.Application/Runtime/ConversationTurnOrigin.cs +++ b/src/AgentCore.Application/Runtime/ConversationTurnOrigin.cs @@ -1,16 +1,17 @@ -namespace AgentCore.Application.Runtime; - -/// Where a turn's words sit in the conversation the caller can see. -/// -/// What the caller calls the message it is sending, or to let the conversation name -/// it. The name is the caller's, and AgentCore reads it only as the handle a later edit anchors on. -/// -/// -/// The message these words hang off, or when they start the conversation afresh. -/// Read only when is set. -/// -public sealed record ConversationTurnOrigin(string? MessageId, string? ParentMessageId) +namespace AgentCore.Application.Runtime { - /// Gets whether the caller answered for where this turn hangs. - public required bool NamesParent { get; init; } + /// Where a turn's words sit in the conversation the caller can see. + /// + /// What the caller calls the message it is sending, or to let the conversation name + /// it. The name is the caller's, and AgentCore reads it only as the handle a later edit anchors on. + /// + /// + /// The message these words hang off, or when they start the conversation afresh. + /// Read only when is set. + /// + public sealed record ConversationTurnOrigin(string? MessageId, string? ParentMessageId) + { + /// Gets whether the caller answered for where this turn hangs. + public required bool NamesParent { get; init; } + } } diff --git a/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs b/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs new file mode 100644 index 00000000..bafa9b6f --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs @@ -0,0 +1,318 @@ +using System.Diagnostics; +using System.Globalization; +using AgentCore.Application.Diagnostics; +using AgentCore.Application.Knowledge; +using AgentCore.Application.Runtime.Turn; +using AgentCore.Application.State; +using AgentCore.Application.Transcript; +using AgentCore.Domain; +using AgentCore.Domain.Audit; +using AgentCore.Domain.Knowledge; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationTurnRunner + { + private readonly ConversationSession _session; + + private (string ToolId, IReadOnlyList Tools)? _delegatedTools; + + private bool _hasScreen; + + private TimeZoneInfo? _timeZone; + + internal ConversationTurnRunner(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// + /// Gives the runs this conversation delegates through one tool a set of tools of their own. + /// + /// The kind: agent tool whose delegated runs are offered these. + /// The tools. An empty list offers nothing, exactly as never calling this does. + /// An argument is . + internal void SetDelegatedTools(string delegatingToolId, IReadOnlyList tools) + { + ArgumentNullException.ThrowIfNull(delegatingToolId); + ArgumentNullException.ThrowIfNull(tools); + + _delegatedTools = (delegatingToolId, tools); + } + + /// + /// Gives this conversation the screen its tools draw on, or takes it away. + /// + internal void SetHasScreen(bool hasScreen) + { + _hasScreen = hasScreen; + } + + /// + /// Tells this conversation which zone the person is in, so the clock line reads their date. + /// + internal void SetTimeZone(TimeZoneInfo zone) + { + _timeZone = zone; + } + + /// Runs one turn of the conversation against the session the conversation holds. + /// What the caller said or answered. + /// Where the turn hangs, or null for a caller that does not say. + /// Cancels the turn. + /// What the turn did. + internal async Task RunTurnCoreAsync( + ChatMessage userInput, ConversationTurnOrigin? origin, CancellationToken cancellationToken) + { + AgentSession session = await _session.Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); + + await AdmitTurnAsync(session, origin, cancellationToken).ConfigureAwait(false); + ConversationTurn turn = BeginTurn(userInput, session, origin); + + CancellationTokenSource cancellation = _session.Interruptions.StartRun(cancellationToken); + + try + { + TurnInvocation invocation = TurnInvocationOf(turn); + + AgentSession runSession = await OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); + + TurnRegistry.Set(runSession, invocation); + + AgentResponse response; + string? toolFault = null; + + try + { + response = await turn.Agent + .RunAsync( + turn.Request, + runSession, + invocation.RunOptions(), + cancellationToken: cancellation.Token) + .ConfigureAwait(false); + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + toolFault = exception.Message; + response = new AgentResponse(); + } + + return await _session.Completion.CompleteTurnAsync(turn, response, toolFault, ConversationTurnStream.ReadDisposition(response), cancellationToken) + .ConfigureAwait(false); + } + finally + { + _session.Interruptions.EndRun(cancellation); + turn.Activity?.Dispose(); + } + } + + /// + /// Admits one turn: refuses a terminal or running conversation, then withdraws whatever the turn + /// replaces. follows, from the same frame. + /// + /// The session of this conversation. + /// Where the turn hangs, or null for a caller that does not say. + /// Cancels the withdrawal. + internal async ValueTask AdmitTurnAsync(AgentSession session, ConversationTurnOrigin? origin, CancellationToken cancellationToken) + { + if (_session.IsComplete) + { + throw new InvalidOperationException( + $"The conversation '{_session.ConversationId}' reached the terminal stage '{_session.Stage}', so it runs no further turn."); + } + + if (!_session.Interruptions.TryEnterTurn()) + { + throw new InvalidOperationException( + $"A turn of the conversation '{_session.ConversationId}' is still running. One conversation runs one turn at a time."); + } + + try + { + _session.Clarifications.BeginTurn(); + + await WithdrawSupersededAsync(session, origin, cancellationToken).ConfigureAwait(false); + } + catch + { + _session.Interruptions.ReleaseTurn(); + + throw; + } + } + + /// + /// Picks the agent, builds the model input, and takes the turn admitted. + /// Synchronous on purpose: the turn span it opens must be the ambient activity of the caller's + /// frame, and an async method hands no back. + /// + /// What the caller said or answered: words, an approval answer, or both. + /// The session of this conversation. + /// Where the turn hangs, or null for a caller that does not say. + /// Everything the rest of the turn needs. + internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, ConversationTurnOrigin? origin = null) + { + Activity? activity = null; + try + { + AIAgent agent = ResolveAgent(); + + string? reminder = _session.Policy is null ? null : UnfilledSlotReminder.Build(_session.State, _session.Policy.CurrentStage); + + ChatMessage spoken = userInput; + + _session.History.BeginTurn(session, _session.State.TurnIndex); + + List request = [spoken]; + if (!_session.SessionCarriesHistory + && !_session.ReusesGraphSession + && TurnMessages.GraphHistory(_session.History.Read(session)) is { } rendered) + { + request = [rendered, spoken]; + } + + activity = AgentCoreTelemetry.StartTurn(_session.ConversationId, _session.State.TurnIndex, _session.State.Stage); + + KnowledgeScope? knowledge = StateKnowledgeScope.Compose( + _session.State, _session.Compiled.Configuration.Providers?.Knowledge?.Scope, _session.Scope); + + if (knowledge is { Origins.Count: > 0 }) + { + Log.KnowledgeScopeComposed(_session.Logger, _session.ConversationId, _session.State.TurnIndex, knowledge.Origins); + } + + return new ConversationTurn( + agent, + session, + request, + spoken, + reminder, + _session.State.Stage, + _session.State.TurnIndex, + activity, + _session.Time.GetTimestamp(), + _hasScreen ? new TurnRenders() : null, + new TurnSources(), + new TurnResults(), + new TurnFiles(), + knowledge, + origin?.MessageId); + } + catch + { + activity?.Dispose(); + + _session.Interruptions.ReleaseTurn(); + + throw; + } + } + + /// Takes back everything the conversation said after the message this turn hangs off. + internal async ValueTask WithdrawSupersededAsync(AgentSession session, ConversationTurnOrigin? origin, CancellationToken cancellationToken) + { + if (origin is not { NamesParent: true }) + { + return; + } + + WithdrawnTurns? cut = _session.History.CanTruncateFrom(session, origin.ParentMessageId) + ? _session.History.TruncateFrom(session, origin.ParentMessageId) + : await _session.Ledger.CutUnderSummaryAsync(session, origin.ParentMessageId, cancellationToken).ConfigureAwait(false); + + if (cut is not { } withdrawn) + { + return; + } + + _session.Clarifications.Withdraw(); + + _ = _session.Events.Raise( + ConversationEventKind.TurnSuperseded, + _session.Time.GetUtcNow(), + _session.State.TurnIndex, + payload: new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.WithdrewFromTurnIndex] = + withdrawn.First.ToString(CultureInfo.InvariantCulture), + [AuditPayloadKeys.WithdrewThroughTurnIndex] = + withdrawn.Last.ToString(CultureInfo.InvariantCulture), + }); + } + + /// Picks the agent that speaks this turn. + /// The agent. + internal AIAgent ResolveAgent() + { + if (_session.Policy is null) + { + return _session.Compiled.TurnAgent; + } + + if (_session.Policy.CurrentAgentId is not { Length: > 0 } + || _session.Compiled.TurnAgentForStage(_session.Policy.Stage) is not { } agent) + { + throw new InvalidOperationException( + $"The stage '{_session.Policy.Stage}' of the conversation '{_session.ConversationId}' names no agent, so no turn can run."); + } + + return agent; + } + + /// + /// Reads the session one run is handed. + /// + /// The turn about to run. + /// Cancels the open. + /// The conversation's session on rows 1 and 2, the conversation's shared workflow session on a graph row that reuses one, and a fresh workflow session on any other graph row. + internal async ValueTask OpenRunAsync(ConversationTurn turn, CancellationToken cancellationToken) + { + if (_session.SessionCarriesHistory) + { + return turn.Session; + } + + if (_session.ReusesGraphSession) + { + return _session.GraphSession ??= await turn.Agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); + } + + return await turn.Agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); + } + + /// Builds the invocation one turn hands its tools. + /// The turn about to run. + /// Everything a tool of this turn may need, as one explicit value. + internal TurnInvocation TurnInvocationOf(ConversationTurn turn) + { + return new() + { + ConversationId = _session.ConversationId, + TurnIndex = turn.Index, + Stage = turn.StageBefore, + Instructions = turn.Reminder, + TimeZone = _timeZone, + Workspace = _session.Workspace, + Shells = _session.Shells, + Knowledge = turn.Knowledge, + Clarifications = _session.Clarifications, + CarriesHistory = _session.SessionCarriesHistory, + Logger = _session.Logger, + Screen = turn.Renders, + Sources = turn.Sources, + Renders = turn.Renders, + Results = turn.Results, + Files = turn.Files, + OnToolFailure = failure => _session.Events.RaiseToolFailure(turn.Index, failure), + Tools = _delegatedTools?.Tools, + ToolsFor = _delegatedTools?.ToolId, + State = _session.State, + }; + } + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationTurnStream.cs b/src/AgentCore.Application/Runtime/ConversationTurnStream.cs new file mode 100644 index 00000000..ba1d556f --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTurnStream.cs @@ -0,0 +1,157 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Runtime.Turn; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationTurnStream + { + private readonly ConversationSession _session; + + internal ConversationTurnStream(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// Streams one turn of the conversation against the session the conversation holds. + /// What the caller said or answered. + /// Where the turn hangs, or null for a caller that does not say. + /// Cancels the model calls. + /// The reply, one update at a time. + internal IAsyncEnumerable RunTurnStreamingCoreAsync( + ChatMessage userInput, + ConversationTurnOrigin? origin, + CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(userInput); + + return RunTurnStreamingIteratorAsync(userInput, origin, cancellationToken); + } + + /// Streams one turn. The caller checks the arguments. + private async IAsyncEnumerable RunTurnStreamingIteratorAsync( + ChatMessage userInput, + ConversationTurnOrigin? origin, + [EnumeratorCancellation] CancellationToken cancellationToken) + { + AgentSession session = await _session.Ledger.OpenSessionAsync(cancellationToken).ConfigureAwait(false); + + await _session.Runner.AdmitTurnAsync(session, origin, cancellationToken).ConfigureAwait(false); + ConversationTurn turn = _session.Runner.BeginTurn(userInput, session, origin); + + // A streaming turn becomes audible only once it hands the host its first piece of content. + // Until then nothing of it has reached the caller, and a barge-in belongs elsewhere. + CancellationTokenSource cancellation = _session.Interruptions.StartRun(cancellationToken); + try + { + List updates = []; + string? toolFault = null; + + TurnInvocation invocation = _session.Runner.TurnInvocationOf(turn); + AgentSession runSession = await _session.Runner.OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); + + TurnRegistry.Set(runSession, invocation); + + IAsyncEnumerator stream = turn.Agent + .RunStreamingAsync( + turn.Request, + runSession, + invocation.RunOptions(), + cancellationToken: cancellation.Token) + .GetAsyncEnumerator(cancellation.Token); + + try + { + while (true) + { + AgentResponseUpdate update; + + try + { + if (!await stream.MoveNextAsync().ConfigureAwait(false)) + { + break; + } + + update = stream.Current; + } + catch (OperationCanceledException) when (_session.Interruptions.CurrentInterruption() is not null) + { + break; + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + toolFault = exception.Message; + + break; + } + + updates.Add(update); + + ChatResponseUpdate content = update.AsChatResponseUpdate(); + if (TurnMessages.CarriesContent(content) && Speaks(update)) + { + _session.Interruptions.RunIsAudible = true; + + yield return content; + } + } + } + finally + { + await stream.DisposeAsync().ConfigureAwait(false); + } + + _ = await _session.Completion.CompleteTurnAsync( + turn, updates.ToAgentResponse(), toolFault, ReadDisposition(updates), cancellationToken) + .ConfigureAwait(false); + } + finally + { + _session.Interruptions.EndRun(cancellation); + turn.Activity?.Dispose(); + } + } + + /// Reads whether the caller hears the node that produced one update. + /// One update of the run. + /// when the host should speak it. + internal bool Speaks(AgentResponseUpdate update) + { + return _session.Compiled.SpokenBy is not { } spoken + || (update.AuthorName is { } author && spoken.Contains(author)) + || update.AdditionalProperties?.Contains() is true; + } + + /// Reads what the turn layers reported about one finished turn. + /// What the agent answered. + /// The disposition, or when no layer marked the turn. + internal static TurnDisposition? ReadDisposition(AgentResponse response) + { + return response.AdditionalProperties is { } properties + && properties.TryGetValue(out TurnDisposition? disposition) + ? disposition + : null; + } + + /// Reads what the turn layers reported across the updates of one streaming turn. + /// Every update the run produced, in order, before the seam filtered them. + /// The disposition, or when no update carried one. + internal static TurnDisposition? ReadDisposition(List updates) + { + TurnDisposition? found = null; + foreach (AgentResponseUpdate update in updates) + { + if (update.AdditionalProperties is { } properties + && properties.TryGetValue(out TurnDisposition? disposition)) + { + found = disposition; + } + } + + return found; + } + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationTurnWriters.cs b/src/AgentCore.Application/Runtime/ConversationTurnWriters.cs new file mode 100644 index 00000000..e013db63 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ConversationTurnWriters.cs @@ -0,0 +1,79 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.State; +using AgentCore.Application.Tools; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + internal sealed class ConversationTurnWriters + { + private readonly ConversationSession _session; + + internal ConversationTurnWriters(ConversationSession session) + { + ArgumentNullException.ThrowIfNull(session); + _session = session; + } + + /// Runs the extractor against the finished turn. + /// The turn that just spoke. + /// What the agent answered. + /// Cancels the model call. + /// The reason the extractor produced nothing, or . + internal async Task ExtractAsync(ConversationTurn turn, AgentResponse response, CancellationToken cancellationToken) + { + if (_session.Extractor is null || _session.Compiled.Configuration.Extractor is not { When: ExtractorTrigger.AfterReply }) + { + return null; + } + + // The extractor reads the finished turn and, in front of it, the last thing the agent said + // before the caller spoke. A caller answering a question — "the ENT one", "yes", "the second + // one" — cannot be read without the question, and the state document cannot carry it because + // nothing was written yet. The rest of the conversation stays out: the document already carries every + // earlier answer. Measured 2026-09-02: with the question in view every such answer resolved, + // and a turn where only the agent had named a machine still filled nothing. + List finished = [turn.Spoken, .. response.Messages]; + if (_session.Transcript.LastOrDefault(message => message.Role == ChatRole.Assistant && message.Text.Length > 0) is { } asked) + { + finished.Insert(0, asked); + } + + // A failed extraction never drops the turn. The result carries the reason instead. + StateExtractionResult result = await _session.Extractor.ExtractAsync(_session.State, finished, _session.Clarifications, cancellationToken) + .ConfigureAwait(false); + + return result.Failure; + } + + /// Fills every tool-written slot from the tool results of one turn. + /// The messages the agent produced, oldest first. + internal void ApplyToolResults(IEnumerable messages) + { + // The name a call carries is the declared tool id, because the compile table names every + // function after the tools: entry it built. + ToolCallNames names = new(); + + foreach (ChatMessage message in messages) + { + foreach (AIContent content in message.Contents) + { + switch (content) + { + case FunctionCallContent conversation: + names.Called(conversation); + break; + + case FunctionResultContent result when names.Of(result) is { } toolId: + _ = ToolStateWriter.Apply(_session.State, toolId, ToolResultJson.ToNode(result.Result)); + break; + + default: + break; + } + } + } + } + } +} diff --git a/src/AgentCore.Application/Runtime/ConversationWorkspace.cs b/src/AgentCore.Application/Runtime/ConversationWorkspace.cs index 7ac8247f..84b642d9 100644 --- a/src/AgentCore.Application/Runtime/ConversationWorkspace.cs +++ b/src/AgentCore.Application/Runtime/ConversationWorkspace.cs @@ -1,87 +1,91 @@ using AgentCore.Application.Diagnostics; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime; - -/// -/// The folder one conversation owns on disk: created with the conversation, and deleted when it ends. -/// -internal sealed class ConversationWorkspace +namespace AgentCore.Application.Runtime { - private ConversationWorkspace(string path) => Path = path; - - /// Gets the folder's path. - public string Path { get; } - /// - /// Creates (or, for a resumed conversation, reuses) the folder root/conversationId. + /// The folder one conversation owns on disk: created with the conversation, and deleted when it ends. /// - /// The root a host bound. - /// - /// The conversation's id. A host-given id must not escape : the combined path is - /// checked, not the text of the id, so this also refuses a conversationId of ".", which - /// would otherwise resolve straight back to the root. - /// - /// - /// is empty or white space, or resolves to a path that is not a strict - /// child of . - /// - public static ConversationWorkspace Create(string root, string conversationId) + internal sealed class ConversationWorkspace { - ArgumentException.ThrowIfNullOrEmpty(root); - ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); - - if (conversationId.Contains('/', StringComparison.Ordinal) || conversationId.Contains('\\', StringComparison.Ordinal)) + private ConversationWorkspace(string path) { - throw new ArgumentException( - $"The conversation id '{conversationId}' must not contain a directory separator.", nameof(conversationId)); + Path = path; } - var fullRoot = System.IO.Path.GetFullPath(root); - var path = System.IO.Path.GetFullPath(System.IO.Path.Combine(fullRoot, conversationId)); + /// Gets the folder's path. + public string Path { get; } - var rootWithSeparator = fullRoot.EndsWith(System.IO.Path.DirectorySeparatorChar) - ? fullRoot - : fullRoot + System.IO.Path.DirectorySeparatorChar; - - // GetFullPath can normalise the last segment away from what the caller wrote — on Windows it - // strips trailing spaces and periods, so " ." or "conversation-1." would otherwise alias the root or - // an unrelated sibling. Requiring the resolved folder name to still equal conversationId catches that, - // on top of the plain containment check. - if (!path.StartsWith(rootWithSeparator, StringComparison.Ordinal) - || path.Length <= rootWithSeparator.Length - || !string.Equals(System.IO.Path.GetFileName(path), conversationId, StringComparison.Ordinal)) + /// + /// Creates (or, for a resumed conversation, reuses) the folder root/conversationId. + /// + /// The root a host bound. + /// + /// The conversation's id. A host-given id must not escape : the combined path is + /// checked, not the text of the id, so this also refuses a conversationId of ".", which + /// would otherwise resolve straight back to the root. + /// + /// + /// is empty or white space, or resolves to a path that is not a strict + /// child of . + /// + public static ConversationWorkspace Create(string root, string conversationId) { - throw new ArgumentException( - $"The conversation id '{conversationId}' must resolve to a folder under the workspace root.", nameof(conversationId)); - } + ArgumentException.ThrowIfNullOrEmpty(root); + ArgumentException.ThrowIfNullOrWhiteSpace(conversationId); - Directory.CreateDirectory(path); - return new ConversationWorkspace(path); - } + if (conversationId.Contains('/', StringComparison.Ordinal) || conversationId.Contains('\\', StringComparison.Ordinal)) + { + throw new ArgumentException( + $"The conversation id '{conversationId}' must not contain a directory separator.", nameof(conversationId)); + } - /// - /// Deletes the folder recursively. Safe to call twice: the second call finds nothing and does - /// not log. Never throws out of a caller ending a conversation. - /// - /// Where a failed delete is logged, at Warning. May be . - public void Delete(ILogger? logger) - { - try - { - Directory.Delete(Path, recursive: true); - } - catch (DirectoryNotFoundException) - { - // Already gone: this is the second call, or the host removed it out of band. + string fullRoot = System.IO.Path.GetFullPath(root); + string path = System.IO.Path.GetFullPath(System.IO.Path.Combine(fullRoot, conversationId)); + + string rootWithSeparator = fullRoot.EndsWith(System.IO.Path.DirectorySeparatorChar) + ? fullRoot + : fullRoot + System.IO.Path.DirectorySeparatorChar; + + // GetFullPath can normalise the last segment away from what the caller wrote — on Windows it + // strips trailing spaces and periods, so " ." or "conversation-1." would otherwise alias the root or + // an unrelated sibling. Requiring the resolved folder name to still equal conversationId catches that, + // on top of the plain containment check. + if (!path.StartsWith(rootWithSeparator, StringComparison.Ordinal) + || path.Length <= rootWithSeparator.Length + || !string.Equals(System.IO.Path.GetFileName(path), conversationId, StringComparison.Ordinal)) + { + throw new ArgumentException( + $"The conversation id '{conversationId}' must resolve to a folder under the workspace root.", nameof(conversationId)); + } + + _ = Directory.CreateDirectory(path); + return new ConversationWorkspace(path); } - catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) + + /// + /// Deletes the folder recursively. Safe to call twice: the second call finds nothing and does + /// not log. Never throws out of a caller ending a conversation. + /// + /// Where a failed delete is logged, at Warning. May be . + public void Delete(ILogger? logger) { - // A concurrent delete from outside this conversation may have removed the folder in the window - // between the failing operation and this check; that is not a failure worth logging. - if (logger is not null && Directory.Exists(Path)) + try + { + Directory.Delete(Path, recursive: true); + } + catch (DirectoryNotFoundException) + { + // Already gone: this is the second call, or the host removed it out of band. + } + catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) { - Log.WorkspaceDeleteFailed(logger, Path, exception); + // A concurrent delete from outside this conversation may have removed the folder in the window + // between the failing operation and this check; that is not a failure worth logging. + if (logger is not null && Directory.Exists(Path)) + { + Log.WorkspaceDeleteFailed(logger, Path, exception); + } } } } diff --git a/src/AgentCore.Application/Runtime/DelegatedAgentRun.cs b/src/AgentCore.Application/Runtime/DelegatedAgentRun.cs index 7f7e7636..ac8d4b52 100644 --- a/src/AgentCore.Application/Runtime/DelegatedAgentRun.cs +++ b/src/AgentCore.Application/Runtime/DelegatedAgentRun.cs @@ -2,60 +2,61 @@ using System.Text.Json; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -// Runs one delegated agent directly — the same RunAsync every other run goes through — -// instead of the framework's agent-as-function machinery, which builds the nested run's -// options where no caller can file the turn. The bridge files the nested turn and the -// tools this delegation is offered on the nested run's own options, exactly like the -// loop does for the outer run. One nested run, one fresh session: concurrent delegations -// never share one. -internal static class DelegatedAgentRun +namespace AgentCore.Application.Runtime { - /// Runs one inner agent for one delegating tool call. - /// The agent being delegated to. - /// What the outer agent asked, in words. - /// The parent turn, stripped per K42 — or null outside a turn. - /// The tools this delegation is offered, or null for none. - /// Cancels the run. - /// What the inner agent answered, as the outer agent reads it. - internal static async ValueTask RunAsync( - AIAgent inner, - string query, - TurnInvocation? nested, - IReadOnlyList? tools, - CancellationToken cancellationToken) + // Runs one delegated agent directly — the same RunAsync every other run goes through — + // instead of the framework's agent-as-function machinery, which builds the nested run's + // options where no caller can file the turn. The bridge files the nested turn and the + // tools this delegation is offered on the nested run's own options, exactly like the + // loop does for the outer run. One nested run, one fresh session: concurrent delegations + // never share one. + internal static class DelegatedAgentRun { - ArgumentNullException.ThrowIfNull(inner); - ArgumentNullException.ThrowIfNull(query); - - var session = await inner.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - - ChatOptions chat = new() - { - AdditionalProperties = [], - }; - - if (nested is not null) + /// Runs one inner agent for one delegating tool call. + /// The agent being delegated to. + /// What the outer agent asked, in words. + /// The parent turn, stripped per K42 — or null outside a turn. + /// The tools this delegation is offered, or null for none. + /// Cancels the run. + /// What the inner agent answered, as the outer agent reads it. + internal static async ValueTask RunAsync( + AIAgent inner, + string query, + TurnInvocation? nested, + IReadOnlyList? tools, + CancellationToken cancellationToken) { - chat.AdditionalProperties[TurnInvocation.ArgumentsKey] = nested; + ArgumentNullException.ThrowIfNull(inner); + ArgumentNullException.ThrowIfNull(query); + + AgentSession session = await inner.CreateSessionAsync(cancellationToken).ConfigureAwait(false); + + ChatOptions chat = new() + { + AdditionalProperties = [], + }; + + if (nested is not null) + { + chat.AdditionalProperties[TurnInvocation.ArgumentsKey] = nested; + } + + if (tools is { Count: > 0 }) + { + chat.Tools = [.. tools]; + } + + AgentResponse response = await inner.RunAsync( + [new ChatMessage(ChatRole.User, query)], + session, + new ChatClientAgentRunOptions(chat), + cancellationToken).ConfigureAwait(false); + + // Marshaled like the framework's own agent-as-function result: the outer loop reads + // words either way, but callers pin the JsonElement shape. + return response.Text is { } text + ? JsonSerializer.SerializeToElement(text) + : null; } - - if (tools is { Count: > 0 }) - { - chat.Tools = [.. tools]; - } - - var response = await inner.RunAsync( - [new ChatMessage(ChatRole.User, query)], - session, - new ChatClientAgentRunOptions(chat), - cancellationToken).ConfigureAwait(false); - - // Marshaled like the framework's own agent-as-function result: the outer loop reads - // words either way, but callers pin the JsonElement shape. - return response.Text is { } text - ? JsonSerializer.SerializeToElement(text) - : null; } } diff --git a/src/AgentCore.Application/Runtime/FallbackAgent.cs b/src/AgentCore.Application/Runtime/FallbackAgent.cs index 58c491d5..76ad94d7 100644 --- a/src/AgentCore.Application/Runtime/FallbackAgent.cs +++ b/src/AgentCore.Application/Runtime/FallbackAgent.cs @@ -2,200 +2,214 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -/// -/// Answers a run that threw, or one that spoke no words at all, with the spoken fallback. -/// -/// -/// -/// R1: a tool that fails four times in a row throws out of the run, and section 8.7 says that must -/// never kill the conversation. R2: at 40 tool rounds the framework sends request 41 with no tools and -/// returns quietly, with no exception — on a voice conversation that silence is the failure, so an empty -/// reply is read rather than trusting the absence of an error. Both end here, and both leave the -/// turn an ordinary successful run. -/// -/// -/// A cancel is not a fault. is never swallowed: a -/// barge-in ends the turn on the caller's terms and the turn loop records what was heard. -/// -/// -/// It wraps an AGENT and not a chat client. One turn is one run of one agent on every row of -/// the compile table. A chat-pipeline layer would answer each graph node separately, and a node that -/// went quiet would then speak the fallback INTO the graph — which is exactly the silent graph -/// failure section 8.2 refuses to ship, hidden rather than raised. -/// -/// -/// A run that threw carries no messages out, because the fault ended it. An empty run keeps the -/// messages it did produce, so a tool pair that finished stays visible to the next turn. -/// -/// -/// On a graph row the emptiness that matters is the OUTPUT node's, not the run's. Measured on -/// Microsoft.Agents.AI 1.17.0: a sequential graph whose last node answers with whitespace returns one -/// message, and it is the node BEFORE it. Reading the run as "it produced text" would put the graph's -/// own deliberation in the caller's ear. The constructor's spokenBy set names the agents whose -/// reply the caller hears, so a quiet output node reads as the silence it is. -/// -/// -/// It holds no per-call state: one instance is compiled once and shared by every conversation under T44 and -/// R7. -/// -/// -internal sealed class FallbackAgent : DelegatingAIAgent +namespace AgentCore.Application.Runtime { - private readonly string _fallbackReply; - private readonly IReadOnlySet? _spokenBy; - - /// Puts the fallback in front of one turn agent. - /// The agent a turn runs. - /// What a failed turn speaks. - /// - /// The agents.items ids whose reply the caller hears, or when the - /// last thing the run produced is that reply. It is null for rows 1 and 2, which run one agent, - /// and for the graph patterns where any participant may answer last. - /// - public FallbackAgent(AIAgent inner, string fallbackReply, IReadOnlySet? spokenBy = null) - : base(inner) - { - ArgumentNullException.ThrowIfNull(fallbackReply); - _fallbackReply = fallbackReply; - _spokenBy = spokenBy; - } - - /// - protected override async Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) + /// + /// Answers a run that threw, or one that spoke no words at all, with the spoken fallback. + /// + /// + /// + /// R1: a tool that fails four times in a row throws out of the run, and section 8.7 says that must + /// never kill the conversation. R2: at 40 tool rounds the framework sends request 41 with no tools and + /// returns quietly, with no exception — on a voice conversation that silence is the failure, so an empty + /// reply is read rather than trusting the absence of an error. Both end here, and both leave the + /// turn an ordinary successful run. + /// + /// + /// A cancel is not a fault. is never swallowed: a + /// barge-in ends the turn on the caller's terms and the turn loop records what was heard. + /// + /// + /// It wraps an AGENT and not a chat client. One turn is one run of one agent on every row of + /// the compile table. A chat-pipeline layer would answer each graph node separately, and a node that + /// went quiet would then speak the fallback INTO the graph — which is exactly the silent graph + /// failure section 8.2 refuses to ship, hidden rather than raised. + /// + /// + /// A run that threw carries no messages out, because the fault ended it. An empty run keeps the + /// messages it did produce, so a tool pair that finished stays visible to the next turn. + /// + /// + /// On a graph row the emptiness that matters is the OUTPUT node's, not the run's. Measured on + /// Microsoft.Agents.AI 1.17.0: a sequential graph whose last node answers with whitespace returns one + /// message, and it is the node BEFORE it. Reading the run as "it produced text" would put the graph's + /// own deliberation in the caller's ear. The constructor's spokenBy set names the agents whose + /// reply the caller hears, so a quiet output node reads as the silence it is. + /// + /// + /// It holds no per-call state: one instance is compiled once and shared by every conversation under T44 and + /// R7. + /// + /// + internal sealed class FallbackAgent : DelegatingAIAgent { - AgentResponse response; - try + private readonly string _fallbackReply; + private readonly IReadOnlySet? _spokenBy; + + /// Puts the fallback in front of one turn agent. + /// The agent a turn runs. + /// What a failed turn speaks. + /// + /// The agents.items ids whose reply the caller hears, or when the + /// last thing the run produced is that reply. It is null for rows 1 and 2, which run one agent, + /// and for the graph patterns where any participant may answer last. + /// + public FallbackAgent(AIAgent inner, string fallbackReply, IReadOnlySet? spokenBy = null) + : base(inner) { - response = await base.RunCoreAsync(messages, session, options, cancellationToken) - .ConfigureAwait(false); + ArgumentNullException.ThrowIfNull(fallbackReply); + _fallbackReply = fallbackReply; + _spokenBy = spokenBy; } + + /// + protected override async Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + AgentResponse response; + try + { + response = await base.RunCoreAsync(messages, session, options, cancellationToken) + .ConfigureAwait(false); + } #pragma warning disable CA1031 // Section 8.7, row six: the run throws, the turn ends, and the conversation lives. - catch (Exception exception) when (exception is not OperationCanceledException) + catch (Exception exception) when (exception is not OperationCanceledException) #pragma warning restore CA1031 - { - AgentResponse spoken = new(new ChatMessage(ChatRole.Assistant, _fallbackReply)); - spoken.AdditionalProperties ??= []; - spoken.AdditionalProperties.Add(Disposition(FallbackCause.Faulted, exception.Message)); - return spoken; - } + { + AgentResponse spoken = new(new ChatMessage(ChatRole.Assistant, _fallbackReply)); + spoken.AdditionalProperties ??= []; + spoken.AdditionalProperties.Add(Disposition(FallbackCause.Faulted, exception.Message)); + return spoken; + } - if (!string.IsNullOrWhiteSpace(SpokenText(response)) || HasApprovalRequest(response.Messages)) - { + if (!string.IsNullOrWhiteSpace(SpokenText(response)) || HasApprovalRequest(response.Messages)) + { + return response; + } + + response.Messages.Add(new ChatMessage(ChatRole.Assistant, _fallbackReply)); + response.AdditionalProperties ??= []; + response.AdditionalProperties.Add(Disposition(FallbackCause.EmptyReply, null)); return response; } - response.Messages.Add(new ChatMessage(ChatRole.Assistant, _fallbackReply)); - response.AdditionalProperties ??= []; - response.AdditionalProperties.Add(Disposition(FallbackCause.EmptyReply, null)); - return response; - } - - /// - /// - /// C# forbids yield return inside a catch (CS1631), so the inner enumerator is - /// driven by hand: the fault goes to a local, and the fallback is emitted after the try/catch. - /// - protected override async IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - var updates = base.RunCoreStreamingAsync(messages, session, options, cancellationToken) - .GetAsyncEnumerator(cancellationToken); + /// + /// + /// C# forbids yield return inside a catch (CS1631), so the inner enumerator is + /// driven by hand: the fault goes to a local, and the fallback is emitted after the try/catch. + /// + protected override async IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + IAsyncEnumerator updates = base.RunCoreStreamingAsync(messages, session, options, cancellationToken) + .GetAsyncEnumerator(cancellationToken); - var spokeText = false; - var cause = FallbackCause.None; - string? reason = null; + bool spokeText = false; + FallbackCause cause = FallbackCause.None; + string? reason = null; - try - { - while (true) + try { - AgentResponseUpdate? current = null; - try + while (true) { - if (await updates.MoveNextAsync().ConfigureAwait(false)) + AgentResponseUpdate? current = null; + try { - current = updates.Current; + if (await updates.MoveNextAsync().ConfigureAwait(false)) + { + current = updates.Current; + } } - } #pragma warning disable CA1031 // Section 8.7, row six. See the buffered path above. - catch (Exception exception) when (exception is not OperationCanceledException) + catch (Exception exception) when (exception is not OperationCanceledException) #pragma warning restore CA1031 - { - cause = FallbackCause.Faulted; - reason = exception.Message; - } + { + cause = FallbackCause.Faulted; + reason = exception.Message; + } - if (cause is not FallbackCause.None || current is null) - { - break; + if (cause is not FallbackCause.None || current is null) + { + break; + } + + spokeText = spokeText || HasApprovalRequest(current) || (Speaks(current.AuthorName) && !string.IsNullOrWhiteSpace(current.Text)); + yield return current; } + } + finally + { + await updates.DisposeAsync().ConfigureAwait(false); + } - spokeText = spokeText || HasApprovalRequest(current) || (Speaks(current.AuthorName) && !string.IsNullOrWhiteSpace(current.Text)); - yield return current; + if (cause is FallbackCause.None && !spokeText) + { + cause = FallbackCause.EmptyReply; + } + + if (cause is not FallbackCause.None) + { + AgentResponseUpdate spoken = new(ChatRole.Assistant, _fallbackReply); + spoken.AdditionalProperties ??= []; + spoken.AdditionalProperties.Add(Disposition(cause, reason)); + yield return spoken; } } - finally + + /// Reads whether the run asks the caller to approve a tool call. + /// What the inner agent answered. + /// Whether any message carries an approval request. + /// + /// A request-only reply carries no text, so without this the run reads as silence and takes + /// the fallback. An approval the caller never hears is a tool that never runs, so a request + /// counts as spoken whoever authored it. + /// + private static bool HasApprovalRequest(IEnumerable messages) { - await updates.DisposeAsync().ConfigureAwait(false); + return messages.Any(message => HasApprovalRequest(message.Contents)); } - if (cause is FallbackCause.None && !spokeText) + /// Reads whether one update asks the caller to approve a tool call. + /// One update of the run. + /// Whether the update carries an approval request. + private static bool HasApprovalRequest(AgentResponseUpdate update) { - cause = FallbackCause.EmptyReply; + return HasApprovalRequest(update.Contents); } - if (cause is not FallbackCause.None) + private static bool HasApprovalRequest(IEnumerable contents) { - AgentResponseUpdate spoken = new(ChatRole.Assistant, _fallbackReply); - spoken.AdditionalProperties ??= []; - spoken.AdditionalProperties.Add(Disposition(cause, reason)); - yield return spoken; + return contents.OfType().Any(); } - } - /// Reads whether the run asks the caller to approve a tool call. - /// What the inner agent answered. - /// Whether any message carries an approval request. - /// - /// A request-only reply carries no text, so without this the run reads as silence and takes - /// the fallback. An approval the caller never hears is a tool that never runs, so a request - /// counts as spoken whoever authored it. - /// - private static bool HasApprovalRequest(IEnumerable messages) - => messages.Any(message => HasApprovalRequest(message.Contents)); - - /// Reads whether one update asks the caller to approve a tool call. - /// One update of the run. - /// Whether the update carries an approval request. - private static bool HasApprovalRequest(AgentResponseUpdate update) - => HasApprovalRequest(update.Contents); - - private static bool HasApprovalRequest(IEnumerable contents) - => contents.OfType().Any(); - - /// Reads the words this run would put in the caller's ear. - /// What the inner agent answered. - /// The spoken text, or an empty string when nothing the caller hears was produced. - private string SpokenText(AgentResponse response) => SpokenReply.From(response.Messages, _spokenBy); + /// Reads the words this run would put in the caller's ear. + /// What the inner agent answered. + /// The spoken text, or an empty string when nothing the caller hears was produced. + private string SpokenText(AgentResponse response) + { + return SpokenReply.From(response.Messages, _spokenBy); + } - /// Reads whether the caller hears what this author said. - /// The node that produced the message or the update, if any. - /// when the text counts as the reply. - private bool Speaks(string? authorName) - => _spokenBy is null || (authorName is not null && _spokenBy.Contains(authorName)); + /// Reads whether the caller hears what this author said. + /// The node that produced the message or the update, if any. + /// when the text counts as the reply. + private bool Speaks(string? authorName) + { + return _spokenBy is null || (authorName is not null && _spokenBy.Contains(authorName)); + } - /// - /// What this layer alone knows. folds its own verdict in above. - /// - private static TurnDisposition Disposition(FallbackCause cause, string? reason) - => new(Moderation: null, FlaggedCategories: null, cause, reason, ModerationReason: null); + /// + /// What this layer alone knows. folds its own verdict in above. + /// + private static TurnDisposition Disposition(FallbackCause cause, string? reason) + { + return new(Moderation: null, FlaggedCategories: null, cause, reason, ModerationReason: null); + } + } } diff --git a/src/AgentCore.Application/Runtime/GraphStateAgent.cs b/src/AgentCore.Application/Runtime/GraphStateAgent.cs index 057d2e27..f10bc110 100644 --- a/src/AgentCore.Application/Runtime/GraphStateAgent.cs +++ b/src/AgentCore.Application/Runtime/GraphStateAgent.cs @@ -1,62 +1,61 @@ +using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Runtime.Turn; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -/// -/// Files the turn's state snapshot at the head of a guarded row 4 graph run, where the -/// graph-state entry strips it into workflow-scoped state for the guard gates. -/// -internal sealed class GraphStateAgent : DelegatingAIAgent +namespace AgentCore.Application.Runtime { - private readonly string _name; - - /// Puts the state filing in front of one guarded graph. - /// The workflow of row 4, already wrapped by AsAIAgent(). - /// The name of the document, which the failure reports. - public GraphStateAgent(AIAgent inner, string name) - : base(inner) + /// + /// Files the turn's state snapshot at the head of a guarded row 4 graph run, where the + /// graph-state entry strips it into workflow-scoped state for the guard gates. + /// + internal sealed class GraphStateAgent : DelegatingAIAgent { - ArgumentNullException.ThrowIfNull(name); - _name = name; - } + private readonly string _name; - /// - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - { - return base.RunCoreAsync(Filed(messages, session, options), session, options, cancellationToken); - } - - /// - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - { - return base.RunCoreStreamingAsync(Filed(messages, session, options), session, options, cancellationToken); - } + /// Puts the state filing in front of one guarded graph. + /// The workflow of row 4, already wrapped by AsAIAgent(). + /// The name of the document, which the failure reports. + public GraphStateAgent(AIAgent inner, string name) + : base(inner) + { + ArgumentNullException.ThrowIfNull(name); + _name = name; + } - private List Filed(IEnumerable messages, AgentSession? session, AgentRunOptions? options) - { - ArgumentNullException.ThrowIfNull(messages); + /// + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + return base.RunCoreAsync(Filed(messages, session, options), session, options, cancellationToken); + } - var invocation = TurnRegistry.For(session) ?? TurnInvocation.From(options); - var snapshot = invocation?.State?.Snapshot(); - - if (snapshot is null) + /// + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) { - throw new InvalidOperationException( - $"The graph '{_name}' runs a guarded edge with no state filed on the run. " - + GraphGuardGate.NoStateMessage); + return base.RunCoreStreamingAsync(Filed(messages, session, options), session, options, cancellationToken); } - return [GraphStateCarrier.Build(snapshot), .. messages]; + private List Filed(IEnumerable messages, AgentSession? session, AgentRunOptions? options) + { + ArgumentNullException.ThrowIfNull(messages); + + TurnInvocation? invocation = TurnRegistry.For(session) ?? TurnInvocation.From(options); + IReadOnlyDictionary? snapshot = invocation?.State?.Snapshot(); + + return snapshot is null + ? throw new InvalidOperationException( + $"The graph '{_name}' runs a guarded edge with no state filed on the run. " + + GraphGuardGate.NoStateMessage) + : [GraphStateCarrier.Build(snapshot), .. messages]; + } } } diff --git a/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs b/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs index 31205fbe..20fce75f 100644 --- a/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs +++ b/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs @@ -1,64 +1,67 @@ using AgentCore.Application.Runtime.Turn; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// Wraps one background: child so every session it gets knows which conversation started it, -/// which zone the person on that call is in, and which workspace and shells that call owns. -/// -/// -/// BackgroundAgentsProvider creates the child session inside the parent's tool call, before -/// it hands the run to a task. At that moment is still the -/// parent's run, and its options carry the parent's turn. That is the only place the conversation id can -/// cross from parent to child: the provider passes the child null run options and a fresh session, -/// and its task-to-session map is private. Proven by probe P2 against Microsoft.Agents.AI 1.21.0. -/// -internal sealed class BackgroundChildAgent(AIAgent inner) : DelegatingAIAgent(inner) +namespace AgentCore.Application.Runtime.Harness { - /// - protected override async ValueTask CreateSessionCoreAsync(CancellationToken cancellationToken = default) + /// + /// Wraps one background: child so every session it gets knows which conversation started it, + /// which zone the person on that call is in, and which workspace and shells that call owns. + /// + /// + /// BackgroundAgentsProvider creates the child session inside the parent's tool call, before + /// it hands the run to a task. At that moment is still the + /// parent's run, and its options carry the parent's turn. That is the only place the conversation id can + /// cross from parent to child: the provider passes the child null run options and a fresh session, + /// and its task-to-session map is private. Proven by probe P2 against Microsoft.Agents.AI 1.21.0. + /// + internal sealed class BackgroundChildAgent(AIAgent inner) : DelegatingAIAgent(inner) { - var parent = AIAgent.CurrentRunContext; + /// + protected override async ValueTask CreateSessionCoreAsync(CancellationToken cancellationToken = default) + { + AgentRunContext? parent = CurrentRunContext; - var session = await InnerAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); + AgentSession session = await InnerAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - var turn = TurnInvocation.From(parent?.RunOptions); + TurnInvocation? turn = TurnInvocation.From(parent?.RunOptions); - if (turn?.ConversationId is { } conversationId) - { - session.StateBag.SetValue(BlobOwnerKey.Value, conversationId); - } + if (turn?.ConversationId is { } conversationId) + { + session.StateBag.SetValue(BlobOwnerKey.Value, conversationId); + } - if (turn?.TimeZone is { } zone) - { - CallerTimeZone.Stamp(session, zone); + if (turn?.TimeZone is { } zone) + { + CallerTimeZone.Stamp(session, zone); + } + + if (turn is not null) + { + TurnRegistry.Set(session, Shared(turn)); + } + + return session; } - if (turn is not null) + /// + /// The part of the parent's turn a child may share: the conversation, its workspace folder, and its + /// shells, so files: and shell: on the child work on the same disk. Every drain, + /// screen, tool list, and clarification stays with the parent; a child's publish reports a + /// link in its result instead. + /// + private static TurnInvocation Shared(TurnInvocation parent) { - TurnRegistry.Set(session, Shared(turn)); + return new() + { + ConversationId = parent.ConversationId, + TurnIndex = parent.TurnIndex, + Stage = parent.Stage, + Workspace = parent.Workspace, + Shells = parent.Shells, + Knowledge = parent.Knowledge, + TimeZone = parent.TimeZone, + Nested = true, + }; } - - return session; } - - /// - /// The part of the parent's turn a child may share: the conversation, its workspace folder, and its - /// shells, so files: and shell: on the child work on the same disk. Every drain, - /// screen, tool list, and clarification stays with the parent; a child's publish reports a - /// link in its result instead. - /// - private static TurnInvocation Shared(TurnInvocation parent) - => new() - { - ConversationId = parent.ConversationId, - TurnIndex = parent.TurnIndex, - Stage = parent.Stage, - Workspace = parent.Workspace, - Shells = parent.Shells, - Knowledge = parent.Knowledge, - TimeZone = parent.TimeZone, - Nested = true, - }; } diff --git a/src/AgentCore.Application/Runtime/Harness/BackgroundSessionRelease.cs b/src/AgentCore.Application/Runtime/Harness/BackgroundSessionRelease.cs index 932e0cd1..38ce5802 100644 --- a/src/AgentCore.Application/Runtime/Harness/BackgroundSessionRelease.cs +++ b/src/AgentCore.Application/Runtime/Harness/BackgroundSessionRelease.cs @@ -2,55 +2,56 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// Releases the harness background providers' sessions when a conversation ends, so children still -/// running cannot outlive it. A task that spans turns is untouched until the end. -/// -internal static class BackgroundSessionRelease +namespace AgentCore.Application.Runtime.Harness { /// - /// How long the release waits for running children to acknowledge the cancel before the - /// conversation's own teardown continues. Bounded like the extractor deadline: teardown never hangs - /// on a child. - /// - private static readonly TimeSpan ReleaseTimeout = TimeSpan.FromSeconds(5); - - /// - /// Cancels each provider's running tasks on and releases the - /// session. Best effort: one provider's fault is logged and the rest still release. + /// Releases the harness background providers' sessions when a conversation ends, so children still + /// running cannot outlive it. A task that spans turns is untouched until the end. /// - /// Every background provider the document compiled. - /// The session of the conversation that ended. - /// The id of the conversation, for the log. - /// The logger of the session. - /// Cancels the release. -#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. - public static async ValueTask ReleaseAsync( - IReadOnlyList providers, - AgentSession session, - string conversationId, - ILogger logger, - CancellationToken cancellationToken) + internal static class BackgroundSessionRelease { - ArgumentNullException.ThrowIfNull(providers); - ArgumentNullException.ThrowIfNull(session); - ArgumentException.ThrowIfNullOrEmpty(conversationId); - ArgumentNullException.ThrowIfNull(logger); + /// + /// How long the release waits for running children to acknowledge the cancel before the + /// conversation's own teardown continues. Bounded like the extractor deadline: teardown never hangs + /// on a child. + /// + private static readonly TimeSpan ReleaseTimeout = TimeSpan.FromSeconds(5); - foreach (var provider in providers) + /// + /// Cancels each provider's running tasks on and releases the + /// session. Best effort: one provider's fault is logged and the rest still release. + /// + /// Every background provider the document compiled. + /// The session of the conversation that ended. + /// The id of the conversation, for the log. + /// The logger of the session. + /// Cancels the release. +#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. + public static async ValueTask ReleaseAsync( + IReadOnlyList providers, + AgentSession session, + string conversationId, + ILogger logger, + CancellationToken cancellationToken) { - try - { - await provider.ReleaseSessionAsync(session, cancelRunning: true, ReleaseTimeout, cancellationToken) - .ConfigureAwait(false); - } - catch (Exception exception) when (exception is not OperationCanceledException) + ArgumentNullException.ThrowIfNull(providers); + ArgumentNullException.ThrowIfNull(session); + ArgumentException.ThrowIfNullOrEmpty(conversationId); + ArgumentNullException.ThrowIfNull(logger); + + foreach (BackgroundAgentsProvider provider in providers) { - Log.BackgroundReleaseFailed(logger, conversationId, exception); + try + { + await provider.ReleaseSessionAsync(session, cancelRunning: true, ReleaseTimeout, cancellationToken) + .ConfigureAwait(false); + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + Log.BackgroundReleaseFailed(logger, conversationId, exception); + } } } - } #pragma warning restore MAAI001 + } } diff --git a/src/AgentCore.Application/Runtime/Harness/BlobOwnerKey.cs b/src/AgentCore.Application/Runtime/Harness/BlobOwnerKey.cs index 978b78c7..c33091f2 100644 --- a/src/AgentCore.Application/Runtime/Harness/BlobOwnerKey.cs +++ b/src/AgentCore.Application/Runtime/Harness/BlobOwnerKey.cs @@ -1,18 +1,19 @@ -namespace AgentCore.Application.Runtime.Harness; - -/// -/// The key under which a background child's -/// session carries the id of the conversation that started it. -/// -/// -/// A parent run has a turn filed in TurnRegistry, so its providers read the conversation id there. -/// A child session has no turn: the framework starts it with fresh, empty state and null run -/// options. stamps this key when the session is created, so the -/// file.publish tool a background child calls can still find the conversation that owns the file -/// when the turn lookup finds nothing. -/// -internal static class BlobOwnerKey +namespace AgentCore.Application.Runtime.Harness { - /// The key. The value is the conversation id, a string. - public const string Value = "urn:agentcore:blob-owner"; + /// + /// The key under which a background child's + /// session carries the id of the conversation that started it. + /// + /// + /// A parent run has a turn filed in TurnRegistry, so its providers read the conversation id there. + /// A child session has no turn: the framework starts it with fresh, empty state and null run + /// options. stamps this key when the session is created, so the + /// file.publish tool a background child calls can still find the conversation that owns the file + /// when the turn lookup finds nothing. + /// + internal static class BlobOwnerKey + { + /// The key. The value is the conversation id, a string. + public const string Value = "urn:agentcore:blob-owner"; + } } diff --git a/src/AgentCore.Application/Runtime/Harness/CallerTimeZone.cs b/src/AgentCore.Application/Runtime/Harness/CallerTimeZone.cs index 8a7111a7..8797d5a4 100644 --- a/src/AgentCore.Application/Runtime/Harness/CallerTimeZone.cs +++ b/src/AgentCore.Application/Runtime/Harness/CallerTimeZone.cs @@ -1,57 +1,62 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// The time zone the person on a conversation is in, as the host learned it — from the browser, on the -/// request. The clock line reads the date in it instead of the server's zone. It is set per -/// request, not once: a person who travels moves the clock with them, and a request that names -/// no zone leaves the last one in place. -/// -public static class CallerTimeZone +namespace AgentCore.Application.Runtime.Harness { - /// The state key a background child's session carries the zone under. The value is a zone id. - internal const string Key = "urn:agentcore:time-zone"; - - /// Reads a zone id the way the host received it, or nothing when it names no zone. - /// An IANA id such as America/Chicago, or a Windows id. - /// The zone, or for an empty or unknown id. - public static TimeZoneInfo? Parse(string? id) + /// + /// The time zone the person on a conversation is in, as the host learned it — from the browser, on the + /// request. The clock line reads the date in it instead of the server's zone. It is set per + /// request, not once: a person who travels moves the clock with them, and a request that names + /// no zone leaves the last one in place. + /// + public static class CallerTimeZone { - if (string.IsNullOrWhiteSpace(id)) + /// The state key a background child's session carries the zone under. The value is a zone id. + internal const string Key = "urn:agentcore:time-zone"; + + /// Reads a zone id the way the host received it, or nothing when it names no zone. + /// An IANA id such as America/Chicago, or a Windows id. + /// The zone, or for an empty or unknown id. + public static TimeZoneInfo? Parse(string? id) { - return null; + if (string.IsNullOrWhiteSpace(id)) + { + return null; + } + + return TimeZoneInfo.TryFindSystemTimeZoneById(id.Trim(), out TimeZoneInfo? zone) ? zone : null; } - return TimeZoneInfo.TryFindSystemTimeZoneById(id.Trim(), out var zone) ? zone : null; - } + /// Puts the caller's zone on the conversation a session carries, replacing what was there. + /// A session this framework created: it names the conversation. + /// The zone the caller is in. + /// The session names no conversation. + public static void Set(AgentSession session, TimeZoneInfo zone) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(zone); - /// Puts the caller's zone on the conversation a session carries, replacing what was there. - /// A session this framework created: it names the conversation. - /// The zone the caller is in. - /// The session names no conversation. - public static void Set(AgentSession session, TimeZoneInfo zone) - { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(zone); + if (session.GetService() is not { } conversation) + { + throw new InvalidOperationException( + "The session is not one this agent created, so it names no call to put the zone on."); + } - if (session.GetService() is not { } conversation) + conversation.Runner.SetTimeZone(zone); + } + + /// Stamps the zone onto a child session, so a run on it reads the caller's date. + /// The child's session. + /// The zone the caller is in. + internal static void Stamp(AgentSession session, TimeZoneInfo zone) { - throw new InvalidOperationException( - "The session is not one this agent created, so it names no call to put the zone on."); + session.StateBag.SetValue(Key, zone.Id); } - conversation.Runner.SetTimeZone(zone); + /// Reads the zone stamped on a child session, or nothing when none was. + /// The session, or . + internal static TimeZoneInfo? Stamped(AgentSession? session) + { + return session is not null && session.StateBag.TryGetValue(Key, out string? id) ? Parse(id) : null; + } } - - /// Stamps the zone onto a child session, so a run on it reads the caller's date. - /// The child's session. - /// The zone the caller is in. - internal static void Stamp(AgentSession session, TimeZoneInfo zone) - => session.StateBag.SetValue(Key, zone.Id); - - /// Reads the zone stamped on a child session, or nothing when none was. - /// The session, or . - internal static TimeZoneInfo? Stamped(AgentSession? session) - => session is not null && session.StateBag.TryGetValue(Key, out var id) ? Parse(id) : null; } diff --git a/src/AgentCore.Application/Runtime/Harness/ClockContextProvider.cs b/src/AgentCore.Application/Runtime/Harness/ClockContextProvider.cs index 489bfb34..a7efbbc4 100644 --- a/src/AgentCore.Application/Runtime/Harness/ClockContextProvider.cs +++ b/src/AgentCore.Application/Runtime/Harness/ClockContextProvider.cs @@ -3,47 +3,48 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// Tells the model the current date and time, once per turn, as a system message below the -/// cached instructions. Without it a relative date such as "the past ten days" has no anchor -/// and the model has to ask the person for one. The zone is the caller's when the host named -/// one (), else the clock's own. -/// -internal sealed class ClockContextProvider(TimeProvider clock) : AIContextProvider +namespace AgentCore.Application.Runtime.Harness { - private readonly TimeProvider _clock = clock ?? throw new ArgumentNullException(nameof(clock)); - - /// - protected override ValueTask ProvideAIContextAsync( - InvokingContext context, CancellationToken cancellationToken = default) + /// + /// Tells the model the current date and time, once per turn, as a system message below the + /// cached instructions. Without it a relative date such as "the past ten days" has no anchor + /// and the model has to ask the person for one. The zone is the caller's when the host named + /// one (), else the clock's own. + /// + internal sealed class ClockContextProvider(TimeProvider clock) : AIContextProvider { - ArgumentNullException.ThrowIfNull(context); - - // The turn's own session carries the zone on a loop-built run; a background child's session - // carries it stamped; anything else reads the server's zone. - var zone = TurnRegistry.For(context.Session)?.TimeZone - ?? CallerTimeZone.Stamped(context.Session) - ?? _clock.LocalTimeZone; - - return new(new AIContext { Messages = [new ChatMessage(ChatRole.System, Describe(_clock, zone))] }); - } - - /// The one line the model reads, for one zone. - /// The clock to read. - /// The zone to read it in. - internal static string Describe(TimeProvider clock, TimeZoneInfo zone) - { - ArgumentNullException.ThrowIfNull(clock); - ArgumentNullException.ThrowIfNull(zone); - - var now = TimeZoneInfo.ConvertTime(clock.GetUtcNow(), zone); - var offset = now.Offset; - var sign = offset < TimeSpan.Zero ? "-" : "+"; - - return string.Create( - CultureInfo.InvariantCulture, - $"Today is {now:dddd}, {now:yyyy-MM-dd}. The local time is {now:HH:mm}, {zone.Id} (UTC{sign}{offset:hh\\:mm})."); + private readonly TimeProvider _clock = clock ?? throw new ArgumentNullException(nameof(clock)); + + /// + protected override ValueTask ProvideAIContextAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(context); + + // The turn's own session carries the zone on a loop-built run; a background child's session + // carries it stamped; anything else reads the server's zone. + TimeZoneInfo zone = TurnRegistry.For(context.Session)?.TimeZone + ?? CallerTimeZone.Stamped(context.Session) + ?? _clock.LocalTimeZone; + + return new(new AIContext { Messages = [new ChatMessage(ChatRole.System, Describe(_clock, zone))] }); + } + + /// The one line the model reads, for one zone. + /// The clock to read. + /// The zone to read it in. + internal static string Describe(TimeProvider clock, TimeZoneInfo zone) + { + ArgumentNullException.ThrowIfNull(clock); + ArgumentNullException.ThrowIfNull(zone); + + DateTimeOffset now = TimeZoneInfo.ConvertTime(clock.GetUtcNow(), zone); + TimeSpan offset = now.Offset; + string sign = offset < TimeSpan.Zero ? "-" : "+"; + + return string.Create( + CultureInfo.InvariantCulture, + $"Today is {now:dddd}, {now:yyyy-MM-dd}. The local time is {now:HH:mm}, {zone.Id} (UTC{sign}{offset:hh\\:mm})."); + } } } diff --git a/src/AgentCore.Application/Runtime/Harness/ConversationFilesProvider.cs b/src/AgentCore.Application/Runtime/Harness/ConversationFilesProvider.cs index 673f2ef7..a54b1445 100644 --- a/src/AgentCore.Application/Runtime/Harness/ConversationFilesProvider.cs +++ b/src/AgentCore.Application/Runtime/Harness/ConversationFilesProvider.cs @@ -1,70 +1,76 @@ using AgentCore.Application.Runtime.Turn; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Harness; - -// The store behind an agent's files: block, bound per invocation: the framework's -// own file-access tools do the work, rooted at the running conversation's workspace folder. A -// shared store cannot serve every conversation — the overrides take no session — so this builds -// the framework provider per conversation around the same options, exactly like the prefetch -// search provider. State keys and post-invocation storage forward to the shared template: -// accumulation lives in the session store, not on any instance. - -#pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - -internal sealed class ConversationFilesProvider : AIContextProvider, IDisposable +namespace AgentCore.Application.Runtime.Harness { - private const string NoTurnMessage = - "A files: tool runs only while a turn runs through a ConversationSession with a workspace root bound."; - - private readonly FileAccessProvider _template; - - private readonly FileAccessProviderOptions _options; - - public ConversationFilesProvider(string root, FileAccessProviderOptions options) - { - ArgumentNullException.ThrowIfNull(root); - ArgumentNullException.ThrowIfNull(options); - - _options = options; - _template = new FileAccessProvider(new FileSystemAgentFileStore(root), options); - } - - /// - public override IReadOnlyList StateKeys => _template.StateKeys; + // The store behind an agent's files: block, bound per invocation: the framework's + // own file-access tools do the work, rooted at the running conversation's workspace folder. A + // shared store cannot serve every conversation — the overrides take no session — so this builds + // the framework provider per conversation around the same options, exactly like the prefetch + // search provider. State keys and post-invocation storage forward to the shared template: + // accumulation lives in the session store, not on any instance. - /// - public override object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - - return serviceType.IsInstanceOfType(this) && serviceKey is null - ? this - : _template.GetService(serviceType, serviceKey); - } +#pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - /// - protected override async ValueTask InvokingCoreAsync( - InvokingContext context, CancellationToken cancellationToken = default) + internal sealed class ConversationFilesProvider : AIContextProvider, IDisposable { - var workspace = TurnRegistry.For(context.Session)?.Workspace - ?? throw new InvalidOperationException(NoTurnMessage); - - // Not using-declared on purpose: the tools this returns run after this method does, - // and disposing the provider would dispose the store out from under them. The store - // holds a path, not handles, so ordinary collection reclaims it. - FileAccessProvider inner = new(new FileSystemAgentFileStore(workspace), _options); - - return await inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); + private const string NoTurnMessage = + "A files: tool runs only while a turn runs through a ConversationSession with a workspace root bound."; + + private readonly FileAccessProvider _template; + + private readonly FileAccessProviderOptions _options; + + public ConversationFilesProvider(string root, FileAccessProviderOptions options) + { + ArgumentNullException.ThrowIfNull(root); + ArgumentNullException.ThrowIfNull(options); + + _options = options; + _template = new FileAccessProvider(new FileSystemAgentFileStore(root), options); + } + + /// + public override IReadOnlyList StateKeys => _template.StateKeys; + + /// + public override object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + + return serviceType.IsInstanceOfType(this) && serviceKey is null + ? this + : _template.GetService(serviceType, serviceKey); + } + + /// + protected override async ValueTask InvokingCoreAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + string workspace = TurnRegistry.For(context.Session)?.Workspace + ?? throw new InvalidOperationException(NoTurnMessage); + + // Not using-declared on purpose: the tools this returns run after this method does, + // and disposing the provider would dispose the store out from under them. The store + // holds a path, not handles, so ordinary collection reclaims it. + FileAccessProvider inner = new(new FileSystemAgentFileStore(workspace), _options); + + return await inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); + } + + /// + protected override ValueTask InvokedCoreAsync( + InvokedContext context, CancellationToken cancellationToken = default) + { + return _template.InvokedAsync(context, cancellationToken); + } + + /// + public void Dispose() + { + _template.Dispose(); + } } - /// - protected override ValueTask InvokedCoreAsync( - InvokedContext context, CancellationToken cancellationToken = default) - => _template.InvokedAsync(context, cancellationToken); - - /// - public void Dispose() => _template.Dispose(); -} - #pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Runtime/Harness/ConversationShellEnvironmentProvider.cs b/src/AgentCore.Application/Runtime/Harness/ConversationShellEnvironmentProvider.cs index 86bebaa5..e24a1a31 100644 --- a/src/AgentCore.Application/Runtime/Harness/ConversationShellEnvironmentProvider.cs +++ b/src/AgentCore.Application/Runtime/Harness/ConversationShellEnvironmentProvider.cs @@ -2,38 +2,39 @@ using Microsoft.Agents.AI; using Microsoft.Agents.AI.Tools.Shell; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// The instructions behind an agent's shell: block: the shell family, version, working -/// directory and CLI versions, probed once per call through that conversation's executor and rendered -/// with MAF's own formatter. No StateKeys — the snapshot lives on -/// and dies with the conversation, so resume re-probes a fresh environment. -/// -internal sealed class ConversationShellEnvironmentProvider : AIContextProvider +namespace AgentCore.Application.Runtime.Harness { - private const string NoTurnMessage = - "A shell: tool runs only while a turn runs through a ConversationSession with a workspace root bound."; - - private readonly ConversationShellOptions _options; - - public ConversationShellEnvironmentProvider(ConversationShellOptions options) + /// + /// The instructions behind an agent's shell: block: the shell family, version, working + /// directory and CLI versions, probed once per call through that conversation's executor and rendered + /// with MAF's own formatter. No StateKeys — the snapshot lives on + /// and dies with the conversation, so resume re-probes a fresh environment. + /// + internal sealed class ConversationShellEnvironmentProvider : AIContextProvider { - ArgumentNullException.ThrowIfNull(options); - _options = options; - } + private const string NoTurnMessage = + "A shell: tool runs only while a turn runs through a ConversationSession with a workspace root bound."; - protected override async ValueTask ProvideAIContextAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - var shells = TurnRegistry.For(context.Session)?.Shells - ?? throw new InvalidOperationException(NoTurnMessage); + private readonly ConversationShellOptions _options; - var snapshot = await shells.GetEnvironmentAsync(_options, cancellationToken).ConfigureAwait(false); + public ConversationShellEnvironmentProvider(ConversationShellOptions options) + { + ArgumentNullException.ThrowIfNull(options); + _options = options; + } - return new AIContext + protected override async ValueTask ProvideAIContextAsync( + InvokingContext context, CancellationToken cancellationToken = default) { - Instructions = ShellEnvironmentProvider.DefaultInstructionsFormatter(snapshot), - }; + ConversationShells shells = TurnRegistry.For(context.Session)?.Shells + ?? throw new InvalidOperationException(NoTurnMessage); + + ShellEnvironmentSnapshot snapshot = await shells.GetEnvironmentAsync(_options, cancellationToken).ConfigureAwait(false); + + return new AIContext + { + Instructions = ShellEnvironmentProvider.DefaultInstructionsFormatter(snapshot), + }; + } } } diff --git a/src/AgentCore.Application/Runtime/Harness/ConversationShellOptions.cs b/src/AgentCore.Application/Runtime/Harness/ConversationShellOptions.cs index e33d780e..082a3c33 100644 --- a/src/AgentCore.Application/Runtime/Harness/ConversationShellOptions.cs +++ b/src/AgentCore.Application/Runtime/Harness/ConversationShellOptions.cs @@ -1,29 +1,30 @@ -using AgentCore.Application.Configuration.Schema; using Microsoft.Agents.AI.Tools.Shell; +using ShellKind = AgentCore.Application.Configuration.Schema.ShellKind; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// What one agent's shell: block resolved to. Built once at compile time and shared by every -/// conversation of that agent; keys one executor per instance of this record. -/// -/// Where the shell runs. -/// The command filter, or for none. -/// How long one command may run, or for the executor default. -/// -/// The environment to add on top of the one the executor kind already supplies, with every -/// ${secret:name} reference already resolved. or empty for none. -/// -/// The per-stream output cap, or for the executor default. -/// The container image. only. -/// The Docker network mode. only. -/// The container memory limit. only. -internal sealed record ConversationShellOptions( - ShellKind Kind, - ShellPolicy? Policy, - TimeSpan? Timeout, - IReadOnlyDictionary? Env = null, - int? MaxOutputBytes = null, - string? Image = null, - string? Network = null, - long? MemoryBytes = null); +namespace AgentCore.Application.Runtime.Harness +{ + /// + /// What one agent's shell: block resolved to. Built once at compile time and shared by every + /// conversation of that agent; keys one executor per instance of this record. + /// + /// Where the shell runs. + /// The command filter, or for none. + /// How long one command may run, or for the executor default. + /// + /// The environment to add on top of the one the executor kind already supplies, with every + /// ${secret:name} reference already resolved. or empty for none. + /// + /// The per-stream output cap, or for the executor default. + /// The container image. only. + /// The Docker network mode. only. + /// The container memory limit. only. + internal sealed record ConversationShellOptions( + ShellKind Kind, + ShellPolicy? Policy, + TimeSpan? Timeout, + IReadOnlyDictionary? Env = null, + int? MaxOutputBytes = null, + string? Image = null, + string? Network = null, + long? MemoryBytes = null); +} diff --git a/src/AgentCore.Application/Runtime/Harness/ConversationShellProvider.cs b/src/AgentCore.Application/Runtime/Harness/ConversationShellProvider.cs index 15ecbc9c..3dc41bd3 100644 --- a/src/AgentCore.Application/Runtime/Harness/ConversationShellProvider.cs +++ b/src/AgentCore.Application/Runtime/Harness/ConversationShellProvider.cs @@ -1,36 +1,37 @@ using AgentCore.Application.Runtime.Turn; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// The context provider behind an agent's shell: block: on every invocation it hands the -/// model this conversation's shell executor as MAF's own tool. No instructions of our own — MAF's tool -/// description is what the model reads — and no StateKeys, because the shell keeps no -/// session state. -/// -internal sealed class ConversationShellProvider : AIContextProvider +namespace AgentCore.Application.Runtime.Harness { - private const string NoTurnMessage = - "A shell: tool runs only while a turn runs through a ConversationSession with a workspace root bound."; - - private readonly ConversationShellOptions _options; - - public ConversationShellProvider(ConversationShellOptions options) + /// + /// The context provider behind an agent's shell: block: on every invocation it hands the + /// model this conversation's shell executor as MAF's own tool. No instructions of our own — MAF's tool + /// description is what the model reads — and no StateKeys, because the shell keeps no + /// session state. + /// + internal sealed class ConversationShellProvider : AIContextProvider { - ArgumentNullException.ThrowIfNull(options); - _options = options; - } + private const string NoTurnMessage = + "A shell: tool runs only while a turn runs through a ConversationSession with a workspace root bound."; - protected override ValueTask ProvideAIContextAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - var shells = TurnRegistry.For(context.Session)?.Shells - ?? throw new InvalidOperationException(NoTurnMessage); + private readonly ConversationShellOptions _options; + + public ConversationShellProvider(ConversationShellOptions options) + { + ArgumentNullException.ThrowIfNull(options); + _options = options; + } - return new ValueTask(new AIContext + protected override ValueTask ProvideAIContextAsync( + InvokingContext context, CancellationToken cancellationToken = default) { - Tools = [shells.Get(_options).AsAIFunction(requireApproval: false)], - }); + ConversationShells shells = TurnRegistry.For(context.Session)?.Shells + ?? throw new InvalidOperationException(NoTurnMessage); + + return new ValueTask(new AIContext + { + Tools = [shells.Get(_options).AsAIFunction(requireApproval: false)], + }); + } } } diff --git a/src/AgentCore.Application/Runtime/Harness/ConversationShells.cs b/src/AgentCore.Application/Runtime/Harness/ConversationShells.cs index fa4d5886..547d6865 100644 --- a/src/AgentCore.Application/Runtime/Harness/ConversationShells.cs +++ b/src/AgentCore.Application/Runtime/Harness/ConversationShells.cs @@ -1,264 +1,265 @@ using System.Collections.ObjectModel; -using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Diagnostics; using Microsoft.Agents.AI.Tools.Shell; +using ShellKind = AgentCore.Application.Configuration.Schema.ShellKind; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// The shell executors one conversation has started. One per -/// instance the agent declares, created on first ask, plus one -/// probed environment snapshot per options for the model to read before its first command. -/// -internal sealed class ConversationShells : IAsyncDisposable +namespace AgentCore.Application.Runtime.Harness { - private readonly string _workspace; - - private readonly ILogger? _logger; + /// + /// The shell executors one conversation has started. One per + /// instance the agent declares, created on first ask, plus one + /// probed environment snapshot per options for the model to read before its first command. + /// + internal sealed class ConversationShells : IAsyncDisposable + { + private readonly string _workspace; - private readonly Lock _lock = new(); + private readonly ILogger? _logger; - private readonly Dictionary _executors = new(ReferenceEqualityComparer.Instance); + private readonly Lock _lock = new(); - private readonly Dictionary> _environments = new(ReferenceEqualityComparer.Instance); + private readonly Dictionary _executors = new(ReferenceEqualityComparer.Instance); - private bool _disposed; + private readonly Dictionary> _environments = new(ReferenceEqualityComparer.Instance); - /// Creates the holder for one conversation. - /// The conversation's workspace folder, the executor's working directory. - /// Where a failed dispose is logged, at Warning. May be . - public ConversationShells(string workspace, ILogger? logger) - { - ArgumentException.ThrowIfNullOrEmpty(workspace); - _workspace = workspace; - _logger = logger; - } + private bool _disposed; - /// - /// Gets this conversation's executor for , creating it on first ask. - /// - /// This conversation's shells have already been torn down. - public ShellExecutor Get(ConversationShellOptions options) - { - ArgumentNullException.ThrowIfNull(options); - - lock (_lock) + /// Creates the holder for one conversation. + /// The conversation's workspace folder, the executor's working directory. + /// Where a failed dispose is logged, at Warning. May be . + public ConversationShells(string workspace, ILogger? logger) { - ObjectDisposedException.ThrowIf(_disposed, this); - return GetLocked(options); + ArgumentException.ThrowIfNullOrEmpty(workspace); + _workspace = workspace; + _logger = logger; } - } - private ShellExecutor GetLocked(ConversationShellOptions options) - { - if (_executors.TryGetValue(options, out var existing)) + /// + /// Gets this conversation's executor for , creating it on first ask. + /// + /// This conversation's shells have already been torn down. + public ShellExecutor Get(ConversationShellOptions options) { - return existing; + ArgumentNullException.ThrowIfNull(options); + + lock (_lock) + { + ObjectDisposedException.ThrowIf(_disposed, this); + return GetLocked(options); + } } - var created = Create(options); - _executors.Add(options, created); - return created; - } + private ShellExecutor GetLocked(ConversationShellOptions options) + { + if (_executors.TryGetValue(options, out ShellExecutor? existing)) + { + return existing; + } - /// - /// Probes this conversation's executor for once and caches the snapshot - /// for the rest of the conversation. A faulted or cancelled probe is dropped so the next turn - /// retries; resume re-probes a fresh environment. - /// - /// This conversation's shells have already been torn down. - public Task GetEnvironmentAsync( - ConversationShellOptions options, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(options); + ShellExecutor created = Create(options); + _executors.Add(options, created); + return created; + } - lock (_lock) + /// + /// Probes this conversation's executor for once and caches the snapshot + /// for the rest of the conversation. A faulted or cancelled probe is dropped so the next turn + /// retries; resume re-probes a fresh environment. + /// + /// This conversation's shells have already been torn down. + public Task GetEnvironmentAsync( + ConversationShellOptions options, CancellationToken cancellationToken = default) { - ObjectDisposedException.ThrowIf(_disposed, this); + ArgumentNullException.ThrowIfNull(options); - if (_environments.TryGetValue(options, out var cached)) + lock (_lock) { - return cached; - } + ObjectDisposedException.ThrowIf(_disposed, this); - var probe = ProbeAsync(GetLocked(options), cancellationToken); - _environments.Add(options, probe); - _ = probe.ContinueWith( - static (task, state) => + if (_environments.TryGetValue(options, out Task? cached)) { - if ((task.IsFaulted || task.IsCanceled) && state is (ConversationShells shells, ConversationShellOptions key)) + return cached; + } + + Task probe = ProbeAsync(GetLocked(options), cancellationToken); + _environments.Add(options, probe); + _ = probe.ContinueWith( + static (task, state) => { - lock (shells._lock) + if ((task.IsFaulted || task.IsCanceled) && state is (ConversationShells shells, ConversationShellOptions key)) { - if (shells._environments.TryGetValue(key, out var current) - && ReferenceEquals(current, task)) + lock (shells._lock) { - shells._environments.Remove(key); + if (shells._environments.TryGetValue(key, out Task? current) + && ReferenceEquals(current, task)) + { + _ = shells._environments.Remove(key); + } } } - } - }, - (this, options), - CancellationToken.None, - TaskContinuationOptions.ExecuteSynchronously, - TaskScheduler.Default); - return probe; + }, + (this, options), + CancellationToken.None, + TaskContinuationOptions.ExecuteSynchronously, + TaskScheduler.Default); + return probe; + } } - } - - private static async Task ProbeAsync( - ShellExecutor executor, CancellationToken cancellationToken) - { - // A throwaway MAF prober per conversation: its single-executor pin is harmless because the - // instance never leaves this probe. Probing runs commands, so for kind: docker the - // container starts on the first turn even when the model never runs a command. That - // is the price of the block: shell: declares intent, and the hints matter most - // before the first command. - ShellEnvironmentProvider prober = new(executor); - return await prober.RefreshAsync(cancellationToken).ConfigureAwait(false); - } - /// - /// The host variables copied into a executor's clean environment, - /// on top of whatever the executor already preserves on its own. LANG missing breaks locale-aware - /// tools (encoding, sorting); TMPDIR missing sends scratch writes to a directory a sandboxed host - /// may not grant. PATH and HOME are listed too, so this allowlist does not depend on the - /// executor's own choice of what it preserves. - /// - private static readonly string[] CleanEnvironmentAllowlist = ["PATH", "HOME", "LANG", "TMPDIR"]; - - private ShellExecutor Create(ConversationShellOptions options) - { - switch (options.Kind) + private static async Task ProbeAsync( + ShellExecutor executor, CancellationToken cancellationToken) { - case ShellKind.Local: - LocalShellExecutorOptions localOptions = new() - { - WorkingDirectory = _workspace, - Mode = ShellMode.Persistent, - ConfineWorkingDirectory = true, - AcknowledgeUnsafe = true, - CleanEnvironment = true, - Environment = BuildLocalEnvironment(options.Env), - Policy = options.Policy, - }; - if (options.Timeout is { } localTimeout) - { - localOptions.Timeout = localTimeout; - } + // A throwaway MAF prober per conversation: its single-executor pin is harmless because the + // instance never leaves this probe. Probing runs commands, so for kind: docker the + // container starts on the first turn even when the model never runs a command. That + // is the price of the block: shell: declares intent, and the hints matter most + // before the first command. + ShellEnvironmentProvider prober = new(executor); + return await prober.RefreshAsync(cancellationToken).ConfigureAwait(false); + } - if (options.MaxOutputBytes is { } localMaxOutputBytes) - { - localOptions.MaxOutputBytes = localMaxOutputBytes; - } + /// + /// The host variables copied into a executor's clean environment, + /// on top of whatever the executor already preserves on its own. LANG missing breaks locale-aware + /// tools (encoding, sorting); TMPDIR missing sends scratch writes to a directory a sandboxed host + /// may not grant. PATH and HOME are listed too, so this allowlist does not depend on the + /// executor's own choice of what it preserves. + /// + private static readonly string[] CleanEnvironmentAllowlist = ["PATH", "HOME", "LANG", "TMPDIR"]; - return new LocalShellExecutor(localOptions); + private ShellExecutor Create(ConversationShellOptions options) + { + switch (options.Kind) + { + case ShellKind.Local: + LocalShellExecutorOptions localOptions = new() + { + WorkingDirectory = _workspace, + Mode = ShellMode.Persistent, + ConfineWorkingDirectory = true, + AcknowledgeUnsafe = true, + CleanEnvironment = true, + Environment = BuildLocalEnvironment(options.Env), + Policy = options.Policy, + }; + if (options.Timeout is { } localTimeout) + { + localOptions.Timeout = localTimeout; + } - case ShellKind.Docker: - // MountReadonly is false because the workspace is this conversation's own scratch folder, - // and files: already writes to it. Every other Docker default (network none, - // read-only root, nobody user, pids limit) stays unless the shell: block overrides it. - DockerShellExecutorOptions dockerOptions = new() - { - HostWorkdir = _workspace, - MountReadonly = false, - Environment = options.Env ?? ReadOnlyDictionary.Empty, - Policy = options.Policy, - }; - if (options.Timeout is { } dockerTimeout) - { - dockerOptions.Timeout = dockerTimeout; - } + if (options.MaxOutputBytes is { } localMaxOutputBytes) + { + localOptions.MaxOutputBytes = localMaxOutputBytes; + } - if (options.MaxOutputBytes is { } dockerMaxOutputBytes) - { - dockerOptions.MaxOutputBytes = dockerMaxOutputBytes; - } + return new LocalShellExecutor(localOptions); - if (options.Image is { } image) - { - dockerOptions.Image = image; - } + case ShellKind.Docker: + // MountReadonly is false because the workspace is this conversation's own scratch folder, + // and files: already writes to it. Every other Docker default (network none, + // read-only root, nobody user, pids limit) stays unless the shell: block overrides it. + DockerShellExecutorOptions dockerOptions = new() + { + HostWorkdir = _workspace, + MountReadonly = false, + Environment = options.Env ?? ReadOnlyDictionary.Empty, + Policy = options.Policy, + }; + if (options.Timeout is { } dockerTimeout) + { + dockerOptions.Timeout = dockerTimeout; + } - if (options.Network is { } network) - { - dockerOptions.Network = network; - } + if (options.MaxOutputBytes is { } dockerMaxOutputBytes) + { + dockerOptions.MaxOutputBytes = dockerMaxOutputBytes; + } - if (options.MemoryBytes is { } memoryBytes) - { - dockerOptions.MemoryBytes = memoryBytes; - } + if (options.Image is { } image) + { + dockerOptions.Image = image; + } - return new DockerShellExecutor(dockerOptions); + if (options.Network is { } network) + { + dockerOptions.Network = network; + } - default: - throw new ArgumentOutOfRangeException(nameof(options), options.Kind, "Unknown shell kind."); - } - } + if (options.MemoryBytes is { } memoryBytes) + { + dockerOptions.MemoryBytes = memoryBytes; + } - /// - /// Builds a executor's environment: the agent's declared - /// shell.env, then backfilled from this process's - /// own environment for whatever shell.env did not already set. - /// - private static Dictionary BuildLocalEnvironment(IReadOnlyDictionary? declared) - { - Dictionary environment = new(StringComparer.Ordinal); + return new DockerShellExecutor(dockerOptions); - if (declared is not null) - { - foreach (var (key, value) in declared) - { - environment[key] = value; + default: + throw new ArgumentOutOfRangeException(nameof(options), options.Kind, "Unknown shell kind."); } } - foreach (var name in CleanEnvironmentAllowlist) + /// + /// Builds a executor's environment: the agent's declared + /// shell.env, then backfilled from this process's + /// own environment for whatever shell.env did not already set. + /// + private static Dictionary BuildLocalEnvironment(IReadOnlyDictionary? declared) { - if (!environment.ContainsKey(name) && Environment.GetEnvironmentVariable(name) is { } value) + Dictionary environment = new(StringComparer.Ordinal); + + if (declared is not null) { - environment[name] = value; + foreach ((string? key, string? value) in declared) + { + environment[key] = value; + } } - } - - return environment; - } - - /// - /// Disposes every executor this conversation started. Idempotent, and never throws out: a failed - /// dispose is logged at Warning through instead. A second - /// concurrent caller returns immediately rather than wait for the first dispose to finish — the - /// executors are only ever taken out and disposed once. - /// - public async ValueTask DisposeAsync() - { - List toDispose; - lock (_lock) - { - if (_disposed) + foreach (string name in CleanEnvironmentAllowlist) { - return; + if (!environment.ContainsKey(name) && Environment.GetEnvironmentVariable(name) is { } value) + { + environment[name] = value; + } } - _disposed = true; - toDispose = [.. _executors.Values]; - _executors.Clear(); + return environment; } - foreach (var executor in toDispose) + /// + /// Disposes every executor this conversation started. Idempotent, and never throws out: a failed + /// dispose is logged at Warning through instead. A second + /// concurrent caller returns immediately rather than wait for the first dispose to finish — the + /// executors are only ever taken out and disposed once. + /// + public async ValueTask DisposeAsync() { - try + List toDispose; + + lock (_lock) { - await executor.DisposeAsync().ConfigureAwait(false); + if (_disposed) + { + return; + } + + _disposed = true; + toDispose = [.. _executors.Values]; + _executors.Clear(); } - catch (Exception exception) + + foreach (ShellExecutor executor in toDispose) { - if (_logger is not null) + try + { + await executor.DisposeAsync().ConfigureAwait(false); + } + catch (Exception exception) { - Log.ShellDisposeFailed(_logger, _workspace, exception); + if (_logger is not null) + { + Log.ShellDisposeFailed(_logger, _workspace, exception); + } } } } diff --git a/src/AgentCore.Application/Runtime/Harness/HarnessSessionState.cs b/src/AgentCore.Application/Runtime/Harness/HarnessSessionState.cs index 5929aa9a..926d560f 100644 --- a/src/AgentCore.Application/Runtime/Harness/HarnessSessionState.cs +++ b/src/AgentCore.Application/Runtime/Harness/HarnessSessionState.cs @@ -3,63 +3,64 @@ using System.Text.Json.Nodes; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// Moves the harness providers' MAF state — todos:, mode:, memory:, -/// files:, background: — and the approval queue and standing rules between a live -/// 's state bag and . -/// -internal static class HarnessSessionState +namespace AgentCore.Application.Runtime.Harness { - private static readonly IReadOnlyDictionary Empty = - ReadOnlyDictionary.Empty; - /// - /// Reads the harness providers' state out of , keeping only the keys - /// names. + /// Moves the harness providers' MAF state — todos:, mode:, memory:, + /// files:, background: — and the approval queue and standing rules between a live + /// 's state bag and . /// - /// The live session, or . - /// The harness providers' state keys this document declares. - /// - /// The kept keys, each value cloned off the bag's own serialization. Empty for a - /// session or an empty — the bag is never - /// serialized in that case. The transcript lives outside the bag, so what is serialized - /// here is provider and approval state only. - /// - public static IReadOnlyDictionary Capture(AgentSession? session, IReadOnlySet keys) + internal static class HarnessSessionState { - if (session is null || keys.Count == 0) - { - return Empty; - } + private static readonly IReadOnlyDictionary Empty = + ReadOnlyDictionary.Empty; - var serialized = session.StateBag.Serialize(); - Dictionary providers = new(StringComparer.Ordinal); - - foreach (var property in serialized.EnumerateObject().Where(property => keys.Contains(property.Name))) + /// + /// Reads the harness providers' state out of , keeping only the keys + /// names. + /// + /// The live session, or . + /// The harness providers' state keys this document declares. + /// + /// The kept keys, each value cloned off the bag's own serialization. Empty for a + /// session or an empty — the bag is never + /// serialized in that case. The transcript lives outside the bag, so what is serialized + /// here is provider and approval state only. + /// + public static IReadOnlyDictionary Capture(AgentSession? session, IReadOnlySet keys) { - providers[property.Name] = property.Value.Clone(); - } + if (session is null || keys.Count == 0) + { + return Empty; + } - return providers.Count == 0 ? Empty : providers; - } + JsonElement serialized = session.StateBag.Serialize(); + Dictionary providers = new(StringComparer.Ordinal); - /// - /// Builds the envelope expects: { "stateBag": - /// { key: element, ... } }, with no other member. - /// - public static JsonElement Wrap(IReadOnlyDictionary providers) - { - JsonObject stateBag = []; + foreach (JsonProperty property in serialized.EnumerateObject().Where(property => keys.Contains(property.Name))) + { + providers[property.Name] = property.Value.Clone(); + } - foreach (var (key, element) in providers) - { - stateBag[key] = JsonSerializer.SerializeToNode(element); + return providers.Count == 0 ? Empty : providers; } - JsonObject envelope = new() { ["stateBag"] = stateBag }; + /// + /// Builds the envelope expects: { "stateBag": + /// { key: element, ... } }, with no other member. + /// + public static JsonElement Wrap(IReadOnlyDictionary providers) + { + JsonObject stateBag = []; - return JsonSerializer.SerializeToElement(envelope); + foreach ((string? key, JsonElement element) in providers) + { + stateBag[key] = JsonSerializer.SerializeToNode(element); + } + + JsonObject envelope = new() { ["stateBag"] = stateBag }; + + return JsonSerializer.SerializeToElement(envelope); + } } } diff --git a/src/AgentCore.Application/Runtime/Harness/PendingApprovalQueue.cs b/src/AgentCore.Application/Runtime/Harness/PendingApprovalQueue.cs index 830404ec..6fc62af8 100644 --- a/src/AgentCore.Application/Runtime/Harness/PendingApprovalQueue.cs +++ b/src/AgentCore.Application/Runtime/Harness/PendingApprovalQueue.cs @@ -2,116 +2,121 @@ using AgentCore.Domain; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Harness; - -/// -/// The framework's pending approval queue, read off a session's state bag. The queue is a JSON -/// array of {toolCall: {name, arguments, conversationId}, requiresConfirmation, requestId} under -/// — a MAF-internal shape pinned by probe -/// docs/probes/harness-agentic/approval-roundtrip/, not a contract. Every read here is -/// lenient: an entry that lost its shape is skipped, never thrown, because the turn must end -/// however the queue looks. -/// -internal static class PendingApprovalQueue +namespace AgentCore.Application.Runtime.Harness { - /// What the function-invocation layer names its queue in the state bag. - internal const string PendingStateKey = "_pendingApprovalRequests"; - - /// What the approval layer names its standing and auto rules in the state bag. - internal const string StandingStateKey = "toolApprovalState"; - - /// Reads the queue out of a serialized state bag. - /// What AgentSessionStateBag.Serialize produced. - /// The pending approvals, oldest first; empty when the bag carries no queue. - internal static IReadOnlyList Read(JsonElement bag) + /// + /// The framework's pending approval queue, read off a session's state bag. The queue is a JSON + /// array of {toolCall: {name, arguments, conversationId}, requiresConfirmation, requestId} under + /// — a MAF-internal shape pinned by probe + /// docs/probes/harness-agentic/approval-roundtrip/, not a contract. Every read here is + /// lenient: an entry that lost its shape is skipped, never thrown, because the turn must end + /// however the queue looks. + /// + internal static class PendingApprovalQueue { - if (!bag.TryGetProperty(PendingStateKey, out var queue) - || queue.ValueKind != JsonValueKind.Array) - { - return []; - } + /// What the function-invocation layer names its queue in the state bag. + internal const string PendingStateKey = "_pendingApprovalRequests"; + + /// What the approval layer names its standing and auto rules in the state bag. + internal const string StandingStateKey = "toolApprovalState"; - List pending = []; - foreach (var entry in queue.EnumerateArray()) + /// Reads the queue out of a serialized state bag. + /// What AgentSessionStateBag.Serialize produced. + /// The pending approvals, oldest first; empty when the bag carries no queue. + internal static IReadOnlyList Read(JsonElement bag) { - if (entry.ValueKind != JsonValueKind.Object - || !entry.TryGetProperty("requestId", out var id) - || id.ValueKind != JsonValueKind.String - || !entry.TryGetProperty("toolCall", out var conversation) - || conversation.ValueKind != JsonValueKind.Object - || !conversation.TryGetProperty("name", out var name) - || name.ValueKind != JsonValueKind.String) + if (!bag.TryGetProperty(PendingStateKey, out JsonElement queue) + || queue.ValueKind != JsonValueKind.Array) { - continue; + return []; } - using var empty = JsonDocument.Parse("{}"); - var arguments = conversation.TryGetProperty("arguments", out var args) && args.ValueKind == JsonValueKind.Object - ? args.Clone() - : empty.RootElement.Clone(); + List pending = []; + foreach (JsonElement entry in queue.EnumerateArray()) + { + if (entry.ValueKind != JsonValueKind.Object + || !entry.TryGetProperty("requestId", out JsonElement id) + || id.ValueKind != JsonValueKind.String + || !entry.TryGetProperty("toolCall", out JsonElement conversation) + || conversation.ValueKind != JsonValueKind.Object + || !conversation.TryGetProperty("name", out JsonElement name) + || name.ValueKind != JsonValueKind.String) + { + continue; + } - pending.Add(new PendingApproval( - id.GetString()!, - name.GetString()!, - arguments)); - } + using JsonDocument empty = JsonDocument.Parse("{}"); + JsonElement arguments = conversation.TryGetProperty("arguments", out JsonElement args) && args.ValueKind == JsonValueKind.Object + ? args.Clone() + : empty.RootElement.Clone(); - return pending; - } + pending.Add(new PendingApproval( + id.GetString()!, + name.GetString()!, + arguments)); + } - /// Builds the answer message for one pending request. - /// What AgentSessionStateBag.Serialize produced. - /// The id the caller answers. - /// Whether the tool may run. - /// The user message carrying the approval response, or when no queued request carries that id. - internal static ChatMessage? AnswerFor(JsonElement bag, string requestId, bool approved) - { - if (!bag.TryGetProperty(PendingStateKey, out var queue) - || queue.ValueKind != JsonValueKind.Array) - { - return null; + return pending; } - foreach (var entry in queue.EnumerateArray()) + /// Builds the answer message for one pending request. + /// What AgentSessionStateBag.Serialize produced. + /// The id the caller answers. + /// Whether the tool may run. + /// The user message carrying the approval response, or when no queued request carries that id. + internal static ChatMessage? AnswerFor(JsonElement bag, string requestId, bool approved) { - if (entry.ValueKind != JsonValueKind.Object - || !entry.TryGetProperty("requestId", out var id) - || id.GetString() != requestId - || !entry.TryGetProperty("toolCall", out var conversation) - || conversation.ValueKind != JsonValueKind.Object - || !conversation.TryGetProperty("name", out var name) - || name.ValueKind != JsonValueKind.String - || !conversation.TryGetProperty("callId", out var conversationId) - || conversationId.ValueKind != JsonValueKind.String) + if (!bag.TryGetProperty(PendingStateKey, out JsonElement queue) + || queue.ValueKind != JsonValueKind.Array) { - continue; + return null; } - Dictionary arguments = new(StringComparer.Ordinal); - if (conversation.TryGetProperty("arguments", out var args) && args.ValueKind == JsonValueKind.Object) + foreach (JsonElement entry in queue.EnumerateArray()) { - foreach (var argument in args.EnumerateObject()) + if (entry.ValueKind != JsonValueKind.Object + || !entry.TryGetProperty("requestId", out JsonElement id) + || id.GetString() != requestId + || !entry.TryGetProperty("toolCall", out JsonElement conversation) + || conversation.ValueKind != JsonValueKind.Object + || !conversation.TryGetProperty("name", out JsonElement name) + || name.ValueKind != JsonValueKind.String + || !conversation.TryGetProperty("callId", out JsonElement conversationId) + || conversationId.ValueKind != JsonValueKind.String) + { + continue; + } + + Dictionary arguments = new(StringComparer.Ordinal); + if (conversation.TryGetProperty("arguments", out JsonElement args) && args.ValueKind == JsonValueKind.Object) { - arguments[argument.Name] = ValueOf(argument.Value); + foreach (JsonProperty argument in args.EnumerateObject()) + { + arguments[argument.Name] = ValueOf(argument.Value); + } } + + FunctionCallContent toolCall = new(conversationId.GetString()!, name.GetString()!, arguments); + return new ChatMessage(ChatRole.User, [new ToolApprovalResponseContent(requestId, approved, toolCall)]); } - var toolCall = new FunctionCallContent(conversationId.GetString()!, name.GetString()!, arguments); - return new ChatMessage(ChatRole.User, [new ToolApprovalResponseContent(requestId, approved, toolCall)]); + return null; } - return null; + private static object? ValueOf(JsonElement element) + { + return element.ValueKind switch + { + JsonValueKind.Object => element.EnumerateObject() + .ToDictionary(property => property.Name, property => ValueOf(property.Value), StringComparer.Ordinal), + JsonValueKind.Array => element.EnumerateArray().Select(ValueOf).ToList(), + JsonValueKind.String => element.GetString(), + JsonValueKind.Number => element.TryGetInt64(out long integer) ? integer : element.GetDouble(), + JsonValueKind.True => true, + JsonValueKind.False => false, + JsonValueKind.Null or JsonValueKind.Undefined => null, + _ => null, + }; + } } - - private static object? ValueOf(JsonElement element) => element.ValueKind switch - { - JsonValueKind.Object => element.EnumerateObject() - .ToDictionary(property => property.Name, property => ValueOf(property.Value), StringComparer.Ordinal), - JsonValueKind.Array => element.EnumerateArray().Select(ValueOf).ToList(), - JsonValueKind.String => element.GetString(), - JsonValueKind.Number => element.TryGetInt64(out var integer) ? integer : element.GetDouble(), - JsonValueKind.True => true, - JsonValueKind.False => false, - _ => null, - }; } diff --git a/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs b/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs index 7aba873d..99b89971 100644 --- a/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs +++ b/src/AgentCore.Application/Runtime/ModelFacingChatClient.cs @@ -2,58 +2,64 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -/// Takes what only the caller can use out of the history before the model sees it. -internal sealed class ModelFacingChatClient(IChatClient inner) : DelegatingChatClient(inner) +namespace AgentCore.Application.Runtime { - public override async Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + /// Takes what only the caller can use out of the history before the model sees it. + internal sealed class ModelFacingChatClient(IChatClient inner) : DelegatingChatClient(inner) { - using var _ = KeyHider.Hide(options); - return await base.GetResponseAsync(Strip(messages), options, cancellationToken).ConfigureAwait(false); - } + public override async Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + using KeyHider _ = KeyHider.Hide(options); + return await base.GetResponseAsync(Strip(messages), options, cancellationToken).ConfigureAwait(false); + } - public override async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - using var _ = KeyHider.Hide(options); - await foreach (var update in base.GetStreamingResponseAsync(Strip(messages), options, cancellationToken).ConfigureAwait(false)) + public override async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - yield return update; + using KeyHider _ = KeyHider.Hide(options); + await foreach (ChatResponseUpdate? update in base.GetStreamingResponseAsync(Strip(messages), options, cancellationToken).ConfigureAwait(false)) + { + yield return update; + } + } + + private static IEnumerable Strip(IEnumerable messages) + { + return messages.Select(static message => message.WithoutHostContent()); } - } - private static IEnumerable Strip(IEnumerable messages) - => messages.Select(static message => message.WithoutHostContent()); + // The loop files the turn on the run's own options for the invoking client above; the + // vendor below must never see it. Hidden in place around the inner call and restored + // after: the options object belongs to this one run, and cloning it would drop vendor + // fields this layer knows nothing about. + private sealed class KeyHider : IDisposable + { + private readonly ChatOptions? _options; - // The loop files the turn on the run's own options for the invoking client above; the - // vendor below must never see it. Hidden in place around the inner call and restored - // after: the options object belongs to this one run, and cloning it would drop vendor - // fields this layer knows nothing about. - private sealed class KeyHider : IDisposable - { - private readonly ChatOptions? _options; + private readonly object? _held; - private readonly object? _held; - - private readonly bool _took; + private readonly bool _took; - private KeyHider(ChatOptions? options) - { - _options = options; - _took = options?.AdditionalProperties?.Remove(TurnInvocation.ArgumentsKey, out _held) ?? false; - } + private KeyHider(ChatOptions? options) + { + _options = options; + _took = options?.AdditionalProperties?.Remove(TurnInvocation.ArgumentsKey, out _held) ?? false; + } - public static KeyHider Hide(ChatOptions? options) => new(options); + public static KeyHider Hide(ChatOptions? options) + { + return new(options); + } - public void Dispose() - { - if (_took && _options?.AdditionalProperties is { } kept) + public void Dispose() { - kept[TurnInvocation.ArgumentsKey] = _held; + if (_took && _options?.AdditionalProperties is { } kept) + { + kept[TurnInvocation.ArgumentsKey] = _held; + } } } } diff --git a/src/AgentCore.Application/Runtime/ModerationAgent.cs b/src/AgentCore.Application/Runtime/ModerationAgent.cs index b73d97bd..d53f8c75 100644 --- a/src/AgentCore.Application/Runtime/ModerationAgent.cs +++ b/src/AgentCore.Application/Runtime/ModerationAgent.cs @@ -3,175 +3,178 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -/// -/// Refuses a turn whose caller text the moderation endpoint flagged, before the agent runs. -/// -internal sealed class ModerationAgent : DelegatingAIAgent +namespace AgentCore.Application.Runtime { - /// How long a turn waits for the moderation endpoint before it answers anyway. - internal static readonly TimeSpan DefaultTimeout = TimeSpan.FromSeconds(2); - - private readonly PromptModerator _moderator; - private readonly string _refusalReply; - private readonly TimeSpan _timeout; - - /// Puts moderation in front of one turn agent. - /// The agent a turn runs. - /// The endpoint seam. - /// What a refused turn speaks. Never the fallback line. - /// How long the caller waits for a verdict before the turn runs anyway. - public ModerationAgent(AIAgent inner, PromptModerator moderator, string refusalReply, TimeSpan timeout) - : base(inner) - { - ArgumentNullException.ThrowIfNull(moderator); - ArgumentNullException.ThrowIfNull(refusalReply); - - _moderator = moderator; - _refusalReply = refusalReply; - _timeout = timeout; - } - - /// - protected override async Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) + /// + /// Refuses a turn whose caller text the moderation endpoint flagged, before the agent runs. + /// + internal sealed class ModerationAgent : DelegatingAIAgent { - ArgumentNullException.ThrowIfNull(messages); - - var verdict = await JudgeAsync(messages, cancellationToken).ConfigureAwait(false); - if (verdict.Moderation is ModerationOutcome.Flagged) + /// How long a turn waits for the moderation endpoint before it answers anyway. + internal static readonly TimeSpan DefaultTimeout = TimeSpan.FromSeconds(2); + + private readonly PromptModerator _moderator; + private readonly string _refusalReply; + private readonly TimeSpan _timeout; + + /// Puts moderation in front of one turn agent. + /// The agent a turn runs. + /// The endpoint seam. + /// What a refused turn speaks. Never the fallback line. + /// How long the caller waits for a verdict before the turn runs anyway. + public ModerationAgent(AIAgent inner, PromptModerator moderator, string refusalReply, TimeSpan timeout) + : base(inner) { - AgentResponse refusal = new(new ChatMessage(ChatRole.Assistant, _refusalReply)); - Attach(refusal.AdditionalProperties ??= [], verdict); - return refusal; - } + ArgumentNullException.ThrowIfNull(moderator); + ArgumentNullException.ThrowIfNull(refusalReply); - var response = await base.RunCoreAsync(messages, session, options, cancellationToken) - .ConfigureAwait(false); + _moderator = moderator; + _refusalReply = refusalReply; + _timeout = timeout; + } - Attach(response.AdditionalProperties ??= [], verdict); - return response; - } + /// + protected override async Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - /// - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + TurnDisposition verdict = await JudgeAsync(messages, cancellationToken).ConfigureAwait(false); + if (verdict.Moderation is ModerationOutcome.Flagged) + { + AgentResponse refusal = new(new ChatMessage(ChatRole.Assistant, _refusalReply)); + Attach(refusal.AdditionalProperties ??= [], verdict); + return refusal; + } - return RunCoreStreamingCoreAsync(messages, session, options, cancellationToken); - } + AgentResponse response = await base.RunCoreAsync(messages, session, options, cancellationToken) + .ConfigureAwait(false); - /// Streams the verdict marker and the run, or the refusal when the caller is flagged. - private async IAsyncEnumerable RunCoreStreamingCoreAsync( - IEnumerable messages, - AgentSession? session, - AgentRunOptions? options, - [EnumeratorCancellation] CancellationToken cancellationToken) - { - var verdict = await JudgeAsync(messages, cancellationToken).ConfigureAwait(false); - if (verdict.Moderation is ModerationOutcome.Flagged) - { - AgentResponseUpdate refusal = new(ChatRole.Assistant, _refusalReply); - Attach(refusal.AdditionalProperties ??= [], verdict); - yield return refusal; - yield break; + Attach(response.AdditionalProperties ??= [], verdict); + return response; } - // A leading update with EMPTY contents. Empty contents contribute no text, so the caller's - // audio is untouched and the turn seam drops the update before the host ever sees it. - // Update-level properties do not survive streaming coalescing, which is why the marker rides - // an update of its own rather than the assistant message the updates fold into. - AgentResponseUpdate marker = new() { Role = ChatRole.Assistant }; - Attach(marker.AdditionalProperties ??= [], verdict); - yield return marker; - - await foreach (var update in base.RunCoreStreamingAsync(messages, session, options, cancellationToken) - .ConfigureAwait(false)) + /// + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) { - yield return update; - } - } + ArgumentNullException.ThrowIfNull(messages); - /// Reads the endpoint's verdict on what the caller said, and never lets it drop a turn. - /// The whole request. The caller's words are its last user message. - /// The host's own token. A cancel it asked for still propagates. - /// The verdict, as the disposition the turn loop reads. - private async ValueTask JudgeAsync( - IEnumerable messages, - CancellationToken cancellationToken) - { - var callerText = CallerText(messages); + return RunCoreStreamingCoreAsync(messages, session, options, cancellationToken); + } - IReadOnlyList categories; - using (var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)) + /// Streams the verdict marker and the run, or the refusal when the caller is flagged. + private async IAsyncEnumerable RunCoreStreamingCoreAsync( + IEnumerable messages, + AgentSession? session, + AgentRunOptions? options, + [EnumeratorCancellation] CancellationToken cancellationToken) { - deadline.CancelAfter(_timeout); - try + TurnDisposition verdict = await JudgeAsync(messages, cancellationToken).ConfigureAwait(false); + if (verdict.Moderation is ModerationOutcome.Flagged) { - categories = await _moderator.FlaggedCategoriesAsync(callerText, deadline.Token) - .ConfigureAwait(false); + AgentResponseUpdate refusal = new(ChatRole.Assistant, _refusalReply); + Attach(refusal.AdditionalProperties ??= [], verdict); + yield return refusal; + yield break; } - catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + + // A leading update with EMPTY contents. Empty contents contribute no text, so the caller's + // audio is untouched and the turn seam drops the update before the host ever sees it. + // Update-level properties do not survive streaming coalescing, which is why the marker rides + // an update of its own rather than the assistant message the updates fold into. + AgentResponseUpdate marker = new() { Role = ChatRole.Assistant }; + Attach(marker.AdditionalProperties ??= [], verdict); + yield return marker; + + await foreach (AgentResponseUpdate? update in base.RunCoreStreamingAsync(messages, session, options, cancellationToken) + .ConfigureAwait(false)) { - // The deadline passed, and not the caller's own token. A cancel the host asked for - // still propagates, because that is the host ending the turn and not a slow vendor. - return Unavailable(ConversationSession.ModerationTimedOutReason); + yield return update; } + } + + /// Reads the endpoint's verdict on what the caller said, and never lets it drop a turn. + /// The whole request. The caller's words are its last user message. + /// The host's own token. A cancel it asked for still propagates. + /// The verdict, as the disposition the turn loop reads. + private async ValueTask JudgeAsync( + IEnumerable messages, + CancellationToken cancellationToken) + { + string callerText = CallerText(messages); + + IReadOnlyList categories; + using (CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)) + { + deadline.CancelAfter(_timeout); + try + { + categories = await _moderator.FlaggedCategoriesAsync(callerText, deadline.Token) + .ConfigureAwait(false); + } + catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + { + // The deadline passed, and not the caller's own token. A cancel the host asked for + // still propagates, because that is the host ending the turn and not a slow vendor. + return Unavailable(ConversationSession.ModerationTimedOutReason); + } #pragma warning disable CA1031 // Moderation guards the turn. It must never be the thing that drops it. - catch (Exception exception) when (exception is not OperationCanceledException) + catch (Exception exception) when (exception is not OperationCanceledException) #pragma warning restore CA1031 - { - return Unavailable(ConversationSession.ModerationFaultedReason); + { + return Unavailable(ConversationSession.ModerationFaultedReason); + } } - } - return categories.Count == 0 - ? new TurnDisposition(ModerationOutcome.Clean, null, FallbackCause.None, null, null) + return categories.Count == 0 + ? new TurnDisposition(ModerationOutcome.Clean, null, FallbackCause.None, null, null) - // The order is the endpoint's, because AuditPayloadKeys.ModerationCategories promises it. - : new TurnDisposition( - ModerationOutcome.Flagged, string.Join(',', categories), FallbackCause.None, null, null); - } + // The order is the endpoint's, because AuditPayloadKeys.ModerationCategories promises it. + : new TurnDisposition( + ModerationOutcome.Flagged, string.Join(',', categories), FallbackCause.None, null, null); + } - private static TurnDisposition Unavailable(string reason) - => new(ModerationOutcome.Unavailable, null, FallbackCause.None, null, reason); + private static TurnDisposition Unavailable(string reason) + { + return new(ModerationOutcome.Unavailable, null, FallbackCause.None, null, reason); + } - /// Reads the words the caller spoke this turn out of the whole request. - /// The request the turn is about to run. - /// The text of the last user message, or an empty string when the request holds none. - private static string CallerText(IEnumerable messages) - { - string? spoken = null; - foreach (var message in messages) + /// Reads the words the caller spoke this turn out of the whole request. + /// The request the turn is about to run. + /// The text of the last user message, or an empty string when the request holds none. + private static string CallerText(IEnumerable messages) { - if (message.Role == ChatRole.User) + string? spoken = null; + foreach (ChatMessage message in messages) { - spoken = message.Text; + if (message.Role == ChatRole.User) + { + spoken = message.Text; + } } - } - return spoken ?? string.Empty; - } + return spoken ?? string.Empty; + } - /// Puts the verdict on the run, folding in what the fallback layer already said. - /// Where the turn loop reads the marker from. - /// What moderation decided. - private static void Attach(AdditionalPropertiesDictionary properties, TurnDisposition verdict) - { - if (properties.TryGetValue(out var existing) && existing is not null) + /// Puts the verdict on the run, folding in what the fallback layer already said. + /// Where the turn loop reads the marker from. + /// What moderation decided. + private static void Attach(AdditionalPropertiesDictionary properties, TurnDisposition verdict) { - verdict = verdict with { Fallback = existing.Fallback, FallbackReason = existing.FallbackReason }; - properties.Remove(); - } + if (properties.TryGetValue(out TurnDisposition? existing) && existing is not null) + { + verdict = verdict with { Fallback = existing.Fallback, FallbackReason = existing.FallbackReason }; + _ = properties.Remove(); + } - properties.Add(verdict); + properties.Add(verdict); + } } } diff --git a/src/AgentCore.Application/Runtime/ReplyOutcome.cs b/src/AgentCore.Application/Runtime/ReplyOutcome.cs new file mode 100644 index 00000000..de95e5d2 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ReplyOutcome.cs @@ -0,0 +1,19 @@ +using AgentCore.Domain; + +namespace AgentCore.Application.Runtime +{ + /// What the turn said, what the caller heard, and why they differ if they do. + /// The text the record holds: what the caller heard. + /// The text the model produced, before any barge-in cut it. + /// The section 8.7 reason, or . + /// The row-six fault, from the run or from the fallback layer. + /// The played duration of a cut reply, or . + /// The tool calls still waiting on a human answer. + internal sealed record ReplyOutcome( + string Reply, + string SpokenReply, + string? Failure, + string? ToolFault, + TimeSpan? InterruptedAfter, + List Approvals); +} diff --git a/src/AgentCore.Application/Runtime/RequireOutputAgent.cs b/src/AgentCore.Application/Runtime/RequireOutputAgent.cs index 5d936bf1..256cbe05 100644 --- a/src/AgentCore.Application/Runtime/RequireOutputAgent.cs +++ b/src/AgentCore.Application/Runtime/RequireOutputAgent.cs @@ -2,70 +2,73 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -/// -/// Fails a row 4 graph run that produced no text, instead of letting it end quietly. -/// -internal sealed class RequireOutputAgent : DelegatingAIAgent +namespace AgentCore.Application.Runtime { - /// The reason a row 4 graph that produced no text reports, after it names the graph. - internal const string NoOutputMessage = - "Row 4 of the section 8.2 compile table ends the run at idle when no outgoing edge guard of " - + "the node that holds the run is true. Measured on Microsoft.Agents.AI.Workflows 1.17.0: " - + "InProcessRunner raises no exception for that, and the AsAIAgent() wrapper emits no update, " - + "so the caller would read an empty run and no error. Read the when: guard of every edge that " - + "leaves the node the run reached, and make one of them true for this state. A stage says " - + "onNoMatch: error, and a graph node takes no such key: D15 makes a new public key a " - + "permanent obligation, so this check adds none."; - - private readonly string _name; - - /// Puts the output check in front of one compiled graph. - /// The workflow of row 4, already wrapped by AsAIAgent(). - /// The name of the document, which the failure reports. - public RequireOutputAgent(AIAgent inner, string name) - : base(inner) + /// + /// Fails a row 4 graph run that produced no text, instead of letting it end quietly. + /// + internal sealed class RequireOutputAgent : DelegatingAIAgent { - ArgumentNullException.ThrowIfNull(name); - _name = name; - } + /// The reason a row 4 graph that produced no text reports, after it names the graph. + internal const string NoOutputMessage = + "Row 4 of the section 8.2 compile table ends the run at idle when no outgoing edge guard of " + + "the node that holds the run is true. Measured on Microsoft.Agents.AI.Workflows 1.17.0: " + + "InProcessRunner raises no exception for that, and the AsAIAgent() wrapper emits no update, " + + "so the caller would read an empty run and no error. Read the when: guard of every edge that " + + "leaves the node the run reached, and make one of them true for this state. A stage says " + + "onNoMatch: error, and a graph node takes no such key: D15 makes a new public key a " + + "permanent obligation, so this check adds none."; - /// - protected override async Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - { - var response = await base.RunCoreAsync(messages, session, options, cancellationToken) - .ConfigureAwait(false); + private readonly string _name; - return string.IsNullOrWhiteSpace(response.Text) ? throw NoOutput() : response; - } + /// Puts the output check in front of one compiled graph. + /// The workflow of row 4, already wrapped by AsAIAgent(). + /// The name of the document, which the failure reports. + public RequireOutputAgent(AIAgent inner, string name) + : base(inner) + { + ArgumentNullException.ThrowIfNull(name); + _name = name; + } - /// - protected override async IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - var carriedText = false; + /// + protected override async Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + AgentResponse response = await base.RunCoreAsync(messages, session, options, cancellationToken) + .ConfigureAwait(false); + + return string.IsNullOrWhiteSpace(response.Text) ? throw NoOutput() : response; + } - await foreach (var update in base.RunCoreStreamingAsync(messages, session, options, cancellationToken) - .ConfigureAwait(false)) + /// + protected override async IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - carriedText |= !string.IsNullOrWhiteSpace(update.Text); - yield return update; + bool carriedText = false; + + await foreach (AgentResponseUpdate? update in base.RunCoreStreamingAsync(messages, session, options, cancellationToken) + .ConfigureAwait(false)) + { + carriedText |= !string.IsNullOrWhiteSpace(update.Text); + yield return update; + } + + if (!carriedText) + { + throw NoOutput(); + } } - if (!carriedText) + private InvalidOperationException NoOutput() { - throw NoOutput(); + return new($"The graph '{_name}' produced no text. " + NoOutputMessage); } } - - private InvalidOperationException NoOutput() - => new($"The graph '{_name}' produced no text. " + NoOutputMessage); } diff --git a/src/AgentCore.Application/Runtime/SpokenReply.cs b/src/AgentCore.Application/Runtime/SpokenReply.cs index 850596d7..9b032997 100644 --- a/src/AgentCore.Application/Runtime/SpokenReply.cs +++ b/src/AgentCore.Application/Runtime/SpokenReply.cs @@ -1,59 +1,60 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime; - -/// -/// Picks the one message of a run that the caller actually hears. -/// -/// -/// -/// AgentResponse.Text concatenates every message of the response. On a graph row that is every -/// node's reply, so the caller would hear the graph deliberating. The last message is the spoken one -/// — but only after two artefacts are stepped over, and both were measured on Microsoft.Agents.AI -/// 1.17.0. -/// -/// -/// A folded stream is mostly lifecycle. Collecting a two-node graph's updates and calling -/// ToAgentResponse() gave 25 messages for two replies: 23 of them carried no content at all, -/// and ten of those sat after the last spoken word. Reading the last message flatly would therefore -/// report every streaming graph turn as an empty reply. -/// -/// -/// A quiet node vanishes when buffered. A sequential graph whose last node answers with -/// whitespace returns one message, and it is the node BEFORE it. Naming the agents the caller hears -/// is what keeps that deliberation out of the caller's ear. -/// -/// -internal static class SpokenReply +namespace AgentCore.Application.Runtime { - /// Reads the words this run puts in the caller's ear. - /// The messages of the run, oldest first. - /// - /// The agents.items ids whose reply the caller hears, or when every - /// message counts. CompiledAgent.SpokenBy names them. - /// - /// The spoken text, or an empty string when the run produced none. - internal static string From(IList messages, IReadOnlySet? spokenBy = null) + /// + /// Picks the one message of a run that the caller actually hears. + /// + /// + /// + /// AgentResponse.Text concatenates every message of the response. On a graph row that is every + /// node's reply, so the caller would hear the graph deliberating. The last message is the spoken one + /// — but only after two artefacts are stepped over, and both were measured on Microsoft.Agents.AI + /// 1.17.0. + /// + /// + /// A folded stream is mostly lifecycle. Collecting a two-node graph's updates and calling + /// ToAgentResponse() gave 25 messages for two replies: 23 of them carried no content at all, + /// and ten of those sat after the last spoken word. Reading the last message flatly would therefore + /// report every streaming graph turn as an empty reply. + /// + /// + /// A quiet node vanishes when buffered. A sequential graph whose last node answers with + /// whitespace returns one message, and it is the node BEFORE it. Naming the agents the caller hears + /// is what keeps that deliberation out of the caller's ear. + /// + /// + internal static class SpokenReply { - for (var index = messages.Count - 1; index >= 0; index--) + /// Reads the words this run puts in the caller's ear. + /// The messages of the run, oldest first. + /// + /// The agents.items ids whose reply the caller hears, or when every + /// message counts. CompiledAgent.SpokenBy names them. + /// + /// The spoken text, or an empty string when the run produced none. + internal static string From(IList messages, IReadOnlySet? spokenBy = null) { - var message = messages[index]; - - // A message with no content at all is a workflow lifecycle event, not speech. A message - // that carries content and no words is a reply that said nothing, which IS the failure. - if (message.Contents.Count == 0) + for (int index = messages.Count - 1; index >= 0; index--) { - continue; - } + ChatMessage message = messages[index]; - if (spokenBy is not null && (message.AuthorName is not { } author || !spokenBy.Contains(author))) - { - continue; + // A message with no content at all is a workflow lifecycle event, not speech. A message + // that carries content and no words is a reply that said nothing, which IS the failure. + if (message.Contents.Count == 0) + { + continue; + } + + if (spokenBy is not null && (message.AuthorName is not { } author || !spokenBy.Contains(author))) + { + continue; + } + + return message.Text; } - return message.Text; + return string.Empty; } - - return string.Empty; } } diff --git a/src/AgentCore.Application/Runtime/ToolCallScopes.cs b/src/AgentCore.Application/Runtime/ToolCallScopes.cs index 1c3e74d9..f4bc6b6c 100644 --- a/src/AgentCore.Application/Runtime/ToolCallScopes.cs +++ b/src/AgentCore.Application/Runtime/ToolCallScopes.cs @@ -1,24 +1,25 @@ using AgentCore.Application.Tools; -namespace AgentCore.Application.Runtime; - -// The of one turn, built from the invocation the conversation runs under. -internal static class ToolCallScopes +namespace AgentCore.Application.Runtime { - /// The message the binder throws with when no turn reached the tool. - internal const string NoTurnMessage = - "A binding declared a ToolCallScope parameter, and no turn is open on this flow of execution. " - + "A bound tool receives a ToolCallScope only while a turn runs through a ConversationSession. Run the " - + "tool through a ConversationSession, or take the ToolCallScope parameter off the binding."; - - /// Builds the scope of the conversation and turn one invocation belongs to. - /// The turn the tool call runs under. - /// The scope. - /// is . - internal static ToolCallScope From(TurnInvocation invocation) + // The of one turn, built from the invocation the conversation runs under. + internal static class ToolCallScopes { - ArgumentNullException.ThrowIfNull(invocation); + /// The message the binder throws with when no turn reached the tool. + internal const string NoTurnMessage = + "A binding declared a ToolCallScope parameter, and no turn is open on this flow of execution. " + + "A bound tool receives a ToolCallScope only while a turn runs through a ConversationSession. Run the " + + "tool through a ConversationSession, or take the ToolCallScope parameter off the binding."; + + /// Builds the scope of the conversation and turn one invocation belongs to. + /// The turn the tool call runs under. + /// The scope. + /// is . + internal static ToolCallScope From(TurnInvocation invocation) + { + ArgumentNullException.ThrowIfNull(invocation); - return new ToolCallScope(invocation.ConversationId, invocation.TurnIndex, invocation.Stage, invocation.Workspace); + return new ToolCallScope(invocation.ConversationId, invocation.TurnIndex, invocation.Stage, invocation.Workspace); + } } } diff --git a/src/AgentCore.Application/Runtime/TranscriptEntry.cs b/src/AgentCore.Application/Runtime/TranscriptEntry.cs new file mode 100644 index 00000000..e13e6b37 --- /dev/null +++ b/src/AgentCore.Application/Runtime/TranscriptEntry.cs @@ -0,0 +1,9 @@ +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime +{ + /// What this turn adds to the transcript. + /// The assistant message the caller heard, or when nothing was. + /// Every message store 0 appends after the caller's own; empty for rows 3 and 4. + internal sealed record TranscriptEntry(ChatMessage? Heard, List Written); +} diff --git a/src/AgentCore.Application/Runtime/Turn/ITurnAttachments.cs b/src/AgentCore.Application/Runtime/Turn/ITurnAttachments.cs index 5bde579d..470cde1f 100644 --- a/src/AgentCore.Application/Runtime/Turn/ITurnAttachments.cs +++ b/src/AgentCore.Application/Runtime/Turn/ITurnAttachments.cs @@ -1,24 +1,25 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Turn; - -/// -/// One kind of thing a turn's tools produce for the caller, as the invoking client handles every -/// kind alike: opened around the outermost tool call, drained onto that call's result message. -/// -/// -/// A new kind implements this once and joins TurnInvocation.Attachments(). The invoking client -/// never names a kind. -/// -internal interface ITurnAttachments +namespace AgentCore.Application.Runtime.Turn { - /// Opens one outermost tool call as the key publishes file under. - /// The id of the outermost tool call now running. - /// The scope. Disposing it puts back the key that was open before. - IDisposable BeginOuterCall(string callId); + /// + /// One kind of thing a turn's tools produce for the caller, as the invoking client handles every + /// kind alike: opened around the outermost tool call, drained onto that call's result message. + /// + /// + /// A new kind implements this once and joins TurnInvocation.Attachments(). The invoking client + /// never names a kind. + /// + internal interface ITurnAttachments + { + /// Opens one outermost tool call as the key publishes file under. + /// The id of the outermost tool call now running. + /// The scope. Disposing it puts back the key that was open before. + IDisposable BeginOuterCall(string callId); - /// Takes what was filed under one outer tool call, in publish order. - /// The call whose content to take. - /// What that call filed, or empty. - IReadOnlyList TakeFor(string callId); + /// Takes what was filed under one outer tool call, in publish order. + /// The call whose content to take. + /// What that call filed, or empty. + IReadOnlyList TakeFor(string callId); + } } diff --git a/src/AgentCore.Application/Runtime/Turn/OuterCall.cs b/src/AgentCore.Application/Runtime/Turn/OuterCall.cs index 448363ff..cdce36ce 100644 --- a/src/AgentCore.Application/Runtime/Turn/OuterCall.cs +++ b/src/AgentCore.Application/Runtime/Turn/OuterCall.cs @@ -1,24 +1,30 @@ -namespace AgentCore.Application.Runtime.Turn; - -/// One outermost tool call, open on every kind of attachment at once. -internal sealed class OuterCall : IDisposable +namespace AgentCore.Application.Runtime.Turn { - private readonly IDisposable[] _opened; + /// One outermost tool call, open on every kind of attachment at once. + internal sealed class OuterCall : IDisposable + { + private readonly IDisposable[] _opened; - private OuterCall(IDisposable[] opened) => _opened = opened; + private OuterCall(IDisposable[] opened) + { + _opened = opened; + } - /// Opens the call on every kind, in list order. - /// Every kind the turn carries. - /// The id of the outermost tool call now running. - /// The scope. Disposing it closes every kind, last opened first. - public static OuterCall Open(IReadOnlyList attachments, string callId) - => new([.. attachments.Select(kind => kind.BeginOuterCall(callId))]); + /// Opens the call on every kind, in list order. + /// Every kind the turn carries. + /// The id of the outermost tool call now running. + /// The scope. Disposing it closes every kind, last opened first. + public static OuterCall Open(IReadOnlyList attachments, string callId) + { + return new([.. attachments.Select(kind => kind.BeginOuterCall(callId))]); + } - public void Dispose() - { - for (var index = _opened.Length - 1; index >= 0; index--) + public void Dispose() { - _opened[index].Dispose(); + for (int index = _opened.Length - 1; index >= 0; index--) + { + _opened[index].Dispose(); + } } } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnAttachments.cs b/src/AgentCore.Application/Runtime/Turn/TurnAttachments.cs index 899c67f9..49c55a83 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnAttachments.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnAttachments.cs @@ -1,102 +1,104 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Turn; - -/// -/// What a turn's tools have produced for the caller and not yet attached to a message, filed under -/// the outermost tool call that produced it. -/// -/// -/// The invoking client opens the outermost tool call around its invocation and takes what was filed -/// under it when it builds the tool-result message. Nested calls keep filing under the outer call; -/// outside any turn there is none, and a publish is discarded. -/// -/// The content one publish files. -internal abstract class TurnAttachments : ITurnAttachments - where TContent : AIContent +namespace AgentCore.Application.Runtime.Turn { - private readonly Lock _gate = new(); - - private readonly Dictionary> _byCallId = new(StringComparer.Ordinal); + /// + /// What a turn's tools have produced for the caller and not yet attached to a message, filed under + /// the outermost tool call that produced it. + /// + /// + /// The invoking client opens the outermost tool call around its invocation and takes what was filed + /// under it when it builds the tool-result message. Nested calls keep filing under the outer call; + /// outside any turn there is none, and a publish is discarded. + /// + /// The content one publish files. + internal abstract class TurnAttachments : ITurnAttachments + where TContent : AIContent + { + private readonly Lock _gate = new(); - private string? _outerCallId; + private readonly Dictionary> _byCallId = new(StringComparer.Ordinal); - /// Gets the id of the outermost tool call now running, or outside one. - protected string? OuterCallId => _outerCallId; + /// Gets the id of the outermost tool call now running, or outside one. + protected string? OuterCallId { get; private set; } - /// Opens one outermost tool call as the key publishes file under. - /// The id of the outermost tool call now running. - /// The scope. Disposing it puts back the key that was open before. - public IDisposable BeginOuterCall(string callId) - { - ArgumentNullException.ThrowIfNull(callId); - - string? previous; - lock (_gate) + /// Opens one outermost tool call as the key publishes file under. + /// The id of the outermost tool call now running. + /// The scope. Disposing it puts back the key that was open before. + public IDisposable BeginOuterCall(string callId) { - previous = _outerCallId; - _outerCallId = callId; - } + ArgumentNullException.ThrowIfNull(callId); - return new OuterCallScope(this, previous); - } - - /// Takes what was filed under one outer tool call, in publish order. - /// The call whose content to take. - /// What that call filed, or empty. - internal IReadOnlyList TakeFor(string callId) - { - ArgumentNullException.ThrowIfNull(callId); + string? previous; + lock (_gate) + { + previous = OuterCallId; + OuterCallId = callId; + } - lock (_gate) - { - return _byCallId.Remove(callId, out var filed) ? filed : []; + return new OuterCallScope(this, previous); } - } - IReadOnlyList ITurnAttachments.TakeFor(string callId) => TakeFor(callId); - - /// Files one content under a call. A later publish of the same thing wins, in the place the earlier one took, so publish order is kept. - /// The outer call to file under. - /// What to file. - /// Whether an already filed content is the same thing as . - protected void Attach(string callId, TContent content, Predicate sameAs) - { - lock (_gate) + /// Takes what was filed under one outer tool call, in publish order. + /// The call whose content to take. + /// What that call filed, or empty. + internal IReadOnlyList TakeFor(string callId) { - if (!_byCallId.TryGetValue(callId, out var filed)) - { - filed = []; - _byCallId[callId] = filed; - } + ArgumentNullException.ThrowIfNull(callId); - var index = filed.FindIndex(sameAs); - if (index >= 0) + lock (_gate) { - filed[index] = content; - } - else - { - filed.Add(content); + return _byCallId.Remove(callId, out List? filed) ? filed : []; } } - } - private sealed class OuterCallScope(TurnAttachments owner, string? previous) : IDisposable - { - private bool _closed; + IReadOnlyList ITurnAttachments.TakeFor(string callId) + { + return TakeFor(callId); + } - public void Dispose() + /// Files one content under a call. A later publish of the same thing wins, in the place the earlier one took, so publish order is kept. + /// The outer call to file under. + /// What to file. + /// Whether an already filed content is the same thing as . + protected void Attach(string callId, TContent content, Predicate sameAs) { - if (_closed) + lock (_gate) { - return; + if (!_byCallId.TryGetValue(callId, out List? filed)) + { + filed = []; + _byCallId[callId] = filed; + } + + int index = filed.FindIndex(sameAs); + if (index >= 0) + { + filed[index] = content; + } + else + { + filed.Add(content); + } } + } + + private sealed class OuterCallScope(TurnAttachments owner, string? previous) : IDisposable + { + private bool _closed; - _closed = true; - lock (owner._gate) + public void Dispose() { - owner._outerCallId = previous; + if (_closed) + { + return; + } + + _closed = true; + lock (owner._gate) + { + owner.OuterCallId = previous; + } } } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnContextProvider.cs b/src/AgentCore.Application/Runtime/Turn/TurnContextProvider.cs index 363b5eea..7d4b5877 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnContextProvider.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnContextProvider.cs @@ -1,26 +1,27 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Turn; - -/// -/// The framework's per-invocation seam, bound to every compiled agent. -/// -internal sealed class TurnContextProvider : AIContextProvider +namespace AgentCore.Application.Runtime.Turn { - /// - protected override ValueTask ProvideAIContextAsync( - InvokingContext context, CancellationToken cancellationToken = default) + /// + /// The framework's per-invocation seam, bound to every compiled agent. + /// + internal sealed class TurnContextProvider : AIContextProvider { - ArgumentNullException.ThrowIfNull(context); + /// + protected override ValueTask ProvideAIContextAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(context); - var instructions = TurnRegistry.For(context.Session)?.Instructions; + string? instructions = TurnRegistry.For(context.Session)?.Instructions; - return new(new AIContext - { - Messages = string.IsNullOrEmpty(instructions) - ? null - : [new ChatMessage(ChatRole.System, instructions)], - }); + return new(new AIContext + { + Messages = string.IsNullOrEmpty(instructions) + ? null + : [new ChatMessage(ChatRole.System, instructions)], + }); + } } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnFiles.cs b/src/AgentCore.Application/Runtime/Turn/TurnFiles.cs index 1a427723..ac44c513 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnFiles.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnFiles.cs @@ -1,22 +1,23 @@ using AgentCore.Application.Transcript; -namespace AgentCore.Application.Runtime.Turn; - -/// What a turn has published to the caller's file store and not yet attached to a message. -internal sealed class TurnFiles : TurnAttachments +namespace AgentCore.Application.Runtime.Turn { - /// Files one published file under the outermost tool call, or drops it outside a turn. - /// The file the store kept. - public void Publish(FileContent file) + /// What a turn has published to the caller's file store and not yet attached to a message. + internal sealed class TurnFiles : TurnAttachments { - ArgumentNullException.ThrowIfNull(file); - - if (OuterCallId is not { } callId) + /// Files one published file under the outermost tool call, or drops it outside a turn. + /// The file the store kept. + public void Publish(FileContent file) { - return; - } + ArgumentNullException.ThrowIfNull(file); - // The same name published twice is one blob: the store replaced the bytes. - Attach(callId, file, existing => string.Equals(existing.Name, file.Name, StringComparison.Ordinal)); + if (OuterCallId is not { } callId) + { + return; + } + + // The same name published twice is one blob: the store replaced the bytes. + Attach(callId, file, existing => string.Equals(existing.Name, file.Name, StringComparison.Ordinal)); + } } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnMessages.cs b/src/AgentCore.Application/Runtime/Turn/TurnMessages.cs index 588ace5c..0ba9b38f 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnMessages.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnMessages.cs @@ -1,111 +1,114 @@ using System.Text; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Turn; - -/// -/// The message shapes one turn builds and filters. Every member is pure: messages in, messages out. -/// -internal static class TurnMessages +namespace AgentCore.Application.Runtime.Turn { /// - /// What opens the system message a graph row's history rides on. - /// - internal const string HistoryPreamble = "Conversation so far:\n"; - - /// - /// What names the caller in that message. + /// The message shapes one turn builds and filters. Every member is pure: messages in, messages out. /// - internal const string CallerLinePrefix = "Caller: "; + internal static class TurnMessages + { + /// + /// What opens the system message a graph row's history rides on. + /// + internal const string HistoryPreamble = "Conversation so far:\n"; - /// - /// What names this agent in that message. - /// - internal const string AgentLinePrefix = "You: "; + /// + /// What names the caller in that message. + /// + internal const string CallerLinePrefix = "Caller: "; - /// - /// Renders the conversation so far into the one role a workflow node still recognises. - /// - /// The caller-facing history of this conversation, oldest first. - /// One system message, or on the first turn of a conversation. - internal static ChatMessage? GraphHistory(IReadOnlyList history) - { - StringBuilder rendered = new(); + /// + /// What names this agent in that message. + /// + internal const string AgentLinePrefix = "You: "; - foreach (var message in history) + /// + /// Renders the conversation so far into the one role a workflow node still recognises. + /// + /// The caller-facing history of this conversation, oldest first. + /// One system message, or on the first turn of a conversation. + internal static ChatMessage? GraphHistory(IReadOnlyList history) { - if (message.Text is not { Length: > 0 } text) + StringBuilder rendered = new(); + + foreach (ChatMessage message in history) { - continue; + if (message.Text is not { Length: > 0 } text) + { + continue; + } + + _ = rendered + .Append(message.Role == ChatRole.User ? CallerLinePrefix : AgentLinePrefix) + .Append(text) + .Append('\n'); } - rendered - .Append(message.Role == ChatRole.User ? CallerLinePrefix : AgentLinePrefix) - .Append(text) - .Append('\n'); + return rendered.Length == 0 + ? null + : new ChatMessage(ChatRole.System, HistoryPreamble + rendered.ToString().TrimEnd('\n')); } - return rendered.Length == 0 - ? null - : new ChatMessage(ChatRole.System, HistoryPreamble + rendered.ToString().TrimEnd('\n')); - } - - /// Reads whether one update carries something a host needs. - /// One update of the run. - /// Whether the host reads it. - internal static bool CarriesContent(ChatResponseUpdate update) - => update.Contents.Any(content => content is not TextContent text || text.Text.Length > 0); - - /// Keeps the tool calls whose results arrived, and drops every unpaired call and every word. - /// Every message the round produced. - /// The tool content that carries a complete call-and-result pair, in its original order. - internal static List FinishedToolMessages(IList messages) - { - HashSet answered = []; - foreach (var message in messages) + /// Reads whether one update carries something a host needs. + /// One update of the run. + /// Whether the host reads it. + internal static bool CarriesContent(ChatResponseUpdate update) { - foreach (var result in message.Contents.OfType()) - { - answered.Add(result.CallId); - } + return update.Contents.Any(content => content is not TextContent text || text.Text.Length > 0); } - List kept = []; - foreach (var message in messages) + /// Keeps the tool calls whose results arrived, and drops every unpaired call and every word. + /// Every message the round produced. + /// The tool content that carries a complete call-and-result pair, in its original order. + internal static List FinishedToolMessages(IList messages) { - // A parallel round can finish one call and leave a sibling call in the same message - // mid-flight. The rule is per call id and not per message, so only the unfinished call - // is stripped out; the finished one, whose side effect already ran, stays in place. - List tools = - [ - .. message.Contents.Where(content => content switch - { - TextContent => false, - FunctionCallContent call => answered.Contains(call.CallId), - _ => true, - }), - ]; - - if (!tools.Any(content => content is FunctionCallContent or FunctionResultContent or ToolApprovalRequestContent)) + HashSet answered = []; + foreach (ChatMessage message in messages) { - // Plain prose, or a message whose every call is still in flight. Neither belongs in - // the next turn. - continue; + foreach (FunctionResultContent result in message.Contents.OfType()) + { + _ = answered.Add(result.CallId); + } } - if (tools.Count == message.Contents.Count) + List kept = []; + foreach (ChatMessage message in messages) { - // Nothing was stripped, so the message is already the finished shape. Keep it whole, - // contents and order unchanged. - kept.Add(message); - continue; + // A parallel round can finish one call and leave a sibling call in the same message + // mid-flight. The rule is per call id and not per message, so only the unfinished call + // is stripped out; the finished one, whose side effect already ran, stays in place. + List tools = + [ + .. message.Contents.Where(content => content switch + { + TextContent => false, + FunctionCallContent call => answered.Contains(call.CallId), + _ => true, + }), + ]; + + if (!tools.Any(content => content is FunctionCallContent or FunctionResultContent or ToolApprovalRequestContent)) + { + // Plain prose, or a message whose every call is still in flight. Neither belongs in + // the next turn. + continue; + } + + if (tools.Count == message.Contents.Count) + { + // Nothing was stripped, so the message is already the finished shape. Keep it whole, + // contents and order unchanged. + kept.Add(message); + continue; + } + + ChatMessage trimmed = message.Clone(); + trimmed.Contents = tools; + kept.Add(trimmed); } - var trimmed = message.Clone(); - trimmed.Contents = tools; - kept.Add(trimmed); + return kept; } - - return kept; } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnRegistry.cs b/src/AgentCore.Application/Runtime/Turn/TurnRegistry.cs index 038760a8..97f69ac6 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnRegistry.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnRegistry.cs @@ -1,33 +1,36 @@ using System.Runtime.CompilerServices; using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime.Turn; - -// The turn running on one session, keyed by the session the framework hands providers — -// the MAF AgentSession.StateBag shape, but live: the bag serializes and a turn holds -// sessions and tools, so the table carries what the bag cannot. The loop files the turn -// under the session the run actually gets, since a graph row re-creates its own per turn. -// Providers read it back off the session their InvokingContext carries. Weak keys: an -// entry dies with its session, and each turn overwrites the last, so nothing here leaks -// or crosses turns. -internal static class TurnRegistry +namespace AgentCore.Application.Runtime.Turn { - private static readonly ConditionalWeakTable Turns = []; - - /// Files the turn running on one session. - /// The session the run actually gets. - /// What that run may see and cite. - internal static void Set(AgentSession session, TurnInvocation turn) + // The turn running on one session, keyed by the session the framework hands providers — + // the MAF AgentSession.StateBag shape, but live: the bag serializes and a turn holds + // sessions and tools, so the table carries what the bag cannot. The loop files the turn + // under the session the run actually gets, since a graph row re-creates its own per turn. + // Providers read it back off the session their InvokingContext carries. Weak keys: an + // entry dies with its session, and each turn overwrites the last, so nothing here leaks + // or crosses turns. + internal static class TurnRegistry { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(turn); + private static readonly ConditionalWeakTable Turns = []; - Turns.Remove(session); - Turns.Add(session, turn); - } + /// Files the turn running on one session. + /// The session the run actually gets. + /// What that run may see and cite. + internal static void Set(AgentSession session, TurnInvocation turn) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(turn); - /// Reads the turn a run on one session belongs to, or null when it is not ours. - /// The session the framework is about to run on. - internal static TurnInvocation? For(AgentSession? session) - => session is not null && Turns.TryGetValue(session, out var turn) ? turn : null; + _ = Turns.Remove(session); + Turns.Add(session, turn); + } + + /// Reads the turn a run on one session belongs to, or null when it is not ours. + /// The session the framework is about to run on. + internal static TurnInvocation? For(AgentSession? session) + { + return session is not null && Turns.TryGetValue(session, out TurnInvocation? turn) ? turn : null; + } + } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs b/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs index 8bf22a1e..ec5c681f 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs @@ -2,26 +2,27 @@ using AgentCore.Application.Ports; using AgentCore.Application.Transcript; -namespace AgentCore.Application.Runtime.Turn; - -/// What a turn has drawn and not yet attached to a message. -internal sealed class TurnRenders : TurnAttachments, IRenderPort +namespace AgentCore.Application.Runtime.Turn { - /// - public void Publish(string name, string renderId, object data, bool transient = false) + /// What a turn has drawn and not yet attached to a message. + internal sealed class TurnRenders : TurnAttachments, IRenderPort { - ArgumentNullException.ThrowIfNull(name); - ArgumentNullException.ThrowIfNull(renderId); - ArgumentNullException.ThrowIfNull(data); - - if (transient || OuterCallId is not { } callId) + /// + public void Publish(string name, string renderId, object data, bool transient = false) { - return; - } + ArgumentNullException.ThrowIfNull(name); + ArgumentNullException.ThrowIfNull(renderId); + ArgumentNullException.ThrowIfNull(data); - var element = JsonSerializer.SerializeToElement(data, data.GetType(), TranscriptJson.Options); - var content = new RenderContent { Name = name, RenderId = renderId, Data = element }; + if (transient || OuterCallId is not { } callId) + { + return; + } - Attach(callId, content, existing => string.Equals(existing.RenderId, renderId, StringComparison.Ordinal)); + JsonElement element = JsonSerializer.SerializeToElement(data, data.GetType(), TranscriptJson.Options); + RenderContent content = new() { Name = name, RenderId = renderId, Data = element }; + + Attach(callId, content, existing => string.Equals(existing.RenderId, renderId, StringComparison.Ordinal)); + } } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnResults.cs b/src/AgentCore.Application/Runtime/Turn/TurnResults.cs index 606518a5..51afafd1 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnResults.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnResults.cs @@ -3,174 +3,175 @@ using AgentCore.Application.Tools; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Runtime.Turn; - -/// -/// What the tools the model called this turn answered, kept so a script can read the rows instead of -/// a model retyping them. -/// -internal sealed class TurnResults +namespace AgentCore.Application.Runtime.Turn { - /// The key under which every result of one tool sits, oldest first. - internal const string AllKey = "$all"; + /// + /// What the tools the model called this turn answered, kept so a script can read the rows instead of + /// a model retyping them. + /// + internal sealed class TurnResults + { + /// The key under which every result of one tool sits, oldest first. + internal const string AllKey = "$all"; - private readonly Lock _gate = new(); + private readonly Lock _gate = new(); - private readonly Dictionary> _byTool = new(StringComparer.Ordinal); + private readonly Dictionary> _byTool = new(StringComparer.Ordinal); - private readonly List _order = []; + private readonly List _order = []; - private readonly HashSet _callIds = new(StringComparer.Ordinal); + private readonly HashSet _callIds = new(StringComparer.Ordinal); - private readonly List>> _sweeps = []; + private readonly List>> _sweeps = []; - /// The tools that answered something structured, in first-answer order. - internal IReadOnlyList Tools - { - get + /// The tools that answered something structured, in first-answer order. + internal IReadOnlyList Tools { - lock (_gate) + get { - return [.. _order]; + lock (_gate) + { + return [.. _order]; + } } } - } - /// Keeps one tool's answer, when it is structured. - /// The tool's declared id. - /// What it returned. - internal void Record(string tool, object? result) - { - ArgumentNullException.ThrowIfNull(tool); - - if (AsStructured(result) is not { } node) + /// Keeps one tool's answer, when it is structured. + /// The tool's declared id. + /// What it returned. + internal void Record(string tool, object? result) { - return; - } + ArgumentNullException.ThrowIfNull(tool); - lock (_gate) - { - if (!_byTool.TryGetValue(tool, out var answers)) + if (AsStructured(result) is not { } node) { - answers = []; - _byTool[tool] = answers; - _order.Add(tool); + return; } - answers.Add(node); + lock (_gate) + { + if (!_byTool.TryGetValue(tool, out List? answers)) + { + answers = []; + _byTool[tool] = answers; + _order.Add(tool); + } + + answers.Add(node); + } } - } - - /// Keeps one tool call's id and its client's drain sweep, so turn end can sweep drain state for calls whose round never drained. - /// The id the model gave this one call. - /// Drops that client's entries for the turn's ids. - internal void NoteCall(string callId, Action> sweep) - { - ArgumentNullException.ThrowIfNull(callId); - ArgumentNullException.ThrowIfNull(sweep); - lock (_gate) + /// Keeps one tool call's id and its client's drain sweep, so turn end can sweep drain state for calls whose round never drained. + /// The id the model gave this one call. + /// Drops that client's entries for the turn's ids. + internal void NoteCall(string callId, Action> sweep) { - _callIds.Add(callId); - _sweeps.Add(sweep); - } - } - - /// Sweeps every recorded client's drain state for this turn's call ids. - internal void Sweep() - { - IReadOnlyList callIds; - List>> sweeps; + ArgumentNullException.ThrowIfNull(callId); + ArgumentNullException.ThrowIfNull(sweep); - lock (_gate) - { - callIds = [.. _callIds]; - sweeps = [.. _sweeps]; + lock (_gate) + { + _ = _callIds.Add(callId); + _sweeps.Add(sweep); + } } - foreach (var sweep in sweeps) + /// Sweeps every recorded client's drain state for this turn's call ids. + internal void Sweep() { - sweep(callIds); - } - } + IReadOnlyList callIds; + List>> sweeps; - /// Every tool call id the turn recorded, in no particular order. - internal IReadOnlyList CallIds - { - get - { lock (_gate) { - return [.. _callIds]; + callIds = [.. _callIds]; + sweeps = [.. _sweeps]; } - } - } - /// The latest answer of one tool, or . - /// The tool's declared id. - /// A copy of the answer. - internal JsonNode? Latest(string tool) - { - lock (_gate) - { - return _byTool.TryGetValue(tool, out var answers) ? answers[^1].DeepClone() : null; + foreach (Action> sweep in sweeps) + { + sweep(callIds); + } } - } - /// - /// What a script sees as data: each tool's latest answer under its id, and every answer - /// under . - /// - /// A fresh object each time. A script may do what it likes to it. - internal JsonObject Data() - { - lock (_gate) + /// Every tool call id the turn recorded, in no particular order. + internal IReadOnlyList CallIds { - JsonObject data = []; - JsonObject all = []; - foreach (var tool in _order) + get { - var answers = _byTool[tool]; - data[tool] = answers[^1].DeepClone(); - all[tool] = new JsonArray([.. answers.Select(answer => answer.DeepClone())]); + lock (_gate) + { + return [.. _callIds]; + } } - - data[AllKey] = all; - return data; } - } - private static JsonNode? AsStructured(object? result) - { - var node = result switch + /// The latest answer of one tool, or . + /// The tool's declared id. + /// A copy of the answer. + internal JsonNode? Latest(string tool) { - null => null, - JsonNode direct => direct.DeepClone(), - JsonElement element => JsonSerializer.SerializeToNode(element), - string text => Parse(text), - _ => JsonSerializer.SerializeToNode(result, result.GetType(), AIJsonUtilities.DefaultOptions), - }; - - return node is JsonObject or JsonArray && !(node is JsonObject error && ToolErrorResult.IsError(error)) - ? node - : null; - } + lock (_gate) + { + return _byTool.TryGetValue(tool, out List? answers) ? answers[^1].DeepClone() : null; + } + } - private static JsonNode? Parse(string text) - { - var trimmed = text.AsSpan().Trim(); - if (trimmed.Length == 0 || (trimmed[0] != '{' && trimmed[0] != '[')) + /// + /// What a script sees as data: each tool's latest answer under its id, and every answer + /// under . + /// + /// A fresh object each time. A script may do what it likes to it. + internal JsonObject Data() { - return null; + lock (_gate) + { + JsonObject data = []; + JsonObject all = []; + foreach (string tool in _order) + { + List answers = _byTool[tool]; + data[tool] = answers[^1].DeepClone(); + all[tool] = new JsonArray([.. answers.Select(answer => answer.DeepClone())]); + } + + data[AllKey] = all; + return data; + } } - try + private static JsonNode? AsStructured(object? result) { - return JsonNode.Parse(text); + JsonNode? node = result switch + { + null => null, + JsonNode direct => direct.DeepClone(), + JsonElement element => JsonSerializer.SerializeToNode(element), + string text => Parse(text), + _ => JsonSerializer.SerializeToNode(result, result.GetType(), AIJsonUtilities.DefaultOptions), + }; + + return node is JsonObject or JsonArray && !(node is JsonObject error && ToolErrorResult.IsError(error)) + ? node + : null; } - catch (JsonException) + + private static JsonNode? Parse(string text) { - return null; + ReadOnlySpan trimmed = text.AsSpan().Trim(); + if (trimmed.Length == 0 || (trimmed[0] != '{' && trimmed[0] != '[')) + { + return null; + } + + try + { + return JsonNode.Parse(text); + } + catch (JsonException) + { + return null; + } } } } diff --git a/src/AgentCore.Application/Runtime/Turn/TurnSources.cs b/src/AgentCore.Application/Runtime/Turn/TurnSources.cs index 3747a7d1..7137d977 100644 --- a/src/AgentCore.Application/Runtime/Turn/TurnSources.cs +++ b/src/AgentCore.Application/Runtime/Turn/TurnSources.cs @@ -2,25 +2,26 @@ using AgentCore.Application.Transcript; using AgentCore.Domain.Sources; -namespace AgentCore.Application.Runtime.Turn; - -/// What a turn has cited and not yet attached to a message. -internal sealed class TurnSources : TurnAttachments, ISourcePort +namespace AgentCore.Application.Runtime.Turn { - /// - public void Publish(SourceReference source) + /// What a turn has cited and not yet attached to a message. + internal sealed class TurnSources : TurnAttachments, ISourcePort { - ArgumentNullException.ThrowIfNull(source); - - if (OuterCallId is not { } callId) + /// + public void Publish(SourceReference source) { - return; - } + ArgumentNullException.ThrowIfNull(source); - var content = new SourceContent { Source = source, CallId = callId }; + if (OuterCallId is not { } callId) + { + return; + } - // Two searches in one turn can return the same card. - Attach(callId, content, existing => - string.Equals(existing.Source.SourceId, source.SourceId, StringComparison.Ordinal)); + SourceContent content = new() { Source = source, CallId = callId }; + + // Two searches in one turn can return the same card. + Attach(callId, content, existing => + string.Equals(existing.Source.SourceId, source.SourceId, StringComparison.Ordinal)); + } } } diff --git a/src/AgentCore.Application/Runtime/TurnDisposition.cs b/src/AgentCore.Application/Runtime/TurnDisposition.cs index 7c0e595f..44537a19 100644 --- a/src/AgentCore.Application/Runtime/TurnDisposition.cs +++ b/src/AgentCore.Application/Runtime/TurnDisposition.cs @@ -1,64 +1,65 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Runtime; - -/// What moderation decided about the caller's words. -internal enum ModerationOutcome +namespace AgentCore.Application.Runtime { - /// The endpoint answered and flagged nothing. - Clean, + /// What moderation decided about the caller's words. + internal enum ModerationOutcome + { + /// The endpoint answered and flagged nothing. + Clean, - /// The endpoint answered and flagged the words, so the model never ran. - Flagged, + /// The endpoint answered and flagged the words, so the model never ran. + Flagged, - /// The endpoint did not answer. Moderation fails open, so the turn ran unchecked. - Unavailable, -} + /// The endpoint did not answer. Moderation fails open, so the turn ran unchecked. + Unavailable, + } -/// Why spoke instead of the model. -internal enum FallbackCause -{ - /// It did not. The model answered. - None, + /// Why spoke instead of the model. + internal enum FallbackCause + { + /// It did not. The model answered. + None, - /// Something below the layer threw. Section 8.7, row six. - Faulted, + /// Something below the layer threw. Section 8.7, row six. + Faulted, - /// The run returned quietly with no text. Section 8.7, last row. - EmptyReply, -} + /// The run returned quietly with no text. Section 8.7, last row. + EmptyReply, + } -/// What the pipeline layers report back to about a turn. -/// -/// What the endpoint decided, or that it could not, or when the pipeline -/// carries no at all because the host moderates nothing. -/// -/// -/// The moderation endpoint's order, unmodified, or when nothing was flagged. -/// -/// Why the fallback layer spoke, or . -/// -/// The message of the fault the fallback layer caught, or . The turn's -/// tool.failed row carries this text, so it is the exception's message and not its type name. -/// -/// -/// Why the endpoint did not answer, in the words the turn loop logs, or . It -/// is set only when is . -/// -/// -/// -/// Carried on when buffered, and on a leading -/// when streaming — update-level properties do not survive -/// streaming coalescing, so the streaming reader must take it off the update, not the folded run. -/// -/// -/// It is attached and read with , which keys on the full -/// type name, so nothing else in the pipeline can collide with it. -/// -/// -internal sealed record TurnDisposition( - ModerationOutcome? Moderation, - string? FlaggedCategories, - FallbackCause Fallback, - string? FallbackReason, - string? ModerationReason); + /// What the pipeline layers report back to about a turn. + /// + /// What the endpoint decided, or that it could not, or when the pipeline + /// carries no at all because the host moderates nothing. + /// + /// + /// The moderation endpoint's order, unmodified, or when nothing was flagged. + /// + /// Why the fallback layer spoke, or . + /// + /// The message of the fault the fallback layer caught, or . The turn's + /// tool.failed row carries this text, so it is the exception's message and not its type name. + /// + /// + /// Why the endpoint did not answer, in the words the turn loop logs, or . It + /// is set only when is . + /// + /// + /// + /// Carried on when buffered, and on a leading + /// when streaming — update-level properties do not survive + /// streaming coalescing, so the streaming reader must take it off the update, not the folded run. + /// + /// + /// It is attached and read with , which keys on the full + /// type name, so nothing else in the pipeline can collide with it. + /// + /// + internal sealed record TurnDisposition( + ModerationOutcome? Moderation, + string? FlaggedCategories, + FallbackCause Fallback, + string? FallbackReason, + string? ModerationReason); +} diff --git a/src/AgentCore.Application/Runtime/TurnInvocation.cs b/src/AgentCore.Application/Runtime/TurnInvocation.cs index 1b6a2924..243eb579 100644 --- a/src/AgentCore.Application/Runtime/TurnInvocation.cs +++ b/src/AgentCore.Application/Runtime/TurnInvocation.cs @@ -7,134 +7,143 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Runtime; - -// Everything one turn hands its tools, as one explicit value. The loop builds one per turn; -// the invoking client files it beside every tool call's arguments, so a tool declares what -// it needs as a parameter instead of reading the flow. Nested runs see the same turn with the -// clarifications stripped and the outermost call id stamped, via `with` copies the client makes. -internal sealed record TurnInvocation +namespace AgentCore.Application.Runtime { - /// The options key the loop files the turn under, for the invoking client to read. - /// Namespaced: no vendor field will ever be called this. - internal const string ArgumentsKey = "urn:agentcore:turn"; - - /// Gets the id of the conversation the turn belongs to. - public required string ConversationId { get; init; } + // Everything one turn hands its tools, as one explicit value. The loop builds one per turn; + // the invoking client files it beside every tool call's arguments, so a tool declares what + // it needs as a parameter instead of reading the flow. Nested runs see the same turn with the + // clarifications stripped and the outermost call id stamped, via `with` copies the client makes. + internal sealed record TurnInvocation + { + /// The options key the loop files the turn under, for the invoking client to read. + /// Namespaced: no vendor field will ever be called this. + internal const string ArgumentsKey = "urn:agentcore:turn"; - /// Gets the zero-based index of the turn now running. - public required int TurnIndex { get; init; } + /// Gets the id of the conversation the turn belongs to. + public required string ConversationId { get; init; } - /// Gets the stage the machine holds. Empty when the entry declares no policy. - public required string Stage { get; init; } + /// Gets the zero-based index of the turn now running. + public required int TurnIndex { get; init; } - /// Gets the folder this conversation owns on disk, or . - public string? Workspace { get; init; } + /// Gets the stage the machine holds. Empty when the entry declares no policy. + public required string Stage { get; init; } - /// Gets this conversation's shell executors, or . - public ConversationShells? Shells { get; init; } + /// Gets the folder this conversation owns on disk, or . + public string? Workspace { get; init; } - /// Gets what the turn may see of the knowledge base, or . - public KnowledgeScope? Knowledge { get; init; } + /// Gets this conversation's shell executors, or . + public ConversationShells? Shells { get; init; } - /// Gets the conversation's ambiguity holder, or inside a nested tool call. - public Clarifications? Clarifications { get; init; } + /// Gets what the turn may see of the knowledge base, or . + public KnowledgeScope? Knowledge { get; init; } - /// Gets the instructions for this one invocation, or for none. - public string? Instructions { get; init; } + /// Gets the conversation's ambiguity holder, or inside a nested tool call. + public Clarifications? Clarifications { get; init; } - /// Gets the zone the person on the conversation is in, or when the host named none. - public TimeZoneInfo? TimeZone { get; init; } + /// Gets the instructions for this one invocation, or for none. + public string? Instructions { get; init; } - /// Gets whether this row's session carries the caller's own history. - public bool CarriesHistory { get; init; } + /// Gets the zone the person on the conversation is in, or when the host named none. + public TimeZoneInfo? TimeZone { get; init; } - /// Gets the conversation's logger, or to log nowhere. - public ILogger? Logger { get; init; } + /// Gets whether this row's session carries the caller's own history. + public bool CarriesHistory { get; init; } - /// Gets the screen this conversation draws on, or when it has none. - public IRenderPort? Screen { get; init; } + /// Gets the conversation's logger, or to log nowhere. + public ILogger? Logger { get; init; } - /// Gets what the turn cites into. Never on a loop-built turn. - public TurnSources? Sources { get; init; } + /// Gets the screen this conversation draws on, or when it has none. + public IRenderPort? Screen { get; init; } - /// Gets what the turn draws into, or when it has no screen. - public TurnRenders? Renders { get; init; } + /// Gets what the turn cites into. Never on a loop-built turn. + public TurnSources? Sources { get; init; } - /// Gets what the turn's tools answer into. Never on a loop-built turn. - public TurnResults? Results { get; init; } + /// Gets what the turn draws into, or when it has no screen. + public TurnRenders? Renders { get; init; } - /// Gets what the turn publishes files into. Never on a loop-built turn. - public TurnFiles? Files { get; init; } + /// Gets what the turn's tools answer into. Never on a loop-built turn. + public TurnResults? Results { get; init; } - /// - /// Lists every kind of thing this turn's tools produce for the caller, in the order they attach to - /// a tool-result message. A new kind is one new property and one name here. - /// - internal IReadOnlyList Attachments() - => [.. new ITurnAttachments?[] { Renders, Sources, Files }.OfType()]; + /// Gets what the turn publishes files into. Never on a loop-built turn. + public TurnFiles? Files { get; init; } - /// Gets the tools a delegated run of this conversation is offered, or for none. - public IReadOnlyList? Tools { get; init; } + /// + /// Lists every kind of thing this turn's tools produce for the caller, in the order they attach to + /// a tool-result message. A new kind is one new property and one name here. + /// + internal IReadOnlyList Attachments() + { + return [.. new ITurnAttachments?[] { Renders, Sources, Files }.OfType()]; + } - /// Gets the id of the delegating tool are meant for. - public string? ToolsFor { get; init; } + /// Gets the tools a delegated run of this conversation is offered, or for none. + public IReadOnlyList? Tools { get; init; } - /// Gets what to do with a tool failure the run reports. - public Action? OnToolFailure { get; init; } + /// Gets the id of the delegating tool are meant for. + public string? ToolsFor { get; init; } - /// Gets the outermost tool call open on this flow, stamped by the invoking client, - /// or before the first tool call. - public string? OuterCallId { get; init; } + /// Gets what to do with a tool failure the run reports. + public Action? OnToolFailure { get; init; } - /// Gets whether this turn runs nested inside another tool call. A nested turn neither latches the holder nor records. - public bool Nested { get; init; } + /// Gets the outermost tool call open on this flow, stamped by the invoking client, + /// or before the first tool call. + public string? OuterCallId { get; init; } - /// - /// Gets the live state document of the conversation running this turn, or - /// outside a turn. The graph-state wrapper snapshots it into the run just before the run starts; - /// nothing writes the document mid-run (writers and the extractor commit after), so the snapshot - /// reads what the old ambient read at edge time. - /// - public StateDocument? State { get; init; } + /// Gets whether this turn runs nested inside another tool call. A nested turn neither latches the holder nor records. + public bool Nested { get; init; } - /// Reads the turn filed on a run's options by , or null when there is none. - internal static TurnInvocation? From(AgentRunOptions? options) - => options is ChatClientAgentRunOptions run ? From(run.ChatOptions) : null; + /// + /// Gets the live state document of the conversation running this turn, or + /// outside a turn. The graph-state wrapper snapshots it into the run just before the run starts; + /// nothing writes the document mid-run (writers and the extractor commit after), so the snapshot + /// reads what the old ambient read at edge time. + /// + public StateDocument? State { get; init; } - /// Reads the turn filed on the options one request carries, or null outside a turn. - internal static TurnInvocation? From(ChatOptions? options) - => options?.AdditionalProperties?.TryGetValue(ArgumentsKey, out var filed) == true - ? filed as TurnInvocation - : null; + /// Reads the turn filed on a run's options by , or null when there is none. + internal static TurnInvocation? From(AgentRunOptions? options) + { + return options is ChatClientAgentRunOptions run ? From(run.ChatOptions) : null; + } - /// Reads the turn filed beside one tool call's arguments by , or null outside a turn. - internal static TurnInvocation? FiledIn(AIFunctionArguments? arguments) - => arguments?.Context?.TryGetValue(typeof(TurnInvocation), out var filed) == true - ? filed as TurnInvocation - : null; + /// Reads the turn filed on the options one request carries, or null outside a turn. + internal static TurnInvocation? From(ChatOptions? options) + { + return options?.AdditionalProperties?.TryGetValue(ArgumentsKey, out object? filed) == true + ? filed as TurnInvocation + : null; + } - /// - /// Files this turn beside one tool call's arguments, where the runtime-bound parameters read it. - /// Beside, never among: the arguments dictionary is the model's own call record, and a checkpoint - /// persists it, while lives only as long as the call. - /// - /// The same arguments, for a caller that builds them inline. - internal AIFunctionArguments FileIn(AIFunctionArguments arguments) - { - arguments.Context ??= new Dictionary(); - arguments.Context[typeof(TurnInvocation)] = this; - return arguments; - } + /// Reads the turn filed beside one tool call's arguments by , or null outside a turn. + internal static TurnInvocation? FiledIn(AIFunctionArguments? arguments) + { + return arguments?.Context?.TryGetValue(typeof(TurnInvocation), out object? filed) == true + ? filed as TurnInvocation + : null; + } + + /// + /// Files this turn beside one tool call's arguments, where the runtime-bound parameters read it. + /// Beside, never among: the arguments dictionary is the model's own call record, and a checkpoint + /// persists it, while lives only as long as the call. + /// + /// The same arguments, for a caller that builds them inline. + internal AIFunctionArguments FileIn(AIFunctionArguments arguments) + { + arguments.Context ??= new Dictionary(); + arguments.Context[typeof(TurnInvocation)] = this; + return arguments; + } - /// Builds the per-run options carrying this turn to the invoking client. - internal ChatClientAgentRunOptions RunOptions() - { - ChatOptions chat = new() + /// Builds the per-run options carrying this turn to the invoking client. + internal ChatClientAgentRunOptions RunOptions() { - AdditionalProperties = new AdditionalPropertiesDictionary { [ArgumentsKey] = this }, - }; + ChatOptions chat = new() + { + AdditionalProperties = new AdditionalPropertiesDictionary { [ArgumentsKey] = this }, + }; - return new ChatClientAgentRunOptions(chat); + return new ChatClientAgentRunOptions(chat); + } } } diff --git a/src/AgentCore.Application/Scripting/ScriptRequest.cs b/src/AgentCore.Application/Scripting/ScriptRequest.cs index 5d8117c5..2dce8300 100644 --- a/src/AgentCore.Application/Scripting/ScriptRequest.cs +++ b/src/AgentCore.Application/Scripting/ScriptRequest.cs @@ -1,21 +1,22 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Scripting; - -/// One script to run. -/// -/// What the model wrote. It is read as the body of a function with in scope -/// as data, ending in return; a bare function expression is called with data -/// instead. Markdown fences around it are ignored. -/// -/// What the script sees as data. -public sealed record ScriptRequest(string Code, JsonNode Data) +namespace AgentCore.Application.Scripting { - /// - /// The name of a function the script may conversation with its result instead of returning it, or - /// when only return counts. A model that was told to call a tool - /// named present will call present(tree) from inside its code about as often as it - /// returns the tree. - /// - public string? Emit { get; init; } + /// One script to run. + /// + /// What the model wrote. It is read as the body of a function with in scope + /// as data, ending in return; a bare function expression is called with data + /// instead. Markdown fences around it are ignored. + /// + /// What the script sees as data. + public sealed record ScriptRequest(string Code, JsonNode Data) + { + /// + /// The name of a function the script may conversation with its result instead of returning it, or + /// when only return counts. A model that was told to call a tool + /// named present will call present(tree) from inside its code about as often as it + /// returns the tree. + /// + public string? Emit { get; init; } + } } diff --git a/src/AgentCore.Application/Scripting/ScriptResult.cs b/src/AgentCore.Application/Scripting/ScriptResult.cs index 2e3227a2..19f1ece0 100644 --- a/src/AgentCore.Application/Scripting/ScriptResult.cs +++ b/src/AgentCore.Application/Scripting/ScriptResult.cs @@ -1,23 +1,30 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Scripting; - -/// What one script run produced. -public sealed record ScriptResult +namespace AgentCore.Application.Scripting { - /// The value the script returned or emitted, as JSON, or when it produced none. - public JsonNode? Value { get; init; } + /// What one script run produced. + public sealed record ScriptResult + { + /// The value the script returned or emitted, as JSON, or when it produced none. + public JsonNode? Value { get; init; } - /// Why the script produced nothing, in words the model can act on, or when it ran. - public string? Error { get; init; } + /// Why the script produced nothing, in words the model can act on, or when it ran. + public string? Error { get; init; } - /// A run that finished. - /// What it produced, or when it returned nothing. - /// The result. - public static ScriptResult Returned(JsonNode? value) => new() { Value = value }; + /// A run that finished. + /// What it produced, or when it returned nothing. + /// The result. + public static ScriptResult Returned(JsonNode? value) + { + return new() { Value = value }; + } - /// A run that did not finish. - /// Why, for the model. - /// The result. - public static ScriptResult Failed(string error) => new() { Error = error }; + /// A run that did not finish. + /// Why, for the model. + /// The result. + public static ScriptResult Failed(string error) + { + return new() { Error = error }; + } + } } diff --git a/src/AgentCore.Application/Secrets/KnownSecrets.cs b/src/AgentCore.Application/Secrets/KnownSecrets.cs index ee838ce5..21d7bca5 100644 --- a/src/AgentCore.Application/Secrets/KnownSecrets.cs +++ b/src/AgentCore.Application/Secrets/KnownSecrets.cs @@ -1,74 +1,75 @@ -namespace AgentCore.Application.Secrets; - -/// -/// Every credential AgentCore itself knows the name of, written down in one place. -/// -public static class KnownSecrets +namespace AgentCore.Application.Secrets { - /// The ${secret:name} name the OpenAI key resolves under. - public const string OpenAiApiKeyName = "openai-api-key"; + /// + /// Every credential AgentCore itself knows the name of, written down in one place. + /// + public static class KnownSecrets + { + /// The ${secret:name} name the OpenAI key resolves under. + public const string OpenAiApiKeyName = "openai-api-key"; - /// The standard OpenAI environment variable, read when the chain holds no name. - public const string OpenAiApiKeyVariable = "OPENAI_API_KEY"; + /// The standard OpenAI environment variable, read when the chain holds no name. + public const string OpenAiApiKeyVariable = "OPENAI_API_KEY"; - /// The ${secret:name} name the Qdrant key resolves under. - public const string QdrantApiKeyName = "qdrant-api-key"; + /// The ${secret:name} name the Qdrant key resolves under. + public const string QdrantApiKeyName = "qdrant-api-key"; - /// The standard Qdrant environment variable, read when the chain holds no name. - public const string QdrantApiKeyVariable = "QDRANT_API_KEY"; + /// The standard Qdrant environment variable, read when the chain holds no name. + public const string QdrantApiKeyVariable = "QDRANT_API_KEY"; - /// The ${secret:name} name the Grafana Cloud instance id resolves under. - public const string GrafanaCloudInstanceIdName = "grafana-cloud-instance-id"; + /// The ${secret:name} name the Grafana Cloud instance id resolves under. + public const string GrafanaCloudInstanceIdName = "grafana-cloud-instance-id"; - /// The environment variable the Grafana Cloud instance id is read from. - public const string GrafanaCloudInstanceIdVariable = "GRAFANA_CLOUD_INSTANCE_ID"; + /// The environment variable the Grafana Cloud instance id is read from. + public const string GrafanaCloudInstanceIdVariable = "GRAFANA_CLOUD_INSTANCE_ID"; - /// The ${secret:name} name the Grafana Cloud token resolves under. - public const string GrafanaCloudApiTokenName = "grafana-cloud-api-token"; + /// The ${secret:name} name the Grafana Cloud token resolves under. + public const string GrafanaCloudApiTokenName = "grafana-cloud-api-token"; - /// The environment variable the Grafana Cloud token is read from. - public const string GrafanaCloudApiTokenVariable = "GRAFANA_CLOUD_API_TOKEN"; + /// The environment variable the Grafana Cloud token is read from. + public const string GrafanaCloudApiTokenVariable = "GRAFANA_CLOUD_API_TOKEN"; - /// The ${secret:name} name the PostgreSQL connection string resolves under. - public const string PostgresConnectionStringName = "postgres-connection-string"; + /// The ${secret:name} name the PostgreSQL connection string resolves under. + public const string PostgresConnectionStringName = "postgres-connection-string"; - /// The environment variable the PostgreSQL connection string is read from. - public const string PostgresConnectionStringVariable = "POSTGRES_CONNECTION_STRING"; + /// The environment variable the PostgreSQL connection string is read from. + public const string PostgresConnectionStringVariable = "POSTGRES_CONNECTION_STRING"; - /// The ${secret:name} name the S3 access key id resolves under. - public const string S3AccessKeyIdName = "s3-access-key-id"; + /// The ${secret:name} name the S3 access key id resolves under. + public const string S3AccessKeyIdName = "s3-access-key-id"; - /// The standard AWS environment variable, read when the chain holds no name. - public const string S3AccessKeyIdVariable = "AWS_ACCESS_KEY_ID"; + /// The standard AWS environment variable, read when the chain holds no name. + public const string S3AccessKeyIdVariable = "AWS_ACCESS_KEY_ID"; - /// The ${secret:name} name the S3 secret access key resolves under. - public const string S3SecretAccessKeyName = "s3-secret-access-key"; + /// The ${secret:name} name the S3 secret access key resolves under. + public const string S3SecretAccessKeyName = "s3-secret-access-key"; - /// The standard AWS environment variable, read when the chain holds no name. - public const string S3SecretAccessKeyVariable = "AWS_SECRET_ACCESS_KEY"; + /// The standard AWS environment variable, read when the chain holds no name. + public const string S3SecretAccessKeyVariable = "AWS_SECRET_ACCESS_KEY"; - /// The one OpenAI credential, which chat, embedding, and moderation all read. - public static readonly SecretName OpenAi = new(OpenAiApiKeyName, OpenAiApiKeyVariable); + /// The one OpenAI credential, which chat, embedding, and moderation all read. + public static readonly SecretName OpenAi = new(OpenAiApiKeyName, OpenAiApiKeyVariable); - /// The Qdrant API key the vector store sends on every conversation. - public static readonly SecretName Qdrant = new(QdrantApiKeyName, QdrantApiKeyVariable); + /// The Qdrant API key the vector store sends on every conversation. + public static readonly SecretName Qdrant = new(QdrantApiKeyName, QdrantApiKeyVariable); - /// The PostgreSQL connection string the audit chain and the transcript are written through. - public static readonly SecretName PostgresConnectionString = - new(PostgresConnectionStringName, PostgresConnectionStringVariable); + /// The PostgreSQL connection string the audit chain and the transcript are written through. + public static readonly SecretName PostgresConnectionString = + new(PostgresConnectionStringName, PostgresConnectionStringVariable); - /// The Grafana Cloud instance id, which is the user half of the OTLP basic credential. - public static readonly SecretName GrafanaCloudInstanceId = - new(GrafanaCloudInstanceIdName, GrafanaCloudInstanceIdVariable); + /// The Grafana Cloud instance id, which is the user half of the OTLP basic credential. + public static readonly SecretName GrafanaCloudInstanceId = + new(GrafanaCloudInstanceIdName, GrafanaCloudInstanceIdVariable); - /// The Grafana Cloud token, which is the password half of the OTLP basic credential. - public static readonly SecretName GrafanaCloudApiToken = - new(GrafanaCloudApiTokenName, GrafanaCloudApiTokenVariable); + /// The Grafana Cloud token, which is the password half of the OTLP basic credential. + public static readonly SecretName GrafanaCloudApiToken = + new(GrafanaCloudApiTokenName, GrafanaCloudApiTokenVariable); - /// The key id half of the S3 credential. Backblaze B2 calls it the keyID. - public static readonly SecretName S3AccessKeyId = new(S3AccessKeyIdName, S3AccessKeyIdVariable); + /// The key id half of the S3 credential. Backblaze B2 calls it the keyID. + public static readonly SecretName S3AccessKeyId = new(S3AccessKeyIdName, S3AccessKeyIdVariable); - /// The secret half of the S3 credential. Backblaze B2 calls it the applicationKey. - public static readonly SecretName S3SecretAccessKey = - new(S3SecretAccessKeyName, S3SecretAccessKeyVariable); + /// The secret half of the S3 credential. Backblaze B2 calls it the applicationKey. + public static readonly SecretName S3SecretAccessKey = + new(S3SecretAccessKeyName, S3SecretAccessKeyVariable); + } } diff --git a/src/AgentCore.Application/Secrets/ResolvedSecrets.cs b/src/AgentCore.Application/Secrets/ResolvedSecrets.cs index f0a10ebb..aae8c275 100644 --- a/src/AgentCore.Application/Secrets/ResolvedSecrets.cs +++ b/src/AgentCore.Application/Secrets/ResolvedSecrets.cs @@ -3,171 +3,177 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; -namespace AgentCore.Application.Secrets; - -/// -/// Every ${secret:name} value one document needs, read once at startup. -/// -public sealed class ResolvedSecrets +namespace AgentCore.Application.Secrets { - private readonly Dictionary _values; - - private ResolvedSecrets(Dictionary values) => _values = values; + /// + /// Every ${secret:name} value one document needs, read once at startup. + /// + public sealed class ResolvedSecrets + { + private readonly Dictionary _values; - /// Gets the set that holds no secret. - public static ResolvedSecrets Empty { get; } = new(new Dictionary(StringComparer.Ordinal)); + private ResolvedSecrets(Dictionary values) + { + _values = values; + } - /// Gets the number of names this set holds. - public int Count => _values.Count; + /// Gets the set that holds no secret. + public static ResolvedSecrets Empty { get; } = new(new Dictionary(StringComparer.Ordinal)); - /// Gets the names this set holds. It never gets the values. - public IReadOnlyCollection Names => _values.Keys; + /// Gets the number of names this set holds. + public int Count => _values.Count; - /// Builds a set from names a host already holds. - /// The name and value pairs. - /// The set. - public static ResolvedSecrets Create(IEnumerable> secrets) - { - ArgumentNullException.ThrowIfNull(secrets); + /// Gets the names this set holds. It never gets the values. + public IReadOnlyCollection Names => _values.Keys; - Dictionary values = new(StringComparer.Ordinal); - foreach (var secret in secrets) + /// Builds a set from names a host already holds. + /// The name and value pairs. + /// The set. + public static ResolvedSecrets Create(IEnumerable> secrets) { - values[secret.Key] = secret.Value; - } + ArgumentNullException.ThrowIfNull(secrets); - return values.Count == 0 ? Empty : new ResolvedSecrets(values); - } + Dictionary values = new(StringComparer.Ordinal); + foreach (KeyValuePair secret in secrets) + { + values[secret.Key] = secret.Value; + } - /// Resolves every reference one loaded document holds. - /// The loaded document. - /// The chain that reads a secret. - /// Cancels the walk. - /// The set the tool factory formats against. - /// One name resolves to nothing. - public static async ValueTask ResolveAsync( - AgentCoreConfiguration configuration, - ISecretResolverPort resolver, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(resolver); + return values.Count == 0 ? Empty : new ResolvedSecrets(values); + } - Dictionary values = new(StringComparer.Ordinal); - foreach (var (template, pointer) in Templates(configuration)) + /// Resolves every reference one loaded document holds. + /// The loaded document. + /// The chain that reads a secret. + /// Cancels the walk. + /// The set the tool factory formats against. + /// One name resolves to nothing. + public static async ValueTask ResolveAsync( + AgentCoreConfiguration configuration, + ISecretResolverPort resolver, + CancellationToken cancellationToken = default) { - foreach (var name in template.References.Select(reference => reference.Name)) + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(resolver); + + Dictionary values = new(StringComparer.Ordinal); + foreach ((SecretTemplate? template, string? pointer) in Templates(configuration)) { - if (values.ContainsKey(name)) + foreach (string? name in template.References.Select(reference => reference.Name)) { - // One name costs one read, however many strings reference it. - continue; + if (values.ContainsKey(name)) + { + // One name costs one read, however many strings reference it. + continue; + } + + string? value = await resolver.TryResolveAsync(name, cancellationToken).ConfigureAwait(false); + values[name] = value + ?? throw SecretResolutionException.Unresolved(name, pointer); } - - var value = await resolver.TryResolveAsync(name, cancellationToken).ConfigureAwait(false); - values[name] = value - ?? throw SecretResolutionException.Unresolved(name, pointer); } - } - return values.Count == 0 ? Empty : new ResolvedSecrets(values); - } + return values.Count == 0 ? Empty : new ResolvedSecrets(values); + } - /// Reports whether the set holds one name. - /// The secret name. - /// when the name resolved. - public bool Contains(string name) - { - ArgumentNullException.ThrowIfNull(name); - return _values.ContainsKey(name); - } + /// Reports whether the set holds one name. + /// The secret name. + /// when the name resolved. + public bool Contains(string name) + { + ArgumentNullException.ThrowIfNull(name); + return _values.ContainsKey(name); + } - /// Rebuilds one configuration string with every reference replaced by its value. - /// The template the parser produced. - /// The text with no reference left in it. - /// The template references a name this set does not hold. - public string Format(SecretTemplate template) - { - ArgumentNullException.ThrowIfNull(template); + /// Rebuilds one configuration string with every reference replaced by its value. + /// The template the parser produced. + /// The text with no reference left in it. + /// The template references a name this set does not hold. + public string Format(SecretTemplate template) + { + ArgumentNullException.ThrowIfNull(template); - return template.Format(name => _values.TryGetValue(name, out var value) - ? value - : throw SecretResolutionException.Unresolved(name)); - } + return template.Format(name => _values.TryGetValue(name, out string? value) + ? value + : throw SecretResolutionException.Unresolved(name)); + } - /// Writes how many names the set holds, and never what they are worth. - /// The count, as text. - public override string ToString() - => "ResolvedSecrets(" + _values.Count.ToString(CultureInfo.InvariantCulture) + " names)"; + /// Writes how many names the set holds, and never what they are worth. + /// The count, as text. + public override string ToString() + { + return "ResolvedSecrets(" + _values.Count.ToString(CultureInfo.InvariantCulture) + " names)"; + } - /// Walks every string of one document that may hold a reference. - private static IEnumerable<(SecretTemplate Template, string Pointer)> Templates(AgentCoreConfiguration configuration) - { - for (var index = 0; index < configuration.Tools.Count; index++) + /// Walks every string of one document that may hold a reference. + private static IEnumerable<(SecretTemplate Template, string Pointer)> Templates(AgentCoreConfiguration configuration) { - if (configuration.Tools[index].Request is not { } request) + for (int index = 0; index < configuration.Tools.Count; index++) { - continue; - } + if (configuration.Tools[index].Request is not { } request) + { + continue; + } - var headers = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer("/tools", index), "request"), - "headers"); + string headers = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer("/tools", index), "request"), + "headers"); - foreach (var reference in In(request.Headers, headers)) - { - yield return reference; + foreach ((SecretTemplate Template, string Pointer) reference in In(request.Headers, headers)) + { + yield return reference; + } } - } - for (var index = 0; index < configuration.Mcp.Count; index++) - { - var server = configuration.Mcp[index]; - var pointer = ConfigurationError.AppendPointer("/mcp", index); - - // A server declares one or the other: the schema's transport branches reject env: on http - // and headers: on stdio. Both are walked because this walk answers "what does the document - // reference", not "which transport is this". - foreach (var reference in In(server.Headers, ConfigurationError.AppendPointer(pointer, "headers"))) + for (int index = 0; index < configuration.Mcp.Count; index++) { - yield return reference; - } + McpServerConfiguration server = configuration.Mcp[index]; + string pointer = ConfigurationError.AppendPointer("/mcp", index); - foreach (var reference in In(server.Env, ConfigurationError.AppendPointer(pointer, "env"))) - { - yield return reference; + // A server declares one or the other: the schema's transport branches reject env: on http + // and headers: on stdio. Both are walked because this walk answers "what does the document + // reference", not "which transport is this". + foreach ((SecretTemplate Template, string Pointer) reference in In(server.Headers, ConfigurationError.AppendPointer(pointer, "headers"))) + { + yield return reference; + } + + foreach ((SecretTemplate Template, string Pointer) reference in In(server.Env, ConfigurationError.AppendPointer(pointer, "env"))) + { + yield return reference; + } } - } - for (var index = 0; index < configuration.Agents.Items.Count; index++) - { - if (configuration.Agents.Items[index].Shell is not { } shell) + for (int index = 0; index < configuration.Agents.Items.Count; index++) { - continue; - } + if (configuration.Agents.Items[index].Shell is not { } shell) + { + continue; + } - var env = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer("/agents/items", index), "shell"), - "env"); + string env = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer("/agents/items", index), "shell"), + "env"); - foreach (var reference in In(shell.Env, env)) - { - yield return reference; + foreach ((SecretTemplate Template, string Pointer) reference in In(shell.Env, env)) + { + yield return reference; + } } } - } - /// Yields every entry of one string map that references a secret. - private static IEnumerable<(SecretTemplate Template, string Pointer)> In( - IReadOnlyDictionary entries, string pointer) - { - foreach (var entry in entries) + /// Yields every entry of one string map that references a secret. + private static IEnumerable<(SecretTemplate Template, string Pointer)> In( + IReadOnlyDictionary entries, string pointer) { - if (entry.Value.HasSecretReferences) + foreach (KeyValuePair entry in entries) { - yield return (entry.Value, ConfigurationError.AppendPointer(pointer, entry.Key)); + if (entry.Value.HasSecretReferences) + { + yield return (entry.Value, ConfigurationError.AppendPointer(pointer, entry.Key)); + } } } } diff --git a/src/AgentCore.Application/Secrets/SecretName.cs b/src/AgentCore.Application/Secrets/SecretName.cs index 34b24156..69914cdd 100644 --- a/src/AgentCore.Application/Secrets/SecretName.cs +++ b/src/AgentCore.Application/Secrets/SecretName.cs @@ -1,51 +1,55 @@ using System.Runtime.CompilerServices; -namespace AgentCore.Application.Secrets; - -/// -/// One credential, named twice: the way a document writes it and the way a shell writes it. -/// -/// -/// -/// A vendor adapter needs both halves at once. It asks the ISecretResolverPort chain for -/// , the name a document writes as ${secret:name}, and it reads -/// when the chain holds nothing, because a deployment that never wrote a -/// document still has the variable every tool of that vendor already reads. Two loose strings drift -/// apart the day one of them moves, so they travel as one value. -/// -/// -/// A name is not a secret. This type holds what a credential is called and never what it is worth, -/// so it is safe in a message, a log line, and this file. -/// -/// -/// Both halves are required, and the constructor is where that is settled: a pair with a blank half -/// would ask the chain for nothing, or fall back to nothing, and the failure would arrive as a -/// missing key rather than as the typo it is. The two properties are read-only for the same reason, -/// so a pair that exists is a pair that was checked. -/// -/// -/// The name between the colon and the closing brace of ${secret:name}. -/// The environment variable that answers when the chain holds nothing. -public sealed record SecretName(string Name, string VariableName) +namespace AgentCore.Application.Secrets { - /// Gets the name the resolver chain is asked for. - public string Name { get; } = Required(Name); + /// + /// One credential, named twice: the way a document writes it and the way a shell writes it. + /// + /// + /// + /// A vendor adapter needs both halves at once. It asks the ISecretResolverPort chain for + /// , the name a document writes as ${secret:name}, and it reads + /// when the chain holds nothing, because a deployment that never wrote a + /// document still has the variable every tool of that vendor already reads. Two loose strings drift + /// apart the day one of them moves, so they travel as one value. + /// + /// + /// A name is not a secret. This type holds what a credential is called and never what it is worth, + /// so it is safe in a message, a log line, and this file. + /// + /// + /// Both halves are required, and the constructor is where that is settled: a pair with a blank half + /// would ask the chain for nothing, or fall back to nothing, and the failure would arrive as a + /// missing key rather than as the typo it is. The two properties are read-only for the same reason, + /// so a pair that exists is a pair that was checked. + /// + /// + /// The name between the colon and the closing brace of ${secret:name}. + /// The environment variable that answers when the chain holds nothing. + public sealed record SecretName(string Name, string VariableName) + { + /// Gets the name the resolver chain is asked for. + public string Name { get; } = Required(Name); - /// Gets the environment variable read when the chain holds nothing. - public string VariableName { get; } = Required(VariableName); + /// Gets the environment variable read when the chain holds nothing. + public string VariableName { get; } = Required(VariableName); - /// Writes both names, because neither one is a value. - /// The text name (VARIABLE). - public override string ToString() => Name + " (" + VariableName + ")"; + /// Writes both names, because neither one is a value. + /// The text name (VARIABLE). + public override string ToString() + { + return Name + " (" + VariableName + ")"; + } - /// Refuses a half that names nothing. - /// The name given. - /// Which half it is, for the exception to report. Filled in by the compiler. - /// The name. - /// The name is null, empty, or blank. - private static string Required(string value, [CallerArgumentExpression(nameof(value))] string parameter = "") - { - ArgumentException.ThrowIfNullOrWhiteSpace(value, parameter); - return value; + /// Refuses a half that names nothing. + /// The name given. + /// Which half it is, for the exception to report. Filled in by the compiler. + /// The name. + /// The name is null, empty, or blank. + private static string Required(string value, [CallerArgumentExpression(nameof(value))] string parameter = "") + { + ArgumentException.ThrowIfNullOrWhiteSpace(value, parameter); + return value; + } } } diff --git a/src/AgentCore.Application/Secrets/SecretResolutionException.cs b/src/AgentCore.Application/Secrets/SecretResolutionException.cs index 686d4831..e3231bc5 100644 --- a/src/AgentCore.Application/Secrets/SecretResolutionException.cs +++ b/src/AgentCore.Application/Secrets/SecretResolutionException.cs @@ -1,56 +1,69 @@ -namespace AgentCore.Application.Secrets; - -/// -/// The one exception a secret reference raises when nothing resolves it. -/// -/// -/// It fails at startup, like every other configuration failure, so a conversation never discovers a missing -/// credential in the middle of a turn. The message names the secret and the place the document -/// wrote it. It never holds the value of any secret, resolved or not. -/// -public sealed class SecretResolutionException : Exception +namespace AgentCore.Application.Secrets { - private const string DefaultMessage = "A ${secret:name} reference did not resolve."; + /// + /// The one exception a secret reference raises when nothing resolves it. + /// + /// + /// It fails at startup, like every other configuration failure, so a conversation never discovers a missing + /// credential in the middle of a turn. The message names the secret and the place the document + /// wrote it. It never holds the value of any secret, resolved or not. + /// + public sealed class SecretResolutionException : Exception + { + private const string DefaultMessage = "A ${secret:name} reference did not resolve."; - /// Creates an exception that names no secret. - public SecretResolutionException() - : base(DefaultMessage) => SecretName = string.Empty; + /// Creates an exception that names no secret. + public SecretResolutionException() + : base(DefaultMessage) + { + SecretName = string.Empty; + } - /// Creates an exception with a plain message. - /// The message a human reads. It never holds a secret value. - public SecretResolutionException(string message) - : base(message) => SecretName = string.Empty; + /// Creates an exception with a plain message. + /// The message a human reads. It never holds a secret value. + public SecretResolutionException(string message) + : base(message) + { + SecretName = string.Empty; + } - /// Creates an exception with a plain message and an inner cause. - /// The message a human reads. It never holds a secret value. - /// The cause. - public SecretResolutionException(string message, Exception? innerException) - : base(message, innerException) => SecretName = string.Empty; + /// Creates an exception with a plain message and an inner cause. + /// The message a human reads. It never holds a secret value. + /// The cause. + public SecretResolutionException(string message, Exception? innerException) + : base(message, innerException) + { + SecretName = string.Empty; + } - private SecretResolutionException(string secretName, string message, Exception? innerException) - : base(message, innerException) => SecretName = secretName; + private SecretResolutionException(string secretName, string message, Exception? innerException) + : base(message, innerException) + { + SecretName = secretName; + } - /// Gets the name of the secret that did not resolve, or an empty string. - public string SecretName { get; } + /// Gets the name of the secret that did not resolve, or an empty string. + public string SecretName { get; } - /// Builds the failure for one name that no resolver holds. - /// The secret name the document wrote. - /// The JSON Pointer to the string that holds the reference, or . - /// The cause, when one exists. - /// The failure. - public static SecretResolutionException Unresolved( - string secretName, - string? documentPointer = null, - Exception? innerException = null) - { - ArgumentNullException.ThrowIfNull(secretName); + /// Builds the failure for one name that no resolver holds. + /// The secret name the document wrote. + /// The JSON Pointer to the string that holds the reference, or . + /// The cause, when one exists. + /// The failure. + public static SecretResolutionException Unresolved( + string secretName, + string? documentPointer = null, + Exception? innerException = null) + { + ArgumentNullException.ThrowIfNull(secretName); - var where = documentPointer is { Length: > 0 } ? $" {documentPointer} reads it." : string.Empty; - return new SecretResolutionException( - secretName, - $"the secret '{secretName}' did not resolve.{where} No resolver in the chain holds that name. " - + "AgentCore resolves every ${secret:name} reference at startup, so this fails before the " - + "first conversation rather than during one.", - innerException); + string where = documentPointer is { Length: > 0 } ? $" {documentPointer} reads it." : string.Empty; + return new SecretResolutionException( + secretName, + $"the secret '{secretName}' did not resolve.{where} No resolver in the chain holds that name. " + + "AgentCore resolves every ${secret:name} reference at startup, so this fails before the " + + "first conversation rather than during one.", + innerException); + } } } diff --git a/src/AgentCore.Application/Secrets/SecretResolverExtensions.cs b/src/AgentCore.Application/Secrets/SecretResolverExtensions.cs index 887a4ce2..61067af2 100644 --- a/src/AgentCore.Application/Secrets/SecretResolverExtensions.cs +++ b/src/AgentCore.Application/Secrets/SecretResolverExtensions.cs @@ -1,121 +1,122 @@ using AgentCore.Application.Ports; -namespace AgentCore.Application.Secrets; - -/// -/// The one way a vendor adapter reads a credential it cannot start without. -/// -/// -/// -/// answers for a name it does not hold, -/// because a chain has to be able to try the next link. An adapter that needs a key therefore has a -/// second question to answer: what to do with the miss. Every adapter answered it the same way, in -/// its own copy of the same three steps, and the copies drifted in their wording while agreeing on -/// their behaviour. This extension is that answer, written once. -/// -/// -/// The steps are: ask the chain by when a chain was bound, then read -/// the variable, then fail. Only moves -/// the read on to the next step. A chain that answers a blank string has answered: the name was -/// held, and the store behind it is empty. That fails here and never falls back, because a mounted -/// secret file that renders empty is a deployment defect, and reading the variable instead would -/// start the host on some other key it was never told to use. -/// -/// -/// A blank variable fails the same way, for the same reason: a key that is the empty string only -/// fails later, at the vendor, as a 401 that names nothing. -/// -/// -/// The failure is , so a missing credential is a startup -/// failure like every other configuration failure and a conversation never discovers one mid-turn. The -/// message names both halves, because the reader has two places to put a key and needs to be told -/// both. It never holds the value of anything, resolved or not. -/// -/// -public static class SecretResolverExtensions +namespace AgentCore.Application.Secrets { - /// Reads one credential through the chain, then the environment, without failing. - /// - /// The resolver chain, or to read the environment alone. - /// - /// The credential, named both ways. - /// Cancels the read. - /// - /// The value, or when neither the chain nor the environment holds the - /// name. An empty string is not a miss: it means a store held the name and answered nothing, - /// which is a deployment defect the caller decides what to do about. - /// - /// is . + /// + /// The one way a vendor adapter reads a credential it cannot start without. + /// /// /// - /// This is for a credential a host may legitimately not have, where the absence selects a - /// different path rather than failing one. is - /// the case that asked for it: no instance id means export to a local collector with no - /// credential, and an instance id means the token beside it is then mandatory. + /// answers for a name it does not hold, + /// because a chain has to be able to try the next link. An adapter that needs a key therefore has a + /// second question to answer: what to do with the miss. Every adapter answered it the same way, in + /// its own copy of the same three steps, and the copies drifted in their wording while agreeing on + /// their behaviour. This extension is that answer, written once. + /// + /// + /// The steps are: ask the chain by when a chain was bound, then read + /// the variable, then fail. Only moves + /// the read on to the next step. A chain that answers a blank string has answered: the name was + /// held, and the store behind it is empty. That fails here and never falls back, because a mounted + /// secret file that renders empty is a deployment defect, and reading the variable instead would + /// start the host on some other key it was never told to use. + /// + /// + /// A blank variable fails the same way, for the same reason: a key that is the empty string only + /// fails later, at the vendor, as a 401 that names nothing. /// /// - /// is this read plus the failure, so the chain-then-environment order - /// is written once and the two paths cannot drift. + /// The failure is , so a missing credential is a startup + /// failure like every other configuration failure and a conversation never discovers one mid-turn. The + /// message names both halves, because the reader has two places to put a key and needs to be told + /// both. It never holds the value of anything, resolved or not. /// /// - public static async ValueTask TryReadAsync( - this ISecretResolverPort? secrets, - SecretName secret, - CancellationToken cancellationToken = default) + public static class SecretResolverExtensions { - ArgumentNullException.ThrowIfNull(secret); - - string? value = null; - if (secrets is not null) + /// Reads one credential through the chain, then the environment, without failing. + /// + /// The resolver chain, or to read the environment alone. + /// + /// The credential, named both ways. + /// Cancels the read. + /// + /// The value, or when neither the chain nor the environment holds the + /// name. An empty string is not a miss: it means a store held the name and answered nothing, + /// which is a deployment defect the caller decides what to do about. + /// + /// is . + /// + /// + /// This is for a credential a host may legitimately not have, where the absence selects a + /// different path rather than failing one. is + /// the case that asked for it: no instance id means export to a local collector with no + /// credential, and an instance id means the token beside it is then mandatory. + /// + /// + /// is this read plus the failure, so the chain-then-environment order + /// is written once and the two paths cannot drift. + /// + /// + public static async ValueTask TryReadAsync( + this ISecretResolverPort? secrets, + SecretName secret, + CancellationToken cancellationToken = default) { - value = await secrets.TryResolveAsync(secret.Name, cancellationToken).ConfigureAwait(false); - } + ArgumentNullException.ThrowIfNull(secret); - // Only a null moves on. A chain that answered a blank string held the name, and a held name - // that is empty is a broken store rather than a miss: falling back would swap in a key the - // deployment never named. - return value ?? Environment.GetEnvironmentVariable(secret.VariableName); - } + string? value = null; + if (secrets is not null) + { + value = await secrets.TryResolveAsync(secret.Name, cancellationToken).ConfigureAwait(false); + } - /// Reads one credential through the chain, then the environment, or fails. - /// - /// The resolver chain, or to read the environment alone. A host that binds - /// no chain is an ordinary case, so this takes the null rather than making each caller test for - /// it. - /// - /// The credential, named both ways. - /// - /// One sentence saying what this caller needed the key for, written whole and ending in a full - /// stop, or when the name says enough. It lands between the failure and - /// the two places to put a key, so a host that never asked for an embedding model learns why one - /// was asking for an OpenAI key. - /// - /// Cancels the read. - /// The value. - /// is . - /// Neither the chain nor the environment holds it. - public static async ValueTask RequireAsync( - this ISecretResolverPort? secrets, - SecretName secret, - string? because = null, - CancellationToken cancellationToken = default) - { - string? value = await secrets.TryReadAsync(secret, cancellationToken).ConfigureAwait(false); + // Only a null moves on. A chain that answered a blank string held the name, and a held name + // that is empty is a broken store rather than a miss: falling back would swap in a key the + // deployment never named. + return value ?? Environment.GetEnvironmentVariable(secret.VariableName); + } - return value is { Length: > 0 } ? value : throw Missing(secret, because); - } + /// Reads one credential through the chain, then the environment, or fails. + /// + /// The resolver chain, or to read the environment alone. A host that binds + /// no chain is an ordinary case, so this takes the null rather than making each caller test for + /// it. + /// + /// The credential, named both ways. + /// + /// One sentence saying what this caller needed the key for, written whole and ending in a full + /// stop, or when the name says enough. It lands between the failure and + /// the two places to put a key, so a host that never asked for an embedding model learns why one + /// was asking for an OpenAI key. + /// + /// Cancels the read. + /// The value. + /// is . + /// Neither the chain nor the environment holds it. + public static async ValueTask RequireAsync( + this ISecretResolverPort? secrets, + SecretName secret, + string? because = null, + CancellationToken cancellationToken = default) + { + string? value = await secrets.TryReadAsync(secret, cancellationToken).ConfigureAwait(false); - /// Builds the failure a credential that is nowhere produces. - /// The credential, named both ways. - /// What the caller needed it for, or . - /// The failure. It names the two places to put a key, and no value. - private static SecretResolutionException Missing(SecretName secret, string? because) - { - var why = because is { Length: > 0 } ? " " + because : string.Empty; + return value is { Length: > 0 } ? value : throw Missing(secret, because); + } + + /// Builds the failure a credential that is nowhere produces. + /// The credential, named both ways. + /// What the caller needed it for, or . + /// The failure. It names the two places to put a key, and no value. + private static SecretResolutionException Missing(SecretName secret, string? because) + { + string why = because is { Length: > 0 } ? " " + because : string.Empty; - return new SecretResolutionException( - "the secret '" + secret.Name + "' did not resolve." + why + " Bind a resolver that holds '" - + secret.Name + "', or set the " + secret.VariableName - + " variable. Nothing on this path holds a key of its own."); + return new SecretResolutionException( + "the secret '" + secret.Name + "' did not resolve." + why + " Bind a resolver that holds '" + + secret.Name + "', or set the " + secret.VariableName + + " variable. Nothing on this path holds a key of its own."); + } } } diff --git a/src/AgentCore.Application/Sessions/Memory/InMemoryConversationSessions.cs b/src/AgentCore.Application/Sessions/Memory/InMemoryConversationSessions.cs index b4e39937..9c04e2fd 100644 --- a/src/AgentCore.Application/Sessions/Memory/InMemoryConversationSessions.cs +++ b/src/AgentCore.Application/Sessions/Memory/InMemoryConversationSessions.cs @@ -3,159 +3,160 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; -namespace AgentCore.Application.Sessions.Memory; - -/// -/// The default . It holds every session in this process. -/// -/// -/// -/// This does not survive a restart and does not span instances. A process that stops loses every -/// call it was holding, and a second instance behind a load balancer never sees the sessions of the -/// first. A deployment that needs either registers another before -/// AddAgentCore, and this steps aside. -/// -/// -/// A session is dropped when it has been untouched for the idle timeout. The voice path does not -/// wait for that — the socket closing is a real end, and it closes the conversation itself. The timeout is -/// for the text path, where a caller who simply stops replying never reaches a terminal stage and -/// would otherwise be held for the life of the process. -/// -/// -public sealed class InMemoryConversationSessions : IConversationSessions +namespace AgentCore.Application.Sessions.Memory { - /// The idle timeout a host gets when it names none. - public static readonly TimeSpan DefaultIdleTimeout = TimeSpan.FromMinutes(30); - - private readonly ConcurrentDictionary _sessions = new(StringComparer.Ordinal); - private readonly IConversationSessionFactory _factory; - private readonly TimeSpan _idleTimeout; - private readonly TimeProvider _time; - - /// Creates the store. - /// Builds the session of a conversation that is not held yet. - /// How long an untouched session is kept. It slides on every read. - /// The clock the idle timeout is measured on. - public InMemoryConversationSessions( - IConversationSessionFactory factory, TimeSpan idleTimeout, TimeProvider timeProvider) + /// + /// The default . It holds every session in this process. + /// + /// + /// + /// This does not survive a restart and does not span instances. A process that stops loses every + /// call it was holding, and a second instance behind a load balancer never sees the sessions of the + /// first. A deployment that needs either registers another before + /// AddAgentCore, and this steps aside. + /// + /// + /// A session is dropped when it has been untouched for the idle timeout. The voice path does not + /// wait for that — the socket closing is a real end, and it closes the conversation itself. The timeout is + /// for the text path, where a caller who simply stops replying never reaches a terminal stage and + /// would otherwise be held for the life of the process. + /// + /// + public sealed class InMemoryConversationSessions : IConversationSessions { - ArgumentNullException.ThrowIfNull(factory); - ArgumentNullException.ThrowIfNull(timeProvider); - ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(idleTimeout, TimeSpan.Zero); - - _factory = factory; - _idleTimeout = idleTimeout; - _time = timeProvider; - } + /// The idle timeout a host gets when it names none. + public static readonly TimeSpan DefaultIdleTimeout = TimeSpan.FromMinutes(30); + + private readonly ConcurrentDictionary _sessions = new(StringComparer.Ordinal); + private readonly IConversationSessionFactory _factory; + private readonly TimeSpan _idleTimeout; + private readonly TimeProvider _time; + + /// Creates the store. + /// Builds the session of a conversation that is not held yet. + /// How long an untouched session is kept. It slides on every read. + /// The clock the idle timeout is measured on. + public InMemoryConversationSessions( + IConversationSessionFactory factory, TimeSpan idleTimeout, TimeProvider timeProvider) + { + ArgumentNullException.ThrowIfNull(factory); + ArgumentNullException.ThrowIfNull(timeProvider); + ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(idleTimeout, TimeSpan.Zero); - /// Gets how many sessions this holds. - public int Count => _sessions.Count; + _factory = factory; + _idleTimeout = idleTimeout; + _time = timeProvider; + } - /// - public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) - { - cancellationToken.ThrowIfCancellationRequested(); + /// Gets how many sessions this holds. + public int Count => _sessions.Count; - var session = _factory.Create(conversationId); - _sessions[session.ConversationId] = new Entry(session, _time.GetUtcNow()); - return ValueTask.FromResult(session); - } + /// + public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) + { + cancellationToken.ThrowIfCancellationRequested(); - /// - public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - cancellationToken.ThrowIfCancellationRequested(); + ConversationSession session = _factory.Create(conversationId); + _sessions[session.ConversationId] = new Entry(session, _time.GetUtcNow()); + return ValueTask.FromResult(session); + } - if (!_sessions.TryGetValue(conversationId, out var entry)) + /// + public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) { - return ValueTask.FromResult(null); - } + ArgumentNullException.ThrowIfNull(conversationId); + cancellationToken.ThrowIfCancellationRequested(); - _sessions.TryUpdate(conversationId, entry with { Touched = _time.GetUtcNow() }, entry); - return ValueTask.FromResult(entry.Session); - } + if (!_sessions.TryGetValue(conversationId, out Entry? entry)) + { + return ValueTask.FromResult(null); + } - /// - public async ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + _ = _sessions.TryUpdate(conversationId, entry with { Touched = _time.GetUtcNow() }, entry); + return ValueTask.FromResult(entry.Session); + } - // Taken out first so a second caller cannot be handed a session that is already draining, - // then flushed while this method still holds the only reference to it. - if (_sessions.TryRemove(conversationId, out var entry)) + /// + public async ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) { - // A store that throws on flush must not leave the session's shells running with - // nothing left to hold a reference to them. - try - { - await entry.Session.FlushTranscriptAsync().ConfigureAwait(false); - } - finally + ArgumentNullException.ThrowIfNull(conversationId); + + // Taken out first so a second caller cannot be handed a session that is already draining, + // then flushed while this method still holds the only reference to it. + if (_sessions.TryRemove(conversationId, out Entry? entry)) { - await entry.Session.DisposeAsync().ConfigureAwait(false); + // A store that throws on flush must not leave the session's shells running with + // nothing left to hold a reference to them. + try + { + await entry.Session.FlushTranscriptAsync().ConfigureAwait(false); + } + finally + { + await entry.Session.DisposeAsync().ConfigureAwait(false); + } } } - } - - /// Closes every session that has been untouched for the idle timeout. - /// Cancels the sweep. - /// A task that completes once every expired session is closed. - /// - /// One or more sessions could not be ended. The sweep still visited every other session first. - /// - /// - /// This goes through and not the dictionary, so an expiring session - /// hands over its words on the way out exactly as one the host closed by hand. - /// - public async ValueTask SweepAsync(CancellationToken cancellationToken = default) - { - var cutoff = _time.GetUtcNow() - _idleTimeout; - List? faults = null; - foreach (var (conversationId, entry) in _sessions.ToArray()) + /// Closes every session that has been untouched for the idle timeout. + /// Cancels the sweep. + /// A task that completes once every expired session is closed. + /// + /// One or more sessions could not be ended. The sweep still visited every other session first. + /// + /// + /// This goes through and not the dictionary, so an expiring session + /// hands over its words on the way out exactly as one the host closed by hand. + /// + public async ValueTask SweepAsync(CancellationToken cancellationToken = default) { - cancellationToken.ThrowIfCancellationRequested(); + DateTimeOffset cutoff = _time.GetUtcNow() - _idleTimeout; + List? faults = null; - if (entry.Touched > cutoff) + foreach ((string? conversationId, Entry? entry) in _sessions.ToArray()) { - continue; + cancellationToken.ThrowIfCancellationRequested(); + + if (entry.Touched > cutoff) + { + continue; + } + + // One session that will not end must not leave every session after it in the + // dictionary for the life of the process, which is the leak this sweep exists to stop. + try + { + await ExpireAsync(conversationId, entry.Session, cancellationToken).ConfigureAwait(false); + } + catch (Exception fault) when (fault is not OperationCanceledException) + { + (faults ??= []).Add(fault); + } } - // One session that will not end must not leave every session after it in the - // dictionary for the life of the process, which is the leak this sweep exists to stop. - try - { - await ExpireAsync(conversationId, entry.Session, cancellationToken).ConfigureAwait(false); - } - catch (Exception fault) when (fault is not OperationCanceledException) + if (faults is not null) { - (faults ??= []).Add(fault); + throw new AggregateException(faults); } } - if (faults is not null) + /// Ends one expired conversation, chain first and session second. + /// + /// §11 item 6 makes conversation.ended the last event of every conversation, and expiry is a way a conversation + /// ends. Nothing else writes it here: the relay closes its own chain from the socket and the + /// turn loop closes its own from a terminal stage, so a caller who simply stops replying is the + /// one ending that would otherwise leave a chain with no end. + /// is idempotent, so a session that already closed its chain keeps the reason it wrote. + /// The reason is because the closed set of §6 holds no + /// reason for an abandoned conversation; see the amendment owed on that enum. + /// + private async ValueTask ExpireAsync( + string conversationId, ConversationSession session, CancellationToken cancellationToken) { - throw new AggregateException(faults); + _ = session.EndConversation(ConversationEndReason.Faulted); + await CloseAsync(conversationId, cancellationToken).ConfigureAwait(false); } - } - /// Ends one expired conversation, chain first and session second. - /// - /// §11 item 6 makes conversation.ended the last event of every conversation, and expiry is a way a conversation - /// ends. Nothing else writes it here: the relay closes its own chain from the socket and the - /// turn loop closes its own from a terminal stage, so a caller who simply stops replying is the - /// one ending that would otherwise leave a chain with no end. - /// is idempotent, so a session that already closed its chain keeps the reason it wrote. - /// The reason is because the closed set of §6 holds no - /// reason for an abandoned conversation; see the amendment owed on that enum. - /// - private async ValueTask ExpireAsync( - string conversationId, ConversationSession session, CancellationToken cancellationToken) - { - _ = session.EndConversation(ConversationEndReason.Faulted); - await CloseAsync(conversationId, cancellationToken).ConfigureAwait(false); + private sealed record Entry(ConversationSession Session, DateTimeOffset Touched); } - - private sealed record Entry(ConversationSession Session, DateTimeOffset Touched); } diff --git a/src/AgentCore.Application/Skills/PinnedSkillsProvider.cs b/src/AgentCore.Application/Skills/PinnedSkillsProvider.cs index daff3faf..4870e0a5 100644 --- a/src/AgentCore.Application/Skills/PinnedSkillsProvider.cs +++ b/src/AgentCore.Application/Skills/PinnedSkillsProvider.cs @@ -1,106 +1,107 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Skills; - -/// -/// The bodies of an agent's pinned: skills, appended to its instructions on every turn. -/// -internal sealed class PinnedSkillsProvider : AIContextProvider +namespace AgentCore.Application.Skills { - private const string FrontmatterFence = "---"; + /// + /// The bodies of an agent's pinned: skills, appended to its instructions on every turn. + /// + internal sealed class PinnedSkillsProvider : AIContextProvider + { + private const string FrontmatterFence = "---"; - private const string ManifestStart = "\n _names; - - private string? _instructions; + private readonly IReadOnlyList _names; - /// Creates the provider. - /// The skills the host bound, shared by every agent. - /// The names this agent pins, in the order their bodies appear. - /// An argument is . - /// is empty. - internal PinnedSkillsProvider(SkillCatalog catalog, IReadOnlyList names) - { - ArgumentNullException.ThrowIfNull(catalog); - ArgumentNullException.ThrowIfNull(names); + private string? _instructions; - if (names.Count == 0) + /// Creates the provider. + /// The skills the host bound, shared by every agent. + /// The names this agent pins, in the order their bodies appear. + /// An argument is . + /// is empty. + internal PinnedSkillsProvider(SkillCatalog catalog, IReadOnlyList names) { - throw new ArgumentException("A pinned skills provider needs at least one skill name.", nameof(names)); - } - - _catalog = catalog; - _names = names; - } + ArgumentNullException.ThrowIfNull(catalog); + ArgumentNullException.ThrowIfNull(names); - /// - protected override async ValueTask ProvideAIContextAsync( - InvokingContext context, - CancellationToken cancellationToken = default) - { - return new AIContext - { - Instructions = _instructions ?? await ReadAsync(context, cancellationToken).ConfigureAwait(false), - }; - } + if (names.Count == 0) + { + throw new ArgumentException("A pinned skills provider needs at least one skill name.", nameof(names)); + } - /// - /// Reads every pinned body once. Two first turns racing here both read the files and store - /// the same text, so there is no lock. - /// - private async ValueTask ReadAsync(InvokingContext context, CancellationToken cancellationToken) - { - var skills = await _catalog.Source - .GetSkillsAsync(new AgentSkillsSourceContext(context.Agent, context.Session), cancellationToken) - .ConfigureAwait(false); + _catalog = catalog; + _names = names; + } - var bodies = new List(_names.Count); - foreach (var name in _names) + /// + protected override async ValueTask ProvideAIContextAsync( + InvokingContext context, + CancellationToken cancellationToken = default) { - var skill = skills.FirstOrDefault(candidate => string.Equals(candidate.Frontmatter.Name, name, StringComparison.Ordinal)) - ?? throw new InvalidOperationException( - $"The pinned skill '{name}' is not in the bound skills folder. Validation should have refused it."); - - var content = await skill.GetContentAsync(cancellationToken).ConfigureAwait(false); - bodies.Add($"\n{StripManifests(StripFrontmatter(content)).Trim()}\n"); + return new AIContext + { + Instructions = _instructions ?? await ReadAsync(context, cancellationToken).ConfigureAwait(false), + }; } - _instructions = string.Join("\n\n", bodies); - return _instructions; - } - - /// - /// Drops the <available_resources> and <available_scripts> blocks MAF - /// appends to a file skill's content. They list what read_skill_resource can fetch, and a - /// pinned skill has no such tool, so the list would only tempt the model. - /// - private static string StripManifests(string content) - { - var start = content.LastIndexOf(ManifestStart, StringComparison.Ordinal); - return start < 0 ? content : content[..start]; - } - - /// - /// Drops the YAML frontmatter. Its name and description serve skill discovery, which a pinned - /// skill never goes through, so the model gets the body alone. - /// - private static string StripFrontmatter(string content) - { - if (!content.StartsWith(FrontmatterFence, StringComparison.Ordinal)) + /// + /// Reads every pinned body once. Two first turns racing here both read the files and store + /// the same text, so there is no lock. + /// + private async ValueTask ReadAsync(InvokingContext context, CancellationToken cancellationToken) { - return content; + IList skills = await _catalog.Source + .GetSkillsAsync(new AgentSkillsSourceContext(context.Agent, context.Session), cancellationToken) + .ConfigureAwait(false); + + List bodies = new(_names.Count); + foreach (string name in _names) + { + AgentSkill skill = skills.FirstOrDefault(candidate => string.Equals(candidate.Frontmatter.Name, name, StringComparison.Ordinal)) + ?? throw new InvalidOperationException( + $"The pinned skill '{name}' is not in the bound skills folder. Validation should have refused it."); + + string content = await skill.GetContentAsync(cancellationToken).ConfigureAwait(false); + bodies.Add($"\n{StripManifests(StripFrontmatter(content)).Trim()}\n"); + } + + _instructions = string.Join("\n\n", bodies); + return _instructions; } - var close = content.IndexOf("\n" + FrontmatterFence, FrontmatterFence.Length, StringComparison.Ordinal); - if (close < 0) + /// + /// Drops the <available_resources> and <available_scripts> blocks MAF + /// appends to a file skill's content. They list what read_skill_resource can fetch, and a + /// pinned skill has no such tool, so the list would only tempt the model. + /// + private static string StripManifests(string content) { - return content; + int start = content.LastIndexOf(ManifestStart, StringComparison.Ordinal); + return start < 0 ? content : content[..start]; } - var bodyStart = content.IndexOf('\n', close + 1); - return bodyStart < 0 ? string.Empty : content[(bodyStart + 1)..]; + /// + /// Drops the YAML frontmatter. Its name and description serve skill discovery, which a pinned + /// skill never goes through, so the model gets the body alone. + /// + private static string StripFrontmatter(string content) + { + if (!content.StartsWith(FrontmatterFence, StringComparison.Ordinal)) + { + return content; + } + + int close = content.IndexOf("\n" + FrontmatterFence, FrontmatterFence.Length, StringComparison.Ordinal); + if (close < 0) + { + return content; + } + + int bodyStart = content.IndexOf('\n', close + 1); + return bodyStart < 0 ? string.Empty : content[(bodyStart + 1)..]; + } } } diff --git a/src/AgentCore.Application/Skills/ReadOnlySkillsProvider.cs b/src/AgentCore.Application/Skills/ReadOnlySkillsProvider.cs index 23255277..c94d8320 100644 --- a/src/AgentCore.Application/Skills/ReadOnlySkillsProvider.cs +++ b/src/AgentCore.Application/Skills/ReadOnlySkillsProvider.cs @@ -1,42 +1,43 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Skills; - -/// -/// One agent's skills provider, with the script tool removed. -/// -internal sealed class ReadOnlySkillsProvider : AIContextProvider, IDisposable +namespace AgentCore.Application.Skills { - private readonly AgentSkillsProvider _inner; - - /// Creates the wrapper, taking ownership of the provider it wraps. - /// The provider whose tools are filtered. - /// is . - internal ReadOnlySkillsProvider(AgentSkillsProvider inner) + /// + /// One agent's skills provider, with the script tool removed. + /// + internal sealed class ReadOnlySkillsProvider : AIContextProvider, IDisposable { - ArgumentNullException.ThrowIfNull(inner); - _inner = inner; - } + private readonly AgentSkillsProvider _inner; - /// - protected override async ValueTask InvokingCoreAsync( - InvokingContext context, - CancellationToken cancellationToken = default) - { - var provided = await _inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); + /// Creates the wrapper, taking ownership of the provider it wraps. + /// The provider whose tools are filtered. + /// is . + internal ReadOnlySkillsProvider(AgentSkillsProvider inner) + { + ArgumentNullException.ThrowIfNull(inner); + _inner = inner; + } - // Null when the agent's filter matched no skill at all. - provided.Tools = provided.Tools? - .Where(tool => !string.Equals(tool.Name, AgentSkillsProvider.RunSkillScriptToolName, StringComparison.Ordinal)) - .ToList(); + /// + protected override async ValueTask InvokingCoreAsync( + InvokingContext context, + CancellationToken cancellationToken = default) + { + AIContext provided = await _inner.InvokingAsync(context, cancellationToken).ConfigureAwait(false); - return provided; - } + // Null when the agent's filter matched no skill at all. + provided.Tools = provided.Tools? + .Where(tool => !string.Equals(tool.Name, AgentSkillsProvider.RunSkillScriptToolName, StringComparison.Ordinal)) + .ToList(); - /// Disposes the provider this wrapper owns. - public void Dispose() - { - _inner.Dispose(); - GC.SuppressFinalize(this); + return provided; + } + + /// Disposes the provider this wrapper owns. + public void Dispose() + { + _inner.Dispose(); + GC.SuppressFinalize(this); + } } } diff --git a/src/AgentCore.Application/Skills/SkillCatalog.cs b/src/AgentCore.Application/Skills/SkillCatalog.cs index 2eb550d5..79f25a3f 100644 --- a/src/AgentCore.Application/Skills/SkillCatalog.cs +++ b/src/AgentCore.Application/Skills/SkillCatalog.cs @@ -1,28 +1,29 @@ using Microsoft.Agents.AI; -namespace AgentCore.Application.Skills; - -/// -/// The skills a host bound, and the names they serve. -/// -public sealed class SkillCatalog +namespace AgentCore.Application.Skills { - /// Creates the catalog. - /// The shared source every agent's filter wraps. - /// Every skill name the source serves. - /// An argument is . - public SkillCatalog(AgentSkillsSource source, IReadOnlySet names) + /// + /// The skills a host bound, and the names they serve. + /// + public sealed class SkillCatalog { - ArgumentNullException.ThrowIfNull(source); - ArgumentNullException.ThrowIfNull(names); + /// Creates the catalog. + /// The shared source every agent's filter wraps. + /// Every skill name the source serves. + /// An argument is . + public SkillCatalog(AgentSkillsSource source, IReadOnlySet names) + { + ArgumentNullException.ThrowIfNull(source); + ArgumentNullException.ThrowIfNull(names); - Source = source; - Names = names; - } + Source = source; + Names = names; + } - /// Gets the shared source. One per process, already cached. - public AgentSkillsSource Source { get; } + /// Gets the shared source. One per process, already cached. + public AgentSkillsSource Source { get; } - /// Gets every skill name the source serves. - public IReadOnlySet Names { get; } + /// Gets every skill name the source serves. + public IReadOnlySet Names { get; } + } } diff --git a/src/AgentCore.Application/Skills/SkillsProviderFactory.cs b/src/AgentCore.Application/Skills/SkillsProviderFactory.cs index 1343fa62..89535573 100644 --- a/src/AgentCore.Application/Skills/SkillsProviderFactory.cs +++ b/src/AgentCore.Application/Skills/SkillsProviderFactory.cs @@ -1,18 +1,18 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Skills; - -/// Builds the skills provider one agent binds. -internal static class SkillsProviderFactory +namespace AgentCore.Application.Skills { - /// - /// The stock MAF wording with the run_skill_script step removed and a closing sentence that - /// says why. The {skills} placeholder is required: the provider's constructor throws - /// without it, and MAF's own copy of that token is private, so nothing checks this string at - /// compile time. - /// - private const string InstructionPrompt = """ + /// Builds the skills provider one agent binds. + internal static class SkillsProviderFactory + { + /// + /// The stock MAF wording with the run_skill_script step removed and a closing sentence that + /// says why. The {skills} placeholder is required: the provider's constructor throws + /// without it, and MAF's own copy of that token is private, so nothing checks this string at + /// compile time. + /// + private const string InstructionPrompt = """ You have access to skills containing domain-specific knowledge and capabilities. Each skill provides specialized instructions, reference documents, and assets for specific tasks. @@ -29,41 +29,42 @@ You have access to skills containing domain-specific knowledge and capabilities. This host runs no skill scripts. Ignore any scripts a skill lists. """; - /// Builds the provider one agent binds. - /// The skills the host bound, shared by every agent. - /// The names this agent may load. - /// Where the provider writes its diagnostics, or . - /// The provider to hang on that agent. - /// A required argument is . - internal static AIContextProvider Create( - SkillCatalog catalog, - IReadOnlyList skills, - ILoggerFactory? loggers) - { - ArgumentNullException.ThrowIfNull(catalog); - ArgumentNullException.ThrowIfNull(skills); + /// Builds the provider one agent binds. + /// The skills the host bound, shared by every agent. + /// The names this agent may load. + /// Where the provider writes its diagnostics, or . + /// The provider to hang on that agent. + /// A required argument is . + internal static AIContextProvider Create( + SkillCatalog catalog, + IReadOnlyList skills, + ILoggerFactory? loggers) + { + ArgumentNullException.ThrowIfNull(catalog); + ArgumentNullException.ThrowIfNull(skills); - HashSet allowed = new(skills, StringComparer.Ordinal); + HashSet allowed = new(skills, StringComparer.Ordinal); - AgentSkillsProviderOptions options = new() - { - // Nothing answers an approval request mid-conversation, so an approval-gated tool would stall - // the turn. The script tool keeps its approval, and the wrapper removes it entirely. - DisableLoadSkillApproval = true, - DisableReadSkillResourceApproval = true, - SkillsInstructionPrompt = InstructionPrompt, - }; + AgentSkillsProviderOptions options = new() + { + // Nothing answers an approval request mid-conversation, so an approval-gated tool would stall + // the turn. The script tool keeps its approval, and the wrapper removes it entirely. + DisableLoadSkillApproval = true, + DisableReadSkillResourceApproval = true, + SkillsInstructionPrompt = InstructionPrompt, + }; - // The filter is never disposed on purpose: disposal cascades into the shared source, which - // every other agent is still reading. ownsSource: false stops the provider doing the same. - return new ReadOnlySkillsProvider( - new AgentSkillsProvider( - new FilteringAgentSkillsSource( - catalog.Source, - (skill, _) => allowed.Contains(skill.Frontmatter.Name), - loggers), - options, - loggers, - ownsSource: false)); + // The filter is never disposed on purpose: disposal cascades into the shared source, which + // every other agent is still reading. ownsSource: false stops the provider doing the same. + return new ReadOnlySkillsProvider( + new AgentSkillsProvider( + new FilteringAgentSkillsSource( + catalog.Source, + (skill, _) => allowed.Contains(skill.Frontmatter.Name), + loggers), + options, + loggers, + ownsSource: false)); + } } } diff --git a/src/AgentCore.Application/State/ConstStateWriter.cs b/src/AgentCore.Application/State/ConstStateWriter.cs index f081619d..8dabd926 100644 --- a/src/AgentCore.Application/State/ConstStateWriter.cs +++ b/src/AgentCore.Application/State/ConstStateWriter.cs @@ -1,37 +1,38 @@ using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.State; - -/// -/// Writer 4 of section 8.3. It fills a slot from a fixed value. -/// -/// -/// A constant never changes, so this writer runs once, when the conversation starts. -/// -public static class ConstStateWriter +namespace AgentCore.Application.State { - /// Fills every writer: const slot from its value:. - /// The state of one conversation. - /// The number of slots this writer filled. - public static int Apply(StateDocument state) + /// + /// Writer 4 of section 8.3. It fills a slot from a fixed value. + /// + /// + /// A constant never changes, so this writer runs once, when the conversation starts. + /// + public static class ConstStateWriter { - ArgumentNullException.ThrowIfNull(state); - - var filled = 0; - foreach (var (name, slot) in state.Configuration.State) + /// Fills every writer: const slot from its value:. + /// The state of one conversation. + /// The number of slots this writer filled. + public static int Apply(StateDocument state) { - if (slot.Writer != StateWriter.Const) - { - continue; - } + ArgumentNullException.ThrowIfNull(state); - // A value that does not coerce leaves the slot at its default. Section 8.3. - if (state.TryWrite(name, slot.Value?.DeepClone())) + int filled = 0; + foreach ((string? name, StateSlotConfiguration? slot) in state.Configuration.State) { - filled++; + if (slot.Writer != StateWriter.Const) + { + continue; + } + + // A value that does not coerce leaves the slot at its default. Section 8.3. + if (state.TryWrite(name, slot.Value?.DeepClone())) + { + filled++; + } } - } - return filled; + return filled; + } } } diff --git a/src/AgentCore.Application/State/CounterStateWriter.cs b/src/AgentCore.Application/State/CounterStateWriter.cs index ea2f5152..c673e4e9 100644 --- a/src/AgentCore.Application/State/CounterStateWriter.cs +++ b/src/AgentCore.Application/State/CounterStateWriter.cs @@ -2,58 +2,59 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; -namespace AgentCore.Application.State; - -/// -/// Writer 3 of section 8.3. It holds an integer that increments whenever its rule is true. -/// -/// -/// The rule is a JSONLogic rule over the same state the guards read, so it runs through -/// . Section 8.7: a rule that throws is not a defect, and the evaluator -/// logs it once and returns . -/// -public sealed class CounterStateWriter +namespace AgentCore.Application.State { - private readonly IGuardEvaluator _rules; - - /// Creates the counter writer. - /// The evaluator that runs an increment rule. - public CounterStateWriter(IGuardEvaluator rules) - { - ArgumentNullException.ThrowIfNull(rules); - _rules = rules; - } - - /// Increments every writer: counter slot whose rule is true. - /// The state of one conversation. - /// The number of slots this writer incremented. - public int Apply(StateDocument state) + /// + /// Writer 3 of section 8.3. It holds an integer that increments whenever its rule is true. + /// + /// + /// The rule is a JSONLogic rule over the same state the guards read, so it runs through + /// . Section 8.7: a rule that throws is not a defect, and the evaluator + /// logs it once and returns . + /// + public sealed class CounterStateWriter { - ArgumentNullException.ThrowIfNull(state); + private readonly IGuardEvaluator _rules; - // The rules read one snapshot, so every counter sees the same state. - var snapshot = state.Snapshot(); + /// Creates the counter writer. + /// The evaluator that runs an increment rule. + public CounterStateWriter(IGuardEvaluator rules) + { + ArgumentNullException.ThrowIfNull(rules); + _rules = rules; + } - var incremented = 0; - foreach (var (name, slot) in state.Configuration.State) + /// Increments every writer: counter slot whose rule is true. + /// The state of one conversation. + /// The number of slots this writer incremented. + public int Apply(StateDocument state) { - if (slot.Writer != StateWriter.Counter || slot.Increment is null) - { - continue; - } + ArgumentNullException.ThrowIfNull(state); - if (!_rules.Evaluate(slot.Increment, snapshot)) - { - continue; - } + // The rules read one snapshot, so every counter sees the same state. + IReadOnlyDictionary snapshot = state.Snapshot(); - var current = state.Read(name) is JsonValue value && value.TryGetValue(out long whole) ? whole : 0L; - if (state.TryWrite(name, JsonValue.Create(current + 1))) + int incremented = 0; + foreach ((string? name, StateSlotConfiguration? slot) in state.Configuration.State) { - incremented++; + if (slot.Writer != StateWriter.Counter || slot.Increment is null) + { + continue; + } + + if (!_rules.Evaluate(slot.Increment, snapshot)) + { + continue; + } + + long current = state.Read(name) is JsonValue value && value.TryGetValue(out long whole) ? whole : 0L; + if (state.TryWrite(name, JsonValue.Create(current + 1))) + { + incremented++; + } } - } - return incremented; + return incremented; + } } } diff --git a/src/AgentCore.Application/State/StateDocument.cs b/src/AgentCore.Application/State/StateDocument.cs index 28d25b93..309c011f 100644 --- a/src/AgentCore.Application/State/StateDocument.cs +++ b/src/AgentCore.Application/State/StateDocument.cs @@ -2,167 +2,171 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.State; - -/// -/// The declared state of one conversation, plus the three reserved slots. -/// -public sealed class StateDocument +namespace AgentCore.Application.State { - private readonly ConcurrentDictionary _written = new(StringComparer.Ordinal); - - /// Creates the state of one conversation from the declared slots. - /// The loaded document. - /// The stage the conversation starts in, or when there is no policy. - public StateDocument(AgentCoreConfiguration configuration, string? stage = null) + /// + /// The declared state of one conversation, plus the three reserved slots. + /// + public sealed class StateDocument { - ArgumentNullException.ThrowIfNull(configuration); + private readonly ConcurrentDictionary _written = new(StringComparer.Ordinal); - Configuration = configuration; - Stage = stage ?? string.Empty; - } - - /// Gets the document this state was declared by. - public AgentCoreConfiguration Configuration { get; } + /// Creates the state of one conversation from the declared slots. + /// The loaded document. + /// The stage the conversation starts in, or when there is no policy. + public StateDocument(AgentCoreConfiguration configuration, string? stage = null) + { + ArgumentNullException.ThrowIfNull(configuration); - /// Gets or sets the reserved stage slot. The policy runtime owns it. - public string Stage { get; set; } + Configuration = configuration; + Stage = stage ?? string.Empty; + } - /// Gets or sets the reserved turnIndex slot. The turn loop owns it. - public int TurnIndex { get; set; } + /// Gets the document this state was declared by. + public AgentCoreConfiguration Configuration { get; } - /// Gets or sets the reserved conversationDurationSeconds slot. The turn loop owns it. - public double ConversationDurationSeconds { get; set; } + /// Gets or sets the reserved stage slot. The policy runtime owns it. + public string Stage { get; set; } - /// Gets the names of the declared slots. The reserved slots are not declared. - public IEnumerable SlotNames => Configuration.State.Keys; + /// Gets or sets the reserved turnIndex slot. The turn loop owns it. + public int TurnIndex { get; set; } - /// Reports whether no writer has filled a slot yet. - /// The slot name. - /// when the slot is declared and still unfilled. - public bool IsUnfilled(string slot) - { - ArgumentNullException.ThrowIfNull(slot); - return Configuration.State.ContainsKey(slot) && !_written.ContainsKey(slot); - } + /// Gets or sets the reserved conversationDurationSeconds slot. The turn loop owns it. + public double ConversationDurationSeconds { get; set; } - /// Reads a slot. An unfilled slot reads as its declared default. - /// The slot name. A reserved name reads the reserved value. - /// The value, or when the slot is unknown or has no default. - public JsonNode? Read(string slot) - { - ArgumentNullException.ThrowIfNull(slot); + /// Gets the names of the declared slots. The reserved slots are not declared. + public IEnumerable SlotNames => Configuration.State.Keys; - if (ReservedStateSlots.Contains(slot)) + /// Reports whether no writer has filled a slot yet. + /// The slot name. + /// when the slot is declared and still unfilled. + public bool IsUnfilled(string slot) { - return ReadReserved(slot); + ArgumentNullException.ThrowIfNull(slot); + return Configuration.State.ContainsKey(slot) && !_written.ContainsKey(slot); } - if (_written.TryGetValue(slot, out var written)) + /// Reads a slot. An unfilled slot reads as its declared default. + /// The slot name. A reserved name reads the reserved value. + /// The value, or when the slot is unknown or has no default. + public JsonNode? Read(string slot) { - return written; - } + ArgumentNullException.ThrowIfNull(slot); - return Configuration.State.TryGetValue(slot, out var declared) - ? declared.Default?.DeepClone() - : null; - } + if (ReservedStateSlots.Contains(slot)) + { + return ReadReserved(slot); + } - /// Writes a slot after coercing the value to the declared type. - /// The declared slot name. - /// The raw value the writer produced. - /// - /// when the value coerced and the slot changed. - /// when coercion failed or the value is outside the slot's enum, which leaves the slot - /// as it was. - /// - /// The slot is reserved, and a reserved slot is read-only. - public bool TryWrite(string slot, JsonNode? value) - { - ArgumentNullException.ThrowIfNull(slot); + if (_written.TryGetValue(slot, out JsonNode? written)) + { + return written; + } - if (ReservedStateSlots.Contains(slot)) - { - throw new ArgumentException($"The slot '{slot}' is reserved and read-only.", nameof(slot)); + return Configuration.State.TryGetValue(slot, out StateSlotConfiguration? declared) + ? declared.Default?.DeepClone() + : null; } - if (!Configuration.State.TryGetValue(slot, out var declared)) + /// Writes a slot after coercing the value to the declared type. + /// The declared slot name. + /// The raw value the writer produced. + /// + /// when the value coerced and the slot changed. + /// when coercion failed or the value is outside the slot's enum, which leaves the slot + /// as it was. + /// + /// The slot is reserved, and a reserved slot is read-only. + public bool TryWrite(string slot, JsonNode? value) { - return false; + ArgumentNullException.ThrowIfNull(slot); + + if (ReservedStateSlots.Contains(slot)) + { + throw new ArgumentException($"The slot '{slot}' is reserved and read-only.", nameof(slot)); + } + + if (!Configuration.State.TryGetValue(slot, out StateSlotConfiguration? declared)) + { + return false; + } + + if (!StateValueCoercion.TryCoerce(value, declared.Type, out JsonNode? coerced)) + { + return false; + } + + // A slot that names its members has a closed domain, and the knowledge scope reads such a + // slot straight into a search filter. Refusing here is the only gate: the extractor's schema + // is a request to the model, and Restore writes a host-supplied blob through this same path. + if (declared.EnumValues is { Count: > 0 } members && !IsMember(members, coerced)) + { + return false; + } + + _written[slot] = coerced; + return true; } - if (!StateValueCoercion.TryCoerce(value, declared.Type, out var coerced)) + // ToJsonString rather than JsonNode.DeepEquals, so the comparison works on every target + // framework this package builds for. + private static bool IsMember(IReadOnlyList members, JsonNode? value) { - return false; - } + string? written = value?.ToJsonString(); - // A slot that names its members has a closed domain, and the knowledge scope reads such a - // slot straight into a search filter. Refusing here is the only gate: the extractor's schema - // is a request to the model, and Restore writes a host-supplied blob through this same path. - if (declared.EnumValues is { Count: > 0 } members && !IsMember(members, coerced)) - { - return false; + return members.Any(member => string.Equals(member.ToJsonString(), written, StringComparison.Ordinal)); } - _written[slot] = coerced; - return true; - } - - // ToJsonString rather than JsonNode.DeepEquals, so the comparison works on every target - // framework this package builds for. - private static bool IsMember(IReadOnlyList members, JsonNode? value) - { - var written = value?.ToJsonString(); + /// Takes a snapshot the guards read. It holds every declared slot and the three reserved slots. + /// The snapshot. It does not change when the document changes. + public IReadOnlyDictionary Snapshot() + { + Dictionary snapshot = new(StringComparer.Ordinal); - return members.Any(member => string.Equals(member.ToJsonString(), written, StringComparison.Ordinal)); - } + foreach (string slot in Configuration.State.Keys) + { + snapshot[slot] = Read(slot); + } - /// Takes a snapshot the guards read. It holds every declared slot and the three reserved slots. - /// The snapshot. It does not change when the document changes. - public IReadOnlyDictionary Snapshot() - { - Dictionary snapshot = new(StringComparer.Ordinal); + snapshot[ReservedStateSlots.Stage] = JsonValue.Create(Stage); + snapshot[ReservedStateSlots.TurnIndex] = JsonValue.Create(TurnIndex); + snapshot[ReservedStateSlots.ConversationDurationSeconds] = JsonValue.Create(ConversationDurationSeconds); + return snapshot; + } - foreach (var slot in Configuration.State.Keys) + /// Reads the declared slots a writer has actually filled, for the durable blob. + /// A copy. An unfilled slot is absent, which is what keeps unfilled and filled-default apart. + /// + /// Not : that one fills every declared slot with its default and adds the + /// three reserved slots, which is right for a guard and wrong for a blob. Restoring a default as + /// though a writer had chosen it would lose the difference + /// exists to keep. + /// + public IReadOnlyDictionary WrittenSlots() { - snapshot[slot] = Read(slot); - } + Dictionary written = new(_written.Count, StringComparer.Ordinal); - snapshot[ReservedStateSlots.Stage] = JsonValue.Create(Stage); - snapshot[ReservedStateSlots.TurnIndex] = JsonValue.Create(TurnIndex); - snapshot[ReservedStateSlots.ConversationDurationSeconds] = JsonValue.Create(ConversationDurationSeconds); - return snapshot; - } + foreach (KeyValuePair entry in _written) + { + written[entry.Key] = entry.Value?.DeepClone(); + } - /// Reads the declared slots a writer has actually filled, for the durable blob. - /// A copy. An unfilled slot is absent, which is what keeps unfilled and filled-default apart. - /// - /// Not : that one fills every declared slot with its default and adds the - /// three reserved slots, which is right for a guard and wrong for a blob. Restoring a default as - /// though a writer had chosen it would lose the difference - /// exists to keep. - /// - public IReadOnlyDictionary WrittenSlots() - { - Dictionary written = new(_written.Count, StringComparer.Ordinal); + return written; + } - foreach (var entry in _written) + private JsonValue? ReadReserved(string slot) { - written[entry.Key] = entry.Value?.DeepClone(); - } + if (string.Equals(slot, ReservedStateSlots.Stage, StringComparison.Ordinal)) + { + return JsonValue.Create(Stage); + } - return written; - } + if (string.Equals(slot, ReservedStateSlots.TurnIndex, StringComparison.Ordinal)) + { + return JsonValue.Create(TurnIndex); + } - private JsonValue? ReadReserved(string slot) - { - if (string.Equals(slot, ReservedStateSlots.Stage, StringComparison.Ordinal)) - { - return JsonValue.Create(Stage); + return JsonValue.Create(ConversationDurationSeconds); } - - return string.Equals(slot, ReservedStateSlots.TurnIndex, StringComparison.Ordinal) - ? JsonValue.Create(TurnIndex) - : JsonValue.Create(ConversationDurationSeconds); } } diff --git a/src/AgentCore.Application/State/StateExtractionResult.cs b/src/AgentCore.Application/State/StateExtractionResult.cs index 25db8c0c..d26b785d 100644 --- a/src/AgentCore.Application/State/StateExtractionResult.cs +++ b/src/AgentCore.Application/State/StateExtractionResult.cs @@ -1,26 +1,30 @@ -namespace AgentCore.Application.State; - -/// -/// What one extractor call did to the state. -/// -/// -/// Section 8.7: the extractor never drops a conversation. A reply that does not deserialize leaves every -/// slot unchanged, and the turn loop logs it once and continues. -/// -/// Whether the reply parsed into the object the schema describes. -/// The number of slots the reply filled. -/// The number of slots the reply answered with null. -/// The number of answers that did not coerce to the declared type. -/// The reason the reply did not parse, or . -public sealed record StateExtractionResult( - bool Deserialized, - int Filled, - int LeftNull, - int Rejected, - string? Failure) +namespace AgentCore.Application.State { - /// Gets the result of a conversation that produced nothing usable. - /// The reason. - /// A result that changed no slot. - public static StateExtractionResult Failed(string failure) => new(false, 0, 0, 0, failure); + /// + /// What one extractor call did to the state. + /// + /// + /// Section 8.7: the extractor never drops a conversation. A reply that does not deserialize leaves every + /// slot unchanged, and the turn loop logs it once and continues. + /// + /// Whether the reply parsed into the object the schema describes. + /// The number of slots the reply filled. + /// The number of slots the reply answered with null. + /// The number of answers that did not coerce to the declared type. + /// The reason the reply did not parse, or . + public sealed record StateExtractionResult( + bool Deserialized, + int Filled, + int LeftNull, + int Rejected, + string? Failure) + { + /// Gets the result of a conversation that produced nothing usable. + /// The reason. + /// A result that changed no slot. + public static StateExtractionResult Failed(string failure) + { + return new(false, 0, 0, 0, failure); + } + } } diff --git a/src/AgentCore.Application/State/StateExtractor.cs b/src/AgentCore.Application/State/StateExtractor.cs index 81530a66..93862b5d 100644 --- a/src/AgentCore.Application/State/StateExtractor.cs +++ b/src/AgentCore.Application/State/StateExtractor.cs @@ -4,289 +4,296 @@ using AgentCore.Application.Runtime; using Microsoft.Extensions.AI; -namespace AgentCore.Application.State; - -/// -/// Writer 1 of section 8.3, and the bridge from prose to typed state. -/// -/// -/// -/// AgentCore builds one JSON Schema from every writer: extractor slot, all nullable, and asks -/// a model to fill what the turn shows and leave the rest null. The extractor never speaks, holds no -/// tools, and decides nothing. The guards decide. -/// -/// -/// Every slot is nullable on the wire, and that is not optional. A required field that the model -/// omits becomes the default silently, so "unfilled" and "filled false" would be the same state. A -/// null answer means the model did not answer, and it leaves the slot at its previous value. -/// -/// -/// The extractor has no retry. One conversation runs, and a reply that does not deserialize leaves the slots -/// unchanged. The stage machine stays where it is and the agent tries again next turn. -/// -/// -public sealed class StateExtractor +namespace AgentCore.Application.State { - /// The name the emitted JSON Schema answers to. - public const string SchemaName = "agentcore_state"; - - private const string SystemPrompt = - "You read one finished turn of a phone conversation and report typed state. " - + "Answer with one JSON object that matches the schema. " - + "Set a field only when this turn shows the answer. " - + "Leave every other field null. Null means you did not answer, and it keeps the earlier value. " - + "Never guess, and never speak to the caller."; + /// + /// Writer 1 of section 8.3, and the bridge from prose to typed state. + /// + /// + /// + /// AgentCore builds one JSON Schema from every writer: extractor slot, all nullable, and asks + /// a model to fill what the turn shows and leave the rest null. The extractor never speaks, holds no + /// tools, and decides nothing. The guards decide. + /// + /// + /// Every slot is nullable on the wire, and that is not optional. A required field that the model + /// omits becomes the default silently, so "unfilled" and "filled false" would be the same state. A + /// null answer means the model did not answer, and it leaves the slot at its previous value. + /// + /// + /// The extractor has no retry. One conversation runs, and a reply that does not deserialize leaves the slots + /// unchanged. The stage machine stays where it is and the agent tries again next turn. + /// + /// + public sealed class StateExtractor + { + /// The name the emitted JSON Schema answers to. + public const string SchemaName = "agentcore_state"; - private readonly IChatClient _chatClient; + private const string SystemPrompt = + "You read one finished turn of a phone conversation and report typed state. " + + "Answer with one JSON object that matches the schema. " + + "Set a field only when this turn shows the answer. " + + "Leave every other field null. Null means you did not answer, and it keeps the earlier value. " + + "Never guess, and never speak to the caller."; - private readonly ChatOptions _options; + private readonly IChatClient _chatClient; - /// Creates the extractor for one loaded document. - /// The loaded document. - /// The model named by extractor.model. - /// The document declares no extractor: section. - public StateExtractor(AgentCoreConfiguration configuration, IChatClient chatClient) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(chatClient); + private readonly ChatOptions _options; - if (configuration.Extractor is null) + /// Creates the extractor for one loaded document. + /// The loaded document. + /// The model named by extractor.model. + /// The document declares no extractor: section. + public StateExtractor(AgentCoreConfiguration configuration, IChatClient chatClient) { - throw new InvalidOperationException( - "The document declares no extractor, so no extractor slot can be filled."); - } + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(chatClient); - Configuration = configuration; + if (configuration.Extractor is null) + { + throw new InvalidOperationException( + "The document declares no extractor, so no extractor slot can be filled."); + } - _chatClient = chatClient; + Configuration = configuration; - SlotNames = [.. configuration.State - .Where(entry => entry.Value.Writer == StateWriter.Extractor) - .Select(entry => entry.Key)]; + _chatClient = chatClient; - Schema = BuildSchema(configuration); - - _options = new ChatOptions - { - ResponseFormat = ChatResponseFormat.ForJsonSchema( - Schema, - SchemaName, - "The state slots this turn may fill. A null field means the turn did not show the answer."), - Temperature = (float?)configuration.Extractor.Model.Temperature, - }; - } + SlotNames = [.. configuration.State + .Where(entry => entry.Value.Writer == StateWriter.Extractor) + .Select(entry => entry.Key)]; - /// Gets the loaded document. - public AgentCoreConfiguration Configuration { get; } + Schema = BuildSchema(configuration); - /// Gets the names of the writer: extractor slots, in document order. - public IReadOnlyList SlotNames { get; } + _options = new ChatOptions + { + ResponseFormat = ChatResponseFormat.ForJsonSchema( + Schema, + SchemaName, + "The state slots this turn may fill. A null field means the turn did not show the answer."), + Temperature = (float?)configuration.Extractor.Model.Temperature, + }; + } - /// Gets the one JSON Schema the extractor sends. Every property is nullable. - public JsonElement Schema { get; } + /// Gets the loaded document. + public AgentCoreConfiguration Configuration { get; } - /// Builds the JSON Schema from every writer: extractor slot. - /// The loaded document. - /// The schema. Every property is nullable, and every property is required. - public static JsonElement BuildSchema(AgentCoreConfiguration configuration) - { - ArgumentNullException.ThrowIfNull(configuration); + /// Gets the names of the writer: extractor slots, in document order. + public IReadOnlyList SlotNames { get; } - JsonObject properties = []; - JsonArray required = []; + /// Gets the one JSON Schema the extractor sends. Every property is nullable. + public JsonElement Schema { get; } - foreach (var (name, slot) in configuration.State) + /// Builds the JSON Schema from every writer: extractor slot. + /// The loaded document. + /// The schema. Every property is nullable, and every property is required. + public static JsonElement BuildSchema(AgentCoreConfiguration configuration) { - if (slot.Writer != StateWriter.Extractor) - { - continue; - } + ArgumentNullException.ThrowIfNull(configuration); - JsonObject property = new() - { - // The null member is the point of this schema. See section 8.3. - ["type"] = new JsonArray(JsonValue.Create(TypeName(slot.Type)), JsonValue.Create("null")), - }; + JsonObject properties = []; + JsonArray required = []; - if (slot.Description is not null) + foreach ((string? name, StateSlotConfiguration? slot) in configuration.State) { - property["description"] = JsonValue.Create(slot.Description); - } - - if (slot.EnumValues is { Count: > 0 }) - { - JsonArray members = []; - foreach (var member in slot.EnumValues) + if (slot.Writer != StateWriter.Extractor) { - members.Add(member.DeepClone()); + continue; } - members.Add(null); - property["enum"] = members; - } - - properties[name] = property; - required.Add(JsonValue.Create(name)); - } + JsonObject property = new() + { + // The null member is the point of this schema. See section 8.3. + ["type"] = new JsonArray(JsonValue.Create(TypeName(slot.Type)), JsonValue.Create("null")), + }; - JsonObject schema = new() - { - ["type"] = "object", - ["properties"] = properties, - ["required"] = required, - ["additionalProperties"] = false, - }; - - using var document = JsonDocument.Parse(schema.ToJsonString()); - return document.RootElement.Clone(); - } + if (slot.Description is not null) + { + property["description"] = JsonValue.Create(slot.Description); + } - /// - /// Runs one extractor call against the finished turn, then writes what it answered. - /// - /// The state of one conversation. - /// The finished turn, newest last. - /// Cancels the model call. - /// What the conversation did to the state. - public Task ExtractAsync( - StateDocument state, - IEnumerable transcript, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(state); - ArgumentNullException.ThrowIfNull(transcript); + if (slot.EnumValues is { Count: > 0 }) + { + JsonArray members = []; + foreach (JsonNode member in slot.EnumValues) + { + members.Add(member.DeepClone()); + } + + members.Add(null); + property["enum"] = members; + } - return ExtractAsync(state, transcript, new Clarifications(), cancellationToken); - } + properties[name] = property; + required.Add(JsonValue.Create(name)); + } - /// Runs one extractor call against the finished turn, then writes what it answered. - /// The state of one conversation. - /// The finished turn, newest last. - /// The conversation's ambiguity holder. reads and writes it. - /// Cancels the model call. - /// What the conversation did to the state. - internal async Task ExtractAsync( - StateDocument state, - IEnumerable transcript, - Clarifications clarifications, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(state); - ArgumentNullException.ThrowIfNull(transcript); - ArgumentNullException.ThrowIfNull(clarifications); + JsonObject schema = new() + { + ["type"] = "object", + ["properties"] = properties, + ["required"] = required, + ["additionalProperties"] = false, + }; - if (SlotNames.Count == 0) - { - return new StateExtractionResult(true, 0, 0, 0, null); + using JsonDocument document = JsonDocument.Parse(schema.ToJsonString()); + return document.RootElement.Clone(); } - List messages = [new ChatMessage(ChatRole.System, SystemPrompt), .. transcript]; - - ChatResponse response; - try - { - response = await _chatClient.GetResponseAsync(messages, _options, cancellationToken).ConfigureAwait(false); - } - catch (Exception exception) when (exception is not OperationCanceledException) + /// + /// Runs one extractor call against the finished turn, then writes what it answered. + /// + /// The state of one conversation. + /// The finished turn, newest last. + /// Cancels the model call. + /// What the conversation did to the state. + public Task ExtractAsync( + StateDocument state, + IEnumerable transcript, + CancellationToken cancellationToken = default) { - // State extraction must never drop a conversation. Section 8.7. - return StateExtractionResult.Failed($"the extractor call failed: {exception.Message}"); + ArgumentNullException.ThrowIfNull(state); + ArgumentNullException.ThrowIfNull(transcript); + + return ExtractAsync(state, transcript, new Clarifications(), cancellationToken); } - return Write(state, response.Text, clarifications); - } + /// Runs one extractor call against the finished turn, then writes what it answered. + /// The state of one conversation. + /// The finished turn, newest last. + /// The conversation's ambiguity holder. reads and writes it. + /// Cancels the model call. + /// What the conversation did to the state. + internal async Task ExtractAsync( + StateDocument state, + IEnumerable transcript, + Clarifications clarifications, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(state); + ArgumentNullException.ThrowIfNull(transcript); + ArgumentNullException.ThrowIfNull(clarifications); - /// Writes one extractor reply into the state. - /// The state of one conversation. - /// The raw JSON the model returned. - /// What the reply did to the state. - public StateExtractionResult Write(StateDocument state, string? replyText) - { - ArgumentNullException.ThrowIfNull(state); + if (SlotNames.Count == 0) + { + return new StateExtractionResult(true, 0, 0, 0, null); + } - return Write(state, replyText, new Clarifications()); - } + List messages = [new ChatMessage(ChatRole.System, SystemPrompt), .. transcript]; - /// Writes one extractor reply into the state. - /// The state of one conversation. - /// The raw JSON the model returned. - /// - /// The conversation's ambiguity holder (K36). A write that lands clears the slot's lastNamed - /// record (K30); a refused write leaves it alone. - /// - /// What the reply did to the state. - internal StateExtractionResult Write( - StateDocument state, - string? replyText, - Clarifications clarifications) - { - ArgumentNullException.ThrowIfNull(state); - ArgumentNullException.ThrowIfNull(clarifications); + ChatResponse response; + try + { + response = await _chatClient.GetResponseAsync(messages, _options, cancellationToken).ConfigureAwait(false); + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + // State extraction must never drop a conversation. Section 8.7. + return StateExtractionResult.Failed($"the extractor call failed: {exception.Message}"); + } - if (string.IsNullOrWhiteSpace(replyText)) - { - return StateExtractionResult.Failed("the extractor returned an empty reply"); + return Write(state, response.Text, clarifications); } - JsonNode? parsed; - try + /// Writes one extractor reply into the state. + /// The state of one conversation. + /// The raw JSON the model returned. + /// What the reply did to the state. + public StateExtractionResult Write(StateDocument state, string? replyText) { - parsed = JsonNode.Parse(replyText); - } - catch (JsonException exception) - { - return StateExtractionResult.Failed($"the extractor reply is not well-formed JSON: {exception.Message}"); - } + ArgumentNullException.ThrowIfNull(state); - if (parsed is not JsonObject answer) - { - return StateExtractionResult.Failed("the extractor reply is not a JSON object"); + return Write(state, replyText, new Clarifications()); } - int filled = 0, left = 0, rejected = 0; - foreach (var name in SlotNames) + /// Writes one extractor reply into the state. + /// The state of one conversation. + /// The raw JSON the model returned. + /// + /// The conversation's ambiguity holder (K36). A write that lands clears the slot's lastNamed + /// record (K30); a refused write leaves it alone. + /// + /// What the reply did to the state. + internal StateExtractionResult Write( + StateDocument state, + string? replyText, + Clarifications clarifications) { - if (!answer.TryGetPropertyValue(name, out var value) || value is null) + ArgumentNullException.ThrowIfNull(state); + ArgumentNullException.ThrowIfNull(clarifications); + + if (string.IsNullOrWhiteSpace(replyText)) { - // The model did not answer. The slot keeps its earlier value. - left++; - continue; + return StateExtractionResult.Failed("the extractor returned an empty reply"); } - if (WriteSlot(state, name, value, clarifications)) + JsonNode? parsed; + try { - filled++; + parsed = JsonNode.Parse(replyText); } - else + catch (JsonException exception) + { + return StateExtractionResult.Failed($"the extractor reply is not well-formed JSON: {exception.Message}"); + } + + if (parsed is not JsonObject answer) + { + return StateExtractionResult.Failed("the extractor reply is not a JSON object"); + } + + int filled = 0, left = 0, rejected = 0; + foreach (string name in SlotNames) { - rejected++; + if (!answer.TryGetPropertyValue(name, out JsonNode? value) || value is null) + { + // The model did not answer. The slot keeps its earlier value. + left++; + continue; + } + + if (WriteSlot(state, name, value, clarifications)) + { + filled++; + } + else + { + rejected++; + } } + + return new StateExtractionResult(true, filled, left, rejected, null); } - return new StateExtractionResult(true, filled, left, rejected, null); - } + /// Coerces and gates one answer through . + private static bool WriteSlot(StateDocument state, string slot, JsonNode value, Clarifications clarifications) + { + if (!state.TryWrite(slot, value.DeepClone())) + { + return false; + } - /// Coerces and gates one answer through . - private static bool WriteSlot(StateDocument state, string slot, JsonNode value, Clarifications clarifications) - { - if (!state.TryWrite(slot, value.DeepClone())) + ClearAmbiguity(clarifications, slot); + return true; + } + + /// K30: a successful write clears the slot's lastNamed record. + private static void ClearAmbiguity(Clarifications clarifications, string slot) { - return false; + clarifications.Update(slot, s => s.LastNamed = Clarifications.LastNamed.None); } - ClearAmbiguity(clarifications, slot); - return true; + private static string TypeName(StateSlotType slotType) + { + return slotType switch + { + StateSlotType.Boolean => "boolean", + StateSlotType.Integer => "integer", + StateSlotType.Number => "number", + StateSlotType.String => "string", + _ => throw new ArgumentOutOfRangeException(nameof(slotType), slotType, "The slot type vocabulary is closed, and this value is not in it."), + }; + } } - - /// K30: a successful write clears the slot's lastNamed record. - private static void ClearAmbiguity(Clarifications clarifications, string slot) - => clarifications.Update(slot, s => s.LastNamed = Clarifications.LastNamed.None); - - private static string TypeName(StateSlotType slotType) => slotType switch - { - StateSlotType.Boolean => "boolean", - StateSlotType.Integer => "integer", - StateSlotType.Number => "number", - _ => "string", - }; } diff --git a/src/AgentCore.Application/State/StateValueCoercion.cs b/src/AgentCore.Application/State/StateValueCoercion.cs index bf27c1af..acb148f2 100644 --- a/src/AgentCore.Application/State/StateValueCoercion.cs +++ b/src/AgentCore.Application/State/StateValueCoercion.cs @@ -2,141 +2,142 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.State; - -/// -/// Coerces a written value to the declared type of a state slot. -/// -/// -/// Section 8.3: a writer: tool path reads an untyped tool result, so the declared type of the -/// slot is authoritative. AgentCore coerces the value to that type, and leaves the slot at its -/// default when coercion fails. -/// -public static class StateValueCoercion +namespace AgentCore.Application.State { - /// Coerces one value to the declared type of a slot. - /// The raw value a writer produced. never coerces. - /// The declared type of the slot. - /// The coerced value, when the coercion succeeds. - /// when the value coerces to the declared type. - public static bool TryCoerce(JsonNode? value, StateSlotType slotType, out JsonNode? coerced) + /// + /// Coerces a written value to the declared type of a state slot. + /// + /// + /// Section 8.3: a writer: tool path reads an untyped tool result, so the declared type of the + /// slot is authoritative. AgentCore coerces the value to that type, and leaves the slot at its + /// default when coercion fails. + /// + public static class StateValueCoercion { - coerced = null; - - if (value is not JsonValue scalar) - { - // An array or an object is never a scalar slot value, and neither is null. - return false; - } - - return slotType switch - { - StateSlotType.Boolean => TryCoerceBoolean(scalar, out coerced), - StateSlotType.Integer => TryCoerceInteger(scalar, out coerced), - StateSlotType.Number => TryCoerceNumber(scalar, out coerced), - StateSlotType.String => TryCoerceText(scalar, out coerced), - _ => false, - }; - } - - private static bool TryCoerceBoolean(JsonValue scalar, out JsonNode? coerced) - { - coerced = null; - - if (scalar.TryGetValue(out bool flag)) + /// Coerces one value to the declared type of a slot. + /// The raw value a writer produced. never coerces. + /// The declared type of the slot. + /// The coerced value, when the coercion succeeds. + /// when the value coerces to the declared type. + public static bool TryCoerce(JsonNode? value, StateSlotType slotType, out JsonNode? coerced) { - coerced = JsonValue.Create(flag); - return true; + coerced = null; + + if (value is not JsonValue scalar) + { + // An array or an object is never a scalar slot value, and neither is null. + return false; + } + + return slotType switch + { + StateSlotType.Boolean => TryCoerceBoolean(scalar, out coerced), + StateSlotType.Integer => TryCoerceInteger(scalar, out coerced), + StateSlotType.Number => TryCoerceNumber(scalar, out coerced), + StateSlotType.String => TryCoerceText(scalar, out coerced), + _ => false, + }; } - if (scalar.TryGetValue(out string? text) && bool.TryParse(text, out var parsed)) + private static bool TryCoerceBoolean(JsonValue scalar, out JsonNode? coerced) { - coerced = JsonValue.Create(parsed); - return true; - } + coerced = null; - return false; - } + if (scalar.TryGetValue(out bool flag)) + { + coerced = JsonValue.Create(flag); + return true; + } - private static bool TryCoerceInteger(JsonValue scalar, out JsonNode? coerced) - { - coerced = null; + if (scalar.TryGetValue(out string? text) && bool.TryParse(text, out bool parsed)) + { + coerced = JsonValue.Create(parsed); + return true; + } - if (scalar.TryGetValue(out bool _)) - { - // A boolean is not a number. Section 8.4 rejects the same confusion in a guard. return false; } - if (scalar.TryGetValue(out long whole)) - { - coerced = JsonValue.Create(whole); - return true; - } - - if (scalar.TryGetValue(out double real) && double.IsInteger(real)) - { - coerced = JsonValue.Create((long)real); - return true; - } - - if (scalar.TryGetValue(out string? text) - && long.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out var parsed)) + private static bool TryCoerceInteger(JsonValue scalar, out JsonNode? coerced) { - coerced = JsonValue.Create(parsed); - return true; - } - - return false; - } - - private static bool TryCoerceNumber(JsonValue scalar, out JsonNode? coerced) - { - coerced = null; + coerced = null; + + if (scalar.TryGetValue(out bool _)) + { + // A boolean is not a number. Section 8.4 rejects the same confusion in a guard. + return false; + } + + if (scalar.TryGetValue(out long whole)) + { + coerced = JsonValue.Create(whole); + return true; + } + + if (scalar.TryGetValue(out double real) && double.IsInteger(real)) + { + coerced = JsonValue.Create((long)real); + return true; + } + + if (scalar.TryGetValue(out string? text) + && long.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out long parsed)) + { + coerced = JsonValue.Create(parsed); + return true; + } - if (scalar.TryGetValue(out bool _)) - { return false; } - if (scalar.TryGetValue(out double real)) + private static bool TryCoerceNumber(JsonValue scalar, out JsonNode? coerced) { - coerced = JsonValue.Create(real); - return true; - } - - if (scalar.TryGetValue(out string? text) - && double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out var parsed)) - { - coerced = JsonValue.Create(parsed); - return true; - } + coerced = null; + + if (scalar.TryGetValue(out bool _)) + { + return false; + } + + if (scalar.TryGetValue(out double real)) + { + coerced = JsonValue.Create(real); + return true; + } + + if (scalar.TryGetValue(out string? text) + && double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out double parsed)) + { + coerced = JsonValue.Create(parsed); + return true; + } - return false; - } - - private static bool TryCoerceText(JsonValue scalar, out JsonNode? coerced) - { - coerced = null; - - if (scalar.TryGetValue(out string? text)) - { - coerced = JsonValue.Create(text); - return true; + return false; } - if (scalar.TryGetValue(out bool flag)) + private static bool TryCoerceText(JsonValue scalar, out JsonNode? coerced) { - coerced = JsonValue.Create(flag ? "true" : "false"); - return true; - } + coerced = null; + + if (scalar.TryGetValue(out string? text)) + { + coerced = JsonValue.Create(text); + return true; + } + + if (scalar.TryGetValue(out bool flag)) + { + coerced = JsonValue.Create(flag ? "true" : "false"); + return true; + } + + if (scalar.TryGetValue(out double real)) + { + coerced = JsonValue.Create(real.ToString(CultureInfo.InvariantCulture)); + return true; + } - if (scalar.TryGetValue(out double real)) - { - coerced = JsonValue.Create(real.ToString(CultureInfo.InvariantCulture)); - return true; + return false; } - - return false; } } diff --git a/src/AgentCore.Application/State/ToolResultPath.cs b/src/AgentCore.Application/State/ToolResultPath.cs index c8325ccd..73b3dc02 100644 --- a/src/AgentCore.Application/State/ToolResultPath.cs +++ b/src/AgentCore.Application/State/ToolResultPath.cs @@ -1,76 +1,77 @@ using System.Text.Json.Nodes; using Json.Pointer; -namespace AgentCore.Application.State; - -/// -/// Reads one value out of an untyped tool result. -/// -/// -/// Section 8.3: a writer: tool path is a JSON Pointer into a tool result, and a tool result -/// has no declared shape. The document writes the path in the compact lookup_order.status -/// form, so both the dotted form and the RFC 6901 pointer form resolve here. The dotted form is -/// normalised to a pointer - escaping ~ and / per RFC 6901 §3 - and then evaluated by -/// , so a segment that happens to contain either character still resolves -/// to the literal property name it named under the hand-rolled resolver this replaced. -/// -internal static class ToolResultPath +namespace AgentCore.Application.State { - /// Resolves a path against a tool result. - /// The tool result, as a node tree. - /// The dotted path, or the RFC 6901 pointer. - /// The node the path names, or when the path reaches nothing. - public static JsonNode? Resolve(JsonNode? result, string path) + /// + /// Reads one value out of an untyped tool result. + /// + /// + /// Section 8.3: a writer: tool path is a JSON Pointer into a tool result, and a tool result + /// has no declared shape. The document writes the path in the compact lookup_order.status + /// form, so both the dotted form and the RFC 6901 pointer form resolve here. The dotted form is + /// normalised to a pointer - escaping ~ and / per RFC 6901 §3 - and then evaluated by + /// , so a segment that happens to contain either character still resolves + /// to the literal property name it named under the hand-rolled resolver this replaced. + /// + internal static class ToolResultPath { - ArgumentNullException.ThrowIfNull(path); - - if (result is null) + /// Resolves a path against a tool result. + /// The tool result, as a node tree. + /// The dotted path, or the RFC 6901 pointer. + /// The node the path names, or when the path reaches nothing. + public static JsonNode? Resolve(JsonNode? result, string path) { - return null; - } + ArgumentNullException.ThrowIfNull(path); - var pointerText = path.Length == 0 || path[0] == '/' ? path : ToPointer(path); + if (result is null) + { + return null; + } - if (!JsonPointer.TryParse(pointerText, out var pointer)) - { - return null; - } + string pointerText = path.Length == 0 || path[0] == '/' ? path : ToPointer(path); - // RFC 6901 §4 defines the segment '-' as "the (nonexistent) member after the last array - // element", and Json.Pointer.JsonPointer.TryEvaluate implements that by resolving it to the - // *existing* last element. This repo does not adopt that reading: the hand-rolled resolver - // this replaced gave '-' no meaning at all (an array index had to parse as a non-negative - // integer, and '-' never does), so a path ending in '-' always reached nothing. That is kept - // deliberately, not by oversight - a state slot must be written because a document's path - // named a value, never as a side effect of which JSON Pointer library happens to evaluate - // the path. So a '-' segment is rejected before it ever reaches the array it would otherwise - // resolve against. - for (var i = 0; i < pointer.SegmentCount; i++) - { - if (pointer[i].Equals("-")) + if (!JsonPointer.TryParse(pointerText, out JsonPointer pointer)) { return null; } - } - return pointer.TryEvaluate(result, out var value) ? value : null; - } + // RFC 6901 §4 defines the segment '-' as "the (nonexistent) member after the last array + // element", and Json.Pointer.JsonPointer.TryEvaluate implements that by resolving it to the + // *existing* last element. This repo does not adopt that reading: the hand-rolled resolver + // this replaced gave '-' no meaning at all (an array index had to parse as a non-negative + // integer, and '-' never does), so a path ending in '-' always reached nothing. That is kept + // deliberately, not by oversight - a state slot must be written because a document's path + // named a value, never as a side effect of which JSON Pointer library happens to evaluate + // the path. So a '-' segment is rejected before it ever reaches the array it would otherwise + // resolve against. + for (int i = 0; i < pointer.SegmentCount; i++) + { + if (pointer[i].Equals("-")) + { + return null; + } + } - /// Normalises the dotted compact form into an RFC 6901 pointer. - /// A path with no leading slash, one segment for each dot-separated part. - /// The equivalent pointer, each segment escaped per RFC 6901 §3. - private static string ToPointer(string path) - { - var segments = path.Split('.'); - for (var i = 0; i < segments.Length; i++) - { - // Escape '~' first, so a literal '~' in the dotted segment does not collide with the - // '~0'/'~1' escape sequences the '/' replacement below introduces. - segments[i] = segments[i] - .Replace("~", "~0", StringComparison.Ordinal) - .Replace("/", "~1", StringComparison.Ordinal); + return pointer.TryEvaluate(result, out JsonNode? value) ? value : null; } - return "/" + string.Join('/', segments); + /// Normalises the dotted compact form into an RFC 6901 pointer. + /// A path with no leading slash, one segment for each dot-separated part. + /// The equivalent pointer, each segment escaped per RFC 6901 §3. + private static string ToPointer(string path) + { + string[] segments = path.Split('.'); + for (int i = 0; i < segments.Length; i++) + { + // Escape '~' first, so a literal '~' in the dotted segment does not collide with the + // '~0'/'~1' escape sequences the '/' replacement below introduces. + segments[i] = segments[i] + .Replace("~", "~0", StringComparison.Ordinal) + .Replace("/", "~1", StringComparison.Ordinal); + } + + return "/" + string.Join('/', segments); + } } } diff --git a/src/AgentCore.Application/State/ToolStateWriter.cs b/src/AgentCore.Application/State/ToolStateWriter.cs index 4f11c86b..c921c190 100644 --- a/src/AgentCore.Application/State/ToolStateWriter.cs +++ b/src/AgentCore.Application/State/ToolStateWriter.cs @@ -1,45 +1,46 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.State; - -/// -/// Writer 2 of section 8.3. It fills a slot from a named field of a named tool result. -/// -/// -/// A tool result has no declared shape, so check 2 verifies only that the tool id exists and check 4 -/// cannot type the slot from the path. The declared type of the slot wins: this writer coerces the -/// value, and leaves the slot at its default when coercion fails. -/// -public static class ToolStateWriter +namespace AgentCore.Application.State { - /// Fills every slot that reads the result of one tool. - /// The state of one conversation. - /// The id of the tool that just returned. - /// The tool result, as a node tree. - /// The number of slots this writer filled. - public static int Apply(StateDocument state, string toolId, JsonNode? result) + /// + /// Writer 2 of section 8.3. It fills a slot from a named field of a named tool result. + /// + /// + /// A tool result has no declared shape, so check 2 verifies only that the tool id exists and check 4 + /// cannot type the slot from the path. The declared type of the slot wins: this writer coerces the + /// value, and leaves the slot at its default when coercion fails. + /// + public static class ToolStateWriter { - ArgumentNullException.ThrowIfNull(state); - ArgumentException.ThrowIfNullOrEmpty(toolId); - - var filled = 0; - foreach (var (name, slot) in state.Configuration.State) + /// Fills every slot that reads the result of one tool. + /// The state of one conversation. + /// The id of the tool that just returned. + /// The tool result, as a node tree. + /// The number of slots this writer filled. + public static int Apply(StateDocument state, string toolId, JsonNode? result) { - if (slot.Writer != StateWriter.Tool - || slot.From is null - || !string.Equals(slot.From.ToolId, toolId, StringComparison.Ordinal)) - { - continue; - } + ArgumentNullException.ThrowIfNull(state); + ArgumentException.ThrowIfNullOrEmpty(toolId); - var value = ToolResultPath.Resolve(result, slot.From.Path); - if (state.TryWrite(name, value)) + int filled = 0; + foreach ((string? name, StateSlotConfiguration? slot) in state.Configuration.State) { - filled++; + if (slot.Writer != StateWriter.Tool + || slot.From is null + || !string.Equals(slot.From.ToolId, toolId, StringComparison.Ordinal)) + { + continue; + } + + JsonNode? value = ToolResultPath.Resolve(result, slot.From.Path); + if (state.TryWrite(name, value)) + { + filled++; + } } - } - return filled; + return filled; + } } } diff --git a/src/AgentCore.Application/State/UnfilledSlotReminder.cs b/src/AgentCore.Application/State/UnfilledSlotReminder.cs index 094421ba..1815a04f 100644 --- a/src/AgentCore.Application/State/UnfilledSlotReminder.cs +++ b/src/AgentCore.Application/State/UnfilledSlotReminder.cs @@ -1,131 +1,136 @@ using System.Text; +using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; -namespace AgentCore.Application.State; - -/// -/// The reminder that an unfilled slot puts in front of the reply agent's input. -/// -public static class UnfilledSlotReminder +namespace AgentCore.Application.State { - /// The tag that opens the reminder. - public const string OpenTag = ""; - - /// The tag that closes the reminder. - public const string CloseTag = ""; - - private const string Lead = "You still need this from the caller before you can continue: "; - - private const string Tail = "Ask for it in your next reply."; - /// - /// Lists the slots the current stage waits on and that still read as null. + /// The reminder that an unfilled slot puts in front of the reply agent's input. /// - /// The state of one conversation. - /// The stage the machine holds. - /// The unfilled slot names, in document order. - public static IReadOnlyList UnfilledSlots(StateDocument state, StageConfiguration stage) + public static class UnfilledSlotReminder { - ArgumentNullException.ThrowIfNull(state); - ArgumentNullException.ThrowIfNull(stage); + /// The tag that opens the reminder. + public const string OpenTag = ""; + + /// The tag that closes the reminder. + public const string CloseTag = ""; - HashSet read = new(StringComparer.Ordinal); - CollectStageExits(state.Configuration, stage, read); + private const string Lead = "You still need this from the caller before you can continue: "; - List unfilled = []; - foreach (var (name, slot) in state.Configuration.State) + private const string Tail = "Ask for it in your next reply."; + + /// + /// Lists the slots the current stage waits on and that still read as null. + /// + /// The state of one conversation. + /// The stage the machine holds. + /// The unfilled slot names, in document order. + public static IReadOnlyList UnfilledSlots(StateDocument state, StageConfiguration stage) { - // Only an extractor slot waits on the caller. Every other writer fills itself. - if (slot.Writer == StateWriter.Extractor && read.Contains(name) && state.Read(name) is null) + ArgumentNullException.ThrowIfNull(state); + ArgumentNullException.ThrowIfNull(stage); + + HashSet read = new(StringComparer.Ordinal); + CollectStageExits(state.Configuration, stage, read); + + List unfilled = []; + foreach ((string? name, StateSlotConfiguration? slot) in state.Configuration.State) { - unfilled.Add(name); + // Only an extractor slot waits on the caller. Every other writer fills itself. + if (slot.Writer == StateWriter.Extractor && read.Contains(name) && state.Read(name) is null) + { + unfilled.Add(name); + } } + + return unfilled; } - return unfilled; - } + /// Builds the reminder for a set of unfilled slots. + /// The loaded document, which holds each slot description. + /// The unfilled slot names. + /// The reminder text, or when no slot is unfilled. + public static string? Build(AgentCoreConfiguration configuration, IReadOnlyList slots) + { + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(slots); - /// Builds the reminder for a set of unfilled slots. - /// The loaded document, which holds each slot description. - /// The unfilled slot names. - /// The reminder text, or when no slot is unfilled. - public static string? Build(AgentCoreConfiguration configuration, IReadOnlyList slots) - { - ArgumentNullException.ThrowIfNull(configuration); - ArgumentNullException.ThrowIfNull(slots); + if (slots.Count == 0) + { + return null; + } - if (slots.Count == 0) - { - return null; + List wanted = []; + foreach (string slot in slots) + { + wanted.Add(configuration.State.TryGetValue(slot, out StateSlotConfiguration? declared) && declared.Description is { Length: > 0 } text + ? text + : slot); + } + + StringBuilder builder = new(); + _ = builder.Append(OpenTag).Append('\n'); + _ = builder.Append(Lead).Append(Join(wanted)).Append(".\n"); + _ = builder.Append(Tail).Append('\n'); + _ = builder.Append(CloseTag); + return builder.ToString(); } - List wanted = []; - foreach (var slot in slots) + /// Builds the reminder for the stage the machine holds. + /// The state of one conversation. + /// The stage the machine holds. + /// The reminder text, or when no slot is unfilled. + public static string? Build(StateDocument state, StageConfiguration stage) { - wanted.Add(configuration.State.TryGetValue(slot, out var declared) && declared.Description is { Length: > 0 } text - ? text - : slot); + ArgumentNullException.ThrowIfNull(state); + return Build(state.Configuration, UnfilledSlots(state, stage)); } - StringBuilder builder = new(); - builder.Append(OpenTag).Append('\n'); - builder.Append(Lead).Append(Join(wanted)).Append(".\n"); - builder.Append(Tail).Append('\n'); - builder.Append(CloseTag); - return builder.ToString(); - } - - /// Builds the reminder for the stage the machine holds. - /// The state of one conversation. - /// The stage the machine holds. - /// The reminder text, or when no slot is unfilled. - public static string? Build(StateDocument state, StageConfiguration stage) - { - ArgumentNullException.ThrowIfNull(state); - return Build(state.Configuration, UnfilledSlots(state, stage)); - } - - private static string Join(List wanted) => wanted.Count switch - { - 1 => wanted[0], - 2 => wanted[0] + " and " + wanted[1], - _ => string.Join(", ", wanted.Take(wanted.Count - 1)) + ", and " + wanted[^1], - }; - - /// Adds every slot the exits of one stage read to a set. - /// The loaded document, which holds the named guards. - /// The stage. - /// The set to fill. - /// - /// A stage waits on the slots its exit guards read, and a guard reads a slot through var - /// and through missing alike. already walks both forms for - /// checks 4 and 5, so this reuses it rather than open-coding a second, narrower walk that only - /// catches var. Section 8.4 bans the iteration operators, so that walk is finite. - /// - private static void CollectStageExits(AgentCoreConfiguration configuration, StageConfiguration stage, HashSet names) - { - foreach (var when in stage.To.Select(exit => exit.When)) + private static string Join(List wanted) { - if (when is null) - { - // An unconditional exit waits on no slots, so it adds nothing to read. - continue; - } - - var rule = when.Rule; - if (rule is null - && when.Name is { } guardName - && configuration.Guards.TryGetValue(guardName, out var named)) + return wanted.Count switch { - rule = named; - } + 1 => wanted[0], + 2 => wanted[0] + " and " + wanted[1], + _ => string.Join(", ", wanted.Take(wanted.Count - 1)) + ", and " + wanted[^1], + }; + } - var facts = new GuardRuleFacts(); - facts.Collect(rule); - foreach (var name in facts.Variables) + /// Adds every slot the exits of one stage read to a set. + /// The loaded document, which holds the named guards. + /// The stage. + /// The set to fill. + /// + /// A stage waits on the slots its exit guards read, and a guard reads a slot through var + /// and through missing alike. already walks both forms for + /// checks 4 and 5, so this reuses it rather than open-coding a second, narrower walk that only + /// catches var. Section 8.4 bans the iteration operators, so that walk is finite. + /// + private static void CollectStageExits(AgentCoreConfiguration configuration, StageConfiguration stage, HashSet names) + { + foreach (GuardReference? when in stage.To.Select(exit => exit.When)) { - names.Add(name); + if (when is null) + { + // An unconditional exit waits on no slots, so it adds nothing to read. + continue; + } + + JsonNode? rule = when.Rule; + if (rule is null + && when.Name is { } guardName + && configuration.Guards.TryGetValue(guardName, out JsonNode? named)) + { + rule = named; + } + + GuardRuleFacts facts = new(); + facts.Collect(rule); + foreach (string name in facts.Variables) + { + _ = names.Add(name); + } } } } diff --git a/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs b/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs index 4f4ae5d3..50b88bb1 100644 --- a/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs +++ b/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs @@ -4,84 +4,90 @@ using AgentCore.Application.Tools.Registry; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Binding; - -/// -/// Serves the kind: binding tools. -/// -public sealed class BindingToolSource : IToolSource +namespace AgentCore.Application.Tools.Binding { - private readonly ToolBindingRegistry _registry; - - /// Creates the source. - /// The delegates the host registered. - public BindingToolSource(ToolBindingRegistry registry) + /// + /// Serves the kind: binding tools. + /// + public sealed class BindingToolSource : IToolSource { - ArgumentNullException.ThrowIfNull(registry); - _registry = registry; - } + private readonly ToolBindingRegistry _registry; - /// - /// - /// A binds: name is missing, is not registered, or names a typed method while the - /// declaration also writes parameters:. - /// - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); + /// Creates the source. + /// The delegates the host registered. + public BindingToolSource(ToolBindingRegistry registry) + { + ArgumentNullException.ThrowIfNull(registry); + _registry = registry; + } - List registrations = []; - foreach (var declared in context.DeclarationsOf(ToolKind.Binding)) + /// + /// + /// A binds: name is missing, is not registered, or names a typed method while the + /// declaration also writes parameters:. + /// + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) { - if (declared.Binds is not { Length: > 0 } name) - { - throw ToolSourceError.Fail($"the tool '{declared.Id}' is kind: binding and names no binds:."); - } + ArgumentNullException.ThrowIfNull(context); - if (_registry.TryGetMethod(name, out var method) && method is not null) + List registrations = []; + foreach (ToolConfiguration declared in context.DeclarationsOf(ToolKind.Binding)) { - if (declared.Parameters is not null) + if (declared.Binds is not { Length: > 0 } name) + { + throw ToolSourceError.Fail($"the tool '{declared.Id}' is kind: binding and names no binds:."); + } + + if (_registry.TryGetMethod(name, out Delegate? method) && method is not null) + { + if (declared.Parameters is not null) + { + throw ToolSourceError.Fail( + $"the tool '{declared.Id}' binds to '{name}', which the host registered as a typed " + + "method, and it also declares parameters:. The method signature is the schema, so " + + "the two disagree the moment either one changes. Take the parameters: off the " + + "declaration, or register the name as a ToolBinding instead."); + } + + Delegate typed = method; + registrations.Add(new ToolRegistration( + declared.Id, declared.Description ?? string.Empty, () => new TypedBindingTool(declared, typed))); + continue; + } + + if (!_registry.TryGetBinding(name, out ToolBinding? binding) || binding is null) { throw ToolSourceError.Fail( - $"the tool '{declared.Id}' binds to '{name}', which the host registered as a typed " - + "method, and it also declares parameters:. The method signature is the schema, so " - + "the two disagree the moment either one changes. Take the parameters: off the " - + "declaration, or register the name as a ToolBinding instead."); + $"the tool '{declared.Id}' binds to '{name}', which the host did not register. Register the " + + "delegate on the ToolBindingRegistry before the document compiles."); } - var typed = method; + ToolBinding bound = binding; registrations.Add(new ToolRegistration( - declared.Id, declared.Description ?? string.Empty, () => new TypedBindingTool(declared, typed))); - continue; - } - - if (!_registry.TryGetBinding(name, out var binding) || binding is null) - { - throw ToolSourceError.Fail( - $"the tool '{declared.Id}' binds to '{name}', which the host did not register. Register the " - + "delegate on the ToolBindingRegistry before the document compiles."); + declared.Id, declared.Description ?? string.Empty, () => new BindingTool(declared, bound))); } - var bound = binding; - registrations.Add(new ToolRegistration( - declared.Id, declared.Description ?? string.Empty, () => new BindingTool(declared, bound))); + return ValueTask.FromResult>(registrations); } - - return ValueTask.FromResult>(registrations); } -} -/// One kind: binding tool. -internal sealed class BindingTool : DeclaredTool -{ - private readonly ToolBinding _binding; + /// One kind: binding tool. + internal sealed class BindingTool : DeclaredTool + { + private readonly ToolBinding _binding; - internal BindingTool(ToolConfiguration tool, ToolBinding binding) - : base(tool) => _binding = binding; + internal BindingTool(ToolConfiguration tool, ToolBinding binding) + : base(tool) + { + _binding = binding; + } - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) - => _binding(ArgumentsAsJson(arguments), cancellationToken); + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + return _binding(ArgumentsAsJson(arguments), cancellationToken); + } + } } diff --git a/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs b/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs index c0ff9199..80eff193 100644 --- a/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs +++ b/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs @@ -1,112 +1,110 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Tools.Binding; - -/// -/// One host delegate a kind: binding tool calls. -/// -/// The arguments the model filled, as one JSON object. -/// Cancels the conversation. -/// -/// The result the model reads. A reaches the model exactly as it is written. -/// -public delegate ValueTask ToolBinding(JsonObject arguments, CancellationToken cancellationToken); - -/// -/// The map from a binds: name to the host delegate behind it. -/// -public sealed class ToolBindingRegistry +namespace AgentCore.Application.Tools.Binding { - private readonly Dictionary _bindings = new(StringComparer.Ordinal); + /// + /// One host delegate a kind: binding tool calls. + /// + /// The arguments the model filled, as one JSON object. + /// Cancels the conversation. + /// + /// The result the model reads. A reaches the model exactly as it is written. + /// + public delegate ValueTask ToolBinding(JsonObject arguments, CancellationToken cancellationToken); - /// Gets the number of names the host registered. - public int Count => _bindings.Count; + /// + /// The map from a binds: name to the host delegate behind it. + /// + public sealed class ToolBindingRegistry + { + private readonly Dictionary _bindings = new(StringComparer.Ordinal); - /// Gets the names the host registered. - public IReadOnlyCollection Names => _bindings.Keys; + /// Gets the number of names the host registered. + public int Count => _bindings.Count; - /// Registers one host delegate that reads the arguments as JSON. - /// The name a binds: field writes. - /// The delegate the tool calls. - /// This registry, so a host chains its registrations. - /// The name is already registered. - public ToolBindingRegistry Register(string name, ToolBinding binding) - { - ArgumentNullException.ThrowIfNull(binding); - return Add(name, binding); - } + /// Gets the names the host registered. + public IReadOnlyCollection Names => _bindings.Keys; - /// Registers one host method, and its parameters become the tool's arguments. - /// The name a binds: field writes. - /// - /// The method the tool calls. Its parameters are the arguments the model fills, and their JSON - /// Schema, so the declaration this name serves must write no parameters:. A - /// on a parameter reaches the model. A - /// parameter of type is filled by the runtime with the conversation the turn - /// belongs to, and is not exposed to the model. - /// - /// This registry, so a host chains its registrations. - /// The name is already registered. - public ToolBindingRegistry Register(string name, Delegate method) - { - ArgumentNullException.ThrowIfNull(method); - return Add(name, method); - } + /// Registers one host delegate that reads the arguments as JSON. + /// The name a binds: field writes. + /// The delegate the tool calls. + /// This registry, so a host chains its registrations. + /// The name is already registered. + public ToolBindingRegistry Register(string name, ToolBinding binding) + { + ArgumentNullException.ThrowIfNull(binding); + return Add(name, binding); + } - /// Reports whether one name is registered, either way. - /// The name a binds: field writes. - /// when the host registered the name. - public bool Contains(string name) - { - ArgumentNullException.ThrowIfNull(name); - return _bindings.ContainsKey(name); - } + /// Registers one host method, and its parameters become the tool's arguments. + /// The name a binds: field writes. + /// + /// The method the tool calls. Its parameters are the arguments the model fills, and their JSON + /// Schema, so the declaration this name serves must write no parameters:. A + /// on a parameter reaches the model. A + /// parameter of type is filled by the runtime with the conversation the turn + /// belongs to, and is not exposed to the model. + /// + /// This registry, so a host chains its registrations. + /// The name is already registered. + public ToolBindingRegistry Register(string name, Delegate method) + { + ArgumentNullException.ThrowIfNull(method); + return Add(name, method); + } - /// Reads the JSON delegate one name points at. - /// The name a binds: field writes. - /// The delegate, when the host registered this name as a JSON delegate. - /// - /// when the host registered the name as a . A - /// name the host registered as a typed method answers ; read it with - /// . - /// - public bool TryGetBinding(string name, out ToolBinding? binding) - { - ArgumentNullException.ThrowIfNull(name); + /// Reports whether one name is registered, either way. + /// The name a binds: field writes. + /// when the host registered the name. + public bool Contains(string name) + { + ArgumentNullException.ThrowIfNull(name); + return _bindings.ContainsKey(name); + } - binding = _bindings.TryGetValue(name, out var registered) ? registered as ToolBinding : null; + /// Reads the JSON delegate one name points at. + /// The name a binds: field writes. + /// The delegate, when the host registered this name as a JSON delegate. + /// + /// when the host registered the name as a . A + /// name the host registered as a typed method answers ; read it with + /// . + /// + public bool TryGetBinding(string name, out ToolBinding? binding) + { + ArgumentNullException.ThrowIfNull(name); - return binding is not null; - } + binding = _bindings.TryGetValue(name, out Delegate? registered) ? registered as ToolBinding : null; - /// Reads the typed method one name points at. - /// The name a binds: field writes. - /// The method, when the host registered this name as a typed method. - /// - /// when the host registered the name as a typed method. A name the host - /// registered as a answers ; read it with - /// . - /// - public bool TryGetMethod(string name, out Delegate? method) - { - ArgumentNullException.ThrowIfNull(name); + return binding is not null; + } - method = _bindings.TryGetValue(name, out var registered) && registered is not ToolBinding - ? registered - : null; + /// Reads the typed method one name points at. + /// The name a binds: field writes. + /// The method, when the host registered this name as a typed method. + /// + /// when the host registered the name as a typed method. A name the host + /// registered as a answers ; read it with + /// . + /// + public bool TryGetMethod(string name, out Delegate? method) + { + ArgumentNullException.ThrowIfNull(name); - return method is not null; - } + method = _bindings.TryGetValue(name, out Delegate? registered) && registered is not ToolBinding + ? registered + : null; - private ToolBindingRegistry Add(string name, Delegate registered) - { - ArgumentException.ThrowIfNullOrEmpty(name); + return method is not null; + } - if (!_bindings.TryAdd(name, registered)) + private ToolBindingRegistry Add(string name, Delegate registered) { - throw new ArgumentException($"the binding '{name}' is already registered.", nameof(name)); - } + ArgumentException.ThrowIfNullOrEmpty(name); - return this; + return !_bindings.TryAdd(name, registered) + ? throw new ArgumentException($"the binding '{name}' is already registered.", nameof(name)) + : this; + } } } diff --git a/src/AgentCore.Application/Tools/Binding/ToolParameterBindings.cs b/src/AgentCore.Application/Tools/Binding/ToolParameterBindings.cs index d8c66790..7779e878 100644 --- a/src/AgentCore.Application/Tools/Binding/ToolParameterBindings.cs +++ b/src/AgentCore.Application/Tools/Binding/ToolParameterBindings.cs @@ -2,34 +2,35 @@ using AgentCore.Application.Runtime; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Binding; - -// The runtime-filled parameters a bound tool declares. The model never sees them: they bind -// from the turn the invoking client filed beside the call's arguments. -internal static class ToolParameterBindings +namespace AgentCore.Application.Tools.Binding { - /// Binds one runtime-filled parameter, or answers for the model's own. - internal static AIFunctionFactoryOptions.ParameterBindingOptions For(ParameterInfo parameter) + // The runtime-filled parameters a bound tool declares. The model never sees them: they bind + // from the turn the invoking client filed beside the call's arguments. + internal static class ToolParameterBindings { - ArgumentNullException.ThrowIfNull(parameter); - - var type = parameter.ParameterType; - return type == typeof(ToolCallScope) || type == typeof(TurnInvocation) - ? new() { ExcludeFromSchema = true, BindParameter = (_, args) => Bind(type, args) } - : default; - } + /// Binds one runtime-filled parameter, or answers for the model's own. + internal static AIFunctionFactoryOptions.ParameterBindingOptions For(ParameterInfo parameter) + { + ArgumentNullException.ThrowIfNull(parameter); - private static object? Bind(Type type, AIFunctionArguments? args) - { - var invocation = TurnInvocation.FiledIn(args); + Type type = parameter.ParameterType; + return type == typeof(ToolCallScope) || type == typeof(TurnInvocation) + ? new() { ExcludeFromSchema = true, BindParameter = (_, args) => Bind(type, args) } + : default; + } - if (type == typeof(TurnInvocation)) + private static object? Bind(Type type, AIFunctionArguments? args) { - return invocation; - } + TurnInvocation? invocation = TurnInvocation.FiledIn(args); - return invocation is not null - ? ToolCallScopes.From(invocation) - : throw new InvalidOperationException(ToolCallScopes.NoTurnMessage); + if (type == typeof(TurnInvocation)) + { + return invocation; + } + + return invocation is not null + ? ToolCallScopes.From(invocation) + : throw new InvalidOperationException(ToolCallScopes.NoTurnMessage); + } } } diff --git a/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs b/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs index c36cb2d1..401ccd34 100644 --- a/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs +++ b/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs @@ -2,32 +2,37 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Binding; - -/// -/// One kind: binding tool whose arguments come from a host method's signature. -/// -internal sealed class TypedBindingTool : DeclaredTool +namespace AgentCore.Application.Tools.Binding { - private readonly AIFunction _inner; + /// + /// One kind: binding tool whose arguments come from a host method's signature. + /// + internal sealed class TypedBindingTool : DeclaredTool + { + private readonly AIFunction _inner; - internal TypedBindingTool(ToolConfiguration tool, Delegate method) - : base(tool) - => _inner = AIFunctionFactory.Create(method, new AIFunctionFactoryOptions + internal TypedBindingTool(ToolConfiguration tool, Delegate method) + : base(tool) { - Name = tool.Id, - Description = tool.Description, - ConfigureParameterBinding = ToolParameterBindings.For, - }); + _inner = AIFunctionFactory.Create(method, new AIFunctionFactoryOptions + { + Name = tool.Id, + Description = tool.Description, + ConfigureParameterBinding = ToolParameterBindings.For, + }); + } - /// - /// Gets the schema the host method's parameters describe. It replaces the base schema, which - /// reads the document's parameters:, because a typed binding declares none. - /// - public override JsonElement JsonSchema => _inner.JsonSchema; + /// + /// Gets the schema the host method's parameters describe. It replaces the base schema, which + /// reads the document's parameters:, because a typed binding declares none. + /// + public override JsonElement JsonSchema => _inner.JsonSchema; - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) - => _inner.InvokeAsync(arguments, cancellationToken); + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + return _inner.InvokeAsync(arguments, cancellationToken); + } + } } diff --git a/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs b/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs index 4cdb310b..6b190218 100644 --- a/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs +++ b/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs @@ -1,11 +1,12 @@ -namespace AgentCore.Application.Tools.Builtin; - -/// The name of every tool AgentCore ships. uses: names one of these. -public static class BuiltinToolNames +namespace AgentCore.Application.Tools.Builtin { - /// Lets the model provider run a web search of its own. - public const string WebSearch = "web.search"; + /// The name of every tool AgentCore ships. uses: names one of these. + public static class BuiltinToolNames + { + /// Lets the model provider run a web search of its own. + public const string WebSearch = "web.search"; - /// Hands one file from the conversation's workspace to the person, through the blob store. - public const string FilePublish = "file.publish"; + /// Hands one file from the conversation's workspace to the person, through the blob store. + public const string FilePublish = "file.publish"; + } } diff --git a/src/AgentCore.Application/Tools/Builtin/BuiltinToolOptions.cs b/src/AgentCore.Application/Tools/Builtin/BuiltinToolOptions.cs index a3fdaf93..f8475519 100644 --- a/src/AgentCore.Application/Tools/Builtin/BuiltinToolOptions.cs +++ b/src/AgentCore.Application/Tools/Builtin/BuiltinToolOptions.cs @@ -2,22 +2,26 @@ using AgentCore.Application.Tools.Binding; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Builtin; - -/// -/// What every built-in hands , and the rules they all share. -/// -internal static class BuiltinToolOptions +namespace AgentCore.Application.Tools.Builtin { - /// Builds the options every built-in is created with. - /// The declaration the document holds. - /// The options: the declared id as the name, the resolved description, no result schema, - /// and the turn bound from the conversation rather than filled by the model. - internal static AIFunctionFactoryOptions Options(ToolConfiguration tool) => new() + /// + /// What every built-in hands , and the rules they all share. + /// + internal static class BuiltinToolOptions { - Name = tool.Id, - Description = tool.Description ?? string.Empty, - ExcludeResultSchema = true, - ConfigureParameterBinding = ToolParameterBindings.For, - }; + /// Builds the options every built-in is created with. + /// The declaration the document holds. + /// The options: the declared id as the name, the resolved description, no result schema, + /// and the turn bound from the conversation rather than filled by the model. + internal static AIFunctionFactoryOptions Options(ToolConfiguration tool) + { + return new() + { + Name = tool.Id, + Description = tool.Description ?? string.Empty, + ExcludeResultSchema = true, + ConfigureParameterBinding = ToolParameterBindings.For, + }; + } + } } diff --git a/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs b/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs index e23de14e..0fb72e14 100644 --- a/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs +++ b/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs @@ -2,96 +2,104 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; using AgentCore.Application.Tools.Registry; +using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Builtin; - -/// -/// Serves the kind: builtin tools. -/// -public sealed class BuiltinToolSource : IToolSource +namespace AgentCore.Application.Tools.Builtin { - private static readonly Dictionary Definitions = - new IBuiltinToolDefinition[] - { - new WebSearchToolDefinition(), - new FilePublishToolDefinition(), - }.ToDictionary(definition => definition.Name, StringComparer.Ordinal); - - private readonly BuiltinToolPorts _ports; - - /// Creates the source. - /// The adapters the host bound. - public BuiltinToolSource(BuiltinToolPorts ports) + /// + /// Serves the kind: builtin tools. + /// + public sealed class BuiltinToolSource : IToolSource { - ArgumentNullException.ThrowIfNull(ports); - _ports = ports; - } + private static readonly Dictionary Definitions = + new IBuiltinToolDefinition[] + { + new WebSearchToolDefinition(), + new FilePublishToolDefinition(), + }.ToDictionary(definition => definition.Name, StringComparer.Ordinal); - /// - public ValueTask> ProvideAsync( - ToolSourceContext context, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); + private readonly BuiltinToolPorts _ports; - List registrations = []; + /// Creates the source. + /// The adapters the host bound. + public BuiltinToolSource(BuiltinToolPorts ports) + { + ArgumentNullException.ThrowIfNull(ports); + _ports = ports; + } - foreach (var declared in context.DeclarationsOf(ToolKind.Builtin)) + /// + public ValueTask> ProvideAsync( + ToolSourceContext context, + CancellationToken cancellationToken = default) { - // Built eagerly: a definition reports an unbound port by throwing, and that failure - // belongs on the boot rather than on the first call. - var uses = declared.Uses; + ArgumentNullException.ThrowIfNull(context); - if (uses is null || !Definitions.TryGetValue(uses, out var definition)) - { - throw UnknownName(declared); - } + List registrations = []; - if (UnreadDial(declared) is { } dial) + foreach (ToolConfiguration declared in context.DeclarationsOf(ToolKind.Builtin)) { - throw ToolSourceError.Fail( - $"the tool '{declared.Id}' is kind: builtin and uses: '{uses}', which is a plain function " - + $"and reads no {dial}. Take the key out."); + // Built eagerly: a definition reports an unbound port by throwing, and that failure + // belongs on the boot rather than on the first call. + string? uses = declared.Uses; + + if (uses is null || !Definitions.TryGetValue(uses, out IBuiltinToolDefinition? definition)) + { + throw UnknownName(declared); + } + + if (UnreadDial(declared) is { } dial) + { + throw ToolSourceError.Fail( + $"the tool '{declared.Id}' is kind: builtin and uses: '{uses}', which is a plain function " + + $"and reads no {dial}. Take the key out."); + } + + ToolConfiguration resolved = Described(declared, definition); + AITool built = definition.Build(resolved, _ports); + + registrations.Add(new ToolRegistration(declared.Id, resolved.Description!, () => built)); } - var resolved = Described(declared, definition); - var built = definition.Build(resolved, _ports); + return ValueTask.FromResult>(registrations); + } - registrations.Add(new ToolRegistration(declared.Id, resolved.Description!, () => built)); + /// + /// Applies the one description rule: what the document wrote, else what the source ships. + /// + /// The declaration the document holds. + /// The shipped thing that name serves. + /// The declaration with a description on it. + internal static ToolConfiguration Described(ToolConfiguration declared, IToolDefinition definition) + { + return declared.Description is null ? declared with { Description = definition.DefaultDescription } : declared; } - return ValueTask.FromResult>(registrations); - } + internal static ConfigurationLoadException Unbound(ToolConfiguration tool, string uses, string port) + { + return ToolSourceError.Fail( + $"the tool '{tool.Id}' is kind: builtin and uses: '{uses}', which reads {port}, and no " + + "adapter binds that port. Bind one, or take the tool out of the document."); + } - /// - /// Applies the one description rule: what the document wrote, else what the source ships. - /// - /// The declaration the document holds. - /// The shipped thing that name serves. - /// The declaration with a description on it. - internal static ToolConfiguration Described(ToolConfiguration declared, IToolDefinition definition) - => declared.Description is null ? declared with { Description = definition.DefaultDescription } : declared; - - internal static ConfigurationLoadException Unbound(ToolConfiguration tool, string uses, string port) - => ToolSourceError.Fail( - $"the tool '{tool.Id}' is kind: builtin and uses: '{uses}', which reads {port}, and no " - + "adapter binds that port. Bind one, or take the tool out of the document."); - - /// Names a dial the document set on a built-in that has nothing to spend it on. - /// The declaration the document holds. - /// The key, or when the declaration sets neither. - private static string? UnreadDial(ToolConfiguration tool) - { - if (tool.Model is not null) + /// Names a dial the document set on a built-in that has nothing to spend it on. + /// The declaration the document holds. + /// The key, or when the declaration sets neither. + private static string? UnreadDial(ToolConfiguration tool) { - return "model:"; + if (tool.Model is not null) + { + return "model:"; + } + + return tool.MaxRounds is not null ? "maxRounds:" : null; } - return tool.MaxRounds is not null ? "maxRounds:" : null; + private static ConfigurationLoadException UnknownName(ToolConfiguration tool) + { + return ToolSourceError.Fail( + $"the tool '{tool.Id}' is kind: builtin and uses: '{tool.Uses}', which AgentCore does " + + $"not ship. This release ships {string.Join(", ", Definitions.Keys)}."); + } } - - private static ConfigurationLoadException UnknownName(ToolConfiguration tool) - => ToolSourceError.Fail( - $"the tool '{tool.Id}' is kind: builtin and uses: '{tool.Uses}', which AgentCore does " - + $"not ship. This release ships {string.Join(", ", Definitions.Keys)}."); } diff --git a/src/AgentCore.Application/Tools/Builtin/FilePublishTool.cs b/src/AgentCore.Application/Tools/Builtin/FilePublishTool.cs index c8e59498..e6690682 100644 --- a/src/AgentCore.Application/Tools/Builtin/FilePublishTool.cs +++ b/src/AgentCore.Application/Tools/Builtin/FilePublishTool.cs @@ -11,172 +11,179 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Tools.Builtin; - -/// -/// Copies one file out of the running conversation's workspace into the blob store, owned by the conversation, and -/// files a on the turn so the card reaches the person. -/// -/// -/// A background child runs with no turn, so it has no drain to file the card on: its blob is still -/// stored under the parent conversation, and the link goes back to the child in the result alone. -/// -internal sealed class FilePublishTool +namespace AgentCore.Application.Tools.Builtin { - private readonly IBlobStore _blobs; - - private readonly BlobPolicy _policy; - - private readonly string _workspaceRoot; - - private readonly ILogger _logger; - - private readonly ToolConfiguration _tool; - - /// Creates the tool. - /// The declaration the document holds. Its id is the name the model calls. - /// The store providers.blobs opened. - /// The cap and the allowlist. - /// The root every conversation's folder sits under. - /// Where a refused file is reported. - public FilePublishTool(ToolConfiguration tool, IBlobStore blobs, BlobPolicy policy, string workspaceRoot, ILogger logger) + /// + /// Copies one file out of the running conversation's workspace into the blob store, owned by the conversation, and + /// files a on the turn so the card reaches the person. + /// + /// + /// A background child runs with no turn, so it has no drain to file the card on: its blob is still + /// stored under the parent conversation, and the link goes back to the child in the result alone. + /// + internal sealed class FilePublishTool { - ArgumentNullException.ThrowIfNull(tool); - ArgumentNullException.ThrowIfNull(blobs); - ArgumentNullException.ThrowIfNull(policy); - ArgumentException.ThrowIfNullOrWhiteSpace(workspaceRoot); - ArgumentNullException.ThrowIfNull(logger); - - _tool = tool; - _blobs = blobs; - _policy = policy; - _workspaceRoot = workspaceRoot; - _logger = logger; - } - - /// Builds the function the model calls, named after the declaration. - /// The function. - public AIFunction AsAIFunction() => AIFunctionFactory.Create(PublishAsync, BuiltinToolOptions.Options(_tool)); + private readonly IBlobStore _blobs; - private async ValueTask PublishAsync( - [Description("The file's path, relative to the workspace.")] string path, - [Description("A short label for the person, such as 'Sales by month'.")] string? title = null, - TurnInvocation? turn = null, - CancellationToken cancellationToken = default) - { - if (string.IsNullOrWhiteSpace(path)) - { - return Failed("path is required: the file's path, relative to the workspace."); - } + private readonly BlobPolicy _policy; - if (OwnerOf(turn) is not { } owner) - { - Log.SandboxFileHasNoOwner(_logger, _tool.Id); - return Failed("no conversation is running, so there is nobody to hand the file to."); - } + private readonly string _workspaceRoot; - var (conversationId, workspace) = owner; + private readonly ILogger _logger; - if (ResolveInside(workspace, path) is not { } full) - { - return Failed($"'{path}' is not inside the workspace. Give a path relative to the workspace, without '..'."); - } + private readonly ToolConfiguration _tool; - if (!File.Exists(full)) + /// Creates the tool. + /// The declaration the document holds. Its id is the name the model calls. + /// The store providers.blobs opened. + /// The cap and the allowlist. + /// The root every conversation's folder sits under. + /// Where a refused file is reported. + public FilePublishTool(ToolConfiguration tool, IBlobStore blobs, BlobPolicy policy, string workspaceRoot, ILogger logger) { - return Failed($"there is no file at '{path}' in the workspace."); + ArgumentNullException.ThrowIfNull(tool); + ArgumentNullException.ThrowIfNull(blobs); + ArgumentNullException.ThrowIfNull(policy); + ArgumentException.ThrowIfNullOrWhiteSpace(workspaceRoot); + ArgumentNullException.ThrowIfNull(logger); + + _tool = tool; + _blobs = blobs; + _policy = policy; + _workspaceRoot = workspaceRoot; + _logger = logger; } - var name = Path.GetFileName(full); - var length = new FileInfo(full).Length; - - if (!BlobName.IsSafe(name)) + /// Builds the function the model calls, named after the declaration. + /// The function. + public AIFunction AsAIFunction() { - Log.SandboxFileRefused(_logger, conversationId, name, "the name is not a plain file name"); - return Failed($"'{name}' is not a plain file name. Rename the file and publish it again."); + return AIFunctionFactory.Create(PublishAsync, BuiltinToolOptions.Options(_tool)); } - if (_policy.WhyRefused(name, length) is { } reason) + private async ValueTask PublishAsync( + [Description("The file's path, relative to the workspace.")] string path, + [Description("A short label for the person, such as 'Sales by month'.")] string? title = null, + TurnInvocation? turn = null, + CancellationToken cancellationToken = default) { - Log.SandboxFileRefused(_logger, conversationId, name, reason); - return Failed($"'{name}' was refused: {reason}. Allowed extensions: {string.Join(", ", _policy.AllowedExtensions)}; " - + $"largest file: {_policy.MaxBytes} bytes."); + if (string.IsNullOrWhiteSpace(path)) + { + return Failed("path is required: the file's path, relative to the workspace."); + } + + if (OwnerOf(turn) is not { } owner) + { + Log.SandboxFileHasNoOwner(_logger, _tool.Id); + return Failed("no conversation is running, so there is nobody to hand the file to."); + } + + (string? conversationId, string? workspace) = owner; + + if (ResolveInside(workspace, path) is not { } full) + { + return Failed($"'{path}' is not inside the workspace. Give a path relative to the workspace, without '..'."); + } + + if (!File.Exists(full)) + { + return Failed($"there is no file at '{path}' in the workspace."); + } + + string name = Path.GetFileName(full); + long length = new FileInfo(full).Length; + + if (!BlobName.IsSafe(name)) + { + Log.SandboxFileRefused(_logger, conversationId, name, "the name is not a plain file name"); + return Failed($"'{name}' is not a plain file name. Rename the file and publish it again."); + } + + if (_policy.WhyRefused(name, length) is { } reason) + { + Log.SandboxFileRefused(_logger, conversationId, name, reason); + return Failed($"'{name}' was refused: {reason}. Allowed extensions: {string.Join(", ", _policy.AllowedExtensions)}; " + + $"largest file: {_policy.MaxBytes} bytes."); + } + + BlobRef blob; + Uri? url; + + try + { + await using FileStream content = File.OpenRead(full); + + blob = await _blobs + .PutAsync(new BlobWrite(conversationId, name, BlobMediaTypes.Of(name), content, length), cancellationToken) + .ConfigureAwait(false); + + url = await _blobs.LinkAsync(blob, BlobLink.Lifetime, cancellationToken).ConfigureAwait(false); + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + Log.SandboxFileCaptureFailed(_logger, conversationId, name, exception); + return Failed($"'{name}' could not be stored: {exception.Message}"); + } + + turn?.Files?.Publish(new FileContent + { + Name = blob.Name, + FileId = path, + Title = string.IsNullOrWhiteSpace(title) ? null : title.Trim(), + MediaType = blob.MediaType, + Length = blob.Length, + Kept = true, + }); + + return new JsonObject + { + ["name"] = blob.Name, + ["mediaType"] = blob.MediaType, + ["length"] = blob.Length, + ["url"] = url?.ToString(), + }; } - BlobRef blob; - Uri? url; - - try + /// + /// The conversation that owns the file and its folder: the filed turn, or for a background child the + /// stamp its session carries and the folder that call id names under the root. + /// + private (string ConversationId, string Workspace)? OwnerOf(TurnInvocation? turn) { - await using var content = File.OpenRead(full); - - blob = await _blobs - .PutAsync(new BlobWrite(conversationId, name, BlobMediaTypes.Of(name), content, length), cancellationToken) - .ConfigureAwait(false); - - url = await _blobs.LinkAsync(blob, BlobLink.Lifetime, cancellationToken).ConfigureAwait(false); - } - catch (Exception exception) when (exception is not OperationCanceledException) - { - Log.SandboxFileCaptureFailed(_logger, conversationId, name, exception); - return Failed($"'{name}' could not be stored: {exception.Message}"); + if (turn is { ConversationId: { } fromTurn }) + { + return turn.Workspace is { } workspace ? (fromTurn, workspace) : null; + } + + AgentSession? session = AIAgent.CurrentRunContext?.Session; + + return session is not null + && session.StateBag.TryGetValue(BlobOwnerKey.Value, out string? stamped) + && stamped is not null + ? (stamped, Path.Combine(_workspaceRoot, stamped)) + : null; } - turn?.Files?.Publish(new FileContent - { - Name = blob.Name, - FileId = path, - Title = string.IsNullOrWhiteSpace(title) ? null : title.Trim(), - MediaType = blob.MediaType, - Length = blob.Length, - Kept = true, - }); - - return new JsonObject - { - ["name"] = blob.Name, - ["mediaType"] = blob.MediaType, - ["length"] = blob.Length, - ["url"] = url?.ToString(), - }; - } - - /// - /// The conversation that owns the file and its folder: the filed turn, or for a background child the - /// stamp its session carries and the folder that call id names under the root. - /// - private (string ConversationId, string Workspace)? OwnerOf(TurnInvocation? turn) - { - if (turn is { ConversationId: { } fromTurn }) + /// Resolves a model-written path under the workspace, or nothing when it escapes. + private static string? ResolveInside(string workspace, string path) { - return turn.Workspace is { } workspace ? (fromTurn, workspace) : null; + if (Path.IsPathRooted(path)) + { + return null; + } + + string root = Path.GetFullPath(workspace); + string rootWithSeparator = root.EndsWith(Path.DirectorySeparatorChar) ? root : root + Path.DirectorySeparatorChar; + string full = Path.GetFullPath(Path.Combine(root, path)); + + return full.StartsWith(rootWithSeparator, StringComparison.Ordinal) && full.Length > rootWithSeparator.Length + ? full + : null; } - var session = AIAgent.CurrentRunContext?.Session; - - return session is not null - && session.StateBag.TryGetValue(BlobOwnerKey.Value, out var stamped) - && stamped is not null - ? (stamped, Path.Combine(_workspaceRoot, stamped)) - : null; - } - - /// Resolves a model-written path under the workspace, or nothing when it escapes. - private static string? ResolveInside(string workspace, string path) - { - if (Path.IsPathRooted(path)) + private JsonObject Failed(string message) { - return null; + return ToolErrorResult.Create(_tool.Id, message); } - - var root = Path.GetFullPath(workspace); - var rootWithSeparator = root.EndsWith(Path.DirectorySeparatorChar) ? root : root + Path.DirectorySeparatorChar; - var full = Path.GetFullPath(Path.Combine(root, path)); - - return full.StartsWith(rootWithSeparator, StringComparison.Ordinal) && full.Length > rootWithSeparator.Length - ? full - : null; } - - private JsonObject Failed(string message) => ToolErrorResult.Create(_tool.Id, message); } diff --git a/src/AgentCore.Application/Tools/Builtin/FilePublishToolDefinition.cs b/src/AgentCore.Application/Tools/Builtin/FilePublishToolDefinition.cs index 9bedb4c3..b40bbcd0 100644 --- a/src/AgentCore.Application/Tools/Builtin/FilePublishToolDefinition.cs +++ b/src/AgentCore.Application/Tools/Builtin/FilePublishToolDefinition.cs @@ -1,41 +1,43 @@ using AgentCore.Application.Blobs; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Tools.Builtin; - -/// -/// The uses: file.publish builtin: one over the blob store. -/// -internal sealed class FilePublishToolDefinition : IBuiltinToolDefinition +namespace AgentCore.Application.Tools.Builtin { - /// - public string Name => BuiltinToolNames.FilePublish; + /// + /// The uses: file.publish builtin: one over the blob store. + /// + internal sealed class FilePublishToolDefinition : IBuiltinToolDefinition + { + /// + public string Name => BuiltinToolNames.FilePublish; - /// - public string DefaultDescription => - "Hands one file from the workspace to the person and returns a link to it. " - + "A file that is not published is lost when the conversation ends."; + /// + public string DefaultDescription => + "Hands one file from the workspace to the person and returns a link to it. " + + "A file that is not published is lost when the conversation ends."; - /// - public AITool Build(ToolConfiguration tool, BuiltinToolPorts ports) - { - ArgumentNullException.ThrowIfNull(tool); - ArgumentNullException.ThrowIfNull(ports); + /// + public AITool Build(ToolConfiguration tool, BuiltinToolPorts ports) + { + ArgumentNullException.ThrowIfNull(tool); + ArgumentNullException.ThrowIfNull(ports); - var blobs = ports.Blobs ?? throw BuiltinToolSource.Unbound(tool, Name, "providers.blobs"); + IBlobStore blobs = ports.Blobs ?? throw BuiltinToolSource.Unbound(tool, Name, "providers.blobs"); - var root = ports.WorkspaceRoot ?? throw BuiltinToolSource.Unbound( - tool, Name, "the workspace root (options.UseWorkspace(...))"); + string root = ports.WorkspaceRoot ?? throw BuiltinToolSource.Unbound( + tool, Name, "the workspace root (options.UseWorkspace(...))"); - return new FilePublishTool( - tool, - blobs, - ports.BlobPolicy ?? BlobPolicy.Default, - root, - ports.Loggers?.CreateLogger() ?? NullLogger.Instance) - .AsAIFunction(); + return new FilePublishTool( + tool, + blobs, + ports.BlobPolicy ?? BlobPolicy.Default, + root, + ports.Loggers?.CreateLogger() ?? NullLogger.Instance) + .AsAIFunction(); + } } } diff --git a/src/AgentCore.Application/Tools/Builtin/IBuiltinToolDefinition.cs b/src/AgentCore.Application/Tools/Builtin/IBuiltinToolDefinition.cs index d1d940cf..e10be944 100644 --- a/src/AgentCore.Application/Tools/Builtin/IBuiltinToolDefinition.cs +++ b/src/AgentCore.Application/Tools/Builtin/IBuiltinToolDefinition.cs @@ -5,38 +5,39 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Tools.Builtin; - -/// The adapters a built-in may need. A built-in uses none or more of them. -/// The factory the tool runs on, or when the host bound none. -/// The store providers.blobs opened, or when the document names none. -/// The cap and the allowlist a published file must pass, or for . -/// The root options.UseWorkspace(...) bound, or when the host bound none. -/// Where a built-in takes its logger from, or to log nothing. -public sealed record BuiltinToolPorts( - IChatClientFactory? ChatClients, - IBlobStore? Blobs = null, - BlobPolicy? BlobPolicy = null, - string? WorkspaceRoot = null, - ILoggerFactory? Loggers = null); - -/// What every uses: name AgentCore ships has, whatever kind of thing it builds. -internal interface IToolDefinition +namespace AgentCore.Application.Tools.Builtin { - /// The name a uses: field writes. - string Name { get; } + /// The adapters a built-in may need. A built-in uses none or more of them. + /// The factory the tool runs on, or when the host bound none. + /// The store providers.blobs opened, or when the document names none. + /// The cap and the allowlist a published file must pass, or for . + /// The root options.UseWorkspace(...) bound, or when the host bound none. + /// Where a built-in takes its logger from, or to log nothing. + public sealed record BuiltinToolPorts( + IChatClientFactory? ChatClients, + IBlobStore? Blobs = null, + BlobPolicy? BlobPolicy = null, + string? WorkspaceRoot = null, + ILoggerFactory? Loggers = null); - /// The sentence the model reads when the document writes no description:. - string DefaultDescription { get; } -} + /// What every uses: name AgentCore ships has, whatever kind of thing it builds. + internal interface IToolDefinition + { + /// The name a uses: field writes. + string Name { get; } -/// One tool AgentCore ships, describing itself. -internal interface IBuiltinToolDefinition : IToolDefinition -{ - /// Builds the tool. - /// The declaration the document holds. - /// The adapters the host bound. - /// The tool. - /// A port this built-in reads is unbound. - AITool Build(ToolConfiguration tool, BuiltinToolPorts ports); + /// The sentence the model reads when the document writes no description:. + string DefaultDescription { get; } + } + + /// One tool AgentCore ships, describing itself. + internal interface IBuiltinToolDefinition : IToolDefinition + { + /// Builds the tool. + /// The declaration the document holds. + /// The adapters the host bound. + /// The tool. + /// A port this built-in reads is unbound. + AITool Build(ToolConfiguration tool, BuiltinToolPorts ports); + } } diff --git a/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs b/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs index 199e8817..1a7c891d 100644 --- a/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs +++ b/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs @@ -1,20 +1,24 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Builtin; - -/// -/// The uses: web.search builtin: one . -/// -internal sealed class WebSearchToolDefinition : IBuiltinToolDefinition +namespace AgentCore.Application.Tools.Builtin { - /// - public string Name => BuiltinToolNames.WebSearch; + /// + /// The uses: web.search builtin: one . + /// + internal sealed class WebSearchToolDefinition : IBuiltinToolDefinition + { + /// + public string Name => BuiltinToolNames.WebSearch; - /// - public string DefaultDescription => - "Searches the public web and reads the pages it finds."; + /// + public string DefaultDescription => + "Searches the public web and reads the pages it finds."; - /// - public AITool Build(ToolConfiguration tool, BuiltinToolPorts ports) => new HostedWebSearchTool(); + /// + public AITool Build(ToolConfiguration tool, BuiltinToolPorts ports) + { + return new HostedWebSearchTool(); + } + } } diff --git a/src/AgentCore.Application/Tools/CachedTool.cs b/src/AgentCore.Application/Tools/CachedTool.cs index 1049cf7f..a7a6771f 100644 --- a/src/AgentCore.Application/Tools/CachedTool.cs +++ b/src/AgentCore.Application/Tools/CachedTool.cs @@ -2,73 +2,73 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Caching.Hybrid; -namespace AgentCore.Application.Tools; - -/// -/// One tool whose answer is served again, for a while, to a repeat of the same arguments. -/// -public sealed class CachedTool : DelegatingAIFunction +namespace AgentCore.Application.Tools { - private const string KeyPrefix = "agentcore:tool:"; - - private static readonly HybridCacheEntryOptions ReadOnly = new() + /// + /// One tool whose answer is served again, for a while, to a repeat of the same arguments. + /// + public sealed class CachedTool : DelegatingAIFunction { - Flags = HybridCacheEntryFlags.DisableUnderlyingData, - }; + private const string KeyPrefix = "agentcore:tool:"; - private readonly HybridCache _cache; + private static readonly HybridCacheEntryOptions ReadOnly = new() + { + Flags = HybridCacheEntryFlags.DisableUnderlyingData, + }; - private readonly HybridCacheEntryOptions _write; + private readonly HybridCache _cache; - /// Creates the wrapper. - /// The tool whose answers are kept. - /// The host's cache. - /// How long one answer is served again. It must be positive. - public CachedTool(AIFunction inner, HybridCache cache, TimeSpan lifetime) - : base(inner) - { - ArgumentNullException.ThrowIfNull(cache); - ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(lifetime, TimeSpan.Zero); + private readonly HybridCacheEntryOptions _write; - _cache = cache; - _write = new HybridCacheEntryOptions { Expiration = lifetime }; - } + /// Creates the wrapper. + /// The tool whose answers are kept. + /// The host's cache. + /// How long one answer is served again. It must be positive. + public CachedTool(AIFunction inner, HybridCache cache, TimeSpan lifetime) + : base(inner) + { + ArgumentNullException.ThrowIfNull(cache); + ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(lifetime, TimeSpan.Zero); - /// - protected override async ValueTask InvokeCoreAsync( - AIFunctionArguments arguments, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(arguments); + _cache = cache; + _write = new HybridCacheEntryOptions { Expiration = lifetime }; + } - var key = CacheKey(arguments); + /// + protected override async ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(arguments); - var kept = await _cache - .GetOrCreateAsync(key, static _ => ValueTask.FromResult(null), ReadOnly, cancellationToken: cancellationToken) - .ConfigureAwait(false); + string key = CacheKey(arguments); - if (kept is not null) - { - return JsonNode.Parse(kept); - } + string? kept = await _cache + .GetOrCreateAsync(key, static _ => ValueTask.FromResult(null), ReadOnly, cancellationToken: cancellationToken) + .ConfigureAwait(false); - var result = await base.InvokeCoreAsync(arguments, cancellationToken).ConfigureAwait(false); + if (kept is not null) + { + return JsonNode.Parse(kept); + } - if (ToolResultJson.ToNode(result) is { } node && !ToolErrorResult.IsError(node)) - { - await _cache.SetAsync(key, node.ToJsonString(), _write, cancellationToken: cancellationToken).ConfigureAwait(false); - } + object? result = await base.InvokeCoreAsync(arguments, cancellationToken).ConfigureAwait(false); - return result; - } + if (ToolResultJson.ToNode(result) is { } node && !ToolErrorResult.IsError(node)) + { + await _cache.SetAsync(key, node.ToJsonString(), _write, cancellationToken: cancellationToken).ConfigureAwait(false); + } - /// The key reads the tool name and the model's arguments, in a fixed order. The side channel () is not part of the call. - private string CacheKey(AIFunctionArguments arguments) - { - var ordered = arguments - .OrderBy(argument => argument.Key, StringComparer.Ordinal) - .Select(argument => new[] { argument.Key, argument.Value }) - .ToArray(); + return result; + } + + /// The key reads the tool name and the model's arguments, in a fixed order. The side channel () is not part of the call. + private string CacheKey(AIFunctionArguments arguments) + { + object?[][] ordered = [.. arguments + .OrderBy(argument => argument.Key, StringComparer.Ordinal) + .Select(argument => new[] { argument.Key, argument.Value })]; - return KeyPrefix + AIJsonUtilities.HashDataToString([Name, ordered], AIJsonUtilities.DefaultOptions); + return KeyPrefix + AIJsonUtilities.HashDataToString([Name, ordered], AIJsonUtilities.DefaultOptions); + } } } diff --git a/src/AgentCore.Application/Tools/DeclaredTool.cs b/src/AgentCore.Application/Tools/DeclaredTool.cs index 10c58ccd..726d6d05 100644 --- a/src/AgentCore.Application/Tools/DeclaredTool.cs +++ b/src/AgentCore.Application/Tools/DeclaredTool.cs @@ -4,99 +4,106 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools; - -/// -/// The base every tool the factory builds shares. -/// -public abstract class DeclaredTool : AIFunction +namespace AgentCore.Application.Tools { - /// The schema a tool advertises when the document declares no parameters:. - private const string NoArgumentsSchema = """{"type":"object","properties":{}}"""; + /// + /// The base every tool the factory builds shares. + /// + public abstract class DeclaredTool : AIFunction + { + /// The schema a tool advertises when the document declares no parameters:. + private const string NoArgumentsSchema = /*lang=json,strict*/ """{"type":"object","properties":{}}"""; - private readonly JsonElement _schema; + private readonly JsonElement _schema; - /// Creates the tool. - /// The declaration the document holds. - protected DeclaredTool(ToolConfiguration tool) - { - ArgumentNullException.ThrowIfNull(tool); + /// Creates the tool. + /// The declaration the document holds. + protected DeclaredTool(ToolConfiguration tool) + { + ArgumentNullException.ThrowIfNull(tool); - Declaration = tool; - _schema = ParseSchema(tool.Parameters?.ToJsonString() ?? NoArgumentsSchema); - } + Declaration = tool; + _schema = ParseSchema(tool.Parameters?.ToJsonString() ?? NoArgumentsSchema); + } - /// Gets the declaration the document holds. - protected ToolConfiguration Declaration { get; } + /// Gets the declaration the document holds. + protected ToolConfiguration Declaration { get; } - /// Gets the tool id the document declares. It is the name the model calls. - public override string Name => Declaration.Id; + /// Gets the tool id the document declares. It is the name the model calls. + public override string Name => Declaration.Id; - /// Gets the description the model reads. - public override string Description => Declaration.Description ?? string.Empty; + /// Gets the description the model reads. + public override string Description => Declaration.Description ?? string.Empty; - /// Gets the raw JSON Schema of the arguments, unchanged. - public override JsonElement JsonSchema => _schema; + /// Gets the raw JSON Schema of the arguments, unchanged. + public override JsonElement JsonSchema => _schema; - /// The entry point. Delegates straight to . - /// The arguments the model filled. - /// Cancels the conversation. - /// Exactly what returned. - protected sealed override async ValueTask InvokeCoreAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(arguments); + /// The entry point. Delegates straight to . + /// The arguments the model filled. + /// Cancels the conversation. + /// Exactly what returned. + protected sealed override async ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(arguments); - return await CallAsync(arguments, cancellationToken).ConfigureAwait(false); - } + return await CallAsync(arguments, cancellationToken).ConfigureAwait(false); + } - /// Runs the tool. - /// The arguments the model filled. - /// Cancels the conversation. - /// The result the model reads. - protected abstract ValueTask CallAsync(AIFunctionArguments arguments, CancellationToken cancellationToken); - - /// Builds the error result of this tool. - /// What went wrong. It never holds a secret value. - /// The result the model reads. - protected JsonObject Failed(string message) => ToolErrorResult.Create(Declaration.Id, message); - - /// Reads one argument as text. - /// The arguments the model filled. - /// The argument name. - /// The text, or when the model filled nothing. - protected static string? ArgumentText(AIFunctionArguments arguments, string name) - { - ArgumentNullException.ThrowIfNull(arguments); - ArgumentNullException.ThrowIfNull(name); + /// Runs the tool. + /// The arguments the model filled. + /// Cancels the conversation. + /// The result the model reads. + protected abstract ValueTask CallAsync(AIFunctionArguments arguments, CancellationToken cancellationToken); - if (!arguments.TryGetValue(name, out var value) || value is null) + /// Builds the error result of this tool. + /// What went wrong. It never holds a secret value. + /// The result the model reads. + protected JsonObject Failed(string message) { - return null; + return ToolErrorResult.Create(Declaration.Id, message); } - return value switch + /// Reads one argument as text. + /// The arguments the model filled. + /// The argument name. + /// The text, or when the model filled nothing. + protected static string? ArgumentText(AIFunctionArguments arguments, string name) { - string text => text, - JsonElement element => element.ValueKind == JsonValueKind.String ? element.GetString() : element.GetRawText(), - JsonValue node when node.TryGetValue(out var text) => text, - JsonNode node => node.ToJsonString(), - IFormattable number => number.ToString(null, CultureInfo.InvariantCulture), - _ => value.ToString(), - }; - } + ArgumentNullException.ThrowIfNull(arguments); + ArgumentNullException.ThrowIfNull(name); + + if (!arguments.TryGetValue(name, out object? value) || value is null) + { + return null; + } + + return value switch + { + string text => text, + JsonElement { ValueKind: JsonValueKind.String } element => element.GetString(), + JsonElement element => element.GetRawText(), + JsonValue node when node.TryGetValue(out string? text) => text, + JsonNode node => node.ToJsonString(), + IFormattable number => number.ToString(null, CultureInfo.InvariantCulture), + _ => value.ToString(), + }; + } - /// Copies every argument into one JSON object. - /// The arguments the model filled. - /// The object a host delegate reads. - protected static JsonObject ArgumentsAsJson(AIFunctionArguments arguments) - => ToolArgumentJson.ToJsonObject(arguments); + /// Copies every argument into one JSON object. + /// The arguments the model filled. + /// The object a host delegate reads. + protected static JsonObject ArgumentsAsJson(AIFunctionArguments arguments) + { + return ToolArgumentJson.ToJsonObject(arguments); + } - /// Reads one JSON Schema into the element the framework advertises. - private static JsonElement ParseSchema(string schema) - { - using var document = JsonDocument.Parse(schema); - return document.RootElement.Clone(); + /// Reads one JSON Schema into the element the framework advertises. + private static JsonElement ParseSchema(string schema) + { + using JsonDocument document = JsonDocument.Parse(schema); + return document.RootElement.Clone(); + } } } diff --git a/src/AgentCore.Application/Tools/Registry/ToolRegistration.cs b/src/AgentCore.Application/Tools/Registry/ToolRegistration.cs index 908ada1b..0774b890 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolRegistration.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolRegistration.cs @@ -1,22 +1,23 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Registry; - -/// -/// One tool a source serves. -/// -/// The name the model calls. It is unique across every source. -/// The sentence the model reads to decide when to call it. -/// -/// Builds the tool. It runs at most once, on the first resolve, and never during a conversation. -/// -/// -/// How long one call may take, or for no deadline of its own. A source sets -/// this when the document gives it one; is what applies it, so -/// every kind that wants a deadline gets the same one implementation and the same message. -/// -public sealed record ToolRegistration( - string Id, - string Description, - Func Materialise, - TimeSpan? CallTimeout = null); +namespace AgentCore.Application.Tools.Registry +{ + /// + /// One tool a source serves. + /// + /// The name the model calls. It is unique across every source. + /// The sentence the model reads to decide when to call it. + /// + /// Builds the tool. It runs at most once, on the first resolve, and never during a conversation. + /// + /// + /// How long one call may take, or for no deadline of its own. A source sets + /// this when the document gives it one; is what applies it, so + /// every kind that wants a deadline gets the same one implementation and the same message. + /// + public sealed record ToolRegistration( + string Id, + string Description, + Func Materialise, + TimeSpan? CallTimeout = null); +} diff --git a/src/AgentCore.Application/Tools/Registry/ToolRegistry.cs b/src/AgentCore.Application/Tools/Registry/ToolRegistry.cs index 2a53e4ba..9dd237d6 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolRegistry.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolRegistry.cs @@ -1,38 +1,42 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Registry; - -/// -/// Every tool the document declares, by id. -/// -public sealed class ToolRegistry +namespace AgentCore.Application.Tools.Registry { - private readonly Dictionary> _tools; + /// + /// Every tool the document declares, by id. + /// + public sealed class ToolRegistry + { + private readonly Dictionary> _tools; - internal ToolRegistry(Dictionary> tools) => _tools = tools; + internal ToolRegistry(Dictionary> tools) + { + _tools = tools; + } - /// Gets every id the sources registered. - public IReadOnlyCollection Ids => _tools.Keys; + /// Gets every id the sources registered. + public IReadOnlyCollection Ids => _tools.Keys; - /// Reports whether one id is registered. - /// The tool id. - /// when a source registered the id. - public bool Contains(string id) - { - ArgumentNullException.ThrowIfNull(id); - return _tools.ContainsKey(id); - } + /// Reports whether one id is registered. + /// The tool id. + /// when a source registered the id. + public bool Contains(string id) + { + ArgumentNullException.ThrowIfNull(id); + return _tools.ContainsKey(id); + } - /// Builds the tool one id names, or returns the one already built. - /// The tool id. - /// The tool. - /// No source registered the id. - public AITool Resolve(string id) - { - ArgumentNullException.ThrowIfNull(id); + /// Builds the tool one id names, or returns the one already built. + /// The tool id. + /// The tool. + /// No source registered the id. + public AITool Resolve(string id) + { + ArgumentNullException.ThrowIfNull(id); - return _tools.TryGetValue(id, out var tool) - ? tool.Value - : throw new KeyNotFoundException($"no tool source registered the tool id '{id}'."); + return _tools.TryGetValue(id, out Lazy? tool) + ? tool.Value + : throw new KeyNotFoundException($"no tool source registered the tool id '{id}'."); + } } } diff --git a/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs b/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs index ec5976c2..690991fb 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolRegistryBuilder.cs @@ -1,130 +1,130 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; -using AgentCore.Application.Tools; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools.Registry; - -/// -/// Asks every source what it serves, and holds the boot rules the answers must pass. -/// -public static class ToolRegistryBuilder +namespace AgentCore.Application.Tools.Registry { - /// Builds the one registry the compile table reads. - /// The sources, asked in order. - /// The document, and what a source resolves against. - /// Cancels the discovery. - /// The registry. - /// - /// Two sources claim one id, the document declares a tool no source serves, or a tool's - /// description resolves to empty. - /// - public static async ValueTask BuildAsync( - IEnumerable sources, - ToolSourceContext context, - CancellationToken cancellationToken = default) + /// + /// Asks every source what it serves, and holds the boot rules the answers must pass. + /// + public static class ToolRegistryBuilder { - ArgumentNullException.ThrowIfNull(sources); - ArgumentNullException.ThrowIfNull(context); + /// Builds the one registry the compile table reads. + /// The sources, asked in order. + /// The document, and what a source resolves against. + /// Cancels the discovery. + /// The registry. + /// + /// Two sources claim one id, the document declares a tool no source serves, or a tool's + /// description resolves to empty. + /// + public static async ValueTask BuildAsync( + IEnumerable sources, + ToolSourceContext context, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(sources); + ArgumentNullException.ThrowIfNull(context); - Dictionary> tools = new(StringComparer.Ordinal); + Dictionary> tools = new(StringComparer.Ordinal); - foreach (var source in sources) - { - if (source is null) + foreach (IToolSource? source in sources) { - throw new ArgumentNullException(nameof(sources)); + if (source is null) + { + throw new ArgumentNullException(nameof(sources)); + } + + IReadOnlyList registrations = await source.ProvideAsync(context, cancellationToken).ConfigureAwait(false); + foreach (ToolRegistration registration in registrations) + { + Add(tools, registration, context); + } } - var registrations = await source.ProvideAsync(context, cancellationToken).ConfigureAwait(false); - foreach (var registration in registrations) - { - Add(tools, registration, context); - } + VerifyEveryDeclarationIsServed(tools, context.Configuration); + + return new ToolRegistry(tools); } - VerifyEveryDeclarationIsServed(tools, context.Configuration); + private static void Add(Dictionary> tools, ToolRegistration registration, ToolSourceContext context) + { + if (string.IsNullOrWhiteSpace(registration.Description)) + { + throw ToolSourceError.Fail( + $"the tool '{registration.Id}' has no description, so the model has nothing to read when it " + + "decides whether to call it. Write a description: on the declaration."); + } - return new ToolRegistry(tools); - } + // Every resolve runs on the single startup flow that compiles the document. Nothing resolves + // once the host is serving, so no request thread can race the Lazy. + Lazy lazy = new(() => Cache(Limit(registration), registration.Id, context), LazyThreadSafetyMode.None); - private static void Add(Dictionary> tools, ToolRegistration registration, ToolSourceContext context) - { - if (string.IsNullOrWhiteSpace(registration.Description)) - { - throw ToolSourceError.Fail( - $"the tool '{registration.Id}' has no description, so the model has nothing to read when it " - + "decides whether to call it. Write a description: on the declaration."); + if (!tools.TryAdd(registration.Id, lazy)) + { + throw ToolSourceError.Fail( + $"two tools claim the id '{registration.Id}'. An id names one tool, so rename one of " + + "them or take one out of the document."); + } } - // Every resolve runs on the single startup flow that compiles the document. Nothing resolves - // once the host is serving, so no request thread can race the Lazy. - Lazy lazy = new(() => Cache(Limit(registration), registration.Id, context), LazyThreadSafetyMode.None); - - if (!tools.TryAdd(registration.Id, lazy)) + /// Builds one tool, with its deadline on it when the source asked for one. + private static AITool Limit(ToolRegistration registration) { - throw ToolSourceError.Fail( - $"two tools claim the id '{registration.Id}'. An id names one tool, so rename one of " - + "them or take one out of the document."); - } - } + AITool tool = registration.Materialise(); - /// Builds one tool, with its deadline on it when the source asked for one. - private static AITool Limit(ToolRegistration registration) - { - var tool = registration.Materialise(); + if (registration.CallTimeout is not { } limit) + { + return tool; + } - if (registration.CallTimeout is not { } limit) - { - return tool; + // A source that asked for a deadline and quietly did not get one is the worst of both: the + // document says the conversation is bounded and nothing bounds it. Only an AIFunction has a conversation to + // put a deadline around, so a source that names one for anything else is wrong about its own + // tool, and says so at boot rather than on a live conversation. + return tool is AIFunction function + ? new TimeLimitedTool(function, limit) + : throw ToolSourceError.Fail( + $"the tool '{registration.Id}' declares a call timeout, but the source built a " + + $"{tool.GetType().Name} rather than an AIFunction, which has no call to time. Take " + + "the timeout off the registration, or serve the tool as an AIFunction."); } - // A source that asked for a deadline and quietly did not get one is the worst of both: the - // document says the conversation is bounded and nothing bounds it. Only an AIFunction has a conversation to - // put a deadline around, so a source that names one for anything else is wrong about its own - // tool, and says so at boot rather than on a live conversation. - return tool is AIFunction function - ? new TimeLimitedTool(function, limit) - : throw ToolSourceError.Fail( - $"the tool '{registration.Id}' declares a call timeout, but the source built a " - + $"{tool.GetType().Name} rather than an AIFunction, which has no call to time. Take " - + "the timeout off the registration, or serve the tool as an AIFunction."); - } + /// Wraps one tool in the cache when its declaration asks for one and the host has one. + private static AITool Cache(AITool tool, string id, ToolSourceContext context) + { + ToolConfiguration? declared = context.Configuration.Tools.FirstOrDefault(entry => string.Equals(entry.Id, id, StringComparison.Ordinal)); - /// Wraps one tool in the cache when its declaration asks for one and the host has one. - private static AITool Cache(AITool tool, string id, ToolSourceContext context) - { - var declared = context.Configuration.Tools.FirstOrDefault(entry => string.Equals(entry.Id, id, StringComparison.Ordinal)); + if (declared?.CacheSeconds is not { } seconds || context.Cache is not { } cache) + { + return tool; + } - if (declared?.CacheSeconds is not { } seconds || context.Cache is not { } cache) - { - return tool; + return tool is AIFunction function + ? new CachedTool(function, cache, TimeSpan.FromSeconds(seconds)) + : throw ToolSourceError.Fail( + $"the tool '{id}' declares cacheSeconds, but the source built a {tool.GetType().Name} " + + "rather than an AIFunction, which has no call to cache. Take cacheSeconds off the " + + "declaration, or serve the tool as an AIFunction."); } - return tool is AIFunction function - ? new CachedTool(function, cache, TimeSpan.FromSeconds(seconds)) - : throw ToolSourceError.Fail( - $"the tool '{id}' declares cacheSeconds, but the source built a {tool.GetType().Name} " - + "rather than an AIFunction, which has no call to cache. Take cacheSeconds off the " - + "declaration, or serve the tool as an AIFunction."); - } - - private static void VerifyEveryDeclarationIsServed( - Dictionary> tools, AgentCoreConfiguration configuration) - { - foreach (var declared in configuration.Tools) + private static void VerifyEveryDeclarationIsServed( + Dictionary> tools, AgentCoreConfiguration configuration) { - // A kind: agent tool reaches no source. The compile table builds it, because it needs - // the inner agent that only exists once that agent has compiled. - if (declared.Kind == ToolKind.Agent || tools.ContainsKey(declared.Id)) + foreach (ToolConfiguration declared in configuration.Tools) { - continue; + // A kind: agent tool reaches no source. The compile table builds it, because it needs + // the inner agent that only exists once that agent has compiled. + if (declared.Kind == ToolKind.Agent || tools.ContainsKey(declared.Id)) + { + continue; + } + + throw ToolSourceError.Fail( + $"the tool '{declared.Id}' is kind: {declared.Kind.ToString().ToLowerInvariant()}, and no tool " + + "source serves it. Register a source for that kind before the document compiles."); } - - throw ToolSourceError.Fail( - $"the tool '{declared.Id}' is kind: {declared.Kind.ToString().ToLowerInvariant()}, and no tool " - + "source serves it. Register a source for that kind before the document compiles."); } } } diff --git a/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs b/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs index 4c244a29..a5a6646f 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolSourceContext.cs @@ -1,23 +1,26 @@ using AgentCore.Application.Configuration.Schema; using Microsoft.Extensions.Caching.Hybrid; -namespace AgentCore.Application.Tools.Registry; - -/// -/// What a tool source is handed when it is asked what it serves. -/// -/// The loaded document. A source reads the declarations that are its own. -public sealed record ToolSourceContext(AgentCoreConfiguration Configuration) +namespace AgentCore.Application.Tools.Registry { /// - /// Gets the cache a cacheSeconds: tool reads through, or when - /// the host set none, in which case every call reaches the tool. + /// What a tool source is handed when it is asked what it serves. /// - public HybridCache? Cache { get; init; } + /// The loaded document. A source reads the declarations that are its own. + public sealed record ToolSourceContext(AgentCoreConfiguration Configuration) + { + /// + /// Gets the cache a cacheSeconds: tool reads through, or when + /// the host set none, in which case every call reaches the tool. + /// + public HybridCache? Cache { get; init; } - /// Every declaration of one kind, in document order. - /// The kind this source serves. - /// The declarations. A source that serves a kind nothing declares gets none. - public IEnumerable DeclarationsOf(ToolKind kind) - => Configuration.Tools.Where(tool => tool.Kind == kind); + /// Every declaration of one kind, in document order. + /// The kind this source serves. + /// The declarations. A source that serves a kind nothing declares gets none. + public IEnumerable DeclarationsOf(ToolKind kind) + { + return Configuration.Tools.Where(tool => tool.Kind == kind); + } + } } diff --git a/src/AgentCore.Application/Tools/Registry/ToolSourceError.cs b/src/AgentCore.Application/Tools/Registry/ToolSourceError.cs index 9aa731aa..c6266933 100644 --- a/src/AgentCore.Application/Tools/Registry/ToolSourceError.cs +++ b/src/AgentCore.Application/Tools/Registry/ToolSourceError.cs @@ -1,25 +1,28 @@ using AgentCore.Application.Configuration.Parsing; -namespace AgentCore.Application.Tools.Registry; - -/// -/// The failure a tool source throws when it cannot serve a declaration. -/// -/// -/// Every one of these points at /tools and reports -/// . Sources share this so a host reading the -/// error gets the same pointer and the same check whichever source threw it. -/// -public static class ToolSourceError +namespace AgentCore.Application.Tools.Registry { - /// Builds the failure one message describes. - /// What is wrong, and what the document should say instead. - /// The exception to throw. - public static ConfigurationLoadException Fail(string message) - => new(new ConfigurationError + /// + /// The failure a tool source throws when it cannot serve a declaration. + /// + /// + /// Every one of these points at /tools and reports + /// . Sources share this so a host reading the + /// error gets the same pointer and the same check whichever source threw it. + /// + public static class ToolSourceError + { + /// Builds the failure one message describes. + /// What is wrong, and what the document should say instead. + /// The exception to throw. + public static ConfigurationLoadException Fail(string message) { - Pointer = "/tools", - Message = message, - Check = ConfigurationCheck.ReferenceResolution, - }); + return new(new ConfigurationError + { + Pointer = "/tools", + Message = message, + Check = ConfigurationCheck.ReferenceResolution, + }); + } + } } diff --git a/src/AgentCore.Application/Tools/TimeLimitedTool.cs b/src/AgentCore.Application/Tools/TimeLimitedTool.cs index 3723772e..3f3d4e18 100644 --- a/src/AgentCore.Application/Tools/TimeLimitedTool.cs +++ b/src/AgentCore.Application/Tools/TimeLimitedTool.cs @@ -1,49 +1,52 @@ using System.Text.Json.Nodes; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools; - -/// -/// One tool, with a deadline on every call. -/// -public sealed class TimeLimitedTool : DelegatingAIFunction +namespace AgentCore.Application.Tools { - private readonly TimeSpan _limit; - - /// Creates the wrapper. - /// The tool being limited. - /// How long one call may take. It must be positive. - public TimeLimitedTool(AIFunction inner, TimeSpan limit) - : base(inner) + /// + /// One tool, with a deadline on every call. + /// + public sealed class TimeLimitedTool : DelegatingAIFunction { - ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(limit, TimeSpan.Zero); + private readonly TimeSpan _limit; - _limit = limit; - } - - /// - protected override async ValueTask InvokeCoreAsync( - AIFunctionArguments arguments, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(arguments); + /// Creates the wrapper. + /// The tool being limited. + /// How long one call may take. It must be positive. + public TimeLimitedTool(AIFunction inner, TimeSpan limit) + : base(inner) + { + ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(limit, TimeSpan.Zero); - using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - deadline.CancelAfter(_limit); + _limit = limit; + } - try + /// + protected override async ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, CancellationToken cancellationToken) { - return await base.InvokeCoreAsync(arguments, deadline.Token).ConfigureAwait(false); + ArgumentNullException.ThrowIfNull(arguments); + + using CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + deadline.CancelAfter(_limit); + + try + { + return await base.InvokeCoreAsync(arguments, deadline.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested && !cancellationToken.IsCancellationRequested) + { + // The turn itself being cancelled is not this: that token is the caller's, and it is left + // to propagate. Only this wrapper's own deadline becomes a result. + return Failed(); + } } - catch (OperationCanceledException) when (deadline.IsCancellationRequested && !cancellationToken.IsCancellationRequested) + + private JsonObject Failed() { - // The turn itself being cancelled is not this: that token is the caller's, and it is left - // to propagate. Only this wrapper's own deadline becomes a result. - return Failed(); + return ToolErrorResult.Create( + Name, + $"the tool did not answer within {_limit.TotalSeconds:0.###}s and was given up on."); } } - - private JsonObject Failed() - => ToolErrorResult.Create( - Name, - $"the tool did not answer within {_limit.TotalSeconds:0.###}s and was given up on."); } diff --git a/src/AgentCore.Application/Tools/ToolArgumentJson.cs b/src/AgentCore.Application/Tools/ToolArgumentJson.cs index 52ff934b..5bb83500 100644 --- a/src/AgentCore.Application/Tools/ToolArgumentJson.cs +++ b/src/AgentCore.Application/Tools/ToolArgumentJson.cs @@ -1,42 +1,46 @@ using System.Text.Json; using System.Text.Json.Nodes; -namespace AgentCore.Application.Tools; - -/// -/// The one rule for carrying what the model filled into JSON. -/// -public static class ToolArgumentJson +namespace AgentCore.Application.Tools { - /// Copies every argument into one JSON object. - /// The arguments the model filled. - /// The object, with one property per argument. - public static JsonObject ToJsonObject(IEnumerable> arguments) + /// + /// The one rule for carrying what the model filled into JSON. + /// + public static class ToolArgumentJson { - ArgumentNullException.ThrowIfNull(arguments); - - JsonObject payload = []; - foreach (var argument in arguments) + /// Copies every argument into one JSON object. + /// The arguments the model filled. + /// The object, with one property per argument. + public static JsonObject ToJsonObject(IEnumerable> arguments) { - payload[argument.Key] = ToNode(argument.Value); + ArgumentNullException.ThrowIfNull(arguments); + + JsonObject payload = []; + foreach (KeyValuePair argument in arguments) + { + payload[argument.Key] = ToNode(argument.Value); + } + + return payload; } - return payload; + /// Carries one tool argument into a JSON node. + /// The value the model filled, in whatever type it arrived as. + /// The node, or when the model filled nothing. + internal static JsonNode? ToNode(object? value) + { + return value switch + { + null => null, + JsonNode node => node.DeepClone(), + JsonElement element => JsonNode.Parse(element.GetRawText()), + string text => JsonValue.Create(text), + bool flag => JsonValue.Create(flag), + int number => JsonValue.Create(number), + long number => JsonValue.Create(number), + double number => JsonValue.Create(number), + decimal number => JsonValue.Create(number), + _ => JsonValue.Create(value.ToString()), + }; + } } - - /// Carries one tool argument into a JSON node. - /// The value the model filled, in whatever type it arrived as. - /// The node, or when the model filled nothing. - internal static JsonNode? ToNode(object? value) => value switch - { - null => null, - JsonNode node => node.DeepClone(), - JsonElement element => JsonNode.Parse(element.GetRawText()), - string text => JsonValue.Create(text), - bool flag => JsonValue.Create(flag), - int number => JsonValue.Create(number), - long number => JsonValue.Create(number), - double number => JsonValue.Create(number), - decimal number => JsonValue.Create(number), - _ => JsonValue.Create(value.ToString()), - }; } diff --git a/src/AgentCore.Application/Tools/ToolCallNames.cs b/src/AgentCore.Application/Tools/ToolCallNames.cs index e6ba8fd6..10db3dd3 100644 --- a/src/AgentCore.Application/Tools/ToolCallNames.cs +++ b/src/AgentCore.Application/Tools/ToolCallNames.cs @@ -1,35 +1,36 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools; - -/// -/// Pairs each tool result with the name of the tool that was called. -/// -/// -/// A carries only the id of the call it answers, so anything -/// that reads results in order has to remember the name off the -/// that came before it. One instance covers one run of contents and is not thread-safe. -/// -public sealed class ToolCallNames +namespace AgentCore.Application.Tools { - private readonly Dictionary _byCallId = new(StringComparer.Ordinal); - - /// Remembers the tool one call names. - /// The call half. - public void Called(FunctionCallContent call) + /// + /// Pairs each tool result with the name of the tool that was called. + /// + /// + /// A carries only the id of the call it answers, so anything + /// that reads results in order has to remember the name off the + /// that came before it. One instance covers one run of contents and is not thread-safe. + /// + public sealed class ToolCallNames { - ArgumentNullException.ThrowIfNull(call); + private readonly Dictionary _byCallId = new(StringComparer.Ordinal); - _byCallId[call.CallId] = call.Name; - } + /// Remembers the tool one call names. + /// The call half. + public void Called(FunctionCallContent call) + { + ArgumentNullException.ThrowIfNull(call); - /// Reads the tool one result answers for. - /// The result half. - /// The tool name, or when no call before it named one. - public string? Of(FunctionResultContent result) - { - ArgumentNullException.ThrowIfNull(result); + _byCallId[call.CallId] = call.Name; + } + + /// Reads the tool one result answers for. + /// The result half. + /// The tool name, or when no call before it named one. + public string? Of(FunctionResultContent result) + { + ArgumentNullException.ThrowIfNull(result); - return _byCallId.TryGetValue(result.CallId, out var name) ? name : null; + return _byCallId.TryGetValue(result.CallId, out string? name) ? name : null; + } } } diff --git a/src/AgentCore.Application/Tools/ToolCallScope.cs b/src/AgentCore.Application/Tools/ToolCallScope.cs index 5e8b1b49..faad83c5 100644 --- a/src/AgentCore.Application/Tools/ToolCallScope.cs +++ b/src/AgentCore.Application/Tools/ToolCallScope.cs @@ -1,8 +1,9 @@ -namespace AgentCore.Application.Tools; - -/// The conversation a bound tool runs in. A binding declares a parameter of this type to receive it; the model never sees that parameter. -/// The conversation the turn belongs to. -/// The zero-based index of the turn now running. -/// The stage the conversation's state machine holds. Empty when the document declares no policy. -/// The conversation's folder on disk, or when the host bound no workspace root. -public sealed record ToolCallScope(string ConversationId, int TurnIndex, string Stage, string? Workspace = null); +namespace AgentCore.Application.Tools +{ + /// The conversation a bound tool runs in. A binding declares a parameter of this type to receive it; the model never sees that parameter. + /// The conversation the turn belongs to. + /// The zero-based index of the turn now running. + /// The stage the conversation's state machine holds. Empty when the document declares no policy. + /// The conversation's folder on disk, or when the host bound no workspace root. + public sealed record ToolCallScope(string ConversationId, int TurnIndex, string Stage, string? Workspace = null); +} diff --git a/src/AgentCore.Application/Tools/ToolErrorResult.cs b/src/AgentCore.Application/Tools/ToolErrorResult.cs index ed14ea00..01c68926 100644 --- a/src/AgentCore.Application/Tools/ToolErrorResult.cs +++ b/src/AgentCore.Application/Tools/ToolErrorResult.cs @@ -1,57 +1,60 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Tools; - -/// -/// The one shape a failing tool returns. -/// -/// -/// -/// Section 8.7: a tool returns an error result and does not throw. A 500 answer, a timeout, a file -/// that is not there, and a host delegate that throws all land here, because the model reads the -/// result and decides what to say next. An exception would end the turn instead, and the caller is -/// on the telephone. -/// -/// -/// The object holds three fields: error is always , tool names -/// the declared tool id, and message says what went wrong in one sentence. -/// -/// -public static class ToolErrorResult +namespace AgentCore.Application.Tools { - /// The property that marks a result as a failure. - public const string ErrorProperty = "error"; + /// + /// The one shape a failing tool returns. + /// + /// + /// + /// Section 8.7: a tool returns an error result and does not throw. A 500 answer, a timeout, a file + /// that is not there, and a host delegate that throws all land here, because the model reads the + /// result and decides what to say next. An exception would end the turn instead, and the caller is + /// on the telephone. + /// + /// + /// The object holds three fields: error is always , tool names + /// the declared tool id, and message says what went wrong in one sentence. + /// + /// + public static class ToolErrorResult + { + /// The property that marks a result as a failure. + public const string ErrorProperty = "error"; - /// The property that names the declared tool. - public const string ToolProperty = "tool"; + /// The property that names the declared tool. + public const string ToolProperty = "tool"; - /// The property that says what went wrong. - public const string MessageProperty = "message"; + /// The property that says what went wrong. + public const string MessageProperty = "message"; - /// Builds the result a failing tool returns. - /// The declared tool id. - /// What went wrong. It never holds a secret value. - /// The result the model reads. - public static JsonObject Create(string tool, string message) - { - ArgumentNullException.ThrowIfNull(tool); - ArgumentNullException.ThrowIfNull(message); + /// Builds the result a failing tool returns. + /// The declared tool id. + /// What went wrong. It never holds a secret value. + /// The result the model reads. + public static JsonObject Create(string tool, string message) + { + ArgumentNullException.ThrowIfNull(tool); + ArgumentNullException.ThrowIfNull(message); + + return new JsonObject + { + [ErrorProperty] = true, + [ToolProperty] = tool, + [MessageProperty] = message, + }; + } - return new JsonObject + /// Reports whether one tool result is a failure. + /// The result the tool returned. + /// when the result carries the error mark. + public static bool IsError(JsonNode? result) { - [ErrorProperty] = true, - [ToolProperty] = tool, - [MessageProperty] = message, - }; + return result is JsonObject map + && map.TryGetPropertyValue(ErrorProperty, out JsonNode? mark) + && mark is JsonValue value + && value.TryGetValue(out bool failed) + && failed; + } } - - /// Reports whether one tool result is a failure. - /// The result the tool returned. - /// when the result carries the error mark. - public static bool IsError(JsonNode? result) - => result is JsonObject map - && map.TryGetPropertyValue(ErrorProperty, out var mark) - && mark is JsonValue value - && value.TryGetValue(out var failed) - && failed; } diff --git a/src/AgentCore.Application/Tools/ToolResultJson.cs b/src/AgentCore.Application/Tools/ToolResultJson.cs index e0f50cca..a665e4df 100644 --- a/src/AgentCore.Application/Tools/ToolResultJson.cs +++ b/src/AgentCore.Application/Tools/ToolResultJson.cs @@ -2,56 +2,60 @@ using System.Text.Json.Nodes; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tools; - -/// -/// The one rule for reading what a tool answered. -/// -/// -/// A tool result has no declared shape. It arrives as a node, as an element, as text that may or -/// may not be JSON, or as an object of the tool's own. Everything that reads a result reads it -/// through here, so no two readers disagree about what one answer means. -/// -public static class ToolResultJson +namespace AgentCore.Application.Tools { - /// Carries one tool result into a JSON node. - /// Whatever the tool returned. - /// The node tree, or when the tool returned nothing. - public static JsonNode? ToNode(object? value) => value switch + /// + /// The one rule for reading what a tool answered. + /// + /// + /// A tool result has no declared shape. It arrives as a node, as an element, as text that may or + /// may not be JSON, or as an object of the tool's own. Everything that reads a result reads it + /// through here, so no two readers disagree about what one answer means. + /// + public static class ToolResultJson { - null => null, - JsonNode node => node.DeepClone(), - - // A tool result has no declared shape. A tool that answers with a JSON document as one - // string still reaches its slot, and a tool that answers with prose reads as that prose. - JsonElement element when element.ValueKind is JsonValueKind.String - => ParseOrText(element.GetString() ?? string.Empty), - JsonElement element => JsonNode.Parse(element.GetRawText()), - string text => ParseOrText(text), - bool flag => JsonValue.Create(flag), - int number => JsonValue.Create(number), - long number => JsonValue.Create(number), - double number => JsonValue.Create(number), - decimal number => JsonValue.Create(number), + /// Carries one tool result into a JSON node. + /// Whatever the tool returned. + /// The node tree, or when the tool returned nothing. + public static JsonNode? ToNode(object? value) + { + return value switch + { + null => null, + JsonNode node => node.DeepClone(), - // A tool may answer with an object of its own. Its type name is not its answer, so it is - // serialised the same way the model was shown it. - _ => JsonSerializer.SerializeToNode(value, value.GetType(), AIJsonUtilities.DefaultOptions), - }; + // A tool result has no declared shape. A tool that answers with a JSON document as one + // string still reaches its slot, and a tool that answers with prose reads as that prose. + JsonElement element when element.ValueKind is JsonValueKind.String + => ParseOrText(element.GetString() ?? string.Empty), + JsonElement element => JsonNode.Parse(element.GetRawText()), + string text => ParseOrText(text), + bool flag => JsonValue.Create(flag), + int number => JsonValue.Create(number), + long number => JsonValue.Create(number), + double number => JsonValue.Create(number), + decimal number => JsonValue.Create(number), - /// Reads one string as JSON, and falls back to the string itself. - /// The text the tool returned. - /// The node tree. - private static JsonNode? ParseOrText(string text) - { - try - { - return JsonNode.Parse(text); + // A tool may answer with an object of its own. Its type name is not its answer, so it is + // serialised the same way the model was shown it. + _ => JsonSerializer.SerializeToNode(value, value.GetType(), AIJsonUtilities.DefaultOptions), + }; } - catch (JsonException) + + /// Reads one string as JSON, and falls back to the string itself. + /// The text the tool returned. + /// The node tree. + private static JsonNode? ParseOrText(string text) { - // Section 8.7: a tool result has no declared shape, and a tool never drops a turn. - return JsonValue.Create(text); + try + { + return JsonNode.Parse(text); + } + catch (JsonException) + { + // Section 8.7: a tool result has no declared shape, and a tool never drops a turn. + return JsonValue.Create(text); + } } } } diff --git a/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs b/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs index 51e94b9c..832a521d 100644 --- a/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs +++ b/src/AgentCore.Application/Transcript/AgentCoreChatHistoryProvider.cs @@ -8,382 +8,379 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.Application.Transcript; - -/// -/// Reports one store 1 write that was dropped, so the conversation can raise a diagnostic for it. -/// -internal delegate void TranscriptWriteDropped(int turnIndex, Exception exception); - -/// -/// Store 1: the words of a conversation, held for the session by the provider and written through to a backing store. -/// -internal sealed class AgentCoreChatHistoryProvider : ChatHistoryProvider +namespace AgentCore.Application.Transcript { - private readonly ConditionalWeakTable _gates = []; - - private readonly IConversationStore _store; - - private readonly ILogger _logger; - - /// Creates the provider over a backing store. - public AgentCoreChatHistoryProvider(IConversationStore? store = null, ILogger? logger = null) - { - _store = store ?? new InMemoryConversationStore(); - - _logger = logger ?? NullLogger.Instance; - } + /// + /// Reports one store 1 write that was dropped, so the conversation can raise a diagnostic for it. + /// + internal delegate void TranscriptWriteDropped(int turnIndex, Exception exception); /// - /// Opens a conversation on one session: names it, reads back what it already said, and says where a - /// dropped write is reported. + /// Store 1: the words of a conversation, held for the session by the provider and written through to a backing store. /// - /// The session this conversation runs on. - /// The conversation being opened. - /// - /// What store 1 already holds for this conversation, which is empty for a conversation that is new. A second - /// session of one conversation is handed the first session's words here, and nowhere else. - /// - /// Where a dropped store 1 write is reported, if anywhere. - /// - /// How far the conversation had got, from store 0's own counters — or the zero marks of a conversation that has - /// never spoken. The words cannot say this on their own, because an edit deletes the rows that - /// would otherwise answer for it. - /// - /// The index the next turn of this conversation takes. - public int BeginConversation( - AgentSession session, - string conversationId, - IReadOnlyList spoken, - TranscriptWriteDropped? report = null, - TranscriptMarks marks = default) + /// Creates the provider over a backing store. + internal sealed class AgentCoreChatHistoryProvider(IConversationStore? store = null, ILogger? logger = null) : ChatHistoryProvider { - ArgumentNullException.ThrowIfNull(session); - ArgumentException.ThrowIfNullOrEmpty(conversationId); - ArgumentNullException.ThrowIfNull(spoken); + private readonly ConditionalWeakTable _gates = []; + + private readonly IConversationStore _store = store ?? new InMemoryConversationStore(); + + private readonly ILogger _logger = logger ?? NullLogger.Instance; + + /// + /// Opens a conversation on one session: names it, reads back what it already said, and says where a + /// dropped write is reported. + /// + /// The session this conversation runs on. + /// The conversation being opened. + /// + /// What store 1 already holds for this conversation, which is empty for a conversation that is new. A second + /// session of one conversation is handed the first session's words here, and nowhere else. + /// + /// Where a dropped store 1 write is reported, if anywhere. + /// + /// How far the conversation had got, from store 0's own counters — or the zero marks of a conversation that has + /// never spoken. The words cannot say this on their own, because an edit deletes the rows that + /// would otherwise answer for it. + /// + /// The index the next turn of this conversation takes. + public int BeginConversation( + AgentSession session, + string conversationId, + IReadOnlyList spoken, + TranscriptWriteDropped? report = null, + TranscriptMarks marks = default) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentException.ThrowIfNullOrEmpty(conversationId); + ArgumentNullException.ThrowIfNull(spoken); - return UnderLock( - session, - (transcript, gate) => - { - transcript.ConversationId = conversationId; - gate.Dropped = report; - return transcript.Resume(spoken, marks); - }); - } + return UnderLock( + session, + (transcript, gate) => + { + transcript.ConversationId = conversationId; + gate.Dropped = report; + return transcript.Resume(spoken, marks); + }); + } - /// Reads the ordinal the session expects the conversation's next row to take. - /// The session this conversation runs on. - /// - /// The next free ordinal as the session counts it. Equal to store 0's own counter unless a row was - /// written by someone else, or one of this session's own writes was dropped. - /// - public int NextOrdinal(AgentSession session) - { - ArgumentNullException.ThrowIfNull(session); + /// Reads the ordinal the session expects the conversation's next row to take. + /// The session this conversation runs on. + /// + /// The next free ordinal as the session counts it. Equal to store 0's own counter unless a row was + /// written by someone else, or one of this session's own writes was dropped. + /// + public int NextOrdinal(AgentSession session) + { + ArgumentNullException.ThrowIfNull(session); - return UnderLock(session, static transcript => transcript.NextOrdinal); - } + return UnderLock(session, static transcript => transcript.NextOrdinal); + } - /// Replaces the conversation's live history with what store 1 holds. - /// The session this conversation runs on. - /// The rows store 1 read for the session, as takes them. - /// The next free ordinal of the conversation, from store 0's own counter. - public void Resync(AgentSession session, IReadOnlyList rows, int nextOrdinal) - { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(rows); + /// Replaces the conversation's live history with what store 1 holds. + /// The session this conversation runs on. + /// The rows store 1 read for the session, as takes them. + /// The next free ordinal of the conversation, from store 0's own counter. + public void Resync(AgentSession session, IReadOnlyList rows, int nextOrdinal) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(rows); - UnderLock( - session, - transcript => - { - transcript.Resync(rows, nextOrdinal); - return true; - }); - } + _ = UnderLock( + session, + transcript => + { + transcript.Resync(rows, nextOrdinal); + return true; + }); + } - /// Reads the summary the session holds in place of its oldest rows, or when every row is live. - /// The session this conversation runs on. - public ChatMessage? Summary(AgentSession session) - { - ArgumentNullException.ThrowIfNull(session); + /// Reads the summary the session holds in place of its oldest rows, or when every row is live. + /// The session this conversation runs on. + public ChatMessage? Summary(AgentSession session) + { + ArgumentNullException.ThrowIfNull(session); - return UnderLock(session, static transcript => transcript.Summary?.Message); - } + return UnderLock(session, static transcript => transcript.Summary?.Message); + } - /// Names where a compaction of the conversation would reach, and the revision it reads. - /// The session this conversation runs on. - /// The floor, or when the conversation holds nothing to compact. - public TranscriptFloor? Floor(AgentSession session) - { - ArgumentNullException.ThrowIfNull(session); + /// Names where a compaction of the conversation would reach, and the revision it reads. + /// The session this conversation runs on. + /// The floor, or when the conversation holds nothing to compact. + public TranscriptFloor? Floor(AgentSession session) + { + ArgumentNullException.ThrowIfNull(session); - return UnderLock(session, static transcript => transcript.Floor()); - } + return UnderLock(session, static transcript => transcript.Floor()); + } - /// - /// Puts one summary in place of every row at or below , unless the - /// words moved since was read, and queues the summary's row for store 1 ahead - /// of the turn's own words. - /// - /// The session this conversation runs on. - /// The message that now speaks for those rows. - /// The last ordinal it speaks for. - /// The revision reported. - /// when the summary now stands. - public bool Compact(AgentSession session, ChatMessage summary, int coversUpTo, int revision) - { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(summary); + /// + /// Puts one summary in place of every row at or below , unless the + /// words moved since was read, and queues the summary's row for store 1 ahead + /// of the turn's own words. + /// + /// The session this conversation runs on. + /// The message that now speaks for those rows. + /// The last ordinal it speaks for. + /// The revision reported. + /// when the summary now stands. + public bool Compact(AgentSession session, ChatMessage summary, int coversUpTo, int revision) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(summary); - return UnderLock( - session, - (transcript, gate) => - { - if (transcript.Compact(summary, coversUpTo, revision) is not { } row) + return UnderLock( + session, + (transcript, gate) => { - return false; - } - - ConversationMessageDraft draft = new(row.TurnIndex, row.Content, row.MessageId) { CoversUpTo = row.CoversUpTo }; - gate.Enqueue(() => new ValueTask(_store.AppendAsync( - transcript.ConversationId, [draft], state: null, CancellationToken.None).AsTask())); - - return true; - }); - } - - /// - /// Whether can cut an edit hanging off one message from what the session - /// holds. It cannot when the cut would reach a row the summary stands in for; every row must be read back first. - /// - /// The session this conversation runs on. - /// The message the edit hangs off, or for the whole conversation. - public bool CanTruncateFrom(AgentSession session, string? parentMessageId) - { - ArgumentNullException.ThrowIfNull(session); + if (transcript.Compact(summary, coversUpTo, revision) is not { } row) + { + return false; + } - return UnderLock(session, transcript => transcript.CanTruncateFrom(parentMessageId)); - } + ConversationMessageDraft draft = new(row.TurnIndex, row.Content, row.MessageId) { CoversUpTo = row.CoversUpTo }; + gate.Enqueue(() => new ValueTask(_store.AppendAsync( + transcript.ConversationId, [draft], state: null, CancellationToken.None).AsTask())); - /// - /// Stamps the turn the next run belongs to. - /// - public void BeginTurn(AgentSession session, int turnIndex) - { - ArgumentNullException.ThrowIfNull(session); + return true; + }); + } - UnderLock( - session, - transcript => - { - transcript.BeginTurn(turnIndex); - return true; - }); - } + /// + /// Whether can cut an edit hanging off one message from what the session + /// holds. It cannot when the cut would reach a row the summary stands in for; every row must be read back first. + /// + /// The session this conversation runs on. + /// The message the edit hangs off, or for the whole conversation. + public bool CanTruncateFrom(AgentSession session, string? parentMessageId) + { + ArgumentNullException.ThrowIfNull(session); - /// - /// Reads the conversation as the model sees it: the summary first, when one stands, then every live row, oldest first. - /// - public IReadOnlyList Read(AgentSession session) - { - ArgumentNullException.ThrowIfNull(session); + return UnderLock(session, transcript => transcript.CanTruncateFrom(parentMessageId)); + } - return UnderLock(session, static transcript => transcript.Read()); - } + /// + /// Stamps the turn the next run belongs to. + /// + public void BeginTurn(AgentSession session, int turnIndex) + { + ArgumentNullException.ThrowIfNull(session); - /// Adds one finished turn's messages to the conversation, and the state that follows them. - /// The session this conversation runs on. - /// The messages the turn produced. - /// - /// The state to store beside the words, or to store none. A value, read - /// by the caller before it conversations: everything the turn writes to the state document — the clock - /// fields, the counters, the stage and whether the machine finished — is already final when the - /// caller enters its commit lock, and the late barge-in path that runs after this conversation amends - /// the record of the turn without touching any of it. So there is nothing later to wait for. - /// - /// - /// What the caller calls the first of these messages, or to name it in the - /// append. Only the first: the rest are this conversation's own words, which no caller had a name for. - /// - /// - /// The name the last of these messages was written under, so the caller can be told what to hang - /// its next edit off. It is only when nothing was written. - /// - public string? AppendTurn( - AgentSession session, - IReadOnlyList messages, - ConversationSessionState? state = null, - string? firstMessageId = null) - { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(messages); + _ = UnderLock( + session, + transcript => + { + transcript.BeginTurn(turnIndex); + return true; + }); + } - if (messages.Count == 0) + /// + /// Reads the conversation as the model sees it: the summary first, when one stands, then every live row, oldest first. + /// + public IReadOnlyList Read(AgentSession session) { - return null; + ArgumentNullException.ThrowIfNull(session); + + return UnderLock(session, static transcript => transcript.Read()); } - return UnderLock( - session, - (transcript, gate) => - { - var rows = transcript.Append(messages, firstMessageId); + /// Adds one finished turn's messages to the conversation, and the state that follows them. + /// The session this conversation runs on. + /// The messages the turn produced. + /// + /// The state to store beside the words, or to store none. A value, read + /// by the caller before it conversations: everything the turn writes to the state document — the clock + /// fields, the counters, the stage and whether the machine finished — is already final when the + /// caller enters its commit lock, and the late barge-in path that runs after this conversation amends + /// the record of the turn without touching any of it. So there is nothing later to wait for. + /// + /// + /// What the caller calls the first of these messages, or to name it in the + /// append. Only the first: the rest are this conversation's own words, which no caller had a name for. + /// + /// + /// The name the last of these messages was written under, so the caller can be told what to hang + /// its next edit off. It is only when nothing was written. + /// + public string? AppendTurn( + AgentSession session, + IReadOnlyList messages, + ConversationSessionState? state = null, + string? firstMessageId = null) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(messages); + + return messages.Count == 0 + ? null + : UnderLock( + session, + (transcript, gate) => + { + IReadOnlyList rows = transcript.Append(messages, firstMessageId); - var drafts = rows - .Select(row => new ConversationMessageDraft(row.TurnIndex, row.Content, row.MessageId)) - .ToArray(); + ConversationMessageDraft[] drafts = [.. rows.Select(row => new ConversationMessageDraft(row.TurnIndex, row.Content, row.MessageId))]; - gate.Enqueue(() => new ValueTask(_store.AppendAsync( - transcript.ConversationId, drafts, state, CancellationToken.None).AsTask())); - return rows[^1].MessageId; - }); - } + gate.Enqueue(() => new ValueTask(_store.AppendAsync( + transcript.ConversationId, drafts, state, CancellationToken.None).AsTask())); + return rows[^1].MessageId; + }); + } - /// Withdraws everything the conversation said after one message, because a caller replaced it. - /// The session this conversation runs on. - /// - /// The message the caller's new words hang off. Everything after it goes. Pass - /// to withdraw the whole conversation, which is what an edit of its first message - /// asks for. - /// - /// - /// The turns the withdrawal took, or when nothing went. Nothing goes when - /// the conversation holds no message of that name — a caller naming a message this host never stored — - /// and the turn then runs as a plain new turn. - /// - /// - /// The cut reaches a row the summary stands in for. Ask first, and read every - /// row back when it says no. - /// - public WithdrawnTurns? TruncateFrom(AgentSession session, string? parentMessageId) - { - ArgumentNullException.ThrowIfNull(session); + /// Withdraws everything the conversation said after one message, because a caller replaced it. + /// The session this conversation runs on. + /// + /// The message the caller's new words hang off. Everything after it goes. Pass + /// to withdraw the whole conversation, which is what an edit of its first message + /// asks for. + /// + /// + /// The turns the withdrawal took, or when nothing went. Nothing goes when + /// the conversation holds no message of that name — a caller naming a message this host never stored — + /// and the turn then runs as a plain new turn. + /// + /// + /// The cut reaches a row the summary stands in for. Ask first, and read every + /// row back when it says no. + /// + public WithdrawnTurns? TruncateFrom(AgentSession session, string? parentMessageId) + { + ArgumentNullException.ThrowIfNull(session); - return UnderLock( - session, - (transcript, gate) => - { - int from; - if (parentMessageId is null) - { - from = 0; - } - else if (transcript.OrdinalOf(parentMessageId) is { } parent) + return UnderLock( + session, + (transcript, gate) => { - from = parent + 1; - } - else - { - return (WithdrawnTurns?)null; - } + int from; + if (parentMessageId is null) + { + from = 0; + } + else if (transcript.OrdinalOf(parentMessageId) is { } parent) + { + from = parent + 1; + } + else + { + return (WithdrawnTurns?)null; + } + + if (transcript.TruncateFrom(from) is not { } withdrawn) + { + return null; + } + + Log.ConversationTruncated(_logger, transcript.ConversationId, from, transcript.TurnIndex); + + gate.Enqueue(() => new ValueTask( + _store.TruncateAsync(transcript.ConversationId, from, CancellationToken.None).AsTask())); + + return withdrawn; + }); + } - if (transcript.TruncateFrom(from) is not { } withdrawn) - { - return null; - } + /// Adds the caller-facing turn of a graph row: what the caller said, and what it heard. + /// The session this conversation runs on. + /// What the caller said. + /// What the caller heard, or when it heard nothing. + /// + /// The state to store beside the words, on the same terms as + /// . + /// + /// What the caller calls the message it sent, if it named one. + /// + public string? AppendCallerFacingTurn( + AgentSession session, + ChatMessage spoken, + ChatMessage? heard, + ConversationSessionState? state = null, + string? firstMessageId = null) + { + ArgumentNullException.ThrowIfNull(spoken); - Log.ConversationTruncated(_logger, transcript.ConversationId, from, transcript.TurnIndex); + return AppendTurn(session, heard is null ? [spoken] : [spoken, heard], state, firstMessageId); + } - gate.Enqueue(() => new ValueTask( - _store.TruncateAsync(transcript.ConversationId, from, CancellationToken.None).AsTask())); + /// + /// Replaces the reply the caller was hearing with the words the caller actually heard. + /// + public bool TruncateLastReply(AgentSession session, string heard, TimeSpan played) + { + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(heard); - return withdrawn; - }); - } + return UnderLock( + session, + (transcript, gate) => + { + IReadOnlyList rows = transcript.TruncateLastReply(heard); + if (rows.Count == 0) + { + return false; + } - /// Adds the caller-facing turn of a graph row: what the caller said, and what it heard. - /// The session this conversation runs on. - /// What the caller said. - /// What the caller heard, or when it heard nothing. - /// - /// The state to store beside the words, on the same terms as - /// . - /// - /// What the caller calls the message it sent, if it named one. - /// - public string? AppendCallerFacingTurn( - AgentSession session, - ChatMessage spoken, - ChatMessage? heard, - ConversationSessionState? state = null, - string? firstMessageId = null) - { - ArgumentNullException.ThrowIfNull(spoken); + Log.ReplyTruncated(_logger, rows[0].ConversationId, rows[0].TurnIndex, played.TotalMilliseconds); - return AppendTurn(session, heard is null ? [spoken] : [spoken, heard], state, firstMessageId); - } + foreach (ConversationMessage row in rows) + { + gate.Enqueue(() => _store.RewriteAsync(row.ConversationId, row.MessageId, row.Content, CancellationToken.None)); + } - /// - /// Replaces the reply the caller was hearing with the words the caller actually heard. - /// - public bool TruncateLastReply(AgentSession session, string heard, TimeSpan played) - { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(heard); - - return UnderLock( - session, - (transcript, gate) => - { - var rows = transcript.TruncateLastReply(heard); - if (rows.Count == 0) - { - return false; - } + return true; + }); + } - Log.ReplyTruncated(_logger, rows[0].ConversationId, rows[0].TurnIndex, played.TotalMilliseconds); + /// + /// Waits for every write this conversation has queued to reach the store. + /// + public Task DrainAsync(AgentSession session) + { + ArgumentNullException.ThrowIfNull(session); - foreach (var row in rows) - { - gate.Enqueue(() => _store.RewriteAsync(row.ConversationId, row.MessageId, row.Content, CancellationToken.None)); - } + ConversationGate gate = GateFor(session); + lock (gate.Sync) + { + return gate.Writes; + } + } - return true; - }); - } + /// + protected override ValueTask> ProvideChatHistoryAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(context); - /// - /// Waits for every write this conversation has queued to reach the store. - /// - public Task DrainAsync(AgentSession session) - { - ArgumentNullException.ThrowIfNull(session); + return new(context.Session is { } session ? Read(session) : []); + } - var gate = GateFor(session); - lock (gate.Sync) + /// + protected override ValueTask StoreChatHistoryAsync( + InvokedContext context, CancellationToken cancellationToken = default) { - return gate.Writes; + return default; } - } - - /// - protected override ValueTask> ProvideChatHistoryAsync( - InvokingContext context, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); - return new(context.Session is { } session ? Read(session) : []); - } + /// Runs one piece of work against the conversation's transcript, alone. + private TResult UnderLock(AgentSession session, Func work) + { + ConversationGate gate = GateFor(session); - /// - protected override ValueTask StoreChatHistoryAsync( - InvokedContext context, CancellationToken cancellationToken = default) => default; + lock (gate.Sync) + { + return work(gate.Transcript, gate); + } + } - /// Runs one piece of work against the conversation's transcript, alone. - private TResult UnderLock(AgentSession session, Func work) - { - var gate = GateFor(session); + private TResult UnderLock(AgentSession session, Func work) + { + return UnderLock(session, (transcript, _) => work(transcript)); + } - lock (gate.Sync) + private ConversationGate GateFor(AgentSession session) { - return work(gate.Transcript, gate); + return _gates.GetValue(session, _ => new ConversationGate(_logger)); } } - - private TResult UnderLock(AgentSession session, Func work) - => UnderLock(session, (transcript, _) => work(transcript)); - - private ConversationGate GateFor(AgentSession session) => _gates.GetValue(session, _ => new ConversationGate(_logger)); } diff --git a/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs b/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs index f2956cbd..06a899bd 100644 --- a/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs +++ b/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs @@ -1,34 +1,35 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// Helpers for editing a 's contents without losing the rest of it. -internal static class ChatMessageExtensions +namespace AgentCore.Application.Transcript { - /// Returns the message with every host-produced content removed. - /// The message to strip. - /// The same message when it carries none, and a stripped copy when it does. - public static ChatMessage WithoutHostContent(this ChatMessage message) + /// Helpers for editing a 's contents without losing the rest of it. + internal static class ChatMessageExtensions { - ArgumentNullException.ThrowIfNull(message); - - if (!message.Contents.Any(static content => content is RenderContent or SourceContent)) + /// Returns the message with every host-produced content removed. + /// The message to strip. + /// The same message when it carries none, and a stripped copy when it does. + public static ChatMessage WithoutHostContent(this ChatMessage message) { - return message; - } + ArgumentNullException.ThrowIfNull(message); - // ChatMessage.Clone()'s own list of what a shallow copy must carry, minus Contents (rebuilt - // below) and Role (passed to the constructor): AdditionalProperties, MessageId, AuthorName, - // CreatedAt, RawRepresentation. - return new ChatMessage( - message.Role, - [.. message.Contents.Where(static content => content is not (RenderContent or SourceContent))]) - { - AdditionalProperties = message.AdditionalProperties, - MessageId = message.MessageId, - AuthorName = message.AuthorName, - CreatedAt = message.CreatedAt, - RawRepresentation = message.RawRepresentation, - }; + if (!message.Contents.Any(static content => content is RenderContent or SourceContent)) + { + return message; + } + + // ChatMessage.Clone()'s own list of what a shallow copy must carry, minus Contents (rebuilt + // below) and Role (passed to the constructor): AdditionalProperties, MessageId, AuthorName, + // CreatedAt, RawRepresentation. + return new ChatMessage( + message.Role, + [.. message.Contents.Where(static content => content is not (RenderContent or SourceContent))]) + { + AdditionalProperties = message.AdditionalProperties, + MessageId = message.MessageId, + AuthorName = message.AuthorName, + CreatedAt = message.CreatedAt, + RawRepresentation = message.RawRepresentation, + }; + } } } diff --git a/src/AgentCore.Application/Transcript/ConversationCut.cs b/src/AgentCore.Application/Transcript/ConversationCut.cs index eed5783c..eba0ed1d 100644 --- a/src/AgentCore.Application/Transcript/ConversationCut.cs +++ b/src/AgentCore.Application/Transcript/ConversationCut.cs @@ -1,6 +1,7 @@ -namespace AgentCore.Application.Transcript; - -/// What one took. -/// How many rows went, a summary row among them. -/// The span of turns whose spoken rows went, or when none did. -public readonly record struct ConversationCut(int Rows, WithdrawnTurns? Turns); +namespace AgentCore.Application.Transcript +{ + /// What one took. + /// How many rows went, a summary row among them. + /// The span of turns whose spoken rows went, or when none did. + public readonly record struct ConversationCut(int Rows, WithdrawnTurns? Turns); +} diff --git a/src/AgentCore.Application/Transcript/ConversationGate.cs b/src/AgentCore.Application/Transcript/ConversationGate.cs index aa7b12d2..74b6bd45 100644 --- a/src/AgentCore.Application/Transcript/ConversationGate.cs +++ b/src/AgentCore.Application/Transcript/ConversationGate.cs @@ -1,56 +1,57 @@ using AgentCore.Application.Diagnostics; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Transcript; - -/// -/// What one conversation holds outside its state bag: its lock, its transcript, and its queue of -/// store writes, which never faults and lets the conversation outlive a store that refuses. -/// -internal sealed class ConversationGate +namespace AgentCore.Application.Transcript { - private readonly ILogger _logger; - - /// Creates the gate of one conversation. + /// + /// What one conversation holds outside its state bag: its lock, its transcript, and its queue of + /// store writes, which never faults and lets the conversation outlive a store that refuses. + /// + /// Creates the gate of one conversation. /// Where a refused write is logged. - public ConversationGate(ILogger logger) => _logger = logger; - - /// Gets the lock every read and every change of this conversation's transcript takes. - public Lock Sync { get; } = new(); - - /// Gets the conversation's live transcript. It never enters the state bag, so serializing the bag stays small. - public ConversationTranscript Transcript { get; } = new(); + internal sealed class ConversationGate(ILogger logger) + { + private readonly ILogger _logger = logger; - /// Gets the tail of this conversation's store writes. It never faults. - public Task Writes { get; private set; } = Task.CompletedTask; + /// Gets the lock every read and every change of this conversation's transcript takes. + public Lock Sync { get; } = new(); - /// Gets or sets where a dropped write of this conversation is reported, if anywhere. - public TranscriptWriteDropped? Dropped { get; set; } + /// Gets the conversation's live transcript. It never enters the state bag, so serializing the bag stays small. + public ConversationTranscript Transcript { get; } = new(); - /// Queues one store write behind everything this conversation has already queued. Runs under . - /// The write. - public void Enqueue(Func write) - => Writes = WriteAfterAsync(Writes, write, Transcript.ConversationId, Transcript.TurnIndex); + /// Gets the tail of this conversation's store writes. It never faults. + public Task Writes { get; private set; } = Task.CompletedTask; - /// Writes to the store, and lets the conversation outlive a store that refuses. - private async Task WriteAfterAsync(Task previous, Func write, string conversationId, int turnIndex) - { - await previous.ConfigureAwait(false); + /// Gets or sets where a dropped write of this conversation is reported, if anywhere. + public TranscriptWriteDropped? Dropped { get; set; } - try + /// Queues one store write behind everything this conversation has already queued. Runs under . + /// The write. + public void Enqueue(Func write) { - await write().ConfigureAwait(false); + Writes = WriteAfterAsync(Writes, write, Transcript.ConversationId, Transcript.TurnIndex); } -#pragma warning disable CA1031 // A store 1 write failure never ends a conversation, and never breaks the chain behind it. - catch (Exception exception) -#pragma warning restore CA1031 + + /// Writes to the store, and lets the conversation outlive a store that refuses. + private async Task WriteAfterAsync(Task previous, Func write, string conversationId, int turnIndex) { - Log.TranscriptWriteFailed(_logger, conversationId, turnIndex, exception); + await previous.ConfigureAwait(false); - // The words are lost and the conversation is not. The report is what turns that into a fact the - // host can count; the contract of TranscriptWriteDropped is that it cannot throw, which - // is what keeps this chain from ever faulting. - Dropped?.Invoke(turnIndex, exception); + try + { + await write().ConfigureAwait(false); + } +#pragma warning disable CA1031 // A store 1 write failure never ends a conversation, and never breaks the chain behind it. + catch (Exception exception) +#pragma warning restore CA1031 + { + Log.TranscriptWriteFailed(_logger, conversationId, turnIndex, exception); + + // The words are lost and the conversation is not. The report is what turns that into a fact the + // host can count; the contract of TranscriptWriteDropped is that it cannot throw, which + // is what keeps this chain from ever faulting. + Dropped?.Invoke(turnIndex, exception); + } } } } diff --git a/src/AgentCore.Application/Transcript/ConversationMessage.cs b/src/AgentCore.Application/Transcript/ConversationMessage.cs index 4a1287f1..005ca43d 100644 --- a/src/AgentCore.Application/Transcript/ConversationMessage.cs +++ b/src/AgentCore.Application/Transcript/ConversationMessage.cs @@ -1,31 +1,32 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// One stored message of one conversation. It is one row of store 1. -/// The conversation the message belongs to. -/// -/// The message's position within the conversation. It is monotonic and never reused. It is not dense: an -/// edit deletes the rows it replaces and the ordinals they held are not issued again, because -/// store 3 still holds audit rows against the turns those ordinals belonged to. -/// -/// The turn the message belongs to. It is the join to the audit chain. -/// The message itself. -/// What this message is called. Unique within the conversation. -/// -/// It is the handle an edit names its parent by, and nothing else — AgentCore reads it for that and -/// gives it no other meaning. A caller's own id is kept when one arrives, and one is minted when -/// none does, because the parent an edit names is usually a reply, and a reply has no id until this -/// host gives it one. -/// -/// -public sealed record ConversationMessage( - string ConversationId, int Ordinal, int TurnIndex, ChatMessage Content, string MessageId) +namespace AgentCore.Application.Transcript { - /// - /// Gets the last ordinal this row stands in for, when it is a summary the session wrote in place - /// of every row at or below it; for a row somebody said. Every consumer - /// read of store 1 leaves summary rows out; only the session's own read returns one. - /// - public int? CoversUpTo { get; init; } + /// One stored message of one conversation. It is one row of store 1. + /// The conversation the message belongs to. + /// + /// The message's position within the conversation. It is monotonic and never reused. It is not dense: an + /// edit deletes the rows it replaces and the ordinals they held are not issued again, because + /// store 3 still holds audit rows against the turns those ordinals belonged to. + /// + /// The turn the message belongs to. It is the join to the audit chain. + /// The message itself. + /// What this message is called. Unique within the conversation. + /// + /// It is the handle an edit names its parent by, and nothing else — AgentCore reads it for that and + /// gives it no other meaning. A caller's own id is kept when one arrives, and one is minted when + /// none does, because the parent an edit names is usually a reply, and a reply has no id until this + /// host gives it one. + /// + /// + public sealed record ConversationMessage( + string ConversationId, int Ordinal, int TurnIndex, ChatMessage Content, string MessageId) + { + /// + /// Gets the last ordinal this row stands in for, when it is a summary the session wrote in place + /// of every row at or below it; for a row somebody said. Every consumer + /// read of store 1 leaves summary rows out; only the session's own read returns one. + /// + public int? CoversUpTo { get; init; } + } } diff --git a/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs b/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs index 88173462..22d9ee22 100644 --- a/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs +++ b/src/AgentCore.Application/Transcript/ConversationMessageDraft.cs @@ -1,16 +1,17 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// One message to write to a conversation. The store gives it its ordinal. -/// -/// The turn the message belongs to, or for a message written outside any -/// turn, which the store stamps with the turn the conversation's session takes next. -/// -/// The message itself. -/// What the message is called. Unique within the conversation. Never empty. -public sealed record ConversationMessageDraft(int? TurnIndex, ChatMessage Content, string MessageId) +namespace AgentCore.Application.Transcript { - /// - public int? CoversUpTo { get; init; } + /// One message to write to a conversation. The store gives it its ordinal. + /// + /// The turn the message belongs to, or for a message written outside any + /// turn, which the store stamps with the turn the conversation's session takes next. + /// + /// The message itself. + /// What the message is called. Unique within the conversation. Never empty. + public sealed record ConversationMessageDraft(int? TurnIndex, ChatMessage Content, string MessageId) + { + /// + public int? CoversUpTo { get; init; } + } } diff --git a/src/AgentCore.Application/Transcript/ConversationMessageIds.cs b/src/AgentCore.Application/Transcript/ConversationMessageIds.cs index 5d4504e0..ab94e67c 100644 --- a/src/AgentCore.Application/Transcript/ConversationMessageIds.cs +++ b/src/AgentCore.Application/Transcript/ConversationMessageIds.cs @@ -1,8 +1,12 @@ -namespace AgentCore.Application.Transcript; - -/// Mints the name a message takes when nobody names it. -public static class ConversationMessageIds +namespace AgentCore.Application.Transcript { - /// Mints a new message id. - public static string New() => Guid.CreateVersion7().ToString("n"); + /// Mints the name a message takes when nobody names it. + public static class ConversationMessageIds + { + /// Mints a new message id. + public static string New() + { + return Guid.CreateVersion7().ToString("n"); + } + } } diff --git a/src/AgentCore.Application/Transcript/ConversationTranscript.cs b/src/AgentCore.Application/Transcript/ConversationTranscript.cs index 987cf47a..318aa5be 100644 --- a/src/AgentCore.Application/Transcript/ConversationTranscript.cs +++ b/src/AgentCore.Application/Transcript/ConversationTranscript.cs @@ -1,354 +1,356 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// The words of one conversation, and the ordinals that address them. -internal sealed class ConversationTranscript +namespace AgentCore.Application.Transcript { - /// Gets or sets the id of the conversation. The turn loop stamps it. - public string ConversationId { get; set; } = string.Empty; - - /// Gets or sets the zero-based index of the turn now running. The turn loop stamps it. - public int TurnIndex { get; set; } - - /// Gets or sets the next free ordinal of the conversation. - public int NextOrdinal { get; set; } - - /// Gets or sets the reply a barge-in would cut, or null when the conversation has spoken none. - public int? LastAssistantOrdinal { get; set; } - - /// - /// Gets or sets the live history of the conversation, oldest first. It needs a setter, not just a getter: - /// with no setter, System.Text.Json silently skips it on deserialize instead of populating it. - /// - public List Messages { get; set; } = []; - - /// Gets the summary that stands in for the oldest rows, or when every row is live. - public StoredMessage? Summary => Messages.Find(static stored => stored.CoversUpTo is not null); - - /// - /// Gets a count that moves on every change to the words. A compaction computed outside the lock - /// names the revision it read, and is refused when the words moved underneath it. - /// - public int Revision { get; private set; } - - /// Reads a conversation that already has words back into a transcript that has none. - /// The rows of the conversation the session reads, as takes them. - /// How far the conversation had got, from the state stored beside these words. - /// The index the next turn of this conversation takes. - public int Resume(IReadOnlyList rows, TranscriptMarks marks) + /// The words of one conversation, and the ordinals that address them. + internal sealed class ConversationTranscript { - Resync(rows, marks.NextOrdinal); + /// Gets or sets the id of the conversation. The turn loop stamps it. + public string ConversationId { get; set; } = string.Empty; - return marks.NextTurnIndex; - } + /// Gets or sets the zero-based index of the turn now running. The turn loop stamps it. + public int TurnIndex { get; set; } - /// - /// Replaces the live history with what store 1 holds, without disturbing - /// or . - /// - /// - /// The rows store 1 read for the session: every row, or the newest summary and the rows above what - /// it covers. A row a summary stands in for is the caller's mistake, not this method's to catch: - /// it lands in the live history beside the summary that already speaks for it. Order does not matter. - /// - /// The next free ordinal of the conversation, from store 0's own counter. - public void Resync(IReadOnlyList rows, int nextOrdinal) - { - ArgumentNullException.ThrowIfNull(rows); + /// Gets or sets the next free ordinal of the conversation. + public int NextOrdinal { get; set; } - // Stripped for the reason Append gives: the live history is serialised into the session - // state bag every turn, and what store 1 keeps is bigger than that bag should ever carry. - Messages = [.. rows - .OrderBy(row => row.Ordinal) - .Select(row => new StoredMessage - { - Ordinal = row.Ordinal, - TurnIndex = row.TurnIndex, - MessageId = row.MessageId, - Message = row.Content.WithoutHostContent(), - CoversUpTo = row.CoversUpTo, - })]; - - NextOrdinal = nextOrdinal; - Revision++; - - // Without this a caller who barges in on the first reply of a resumed session is not heard: - // TruncateLastReply finds no ordinal to cut at and returns nothing, and the provider reports - // that as a write it declined rather than as a cut it lost. - RestoreLastAssistantOrdinal(); - } + /// Gets or sets the reply a barge-in would cut, or null when the conversation has spoken none. + public int? LastAssistantOrdinal { get; set; } - /// Finds the ordinal a message sits at, by the name a caller knows it under. - /// What the caller calls the message. - /// - /// The ordinal, or when the live history holds no message of that name. - /// A message the stands in for is not held, and answers null too. - /// - public int? OrdinalOf(string messageId) - { - ArgumentException.ThrowIfNullOrEmpty(messageId); + /// + /// Gets or sets the live history of the conversation, oldest first. It needs a setter, not just a getter: + /// with no setter, System.Text.Json silently skips it on deserialize instead of populating it. + /// + public List Messages { get; set; } = []; - return Messages.Find(stored => string.Equals(stored.MessageId, messageId, StringComparison.Ordinal)) - ?.Ordinal; - } + /// Gets the summary that stands in for the oldest rows, or when every row is live. + public StoredMessage? Summary => Messages.Find(static stored => stored.CoversUpTo is not null); - /// - /// Whether an edit hanging off one message can be cut from what this transcript holds. It can - /// unless the cut would reach a row the stands in for: the whole - /// conversation, or a parent this transcript does not hold. Such an edit needs every row read - /// back first, because the summary must go and the rows it spoke for must come back. - /// - /// The message the edit hangs off, or for the whole conversation. - public bool CanTruncateFrom(string? parentMessageId) - { - if (Summary is not { CoversUpTo: { } covered }) + /// + /// Gets a count that moves on every change to the words. A compaction computed outside the lock + /// names the revision it read, and is refused when the words moved underneath it. + /// + public int Revision { get; private set; } + + /// Reads a conversation that already has words back into a transcript that has none. + /// The rows of the conversation the session reads, as takes them. + /// How far the conversation had got, from the state stored beside these words. + /// The index the next turn of this conversation takes. + public int Resume(IReadOnlyList rows, TranscriptMarks marks) { - return true; - } + Resync(rows, marks.NextOrdinal); - return parentMessageId is not null && OrdinalOf(parentMessageId) is { } ordinal && ordinal > covered; - } + return marks.NextTurnIndex; + } - /// - /// Withdraws the tail of the conversation, from one ordinal onward. The - /// stays when the cut lies above what it covers, whatever its own ordinal: it was written after - /// the rows it stands for, so its ordinal says nothing about where the cut falls. - /// - /// The first ordinal to drop. It goes too. It lies above what the covers. - /// The turns the withdrawal took, or when nothing went. - /// The cut reaches a row the stands in for. - public WithdrawnTurns? TruncateFrom(int fromOrdinal) - { - if (Summary is { CoversUpTo: { } covered } && fromOrdinal <= covered) + /// + /// Replaces the live history with what store 1 holds, without disturbing + /// or . + /// + /// + /// The rows store 1 read for the session: every row, or the newest summary and the rows above what + /// it covers. A row a summary stands in for is the caller's mistake, not this method's to catch: + /// it lands in the live history beside the summary that already speaks for it. Order does not matter. + /// + /// The next free ordinal of the conversation, from store 0's own counter. + public void Resync(IReadOnlyList rows, int nextOrdinal) { - throw new InvalidOperationException( - $"The cut at ordinal {fromOrdinal} reaches under the summary of the conversation '{ConversationId}', " - + $"which covers every row up to {covered}. Read every row back before cutting there."); + ArgumentNullException.ThrowIfNull(rows); + + // Stripped for the reason Append gives: the live history is serialised into the session + // state bag every turn, and what store 1 keeps is bigger than that bag should ever carry. + Messages = [.. rows + .OrderBy(row => row.Ordinal) + .Select(row => new StoredMessage + { + Ordinal = row.Ordinal, + TurnIndex = row.TurnIndex, + MessageId = row.MessageId, + Message = row.Content.WithoutHostContent(), + CoversUpTo = row.CoversUpTo, + })]; + + NextOrdinal = nextOrdinal; + Revision++; + + // Without this a caller who barges in on the first reply of a resumed session is not heard: + // TruncateLastReply finds no ordinal to cut at and returns nothing, and the provider reports + // that as a write it declined rather than as a cut it lost. + RestoreLastAssistantOrdinal(); } - var first = int.MaxValue; - var last = int.MinValue; - foreach (var stored in Messages) + /// Finds the ordinal a message sits at, by the name a caller knows it under. + /// What the caller calls the message. + /// + /// The ordinal, or when the live history holds no message of that name. + /// A message the stands in for is not held, and answers null too. + /// + public int? OrdinalOf(string messageId) { - if (stored.Ordinal < fromOrdinal || stored.CoversUpTo is not null) - { - continue; - } + ArgumentException.ThrowIfNullOrEmpty(messageId); - first = Math.Min(first, stored.TurnIndex); - last = Math.Max(last, stored.TurnIndex); + return Messages.Find(stored => string.Equals(stored.MessageId, messageId, StringComparison.Ordinal)) + ?.Ordinal; } - if (last < first) + /// + /// Whether an edit hanging off one message can be cut from what this transcript holds. It can + /// unless the cut would reach a row the stands in for: the whole + /// conversation, or a parent this transcript does not hold. Such an edit needs every row read + /// back first, because the summary must go and the rows it spoke for must come back. + /// + /// The message the edit hangs off, or for the whole conversation. + public bool CanTruncateFrom(string? parentMessageId) { - return null; + return Summary is not { CoversUpTo: { } covered } || (parentMessageId is not null && OrdinalOf(parentMessageId) is { } ordinal && ordinal > covered); } - Messages.RemoveAll(stored => stored.Ordinal >= fromOrdinal && stored.CoversUpTo is null); - RestoreLastAssistantOrdinal(); - Revision++; - return new WithdrawnTurns(first, last); - } + /// + /// Withdraws the tail of the conversation, from one ordinal onward. The + /// stays when the cut lies above what it covers, whatever its own ordinal: it was written after + /// the rows it stands for, so its ordinal says nothing about where the cut falls. + /// + /// The first ordinal to drop. It goes too. It lies above what the covers. + /// The turns the withdrawal took, or when nothing went. + /// The cut reaches a row the stands in for. + public WithdrawnTurns? TruncateFrom(int fromOrdinal) + { + if (Summary is { CoversUpTo: { } covered } && fromOrdinal <= covered) + { + throw new InvalidOperationException( + $"The cut at ordinal {fromOrdinal} reaches under the summary of the conversation '{ConversationId}', " + + $"which covers every row up to {covered}. Read every row back before cutting there."); + } - private void RestoreLastAssistantOrdinal() - => LastAssistantOrdinal = Messages - .Where(stored => stored.CoversUpTo is null - && stored.Message.Role == ChatRole.Assistant - && !string.IsNullOrWhiteSpace(stored.Message.Text)) - .Select(stored => (int?)stored.Ordinal) - .LastOrDefault(); - - /// Opens a turn, so the rows it appends carry its index. - public void BeginTurn(int turnIndex) => TurnIndex = turnIndex; - - /// - /// Reads the conversation as the model sees it: the first, then every live - /// row, oldest first. The summary leads whatever its ordinal: it was written after the newest - /// rows it does not cover, and those must follow it, not precede it. - /// - public IReadOnlyList Read() => [.. View(Messages.Count).Select(entry => entry.Message)]; - - /// - /// Names what a compaction of the conversation would cover: everything before the newest live - /// turn. That turn stays live so the edit a caller most often makes — of the last question, which - /// hangs off the reply before it — still finds its parent without a full read. - /// - /// - /// The view the compaction would run over, or when nothing lies before the - /// newest live turn: a conversation of one turn, or a summary with one turn above it — which the - /// summary already covers. - /// - public TranscriptFloor? Floor() - { - var newest = Messages.FindLast(static stored => stored.CoversUpTo is null)?.TurnIndex; + int first = int.MaxValue; + int last = int.MinValue; + foreach (StoredMessage stored in Messages) + { + if (stored.Ordinal < fromOrdinal || stored.CoversUpTo is not null) + { + continue; + } - var last = Messages.FindLastIndex(stored => stored.CoversUpTo is null && stored.TurnIndex < newest); + first = Math.Min(first, stored.TurnIndex); + last = Math.Max(last, stored.TurnIndex); + } - if (last < 0) - { - return null; - } + if (last < first) + { + return null; + } - return new TranscriptFloor(Revision, Summary?.CoversUpTo, [.. View(last + 1)]); - } + _ = Messages.RemoveAll(stored => stored.Ordinal >= fromOrdinal && stored.CoversUpTo is null); + RestoreLastAssistantOrdinal(); + Revision++; + return new WithdrawnTurns(first, last); + } - /// The model view of the first rows: the summary first, then each live row at its own ordinal. - private IEnumerable View(int count) - { - if (Summary is { CoversUpTo: { } covered } summary) + private void RestoreLastAssistantOrdinal() { - yield return new ViewMessage(summary.Message, covered); + LastAssistantOrdinal = Messages + .Where(stored => stored.CoversUpTo is null + && stored.Message.Role == ChatRole.Assistant + && !string.IsNullOrWhiteSpace(stored.Message.Text)) + .Select(stored => (int?)stored.Ordinal) + .LastOrDefault(); } - foreach (var stored in Messages.Take(count).Where(stored => stored.CoversUpTo is null)) + /// Opens a turn, so the rows it appends carry its index. + public void BeginTurn(int turnIndex) { - yield return new ViewMessage(stored.Message, stored.Ordinal); + TurnIndex = turnIndex; } - } - - /// - /// Puts one summary in place of every row at or below and of the - /// summary that stood before it, unless the words moved since was read. - /// - /// The message that now speaks for those rows. - /// The last ordinal it speaks for. Never below what the standing covers. - /// The the compaction read. - /// The row the summary became, for store 1; or when the compaction was stale and dropped. - public ConversationMessage? Compact(ChatMessage summary, int coversUpTo, int revision) - { - ArgumentNullException.ThrowIfNull(summary); - if (Summary is { CoversUpTo: { } covered }) + /// + /// Reads the conversation as the model sees it: the first, then every live + /// row, oldest first. The summary leads whatever its ordinal: it was written after the newest + /// rows it does not cover, and those must follow it, not precede it. + /// + public IReadOnlyList Read() { - ArgumentOutOfRangeException.ThrowIfLessThan(coversUpTo, covered); + return [.. View(Messages.Count).Select(entry => entry.Message)]; } - if (revision != Revision) + /// + /// Names what a compaction of the conversation would cover: everything before the newest live + /// turn. That turn stays live so the edit a caller most often makes — of the last question, which + /// hangs off the reply before it — still finds its parent without a full read. + /// + /// + /// The view the compaction would run over, or when nothing lies before the + /// newest live turn: a conversation of one turn, or a summary with one turn above it — which the + /// summary already covers. + /// + public TranscriptFloor? Floor() { - return null; - } + int? newest = Messages.FindLast(static stored => stored.CoversUpTo is null)?.TurnIndex; + + int last = Messages.FindLastIndex(stored => stored.CoversUpTo is null && stored.TurnIndex < newest); - Messages.RemoveAll(stored => stored.Ordinal <= coversUpTo || stored.CoversUpTo is not null); + return last < 0 ? null : new TranscriptFloor(Revision, Summary?.CoversUpTo, [.. View(last + 1)]); + } - var ordinal = NextOrdinal++; - var messageId = NewMessageId(); - Messages.Add(new StoredMessage + /// The model view of the first rows: the summary first, then each live row at its own ordinal. + private IEnumerable View(int count) { - Ordinal = ordinal, - TurnIndex = TurnIndex, - MessageId = messageId, - Message = summary.WithoutHostContent(), - CoversUpTo = coversUpTo, - }); - - RestoreLastAssistantOrdinal(); - Revision++; - return new ConversationMessage(ConversationId, ordinal, TurnIndex, summary, messageId) { CoversUpTo = coversUpTo }; - } + if (Summary is { CoversUpTo: { } covered } summary) + { + yield return new ViewMessage(summary.Message, covered); + } - /// Adds new messages to the conversation, and returns the rows they became. - /// The messages the turn produced, oldest first. - /// - /// What the caller calls the first of them, or to name it here. Only the - /// first: it is the one the caller sent and so the only one the caller had a name for. - /// - public IReadOnlyList Append( - IReadOnlyList messages, string? firstMessageId = null) - { - ArgumentNullException.ThrowIfNull(messages); + foreach (StoredMessage? stored in Messages.Take(count).Where(stored => stored.CoversUpTo is null)) + { + yield return new ViewMessage(stored.Message, stored.Ordinal); + } + } - var rows = new List(messages.Count); - for (var index = 0; index < messages.Count; index++) + /// + /// Puts one summary in place of every row at or below and of the + /// summary that stood before it, unless the words moved since was read. + /// + /// The message that now speaks for those rows. + /// The last ordinal it speaks for. Never below what the standing covers. + /// The the compaction read. + /// The row the summary became, for store 1; or when the compaction was stale and dropped. + public ConversationMessage? Compact(ChatMessage summary, int coversUpTo, int revision) { - var message = messages[index]; + ArgumentNullException.ThrowIfNull(summary); - var ordinal = NextOrdinal++; + if (Summary is { CoversUpTo: { } covered }) + { + ArgumentOutOfRangeException.ThrowIfLessThan(coversUpTo, covered); + } - var messageId = (index == 0 ? firstMessageId : null) ?? NewMessageId(); + if (revision != Revision) + { + return null; + } - rows.Add(new ConversationMessage(ConversationId, ordinal, TurnIndex, message, messageId)); + _ = Messages.RemoveAll(stored => stored.Ordinal <= coversUpTo || stored.CoversUpTo is not null); + int ordinal = NextOrdinal++; + string messageId = NewMessageId(); Messages.Add(new StoredMessage { Ordinal = ordinal, TurnIndex = TurnIndex, MessageId = messageId, - Message = message.WithoutHostContent(), + Message = summary.WithoutHostContent(), + CoversUpTo = coversUpTo, }); - if (message.Role == ChatRole.Assistant && !string.IsNullOrWhiteSpace(message.Text)) - { - LastAssistantOrdinal = ordinal; - } + RestoreLastAssistantOrdinal(); + Revision++; + return new ConversationMessage(ConversationId, ordinal, TurnIndex, summary, messageId) { CoversUpTo = coversUpTo }; } - Revision++; - return rows; - } + /// Adds new messages to the conversation, and returns the rows they became. + /// The messages the turn produced, oldest first. + /// + /// What the caller calls the first of them, or to name it here. Only the + /// first: it is the one the caller sent and so the only one the caller had a name for. + /// + public IReadOnlyList Append( + IReadOnlyList messages, string? firstMessageId = null) + { + ArgumentNullException.ThrowIfNull(messages); - /// Cuts the turn the caller was hearing down to the words the caller actually heard. - public IReadOnlyList TruncateLastReply(string heard) - { - ArgumentNullException.ThrowIfNull(heard); + List rows = new(messages.Count); + for (int index = 0; index < messages.Count; index++) + { + ChatMessage message = messages[index]; - if (LastAssistantOrdinal is not int ordinal - || Messages.Find(message => message.Ordinal == ordinal) is not { } spoken) - { - return []; + int ordinal = NextOrdinal++; + + string messageId = (index == 0 ? firstMessageId : null) ?? NewMessageId(); + + rows.Add(new ConversationMessage(ConversationId, ordinal, TurnIndex, message, messageId)); + + Messages.Add(new StoredMessage + { + Ordinal = ordinal, + TurnIndex = TurnIndex, + MessageId = messageId, + Message = message.WithoutHostContent(), + }); + + if (message.Role == ChatRole.Assistant && !string.IsNullOrWhiteSpace(message.Text)) + { + LastAssistantOrdinal = ordinal; + } + } + + Revision++; + return rows; } - List rows = []; - foreach (var stored in Messages) + /// Cuts the turn the caller was hearing down to the words the caller actually heard. + public IReadOnlyList TruncateLastReply(string heard) { - if (stored.TurnIndex != spoken.TurnIndex || stored.Message.Role != ChatRole.Assistant || stored.CoversUpTo is not null) + ArgumentNullException.ThrowIfNull(heard); + + if (LastAssistantOrdinal is not int ordinal + || Messages.Find(message => message.Ordinal == ordinal) is not { } spoken) { - continue; + return []; } - var isReply = stored.Ordinal == ordinal; - if (!isReply && !stored.Message.Contents.Any(content => content is TextContent)) + List rows = []; + foreach (StoredMessage stored in Messages) { - continue; - } + if (stored.TurnIndex != spoken.TurnIndex || stored.Message.Role != ChatRole.Assistant || stored.CoversUpTo is not null) + { + continue; + } + + bool isReply = stored.Ordinal == ordinal; + if (!isReply && !stored.Message.Contents.Any(content => content is TextContent)) + { + continue; + } + + List kept = [.. stored.Message.Contents.Where(content => content is not TextContent)]; - List kept = [.. stored.Message.Contents.Where(content => content is not TextContent)]; + ChatMessage corrected = stored.Message.Clone(); + corrected.Contents = isReply && heard.Length > 0 ? [new TextContent(heard), .. kept] : kept; + stored.Message = corrected; + + rows.Add(new ConversationMessage( + ConversationId, stored.Ordinal, stored.TurnIndex, corrected, stored.MessageId)); + } - var corrected = stored.Message.Clone(); - corrected.Contents = isReply && heard.Length > 0 ? [new TextContent(heard), .. kept] : kept; - stored.Message = corrected; + if (rows.Count > 0) + { + Revision++; + } - rows.Add(new ConversationMessage( - ConversationId, stored.Ordinal, stored.TurnIndex, corrected, stored.MessageId)); + return rows; } - if (rows.Count > 0) + /// Mints a name for a row the caller had no name for. + private static string NewMessageId() { - Revision++; + return ConversationMessageIds.New(); } - return rows; - } - - /// Mints a name for a row the caller had no name for. - private static string NewMessageId() => ConversationMessageIds.New(); + /// One message of the live history, with the ordinal its stored row carries. + internal sealed class StoredMessage + { + /// Gets or sets the message's position within the conversation. + public int Ordinal { get; set; } - /// One message of the live history, with the ordinal its stored row carries. - internal sealed class StoredMessage - { - /// Gets or sets the message's position within the conversation. - public int Ordinal { get; set; } + /// Gets or sets the turn the message belongs to. It is the join to the audit chain. + public int TurnIndex { get; set; } - /// Gets or sets the turn the message belongs to. It is the join to the audit chain. - public int TurnIndex { get; set; } + /// Gets or sets the name this message is known by, inside the conversation and outside it. + public string MessageId { get; set; } = string.Empty; - /// Gets or sets the name this message is known by, inside the conversation and outside it. - public string MessageId { get; set; } = string.Empty; + /// Gets or sets the message. A barge-in replaces it with what the caller heard. + public ChatMessage Message { get; set; } = new(ChatRole.Assistant, string.Empty); - /// Gets or sets the message. A barge-in replaces it with what the caller heard. - public ChatMessage Message { get; set; } = new(ChatRole.Assistant, string.Empty); - - /// - public int? CoversUpTo { get; set; } + /// + public int? CoversUpTo { get; set; } + } } } diff --git a/src/AgentCore.Application/Transcript/FileContent.cs b/src/AgentCore.Application/Transcript/FileContent.cs index 8b193367..51fd0d77 100644 --- a/src/AgentCore.Application/Transcript/FileContent.cs +++ b/src/AgentCore.Application/Transcript/FileContent.cs @@ -1,28 +1,29 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// -/// A file the reply produced, carried by the message that produced it. This is the only shape a -/// reader sees: where the file came from is AgentCore's business. -/// -public sealed class FileContent : AIContent +namespace AgentCore.Application.Transcript { - /// The file name. It is the name the store keeps it under. - public required string Name { get; set; } + /// + /// A file the reply produced, carried by the message that produced it. This is the only shape a + /// reader sees: where the file came from is AgentCore's business. + /// + public sealed class FileContent : AIContent + { + /// The file name. It is the name the store keeps it under. + public required string Name { get; set; } - /// Where the file came from: the workspace-relative path the model published. - public required string FileId { get; set; } + /// Where the file came from: the workspace-relative path the model published. + public required string FileId { get; set; } - /// A short label the model gave the file for the person, or . - public string? Title { get; set; } + /// A short label the model gave the file for the person, or . + public string? Title { get; set; } - /// The IANA media type the store holds the file under. - public string MediaType { get; set; } = "application/octet-stream"; + /// The IANA media type the store holds the file under. + public string MediaType { get; set; } = "application/octet-stream"; - /// How many bytes the store holds. - public long Length { get; set; } + /// How many bytes the store holds. + public long Length { get; set; } - /// Whether the store holds the file. A reader links only what is kept. - public bool Kept { get; set; } + /// Whether the store holds the file. A reader links only what is kept. + public bool Kept { get; set; } + } } diff --git a/src/AgentCore.Application/Transcript/ReaderContent.cs b/src/AgentCore.Application/Transcript/ReaderContent.cs index a668122c..61233f31 100644 --- a/src/AgentCore.Application/Transcript/ReaderContent.cs +++ b/src/AgentCore.Application/Transcript/ReaderContent.cs @@ -1,65 +1,66 @@ using System.Text.Json; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// -/// The content types AgentCore adds to a message for the person reading the transcript, not for -/// the model: a drawing, a citation, a published file. This is the one list of them. It decides -/// how a store encodes them and what is stripped before a message reaches the model. -/// -internal static class ReaderContent +namespace AgentCore.Application.Transcript { - /// The discriminator a stored RenderContent is written with. It is a wire format. - private const string RenderContentTypeId = "agentcore.render"; - - /// The discriminator a stored SourceContent is written with. It is a wire format. - private const string SourceContentTypeId = "agentcore.source"; - - /// The discriminator a stored FileContent is written with. It is a wire format. - private const string FileContentTypeId = "agentcore.file"; + /// + /// The content types AgentCore adds to a message for the person reading the transcript, not for + /// the model: a drawing, a citation, a published file. This is the one list of them. It decides + /// how a store encodes them and what is stripped before a message reaches the model. + /// + internal static class ReaderContent + { + /// The discriminator a stored RenderContent is written with. It is a wire format. + private const string RenderContentTypeId = "agentcore.render"; - /// Whether is for the reader and not the model. - /// The content to test. - public static bool Is(AIContent content) => content is RenderContent or SourceContent or FileContent; + /// The discriminator a stored SourceContent is written with. It is a wire format. + private const string SourceContentTypeId = "agentcore.source"; - /// Teaches to encode and decode every reader content type. - /// A writable options instance. - public static void Register(JsonSerializerOptions options) - { - ArgumentNullException.ThrowIfNull(options); + /// The discriminator a stored FileContent is written with. It is a wire format. + private const string FileContentTypeId = "agentcore.file"; - options.AddAIContentType(RenderContentTypeId); - options.AddAIContentType(SourceContentTypeId); - options.AddAIContentType(FileContentTypeId); - } + /// Whether is for the reader and not the model. + /// The content to test. + public static bool Is(AIContent content) + { + return content is RenderContent or SourceContent or FileContent; + } - /// - /// The same messages with every reader content removed. A message that holds none is returned - /// as-is; one that does is copied, so the transcript's own instance keeps what it had. - /// - /// The messages bound for the model. - public static IEnumerable Strip(IEnumerable messages) - { - ArgumentNullException.ThrowIfNull(messages); + /// Teaches to encode and decode every reader content type. + /// A writable options instance. + public static void Register(JsonSerializerOptions options) + { + ArgumentNullException.ThrowIfNull(options); - return messages.Select(Strip); - } + options.AddAIContentType(RenderContentTypeId); + options.AddAIContentType(SourceContentTypeId); + options.AddAIContentType(FileContentTypeId); + } - private static ChatMessage Strip(ChatMessage message) - { - if (!message.Contents.Any(Is)) + /// + /// The same messages with every reader content removed. A message that holds none is returned + /// as-is; one that does is copied, so the transcript's own instance keeps what it had. + /// + /// The messages bound for the model. + public static IEnumerable Strip(IEnumerable messages) { - return message; + ArgumentNullException.ThrowIfNull(messages); + + return messages.Select(Strip); } - return new ChatMessage(message.Role, message.Contents.Where(content => !Is(content)).ToList()) + private static ChatMessage Strip(ChatMessage message) { - AuthorName = message.AuthorName, - MessageId = message.MessageId, - CreatedAt = message.CreatedAt, - AdditionalProperties = message.AdditionalProperties, - RawRepresentation = message.RawRepresentation, - }; + return !message.Contents.Any(Is) + ? message + : new ChatMessage(message.Role, [.. message.Contents.Where(content => !Is(content))]) + { + AuthorName = message.AuthorName, + MessageId = message.MessageId, + CreatedAt = message.CreatedAt, + AdditionalProperties = message.AdditionalProperties, + RawRepresentation = message.RawRepresentation, + }; + } } } diff --git a/src/AgentCore.Application/Transcript/RenderContent.cs b/src/AgentCore.Application/Transcript/RenderContent.cs index a2f8c6d8..98c32565 100644 --- a/src/AgentCore.Application/Transcript/RenderContent.cs +++ b/src/AgentCore.Application/Transcript/RenderContent.cs @@ -1,19 +1,20 @@ using System.Text.Json; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// Something the caller was shown, carried by the message that produced it. -public sealed class RenderContent : AIContent +namespace AgentCore.Application.Transcript { - /// The renderer the host looks up. - public required string Name { get; set; } + /// Something the caller was shown, carried by the message that produced it. + public sealed class RenderContent : AIContent + { + /// The renderer the host looks up. + public required string Name { get; set; } - /// - /// Names the thing shown. Publishing the same id again within a turn replaces it. - /// - public required string RenderId { get; set; } + /// + /// Names the thing shown. Publishing the same id again within a turn replaces it. + /// + public required string RenderId { get; set; } - /// The payload that renderer reads. Its shape belongs to the renderer. - public required JsonElement Data { get; set; } + /// The payload that renderer reads. Its shape belongs to the renderer. + public required JsonElement Data { get; set; } + } } diff --git a/src/AgentCore.Application/Transcript/SourceContent.cs b/src/AgentCore.Application/Transcript/SourceContent.cs index 3b3bce4e..6f4575af 100644 --- a/src/AgentCore.Application/Transcript/SourceContent.cs +++ b/src/AgentCore.Application/Transcript/SourceContent.cs @@ -1,16 +1,17 @@ using AgentCore.Domain.Sources; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// Where an answer came from, carried by the message that produced it. -public sealed class SourceContent : AIContent +namespace AgentCore.Application.Transcript { - /// The source this content carries. - public required SourceReference Source { get; set; } + /// Where an answer came from, carried by the message that produced it. + public sealed class SourceContent : AIContent + { + /// The source this content carries. + public required SourceReference Source { get; set; } - /// - /// The id of the tool call this source was cited under. - /// - public required string CallId { get; set; } + /// + /// The id of the tool call this source was cited under. + /// + public required string CallId { get; set; } + } } diff --git a/src/AgentCore.Application/Transcript/TranscriptFloor.cs b/src/AgentCore.Application/Transcript/TranscriptFloor.cs index daa3f4c2..a7896fda 100644 --- a/src/AgentCore.Application/Transcript/TranscriptFloor.cs +++ b/src/AgentCore.Application/Transcript/TranscriptFloor.cs @@ -1,7 +1,8 @@ -namespace AgentCore.Application.Transcript; - -/// What a compaction of the conversation would cover, read before the compaction runs. -/// The the words stood at when read. -/// The last ordinal the summary that already stands covers, or when none stands. -/// Every message the compaction covers, as the model sees them, oldest first. A standing summary comes first. -internal readonly record struct TranscriptFloor(int Revision, int? CoversUpTo, IReadOnlyList Messages); +namespace AgentCore.Application.Transcript +{ + /// What a compaction of the conversation would cover, read before the compaction runs. + /// The the words stood at when read. + /// The last ordinal the summary that already stands covers, or when none stands. + /// Every message the compaction covers, as the model sees them, oldest first. A standing summary comes first. + internal readonly record struct TranscriptFloor(int Revision, int? CoversUpTo, IReadOnlyList Messages); +} diff --git a/src/AgentCore.Application/Transcript/TranscriptJson.cs b/src/AgentCore.Application/Transcript/TranscriptJson.cs index fdb98218..3b416fb6 100644 --- a/src/AgentCore.Application/Transcript/TranscriptJson.cs +++ b/src/AgentCore.Application/Transcript/TranscriptJson.cs @@ -1,29 +1,30 @@ using System.Text.Json; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// How a stored message is encoded and decoded. Every store and the state bag agree on it. -public static class TranscriptJson +namespace AgentCore.Application.Transcript { - /// The shared options. Every store and the state bag serialise a ChatMessage with it. - public static JsonSerializerOptions Options { get; } = Build(); - - private static JsonSerializerOptions Build() + /// How a stored message is encoded and decoded. Every store and the state bag agree on it. + public static class TranscriptJson { - // AIJsonUtilities.DefaultOptions ships the polymorphic converters, so a tool call, a tool - // result, text, and usage all round-trip with no code of ours. It is read-only, though, and - // AddAIContentType throws on a read-only instance, so copy first. - JsonSerializerOptions options = new(AIJsonUtilities.DefaultOptions) + /// The shared options. Every store and the state bag serialise a ChatMessage with it. + public static JsonSerializerOptions Options { get; } = Build(); + + private static JsonSerializerOptions Build() { - // jsonb keeps no key order, so the $type discriminator does not come back first. - // Without this every read of a stored message throws. - AllowOutOfOrderMetadataProperties = true, - }; + // AIJsonUtilities.DefaultOptions ships the polymorphic converters, so a tool call, a tool + // result, text, and usage all round-trip with no code of ours. It is read-only, though, and + // AddAIContentType throws on a read-only instance, so copy first. + JsonSerializerOptions options = new(AIJsonUtilities.DefaultOptions) + { + // jsonb keeps no key order, so the $type discriminator does not come back first. + // Without this every read of a stored message throws. + AllowOutOfOrderMetadataProperties = true, + }; - ReaderContent.Register(options); - options.MakeReadOnly(); + ReaderContent.Register(options); + options.MakeReadOnly(); - return options; + return options; + } } } diff --git a/src/AgentCore.Application/Transcript/TranscriptMarks.cs b/src/AgentCore.Application/Transcript/TranscriptMarks.cs index a39b53ba..3a0bc2bf 100644 --- a/src/AgentCore.Application/Transcript/TranscriptMarks.cs +++ b/src/AgentCore.Application/Transcript/TranscriptMarks.cs @@ -1,6 +1,7 @@ -namespace AgentCore.Application.Transcript; - -/// How far a conversation has got, in places rather than in counts. -/// The next ordinal the conversation issues. -/// The index the conversation's next turn takes. -internal readonly record struct TranscriptMarks(int NextOrdinal, int NextTurnIndex); +namespace AgentCore.Application.Transcript +{ + /// How far a conversation has got, in places rather than in counts. + /// The next ordinal the conversation issues. + /// The index the conversation's next turn takes. + internal readonly record struct TranscriptMarks(int NextOrdinal, int NextTurnIndex); +} diff --git a/src/AgentCore.Application/Transcript/TranscriptWindow.cs b/src/AgentCore.Application/Transcript/TranscriptWindow.cs index 78024125..9a8f9966 100644 --- a/src/AgentCore.Application/Transcript/TranscriptWindow.cs +++ b/src/AgentCore.Application/Transcript/TranscriptWindow.cs @@ -1,24 +1,28 @@ -namespace AgentCore.Application.Transcript; - -/// -/// One page of a conversation's words, counted in turns rather than rows. A turn holds a question, -/// the tool calls that answered it, and the reply, and a page boundary never falls inside one, so a -/// reader can draw a page without a reply whose tool calls are on the page before it. -/// -/// -/// Only turns with a smaller index are read, or to read back from the newest. -/// -/// How many turns at most. Positive. -/// is not positive. -public readonly record struct TranscriptWindow(int? BeforeTurn, int Turns) +namespace AgentCore.Application.Transcript { - /// How many turns at most. Positive, except on default, which reads an empty page. - public int Turns { get; init; } = Turns > 0 - ? Turns - : throw new ArgumentOutOfRangeException(nameof(Turns), Turns, "A window holds at least one turn."); + /// + /// One page of a conversation's words, counted in turns rather than rows. A turn holds a question, + /// the tool calls that answered it, and the reply, and a page boundary never falls inside one, so a + /// reader can draw a page without a reply whose tool calls are on the page before it. + /// + /// + /// Only turns with a smaller index are read, or to read back from the newest. + /// + /// How many turns at most. Positive. + /// is not positive. + public readonly record struct TranscriptWindow(int? BeforeTurn, int Turns) + { + /// How many turns at most. Positive, except on default, which reads an empty page. + public int Turns { get; init; } = Turns > 0 + ? Turns + : throw new ArgumentOutOfRangeException(nameof(Turns), Turns, "A window holds at least one turn."); - /// Whether a turn falls before the window's start. - /// The turn to test. - /// when the turn is one the window may hold. - public bool Admits(int turnIndex) => BeforeTurn is not { } before || turnIndex < before; + /// Whether a turn falls before the window's start. + /// The turn to test. + /// when the turn is one the window may hold. + public bool Admits(int turnIndex) + { + return BeforeTurn is not { } before || turnIndex < before; + } + } } diff --git a/src/AgentCore.Application/Transcript/ViewMessage.cs b/src/AgentCore.Application/Transcript/ViewMessage.cs index ff34fc7c..ddd49dea 100644 --- a/src/AgentCore.Application/Transcript/ViewMessage.cs +++ b/src/AgentCore.Application/Transcript/ViewMessage.cs @@ -1,12 +1,13 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Transcript; - -/// -/// One message of a compaction view, with the last ordinal it stands for: a live row's own, or -/// what a standing summary covers. This is what lets the strategy's output land back on ordinals -/// instead of positions. -/// -/// The message, as the model would see it. -/// The last ordinal this message stands for, inclusive. -internal readonly record struct ViewMessage(ChatMessage Message, int LastOrdinal); +namespace AgentCore.Application.Transcript +{ + /// + /// One message of a compaction view, with the last ordinal it stands for: a live row's own, or + /// what a standing summary covers. This is what lets the strategy's output land back on ordinals + /// instead of positions. + /// + /// The message, as the model would see it. + /// The last ordinal this message stands for, inclusive. + internal readonly record struct ViewMessage(ChatMessage Message, int LastOrdinal); +} diff --git a/src/AgentCore.Application/Transcript/WithdrawnTurns.cs b/src/AgentCore.Application/Transcript/WithdrawnTurns.cs index e8ce0e74..8684e1f8 100644 --- a/src/AgentCore.Application/Transcript/WithdrawnTurns.cs +++ b/src/AgentCore.Application/Transcript/WithdrawnTurns.cs @@ -1,6 +1,7 @@ -namespace AgentCore.Application.Transcript; - -/// The span of turns one withdrawal took, both ends included. -/// The lowest turn index withdrawn. -/// The highest turn index withdrawn. -public readonly record struct WithdrawnTurns(int First, int Last); +namespace AgentCore.Application.Transcript +{ + /// The span of turns one withdrawal took, both ends included. + /// The lowest turn index withdrawn. + /// The highest turn index withdrawn. + public readonly record struct WithdrawnTurns(int First, int Last); +} diff --git a/src/AgentCore.AspNetCore/Conversation/ConnectionTaskObserver.cs b/src/AgentCore.AspNetCore/Conversation/ConnectionTaskObserver.cs index c64f62e2..5b5cba38 100644 --- a/src/AgentCore.AspNetCore/Conversation/ConnectionTaskObserver.cs +++ b/src/AgentCore.AspNetCore/Conversation/ConnectionTaskObserver.cs @@ -1,178 +1,182 @@ -namespace AgentCore.AspNetCore.Conversation; - -/// Which task an observer is watching, so it logs the right line. -internal enum ConnectionTaskKind +namespace AgentCore.AspNetCore.Conversation { - /// The loop that reads the transport. - ReadLoop, + /// Which task an observer is watching, so it logs the right line. + internal enum ConnectionTaskKind + { + /// The loop that reads the transport. + ReadLoop, - /// The task running one turn. - Turn, + /// The task running one turn. + Turn, - /// The loop that writes the transport. - WriteLoop, + /// The loop that writes the transport. + WriteLoop, - /// The wait for the conversation to end: its words reach store 1, then its session goes. - SessionClose, -} + /// The wait for the conversation to end: its words reach store 1, then its session goes. + SessionClose, + } -/// -/// Awaits the loops and turns of one connection, and never lets a fault go unobserved. -/// -/// Names the conversation in a log line. A function, because the id arrives mid-conversation. -/// Logs that a task passed its teardown deadline. -/// Logs a fault this observer could not classify. -/// -/// Gives an adapter first refusal on an exception, so a vendor-specific cause can be logged in its -/// own words. It returns when it handled the exception, and -/// to fall through to . It must not throw. -/// -internal sealed class ConnectionTaskObserver( - Func conversationId, - Action logTimeout, - Action logFault, - Func classify) -{ - /// Awaits a loop or a turn task, and never lets its fault go unobserved. - /// The read loop's task, the write loop's task, or a turn's task. - /// Which log line names the fault, if there is one. - /// - /// How long to wait before giving up on , or to - /// wait for it unconditionally. + /// + /// Awaits the loops and turns of one connection, and never lets a fault go unobserved. + /// + /// Names the conversation in a log line. A function, because the id arrives mid-conversation. + /// Logs that a task passed its teardown deadline. + /// Logs a fault this observer could not classify. + /// + /// Gives an adapter first refusal on an exception, so a vendor-specific cause can be logged in its + /// own words. It returns when it handled the exception, and + /// to fall through to . It must not throw. /// - /// A task that completes once has been observed. - /// - /// A cancellation raised by the connection's own token is teardown that connection asked for - /// itself, so it stays quiet. Anything else is the silence a voice conversation must never answer with, - /// per the house rule in . - /// - public async Task ObserveAsync(Task task, ConnectionTaskKind kind, TimeSpan? timeout = null) + internal sealed class ConnectionTaskObserver( + Func conversationId, + Action logTimeout, + Action logFault, + Func classify) { - try + /// Awaits a loop or a turn task, and never lets its fault go unobserved. + /// The read loop's task, the write loop's task, or a turn's task. + /// Which log line names the fault, if there is one. + /// + /// How long to wait before giving up on , or to + /// wait for it unconditionally. + /// + /// A task that completes once has been observed. + /// + /// A cancellation raised by the connection's own token is teardown that connection asked for + /// itself, so it stays quiet. Anything else is the silence a voice conversation must never answer with, + /// per the house rule in . + /// + public async Task ObserveAsync(Task task, ConnectionTaskKind kind, TimeSpan? timeout = null) { - if (timeout is { } bound) + try { - await task.WaitAsync(bound).ConfigureAwait(false); + if (timeout is { } bound) + { + await task.WaitAsync(bound).ConfigureAwait(false); + } + else + { + await task.ConfigureAwait(false); + } } - else + catch (OperationCanceledException) { - await task.ConfigureAwait(false); + // This connection's own token just cancelled it. That is teardown, not a fault. } - } - catch (OperationCanceledException) - { - // This connection's own token just cancelled it. That is teardown, not a fault. - } - catch (TimeoutException) when (timeout is not null) - { - SafeLog(() => logTimeout(conversationId(), DisplayName(kind))); + catch (TimeoutException) when (timeout is not null) + { + SafeLog(() => logTimeout(conversationId(), DisplayName(kind))); - // Task.WaitAsync removes its own continuation from task once the timeout fires, rather - // than leaving one behind to observe a later fault: a probe confirmed this directly. So - // if task faults afterward with nobody else watching, that fault surfaces only as an - // UnobservedTaskException raised during a GC — which produces no log line, and, under - // the default ThrowUnobservedTaskExceptions setting, does not crash the process either. - // Without a continuation of our own here, the real fault behind this timeout — a model - // fault, a tool fault, or the ObjectDisposedException from the token source teardown - // is about to dispose — would stay exactly that unseen. This continuation is what makes - // it visible instead. It does not await task, so it does not block; it can run inline on - // this thread if task happens to fault in the narrow window between the timeout firing - // and this line attaching it, which ExecuteSynchronously allows and which is harmless - // either way; and it must not throw, which LogFault's own SafeLog guard below - // guarantees. - _ = task.ContinueWith( - completed => LogFault(kind, completed.Exception?.GetBaseException()), - CancellationToken.None, - TaskContinuationOptions.OnlyOnFaulted | TaskContinuationOptions.ExecuteSynchronously, - TaskScheduler.Default); - } - catch (Exception fault) when (SafeClassify(fault, kind, conversationId())) - { - // The adapter recognised this one and logged it in its own words. It sits here, after - // the two clauses above and before the general one below, because a cause a vendor can - // name is more specific than this connection's own teardown but less specific than a - // cancellation it asked for itself. - } - catch (Exception fault) - { - LogFault(kind, fault); + // Task.WaitAsync removes its own continuation from task once the timeout fires, rather + // than leaving one behind to observe a later fault: a probe confirmed this directly. So + // if task faults afterward with nobody else watching, that fault surfaces only as an + // UnobservedTaskException raised during a GC — which produces no log line, and, under + // the default ThrowUnobservedTaskExceptions setting, does not crash the process either. + // Without a continuation of our own here, the real fault behind this timeout — a model + // fault, a tool fault, or the ObjectDisposedException from the token source teardown + // is about to dispose — would stay exactly that unseen. This continuation is what makes + // it visible instead. It does not await task, so it does not block; it can run inline on + // this thread if task happens to fault in the narrow window between the timeout firing + // and this line attaching it, which ExecuteSynchronously allows and which is harmless + // either way; and it must not throw, which LogFault's own SafeLog guard below + // guarantees. + _ = task.ContinueWith( + completed => LogFault(kind, completed.Exception?.GetBaseException()), + CancellationToken.None, + TaskContinuationOptions.OnlyOnFaulted | TaskContinuationOptions.ExecuteSynchronously, + TaskScheduler.Default); + } + catch (Exception fault) when (SafeClassify(fault, kind, conversationId())) + { + // The adapter recognised this one and logged it in its own words. It sits here, after + // the two clauses above and before the general one below, because a cause a vendor can + // name is more specific than this connection's own teardown but less specific than a + // cancellation it asked for itself. + } + catch (Exception fault) + { + LogFault(kind, fault); + } } - } - /// Runs one log conversation, and never lets it break the teardown sequence around it. - /// The conversation to make, already bound to its logger and its arguments. - /// - /// aggregates and rethrows a provider's own fault, so - /// even a line whose only job is to report a defect can itself throw. Every log conversation teardown - /// makes — cancelling the token, the close, an observed fault, a teardown timeout — sits behind - /// this guard for that reason; logging exists to help diagnose a defect, and must never become a - /// second one that stops the store removal or the rest of teardown from running. - /// - public static void SafeLog(Action log) - { - try + /// Runs one log conversation, and never lets it break the teardown sequence around it. + /// The conversation to make, already bound to its logger and its arguments. + /// + /// aggregates and rethrows a provider's own fault, so + /// even a line whose only job is to report a defect can itself throw. Every log conversation teardown + /// makes — cancelling the token, the close, an observed fault, a teardown timeout — sits behind + /// this guard for that reason; logging exists to help diagnose a defect, and must never become a + /// second one that stops the store removal or the rest of teardown from running. + /// + public static void SafeLog(Action log) { - log(); - } - catch (Exception) - { - // Nothing above this point can safely observe a logging fault either, so it stops here. + try + { + log(); + } + catch (Exception) + { + // Nothing above this point can safely observe a logging fault either, so it stops here. + } } - } - /// Names one for a log line, in the sentence it reads in. - /// Which task the sentence is about. - /// The name to read in that sentence. - private static string DisplayName(ConnectionTaskKind kind) => kind switch - { - ConnectionTaskKind.ReadLoop => "the read loop", - ConnectionTaskKind.Turn => "the last turn", - ConnectionTaskKind.WriteLoop => "the write loop", - ConnectionTaskKind.SessionClose => "the session close", - _ => "a task", - }; - - /// Hands a fault to logFault, whichever names. - /// Which task faulted. - /// The cause, or when none was available. - /// - /// Called from directly, and from the fault-only continuation it - /// attaches on a timeout. The continuation runs with nothing above it to catch a throw, so the - /// guard here is what keeps this method from ever throwing, not the - /// caller. - /// - private void LogFault(ConnectionTaskKind kind, Exception? fault) - { - if (fault is null) + /// Names one for a log line, in the sentence it reads in. + /// Which task the sentence is about. + /// The name to read in that sentence. + private static string DisplayName(ConnectionTaskKind kind) { - return; + return kind switch + { + ConnectionTaskKind.ReadLoop => "the read loop", + ConnectionTaskKind.Turn => "the last turn", + ConnectionTaskKind.WriteLoop => "the write loop", + ConnectionTaskKind.SessionClose => "the session close", + _ => "a task", + }; } - SafeLog(() => logFault(kind, conversationId(), fault)); - } - - /// Runs classify behind the same guard uses. - /// The exception the adapter gets first refusal on. - /// Which task faulted. - /// The conversation the fault belongs to. - /// - /// when the adapter handled itself, and - /// when it did not — including when it threw. - /// - /// - /// An adapter's classifier is another adapter's code running inside this connection's teardown, - /// and teardown must finish whatever that code does. A classifier that throws has handled - /// nothing, so the fault falls through to logFault exactly as an unrecognised one does. - /// - private bool SafeClassify(Exception fault, ConnectionTaskKind kind, string id) - { - try + /// Hands a fault to logFault, whichever names. + /// Which task faulted. + /// The cause, or when none was available. + /// + /// Called from directly, and from the fault-only continuation it + /// attaches on a timeout. The continuation runs with nothing above it to catch a throw, so the + /// guard here is what keeps this method from ever throwing, not the + /// caller. + /// + private void LogFault(ConnectionTaskKind kind, Exception? fault) { - return classify(fault, kind, id); + if (fault is null) + { + return; + } + + SafeLog(() => logFault(kind, conversationId(), fault)); } - catch (Exception) + + /// Runs classify behind the same guard uses. + /// The exception the adapter gets first refusal on. + /// Which task faulted. + /// The conversation the fault belongs to. + /// + /// when the adapter handled itself, and + /// when it did not — including when it threw. + /// + /// + /// An adapter's classifier is another adapter's code running inside this connection's teardown, + /// and teardown must finish whatever that code does. A classifier that throws has handled + /// nothing, so the fault falls through to logFault exactly as an unrecognised one does. + /// + private bool SafeClassify(Exception fault, ConnectionTaskKind kind, string id) { - return false; + try + { + return classify(fault, kind, id); + } + catch (Exception) + { + return false; + } } } } diff --git a/src/AgentCore.AspNetCore/Conversation/ConversationEndpointRouteBuilderExtensions.cs b/src/AgentCore.AspNetCore/Conversation/ConversationEndpointRouteBuilderExtensions.cs index 7ce63829..666aeca1 100644 --- a/src/AgentCore.AspNetCore/Conversation/ConversationEndpointRouteBuilderExtensions.cs +++ b/src/AgentCore.AspNetCore/Conversation/ConversationEndpointRouteBuilderExtensions.cs @@ -8,104 +8,109 @@ using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; -namespace AgentCore.AspNetCore.Conversation; - -/// -/// Maps the inbound conversation route, with the URL naming the entry, onto whichever transport the -/// document names. -/// -public static class ConversationEndpointRouteBuilderExtensions +namespace AgentCore.AspNetCore.Conversation { - /// The route parameter that names the entry, as {entry} in a pattern. - public const string EntryRouteParameter = "entry"; - - /// The route every entry answers on when the host names none. - public const string DefaultPattern = "/v1/{" + EntryRouteParameter + "}/call"; - - /// Maps every entry on , with the URL naming the entry. - /// The route builder of the host. - /// The mapped endpoint, so a host adds its own conventions. - public static IEndpointConventionBuilder MapCall(this IEndpointRouteBuilder endpoints) - => endpoints.MapCall(DefaultPattern); - - /// Maps every entry on one route, with the URL naming the entry. - /// The route builder of the host. - /// The route to answer on. It must carry the {entry} parameter. - /// The mapped endpoint, so a host adds its own conventions. - /// carries no {entry}. - public static IEndpointConventionBuilder MapCall(this IEndpointRouteBuilder endpoints, string pattern) + /// + /// Maps the inbound conversation route, with the URL naming the entry, onto whichever transport the + /// document names. + /// + public static class ConversationEndpointRouteBuilderExtensions { - ArgumentNullException.ThrowIfNull(endpoints); - ArgumentException.ThrowIfNullOrEmpty(pattern); + /// The route parameter that names the entry, as {entry} in a pattern. + public const string EntryRouteParameter = "entry"; + + /// The route every entry answers on when the host names none. + public const string DefaultPattern = "/v1/{" + EntryRouteParameter + "}/call"; - if (!pattern.Contains("{" + EntryRouteParameter + "}", StringComparison.Ordinal)) + /// Maps every entry on , with the URL naming the entry. + /// The route builder of the host. + /// The mapped endpoint, so a host adds its own conventions. + public static IEndpointConventionBuilder MapCall(this IEndpointRouteBuilder endpoints) { - throw new ArgumentException( - $"The pattern '{pattern}' carries no {{{EntryRouteParameter}}} parameter, so no URL can name " - + "an entry.", - nameof(pattern)); + return endpoints.MapCall(DefaultPattern); } - // Map, and not MapGet. An HTTP/2 WebSocket arrives as CONNECT rather than GET, and MapGet - // would answer 405 to it. - return endpoints.Map(pattern, (HttpContext http) => DispatchAsync(http, pattern)); - } - - /// Reads the entry the URL names, off the {entry} route parameter. - /// The request on a conversation route. - /// The entry key, or the empty string when the route carries none. - public static string EntryOf(HttpContext http) - { - ArgumentNullException.ThrowIfNull(http); - return http.Request.RouteValues[EntryRouteParameter] as string ?? string.Empty; - } - - private static Task DispatchAsync(HttpContext http, string pattern) - { - // GetService and never GetRequiredService, on purpose. A host may map this route with no - // AgentCore registration at all, and such a host must get a readable reason rather than a - // resolution failure. - if (http.RequestServices.GetService() is not { } boot) + /// Maps every entry on one route, with the URL naming the entry. + /// The route builder of the host. + /// The route to answer on. It must carry the {entry} parameter. + /// The mapped endpoint, so a host adds its own conventions. + /// carries no {entry}. + public static IEndpointConventionBuilder MapCall(this IEndpointRouteBuilder endpoints, string pattern) { - return NotRoutedAsync(http, pattern, "this host registered no AgentCore services"); + ArgumentNullException.ThrowIfNull(endpoints); + ArgumentException.ThrowIfNullOrEmpty(pattern); + + if (!pattern.Contains("{" + EntryRouteParameter + "}", StringComparison.Ordinal)) + { + throw new ArgumentException( + $"The pattern '{pattern}' carries no {{{EntryRouteParameter}}} parameter, so no URL can name " + + "an entry.", + nameof(pattern)); + } + + // Map, and not MapGet. An HTTP/2 WebSocket arrives as CONNECT rather than GET, and MapGet + // would answer 405 to it. + return endpoints.Map(pattern, http => DispatchAsync(http, pattern)); } - if (boot.ConversationHandler is not { } handler) + /// Reads the entry the URL names, off the {entry} route parameter. + /// The request on a conversation route. + /// The entry key, or the empty string when the route carries none. + public static string EntryOf(HttpContext http) { - return NotRoutedAsync(http, pattern, boot.ConversationUnroutable ?? "this host routes no inbound conversation"); + ArgumentNullException.ThrowIfNull(http); + return http.Request.RouteValues[EntryRouteParameter] as string ?? string.Empty; } - var entry = EntryOf(http); - - return boot.Entries.ConversationSessions.ContainsKey(entry) - ? handler(http) - : UnknownEntryAsync(http, EntryRegistry.UnknownEntryMessage(entry, boot.Entries.Entries)); - } - - private static async Task NotRoutedAsync(HttpContext http, string pattern, string reason) - { - var logger = (http.RequestServices.GetService() ?? NullLoggerFactory.Instance) - .CreateLogger(typeof(ConversationEndpointRouteBuilderExtensions).FullName!); + private static Task DispatchAsync(HttpContext http, string pattern) + { + // GetService and never GetRequiredService, on purpose. A host may map this route with no + // AgentCore registration at all, and such a host must get a readable reason rather than a + // resolution failure. + if (http.RequestServices.GetService() is not { } boot) + { + return NotRoutedAsync(http, pattern, "this host registered no AgentCore services"); + } + + if (boot.ConversationHandler is not { } handler) + { + return NotRoutedAsync(http, pattern, boot.ConversationUnroutable ?? "this host routes no inbound conversation"); + } + + string entry = EntryOf(http); + + return boot.Entries.ConversationSessions.ContainsKey(entry) + ? handler(http) + : UnknownEntryAsync(http, EntryRegistry.UnknownEntryMessage(entry, boot.Entries.Entries)); + } - ConversationRouteLog.RouteNotMapped(logger, pattern, reason); + private static async Task NotRoutedAsync(HttpContext http, string pattern, string reason) + { + ILogger logger = (http.RequestServices.GetService() ?? NullLoggerFactory.Instance) + .CreateLogger(typeof(ConversationEndpointRouteBuilderExtensions).FullName!); - await WriteProblemAsync(http, StatusCodes.Status503ServiceUnavailable, "This host routes no inbound conversation.", reason, pattern) - .ConfigureAwait(false); - } + ConversationRouteLog.RouteNotMapped(logger, pattern, reason); - private static Task UnknownEntryAsync(HttpContext http, string reason) - => WriteProblemAsync(http, StatusCodes.Status404NotFound, "No entry answers on this route.", reason, http.Request.Path); + await WriteProblemAsync(http, StatusCodes.Status503ServiceUnavailable, "This host routes no inbound conversation.", reason, pattern) + .ConfigureAwait(false); + } - private static async Task WriteProblemAsync(HttpContext http, int status, string title, string detail, string instance) - { - http.Response.StatusCode = status; + private static Task UnknownEntryAsync(HttpContext http, string reason) + { + return WriteProblemAsync(http, StatusCodes.Status404NotFound, "No entry answers on this route.", reason, http.Request.Path); + } - await http.Response.WriteAsJsonAsync(new ProblemDetails + private static async Task WriteProblemAsync(HttpContext http, int status, string title, string detail, string instance) { - Status = status, - Title = title, - Detail = detail, - Instance = instance, - }, http.RequestAborted).ConfigureAwait(false); + http.Response.StatusCode = status; + + await http.Response.WriteAsJsonAsync(new ProblemDetails + { + Status = status, + Title = title, + Detail = detail, + Instance = instance, + }, http.RequestAborted).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.AspNetCore/Conversation/ConversationRouteLog.cs b/src/AgentCore.AspNetCore/Conversation/ConversationRouteLog.cs index 3bd1b11d..cd19fbb6 100644 --- a/src/AgentCore.AspNetCore/Conversation/ConversationRouteLog.cs +++ b/src/AgentCore.AspNetCore/Conversation/ConversationRouteLog.cs @@ -1,33 +1,34 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.Conversation; - -/// The lines the conversation route writes while the host starts. -/// -/// Source-generated by , as CA1848 asks. Silently leaving a -/// route unmapped is how a deployment loses every call to a 404 with nothing to read, so each -/// reason says so once. -/// -internal static partial class ConversationRouteLog +namespace AgentCore.AspNetCore.Conversation { - /// The host registered no conversation adapter, or loaded no document. - /// The logger of the map-time gate, not of any conversation. - /// The route this host asked for and did not get. - /// What was missing, in the words a reader can act on. - [LoggerMessage( - EventId = 1, - Level = LogLevel.Information, - Message = "the conversation route '{Pattern}' is not mapped: {Reason}.")] - public static partial void RouteNotMapped(ILogger logger, string pattern, string reason); + /// The lines the conversation route writes while the host starts. + /// + /// Source-generated by , as CA1848 asks. Silently leaving a + /// route unmapped is how a deployment loses every call to a 404 with nothing to read, so each + /// reason says so once. + /// + internal static partial class ConversationRouteLog + { + /// The host registered no conversation adapter, or loaded no document. + /// The logger of the map-time gate, not of any conversation. + /// The route this host asked for and did not get. + /// What was missing, in the words a reader can act on. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Information, + Message = "the conversation route '{Pattern}' is not mapped: {Reason}.")] + public static partial void RouteNotMapped(ILogger logger, string pattern, string reason); - /// The document named a vendor this process dials out to, which owns no route. - /// The logger of the map-time gate, not of any conversation. - /// The providers.conversation.kind the document named. - /// The route this host asked for and did not get. - [LoggerMessage( - EventId = 2, - Level = LogLevel.Information, - Message = "providers.conversation names '{Kind}', which this process dials out to rather than " - + "being dialled in to, so the conversation route '{Pattern}' is not mapped.")] - public static partial void DialOutVendorMapsNoRoute(ILogger logger, string kind, string pattern); + /// The document named a vendor this process dials out to, which owns no route. + /// The logger of the map-time gate, not of any conversation. + /// The providers.conversation.kind the document named. + /// The route this host asked for and did not get. + [LoggerMessage( + EventId = 2, + Level = LogLevel.Information, + Message = "providers.conversation names '{Kind}', which this process dials out to rather than " + + "being dialled in to, so the conversation route '{Pattern}' is not mapped.")] + public static partial void DialOutVendorMapsNoRoute(ILogger logger, string kind, string pattern); + } } diff --git a/src/AgentCore.AspNetCore/Conversation/ConversationSeams.cs b/src/AgentCore.AspNetCore/Conversation/ConversationSeams.cs index fcff8ac8..24e5ae0b 100644 --- a/src/AgentCore.AspNetCore/Conversation/ConversationSeams.cs +++ b/src/AgentCore.AspNetCore/Conversation/ConversationSeams.cs @@ -1,11 +1,12 @@ using AgentCore.Application.Providers; -namespace AgentCore.AspNetCore.Conversation; - -/// The names the conversation seam uses in every failure it raises. -internal static class ConversationSeams +namespace AgentCore.AspNetCore.Conversation { - /// The providers.conversation seam. - public static readonly VendorSeam Conversation = - new("providers.conversation", "/providers/conversation/kind", "options.UseConversation(...)"); + /// The names the conversation seam uses in every failure it raises. + internal static class ConversationSeams + { + /// The providers.conversation seam. + public static readonly VendorSeam Conversation = + new("providers.conversation", "/providers/conversation/kind", "options.UseConversation(...)"); + } } diff --git a/src/AgentCore.AspNetCore/Conversation/ConversationTurnArbiter.cs b/src/AgentCore.AspNetCore/Conversation/ConversationTurnArbiter.cs index b6af0bc8..19247f47 100644 --- a/src/AgentCore.AspNetCore/Conversation/ConversationTurnArbiter.cs +++ b/src/AgentCore.AspNetCore/Conversation/ConversationTurnArbiter.cs @@ -1,75 +1,21 @@ using AgentCore.Application.Ports; +using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Conversation; - -/// -/// Decides which turn of one conversation may speak, and which one a barge-in cuts short. -/// -/// -/// -/// The first of the two barge-in gates lives here: once a turn is marked interrupted this class -/// stops handing its fragments to . The last gate, immediately -/// before the wire, belongs to the port's own implementation and is expressed in that -/// implementation's private vocabulary, so no turn id of this class ever crosses the port. -/// -/// -internal sealed class ConversationTurnArbiter +namespace AgentCore.AspNetCore.Conversation { - // Not readonly, and volatile for the same reason the connection's own session field is: a - // repeated setup frame replaces the conversation this arbiter runs turns against, and every turn that - // starts after it must run against the replacement. One arbiter serves the whole connection, - // across as many sessions as the vendor names, because "one turn at a time" is a property of - // the transport and not of any one session: a second arbiter would carry its own _turnActive, - // its own held prompt, and its own ids, and a prompt arriving while the replaced session's turn - // still ran would start a second turn writing into the same channel. - private volatile IConversationPort _session; - private readonly IConversationOutputPort _output; - private readonly ConnectionTaskObserver _observer; - private readonly Action _logPromptHeld; - private readonly Action _logPendingPromptDropped; - private readonly CancellationToken _connectionToken; - - private Task _turn = Task.CompletedTask; - private bool _loggedPendingPromptDropped; - - // Guards _turnId, _interruptedTurnId, _turnActive, _pendingPrompt, and every place _turn is - // read then reassigned. The read loop reaches this lock through StartTurnAsync and - // Interrupt, one frame at a time; a turn's own task reaches it too, from - // RunPendingPrompt, once it finishes. _turnId and _interruptedTurnId are also read without the - // lock, through Interlocked.Read, from inside a turn's own hot loop, where taking a lock on - // every update would slow the path this guard exists to protect. - private readonly Lock _turnLock = new(); - private long _turnId; - - // The id a barge-in invalidated, or 0 when nothing has been interrupted yet. This is a - // separate field from _turnId, not a reuse of it, because _turnId also advances on every - // ordinary turn transition — RunPendingPrompt mints the next id as soon as one turn's own task - // finishes, which can race ahead of the write loop still sending that turn's own trailing - // frames. A single shared "current id" field cannot tell "a newer turn has started normally" - // apart from "this turn was cut short": both look like a mismatch to a check that only asks - // "does this item's id equal the current one." Recording which id was interrupted, instead of - // just raising a shared counter, is what lets a turn's own guard ask the question that - // actually matters: was *this* turn, specifically, the one barge-in cut off, regardless of how - // many ordinary turns have started since. - private long _interruptedTurnId; - - // The newest turn whose output this arbiter has actually handed to the output port, or 0 while - // no turn has produced a word. It is not _turnId, and the difference is the whole of the - // barge-in target: the transport paces the audio itself, so turn N is still being spoken after - // its own stream ended, and RunPendingPrompt starts turn N+1 inside turn N's own finally. A - // barge-in in that window belongs to turn N — the turn the caller was hearing — and marking - // N+1 instead would drop every update of a turn nobody has heard yet and skip its closing - // last: true frame, leaving the caller with dead air and the vendor with an unfinished reply. - private long _spokenTurnId; - private bool _turnActive; - private string? _pendingPrompt; - - /// What a voice caller hears when a tool waits on an approval the conversation cannot take. - internal const string PendingApprovalNotice = - "That action needs a human approval, which this conversation can't take."; - - /// Builds the arbiter one conversation runs its turns through. - /// The conversation this arbiter runs turns against, until names another. + /// + /// Decides which turn of one conversation may speak, and which one a barge-in cuts short. + /// + /// + /// + /// The first of the two barge-in gates lives here: once a turn is marked interrupted this class + /// stops handing its fragments to . The last gate, immediately + /// before the wire, belongs to the port's own implementation and is expressed in that + /// implementation's private vocabulary, so no turn id of this class ever crosses the port. + /// + /// + /// Builds the arbiter one conversation runs its turns through. + /// /// Where a turn's reply goes, one fragment at a time. /// Watches a turn's task, and never lets its fault go unobserved. /// @@ -84,345 +30,394 @@ internal sealed class ConversationTurnArbiter /// Cancelled once, for any reason the transport is going away. Every turn reads it, and no /// held prompt starts a turn after it fires. /// - public ConversationTurnArbiter( - IConversationPort session, + internal sealed class ConversationTurnArbiter( + IConversationPort initialSession, IConversationOutputPort output, ConnectionTaskObserver observer, Action logPromptHeld, Action logPendingPromptDropped, CancellationToken connectionToken) { - _session = session; - _output = output; - _observer = observer; - _logPromptHeld = logPromptHeld; - _logPendingPromptDropped = logPendingPromptDropped; - _connectionToken = connectionToken; - } - - /// Gets the turn running now, or the one that ran last. - /// - /// Read under the same lock every writer takes. can reassign the - /// turn from a turn's own task, off the read loop, so teardown is not the only writer's own - /// reader: without the lock it could observe a stale reference and let the real last turn - /// finish unobserved. itself checks the connection token before - /// it will start a turn from a held prompt, which is what stops the reverse case — a fresh turn - /// appearing here after teardown already read it. - /// - public Task CurrentTurn - { - get + // Not readonly, and volatile for the same reason the connection's own session field is: a + // repeated setup frame replaces the conversation this arbiter runs turns against, and every turn that + // starts after it must run against the replacement. One arbiter serves the whole connection, + // across as many sessions as the vendor names, because "one turn at a time" is a property of + // the transport and not of any one session: a second arbiter would carry its own _turnActive, + // its own held prompt, and its own ids, and a prompt arriving while the replaced session's turn + // still ran would start a second turn writing into the same channel. + private volatile IConversationPort _session = initialSession; + private readonly IConversationOutputPort _output = output; + private readonly ConnectionTaskObserver _observer = observer; + private readonly Action _logPromptHeld = logPromptHeld; + private readonly Action _logPendingPromptDropped = logPendingPromptDropped; + private readonly CancellationToken _connectionToken = connectionToken; + + private Task _turn = Task.CompletedTask; + private bool _loggedPendingPromptDropped; + + // Guards _turnId, _interruptedTurnId, _turnActive, _pendingPrompt, and every place _turn is + // read then reassigned. The read loop reaches this lock through StartTurnAsync and + // Interrupt, one frame at a time; a turn's own task reaches it too, from + // RunPendingPrompt, once it finishes. _turnId and _interruptedTurnId are also read without the + // lock, through Interlocked.Read, from inside a turn's own hot loop, where taking a lock on + // every update would slow the path this guard exists to protect. + private readonly Lock _turnLock = new(); + private long _turnId; + + // The id a barge-in invalidated, or 0 when nothing has been interrupted yet. This is a + // separate field from _turnId, not a reuse of it, because _turnId also advances on every + // ordinary turn transition — RunPendingPrompt mints the next id as soon as one turn's own task + // finishes, which can race ahead of the write loop still sending that turn's own trailing + // frames. A single shared "current id" field cannot tell "a newer turn has started normally" + // apart from "this turn was cut short": both look like a mismatch to a check that only asks + // "does this item's id equal the current one." Recording which id was interrupted, instead of + // just raising a shared counter, is what lets a turn's own guard ask the question that + // actually matters: was *this* turn, specifically, the one barge-in cut off, regardless of how + // many ordinary turns have started since. + private long _interruptedTurnId; + + // The newest turn whose output this arbiter has actually handed to the output port, or 0 while + // no turn has produced a word. It is not _turnId, and the difference is the whole of the + // barge-in target: the transport paces the audio itself, so turn N is still being spoken after + // its own stream ended, and RunPendingPrompt starts turn N+1 inside turn N's own finally. A + // barge-in in that window belongs to turn N — the turn the caller was hearing — and marking + // N+1 instead would drop every update of a turn nobody has heard yet and skip its closing + // last: true frame, leaving the caller with dead air and the vendor with an unfinished reply. + private long _spokenTurnId; + private bool _turnActive; + private string? _pendingPrompt; + + /// What a voice caller hears when a tool waits on an approval the conversation cannot take. + internal const string PendingApprovalNotice = + "That action needs a human approval, which this conversation can't take."; + + /// Gets the turn running now, or the one that ran last. + /// + /// Read under the same lock every writer takes. can reassign the + /// turn from a turn's own task, off the read loop, so teardown is not the only writer's own + /// reader: without the lock it could observe a stale reference and let the real last turn + /// finish unobserved. itself checks the connection token before + /// it will start a turn from a held prompt, which is what stops the reverse case — a fresh turn + /// appearing here after teardown already read it. + /// + public Task CurrentTurn { - lock (_turnLock) + get { - return _turn; + lock (_turnLock) + { + return _turn; + } } } - } - /// Points this arbiter at another conversation, keeping every turn it is already running. - /// The conversation every turn started from now on runs against. - /// - /// For the one caller that needs it: a transport whose vendor names the conversation a second time on - /// one connection. Only the session moves. _turnActive, the held prompt, the ids, and the - /// log-once flag all stay exactly where they are, because "one turn at a time" and "one held - /// prompt, logged once" are promises this connection makes for its whole life and not for one - /// session of it. A turn already in flight keeps the session it started on, the same way it - /// would have before this method existed. - /// - public void Rebind(IConversationPort session) => _session = session; - - /// Starts a turn for what the caller just said, or holds it until the turn in flight ends. - /// What the caller said. - /// - /// The turn this conversation started, or a completed task when the prompt was held or dropped. It - /// reports only completion: a turn's own fault stays on , which the - /// next turn and teardown both already observe through . - /// - public Task StartTurnAsync(string text) - { - // Read once, here, so the turn this conversation starts and the line it may log about holding the - // prompt both name the conversation the setup frame most recently gave this connection. - var session = _session; + /// Points this arbiter at another conversation, keeping every turn it is already running. + /// The conversation every turn started from now on runs against. + /// + /// For the one caller that needs it: a transport whose vendor names the conversation a second time on + /// one connection. Only the session moves. _turnActive, the held prompt, the ids, and the + /// log-once flag all stay exactly where they are, because "one turn at a time" and "one held + /// prompt, logged once" are promises this connection makes for its whole life and not for one + /// session of it. A turn already in flight keeps the session it started on, the same way it + /// would have before this method existed. + /// + public void Rebind(IConversationPort session) + { + _session = session; + } - Task justFinished; - lock (_turnLock) + /// Starts a turn for what the caller just said, or holds it until the turn in flight ends. + /// What the caller said. + /// + /// The turn this conversation started, or a completed task when the prompt was held or dropped. It + /// reports only completion: a turn's own fault stays on , which the + /// next turn and teardown both already observe through . + /// + public Task StartTurnAsync(string text) { - if (_turnActive) + // Read once, here, so the turn this conversation starts and the line it may log about holding the + // prompt both name the conversation the setup frame most recently gave this connection. + IConversationPort session = _session; + + Task justFinished; + lock (_turnLock) { - // The caller finished a second sentence before the agent spoke. There is no - // interrupt frame for this, because the vendor never truncated anything, so there - // is no heard text to record. IConversationPort throws on a second turn of one - // conversation, and a throw here would drop it, so one prompt is held and runs once the - // turn in flight ends. Item 6a of section 11 draws the line at one: a queue of - // held prompts would answer questions the caller has already moved past, so a - // third prompt is dropped instead of queued behind the first. - // - // _turnActive, not _turn.IsCompleted: RunPendingPrompt runs inside RunTurnAsync's - // own finally, strictly before that turn's Task itself transitions to completed, so - // a check against IsCompleted here could see "no turn running" for a conversation whose own - // RunPendingPrompt had already run and found nothing pending — losing this prompt - // outright, since nothing would ever come back to run it. _turnActive is cleared by - // RunPendingPrompt in that same lock acquisition instead, so this check and that - // clear can never miss each other. - if (_pendingPrompt is null) + if (_turnActive) { - _pendingPrompt = text; - _logPromptHeld(session.ConversationId); - } - else if (!_loggedPendingPromptDropped) - { - // Log once for the conversation, not once for the frame. Same rule as the - // unknown-frame line. - _loggedPendingPromptDropped = true; - _logPendingPromptDropped(session.ConversationId); + // The caller finished a second sentence before the agent spoke. There is no + // interrupt frame for this, because the vendor never truncated anything, so there + // is no heard text to record. IConversationPort throws on a second turn of one + // conversation, and a throw here would drop it, so one prompt is held and runs once the + // turn in flight ends. Item 6a of section 11 draws the line at one: a queue of + // held prompts would answer questions the caller has already moved past, so a + // third prompt is dropped instead of queued behind the first. + // + // _turnActive, not _turn.IsCompleted: RunPendingPrompt runs inside RunTurnAsync's + // own finally, strictly before that turn's Task itself transitions to completed, so + // a check against IsCompleted here could see "no turn running" for a conversation whose own + // RunPendingPrompt had already run and found nothing pending — losing this prompt + // outright, since nothing would ever come back to run it. _turnActive is cleared by + // RunPendingPrompt in that same lock acquisition instead, so this check and that + // clear can never miss each other. + if (_pendingPrompt is null) + { + _pendingPrompt = text; + _logPromptHeld(session.ConversationId); + } + else if (!_loggedPendingPromptDropped) + { + // Log once for the conversation, not once for the frame. Same rule as the + // unknown-frame line. + _loggedPendingPromptDropped = true; + _logPendingPromptDropped(session.ConversationId); + } + + return Task.CompletedTask; } - return Task.CompletedTask; + justFinished = _turn; + _turnActive = true; } - justFinished = _turn; - _turnActive = true; + return StartAfterAsync(session, text, justFinished); } - return StartAfterAsync(session, text, justFinished); - } - - /// Ends the running turn where the caller cut the reply off, and stops the audio behind it. - /// The text the caller actually heard, as the transport reported it. - /// How much of the reply played, as the transport reported it. - /// - /// when the conversation recorded the barge-in, against the running turn or - /// against the turn that finished last, and when there was nothing to - /// record it against. - /// - /// - /// Synchronous, and it stays synchronous. It marks the interrupted id, decides - /// cutsRunningTurn, and calls before anything - /// awaits, and it hands 's task to the observer rather - /// than awaiting it: this runs on the read loop, and a read loop that blocks cannot receive the - /// next frame. - /// - public bool Interrupt(string heardText, TimeSpan playedDuration) - { - // Read once, here, so the record goes to the conversation the setup frame most recently named — the - // same field, read at the same point, as when this method still lived on the connection. - var session = _session; - - bool cutsRunningTurn; - lock (_turnLock) + /// Ends the running turn where the caller cut the reply off, and stops the audio behind it. + /// The text the caller actually heard, as the transport reported it. + /// How much of the reply played, as the transport reported it. + /// + /// when the conversation recorded the barge-in, against the running turn or + /// against the turn that finished last, and when there was nothing to + /// record it against. + /// + /// + /// Synchronous, and it stays synchronous. It marks the interrupted id, decides + /// cutsRunningTurn, and calls before anything + /// awaits, and it hands 's task to the observer rather + /// than awaiting it: this runs on the read loop, and a read loop that blocks cannot receive the + /// next frame. + /// + public bool Interrupt(string heardText, TimeSpan playedDuration) { - // Mark before cancelling. Every project that solves this race does it in this order: - // a token already past the guard in RunTurnAsync must find its own id already marked - // interrupted right here, not a cancellation that is still on its way to the model - // conversation. - // - // _spokenTurnId is what is marked, and never _turnId. The two differ exactly when a - // held prompt fired: turn N finishes streaming, RunPendingPrompt starts turn N+1 inside - // turn N's own finally, and the transport is still speaking turn N. _turnId then names - // N+1, a turn the caller has not heard one word of, and marking it would silence it and - // skip its closing frame. _spokenTurnId names the turn whose output actually reached - // the transport, which is the turn the caller was hearing and the only one a barge-in - // may cut. - // - // Zero means no turn has produced a word yet, so there is nothing to cut short and the - // mark stays where it was. - var spoken = Interlocked.Read(ref _spokenTurnId); - if (spoken != 0) - { - Interlocked.Exchange(ref _interruptedTurnId, spoken); - } + // Read once, here, so the record goes to the conversation the setup frame most recently named — the + // same field, read at the same point, as when this method still lived on the connection. + IConversationPort session = _session; - // The same comparison the mark above rests on, carried across the seam. ConversationSession - // cannot reach it: it decides from whether the *running* turn is audible to it, and a - // turn is audible to it the moment it hands over any content at all — a tool call, a - // line of reasoning — none of which is a word the transport ever spoke. So turn N+1 can - // be audible to the core while _spokenTurnId still names turn N, which is the turn the - // transport is still playing and the only one the caller has heard. Deciding here, where - // both ids are known and already under the lock that guards them, is what puts the heard - // text on turn N instead of on a turn nobody has heard one word of. - // - // Zero answers false as well. Nothing of this conversation has reached the transport, so there - // is no running turn the caller was hearing, and cutting one short would destroy a reply - // against nothing — the same rule the mark above already follows by staying put. - cutsRunningTurn = spoken != 0 && spoken == Interlocked.Read(ref _turnId); - } + bool cutsRunningTurn; + lock (_turnLock) + { + // Mark before cancelling. Every project that solves this race does it in this order: + // a token already past the guard in RunTurnAsync must find its own id already marked + // interrupted right here, not a cancellation that is still on its way to the model + // conversation. + // + // _spokenTurnId is what is marked, and never _turnId. The two differ exactly when a + // held prompt fired: turn N finishes streaming, RunPendingPrompt starts turn N+1 inside + // turn N's own finally, and the transport is still speaking turn N. _turnId then names + // N+1, a turn the caller has not heard one word of, and marking it would silence it and + // skip its closing frame. _spokenTurnId names the turn whose output actually reached + // the transport, which is the turn the caller was hearing and the only one a barge-in + // may cut. + // + // Zero means no turn has produced a word yet, so there is nothing to cut short and the + // mark stays where it was. + long spoken = Interlocked.Read(ref _spokenTurnId); + if (spoken != 0) + { + _ = Interlocked.Exchange(ref _interruptedTurnId, spoken); + } - // The transport measured both values itself. D28 and item 6a: nothing here estimates either - // one. A false result means there was no turn to record the barge-in against — not merely - // that none was running, because a turn that already ended is amended rather than ignored. - var recorded = session.Interrupt(heardText, playedDuration, cutsRunningTurn); + // The same comparison the mark above rests on, carried across the seam. ConversationSession + // cannot reach it: it decides from whether the *running* turn is audible to it, and a + // turn is audible to it the moment it hands over any content at all — a tool call, a + // line of reasoning — none of which is a word the transport ever spoke. So turn N+1 can + // be audible to the core while _spokenTurnId still names turn N, which is the turn the + // transport is still playing and the only one the caller has heard. Deciding here, where + // both ids are known and already under the lock that guards them, is what puts the heard + // text on turn N instead of on a turn nobody has heard one word of. + // + // Zero answers false as well. Nothing of this conversation has reached the transport, so there + // is no running turn the caller was hearing, and cutting one short would destroy a reply + // against nothing — the same rule the mark above already follows by staying put. + cutsRunningTurn = spoken != 0 && spoken == Interlocked.Read(ref _turnId); + } - // The transport already stopped its own audio, and anything the port still holds is the - // only audio left that could start it playing again. Handed to the observer rather than - // awaited: this runs on the read loop, and a read loop that blocks cannot receive the next - // frame. StopAsync itself is called here, before the discard, so whatever it does - // synchronously — dropping what has not been spoken — has already happened by the time this - // method returns. - _ = _observer.ObserveAsync(_output.StopAsync(_connectionToken).AsTask(), ConnectionTaskKind.WriteLoop); + // The transport measured both values itself. D28 and item 6a: nothing here estimates either + // one. A false result means there was no turn to record the barge-in against — not merely + // that none was running, because a turn that already ended is amended rather than ignored. + bool recorded = session.Interrupt(heardText, playedDuration, cutsRunningTurn); - return recorded; - } + // The transport already stopped its own audio, and anything the port still holds is the + // only audio left that could start it playing again. Handed to the observer rather than + // awaited: this runs on the read loop, and a read loop that blocks cannot receive the next + // frame. StopAsync itself is called here, before the discard, so whatever it does + // synchronously — dropping what has not been spoken — has already happened by the time this + // method returns. + _ = _observer.ObserveAsync(_output.StopAsync(_connectionToken).AsTask(), ConnectionTaskKind.WriteLoop); - /// Observes the turn that just ended, then starts the next one and follows it to its end. - /// The conversation the turn this starts runs against. - /// What the caller said. - /// The turn this conversation read out of . - /// A task that completes when the turn this conversation starts completes. - private async Task StartAfterAsync(IConversationPort session, string text, Task justFinished) - { - // A conversation runs many turns, and CurrentTurn only ever holds the most recent one. Observing the - // finished turn here is what stops a turn that faulted mid-conversation from being silently - // replaced by the next one before anything looks at it. The in-flight guard above only - // proved _turnActive was false, not that justFinished itself has completed: RunPendingPrompt - // clears _turnActive from inside RunTurnAsync's own finally, strictly before that turn's - // Task transitions to completed, so a moment can exist where _turnActive already reads false - // while justFinished is still finishing the last step of its own async state machine. This - // await can therefore still yield here, but only for as long as that tail takes to unwind — - // microseconds — which is why it is safe to await inline rather than fire-and-forget. Only - // the very last turn of the conversation still relies on teardown's own observation. - await _observer.ObserveAsync(justFinished, ConnectionTaskKind.Turn).ConfigureAwait(false); + return recorded; + } - Task started; - lock (_turnLock) + /// Observes the turn that just ended, then starts the next one and follows it to its end. + /// The conversation the turn this starts runs against. + /// What the caller said. + /// The turn this conversation read out of . + /// A task that completes when the turn this conversation starts completes. + private async Task StartAfterAsync(IConversationPort session, string text, Task justFinished) { - // Teardown may have completed while the previous turn unwound; a turn started now - // would outlive the connection's own wait. - if (_connectionToken.IsCancellationRequested) + // A conversation runs many turns, and CurrentTurn only ever holds the most recent one. Observing the + // finished turn here is what stops a turn that faulted mid-conversation from being silently + // replaced by the next one before anything looks at it. The in-flight guard above only + // proved _turnActive was false, not that justFinished itself has completed: RunPendingPrompt + // clears _turnActive from inside RunTurnAsync's own finally, strictly before that turn's + // Task transitions to completed, so a moment can exist where _turnActive already reads false + // while justFinished is still finishing the last step of its own async state machine. This + // await can therefore still yield here, but only for as long as that tail takes to unwind — + // microseconds — which is why it is safe to await inline rather than fire-and-forget. Only + // the very last turn of the conversation still relies on teardown's own observation. + await _observer.ObserveAsync(justFinished, ConnectionTaskKind.Turn).ConfigureAwait(false); + + Task started; + lock (_turnLock) { - _turnActive = false; - return; - } + // Teardown may have completed while the previous turn unwound; a turn started now + // would outlive the connection's own wait. + if (_connectionToken.IsCancellationRequested) + { + _turnActive = false; + return; + } - var turnId = Interlocked.Increment(ref _turnId); - started = _turn = RunTurnAsync(session, text, turnId); - } + long turnId = Interlocked.Increment(ref _turnId); + started = _turn = RunTurnAsync(session, text, turnId); + } - try - { - await started.ConfigureAwait(false); - } - catch (Exception) - { - // Swallowed here on purpose, and only here. The task this method returns exists so a - // caller can follow the turn to its end; the fault itself stays on CurrentTurn, which - // the next turn's own observation above and teardown's both already report through - // ConnectionTaskObserver. Reporting it a second time here would log one fault twice. + try + { + await started.ConfigureAwait(false); + } + catch (Exception) + { + // Swallowed here on purpose, and only here. The task this method returns exists so a + // caller can follow the turn to its end; the fault itself stays on CurrentTurn, which + // the next turn's own observation above and teardown's both already report through + // ConnectionTaskObserver. Reporting it a second time here would log one fault twice. + } } - } - /// Runs one turn end to end, and streams its reply to the output port. - /// - /// The conversation this turn runs against. Passed in rather than read off the field, so a turn already - /// in flight when names another conversation still finishes on the one it started on. - /// - /// What the caller said. - /// The id this turn's output is marked with. - /// A task that completes when the turn has ended, however it ended. - private async Task RunTurnAsync(IConversationPort session, string text, long turnId) - { - try + /// Runs one turn end to end, and streams its reply to the output port. + /// + /// The conversation this turn runs against. Passed in rather than read off the field, so a turn already + /// in flight when names another conversation still finishes on the one it started on. + /// + /// What the caller said. + /// The id this turn's output is marked with. + /// A task that completes when the turn has ended, however it ended. + private async Task RunTurnAsync(IConversationPort session, string text, long turnId) { - await foreach (var update in session - .RunTurnStreamingAsync(text, _connectionToken) - .ConfigureAwait(false)) + try { - // This check narrows the race; it does not close it. It sits after the await on the - // enumerator and before the await on the output port, so it stops every update the - // model produces *after* Interrupt marks this turn interrupted. It cannot stop - // an update already past this line at that moment — already queued inside the port, - // or parked inside SpeakAsync waiting for room — so the port's own last gate, - // immediately before the wire, is what actually keeps a straggler off the wire. - // That gate reads the port's own reply generation rather than this id, because no - // turn id of this class may cross the port; StopAsync raises the generation, and - // every fragment already queued under the old one is dropped there. The check is - // against _interruptedTurnId, not _turnId: a later, ordinary turn starting also - // moves _turnId, and that alone must not silence a turn nothing actually - // interrupted. - // - // continue, not return: abandoning the enumeration here would dispose - // ConversationSession's own iterator from the outside, which unwinds it past the code that - // records the interruption on LastTurn rather than through it. Session.Interrupt - // already asked the model call to stop; this loop still has to drain whatever - // update that call already had in flight so ConversationSession reaches its own ending on - // its own terms. Every update after the raised id is read and thrown away instead - // of queued, which is what keeps the queue itself from growing on a barge-in. - if (Interlocked.Read(ref _interruptedTurnId) == turnId) + await foreach (ChatResponseUpdate? update in session + .RunTurnStreamingAsync(text, _connectionToken) + .ConfigureAwait(false)) { - continue; + // This check narrows the race; it does not close it. It sits after the await on the + // enumerator and before the await on the output port, so it stops every update the + // model produces *after* Interrupt marks this turn interrupted. It cannot stop + // an update already past this line at that moment — already queued inside the port, + // or parked inside SpeakAsync waiting for room — so the port's own last gate, + // immediately before the wire, is what actually keeps a straggler off the wire. + // That gate reads the port's own reply generation rather than this id, because no + // turn id of this class may cross the port; StopAsync raises the generation, and + // every fragment already queued under the old one is dropped there. The check is + // against _interruptedTurnId, not _turnId: a later, ordinary turn starting also + // moves _turnId, and that alone must not silence a turn nothing actually + // interrupted. + // + // continue, not return: abandoning the enumeration here would dispose + // ConversationSession's own iterator from the outside, which unwinds it past the code that + // records the interruption on LastTurn rather than through it. Session.Interrupt + // already asked the model call to stop; this loop still has to drain whatever + // update that call already had in flight so ConversationSession reaches its own ending on + // its own terms. Every update after the raised id is read and thrown away instead + // of queued, which is what keeps the queue itself from growing on a barge-in. + if (Interlocked.Read(ref _interruptedTurnId) == turnId) + { + continue; + } + + if (update.Text is { Length: > 0 } piece) + { + // Marked before the write, not after it. Once a piece is committed to the + // port the caller is going to hear it, and a barge-in that lands while this + // write waits on backpressure still belongs to this turn. The ids only ever + // increase here, because RunPendingPrompt starts the next turn from inside this + // turn's own finally, so a plain exchange cannot move this value backwards. + _ = Interlocked.Exchange(ref _spokenTurnId, turnId); + + await _output.SpeakAsync(piece, _connectionToken).ConfigureAwait(false); + } } - if (update.Text is { Length: > 0 } piece) + if (Interlocked.Read(ref _interruptedTurnId) != turnId) { - // Marked before the write, not after it. Once a piece is committed to the - // port the caller is going to hear it, and a barge-in that lands while this - // write waits on backpressure still belongs to this turn. The ids only ever - // increase here, because RunPendingPrompt starts the next turn from inside this - // turn's own finally, so a plain exchange cannot move this value backwards. - Interlocked.Exchange(ref _spokenTurnId, turnId); - - await _output.SpeakAsync(piece, _connectionToken).ConfigureAwait(false); + if (session.LastTurn?.Approvals is { Count: > 0 }) + { + // A tool waits on a human answer, and a voice conversation has no surface to give one. + // Say so instead of hanging in the silence the pending turn speaks. + await _output.SpeakAsync(PendingApprovalNotice, _connectionToken).ConfigureAwait(false); + } + + // The vendor closes a reply on last: true, and the sample uses an empty final + // token when the stream ended with no trailing text. A barge-in already ended + // this turn, so a closing frame now would speak a reply the caller cut off. + await _output.CompleteAsync(_connectionToken).ConfigureAwait(false); } } - - if (Interlocked.Read(ref _interruptedTurnId) != turnId) + catch (OperationCanceledException) { - if (session.LastTurn?.Approvals is { Count: > 0 }) - { - // A tool waits on a human answer, and a voice conversation has no surface to give one. - // Say so instead of hanging in the silence the pending turn speaks. - await _output.SpeakAsync(PendingApprovalNotice, _connectionToken).ConfigureAwait(false); - } - - // The vendor closes a reply on last: true, and the sample uses an empty final - // token when the stream ended with no trailing text. A barge-in already ended - // this turn, so a closing frame now would speak a reply the caller cut off. - await _output.CompleteAsync(_connectionToken).ConfigureAwait(false); + // ConversationSession absorbs a barge-in's own cancellation internally and ends the turn + // normally, so what reaches here is the connection's own teardown token instead. The + // conversation itself goes on; only this turn stops. + } + finally + { + RunPendingPrompt(); } } - catch (OperationCanceledException) - { - // ConversationSession absorbs a barge-in's own cancellation internally and ends the turn - // normally, so what reaches here is the connection's own teardown token instead. The - // conversation itself goes on; only this turn stops. - } - finally - { - RunPendingPrompt(); - } - } - /// Starts the one prompt held while this turn ran. - /// - /// Called from a turn's own finally, so it runs on whichever thread that turn happens - /// to finish on — never the read loop, and strictly before the Task - /// returns actually completes. Reading , clearing or handing it to a new turn, and reassigning all - /// happen inside one lock acquisition, because a caller of that - /// reads _turnActive as false must also see as null in that - /// same instant — otherwise both this method and that caller could start a turn at once. - /// - private void RunPendingPrompt() - { - lock (_turnLock) + /// Starts the one prompt held while this turn ran. + /// + /// Called from a turn's own finally, so it runs on whichever thread that turn happens + /// to finish on — never the read loop, and strictly before the Task + /// returns actually completes. Reading , clearing or handing it to a new turn, and reassigning all + /// happen inside one lock acquisition, because a caller of that + /// reads _turnActive as false must also see as null in that + /// same instant — otherwise both this method and that caller could start a turn at once. + /// + private void RunPendingPrompt() { - // The connection is tearing down, so a fresh turn here would speak after the transport - // stopped reading, and teardown's own read of CurrentTurn (also under this lock) may - // already have captured the task this conversation is inside of — leaving a turn nothing waits - // for. The caller's last sentence goes unanswered either way once the socket is gone. - if (_pendingPrompt is not { } held || _connectionToken.IsCancellationRequested) + lock (_turnLock) { - _turnActive = false; - return; - } + // The connection is tearing down, so a fresh turn here would speak after the transport + // stopped reading, and teardown's own read of CurrentTurn (also under this lock) may + // already have captured the task this conversation is inside of — leaving a turn nothing waits + // for. The caller's last sentence goes unanswered either way once the socket is gone. + if (_pendingPrompt is not { } held || _connectionToken.IsCancellationRequested) + { + _turnActive = false; + return; + } - _pendingPrompt = null; - var turnId = Interlocked.Increment(ref _turnId); + _pendingPrompt = null; + long turnId = Interlocked.Increment(ref _turnId); - // Read here and not captured when the prompt was held: a setup frame that named another - // conversation in between makes that call the one to answer, which is the rule the connection - // followed when this method still lived there. - _turn = RunTurnAsync(_session, held, turnId); + // Read here and not captured when the prompt was held: a setup frame that named another + // conversation in between makes that call the one to answer, which is the rule the connection + // followed when this method still lived there. + _turn = RunTurnAsync(_session, held, turnId); + } } } } diff --git a/src/AgentCore.AspNetCore/Conversation/FrameOutcome.cs b/src/AgentCore.AspNetCore/Conversation/FrameOutcome.cs index ef1cf2b1..88e919a7 100644 --- a/src/AgentCore.AspNetCore/Conversation/FrameOutcome.cs +++ b/src/AgentCore.AspNetCore/Conversation/FrameOutcome.cs @@ -1,7 +1,8 @@ -namespace AgentCore.AspNetCore.Conversation; - -/// What reading one inbound message produced. -/// The parsed frame, or when none was read. -/// The discriminator no case matched, or . -/// The known discriminator whose body would not bind, or . -internal readonly record struct FrameOutcome(object? Frame, string? UnknownType, string? RefusedType); +namespace AgentCore.AspNetCore.Conversation +{ + /// What reading one inbound message produced. + /// The parsed frame, or when none was read. + /// The discriminator no case matched, or . + /// The known discriminator whose body would not bind, or . + internal readonly record struct FrameOutcome(object? Frame, string? UnknownType, string? RefusedType); +} diff --git a/src/AgentCore.AspNetCore/Conversation/FrameParser.cs b/src/AgentCore.AspNetCore/Conversation/FrameParser.cs index ea90df8d..7fb152ca 100644 --- a/src/AgentCore.AspNetCore/Conversation/FrameParser.cs +++ b/src/AgentCore.AspNetCore/Conversation/FrameParser.cs @@ -1,6 +1,7 @@ -namespace AgentCore.AspNetCore.Conversation; - -/// Reads one reassembled inbound message into a . -/// The whole message, already reassembled. -/// What the adapter's own reader made of those bytes. -internal delegate FrameOutcome FrameParser(ReadOnlySpan utf8); +namespace AgentCore.AspNetCore.Conversation +{ + /// Reads one reassembled inbound message into a . + /// The whole message, already reassembled. + /// What the adapter's own reader made of those bytes. + internal delegate FrameOutcome FrameParser(ReadOnlySpan utf8); +} diff --git a/src/AgentCore.AspNetCore/Conversation/IConversationTransportAdapter.cs b/src/AgentCore.AspNetCore/Conversation/IConversationTransportAdapter.cs index a2a595f6..9151df56 100644 --- a/src/AgentCore.AspNetCore/Conversation/IConversationTransportAdapter.cs +++ b/src/AgentCore.AspNetCore/Conversation/IConversationTransportAdapter.cs @@ -2,19 +2,20 @@ using AgentCore.Application.Ports; using Microsoft.AspNetCore.Http; -namespace AgentCore.AspNetCore.Conversation; - -/// -/// A conversation vendor this process is dialled in to, which therefore owns an inbound route. -/// -public interface IConversationTransportAdapter : IConversationAdapter +namespace AgentCore.AspNetCore.Conversation { - /// Builds the handler the conversation route answers every entry with. - /// The providers.conversation block, including its limits. - /// - /// The delegate the conversation route runs. The URL names the entry, and the route has already - /// refused one the document does not declare; the handler reads it with - /// . - /// - RequestDelegate CreateHandler(ConversationProviderConfiguration configuration); + /// + /// A conversation vendor this process is dialled in to, which therefore owns an inbound route. + /// + public interface IConversationTransportAdapter : IConversationAdapter + { + /// Builds the handler the conversation route answers every entry with. + /// The providers.conversation block, including its limits. + /// + /// The delegate the conversation route runs. The URL names the entry, and the route has already + /// refused one the document does not declare; the handler reads it with + /// . + /// + RequestDelegate CreateHandler(ConversationProviderConfiguration configuration); + } } diff --git a/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPump.cs b/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPump.cs index d0bf691d..e185220b 100644 --- a/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPump.cs +++ b/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPump.cs @@ -3,392 +3,395 @@ using System.Text.Json; using System.Threading.Channels; -namespace AgentCore.AspNetCore.Conversation; - -/// -/// The read loop, the write loop, and the close of one duplex JSON-over-WebSocket connection. -/// -/// -/// -/// Moved out of the Telnyx connection with its comments intact. Every duplex conversation adapter reads -/// one message at a time off a socket that fragments where it likes, sends from exactly one task -/// because a WebSocket supports one send at a time, and closes on a bounded deadline — and none of -/// that names a vendor. The three seams that would have are delegates: the parse, the exception -/// factory, and the log callbacks. -/// -/// -/// Nothing here decides what a message means or what a reply is worth sending. The parse belongs to -/// the adapter's own reader, and so does the gate in front of the write loop's one send: an item -/// that a barge-in already cut off is stale in the output port's vocabulary, not the transport's, -/// so only asks its caller to write the bytes and drops whatever the -/// caller declines to write. -/// -/// -/// The accepted socket. The connection that built this pump owns its lifetime. -/// What this pump may do, and for how long. -/// The clock the idle deadline reads. -/// -/// Cancelled once, for any reason the socket is going away: the request aborted, the host is -/// stopping, or one of the connection's own tasks ended. -/// -internal sealed class JsonWebSocketPump( - WebSocket socket, - JsonWebSocketPumpOptions options, - TimeProvider timeProvider, - CancellationToken connectionToken) +namespace AgentCore.AspNetCore.Conversation { - private bool _loggedUnknownFrame; - private bool _loggedRefusedFrameBody; - - /// Reads whole messages off the socket until the conversation ends, and hands each one over. - /// Reads one reassembled message, and never throws on what the peer sent. - /// - /// Takes one parsed frame. It is awaited, so a caller that must not block the loop — a turn, for - /// one — starts its own task and returns. - /// - /// A task that completes when the socket, the idle deadline, or teardown ends the loop. + /// + /// The read loop, the write loop, and the close of one duplex JSON-over-WebSocket connection. + /// /// - /// Returns rather than throws for every ordinary end of a conversation, including the idle deadline, so - /// a caller reading for its close status sees a fault only when - /// something actually went wrong. + /// + /// Moved out of the Telnyx connection with its comments intact. Every duplex conversation adapter reads + /// one message at a time off a socket that fragments where it likes, sends from exactly one task + /// because a WebSocket supports one send at a time, and closes on a bounded deadline — and none of + /// that names a vendor. The three seams that would have are delegates: the parse, the exception + /// factory, and the log callbacks. + /// + /// + /// Nothing here decides what a message means or what a reply is worth sending. The parse belongs to + /// the adapter's own reader, and so does the gate in front of the write loop's one send: an item + /// that a barge-in already cut off is stale in the output port's vocabulary, not the transport's, + /// so only asks its caller to write the bytes and drops whatever the + /// caller declines to write. + /// /// - public async Task ReadLoopAsync(FrameParser parse, Func dispatch) + /// The accepted socket. The connection that built this pump owns its lifetime. + /// What this pump may do, and for how long. + /// The clock the idle deadline reads. + /// + /// Cancelled once, for any reason the socket is going away: the request aborted, the host is + /// stopping, or one of the connection's own tasks ended. + /// + internal sealed class JsonWebSocketPump( + WebSocket socket, + JsonWebSocketPumpOptions options, + TimeProvider timeProvider, + CancellationToken connectionToken) { - var rented = ArrayPool.Shared.Rent(4 * 1024); - ArrayBufferWriter message = new(4 * 1024); + private bool _loggedUnknownFrame; + private bool _loggedRefusedFrameBody; + + /// Reads whole messages off the socket until the conversation ends, and hands each one over. + /// Reads one reassembled message, and never throws on what the peer sent. + /// + /// Takes one parsed frame. It is awaited, so a caller that must not block the loop — a turn, for + /// one — starts its own task and returns. + /// + /// A task that completes when the socket, the idle deadline, or teardown ends the loop. + /// + /// Returns rather than throws for every ordinary end of a conversation, including the idle deadline, so + /// a caller reading for its close status sees a fault only when + /// something actually went wrong. + /// + public async Task ReadLoopAsync(FrameParser parse, Func dispatch) + { + byte[] rented = ArrayPool.Shared.Rent(4 * 1024); + ArrayBufferWriter message = new(4 * 1024); - // Set the moment an abandoned receive takes over returning `rented` — see - // ObserveAbandonedReceive. Once true, the finally below must not also return it: the pool - // would then hand the same array out twice at once, which corrupts it just as surely as - // returning it too early does. - var bufferOwnedByAbandonedReceive = false; + // Set the moment an abandoned receive takes over returning `rented` — see + // ObserveAbandonedReceive. Once true, the finally below must not also return it: the pool + // would then hand the same array out twice at once, which corrupts it just as surely as + // returning it too early does. + bool bufferOwnedByAbandonedReceive = false; - try - { - while (!connectionToken.IsCancellationRequested) + try { - message.ResetWrittenCount(); - - // The vendor never reconnects, so a socket with no inbound frame for IdleTimeout is - // a conversation that already ended, not a fault. The first receive of every message races - // the deadline rather than being cancelled by one: a probe against a real Kestrel - // WebSocket confirmed that cancelling ReceiveAsync's own token while it is pending - // aborts the socket outright — WebSocketState.Aborted — which then makes the - // graceful NormalClosure close below throw instead of reaching the vendor. Racing a - // side task leaves the receive itself untouched; the side that loses the race is - // simply abandoned rather than cancelled, exactly as a healthy send and a healthy - // receive already run concurrently on this same socket during ordinary operation. - // - // idling is built first, deliberately: Task.Delay validates IdleTimeout and throws - // synchronously — confirmed on net10 for a negative span, 60 days, and - // TimeSpan.MaxValue — for anything app.MapCall()'s own startup check did not - // catch. Building it before receiving exists means that throw can only ever find - // no receive in flight yet, so the finally below stays free to return `rented` - // unconditionally; building it after would leave a live receive, on - // CancellationToken.None, stranded against an array the finally had already handed - // back to the pool — the exact hazard fixed elsewhere in this method, reopened by a - // bad option value instead of by teardown. - using CancellationTokenSource idleCancel = CancellationTokenSource.CreateLinkedTokenSource(connectionToken); - var idling = Task.Delay(options.IdleTimeout, timeProvider, idleCancel.Token); - var receiving = socket.ReceiveAsync(rented.AsMemory(), CancellationToken.None).AsTask(); - - if (await Task.WhenAny(receiving, idling).ConfigureAwait(false) != receiving) + while (!connectionToken.IsCancellationRequested) { - // idling won: either IdleTimeout actually elapsed, or the connection token - // itself fired and cancelled this Task.Delay along with it — host stopping, or - // the request aborting. IsCompletedSuccessfully tells the two apart, since a - // cancelled Task.Delay never reaches that state, and only the elapsed case is - // this connection's own idle deadline rather than teardown asked for elsewhere. - // Either way, DetermineCloseStatus only reaches InternalServerError off - // reading.IsFaulted, and returning here rather than throwing leaves this task - // Completed, not Faulted, so both fall through its checks to the same - // NormalClosure a clean close already gets — or to EndpointUnavailable, when - // the host is the one stopping. - bufferOwnedByAbandonedReceive = true; - ObserveAbandonedReceive(receiving, rented); - - if (idling.IsCompletedSuccessfully) + message.ResetWrittenCount(); + + // The vendor never reconnects, so a socket with no inbound frame for IdleTimeout is + // a conversation that already ended, not a fault. The first receive of every message races + // the deadline rather than being cancelled by one: a probe against a real Kestrel + // WebSocket confirmed that cancelling ReceiveAsync's own token while it is pending + // aborts the socket outright — WebSocketState.Aborted — which then makes the + // graceful NormalClosure close below throw instead of reaching the vendor. Racing a + // side task leaves the receive itself untouched; the side that loses the race is + // simply abandoned rather than cancelled, exactly as a healthy send and a healthy + // receive already run concurrently on this same socket during ordinary operation. + // + // idling is built first, deliberately: Task.Delay validates IdleTimeout and throws + // synchronously — confirmed on net10 for a negative span, 60 days, and + // TimeSpan.MaxValue — for anything app.MapCall()'s own startup check did not + // catch. Building it before receiving exists means that throw can only ever find + // no receive in flight yet, so the finally below stays free to return `rented` + // unconditionally; building it after would leave a live receive, on + // CancellationToken.None, stranded against an array the finally had already handed + // back to the pool — the exact hazard fixed elsewhere in this method, reopened by a + // bad option value instead of by teardown. + using CancellationTokenSource idleCancel = CancellationTokenSource.CreateLinkedTokenSource(connectionToken); + Task idling = Task.Delay(options.IdleTimeout, timeProvider, idleCancel.Token); + Task receiving = socket.ReceiveAsync(rented.AsMemory(), CancellationToken.None).AsTask(); + + if (await Task.WhenAny(receiving, idling).ConfigureAwait(false) != receiving) { - ConnectionTaskObserver.SafeLog(options.LogIdleTimeout); + // idling won: either IdleTimeout actually elapsed, or the connection token + // itself fired and cancelled this Task.Delay along with it — host stopping, or + // the request aborting. IsCompletedSuccessfully tells the two apart, since a + // cancelled Task.Delay never reaches that state, and only the elapsed case is + // this connection's own idle deadline rather than teardown asked for elsewhere. + // Either way, DetermineCloseStatus only reaches InternalServerError off + // reading.IsFaulted, and returning here rather than throwing leaves this task + // Completed, not Faulted, so both fall through its checks to the same + // NormalClosure a clean close already gets — or to EndpointUnavailable, when + // the host is the one stopping. + bufferOwnedByAbandonedReceive = true; + ObserveAbandonedReceive(receiving, rented); + + if (idling.IsCompletedSuccessfully) + { + ConnectionTaskObserver.SafeLog(options.LogIdleTimeout); + } + + return; } - return; - } + // The receive won the race. Cancelling idling's own token here, rather than + // leaving it to expire on its own after IdleTimeout, releases the timer behind it + // now instead of leaving one pending per message for as long as a busy conversation keeps + // sending faster than IdleTimeout — CancelAfter is never involved, so this touches + // nothing outside this one local source. + await idleCancel.CancelAsync().ConfigureAwait(false); + ValueWebSocketReceiveResult first = await receiving.ConfigureAwait(false); - // The receive won the race. Cancelling idling's own token here, rather than - // leaving it to expire on its own after IdleTimeout, releases the timer behind it - // now instead of leaving one pending per message for as long as a busy conversation keeps - // sending faster than IdleTimeout — CancelAfter is never involved, so this touches - // nothing outside this one local source. - await idleCancel.CancelAsync().ConfigureAwait(false); - var first = await receiving.ConfigureAwait(false); + if (!await AssembleMessageAsync(first, rented, message).ConfigureAwait(false)) + { + return; + } - if (!await AssembleMessageAsync(first, rented, message).ConfigureAwait(false)) - { - return; - } + // Parsed here, synchronously, before any await sees this iteration again. Passing + // the parsed frame to dispatch — rather than the bytes, which an async method + // cannot take as a ReadOnlySpan parameter anyway — means nothing async + // can ever alias the rented buffer or the ArrayBufferWriter this loop is about to + // reset and reuse. + FrameOutcome outcome = parse(message.WrittenSpan); - // Parsed here, synchronously, before any await sees this iteration again. Passing - // the parsed frame to dispatch — rather than the bytes, which an async method - // cannot take as a ReadOnlySpan parameter anyway — means nothing async - // can ever alias the rented buffer or the ArrayBufferWriter this loop is about to - // reset and reuse. - var outcome = parse(message.WrittenSpan); + if (outcome.Frame is null) + { + RefuseFrame(outcome); + continue; + } - if (outcome.Frame is null) + await dispatch(outcome.Frame).ConfigureAwait(false); + } + } + finally + { + // Skipped when an abandoned receive is still live against `rented`: ObserveAbandonedReceive + // owns the return in that case, deferred until that receive itself finishes, and this + // method has no way to know that has happened yet — returning here too would hand the + // same array to a second renter while the first receive can still write into it. + if (!bufferOwnedByAbandonedReceive) { - RefuseFrame(outcome); - continue; + // clearArray: true, for the reason ObserveAbandonedReceive gives: this array holds + // what the caller said, and the pool behind it is shared with the whole process. + ArrayPool.Shared.Return(rented, clearArray: true); } - - await dispatch(outcome.Frame).ConfigureAwait(false); } } - finally + + /// Collects the rest of one message into , fragment by fragment. + /// The fragment that already won the idle race. + /// The array every fragment lands in before it is copied out. + /// The writer the whole message is assembled into. + /// + /// once the whole message is in ; + /// when the peer sent a close frame instead. + /// + /// + /// A loop that parsed each receive on its own would fail on a fragment, and it would cut a + /// multi-byte character in half. Only the first fragment raced the idle deadline: the vendor + /// is, by definition, no longer silent once one fragment of a message has already arrived. + /// + private async Task AssembleMessageAsync( + ValueWebSocketReceiveResult first, + byte[] rented, + ArrayBufferWriter message) { - // Skipped when an abandoned receive is still live against `rented`: ObserveAbandonedReceive - // owns the return in that case, deferred until that receive itself finishes, and this - // method has no way to know that has happened yet — returning here too would hand the - // same array to a second renter while the first receive can still write into it. - if (!bufferOwnedByAbandonedReceive) + ValueWebSocketReceiveResult result = first; + + while (true) { - // clearArray: true, for the reason ObserveAbandonedReceive gives: this array holds - // what the caller said, and the pool behind it is shared with the whole process. - ArrayPool.Shared.Return(rented, clearArray: true); + if (result.MessageType == WebSocketMessageType.Close) + { + return false; + } + + if (message.WrittenCount + result.Count > options.MaxFrameBytes) + { + throw options.ProtocolFault( + WebSocketCloseStatus.MessageTooBig, + "the relay frame passes the size limit."); + } + + message.Write(rented.AsSpan(0, result.Count)); + + if (result.EndOfMessage) + { + return true; + } + + result = await socket + .ReceiveAsync(rented.AsMemory(), connectionToken) + .ConfigureAwait(false); } } - } - /// Collects the rest of one message into , fragment by fragment. - /// The fragment that already won the idle race. - /// The array every fragment lands in before it is copied out. - /// The writer the whole message is assembled into. - /// - /// once the whole message is in ; - /// when the peer sent a close frame instead. - /// - /// - /// A loop that parsed each receive on its own would fail on a fragment, and it would cut a - /// multi-byte character in half. Only the first fragment raced the idle deadline: the vendor - /// is, by definition, no longer silent once one fragment of a message has already arrived. - /// - private async Task AssembleMessageAsync( - ValueWebSocketReceiveResult first, - byte[] rented, - ArrayBufferWriter message) - { - var result = first; - - while (true) + /// Logs, or closes the socket over, a message the parser produced no frame for. + /// An outcome whose is . + private void RefuseFrame(FrameOutcome outcome) { - if (result.MessageType == WebSocketMessageType.Close) + if (outcome.UnknownType is null && outcome.RefusedType is null) { - return false; + // Neither name is set, so the bytes carried no readable type at all: not + // JSON, not an object, or a type that is not a string. That is the only + // shape this endpoint closes a socket over. + throw options.ProtocolFault( + WebSocketCloseStatus.InvalidPayloadData, + "the relay sent a frame this endpoint cannot parse."); } - if (message.WrittenCount + result.Count > options.MaxFrameBytes) + // Log once for the conversation, not once for the frame. Section 3.1. + if (outcome.UnknownType is { } unmodelled) { - throw options.ProtocolFault( - WebSocketCloseStatus.MessageTooBig, - "the relay frame passes the size limit."); + if (!_loggedUnknownFrame) + { + _loggedUnknownFrame = true; + options.LogUnknownFrameType(unmodelled); + } } - - message.Write(rented.AsSpan(0, result.Count)); - - if (result.EndOfMessage) + else if (!_loggedRefusedFrameBody) { - return true; + // A known type whose body will not bind. Section 7.1 treats a vendor that + // changes a frame exactly as it treats one that adds a frame: the frame is + // refused, and the conversation goes on. + _loggedRefusedFrameBody = true; + options.LogRefusedFrameBody(outcome.RefusedType!); } - - result = await socket - .ReceiveAsync(rented.AsMemory(), connectionToken) - .ConfigureAwait(false); - } - } - - /// Logs, or closes the socket over, a message the parser produced no frame for. - /// An outcome whose is . - private void RefuseFrame(FrameOutcome outcome) - { - if (outcome.UnknownType is null && outcome.RefusedType is null) - { - // Neither name is set, so the bytes carried no readable type at all: not - // JSON, not an object, or a type that is not a string. That is the only - // shape this endpoint closes a socket over. - throw options.ProtocolFault( - WebSocketCloseStatus.InvalidPayloadData, - "the relay sent a frame this endpoint cannot parse."); } - // Log once for the conversation, not once for the frame. Section 3.1. - if (outcome.UnknownType is { } unmodelled) + /// Sends whatever the caller queues, one item at a time, until the conversation ends. + /// Whatever the caller queues. This pump never looks inside one. + /// The queue the caller's own writers fill. + /// + /// Writes one queued item into the loop's own , and returns + /// to drop it instead. Both halves belong to the caller: the writing is + /// the adapter's wire format, and the drop is the last barge-in gate, which is expressed in the + /// output port's own vocabulary and never in this pump's. It runs immediately before the one + /// send below, which is the whole point of it running here rather than at the point an item was + /// queued. It is handed the writer rather than asked for an array so that the buffer behind it + /// can be reused for the life of the loop; it must write one complete JSON value and it must not + /// keep the writer, flush it, or hold anything the writer wrote past its own return. + /// + /// A task that completes when the queue completes, the socket closes, or teardown cancels. + public async Task WriteLoopAsync(ChannelReader reader, Func encode) { - if (!_loggedUnknownFrame) + // One buffer and one writer for the life of the loop, rather than one array per spoken + // word. The channel is SingleReader, so this loop is the only thing that touches either. + // Every send is awaited before the next frame resets the buffer, so nothing can hand the + // same memory to two sends at once — and WrittenMemory never leaves this method, so nothing + // outside it can still be holding the previous frame's bytes when the reset happens. + ArrayBufferWriter buffer = new(256); + using Utf8JsonWriter writer = new(buffer); + + await foreach (T? item in reader.ReadAllAsync(connectionToken).ConfigureAwait(false)) { - _loggedUnknownFrame = true; - options.LogUnknownFrameType(unmodelled); + if (socket.State is not (WebSocketState.Open or WebSocketState.CloseReceived)) + { + return; + } + + // Reset before encode rather than after the send: an item the gate inside encode drops + // writes nothing at all, and leaving the reset to the next iteration would then send + // the frame before it a second time. + buffer.ResetWrittenCount(); + writer.Reset(buffer); + + if (!encode(item, writer)) + { + continue; + } + + // The caller writes; this loop flushes. A Utf8JsonWriter holds the tail of a value in + // its own buffer until something asks for it, so the send below would otherwise get a + // truncated frame rather than a whole one. + await writer.FlushAsync().ConfigureAwait(false); + + await socket + .SendAsync(buffer.WrittenMemory, WebSocketMessageType.Text, endOfMessage: true, connectionToken) + .ConfigureAwait(false); } } - else if (!_loggedRefusedFrameBody) - { - // A known type whose body will not bind. Section 7.1 treats a vendor that - // changes a frame exactly as it treats one that adds a frame: the frame is - // refused, and the conversation goes on. - _loggedRefusedFrameBody = true; - options.LogRefusedFrameBody(outcome.RefusedType!); - } - } - /// Sends whatever the caller queues, one item at a time, until the conversation ends. - /// Whatever the caller queues. This pump never looks inside one. - /// The queue the caller's own writers fill. - /// - /// Writes one queued item into the loop's own , and returns - /// to drop it instead. Both halves belong to the caller: the writing is - /// the adapter's wire format, and the drop is the last barge-in gate, which is expressed in the - /// output port's own vocabulary and never in this pump's. It runs immediately before the one - /// send below, which is the whole point of it running here rather than at the point an item was - /// queued. It is handed the writer rather than asked for an array so that the buffer behind it - /// can be reused for the life of the loop; it must write one complete JSON value and it must not - /// keep the writer, flush it, or hold anything the writer wrote past its own return. - /// - /// A task that completes when the queue completes, the socket closes, or teardown cancels. - public async Task WriteLoopAsync(ChannelReader reader, Func encode) - { - // One buffer and one writer for the life of the loop, rather than one array per spoken - // word. The channel is SingleReader, so this loop is the only thing that touches either. - // Every send is awaited before the next frame resets the buffer, so nothing can hand the - // same memory to two sends at once — and WrittenMemory never leaves this method, so nothing - // outside it can still be holding the previous frame's bytes when the reset happens. - ArrayBufferWriter buffer = new(256); - using Utf8JsonWriter writer = new(buffer); - - await foreach (var item in reader.ReadAllAsync(connectionToken).ConfigureAwait(false)) + /// Closes the socket, and never waits on the peer forever to do it. + /// The status the peer should see. + /// Why, or when the status says it all. + /// A task that completes once the socket is closed or aborted. + public async Task CloseAsync(WebSocketCloseStatus status, string? description) { if (socket.State is not (WebSocketState.Open or WebSocketState.CloseReceived)) { return; } - // Reset before encode rather than after the send: an item the gate inside encode drops - // writes nothing at all, and leaving the reset to the next iteration would then send - // the frame before it a second time. - buffer.ResetWrittenCount(); - writer.Reset(buffer); + // Sends serialize behind the WebSocket's own send mutex, so a close that overlaps a send + // stuck on relay backpressure waits on it rather than throwing — and CancellationToken.None + // would then wait forever. The connection token is already cancelled by the time this runs, + // so the close gets its own bounded token instead. + using CancellationTokenSource closeDeadline = new(); + closeDeadline.CancelAfter(options.CloseTimeout); - if (!encode(item, writer)) + try { - continue; + // CloseOutputAsync, never CloseAsync. CloseAsync waits for the peer close frame, and a + // conversation that already dropped never sends one. + await socket + .CloseOutputAsync(status, TruncateForCloseFrame(description), closeDeadline.Token) + .ConfigureAwait(false); + } + catch (OperationCanceledException) when (closeDeadline.IsCancellationRequested) + { + // The relay stopped reading and applied backpressure, so the send behind the close + // would never complete. Abort rather than leave the connection, the Kestrel request, + // and the store entry alive forever. + socket.Abort(); + } + catch (WebSocketException) + { + // The far end already went away. That is the end of a conversation, not a fault. } - - // The caller writes; this loop flushes. A Utf8JsonWriter holds the tail of a value in - // its own buffer until something asks for it, so the send below would otherwise get a - // truncated frame rather than a whole one. - await writer.FlushAsync().ConfigureAwait(false); - - await socket - .SendAsync(buffer.WrittenMemory, WebSocketMessageType.Text, endOfMessage: true, connectionToken) - .ConfigureAwait(false); } - } - /// Closes the socket, and never waits on the peer forever to do it. - /// The status the peer should see. - /// Why, or when the status says it all. - /// A task that completes once the socket is closed or aborted. - public async Task CloseAsync(WebSocketCloseStatus status, string? description) - { - if (socket.State is not (WebSocketState.Open or WebSocketState.CloseReceived)) + /// Waits out the losing side of the idle race, then hands its buffer back to the pool. + /// The receive the idle deadline, or teardown, won the race against. + /// + /// The array still writes into until it completes. Ownership of + /// returning it to moves here, and here only, the moment + /// abandons this receive — ReadLoopAsync's own finally + /// must not also return it, or the pool would see it twice. + /// + /// + /// + /// Nothing here awaits inline, and nothing may: the socket is + /// about to receive a graceful close, and blocking on a receive that is still pending against + /// a socket this connection no longer owns would either wait on a peer that already stopped + /// sending or throw once the close races it. + /// + /// + /// The buffer is returned from this continuation, never from ReadLoopAsync's own + /// finally, because that finally runs the instant ReadLoopAsync returns — + /// while can still be mid-write into . A + /// probe with two real sockets over a loopback TCP pair proved exactly that: returning early + /// let a second renter receive the same array, and the first receive's own bytes then landed + /// in it once the peer actually sent something, overwriting whatever the second renter had put + /// there. is shared with every other read loop in this + /// process, including one on a completely different conversation, so that corruption is not confined + /// to this connection. Deferring the return until itself finishes + /// — successfully, faulted, or cancelled, it makes no difference — is what keeps the array out + /// of the pool for exactly as long as something can still write to it, never shorter. + /// + /// + private static void ObserveAbandonedReceive(Task receiving, byte[] buffer) { - return; + _ = receiving.ContinueWith( + completed => + { + // Marks a fault observed the same way the earlier, buffer-free version did, so it + // never becomes an unobserved task exception, whatever receiving finished with. + _ = completed.Exception; + + // clearArray: true. The array still holds the caller's own words, and the pool it + // goes back to is shared with Kestrel and with every other read loop in this + // process. D23 makes the audit chain the record of a conversation; a pooled buffer that + // hands a transcript to the next renter is not a record, it is a leak. + ArrayPool.Shared.Return(buffer, clearArray: true); + }, + CancellationToken.None, + TaskContinuationOptions.ExecuteSynchronously, + TaskScheduler.Default); } - // Sends serialize behind the WebSocket's own send mutex, so a close that overlaps a send - // stuck on relay backpressure waits on it rather than throwing — and CancellationToken.None - // would then wait forever. The connection token is already cancelled by the time this runs, - // so the close gets its own bounded token instead. - using CancellationTokenSource closeDeadline = new(); - closeDeadline.CancelAfter(options.CloseTimeout); - - try - { - // CloseOutputAsync, never CloseAsync. CloseAsync waits for the peer close frame, and a - // conversation that already dropped never sends one. - await socket - .CloseOutputAsync(status, TruncateForCloseFrame(description), closeDeadline.Token) - .ConfigureAwait(false); - } - catch (OperationCanceledException) when (closeDeadline.IsCancellationRequested) - { - // The relay stopped reading and applied backpressure, so the send behind the close - // would never complete. Abort rather than leave the connection, the Kestrel request, - // and the store entry alive forever. - socket.Abort(); - } - catch (WebSocketException) + /// Keeps a close description inside the 123-byte limit the close frame's control payload allows. + /// The description a status carries, or null. + /// The description, cut short if needed, or null. + /// + /// Every description this class ever passes is one of the two fixed, short, plain-English + /// messages the protocol faults above carry today, so a character cut is a safe + /// stand-in for a byte-accurate one — this only guards a future message that grows past the + /// limit, so never throws instead of closing. + /// + private static string? TruncateForCloseFrame(string? description) { - // The far end already went away. That is the end of a conversation, not a fault. + return description is { Length: > 100 } ? description[..100] : description; } } - - /// Waits out the losing side of the idle race, then hands its buffer back to the pool. - /// The receive the idle deadline, or teardown, won the race against. - /// - /// The array still writes into until it completes. Ownership of - /// returning it to moves here, and here only, the moment - /// abandons this receive — ReadLoopAsync's own finally - /// must not also return it, or the pool would see it twice. - /// - /// - /// - /// Nothing here awaits inline, and nothing may: the socket is - /// about to receive a graceful close, and blocking on a receive that is still pending against - /// a socket this connection no longer owns would either wait on a peer that already stopped - /// sending or throw once the close races it. - /// - /// - /// The buffer is returned from this continuation, never from ReadLoopAsync's own - /// finally, because that finally runs the instant ReadLoopAsync returns — - /// while can still be mid-write into . A - /// probe with two real sockets over a loopback TCP pair proved exactly that: returning early - /// let a second renter receive the same array, and the first receive's own bytes then landed - /// in it once the peer actually sent something, overwriting whatever the second renter had put - /// there. is shared with every other read loop in this - /// process, including one on a completely different conversation, so that corruption is not confined - /// to this connection. Deferring the return until itself finishes - /// — successfully, faulted, or cancelled, it makes no difference — is what keeps the array out - /// of the pool for exactly as long as something can still write to it, never shorter. - /// - /// - private static void ObserveAbandonedReceive(Task receiving, byte[] buffer) - { - _ = receiving.ContinueWith( - completed => - { - // Marks a fault observed the same way the earlier, buffer-free version did, so it - // never becomes an unobserved task exception, whatever receiving finished with. - _ = completed.Exception; - - // clearArray: true. The array still holds the caller's own words, and the pool it - // goes back to is shared with Kestrel and with every other read loop in this - // process. D23 makes the audit chain the record of a conversation; a pooled buffer that - // hands a transcript to the next renter is not a record, it is a leak. - ArrayPool.Shared.Return(buffer, clearArray: true); - }, - CancellationToken.None, - TaskContinuationOptions.ExecuteSynchronously, - TaskScheduler.Default); - } - - /// Keeps a close description inside the 123-byte limit the close frame's control payload allows. - /// The description a status carries, or null. - /// The description, cut short if needed, or null. - /// - /// Every description this class ever passes is one of the two fixed, short, plain-English - /// messages the protocol faults above carry today, so a character cut is a safe - /// stand-in for a byte-accurate one — this only guards a future message that grows past the - /// limit, so never throws instead of closing. - /// - private static string? TruncateForCloseFrame(string? description) - => description is { Length: > 100 } ? description[..100] : description; } diff --git a/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPumpOptions.cs b/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPumpOptions.cs index fa039c0e..d88686ec 100644 --- a/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPumpOptions.cs +++ b/src/AgentCore.AspNetCore/Conversation/JsonWebSocketPumpOptions.cs @@ -1,30 +1,31 @@ using System.Net.WebSockets; -namespace AgentCore.AspNetCore.Conversation; - -/// What one pump may do, and for how long. -/// The largest inbound message the pump accepts, in bytes. -/// How long the pump waits with no inbound message before it ends the conversation. -/// How long the close handshake may take before the socket is aborted. -/// -/// Builds the exception the pump throws when the peer broke the contract. The adapter supplies it, -/// so the pump raises the adapter's own exception type and the adapter's own close-status rules -/// still recognise it. -/// -/// -/// Logs a discriminator no case matched. The pump calls it once for the conversation, not once for the -/// frame, and passes the name; the line itself names the vendor, which is why it is a callback. -/// -/// -/// Logs a known discriminator whose body would not bind, on the same once-for-the-conversation rule as -/// . -/// -/// Logs that the idle deadline, rather than teardown, ended the conversation. -internal sealed record JsonWebSocketPumpOptions( - int MaxFrameBytes, - TimeSpan IdleTimeout, - TimeSpan CloseTimeout, - Func ProtocolFault, - Action LogUnknownFrameType, - Action LogRefusedFrameBody, - Action LogIdleTimeout); +namespace AgentCore.AspNetCore.Conversation +{ + /// What one pump may do, and for how long. + /// The largest inbound message the pump accepts, in bytes. + /// How long the pump waits with no inbound message before it ends the conversation. + /// How long the close handshake may take before the socket is aborted. + /// + /// Builds the exception the pump throws when the peer broke the contract. The adapter supplies it, + /// so the pump raises the adapter's own exception type and the adapter's own close-status rules + /// still recognise it. + /// + /// + /// Logs a discriminator no case matched. The pump calls it once for the conversation, not once for the + /// frame, and passes the name; the line itself names the vendor, which is why it is a callback. + /// + /// + /// Logs a known discriminator whose body would not bind, on the same once-for-the-conversation rule as + /// . + /// + /// Logs that the idle deadline, rather than teardown, ended the conversation. + internal sealed record JsonWebSocketPumpOptions( + int MaxFrameBytes, + TimeSpan IdleTimeout, + TimeSpan CloseTimeout, + Func ProtocolFault, + Action LogUnknownFrameType, + Action LogRefusedFrameBody, + Action LogIdleTimeout); +} diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index ce18be43..4bb87029 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -15,348 +15,356 @@ using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options; +using Microsoft.Extensions.AI; +using AgentCore.Application.Skills; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Everything one document opens, behind one owner the container built. -internal sealed class AgentCoreBoot : IAsyncDisposable, IDisposable +namespace AgentCore.AspNetCore.DependencyInjection { - private readonly AgentCoreOptions _options; - - private readonly ILoggerFactory _loggers; - - private readonly IServiceProvider? _services; - - private readonly List _opened = []; + /// Everything one document opens, behind one owner the container built. + internal sealed class AgentCoreBoot : IAsyncDisposable, IDisposable + { + private readonly AgentCoreOptions _options; - private readonly Lock _gate = new(); + private readonly ILoggerFactory _loggers; + private readonly List _opened = []; - private BootState? _state; + private readonly Lock _gate = new(); + private int _closed; - private int _closed; - - /// Takes the options a host filled and the loggers the container holds. - /// The options every Use* seam wrote into. - /// The container's factory, used unless the options name another. - /// The container, read for the mapped routes the startup check walks. - public AgentCoreBoot(IOptions options, ILoggerFactory loggers, IServiceProvider? services = null) - { - ArgumentNullException.ThrowIfNull(options); - ArgumentNullException.ThrowIfNull(loggers); + /// Takes the options a host filled and the loggers the container holds. + /// The options every Use* seam wrote into. + /// The container's factory, used unless the options name another. + /// The container, read for the mapped routes the startup check walks. + public AgentCoreBoot(IOptions options, ILoggerFactory loggers, IServiceProvider? services = null) + { + ArgumentNullException.ThrowIfNull(options); + ArgumentNullException.ThrowIfNull(loggers); - _options = options.Value; - _loggers = _options.LoggerFactory ?? loggers; - _services = services; - } + _options = options.Value; + _loggers = _options.LoggerFactory ?? loggers; + Services = services; + } - /// Gets the loaded document. - internal AgentCoreConfiguration Configuration => Started.Configuration; + /// Gets the loaded document. + internal AgentCoreConfiguration Configuration => Started.Configuration; - /// Gets every ${secret:name} value, read once while the host started. - internal ResolvedSecrets Secrets => Started.Secrets; + /// Gets every ${secret:name} value, read once while the host started. + internal ResolvedSecrets Secrets => Started.Secrets; - /// Gets the bindings the host registered by name. - internal ToolBindingRegistry Bindings => _options.Bindings; + /// Gets the bindings the host registered by name. + internal ToolBindingRegistry Bindings => _options.Bindings; - /// Gets the registry that compiled the document, and would compile it again. - internal CompiledAgentRegistry CompiledRegistry => Started.Graph.Registry; + /// Gets the registry that compiled the document, and would compile it again. + internal CompiledAgentRegistry CompiledRegistry => Started.Graph.Registry; - /// Gets the compiled entries, keyed by entry name. Every conversation shares them. - internal IReadOnlyDictionary CompiledEntries => Started.Graph.Entries; + /// Gets the compiled entries, keyed by entry name. Every conversation shares them. + internal IReadOnlyDictionary CompiledEntries => Started.Graph.Entries; - /// Gets the factory the compile table asks for every agent and for the extractor. - internal IChatClientFactory ChatClients => Started.Graph.ChatClients; + /// Gets the factory the compile table asks for every agent and for the extractor. + internal IChatClientFactory ChatClients => Started.Graph.ChatClients; - /// Gets the shared guard evaluator. - internal IGuardEvaluator Guards => Started.Graph.Guards; + /// Gets the shared guard evaluator. + internal IGuardEvaluator Guards => Started.Graph.Guards; - /// Gets the registry the compile table reads. - internal ToolRegistry Tools => Started.Tools; + /// Gets the registry the compile table reads. + internal ToolRegistry Tools => Started.Tools; - /// Gets the backing every conversation's row and every word of it is kept in. - internal Conversations Conversations => Started.Conversations; + /// Gets the backing every conversation's row and every word of it is kept in. + internal Conversations Conversations => Started.Conversations; - /// Gets the registry the turn loop reads, and the offline golden set alike. - internal EvaluatorRegistry Evaluators => Started.Evaluators; + /// Gets the registry the turn loop reads, and the offline golden set alike. + internal EvaluatorRegistry Evaluators => Started.Evaluators; - /// Gets the queue that answers the audit port, not the store behind it. - internal QueuedAuditSink AuditQueue => Started.AuditQueue; + /// Gets the queue that answers the audit port, not the store behind it. + internal QueuedAuditSink AuditQueue => Started.AuditQueue; - /// Gets one factory, one agent, and one session store per entry. - internal EntryRegistry Entries => Started.Entries; + /// Gets one factory, one agent, and one session store per entry. + internal EntryRegistry Entries => Started.Entries; - /// Gets the container, read for host-registered seams the boot honors. - internal IServiceProvider? Services => _services; + /// Gets the container, read for host-registered seams the boot honors. + internal IServiceProvider? Services { get; } - /// Gets the knowledge base, or when no agent reads one. - internal IKnowledgeRetrievalPort? Knowledge => Started.Knowledge; + /// Gets the knowledge base, or when no agent reads one. + internal IKnowledgeRetrievalPort? Knowledge => Started.Knowledge; - /// Gets the blob store, or when the document names none. - internal IBlobStore? Blobs => Started.Blobs; + /// Gets the blob store, or when the document names none. + internal IBlobStore? Blobs => Started.Blobs; - /// Gets what the conversation route runs, or when no conversation routes here. - internal RequestDelegate? ConversationHandler => Started.ConversationHandler; + /// Gets what the conversation route runs, or when no conversation routes here. + internal RequestDelegate? ConversationHandler => Started.ConversationHandler; - /// Gets why no conversation routes here, or when conversations route. - internal string? ConversationUnroutable => Started.ConversationUnroutable; + /// Gets why no conversation routes here, or when conversations route. + internal string? ConversationUnroutable => Started.ConversationUnroutable; - /// Gets the conversation transports the host registered, or if it registered none. - internal IReadOnlyList? ConversationAdapters => Started.ConversationAdapters; + /// Gets the conversation transports the host registered, or if it registered none. + internal IReadOnlyList? ConversationAdapters => Started.ConversationAdapters; - /// Gets the speech vendors the host registered, or if it registered none. - internal IReadOnlyList? SpeechAdapters => Started.SpeechAdapters; + /// Gets the speech vendors the host registered, or if it registered none. + internal IReadOnlyList? SpeechAdapters => Started.SpeechAdapters; - /// Gets the telemetry export, or when the host registered no vendor. - internal ITelemetrySession? Telemetry => Started.Telemetry; + /// Gets the telemetry export, or when the host registered no vendor. + internal ITelemetrySession? Telemetry => Started.Telemetry; - private BootState Started => _state ?? throw NotStarted(); + private BootState Started { get => field ?? throw NotStarted(); set; } - /// Takes ownership of one resource, and hands it straight back. - /// The resource's own type, so a caller loses nothing by owning it. - /// What to close when the host stops. Anything not disposable is ignored. - /// , unchanged. - internal T Track(T resource) - { - if (resource is IAsyncDisposable or IDisposable) + /// Takes ownership of one resource, and hands it straight back. + /// The resource's own type, so a caller loses nothing by owning it. + /// What to close when the host stops. Anything not disposable is ignored. + /// , unchanged. + internal T Track(T resource) { - lock (_gate) + if (resource is IAsyncDisposable or IDisposable) { - _opened.Add(resource); + lock (_gate) + { + _opened.Add(resource); + } } - } - return resource; - } + return resource; + } - /// Gives up ownership of one resource, and hands it straight back. - /// What the caller is resolving. - /// What the container is about to take. - /// , unchanged. - internal T Release(T resource) - { - if (resource is IAsyncDisposable or IDisposable) + /// Gives up ownership of one resource, and hands it straight back. + /// What the caller is resolving. + /// What the container is about to take. + /// , unchanged. + internal T Release(T resource) { - lock (_gate) + if (resource is IAsyncDisposable or IDisposable) { - _opened.Remove(resource); + lock (_gate) + { + _ = _opened.Remove(resource); + } } - } - - return resource; - } - - /// Loads the document, opens everything it names, and compiles it. - /// Cancels the secret reads and the adapter builds. - /// A task that completes when the graph is ready to take a conversation. - /// - /// The options name no document, name two, or bind no chat client adapter. - /// - /// - /// The document fails one of the eight checks, names a kind no registered adapter serves, - /// does not compile, or a mapped route names an entry it does not declare. - /// - /// One ${secret:name} reference resolves to nothing. - internal async ValueTask BootAsync(CancellationToken cancellationToken) - { - var (configuration, configurationWarnings) = ConfigurationStartup.Load(_options); - var telemetry = Track(await TelemetryStartup - .StartAsync(configuration, _options, _loggers, cancellationToken) - .ConfigureAwait(false)); - - var bootLogger = _loggers.CreateLogger(); - foreach (var warning in configurationWarnings) - { - AgentCoreBootLog.ConfigurationWarning(bootLogger, warning.ToString()); + return resource; } - var secrets = await SecretsStartup - .ResolveAsync(configuration, _options, cancellationToken) - .ConfigureAwait(false); - - AgentCoreStartup startup = new(configuration, secrets); - - var agents = configuration.Agents; - - var embeddings = Track(await EmbeddingStartup - .OpenAsync(configuration, _options, cancellationToken) - .ConfigureAwait(false)); - - var knowledge = Track(await KnowledgeStartup - .OpenAsync( - configuration, - _options, - startup, - embeddings, - scopeDeclared: AgentKnowledge.AnyScoped(agents), - requireScope: AgentKnowledge.AllScoped(agents), - cancellationToken) - .ConfigureAwait(false)); - - var chatClients = Track(await ChatClientStartup - .BuildAsync(_options, startup, cancellationToken) - .ConfigureAwait(false)); - - // Opened before the tools: file.publish reads the store at build time. - var blobs = Track(await BlobStartup - .OpenAsync(configuration, _options, cancellationToken) - .ConfigureAwait(false)); - - var tools = await ToolRegistryStartup - .BuildAsync( - this, - _options, - startup, - new BuiltinToolPorts(chatClients, blobs, WorkspaceRoot: _options.WorkspaceRoot, Loggers: _loggers), - cancellationToken) - .ConfigureAwait(false); - - ConfigurationValidator.ValidateToolReferences(configuration, tools.ServedIds); - - var skills = await SkillsStartup - .OpenAsync(_options, _loggers, cancellationToken) - .ConfigureAwait(false); - - if (skills is not null) + /// Loads the document, opens everything it names, and compiles it. + /// Cancels the secret reads and the adapter builds. + /// A task that completes when the graph is ready to take a conversation. + /// + /// The options name no document, name two, or bind no chat client adapter. + /// + /// + /// The document fails one of the eight checks, names a kind no registered adapter serves, + /// does not compile, or a mapped route names an entry it does not declare. + /// + /// One ${secret:name} reference resolves to nothing. + internal async ValueTask BootAsync(CancellationToken cancellationToken) { - Track(skills.Source); - ConfigurationValidator.ValidateSkillReferences(configuration, skills.Names); - } + (AgentCoreConfiguration? configuration, IReadOnlyList? configurationWarnings) = ConfigurationStartup.Load(_options); - ConfigurationValidator.ValidateSkillToolNames(configuration); + ITelemetrySession? telemetry = Track(await TelemetryStartup + .StartAsync(configuration, _options, _loggers, cancellationToken) + .ConfigureAwait(false)); - var store = Track(await ConversationStartup - .OpenAsync(configuration, _options, _loggers, cancellationToken) - .ConfigureAwait(false)); - - Conversations conversations = new(store, blobs); + ILogger bootLogger = _loggers.CreateLogger(); + foreach (ConfigurationError warning in configurationWarnings) + { + AgentCoreBootLog.ConfigurationWarning(bootLogger, warning.ToString()); + } - var evaluators = await EvaluationStartup - .CreateRegistryAsync(configuration, _options, cancellationToken) - .ConfigureAwait(false); + ResolvedSecrets secrets = await SecretsStartup + .ResolveAsync(configuration, _options, cancellationToken) + .ConfigureAwait(false); + + AgentCoreStartup startup = new(configuration, secrets); + + AgentsConfiguration agents = configuration.Agents; + + IEmbeddingGenerator>? embeddings = Track(await EmbeddingStartup + .OpenAsync(configuration, _options, cancellationToken) + .ConfigureAwait(false)); + + IKnowledgeRetrievalPort? knowledge = Track(await KnowledgeStartup + .OpenAsync( + configuration, + _options, + startup, + embeddings, + scopeDeclared: AgentKnowledge.AnyScoped(agents), + requireScope: AgentKnowledge.AllScoped(agents), + cancellationToken) + .ConfigureAwait(false)); + + IChatClientFactory chatClients = Track(await ChatClientStartup + .BuildAsync(_options, startup, cancellationToken) + .ConfigureAwait(false)); + + // Opened before the tools: file.publish reads the store at build time. + IBlobStore? blobs = Track(await BlobStartup + .OpenAsync(configuration, _options, cancellationToken) + .ConfigureAwait(false)); + + ToolRegistryBuildResult tools = await ToolRegistryStartup + .BuildAsync( + this, + _options, + startup, + new BuiltinToolPorts(chatClients, blobs, WorkspaceRoot: _options.WorkspaceRoot, Loggers: _loggers), + cancellationToken) + .ConfigureAwait(false); + + ConfigurationValidator.ValidateToolReferences(configuration, tools.ServedIds); + + SkillCatalog? skills = await SkillsStartup + .OpenAsync(_options, _loggers, cancellationToken) + .ConfigureAwait(false); + + if (skills is not null) + { + _ = Track(skills.Source); + ConfigurationValidator.ValidateSkillReferences(configuration, skills.Names); + } - var graph = await CompilationStartup - .CompileAsync( + ConfigurationValidator.ValidateSkillToolNames(configuration); + + IConversationStore store = Track(await ConversationStartup + .OpenAsync(configuration, _options, _loggers, cancellationToken) + .ConfigureAwait(false)); + + Conversations conversations = new(store, blobs); + + EvaluatorRegistry evaluators = await EvaluationStartup + .CreateRegistryAsync(configuration, _options, cancellationToken) + .ConfigureAwait(false); + + CompiledGraph graph = await CompilationStartup + .CompileAsync( + configuration, + new AgentCompilationContext(chatClients) + { + Tools = tools.Registry, + Guards = new GuardEvaluator(configuration.Guards, _loggers.CreateLogger()), + Moderation = PromptModerator.FromRegistry(evaluators), + ConversationStore = conversations, + Knowledge = knowledge, + Skills = skills, + Citations = KnowledgeCitationFormatterFactory.Resolve(configuration, _options.KnowledgeCitations), + Loggers = _loggers, + WorkspaceRoot = _options.WorkspaceRoot, + Clock = _options.TimeProvider, + Secrets = secrets, + }) + .ConfigureAwait(false); + + ConversationSeamAdapters seams = ConversationSeamStartup.Build(configuration, _options); + + ConversationSessionSeam conversation = await ConversationSessionStartup + .OpenAsync(this, configuration, _options, graph, _loggers, cancellationToken) + .ConfigureAwait(false); + + Started = new BootState( configuration, - new AgentCompilationContext(chatClients) - { - Tools = tools.Registry, - Guards = new GuardEvaluator(configuration.Guards, _loggers.CreateLogger()), - Moderation = PromptModerator.FromRegistry(evaluators), - ConversationStore = conversations, - Knowledge = knowledge, - Skills = skills, - Citations = KnowledgeCitationFormatterFactory.Resolve(configuration, _options.KnowledgeCitations), - Loggers = _loggers, - WorkspaceRoot = _options.WorkspaceRoot, - Clock = _options.TimeProvider, - Secrets = secrets, - }) - .ConfigureAwait(false); - - var seams = ConversationSeamStartup.Build(configuration, _options); - - var conversation = await ConversationSessionStartup - .OpenAsync(this, configuration, _options, graph, _loggers, cancellationToken) - .ConfigureAwait(false); - - _state = new BootState( - configuration, - secrets, - telemetry, - tools.Registry, - conversations, - blobs, - evaluators, - graph, - conversation.Entries, - conversation.Queue, - knowledge, - seams.Conversation, - seams.Speech, - seams.Handler, - seams.Unroutable); - } - - /// - public async ValueTask DisposeAsync() => await CloseAsync().ConfigureAwait(false); - - /// Closes everything, blocking until it is done. - public void Dispose() => CloseAsync().AsTask().GetAwaiter().GetResult(); + secrets, + telemetry, + tools.Registry, + conversations, + blobs, + evaluators, + graph, + conversation.Entries, + conversation.Queue, + knowledge, + seams.Conversation, + seams.Speech, + seams.Handler, + seams.Unroutable); + } - private async ValueTask CloseAsync() - { - if (Interlocked.Exchange(ref _closed, 1) != 0) + /// + public async ValueTask DisposeAsync() { - return; + await CloseAsync().ConfigureAwait(false); } - object[] opened; - - lock (_gate) + /// Closes everything, blocking until it is done. + public void Dispose() { - opened = [.. _opened]; - _opened.Clear(); + CloseAsync().AsTask().GetAwaiter().GetResult(); } - for (var index = opened.Length - 1; index >= 0; index--) + private async ValueTask CloseAsync() { - try + if (Interlocked.Exchange(ref _closed, 1) != 0) { - switch (opened[index]) - { - // Asynchronous first: a resource that carries both, as the audit queue does, must - // not be drained on the path that blocks a thread while it waits. - case IAsyncDisposable asyncDisposable: - await asyncDisposable.DisposeAsync().ConfigureAwait(false); - break; - - case IDisposable disposable: - disposable.Dispose(); - break; - } + return; } - catch + + object[] opened; + + lock (_gate) { - // A boot that already failed carries the exception a deployer needs; a resource that - // also fails to close must not replace or hide it. + opened = [.. _opened]; + _opened.Clear(); + } + + for (int index = opened.Length - 1; index >= 0; index--) + { + try + { + switch (opened[index]) + { + // Asynchronous first: a resource that carries both, as the audit queue does, must + // not be drained on the path that blocks a thread while it waits. + case IAsyncDisposable asyncDisposable: + await asyncDisposable.DisposeAsync().ConfigureAwait(false); + break; + + case IDisposable disposable: + disposable.Dispose(); + break; + + default: + break; + } + } + catch + { + // A boot that already failed carries the exception a deployer needs; a resource that + // also fails to close must not replace or hide it. + } } } - } - private static InvalidOperationException NotStarted() - => new( - "AgentCore has not booted: the document is loaded, and every adapter it names is opened, " - + "when the host starts. Resolve this service from a started host — await " - + "host.StartAsync(), or app.Run() — and not from a provider nobody started."); - - private sealed record BootState( - AgentCoreConfiguration Configuration, - ResolvedSecrets Secrets, - ITelemetrySession? Telemetry, - ToolRegistry Tools, - Conversations Conversations, - IBlobStore? Blobs, - EvaluatorRegistry Evaluators, - CompiledGraph Graph, - EntryRegistry Entries, - QueuedAuditSink AuditQueue, - IKnowledgeRetrievalPort? Knowledge, - IReadOnlyList? ConversationAdapters, - IReadOnlyList? SpeechAdapters, - RequestDelegate? ConversationHandler, - string? ConversationUnroutable); -} + private static InvalidOperationException NotStarted() + { + return new( + "AgentCore has not booted: the document is loaded, and every adapter it names is opened, " + + "when the host starts. Resolve this service from a started host — await " + + "host.StartAsync(), or app.Run() — and not from a provider nobody started."); + } -/// Every line writes itself, below what each startup step logs. -internal static partial class AgentCoreBootLog -{ - /// One of section 8.5's structural warnings, or one of section 10's two (K33, K39). - /// The boot's own logger. - /// The warning's ToString(): its pointer, its message, and its check. - [LoggerMessage( - EventId = 1, - Level = LogLevel.Warning, - Message = "{Warning}")] - public static partial void ConfigurationWarning(ILogger logger, string warning); + private sealed record BootState( + AgentCoreConfiguration Configuration, + ResolvedSecrets Secrets, + ITelemetrySession? Telemetry, + ToolRegistry Tools, + Conversations Conversations, + IBlobStore? Blobs, + EvaluatorRegistry Evaluators, + CompiledGraph Graph, + EntryRegistry Entries, + QueuedAuditSink AuditQueue, + IKnowledgeRetrievalPort? Knowledge, + IReadOnlyList? ConversationAdapters, + IReadOnlyList? SpeechAdapters, + RequestDelegate? ConversationHandler, + string? ConversationUnroutable); + } + + /// Every line writes itself, below what each startup step logs. + internal static partial class AgentCoreBootLog + { + /// One of section 8.5's structural warnings, or one of section 10's two (K33, K39). + /// The boot's own logger. + /// The warning's ToString(): its pointer, its message, and its check. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Warning, + Message = "{Warning}")] + public static partial void ConfigurationWarning(ILogger logger, string warning); + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBootService.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBootService.cs index 5d693759..eb498f87 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBootService.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBootService.cs @@ -1,33 +1,51 @@ using Microsoft.Extensions.Hosting; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Runs the boot, before anything a half-booted graph could answer. -/// The owner every opened resource belongs to. -internal sealed class AgentCoreBootService(AgentCoreBoot boot) : IHostedLifecycleService +namespace AgentCore.AspNetCore.DependencyInjection { - /// Loads the document and opens everything it names. - /// Cancels the secret reads and the adapter builds. - /// A task that completes when the graph is ready to take a conversation. - public Task StartingAsync(CancellationToken cancellationToken) - => boot.BootAsync(cancellationToken).AsTask(); + /// Runs the boot, before anything a half-booted graph could answer. + /// The owner every opened resource belongs to. + internal sealed class AgentCoreBootService(AgentCoreBoot boot) : IHostedLifecycleService + { + /// Loads the document and opens everything it names. + /// Cancels the secret reads and the adapter builds. + /// A task that completes when the graph is ready to take a conversation. + public Task StartingAsync(CancellationToken cancellationToken) + { + return boot.BootAsync(cancellationToken).AsTask(); + } - /// - public Task StartAsync(CancellationToken cancellationToken) => Task.CompletedTask; + /// + public Task StartAsync(CancellationToken cancellationToken) + { + return Task.CompletedTask; + } - /// - public Task StartedAsync(CancellationToken cancellationToken) => Task.CompletedTask; + /// + public Task StartedAsync(CancellationToken cancellationToken) + { + return Task.CompletedTask; + } - /// - public Task StoppingAsync(CancellationToken cancellationToken) => Task.CompletedTask; + /// + public Task StoppingAsync(CancellationToken cancellationToken) + { + return Task.CompletedTask; + } - /// - /// - /// Nothing closes here. A failed start never calls StopAsync at all, so shutdown lives in - /// , which the container reaches on both paths. - /// - public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask; + /// + /// + /// Nothing closes here. A failed start never calls StopAsync at all, so shutdown lives in + /// , which the container reaches on both paths. + /// + public Task StopAsync(CancellationToken cancellationToken) + { + return Task.CompletedTask; + } - /// - public Task StoppedAsync(CancellationToken cancellationToken) => Task.CompletedTask; + /// + public Task StoppedAsync(CancellationToken cancellationToken) + { + return Task.CompletedTask; + } + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreHttpClients.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreHttpClients.cs index cb2af34d..52d39125 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreHttpClients.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreHttpClients.cs @@ -6,172 +6,185 @@ using Polly; using Polly.Retry; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// -/// The one outbound HTTP pipeline this host sends every vendor request on. -/// -public sealed class AgentCoreHttpClients : IHttpClientFactory, IHttpMessageHandlerFactory, IDisposable +namespace AgentCore.AspNetCore.DependencyInjection { - /// The deadline of one call, over every attempt this pipeline makes. - /// - /// This is the whole of a send and not one attempt: attempts and the - /// backoff between them all have to finish inside it. - /// - public static readonly TimeSpan RequestDeadline = TimeSpan.FromSeconds(100); - - /// How long a pooled connection is kept before it is opened again. - public static readonly TimeSpan ConnectionLifetime = TimeSpan.FromMinutes(2); - - /// The wait before the first retry. Each later one waits about twice the last. - public static readonly TimeSpan FirstRetryDelay = TimeSpan.FromSeconds(1); - - /// The number of attempts one request gets, including the first. - public const int MaxAttempts = 3; - - /// The name the resilience handler of this pipeline reports as. - public const string PipelineName = "agentcore-http"; - - private readonly ServiceProvider _provider; - - private readonly IHttpClientFactory _clients; - - /// Builds the pipeline. - /// - /// The handler every client of this pipeline sends on, or for the pooled - /// default. A caller that passes one keeps it: this pipeline neither rotates nor disposes it. - /// - /// - /// The factory the retry writes its lines to, or to write nowhere. - /// - public AgentCoreHttpClients(HttpMessageHandler? primaryHandler = null, ILoggerFactory? loggers = null) + /// + /// The one outbound HTTP pipeline this host sends every vendor request on. + /// + public sealed class AgentCoreHttpClients : IHttpClientFactory, IHttpMessageHandlerFactory, IDisposable { - ServiceCollection services = []; + /// The deadline of one call, over every attempt this pipeline makes. + /// + /// This is the whole of a send and not one attempt: attempts and the + /// backoff between them all have to finish inside it. + /// + public static readonly TimeSpan RequestDeadline = TimeSpan.FromSeconds(100); + + /// How long a pooled connection is kept before it is opened again. + public static readonly TimeSpan ConnectionLifetime = TimeSpan.FromMinutes(2); + + /// The wait before the first retry. Each later one waits about twice the last. + public static readonly TimeSpan FirstRetryDelay = TimeSpan.FromSeconds(1); + + /// The number of attempts one request gets, including the first. + public const int MaxAttempts = 3; + + /// The name the resilience handler of this pipeline reports as. + public const string PipelineName = "agentcore-http"; + + private readonly ServiceProvider _provider; + + private readonly IHttpClientFactory _clients; + + /// Builds the pipeline. + /// + /// The handler every client of this pipeline sends on, or for the pooled + /// default. A caller that passes one keeps it: this pipeline neither rotates nor disposes it. + /// + /// + /// The factory the retry writes its lines to, or to write nowhere. + /// + public AgentCoreHttpClients(HttpMessageHandler? primaryHandler = null, ILoggerFactory? loggers = null) + { + ServiceCollection services = []; + + _ = services.AddLogging(); + if (loggers is not null) + { + _ = services.Replace(ServiceDescriptor.Singleton(loggers)); + } - services.AddLogging(); - if (loggers is not null) + _ = services.AddHttpClient(); + _ = services.ConfigureHttpClientDefaults(builder => + { + _ = builder.ConfigureHttpClient(client => client.Timeout = RequestDeadline); + + if (primaryHandler is null) + { + _ = builder.ConfigurePrimaryHttpMessageHandler( + () => new SocketsHttpHandler { PooledConnectionLifetime = ConnectionLifetime }); + } + else + { + // The caller owns this handler, so the rotation that would dispose it is turned off. + _ = builder.ConfigurePrimaryHttpMessageHandler(() => primaryHandler) + .SetHandlerLifetime(Timeout.InfiniteTimeSpan); + } + + _ = builder.AddResilienceHandler(PipelineName, Retry); + }); + + _provider = services.BuildServiceProvider(); + _clients = _provider.GetRequiredService(); + } + + /// Opens one client of this pipeline. + /// The vendor name, such as agentcore.openai. Any name is served. + /// The client. It carries the deadline and the retry, and no base address. + public HttpClient CreateClient(string name) { - services.Replace(ServiceDescriptor.Singleton(loggers)); + return _clients.CreateClient(name); } - services.AddHttpClient(); - services.ConfigureHttpClientDefaults(builder => + /// Opens the handler chain of one client, for a caller that adds a handler of its own. + /// The vendor name, such as agentcore.openai. Any name is served. + /// The chain. This pipeline owns it, so a caller never disposes it. + public HttpMessageHandler CreateHandler(string name) { - builder.ConfigureHttpClient(client => client.Timeout = RequestDeadline); + return ((IHttpMessageHandlerFactory)_clients).CreateHandler(name); + } - if (primaryHandler is null) + /// Closes the pipeline. A handler the caller passed in is left open. + public void Dispose() + { + _provider.Dispose(); + } + + /// Reads the wait one answer asked for, in either form the header takes. + /// The answer, or when the attempt threw. + /// The wait, or to leave the backoff of this pipeline in place. + internal static TimeSpan? RetryAfter(HttpResponseMessage? response) + { + if (response?.Headers.RetryAfter is not { } asked) { - builder.ConfigurePrimaryHttpMessageHandler( - () => new SocketsHttpHandler { PooledConnectionLifetime = ConnectionLifetime }); + return null; } - else + + if (asked.Delta is { } delta && delta > TimeSpan.Zero) { - // The caller owns this handler, so the rotation that would dispose it is turned off. - builder.ConfigurePrimaryHttpMessageHandler(() => primaryHandler) - .SetHandlerLifetime(Timeout.InfiniteTimeSpan); + return delta; } - builder.AddResilienceHandler(PipelineName, Retry); - }); - - _provider = services.BuildServiceProvider(); - _clients = _provider.GetRequiredService(); - } - - /// Opens one client of this pipeline. - /// The vendor name, such as agentcore.openai. Any name is served. - /// The client. It carries the deadline and the retry, and no base address. - public HttpClient CreateClient(string name) => _clients.CreateClient(name); - - /// Opens the handler chain of one client, for a caller that adds a handler of its own. - /// The vendor name, such as agentcore.openai. Any name is served. - /// The chain. This pipeline owns it, so a caller never disposes it. - public HttpMessageHandler CreateHandler(string name) - => ((IHttpMessageHandlerFactory)_clients).CreateHandler(name); - - /// Closes the pipeline. A handler the caller passed in is left open. - public void Dispose() => _provider.Dispose(); + if (asked.Date is { } until) + { + TimeSpan wait = until - DateTimeOffset.UtcNow; + if (wait > TimeSpan.Zero) + { + return wait; + } + } - /// Reads the wait one answer asked for, in either form the header takes. - /// The answer, or when the attempt threw. - /// The wait, or to leave the backoff of this pipeline in place. - internal static TimeSpan? RetryAfter(HttpResponseMessage? response) - { - if (response?.Headers.RetryAfter is not { } asked) - { return null; } - if (asked.Delta is { } delta && delta > TimeSpan.Zero) + /// The methods this pipeline retries. Every other method, POST and PATCH included, is sent once. + /// + /// GET, HEAD, OPTIONS, and TRACE never write, and PUT and DELETE are defined to be idempotent even + /// though they do. A kind: http tool that POSTs must not fire its side effect more than + /// once, so POST and PATCH — and any method this pipeline does not recognize — are never retried, + /// regardless of how the attempt failed. + /// + private static readonly FrozenSet IdempotentMethods = new[] { - return delta; + HttpMethod.Get, + HttpMethod.Head, + HttpMethod.Options, + HttpMethod.Trace, + HttpMethod.Put, + HttpMethod.Delete, + }.ToFrozenSet(); + + /// Adds the one retry strategy every client of this pipeline shares. + /// The strategy builder of this client. + private static void Retry(ResiliencePipelineBuilder builder) + { + _ = builder.AddRetry(new RetryStrategyOptions + { + MaxRetryAttempts = MaxAttempts - 1, + BackoffType = DelayBackoffType.Exponential, + UseJitter = true, + Delay = FirstRetryDelay, + ShouldHandle = ShouldRetry, + DelayGenerator = arguments => ValueTask.FromResult(RetryAfter(arguments.Outcome.Result)), + }); } - if (asked.Date is { } until) + /// Decides whether one failed attempt is worth repeating. + /// The outcome of the attempt, and the context it ran in. + /// when the failure is transient and the method is safe to repeat. + private static ValueTask ShouldRetry(RetryPredicateArguments arguments) { - var wait = until - DateTimeOffset.UtcNow; - if (wait > TimeSpan.Zero) + HttpMethod? method = arguments.Context.GetRequestMessage()?.Method; + if (method is null || !IdempotentMethods.Contains(method)) { - return wait; + return ValueTask.FromResult(false); } - } - return null; - } + Outcome outcome = arguments.Outcome; + bool isTransientFailure = (outcome.Result is { } response && IsTransient(response)) + || outcome.Exception is HttpRequestException + || outcome.Exception is TaskCanceledException; + return ValueTask.FromResult(isTransientFailure); + } - /// The methods this pipeline retries. Every other method, POST and PATCH included, is sent once. - /// - /// GET, HEAD, OPTIONS, and TRACE never write, and PUT and DELETE are defined to be idempotent even - /// though they do. A kind: http tool that POSTs must not fire its side effect more than - /// once, so POST and PATCH — and any method this pipeline does not recognize — are never retried, - /// regardless of how the attempt failed. - /// - private static readonly FrozenSet IdempotentMethods = new[] - { - HttpMethod.Get, - HttpMethod.Head, - HttpMethod.Options, - HttpMethod.Trace, - HttpMethod.Put, - HttpMethod.Delete, - }.ToFrozenSet(); - - /// Adds the one retry strategy every client of this pipeline shares. - /// The strategy builder of this client. - private static void Retry(ResiliencePipelineBuilder builder) - => builder.AddRetry(new RetryStrategyOptions + /// Reads whether one answer is worth sending again. + /// The answer. + /// when the endpoint failed rather than refused. + private static bool IsTransient(HttpResponseMessage response) { - MaxRetryAttempts = MaxAttempts - 1, - BackoffType = DelayBackoffType.Exponential, - UseJitter = true, - Delay = FirstRetryDelay, - ShouldHandle = ShouldRetry, - DelayGenerator = arguments => ValueTask.FromResult(RetryAfter(arguments.Outcome.Result)), - }); - - /// Decides whether one failed attempt is worth repeating. - /// The outcome of the attempt, and the context it ran in. - /// when the failure is transient and the method is safe to repeat. - private static ValueTask ShouldRetry(RetryPredicateArguments arguments) - { - var method = arguments.Context.GetRequestMessage()?.Method; - if (method is null || !IdempotentMethods.Contains(method)) - { - return ValueTask.FromResult(false); + return (int)response.StatusCode >= 500 + || response.StatusCode == HttpStatusCode.TooManyRequests + || response.StatusCode == HttpStatusCode.RequestTimeout; } - - var outcome = arguments.Outcome; - var isTransientFailure = (outcome.Result is { } response && IsTransient(response)) - || outcome.Exception is HttpRequestException - || outcome.Exception is TaskCanceledException; - return ValueTask.FromResult(isTransientFailure); } - - /// Reads whether one answer is worth sending again. - /// The answer. - /// when the endpoint failed rather than refused. - private static bool IsTransient(HttpResponseMessage response) - => (int)response.StatusCode >= 500 - || response.StatusCode == HttpStatusCode.TooManyRequests - || response.StatusCode == HttpStatusCode.RequestTimeout; } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs index 620a43a2..e8ae944e 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs @@ -8,353 +8,354 @@ using Microsoft.Extensions.Caching.Hybrid; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// -/// Everything AddAgentCore needs that the document does not hold. -/// -public sealed class AgentCoreOptions +namespace AgentCore.AspNetCore.DependencyInjection { - private readonly List> _toolSources = []; - - private readonly List _observers = []; - - /// Gets the path of the configuration document, or . - public string? ConfigurationPath { get; set; } - - /// Gets or sets a document the host already loaded, or . - public AgentCoreConfiguration? Configuration { get; set; } - - /// Gets or sets the chain that reads a ${secret:name} reference. - public ISecretResolverPort? SecretResolver { get; set; } - - /// Gets or sets the clock this container runs on, or for . - public TimeProvider? TimeProvider { get; set; } - - /// Gets or sets the factory the library takes its loggers from. - public ILoggerFactory? LoggerFactory { get; set; } - - /// - /// Gets or sets the cache this container reads through, or for none. - /// - public HybridCache? Cache { get; set; } - - /// Gets the map from a binds: name to the host delegate behind it. - public ToolBindingRegistry Bindings { get; } = new(); - - /// Gets the seam that resolves a model reference, or . - internal Func>? ChatClients { get; private set; } - - /// Gets the embedding vendors the host registered, or . - internal IReadOnlyList? Embeddings { get; private set; } - - /// Gets the knowledge vendors the host registered, or . - internal IReadOnlyList? KnowledgeStores { get; private set; } - - /// Gets the seam that beats the providers.knowledge.kind registry, or . - internal Func? KnowledgeRetrieval { get; private set; } - - /// Gets the analyzers providers.knowledge.analyzer may name. - internal IReadOnlyList KnowledgeAnalyzers { get; private set; } = []; - - /// Gets the mappers providers.knowledge.mapper may name. - internal IReadOnlyList KnowledgeMappers { get; private set; } = []; - - /// Gets the citation formatters providers.knowledge.citation may name. - internal IReadOnlyList KnowledgeCitations { get; private set; } = []; - - /// Gets the moderation vendors the host registered, or . - internal IReadOnlyList? Moderation { get; private set; } - - /// Gets the telemetry vendors the host registered, or . - internal IReadOnlyList? Telemetry { get; private set; } - - /// Gets the audit sink vendors the host registered, or . - internal IReadOnlyList? AuditSinks { get; private set; } - - /// Gets the conversation store vendors the host registered, or . - internal IReadOnlyList? ConversationStores { get; private set; } - - /// Gets the blob store vendors the host registered, or . - internal IReadOnlyList? BlobStores { get; private set; } - - /// Gets the speech vendors the host registered, or . - internal IReadOnlyList? Speech { get; private set; } - - /// Gets the folder that holds the SKILL.md directories, or . - internal string? SkillsPath { get; private set; } - - /// Gets the skills source a host bound directly, or . - internal AgentSkillsSource? SkillsSource { get; private set; } - - /// Gets the conversation transports this host supports, or . - internal IReadOnlyList? ConversationAdapters { get; private set; } - - /// Gets the folder under which every conversation gets its own workspace, or . - internal string? WorkspaceRoot { get; private set; } - - /// Gets the extra tool sources, in the order the registry asks them. - internal IReadOnlyList> ToolSources => _toolSources; - - /// Gets the observers the host registered, in the order it registered them. - internal IReadOnlyList Observers => _observers; - - /// Gets the store opener the host bound, or for the in-memory default. - internal Func? ConversationSessions { get; private set; } - - /// Binds the session store, one per entry. - /// - /// Opens the store for one entry. It takes the entry name and the factory that builds that - /// entry's sessions, and it runs once per entry the document declares. Each conversation must return a - /// distinct store: two entries that share one store let a vendor call id arriving on both - /// entries read one call through two shapes. - /// - /// These options, so a host chains its conversations. - public AgentCoreOptions UseConversationSessions(Func open) - { - ArgumentNullException.ThrowIfNull(open); - ConversationSessions = open; - return this; - } - - /// Binds the vendor adapters, and the document picks one by each entry's kind. - /// One adapter for each vendor this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseChatClients(params IChatClientAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - return UseChatClients(async (startup, cancellationToken) => await CompositeChatClientFactory - .CreateAsync(startup.Configuration, SecretResolver, adapters, cancellationToken) - .ConfigureAwait(false)); - } - - /// Binds the adapter that turns a model reference into a chat client. - /// Builds the adapter from the loaded document, without a wait. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseChatClients(Func chatClients) - { - ArgumentNullException.ThrowIfNull(chatClients); - return UseChatClients((startup, _) => ValueTask.FromResult(chatClients(startup))); - } - - /// Binds the adapter that turns a model reference into a chat client, with a wait. - /// Builds the adapter from the loaded document. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseChatClients(Func> chatClients) - { - ArgumentNullException.ThrowIfNull(chatClients); - ChatClients = chatClients; - return this; - } - - /// Binds the embedding vendors, and the document picks one by providers.embeddings.kind. - /// One adapter for each embedding vendor this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseEmbeddings(params IEmbeddingGeneratorAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - Embeddings = adapters; - return this; - } - - /// Binds the knowledge vendors, and the document picks one by providers.knowledge.kind. - /// One adapter for each knowledge vendor this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseKnowledgeStores(params IKnowledgeStoreAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - KnowledgeStores = adapters; - return this; - } - - /// Binds the adapter that beats the providers.knowledge.kind registry. - /// Builds the adapter from the loaded document. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseKnowledgeRetrieval(Func retrieval) - { - ArgumentNullException.ThrowIfNull(retrieval); - KnowledgeRetrieval = retrieval; - return this; - } - - /// Binds the query analyzers, and the document picks one by providers.knowledge.analyzer. - public AgentCoreOptions UseKnowledgeQueryAnalyzers(params IKnowledgeQueryAnalyzer[] analyzers) - { - ArgumentNullException.ThrowIfNull(analyzers); - KnowledgeAnalyzers = analyzers; - return this; - } - - /// Binds the point mappers, and the document picks one by providers.knowledge.mapper. - public AgentCoreOptions UseKnowledgePointMappers(params IKnowledgePointMapper[] mappers) - { - ArgumentNullException.ThrowIfNull(mappers); - KnowledgeMappers = mappers; - return this; - } - /// - /// Binds the citation formatters, and the document picks one by - /// providers.knowledge.citation. + /// Everything AddAgentCore needs that the document does not hold. /// - public AgentCoreOptions UseKnowledgeCitationFormatters(params IKnowledgeCitationFormatter[] formatters) - { - ArgumentNullException.ThrowIfNull(formatters); - KnowledgeCitations = formatters; - return this; - } - - /// Binds the moderation vendors, and the document picks one by kind. - /// The vendors this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseModeration(params IModerationAdapter[] adapters) + public sealed class AgentCoreOptions { - ArgumentNullException.ThrowIfNull(adapters); - Moderation = adapters; - return this; - } - - /// Binds the telemetry vendors, and the document picks one by kind. - /// The vendors this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseTelemetry(params ITelemetryAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - Telemetry = adapters; - return this; - } - - /// Binds the audit sink vendors, and the document picks one by kind. - /// The vendors this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseAuditSinks(params IAuditSinkAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - AuditSinks = adapters; - return this; - } + private readonly List> _toolSources = []; - /// Binds the conversation store vendors, and the document picks one by kind. - /// The vendors this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseConversationStores(params IConversationStoreAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - ConversationStores = adapters; - return this; - } + private readonly List _observers = []; - /// Binds the blob store vendors, and the document picks one by providers.blobs.kind. - /// The vendors this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseBlobStores(params IBlobStoreAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - BlobStores = adapters; - return this; - } + /// Gets the path of the configuration document, or . + public string? ConfigurationPath { get; set; } - /// Binds the host's own readings of a conversation, beside the three this library keeps. - /// - /// What the host wants told about every conversation. Each one takes every fact, in the order the conversation - /// produced it. An empty set is legal and registers nothing. - /// - /// These options, so a host chains its conversations. - public AgentCoreOptions UseObservers(params IConversationObserver[] observers) - { - ArgumentNullException.ThrowIfNull(observers); - _observers.AddRange(observers); - return this; - } + /// Gets or sets a document the host already loaded, or . + public AgentCoreConfiguration? Configuration { get; set; } - /// Binds the speech vendors, and the document picks one by kind. - /// The vendors this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseSpeech(params ISpeechAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - Speech = adapters; - return this; - } + /// Gets or sets the chain that reads a ${secret:name} reference. + public ISecretResolverPort? SecretResolver { get; set; } - /// Binds the folder that holds this host's SKILL.md directories. - public AgentCoreOptions UseSkills(string path) - { - ArgumentException.ThrowIfNullOrWhiteSpace(path); - SkillsPath = path; - SkillsSource = null; - return this; - } + /// Gets or sets the clock this container runs on, or for . + public TimeProvider? TimeProvider { get; set; } - /// Binds a skills source directly, for a host with no filesystem to read. - public AgentCoreOptions UseSkills(AgentSkillsSource source) - { - ArgumentNullException.ThrowIfNull(source); - SkillsSource = source; - SkillsPath = null; - return this; - } + /// Gets or sets the factory the library takes its loggers from. + public ILoggerFactory? LoggerFactory { get; set; } - /// Lists the vendors that may carry a conversation, so providers.conversation.kind can pick one. - /// The transports this host supports. - /// These options, so a host chains its conversations. - public AgentCoreOptions UseConversation(params IConversationAdapter[] adapters) - { - ArgumentNullException.ThrowIfNull(adapters); - ConversationAdapters = adapters; - return this; - } + /// + /// Gets or sets the cache this container reads through, or for none. + /// + public HybridCache? Cache { get; set; } - /// Adds one tool source the registry asks at startup. - /// - /// Builds the source from the loaded document. The composition root calls this once and keeps - /// what it returns: when the source it builds implements or - /// , the composition root closes it when the host stops. Do not return an - /// instance the host still needs after that. - /// - /// These options, so a host chains its conversations. - public AgentCoreOptions AddToolSource(Func toolSource) - { - ArgumentNullException.ThrowIfNull(toolSource); - _toolSources.Add(toolSource); - return this; - } + /// Gets the map from a binds: name to the host delegate behind it. + public ToolBindingRegistry Bindings { get; } = new(); - /// - /// Binds the folder under which every conversation gets its own workspace directory, - /// <root>/<conversationId>/, created with the conversation and deleted when the conversation ends. - /// - public AgentCoreOptions UseWorkspace(string root) - { - ArgumentException.ThrowIfNullOrWhiteSpace(root); - WorkspaceRoot = root; - return this; - } + /// Gets the seam that resolves a model reference, or . + internal Func>? ChatClients { get; private set; } - /// Registers one host delegate behind a binds: name. - /// The name a binds: field writes, such as CreateCase. - /// The delegate the tool calls. - /// These options, so a host chains its conversations. - /// The name is already registered. - public AgentCoreOptions Bind(string name, ToolBinding binding) - { - Bindings.Register(name, binding); - return this; - } + /// Gets the embedding vendors the host registered, or . + internal IReadOnlyList? Embeddings { get; private set; } - /// Registers one host method behind a binds: name. - /// The name a binds: field writes, such as CreateCase. - /// - /// The method the tool calls. Its parameters are the arguments the model fills, and their JSON - /// Schema, so the declaration writes no parameters:. A parameter of type - /// is filled by the runtime with the conversation the turn belongs to, and - /// is not exposed to the model. - /// - /// These options, so a host chains its conversations. - /// The name is already registered. - public AgentCoreOptions Bind(string name, Delegate method) - { - Bindings.Register(name, method); - return this; + /// Gets the knowledge vendors the host registered, or . + internal IReadOnlyList? KnowledgeStores { get; private set; } + + /// Gets the seam that beats the providers.knowledge.kind registry, or . + internal Func? KnowledgeRetrieval { get; private set; } + + /// Gets the analyzers providers.knowledge.analyzer may name. + internal IReadOnlyList KnowledgeAnalyzers { get; private set; } = []; + + /// Gets the mappers providers.knowledge.mapper may name. + internal IReadOnlyList KnowledgeMappers { get; private set; } = []; + + /// Gets the citation formatters providers.knowledge.citation may name. + internal IReadOnlyList KnowledgeCitations { get; private set; } = []; + + /// Gets the moderation vendors the host registered, or . + internal IReadOnlyList? Moderation { get; private set; } + + /// Gets the telemetry vendors the host registered, or . + internal IReadOnlyList? Telemetry { get; private set; } + + /// Gets the audit sink vendors the host registered, or . + internal IReadOnlyList? AuditSinks { get; private set; } + + /// Gets the conversation store vendors the host registered, or . + internal IReadOnlyList? ConversationStores { get; private set; } + + /// Gets the blob store vendors the host registered, or . + internal IReadOnlyList? BlobStores { get; private set; } + + /// Gets the speech vendors the host registered, or . + internal IReadOnlyList? Speech { get; private set; } + + /// Gets the folder that holds the SKILL.md directories, or . + internal string? SkillsPath { get; private set; } + + /// Gets the skills source a host bound directly, or . + internal AgentSkillsSource? SkillsSource { get; private set; } + + /// Gets the conversation transports this host supports, or . + internal IReadOnlyList? ConversationAdapters { get; private set; } + + /// Gets the folder under which every conversation gets its own workspace, or . + internal string? WorkspaceRoot { get; private set; } + + /// Gets the extra tool sources, in the order the registry asks them. + internal IReadOnlyList> ToolSources => _toolSources; + + /// Gets the observers the host registered, in the order it registered them. + internal IReadOnlyList Observers => _observers; + + /// Gets the store opener the host bound, or for the in-memory default. + internal Func? ConversationSessions { get; private set; } + + /// Binds the session store, one per entry. + /// + /// Opens the store for one entry. It takes the entry name and the factory that builds that + /// entry's sessions, and it runs once per entry the document declares. Each conversation must return a + /// distinct store: two entries that share one store let a vendor call id arriving on both + /// entries read one call through two shapes. + /// + /// These options, so a host chains its conversations. + public AgentCoreOptions UseConversationSessions(Func open) + { + ArgumentNullException.ThrowIfNull(open); + ConversationSessions = open; + return this; + } + + /// Binds the vendor adapters, and the document picks one by each entry's kind. + /// One adapter for each vendor this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseChatClients(params IChatClientAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + return UseChatClients(async (startup, cancellationToken) => await CompositeChatClientFactory + .CreateAsync(startup.Configuration, SecretResolver, adapters, cancellationToken) + .ConfigureAwait(false)); + } + + /// Binds the adapter that turns a model reference into a chat client. + /// Builds the adapter from the loaded document, without a wait. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseChatClients(Func chatClients) + { + ArgumentNullException.ThrowIfNull(chatClients); + return UseChatClients((startup, _) => ValueTask.FromResult(chatClients(startup))); + } + + /// Binds the adapter that turns a model reference into a chat client, with a wait. + /// Builds the adapter from the loaded document. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseChatClients(Func> chatClients) + { + ArgumentNullException.ThrowIfNull(chatClients); + ChatClients = chatClients; + return this; + } + + /// Binds the embedding vendors, and the document picks one by providers.embeddings.kind. + /// One adapter for each embedding vendor this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseEmbeddings(params IEmbeddingGeneratorAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + Embeddings = adapters; + return this; + } + + /// Binds the knowledge vendors, and the document picks one by providers.knowledge.kind. + /// One adapter for each knowledge vendor this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseKnowledgeStores(params IKnowledgeStoreAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + KnowledgeStores = adapters; + return this; + } + + /// Binds the adapter that beats the providers.knowledge.kind registry. + /// Builds the adapter from the loaded document. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseKnowledgeRetrieval(Func retrieval) + { + ArgumentNullException.ThrowIfNull(retrieval); + KnowledgeRetrieval = retrieval; + return this; + } + + /// Binds the query analyzers, and the document picks one by providers.knowledge.analyzer. + public AgentCoreOptions UseKnowledgeQueryAnalyzers(params IKnowledgeQueryAnalyzer[] analyzers) + { + ArgumentNullException.ThrowIfNull(analyzers); + KnowledgeAnalyzers = analyzers; + return this; + } + + /// Binds the point mappers, and the document picks one by providers.knowledge.mapper. + public AgentCoreOptions UseKnowledgePointMappers(params IKnowledgePointMapper[] mappers) + { + ArgumentNullException.ThrowIfNull(mappers); + KnowledgeMappers = mappers; + return this; + } + + /// + /// Binds the citation formatters, and the document picks one by + /// providers.knowledge.citation. + /// + public AgentCoreOptions UseKnowledgeCitationFormatters(params IKnowledgeCitationFormatter[] formatters) + { + ArgumentNullException.ThrowIfNull(formatters); + KnowledgeCitations = formatters; + return this; + } + + /// Binds the moderation vendors, and the document picks one by kind. + /// The vendors this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseModeration(params IModerationAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + Moderation = adapters; + return this; + } + + /// Binds the telemetry vendors, and the document picks one by kind. + /// The vendors this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseTelemetry(params ITelemetryAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + Telemetry = adapters; + return this; + } + + /// Binds the audit sink vendors, and the document picks one by kind. + /// The vendors this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseAuditSinks(params IAuditSinkAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + AuditSinks = adapters; + return this; + } + + /// Binds the conversation store vendors, and the document picks one by kind. + /// The vendors this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseConversationStores(params IConversationStoreAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + ConversationStores = adapters; + return this; + } + + /// Binds the blob store vendors, and the document picks one by providers.blobs.kind. + /// The vendors this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseBlobStores(params IBlobStoreAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + BlobStores = adapters; + return this; + } + + /// Binds the host's own readings of a conversation, beside the three this library keeps. + /// + /// What the host wants told about every conversation. Each one takes every fact, in the order the conversation + /// produced it. An empty set is legal and registers nothing. + /// + /// These options, so a host chains its conversations. + public AgentCoreOptions UseObservers(params IConversationObserver[] observers) + { + ArgumentNullException.ThrowIfNull(observers); + _observers.AddRange(observers); + return this; + } + + /// Binds the speech vendors, and the document picks one by kind. + /// The vendors this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseSpeech(params ISpeechAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + Speech = adapters; + return this; + } + + /// Binds the folder that holds this host's SKILL.md directories. + public AgentCoreOptions UseSkills(string path) + { + ArgumentException.ThrowIfNullOrWhiteSpace(path); + SkillsPath = path; + SkillsSource = null; + return this; + } + + /// Binds a skills source directly, for a host with no filesystem to read. + public AgentCoreOptions UseSkills(AgentSkillsSource source) + { + ArgumentNullException.ThrowIfNull(source); + SkillsSource = source; + SkillsPath = null; + return this; + } + + /// Lists the vendors that may carry a conversation, so providers.conversation.kind can pick one. + /// The transports this host supports. + /// These options, so a host chains its conversations. + public AgentCoreOptions UseConversation(params IConversationAdapter[] adapters) + { + ArgumentNullException.ThrowIfNull(adapters); + ConversationAdapters = adapters; + return this; + } + + /// Adds one tool source the registry asks at startup. + /// + /// Builds the source from the loaded document. The composition root calls this once and keeps + /// what it returns: when the source it builds implements or + /// , the composition root closes it when the host stops. Do not return an + /// instance the host still needs after that. + /// + /// These options, so a host chains its conversations. + public AgentCoreOptions AddToolSource(Func toolSource) + { + ArgumentNullException.ThrowIfNull(toolSource); + _toolSources.Add(toolSource); + return this; + } + + /// + /// Binds the folder under which every conversation gets its own workspace directory, + /// <root>/<conversationId>/, created with the conversation and deleted when the conversation ends. + /// + public AgentCoreOptions UseWorkspace(string root) + { + ArgumentException.ThrowIfNullOrWhiteSpace(root); + WorkspaceRoot = root; + return this; + } + + /// Registers one host delegate behind a binds: name. + /// The name a binds: field writes, such as CreateCase. + /// The delegate the tool calls. + /// These options, so a host chains its conversations. + /// The name is already registered. + public AgentCoreOptions Bind(string name, ToolBinding binding) + { + _ = Bindings.Register(name, binding); + return this; + } + + /// Registers one host method behind a binds: name. + /// The name a binds: field writes, such as CreateCase. + /// + /// The method the tool calls. Its parameters are the arguments the model fills, and their JSON + /// Schema, so the declaration writes no parameters:. A parameter of type + /// is filled by the runtime with the conversation the turn belongs to, and + /// is not exposed to the model. + /// + /// These options, so a host chains its conversations. + /// The name is already registered. + public AgentCoreOptions Bind(string name, Delegate method) + { + _ = Bindings.Register(name, method); + return this; + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs index ef05948c..9c31dc91 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs @@ -14,113 +14,116 @@ using Microsoft.Extensions.Logging.Abstractions; using Microsoft.Extensions.Options; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// -/// The composition root. It turns one document into the services a host resolves. -/// -public static class AgentCoreServiceCollectionExtensions +namespace AgentCore.AspNetCore.DependencyInjection { - /// Registers everything a conversation needs, and loads the document when the host starts. - /// The service collection of the host. - /// Binds the document and the adapters the document names. - /// The same collection, so a host chains its conversations. - public static IServiceCollection AddAgentCore( - this IServiceCollection services, - Action configure) + /// + /// The composition root. It turns one document into the services a host resolves. + /// + public static class AgentCoreServiceCollectionExtensions { - ArgumentNullException.ThrowIfNull(services); - ArgumentNullException.ThrowIfNull(configure); - - services.AddOptions(); - services.Configure(configure); - services.AddLogging(); - - services.AddSingleton(); - services.AddHostedService(); - services.AddSingleton(Boot(boot => boot.Configuration)); - services.AddSingleton(Boot(boot => boot.Secrets)); - services.AddSingleton(Boot(boot => boot.Bindings)); - services.AddSingleton(Boot(boot => boot.CompiledRegistry)); - services.AddSingleton(Boot(boot => boot.CompiledEntries)); - services.AddSingleton(Boot(boot => boot.ChatClients)); - services.AddSingleton(Boot(boot => boot.Guards)); - services.AddSingleton(Boot(boot => boot.Tools)); - services.AddSingleton(Boot(boot => boot.Conversations)); - services.AddSingleton(provider => provider.GetRequiredService()); - services.AddSingleton(provider => provider.GetRequiredService()); - services.AddSingleton(Boot(boot => boot.Entries)); - services.AddSingleton(provider => provider.GetRequiredService()); - services.AddSingleton(Boot(boot => boot.AuditQueue)); - - services.TryAddSingleton(provider => - new AgentCoreAgentSessionStore(provider.GetRequiredService())); - - services.TryAddSingleton(provider => - provider.GetRequiredService()); - - services.AddSingleton(provider => provider.GetRequiredService()); - - - services.AddSingleton(Boot(boot => boot.Telemetry!)); - services.AddSingleton(Boot(boot => boot.Knowledge!)); - services.AddSingleton(Boot(boot => boot.Blobs!)); - services.AddSingleton(Boot(boot => boot.ConversationAdapters!)); - services.AddSingleton(Boot(boot => boot.SpeechAdapters!)); - - services.TryAddSingleton(provider => - provider.GetRequiredService>().Value.TimeProvider - ?? TimeProvider.System); - - services.TryAddSingleton(provider => - provider.GetRequiredService>().Value.Cache - ?? PassThroughHybridCache.Instance); - - services.AddHostedService(provider => new ConversationSessionSweeper( - provider, - provider.GetRequiredService(), - provider.GetService()?.CreateLogger() - ?? NullLogger.Instance)); - - services.TryAddSingleton(provider => new ChatConversationTitler( - provider.GetRequiredService(), - provider.GetRequiredService() - .GetChatClient(provider.GetRequiredService().Titler?.Model))); - - services.TryAddSingleton(Boot(boot => boot.Evaluators)); - - services.TryAddSingleton(provider => new EvaluationSampler( - provider.GetRequiredService().Evaluation?.SampleRate - ?? EvaluationConfiguration.DefaultSampleRate)); - - services.TryAddSingleton(); - - return services; - } - - /// Registers WebSocket options that suit a phone conversation rather than a browser tab. - /// The service collection of the host. - /// The same collection, so a host chains its conversations. - public static IServiceCollection AddAgentCoreWebSockets(this IServiceCollection services) - { - ArgumentNullException.ThrowIfNull(services); - - return services.AddWebSockets(options => + /// Registers everything a conversation needs, and loads the document when the host starts. + /// The service collection of the host. + /// Binds the document and the adapters the document names. + /// The same collection, so a host chains its conversations. + public static IServiceCollection AddAgentCore( + this IServiceCollection services, + Action configure) { - options.KeepAliveInterval = TimeSpan.FromSeconds(20); - options.KeepAliveTimeout = TimeSpan.FromSeconds(20); - }); - } - - /// Reads one thing out of the boot, once the host has started it. - /// What the caller is registering. - /// Picks it off the started boot. - /// A factory the container conversations on first resolve. - private static Func Boot(Func read) - where T : class - => provider => + ArgumentNullException.ThrowIfNull(services); + ArgumentNullException.ThrowIfNull(configure); + + _ = services.AddOptions(); + _ = services.Configure(configure); + _ = services.AddLogging(); + + _ = services.AddSingleton(); + _ = services.AddHostedService(); + _ = services.AddSingleton(Boot(boot => boot.Configuration)); + _ = services.AddSingleton(Boot(boot => boot.Secrets)); + _ = services.AddSingleton(Boot(boot => boot.Bindings)); + _ = services.AddSingleton(Boot(boot => boot.CompiledRegistry)); + _ = services.AddSingleton(Boot(boot => boot.CompiledEntries)); + _ = services.AddSingleton(Boot(boot => boot.ChatClients)); + _ = services.AddSingleton(Boot(boot => boot.Guards)); + _ = services.AddSingleton(Boot(boot => boot.Tools)); + _ = services.AddSingleton(Boot(boot => boot.Conversations)); + _ = services.AddSingleton(provider => provider.GetRequiredService()); + _ = services.AddSingleton(provider => provider.GetRequiredService()); + _ = services.AddSingleton(Boot(boot => boot.Entries)); + _ = services.AddSingleton(provider => provider.GetRequiredService()); + _ = services.AddSingleton(Boot(boot => boot.AuditQueue)); + + services.TryAddSingleton(provider => + new AgentCoreAgentSessionStore(provider.GetRequiredService())); + + services.TryAddSingleton(provider => + provider.GetRequiredService()); + + _ = services.AddSingleton(provider => provider.GetRequiredService()); + + + _ = services.AddSingleton(Boot(boot => boot.Telemetry!)); + _ = services.AddSingleton(Boot(boot => boot.Knowledge!)); + _ = services.AddSingleton(Boot(boot => boot.Blobs!)); + _ = services.AddSingleton(Boot(boot => boot.ConversationAdapters!)); + _ = services.AddSingleton(Boot(boot => boot.SpeechAdapters!)); + + services.TryAddSingleton(provider => + provider.GetRequiredService>().Value.TimeProvider + ?? TimeProvider.System); + + services.TryAddSingleton(provider => + provider.GetRequiredService>().Value.Cache + ?? PassThroughHybridCache.Instance); + + _ = services.AddHostedService(provider => new ConversationSessionSweeper( + provider, + provider.GetRequiredService(), + provider.GetService()?.CreateLogger() + ?? NullLogger.Instance)); + + services.TryAddSingleton(provider => new ChatConversationTitler( + provider.GetRequiredService(), + provider.GetRequiredService() + .GetChatClient(provider.GetRequiredService().Titler?.Model))); + + services.TryAddSingleton(Boot(boot => boot.Evaluators)); + + services.TryAddSingleton(provider => new EvaluationSampler( + provider.GetRequiredService().Evaluation?.SampleRate + ?? EvaluationConfiguration.DefaultSampleRate)); + + services.TryAddSingleton(); + + return services; + } + + /// Registers WebSocket options that suit a phone conversation rather than a browser tab. + /// The service collection of the host. + /// The same collection, so a host chains its conversations. + public static IServiceCollection AddAgentCoreWebSockets(this IServiceCollection services) { - var boot = provider.GetRequiredService(); - return boot.Release(read(boot)); - }; + ArgumentNullException.ThrowIfNull(services); + + return services.AddWebSockets(options => + { + options.KeepAliveInterval = TimeSpan.FromSeconds(20); + options.KeepAliveTimeout = TimeSpan.FromSeconds(20); + }); + } + + /// Reads one thing out of the boot, once the host has started it. + /// What the caller is registering. + /// Picks it off the started boot. + /// A factory the container conversations on first resolve. + private static Func Boot(Func read) + where T : class + { + return provider => + { + AgentCoreBoot boot = provider.GetRequiredService(); + return boot.Release(read(boot)); + }; + } + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreStartup.cs index 0c0f721e..22bdaf60 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreStartup.cs @@ -1,30 +1,31 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Secrets; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// -/// What AddAgentCore already knows when it asks the host to build one seam. -/// -/// -/// The document loads and the secrets resolve before any adapter is built, so every adapter the host -/// contributes reads both. That is why the knowledge store can read providers.knowledge and -/// the HTTP tool factory can read the resolved secrets without either of them loading anything. -/// -public sealed class AgentCoreStartup +namespace AgentCore.AspNetCore.DependencyInjection { - /// Creates the context. - /// The loaded and validated document. - /// Every ${secret:name} value the document needs. - internal AgentCoreStartup(AgentCoreConfiguration configuration, ResolvedSecrets secrets) + /// + /// What AddAgentCore already knows when it asks the host to build one seam. + /// + /// + /// The document loads and the secrets resolve before any adapter is built, so every adapter the host + /// contributes reads both. That is why the knowledge store can read providers.knowledge and + /// the HTTP tool factory can read the resolved secrets without either of them loading anything. + /// + public sealed class AgentCoreStartup { - Configuration = configuration; - Secrets = secrets; - } + /// Creates the context. + /// The loaded and validated document. + /// Every ${secret:name} value the document needs. + internal AgentCoreStartup(AgentCoreConfiguration configuration, ResolvedSecrets secrets) + { + Configuration = configuration; + Secrets = secrets; + } - /// Gets the loaded document. It already passed checks 1 to 8. - public AgentCoreConfiguration Configuration { get; } + /// Gets the loaded document. It already passed checks 1 to 8. + public AgentCoreConfiguration Configuration { get; } - /// Gets the resolved secrets. It reads out values through its own formatter only. - public ResolvedSecrets Secrets { get; } + /// Gets the resolved secrets. It reads out values through its own formatter only. + public ResolvedSecrets Secrets { get; } + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/BlobStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/BlobStartup.cs index 1c2f4a8f..f7d0c682 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/BlobStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/BlobStartup.cs @@ -2,23 +2,26 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// Step 4d: open the blob store the document names, before the document is compiled. -internal static class BlobStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Opens the store providers.blobs names, or nothing. - /// The loaded document. It carries providers.blobs. - /// The options the host filled. It carries the blob store vendors. - /// Cancels the store open. - /// The store, or when the document names none. - internal static ValueTask OpenAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - CancellationToken cancellationToken) - => BlobStoreFactory.OpenAsync( - configuration, - options.SecretResolver, - options.BlobStores ?? [], - cancellationToken); + /// Step 4d: open the blob store the document names, before the document is compiled. + internal static class BlobStartup + { + /// Opens the store providers.blobs names, or nothing. + /// The loaded document. It carries providers.blobs. + /// The options the host filled. It carries the blob store vendors. + /// Cancels the store open. + /// The store, or when the document names none. + internal static ValueTask OpenAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + CancellationToken cancellationToken) + { + return BlobStoreFactory.OpenAsync( + configuration, + options.SecretResolver, + options.BlobStores ?? [], + cancellationToken); + } + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ChatClientStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ChatClientStartup.cs index 2644ec58..7fab5550 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ChatClientStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ChatClientStartup.cs @@ -1,28 +1,31 @@ using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Step 3c: build the chat client factory, before anything that needs a model. -/// -/// It is built from the document and the resolved secrets and from nothing else, so it can be built -/// before the tools. That ordering is what lets a shipped agent hold its own model rather than -/// looking one up at conversation time. -/// -internal static class ChatClientStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Asks the host for its chat clients. - /// The options the host filled. It carries the chat client seam. - /// The loaded document and the resolved secrets. - /// Cancels the build. - /// The factory. - /// The options bind no chat client adapter. - internal static ValueTask BuildAsync( - AgentCoreOptions options, - AgentCoreStartup startup, - CancellationToken cancellationToken) - => (options.ChatClients - ?? throw new InvalidOperationException( - "AddAgentCoreAsync binds no chat client adapter. Call options.UseChatClients(...), because the " - + "compile table asks it for every agent and for the extractor.")) - .Invoke(startup, cancellationToken); + /// Step 3c: build the chat client factory, before anything that needs a model. + /// + /// It is built from the document and the resolved secrets and from nothing else, so it can be built + /// before the tools. That ordering is what lets a shipped agent hold its own model rather than + /// looking one up at conversation time. + /// + internal static class ChatClientStartup + { + /// Asks the host for its chat clients. + /// The options the host filled. It carries the chat client seam. + /// The loaded document and the resolved secrets. + /// Cancels the build. + /// The factory. + /// The options bind no chat client adapter. + internal static ValueTask BuildAsync( + AgentCoreOptions options, + AgentCoreStartup startup, + CancellationToken cancellationToken) + { + return (options.ChatClients + ?? throw new InvalidOperationException( + "AddAgentCoreAsync binds no chat client adapter. Call options.UseChatClients(...), because the " + + "compile table asks it for every agent and for the extractor.")) + .Invoke(startup, cancellationToken); + } + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/CompilationStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/CompilationStartup.cs index f7a576f2..6c2ba554 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/CompilationStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/CompilationStartup.cs @@ -4,39 +4,40 @@ using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Everything step 5 compiled, and the two seams it needed to do it. -/// The factory the compile table asks for every agent and for the extractor. -/// The shared evaluator. It holds no state of its own. -/// The registry that compiled the document, and would compile it again. -/// The compiled entries, keyed by entry name. Every conversation shares them. -internal readonly record struct CompiledGraph( - IChatClientFactory ChatClients, - IGuardEvaluator Guards, - CompiledAgentRegistry Registry, - IReadOnlyDictionary Entries); - -/// Step 5: compile the document once, so every conversation shares the result. -internal static class CompilationStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Compiles every entry of the document against the seams the earlier steps built. - /// The loaded document. - /// - /// The seams the compile table needs. is set: R3 puts - /// moderation and the guards in the chat pipeline of every compiled agent, so both are bound - /// here rather than on the session factory. - /// - /// The compiled entries, and the seams that made them. - /// An entry does not compile. - internal static ValueTask CompileAsync(AgentCoreConfiguration configuration, AgentCompilationContext context) + /// Everything step 5 compiled, and the two seams it needed to do it. + /// The factory the compile table asks for every agent and for the extractor. + /// The shared evaluator. It holds no state of its own. + /// The registry that compiled the document, and would compile it again. + /// The compiled entries, keyed by entry name. Every conversation shares them. + internal readonly record struct CompiledGraph( + IChatClientFactory ChatClients, + IGuardEvaluator Guards, + CompiledAgentRegistry Registry, + IReadOnlyDictionary Entries); + + /// Step 5: compile the document once, so every conversation shares the result. + internal static class CompilationStartup { - var guards = context.Guards - ?? throw new InvalidOperationException("Step 5 compiles against a guard evaluator, and the context names none."); + /// Compiles every entry of the document against the seams the earlier steps built. + /// The loaded document. + /// + /// The seams the compile table needs. is set: R3 puts + /// moderation and the guards in the chat pipeline of every compiled agent, so both are bound + /// here rather than on the session factory. + /// + /// The compiled entries, and the seams that made them. + /// An entry does not compile. + internal static ValueTask CompileAsync(AgentCoreConfiguration configuration, AgentCompilationContext context) + { + IGuardEvaluator guards = context.Guards + ?? throw new InvalidOperationException("Step 5 compiles against a guard evaluator, and the context names none."); - CompiledAgentRegistry registry = new(); - var entries = registry.EnsureAll(configuration, context); + CompiledAgentRegistry registry = new(); + IReadOnlyDictionary entries = registry.EnsureAll(configuration, context); - return ValueTask.FromResult(new CompiledGraph(context.ChatClients, guards, registry, entries)); + return ValueTask.FromResult(new CompiledGraph(context.ChatClients, guards, registry, entries)); + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs index 5c872acf..af904403 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs @@ -2,66 +2,58 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// What hands back: the document, and the warnings its validation carried. -/// The loaded document. See for what it has already passed. -/// -/// Every partial-coverage warning check 5 raises, and section 10's ambiguity warning (K33). no longer discards these — a caller logs -/// them once a logger exists. -/// -internal readonly record struct ConfigurationLoadResult( - AgentCoreConfiguration Configuration, IReadOnlyList Warnings); - -/// Steps 1 and 2: read the one document the options name, and check its structure. -internal static class ConfigurationStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Loads the one document the options name, and runs every structural check on it. - /// The options the host filled. - /// - /// The loaded document, which has passed every check of section 8.5 except tool-reference - /// resolution, and every warning that check raised. Decision 15 runs tool-reference resolution - /// after discovery, in the composition root, against the ids the tool registry actually serves — - /// so an MCP-discovered id can satisfy a reference. - /// - /// The options name no document, or name two. - /// The document fails one of the structural checks. - /// - /// The structural checks report every defect at once, so one start names them all. - /// - internal static ConfigurationLoadResult Load(AgentCoreOptions options) - { - var configuration = LoadDocument(options); - var result = ConfigurationValidator.ValidateStructure(configuration); - return new ConfigurationLoadResult(configuration, result.Warnings); - } + /// What hands back: the document, and the warnings its validation carried. + /// The loaded document. See for what it has already passed. + /// + /// Every partial-coverage warning check 5 raises, and section 10's ambiguity warning (K33). no longer discards these — a caller logs + /// them once a logger exists. + /// + internal readonly record struct ConfigurationLoadResult( + AgentCoreConfiguration Configuration, IReadOnlyList Warnings); - /// Reads the one document the options name. - /// The options the host filled. - /// The loaded document. - /// The options name no document, or name two. - private static AgentCoreConfiguration LoadDocument(AgentCoreOptions options) + /// Steps 1 and 2: read the one document the options name, and check its structure. + internal static class ConfigurationStartup { - var hasPath = options.ConfigurationPath is { Length: > 0 }; - if (options.Configuration is { } loaded) + /// Loads the one document the options name, and runs every structural check on it. + /// The options the host filled. + /// + /// The loaded document, which has passed every check of section 8.5 except tool-reference + /// resolution, and every warning that check raised. Decision 15 runs tool-reference resolution + /// after discovery, in the composition root, against the ids the tool registry actually serves — + /// so an MCP-discovered id can satisfy a reference. + /// + /// The options name no document, or name two. + /// The document fails one of the structural checks. + /// + /// The structural checks report every defect at once, so one start names them all. + /// + internal static ConfigurationLoadResult Load(AgentCoreOptions options) { - if (hasPath) - { - throw new InvalidOperationException( - "AddAgentCoreAsync names two documents: options.Configuration holds one and " - + "options.ConfigurationPath names another. Set one of the two."); - } - - return loaded; + AgentCoreConfiguration configuration = LoadDocument(options); + ConfigurationValidationResult result = ConfigurationValidator.ValidateStructure(configuration); + return new ConfigurationLoadResult(configuration, result.Warnings); } - if (!hasPath) + /// Reads the one document the options name. + /// The options the host filled. + /// The loaded document. + /// The options name no document, or name two. + private static AgentCoreConfiguration LoadDocument(AgentCoreOptions options) { - throw new InvalidOperationException( - "AddAgentCoreAsync names no document. Set options.ConfigurationPath to a .yaml, .yml, or .json " - + "file, or set options.Configuration to a document the host already loaded."); + bool hasPath = options.ConfigurationPath is { Length: > 0 }; + return (options.Configuration, hasPath) switch + { + ({ } loaded, false) => loaded, + (null, true) => ConfigurationLoader.LoadFile(options.ConfigurationPath!), + ({ }, true) => throw new InvalidOperationException( + "AddAgentCoreAsync names two documents: options.Configuration holds one and " + + "options.ConfigurationPath names another. Set one of the two."), + (null, false) => throw new InvalidOperationException( + "AddAgentCoreAsync names no document. Set options.ConfigurationPath to a .yaml, .yml, or .json " + + "file, or set options.Configuration to a document the host already loaded."), + }; } - - return ConfigurationLoader.LoadFile(options.ConfigurationPath!); } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSeamStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSeamStartup.cs index 2639ed8f..3cdd393d 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSeamStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSeamStartup.cs @@ -6,111 +6,113 @@ using AgentCore.AspNetCore.Conversation; using Microsoft.AspNetCore.Http; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// What the conversation seam produced while the host started. -/// The transports registered. -/// -/// The vendors registered, selected by nothing. -/// providers.speech names the recognition vendor and the synthesis vendor, but no code in -/// this solution turns either name into a constructed adapter: the one transport shipped today -/// carries text, so it is itself both and there is nothing to build. The list goes in the container -/// beside the document so that a vendor which does need constructing has somewhere to be found. -/// -/// -/// What the MapCall route runs for every entry, or when this -/// document routes no inbound conversation — the host registered no transport, wrote no -/// providers.conversation block, or named a vendor this process dials out to, which has no inbound URL. -/// -/// -/// Why is , in the words a deployer can act on, or -/// when conversations route. -/// -internal readonly record struct ConversationSeamAdapters( - IReadOnlyList? Conversation, - IReadOnlyList? Speech, - RequestDelegate? Handler, - string? Unroutable); - -/// The two provider blocks a conversation arrives on: providers.conversation and providers.speech. -internal static class ConversationSeamStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Checks the two blocks agree, and hands back the vendor lists and the handler to register. - /// The loaded document. It carries both provider blocks. - /// The options the host filled. It carries the registered vendors. - /// The two lists and the handler, each one or when the host registered none. - internal static ConversationSeamAdapters Build( - AgentCoreConfiguration configuration, - AgentCoreOptions options) + /// What the conversation seam produced while the host started. + /// The transports registered. + /// + /// The vendors registered, selected by nothing. + /// providers.speech names the recognition vendor and the synthesis vendor, but no code in + /// this solution turns either name into a constructed adapter: the one transport shipped today + /// carries text, so it is itself both and there is nothing to build. The list goes in the container + /// beside the document so that a vendor which does need constructing has somewhere to be found. + /// + /// + /// What the MapCall route runs for every entry, or when this + /// document routes no inbound conversation — the host registered no transport, wrote no + /// providers.conversation block, or named a vendor this process dials out to, which has no inbound URL. + /// + /// + /// Why is , in the words a deployer can act on, or + /// when conversations route. + /// + internal readonly record struct ConversationSeamAdapters( + IReadOnlyList? Conversation, + IReadOnlyList? Speech, + RequestDelegate? Handler, + string? Unroutable); + + /// The two provider blocks a conversation arrives on: providers.conversation and providers.speech. + internal static class ConversationSeamStartup { - if (options.ConversationAdapters is not { } conversationAdapters) + /// Checks the two blocks agree, and hands back the vendor lists and the handler to register. + /// The loaded document. It carries both provider blocks. + /// The options the host filled. It carries the registered vendors. + /// The two lists and the handler, each one or when the host registered none. + internal static ConversationSeamAdapters Build( + AgentCoreConfiguration configuration, + AgentCoreOptions options) { - return new ConversationSeamAdapters( - null, options.Speech, null, "this host registered no conversation adapter"); - } + if (options.ConversationAdapters is not { } conversationAdapters) + { + return new ConversationSeamAdapters( + null, options.Speech, null, "this host registered no conversation adapter"); + } - // Registering a vendor is what turns this seam on. A host that registered none is not asked - // what its document says, exactly as telemetry, knowledge, and moderation are not read when - // a host registered no adapter for them. - var conversationEntry = configuration.Providers?.Conversation - ?? throw MissingConversationBlock(); + // Registering a vendor is what turns this seam on. A host that registered none is not asked + // what its document says, exactly as telemetry, knowledge, and moderation are not read when + // a host registered no adapter for them. + ConversationProviderConfiguration conversationEntry = configuration.Providers?.Conversation + ?? throw MissingConversationBlock(); - var selectedConversation = VendorAdapterSelector.Select( - conversationEntry.Kind, conversationAdapters, ConversationSeams.Conversation); + IConversationAdapter selectedConversation = VendorAdapterSelector.Select( + conversationEntry.Kind, conversationAdapters, ConversationSeams.Conversation); - var speechEntry = configuration.Providers?.Speech - ?? throw MissingSpeechBlock(); + SpeechProviderConfiguration speechEntry = configuration.Providers?.Speech + ?? throw MissingSpeechBlock(); - // Read here, and not only where the route is mapped. Agreement between two document entries - // is a document fact: it is true or false whether or not anything is routed, so a host that - // forgets app.MapCall() still learns its document contradicts itself. - ConversationSpeechPairing.Validate(conversationEntry, speechEntry, selectedConversation); + // Read here, and not only where the route is mapped. Agreement between two document entries + // is a document fact: it is true or false whether or not anything is routed, so a host that + // forgets app.MapCall() still learns its document contradicts itself. + ConversationSpeechPairing.Validate(conversationEntry, speechEntry, selectedConversation); - // Built here and not where the route is mapped, so an unusable limit in providers.conversation stops - // the host rather than the first conversation that arrives on it. A vendor this process dials out to - // has no inbound URL, and that is not a failure: it is the other half of the seam working. - if (selectedConversation is not IConversationTransportAdapter transport) - { - return new ConversationSeamAdapters( - conversationAdapters, - options.Speech, - null, - $"'{selectedConversation.Kind}' is a vendor this process dials out to, so it answers no inbound route"); + // Built here and not where the route is mapped, so an unusable limit in providers.conversation stops + // the host rather than the first conversation that arrives on it. A vendor this process dials out to + // has no inbound URL, and that is not a failure: it is the other half of the seam working. + return selectedConversation is not IConversationTransportAdapter transport + ? new ConversationSeamAdapters( + conversationAdapters, + options.Speech, + null, + $"'{selectedConversation.Kind}' is a vendor this process dials out to, so it answers no inbound route") + : new ConversationSeamAdapters(conversationAdapters, options.Speech, transport.CreateHandler(conversationEntry), null); } - return new ConversationSeamAdapters(conversationAdapters, options.Speech, transport.CreateHandler(conversationEntry), null); - } - - /// Refuses a configuration that turned the conversation seam on and named no transport. - /// The failure to throw, pointed at the block that is missing. - private static ConfigurationLoadException MissingConversationBlock() - => new(new ConfigurationError + /// Refuses a configuration that turned the conversation seam on and named no transport. + /// The failure to throw, pointed at the block that is missing. + private static ConfigurationLoadException MissingConversationBlock() { - Pointer = "/providers/conversation", - Message = - "This host registered a conversation transport with options.UseConversation(...), and this " - + "configuration writes no providers.conversation block for a kind to be picked from. A " - + "document that writes a providers section names both conversation and speech, because the " - + "schema requires them there; a document that writes no providers section at all is " - + "valid, and so is a configuration a host built in code, which passes through no " - + "schema. Write providers.conversation: { kind: ... }, or drop the options.UseConversation(...) call.", - Check = ConfigurationCheck.ReferenceResolution, - }); + return new(new ConfigurationError + { + Pointer = "/providers/conversation", + Message = + "This host registered a conversation transport with options.UseConversation(...), and this " + + "configuration writes no providers.conversation block for a kind to be picked from. A " + + "document that writes a providers section names both conversation and speech, because the " + + "schema requires them there; a document that writes no providers section at all is " + + "valid, and so is a configuration a host built in code, which passes through no " + + "schema. Write providers.conversation: { kind: ... }, or drop the options.UseConversation(...) call.", + Check = ConfigurationCheck.ReferenceResolution, + }); + } - /// Refuses a configuration whose conversation transport has no speech block to be paired with. - /// The failure to throw, pointed at the block that is missing. - private static ConfigurationLoadException MissingSpeechBlock() - => new(new ConfigurationError + /// Refuses a configuration whose conversation transport has no speech block to be paired with. + /// The failure to throw, pointed at the block that is missing. + private static ConfigurationLoadException MissingSpeechBlock() { - Pointer = "/providers/speech", - Message = - "This configuration names providers.conversation and no providers.speech, so there is " - + "nothing to check the transport against: a transport that carries text is itself " - + "the recognizer, and one that carries audio needs a speech vendor named. A " - + "document that writes a providers section names both, because the schema requires " - + "them there; a document that writes no providers section at all is valid, and so " - + "is a configuration a host built in code, which passes through no schema. Write " - + "providers.speech with both of its roles: stt: { kind: ... } and tts: { kind: ... }.", - Check = ConfigurationCheck.ReferenceResolution, - }); + return new(new ConfigurationError + { + Pointer = "/providers/speech", + Message = + "This configuration names providers.conversation and no providers.speech, so there is " + + "nothing to check the transport against: a transport that carries text is itself " + + "the recognizer, and one that carries audio needs a speech vendor named. A " + + "document that writes a providers section names both, because the schema requires " + + "them there; a document that writes no providers section at all is valid, and so " + + "is a configuration a host built in code, which passes through no schema. Write " + + "providers.speech with both of its roles: stt: { kind: ... } and tts: { kind: ... }.", + Check = ConfigurationCheck.ReferenceResolution, + }); + } + } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSessionStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSessionStartup.cs index 32318ed9..9930bb8b 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSessionStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationSessionStartup.cs @@ -7,91 +7,92 @@ using AgentCore.Application.Sessions.Memory; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// Everything the conversation seam opened: the audit chain, and one session factory per entry. -/// One factory, one agent, and one session store per entry, keyed by entry name. -/// The queue that answers the audit port, not the store behind it. -internal readonly record struct ConversationSessionSeam( - EntryRegistry Entries, QueuedAuditSink Queue); - -/// The seam a conversation arrives on: the audit queue, the observers, and one session factory per entry. -internal static class ConversationSessionStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Opens the audit store the document names and builds one session factory per entry over it. - /// The owner the audit chain is tracked against. - /// The loaded document. It carries providers.audit. - /// The options the host filled. It carries the audit vendors, the clock, and any observer. - /// The compiled entries and the seams step 5 made. - /// The factory the session and the audit queue take their loggers from. - /// Cancels the store open. - /// The per-entry seams, and the queue in front of the store. - internal static async ValueTask OpenAsync( - AgentCoreBoot boot, - AgentCoreConfiguration configuration, - AgentCoreOptions options, - CompiledGraph graph, - ILoggerFactory loggers, - CancellationToken cancellationToken) - { - IAuditSinkPort store = boot.Track(await AuditSinkFactory - .OpenAsync( - configuration, - options.SecretResolver, - options.AuditSinks ?? [], - cancellationToken) - .ConfigureAwait(false)); + /// Everything the conversation seam opened: the audit chain, and one session factory per entry. + /// One factory, one agent, and one session store per entry, keyed by entry name. + /// The queue that answers the audit port, not the store behind it. + internal readonly record struct ConversationSessionSeam( + EntryRegistry Entries, QueuedAuditSink Queue); - if (store is InMemoryAuditSink && configuration.Providers?.Audit is null) + /// The seam a conversation arrives on: the audit queue, the observers, and one session factory per entry. + internal static class ConversationSessionStartup + { + /// Opens the audit store the document names and builds one session factory per entry over it. + /// The owner the audit chain is tracked against. + /// The loaded document. It carries providers.audit. + /// The options the host filled. It carries the audit vendors, the clock, and any observer. + /// The compiled entries and the seams step 5 made. + /// The factory the session and the audit queue take their loggers from. + /// Cancels the store open. + /// The per-entry seams, and the queue in front of the store. + internal static async ValueTask OpenAsync( + AgentCoreBoot boot, + AgentCoreConfiguration configuration, + AgentCoreOptions options, + CompiledGraph graph, + ILoggerFactory loggers, + CancellationToken cancellationToken) { - StartupLog.AuditSinkDefaulted(loggers.CreateLogger()); - } + IAuditSinkPort store = boot.Track(await AuditSinkFactory + .OpenAsync( + configuration, + options.SecretResolver, + options.AuditSinks ?? [], + cancellationToken) + .ConfigureAwait(false)); - QueuedAuditSink auditSink = boot.Track(new QueuedAuditSink(store, loggers.CreateLogger())); - - var sessionLogger = loggers.CreateLogger(); - - if (options.WorkspaceRoot is { } root) - { - try + if (store is InMemoryAuditSink && configuration.Providers?.Audit is null) { - Directory.CreateDirectory(root); + StartupLog.AuditSinkDefaulted(loggers.CreateLogger()); } - catch (Exception exception) when (exception is not OperationCanceledException) + + QueuedAuditSink auditSink = boot.Track(new QueuedAuditSink(store, loggers.CreateLogger())); + + ILogger sessionLogger = loggers.CreateLogger(); + + if (options.WorkspaceRoot is { } root) { - throw new ConfigurationLoadException( - $"The configuration document did not load. The workspace root '{root}' could not be " - + $"created: {exception.Message} Check the path passed to options.UseWorkspace(...), " - + "and that the process has permission to create it.", - exception); + try + { + _ = Directory.CreateDirectory(root); + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + throw new ConfigurationLoadException( + $"The configuration document did not load. The workspace root '{root}' could not be " + + $"created: {exception.Message} Check the path passed to options.UseWorkspace(...), " + + "and that the process has permission to create it.", + exception); + } } - } - var observers = ConversationObservers.Standard(auditSink, sessionLogger, options.Observers); - var timeProvider = options.TimeProvider ?? TimeProvider.System; + IReadOnlyList observers = ConversationObservers.Standard(auditSink, sessionLogger, options.Observers); + TimeProvider timeProvider = options.TimeProvider ?? TimeProvider.System; - Dictionary factories = new(StringComparer.Ordinal); - Dictionary agents = new(StringComparer.Ordinal); - Dictionary sessions = new(StringComparer.Ordinal); + Dictionary factories = new(StringComparer.Ordinal); + Dictionary agents = new(StringComparer.Ordinal); + Dictionary sessions = new(StringComparer.Ordinal); - foreach (var (entryName, compiled) in graph.Entries) - { - ConversationSessionFactory factory = new( - compiled, - graph.Guards, - ConversationSessionFactory.CreateExtractor(compiled, graph.ChatClients), - options.TimeProvider, - sessionLogger, - observers, - options.WorkspaceRoot); + foreach ((string? entryName, Application.Configuration.Compilation.CompiledAgent? compiled) in graph.Entries) + { + ConversationSessionFactory factory = new( + compiled, + graph.Guards, + ConversationSessionFactory.CreateExtractor(compiled, graph.ChatClients), + options.TimeProvider, + sessionLogger, + observers, + options.WorkspaceRoot); - factories[entryName] = factory; - agents[entryName] = new AgentCoreAgent(factory, entryName); - sessions[entryName] = options.ConversationSessions?.Invoke(entryName, factory) - ?? new InMemoryConversationSessions( - factory, InMemoryConversationSessions.DefaultIdleTimeout, timeProvider); - } + factories[entryName] = factory; + agents[entryName] = new AgentCoreAgent(factory, entryName); + sessions[entryName] = options.ConversationSessions?.Invoke(entryName, factory) + ?? new InMemoryConversationSessions( + factory, InMemoryConversationSessions.DefaultIdleTimeout, timeProvider); + } - return new ConversationSessionSeam(new EntryRegistry(factories, agents, sessions), auditSink); + return new ConversationSessionSeam(new EntryRegistry(factories, agents, sessions), auditSink); + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationStartup.cs index b6f3d2a9..072f4738 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConversationStartup.cs @@ -4,36 +4,37 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// Step 4c: open the store 0 backing the document names, before the document is compiled. -internal static class ConversationStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Opens the store providers.conversations names, or the built-in one. - /// The loaded document. It carries providers.conversations. - /// The options the host filled. It carries the conversation store vendors. - /// The factory the defaulting warning is written through. - /// Cancels the store open. - /// The store, which is never . - internal static async ValueTask OpenAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - ILoggerFactory loggers, - CancellationToken cancellationToken) + /// Step 4c: open the store 0 backing the document names, before the document is compiled. + internal static class ConversationStartup { - IConversationStore store = await ConversationStoreFactory - .OpenAsync( - configuration, - options.SecretResolver, - options.ConversationStores ?? [], - cancellationToken) - .ConfigureAwait(false); - - if (store is InMemoryConversationStore && configuration.Providers?.Conversations is null) + /// Opens the store providers.conversations names, or the built-in one. + /// The loaded document. It carries providers.conversations. + /// The options the host filled. It carries the conversation store vendors. + /// The factory the defaulting warning is written through. + /// Cancels the store open. + /// The store, which is never . + internal static async ValueTask OpenAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + ILoggerFactory loggers, + CancellationToken cancellationToken) { - StartupLog.ConversationStoreDefaulted(loggers.CreateLogger()); - } + IConversationStore store = await ConversationStoreFactory + .OpenAsync( + configuration, + options.SecretResolver, + options.ConversationStores ?? [], + cancellationToken) + .ConfigureAwait(false); - return store; + if (store is InMemoryConversationStore && configuration.Providers?.Conversations is null) + { + StartupLog.ConversationStoreDefaulted(loggers.CreateLogger()); + } + + return store; + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/EmbeddingStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/EmbeddingStartup.cs index 953dc01a..535be206 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/EmbeddingStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/EmbeddingStartup.cs @@ -2,31 +2,32 @@ using AgentCore.Application.Embeddings; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Step 3a: build the embedding generator the document names, before knowledge opens. -internal static class EmbeddingStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Builds the generator the document names. - /// The loaded document. It carries providers.embeddings. - /// The options the host filled. It carries the registered vendors. - /// Cancels the adapter build. - internal static async ValueTask>?> OpenAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - CancellationToken cancellationToken) + /// Step 3a: build the embedding generator the document names, before knowledge opens. + internal static class EmbeddingStartup { - if (options.Embeddings is not { } adapters) + /// Builds the generator the document names. + /// The loaded document. It carries providers.embeddings. + /// The options the host filled. It carries the registered vendors. + /// Cancels the adapter build. + internal static async ValueTask>?> OpenAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + CancellationToken cancellationToken) { - return null; - } + if (options.Embeddings is not { } adapters) + { + return null; + } - var generator = await CompositeEmbeddingGeneratorFactory - .CreateAsync(configuration, options.SecretResolver, adapters, cancellationToken) - .ConfigureAwait(false); + IEmbeddingGenerator>? generator = await CompositeEmbeddingGeneratorFactory + .CreateAsync(configuration, options.SecretResolver, adapters, cancellationToken) + .ConfigureAwait(false); - return generator is null || options.Cache is not { } cache - ? generator - : new HybridCachingEmbeddingGenerator(generator, cache); + return generator is null || options.Cache is not { } cache + ? generator + : new HybridCachingEmbeddingGenerator(generator, cache); + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/EntryRegistry.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/EntryRegistry.cs index 8edb9ec3..2e1869af 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/EntryRegistry.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/EntryRegistry.cs @@ -1,83 +1,87 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// One factory, one agent shim, and one session store per entry. -/// -/// Each entry compiles its own shape over the shared pool, so each entry gets its own -/// session factory and its own store: a vendor call id arriving on two routes opens two -/// isolated conversations rather than one conversation read through two shapes. The audit chain, the -/// observers, and the workspace root are shared across entries, because they describe the -/// deployment rather than the shape. Agents are named by entry key. -/// -internal sealed class EntryRegistry : IConversationSessionRegistry +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Creates the registry over the per-entry seams. - /// The session factories, keyed by entry name. - /// The agent shims, keyed by entry name. - /// The session stores, keyed by entry name. - public EntryRegistry( - IReadOnlyDictionary factories, - IReadOnlyDictionary agents, - IReadOnlyDictionary conversationSessions) + /// One factory, one agent shim, and one session store per entry. + /// + /// Each entry compiles its own shape over the shared pool, so each entry gets its own + /// session factory and its own store: a vendor call id arriving on two routes opens two + /// isolated conversations rather than one conversation read through two shapes. The audit chain, the + /// observers, and the workspace root are shared across entries, because they describe the + /// deployment rather than the shape. Agents are named by entry key. + /// + internal sealed class EntryRegistry : IConversationSessionRegistry { - ArgumentNullException.ThrowIfNull(factories); - ArgumentNullException.ThrowIfNull(agents); - ArgumentNullException.ThrowIfNull(conversationSessions); - - Factories = factories; - Agents = agents; - ConversationSessions = conversationSessions; - Entries = conversationSessions.Keys.ToArray(); - } - - /// Gets the session factories, keyed by entry name. - public IReadOnlyDictionary Factories { get; } + /// Creates the registry over the per-entry seams. + /// The session factories, keyed by entry name. + /// The agent shims, keyed by entry name. + /// The session stores, keyed by entry name. + public EntryRegistry( + IReadOnlyDictionary factories, + IReadOnlyDictionary agents, + IReadOnlyDictionary conversationSessions) + { + ArgumentNullException.ThrowIfNull(factories); + ArgumentNullException.ThrowIfNull(agents); + ArgumentNullException.ThrowIfNull(conversationSessions); - /// Gets the agent shims, keyed by entry name. - public IReadOnlyDictionary Agents { get; } + Factories = factories; + Agents = agents; + ConversationSessions = conversationSessions; + Entries = [.. conversationSessions.Keys]; + } - /// Gets the session stores, keyed by entry name. - public IReadOnlyDictionary ConversationSessions { get; } + /// Gets the session factories, keyed by entry name. + public IReadOnlyDictionary Factories { get; } - /// - public IReadOnlyCollection Entries { get; } + /// Gets the agent shims, keyed by entry name. + public IReadOnlyDictionary Agents { get; } - /// Reads one entry's factory. - /// The entry key a route named. - /// The factory for that entry. - /// The entry is not declared. - public IConversationSessionFactory ForFactory(string entry) - => For(Factories, entry); + /// Gets the session stores, keyed by entry name. + public IReadOnlyDictionary ConversationSessions { get; } - /// Reads one entry's agent shim. - /// The entry key a route named. - /// The agent for that entry. - /// The entry is not declared. - public AgentCoreAgent ForAgent(string entry) - => For(Agents, entry); + /// + public IReadOnlyCollection Entries { get; } - /// - public IConversationSessions ForSessions(string entry) - => For(ConversationSessions, entry); + /// Reads one entry's factory. + /// The entry key a route named. + /// The factory for that entry. + /// The entry is not declared. + public IConversationSessionFactory ForFactory(string entry) + { + return For(Factories, entry); + } - /// Builds the failure text for an entry nothing declares, in one place. - /// The entry key a route named. - /// The declared entry names. - /// The message both the startup check and the per-request backstop carry. - internal static string UnknownEntryMessage(string entry, IEnumerable valid) - => $"The entry '{entry}' is not declared. Valid entries: {string.Join(", ", valid)}."; + /// Reads one entry's agent shim. + /// The entry key a route named. + /// The agent for that entry. + /// The entry is not declared. + public AgentCoreAgent ForAgent(string entry) + { + return For(Agents, entry); + } - private static T For(IReadOnlyDictionary map, string entry) - { - ArgumentException.ThrowIfNullOrEmpty(entry); + /// + public IConversationSessions ForSessions(string entry) + { + return For(ConversationSessions, entry); + } - if (map.TryGetValue(entry, out var value)) + /// Builds the failure text for an entry nothing declares, in one place. + /// The entry key a route named. + /// The declared entry names. + /// The message both the startup check and the per-request backstop carry. + internal static string UnknownEntryMessage(string entry, IEnumerable valid) { - return value; + return $"The entry '{entry}' is not declared. Valid entries: {string.Join(", ", valid)}."; } - throw new InvalidOperationException(UnknownEntryMessage(entry, map.Keys)); + private static T For(IReadOnlyDictionary map, string entry) + { + ArgumentException.ThrowIfNullOrEmpty(entry); + + return map.TryGetValue(entry, out T? value) ? value : throw new InvalidOperationException(UnknownEntryMessage(entry, map.Keys)); + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/EvaluationStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/EvaluationStartup.cs index fdda7951..c1a971c6 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/EvaluationStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/EvaluationStartup.cs @@ -1,32 +1,33 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Evaluation; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// The evaluation seam of D13: the registry the turn loop reads, and the sampled judge. -internal static class EvaluationStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Builds the registry, with the built-in evaluator and any moderation vendor. - /// The loaded document. It carries providers.moderation. - /// The options the host filled. It carries the registered vendors. - /// Cancels the adapter build. - /// The registry, ready for the turn loop and for the offline golden set alike. - internal static async ValueTask CreateRegistryAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - CancellationToken cancellationToken) + /// The evaluation seam of D13: the registry the turn loop reads, and the sampled judge. + internal static class EvaluationStartup { - EvaluatorRegistry evaluators = new(); - evaluators.Register("fault_code", new FaultCodeEvaluator()); - - if (options.Moderation is { } moderationAdapters - && await ModerationEvaluatorFactory - .CreateAsync(configuration, options.SecretResolver, moderationAdapters, cancellationToken) - .ConfigureAwait(false) is { } moderation) + /// Builds the registry, with the built-in evaluator and any moderation vendor. + /// The loaded document. It carries providers.moderation. + /// The options the host filled. It carries the registered vendors. + /// Cancels the adapter build. + /// The registry, ready for the turn loop and for the offline golden set alike. + internal static async ValueTask CreateRegistryAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + CancellationToken cancellationToken) { - evaluators.Register(PromptModerator.ModerationEvaluatorName, moderation); - } + EvaluatorRegistry evaluators = new(); + _ = evaluators.Register("fault_code", new FaultCodeEvaluator()); - return evaluators; + if (options.Moderation is { } moderationAdapters + && await ModerationEvaluatorFactory + .CreateAsync(configuration, options.SecretResolver, moderationAdapters, cancellationToken) + .ConfigureAwait(false) is { } moderation) + { + _ = evaluators.Register(PromptModerator.ModerationEvaluatorName, moderation); + } + + return evaluators; + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index 509f8d19..29173c8c 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs @@ -4,74 +4,77 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Step 3b: open the knowledge base the document names, before any tool is built. -internal static class KnowledgeStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Opens the knowledge port the document names. - /// The loaded document. It carries providers.knowledge. - /// The options the host filled. It carries the registered vendors and any explicit seam. - /// The loaded document and the resolved secrets. - /// - /// The generator providers.embeddings built, or when the document - /// names none. Handed to the matched adapter, which fails the start by name when it ranks by - /// vector and received none. - /// - /// Whether ANY agent in the document declares knowledge: { scoped: true }. - /// - /// Whether EVERY agent in the document declares knowledge: { scoped: true }. See - /// for why this is a different question - /// from . - /// - /// Cancels the adapter build. - /// The port, open, or . - internal static async ValueTask OpenAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - AgentCoreStartup startup, - IEmbeddingGenerator>? embeddings, - bool scopeDeclared, - bool requireScope, - CancellationToken cancellationToken) + /// Step 3b: open the knowledge base the document names, before any tool is built. + internal static class KnowledgeStartup { - var port = await OpenStoreAsync( - configuration, options, startup, embeddings, scopeDeclared, requireScope, cancellationToken) - .ConfigureAwait(false); + /// Opens the knowledge port the document names. + /// The loaded document. It carries providers.knowledge. + /// The options the host filled. It carries the registered vendors and any explicit seam. + /// The loaded document and the resolved secrets. + /// + /// The generator providers.embeddings built, or when the document + /// names none. Handed to the matched adapter, which fails the start by name when it ranks by + /// vector and received none. + /// + /// Whether ANY agent in the document declares knowledge: { scoped: true }. + /// + /// Whether EVERY agent in the document declares knowledge: { scoped: true }. See + /// for why this is a different question + /// from . + /// + /// Cancels the adapter build. + /// The port, open, or . + internal static async ValueTask OpenAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + AgentCoreStartup startup, + IEmbeddingGenerator>? embeddings, + bool scopeDeclared, + bool requireScope, + CancellationToken cancellationToken) + { + IKnowledgeRetrievalPort? port = await OpenStoreAsync( + configuration, options, startup, embeddings, scopeDeclared, requireScope, cancellationToken) + .ConfigureAwait(false); - return port is null || options.Cache is not { } cache - ? port - : new HybridCachingKnowledgeRetrievalPort(port, cache); - } + return port is null || options.Cache is not { } cache + ? port + : new HybridCachingKnowledgeRetrievalPort(port, cache); + } - private static ValueTask OpenStoreAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - AgentCoreStartup startup, - IEmbeddingGenerator>? embeddings, - bool scopeDeclared, - bool requireScope, - CancellationToken cancellationToken) - { - if (options.KnowledgeRetrieval is { } retrieval) + private static ValueTask OpenStoreAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + AgentCoreStartup startup, + IEmbeddingGenerator>? embeddings, + bool scopeDeclared, + bool requireScope, + CancellationToken cancellationToken) { - return ValueTask.FromResult(retrieval(startup)); + if (options.KnowledgeRetrieval is { } retrieval) + { + return ValueTask.FromResult(retrieval(startup)); + } + + if (configuration.Providers?.Knowledge is null && !AnyAgentDeclares(configuration)) + { + return ValueTask.FromResult(null); + } + + return options.KnowledgeStores is { } stores + ? CompositeKnowledgeStoreFactory.CreateAsync( + configuration, options.SecretResolver, stores, embeddings, scopeDeclared, requireScope, cancellationToken) + : ValueTask.FromResult(null); } - if (configuration.Providers?.Knowledge is null && !AnyAgentDeclares(configuration)) + /// Whether any agent's knowledge: block composes. + /// The loaded document. + /// when at least one agent reads the knowledge base. + private static bool AnyAgentDeclares(AgentCoreConfiguration configuration) { - return ValueTask.FromResult(null); + return configuration.Agents is { } agents && AgentKnowledge.AnyDeclared(agents); } - - return options.KnowledgeStores is { } stores - ? CompositeKnowledgeStoreFactory.CreateAsync( - configuration, options.SecretResolver, stores, embeddings, scopeDeclared, requireScope, cancellationToken) - : ValueTask.FromResult(null); } - - /// Whether any agent's knowledge: block composes. - /// The loaded document. - /// when at least one agent reads the knowledge base. - private static bool AnyAgentDeclares(AgentCoreConfiguration configuration) - => configuration.Agents is { } agents && AgentKnowledge.AnyDeclared(agents); } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/SecretsStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/SecretsStartup.cs index ca014715..1cb95b06 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/SecretsStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/SecretsStartup.cs @@ -2,39 +2,44 @@ using AgentCore.Application.Ports; using AgentCore.Application.Secrets; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Step 3: resolve every ${secret:name} once, while the host starts. -internal static class SecretsStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Resolves every secret the document references. - /// The loaded document. - /// The options the host filled. It carries the resolver chain. - /// Cancels the secret reads. - /// Every value the document needs, read exactly once. - /// One ${secret:name} reference resolves to nothing. - /// - /// A tool call then costs no lookup, and a missing credential stops the host rather than one turn. - /// - internal static ValueTask ResolveAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - CancellationToken cancellationToken) - => ResolvedSecrets.ResolveAsync( - configuration, - options.SecretResolver ?? NoSecretResolver.Instance, - cancellationToken); - - /// The chain a host that bound none gets: it holds no name at all. - /// - /// A document that references no secret resolves cleanly against this. A document that references - /// one fails, and the failure names the reference and its JSON Pointer. - /// - private sealed class NoSecretResolver : ISecretResolverPort + /// Step 3: resolve every ${secret:name} once, while the host starts. + internal static class SecretsStartup { - public static NoSecretResolver Instance { get; } = new(); + /// Resolves every secret the document references. + /// The loaded document. + /// The options the host filled. It carries the resolver chain. + /// Cancels the secret reads. + /// Every value the document needs, read exactly once. + /// One ${secret:name} reference resolves to nothing. + /// + /// A tool call then costs no lookup, and a missing credential stops the host rather than one turn. + /// + internal static ValueTask ResolveAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + CancellationToken cancellationToken) + { + return ResolvedSecrets.ResolveAsync( + configuration, + options.SecretResolver ?? NoSecretResolver.Instance, + cancellationToken); + } + + /// The chain a host that bound none gets: it holds no name at all. + /// + /// A document that references no secret resolves cleanly against this. A document that references + /// one fails, and the failure names the reference and its JSON Pointer. + /// + private sealed class NoSecretResolver : ISecretResolverPort + { + public static NoSecretResolver Instance { get; } = new(); - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - => ValueTask.FromResult(null); + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(null); + } + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/SkillsStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/SkillsStartup.cs index 9d77ecce..79a3f0f9 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/SkillsStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/SkillsStartup.cs @@ -4,233 +4,242 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// Opens the skills folder the host bound, before the document is compiled. -internal static class SkillsStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// MAF's own cap. It is a const on AgentFileSkillsSource, not a settable option. - private const int MaximumDepth = 2; - - /// Builds the catalog the compile table reads. - /// The host's options. They carry the folder or the source. - /// Where the source writes its diagnostics. - /// Cancels the enumeration. - /// The catalog, or when the host bound nothing. - /// The folder is unusable. - internal static async ValueTask OpenAsync( - AgentCoreOptions options, - ILoggerFactory loggers, - CancellationToken cancellationToken) + /// Opens the skills folder the host bound, before the document is compiled. + internal static class SkillsStartup { - ArgumentNullException.ThrowIfNull(options); - ArgumentNullException.ThrowIfNull(loggers); - - AgentSkillsSource source; - string? path = null; - - if (options.SkillsSource is { } bound) - { - source = bound; - } - else if (options.SkillsPath is { } folder) + /// MAF's own cap. It is a const on AgentFileSkillsSource, not a settable option. + private const int MaximumDepth = 2; + + /// Builds the catalog the compile table reads. + /// The host's options. They carry the folder or the source. + /// Where the source writes its diagnostics. + /// Cancels the enumeration. + /// The catalog, or when the host bound nothing. + /// The folder is unusable. + internal static async ValueTask OpenAsync( + AgentCoreOptions options, + ILoggerFactory loggers, + CancellationToken cancellationToken) { - path = folder; + ArgumentNullException.ThrowIfNull(options); + ArgumentNullException.ThrowIfNull(loggers); - if (!Directory.Exists(path)) + AgentSkillsSource source; + string? path = null; + + if (options.SkillsSource is { } bound) + { + source = bound; + } + else if (options.SkillsPath is { } folder) { - throw Fail(File.Exists(path) - ? $"the skills path '{path}' is a file, not a folder, so no skill can load. " - + "Pass options.UseSkills(...) the folder that holds the skill directories." - : $"the skills folder '{path}' does not exist, so no skill can load. " - + "Check the path passed to options.UseSkills(...), and that the folder ships with the app."); + path = folder; + + if (!Directory.Exists(path)) + { + throw Fail(File.Exists(path) + ? $"the skills path '{path}' is a file, not a folder, so no skill can load. " + + "Pass options.UseSkills(...) the folder that holds the skill directories." + : $"the skills folder '{path}' does not exist, so no skill can load. " + + "Check the path passed to options.UseSkills(...), and that the folder ships with the app."); + } + + // Scripts are refused at three layers, and this is the one the model cannot see past: without + // it, load_skill's own result advertises every script file with its parameter schema. + AgentFileSkillsSourceOptions fileOptions = new() { ScriptFilter = _ => false }; + source = new CachingAgentSkillsSource(new AgentFileSkillsSource(path, null, fileOptions, loggers)); + } + else + { + return null; } - // Scripts are refused at three layers, and this is the one the model cannot see past: without - // it, load_skill's own result advertises every script file with its parameter schema. - AgentFileSkillsSourceOptions fileOptions = new() { ScriptFilter = _ => false }; - source = new CachingAgentSkillsSource(new AgentFileSkillsSource(path, null, fileOptions, loggers)); - } - else - { - return null; + try + { + return new SkillCatalog(source, await NamesAsync(source, path, cancellationToken).ConfigureAwait(false)); + } + catch + { + // AgentCoreBoot takes ownership of what this returns, so a check inside NamesAsync that + // throws leaves nothing else holding the source — a host's own included, since + // UseSkills(AgentSkillsSource) took ownership of that one. + source.Dispose(); + throw; + } } - try + /// Enumerates once, then runs every check the framework does not. + /// The source to enumerate. + /// The bound folder, or when the host bound a source. + /// Cancels the enumeration. + /// Every name the source serves. + /// The folder is unusable. + private static async ValueTask> NamesAsync( + AgentSkillsSource source, + string? path, + CancellationToken cancellationToken) { - return new SkillCatalog(source, await NamesAsync(source, path, cancellationToken).ConfigureAwait(false)); - } - catch - { - // AgentCoreBoot takes ownership of what this returns, so a check inside NamesAsync that - // throws leaves nothing else holding the source — a host's own included, since - // UseSkills(AgentSkillsSource) took ownership of that one. - source.Dispose(); - throw; - } - } + IList skills; + List candidates = []; - /// Enumerates once, then runs every check the framework does not. - /// The source to enumerate. - /// The bound folder, or when the host bound a source. - /// Cancels the enumeration. - /// Every name the source serves. - /// The folder is unusable. - private static async ValueTask> NamesAsync( - AgentSkillsSource source, - string? path, - CancellationToken cancellationToken) - { - IList skills; - List candidates = []; + try + { + using ProbeChatClient client = new(); + ChatClientAgent probe = new(client, new ChatClientAgentOptions { Name = "skills-probe" }); - try - { - using ProbeChatClient client = new(); - ChatClientAgent probe = new(client, new ChatClientAgentOptions { Name = "skills-probe" }); + skills = await source + .GetSkillsAsync(new AgentSkillsSourceContext(probe, null), cancellationToken) + .ConfigureAwait(false); - skills = await source - .GetSkillsAsync(new AgentSkillsSourceContext(probe, null), cancellationToken) - .ConfigureAwait(false); + if (path is not null) + { + Walk(path, 0, candidates); + } + } + catch (UnauthorizedAccessException exception) + { + throw Fail( + path is null + ? $"the skills source bound by options.UseSkills(...) could not be read: {exception.Message} " + + "Grant the process access to whatever that source reads." + : $"the skills folder '{path}' could not be read: {exception.Message} " + + "Grant the process read access to the folder and to every skill directory under it.", + exception); + } + // This check runs first on purpose. A folder whose only skill is dropped enumerates to zero, + // so a "serves no skill" test placed above would win and hide the directory that is actually + // at fault — which is the whole reason for reproducing the framework's walk. if (path is not null) { - Walk(path, 0, candidates); + HashSet loaded = skills + .OfType() + .Select(skill => Path.GetFullPath(skill.Path)) + .ToHashSet(StringComparer.Ordinal); + + List dropped = [.. candidates.Where(candidate => !loaded.Contains(candidate))]; + if (dropped.Count > 0) + { + throw Fail($"these directories hold a SKILL.md that did not load: {string.Join(", ", dropped.Select(directory => $"'{directory}'"))}. " + + "The usual causes are a frontmatter name: that differs from the directory name, " + + "or a directory name outside the skill charset of lower-case letters, digits and " + + "single hyphens. The framework logs the reason at Error level."); + } } - } - catch (UnauthorizedAccessException exception) - { - throw Fail( - path is null - ? $"the skills source bound by options.UseSkills(...) could not be read: {exception.Message} " - + "Grant the process access to whatever that source reads." - : $"the skills folder '{path}' could not be read: {exception.Message} " - + "Grant the process read access to the folder and to every skill directory under it.", - exception); - } - // This check runs first on purpose. A folder whose only skill is dropped enumerates to zero, - // so a "serves no skill" test placed above would win and hide the directory that is actually - // at fault — which is the whole reason for reproducing the framework's walk. - if (path is not null) - { - var loaded = skills - .OfType() - .Select(skill => Path.GetFullPath(skill.Path)) - .ToHashSet(StringComparer.Ordinal); + if (skills.Count == 0) + { + throw Fail(path is null + ? "the skills source bound by options.UseSkills(...) serves no skill." + : $"the skills folder '{path}' serves no skill. Each skill is a directory holding a " + + "SKILL.md, one or two levels below the folder."); + } + + List> duplicates = [.. skills + .GroupBy(skill => skill.Frontmatter.Name, StringComparer.Ordinal) + .Where(group => group.Count() > 1)]; - var dropped = candidates.Where(candidate => !loaded.Contains(candidate)).ToList(); - if (dropped.Count > 0) + if (duplicates.Count > 0) { - throw Fail($"these directories hold a SKILL.md that did not load: {string.Join(", ", dropped.Select(directory => $"'{directory}'"))}. " - + "The usual causes are a frontmatter name: that differs from the directory name, " - + "or a directory name outside the skill charset of lower-case letters, digits and " - + "single hyphens. The framework logs the reason at Error level."); + string detail = string.Join("; ", duplicates.Select(Describe)); + + throw Fail(path is null + ? $"the skills source bound by options.UseSkills(...) serves one name more than once: {detail}. " + + "Which copy loads is decided by the order the source returned them, so the answer can " + + "change between runs. Serve each name once." + : $"the skills folder serves one name from more than one directory: {detail}. " + + "Which one loads is decided by the order the folder was written to disk, so two " + + "deploys of one commit can differ. Rename one."); } - } - if (skills.Count == 0) - { - throw Fail(path is null - ? "the skills source bound by options.UseSkills(...) serves no skill." - : $"the skills folder '{path}' serves no skill. Each skill is a directory holding a " - + "SKILL.md, one or two levels below the folder."); + return skills.Select(skill => skill.Frontmatter.Name).ToHashSet(StringComparer.Ordinal); } - var duplicates = skills - .GroupBy(skill => skill.Frontmatter.Name, StringComparer.Ordinal) - .Where(group => group.Count() > 1) - .ToList(); - - if (duplicates.Count > 0) + /// Names the copies of one duplicated skill name. + /// Every skill the source served under that name. + /// The clause naming the name and its copies. + private static string Describe(IGrouping group) { - var detail = string.Join("; ", duplicates.Select(Describe)); - - throw Fail(path is null - ? $"the skills source bound by options.UseSkills(...) serves one name more than once: {detail}. " - + "Which copy loads is decided by the order the source returned them, so the answer can " - + "change between runs. Serve each name once." - : $"the skills folder serves one name from more than one directory: {detail}. " - + "Which one loads is decided by the order the folder was written to disk, so two " - + "deploys of one commit can differ. Rename one."); - } + // A source the host bound need serve no file skill at all, and a skill with no path leaves + // nothing to point at but how many copies there are and what they are. + if (!group.All(skill => skill is AgentFileSkill)) + { + IOrderedEnumerable types = group + .Select(skill => skill.GetType().Name) + .Distinct(StringComparer.Ordinal) + .Order(StringComparer.Ordinal); - return skills.Select(skill => skill.Frontmatter.Name).ToHashSet(StringComparer.Ordinal); - } + return $"'{group.Key}' is served by {group.Count()} skills, of type {string.Join(" and ", types)}"; + } - /// Names the copies of one duplicated skill name. - /// Every skill the source served under that name. - /// The clause naming the name and its copies. - private static string Describe(IGrouping group) - { - // A source the host bound need serve no file skill at all, and a skill with no path leaves - // nothing to point at but how many copies there are and what they are. - if (!group.All(skill => skill is AgentFileSkill)) - { - var types = group - .Select(skill => skill.GetType().Name) - .Distinct(StringComparer.Ordinal) - .Order(StringComparer.Ordinal); + IEnumerable paths = group.Cast().Select(skill => $"'{skill.Path}'"); - return $"'{group.Key}' is served by {group.Count()} skills, of type {string.Join(" and ", types)}"; + return $"'{group.Key}' is served by {string.Join(" and ", paths)}"; } - var paths = group.Cast().Select(skill => $"'{skill.Path}'"); + /// + /// Reproduces the framework's own discovery walk. It is not a glob: a directory holding a + /// SKILL.md is never descended into, and the bound folder itself is a candidate, so a + /// */SKILL.md pattern would report a legal nested layout as a dropped skill. + /// + /// The directory to test. + /// How far below the bound folder this directory sits. + /// The list every candidate directory is added to. + private static void Walk(string directory, int depth, List candidates) + { + if (File.Exists(Path.Combine(directory, "SKILL.md"))) + { + candidates.Add(Path.GetFullPath(directory)); + return; + } - return $"'{group.Key}' is served by {string.Join(" and ", paths)}"; - } + if (depth >= MaximumDepth) + { + return; + } - /// - /// Reproduces the framework's own discovery walk. It is not a glob: a directory holding a - /// SKILL.md is never descended into, and the bound folder itself is a candidate, so a - /// */SKILL.md pattern would report a legal nested layout as a dropped skill. - /// - /// The directory to test. - /// How far below the bound folder this directory sits. - /// The list every candidate directory is added to. - private static void Walk(string directory, int depth, List candidates) - { - if (File.Exists(Path.Combine(directory, "SKILL.md"))) - { - candidates.Add(Path.GetFullPath(directory)); - return; + foreach (string child in Directory.EnumerateDirectories(directory)) + { + Walk(child, depth + 1, candidates); + } } - if (depth >= MaximumDepth) + /// Builds the one exception a load failure uses. + /// What went wrong, and what to do next. + /// The cause, when one exists. + /// The exception to throw. + private static ConfigurationLoadException Fail(string message, Exception? innerException = null) { - return; + return new("The configuration document did not load. " + message, innerException); } - foreach (var child in Directory.EnumerateDirectories(directory)) + /// + /// The framework's enumeration context refuses a null agent, and an agent needs a chat client. + /// Nothing calls the model during enumeration, so both response methods throw rather than + /// answer. + /// + private sealed class ProbeChatClient : IChatClient { - Walk(child, depth + 1, candidates); - } - } - - /// Builds the one exception a load failure uses. - /// What went wrong, and what to do next. - /// The cause, when one exists. - /// The exception to throw. - private static ConfigurationLoadException Fail(string message, Exception? innerException = null) - => new("The configuration document did not load. " + message, innerException); - - /// - /// The framework's enumeration context refuses a null agent, and an agent needs a chat client. - /// Nothing calls the model during enumeration, so both response methods throw rather than - /// answer. - /// - private sealed class ProbeChatClient : IChatClient - { - public Task GetResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public Task GetResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - public IAsyncEnumerable GetStreamingResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public IAsyncEnumerable GetStreamingResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - public void Dispose() - { + public void Dispose() + { + } } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/TelemetryStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/TelemetryStartup.cs index 09aae8c5..ef393d29 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/TelemetryStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/TelemetryStartup.cs @@ -3,34 +3,35 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// Step 2b: start the telemetry export, before anything below writes a line worth keeping. -internal static class TelemetryStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Starts the export the document names, and attaches its log provider. - /// The loaded document. It carries providers.telemetry. - /// The options the host filled. It carries the registered vendors. - /// The factory every seam below takes its loggers from. - /// Cancels the adapter build. - /// The session, or when the host registered no vendor. - internal static async ValueTask StartAsync( - AgentCoreConfiguration configuration, - AgentCoreOptions options, - ILoggerFactory loggers, - CancellationToken cancellationToken) + /// Step 2b: start the telemetry export, before anything below writes a line worth keeping. + internal static class TelemetryStartup { - ITelemetrySession? telemetry = options.Telemetry is { } telemetryAdapters - ? await TelemetrySessionFactory - .StartAsync(configuration, options.SecretResolver, telemetryAdapters, cancellationToken) - .ConfigureAwait(false) - : null; - - if (telemetry?.Logs is { } telemetryLogs) + /// Starts the export the document names, and attaches its log provider. + /// The loaded document. It carries providers.telemetry. + /// The options the host filled. It carries the registered vendors. + /// The factory every seam below takes its loggers from. + /// Cancels the adapter build. + /// The session, or when the host registered no vendor. + internal static async ValueTask StartAsync( + AgentCoreConfiguration configuration, + AgentCoreOptions options, + ILoggerFactory loggers, + CancellationToken cancellationToken) { - loggers.AddProvider(telemetryLogs); - } + ITelemetrySession? telemetry = options.Telemetry is { } telemetryAdapters + ? await TelemetrySessionFactory + .StartAsync(configuration, options.SecretResolver, telemetryAdapters, cancellationToken) + .ConfigureAwait(false) + : null; - return telemetry; + if (telemetry?.Logs is { } telemetryLogs) + { + loggers.AddProvider(telemetryLogs); + } + + return telemetry; + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs index 719666b0..ebf23ba7 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ToolRegistryStartup.cs @@ -4,92 +4,93 @@ using AgentCore.Application.Tools.Builtin; using AgentCore.Application.Tools.Registry; -namespace AgentCore.AspNetCore.DependencyInjection.Startup; - -/// Everything step 4 built. -/// The registry the compile table reads. Its own Ids are every id it serves. -/// -/// Every id decision 15's reference pass may treat as satisfied: 's own -/// Ids, unioned with every declared kind: agent tool id. That kind reaches no source — -/// the compile table builds it once the agent it names has compiled — so -/// never holds it, the same reason carves it out of its -/// own "every declaration is served" check. Computed once, here, so the composition root's reference -/// pass and that check can never silently disagree about which ids count as served. -/// -internal readonly record struct ToolRegistryBuildResult( - ToolRegistry Registry, IReadOnlySet ServedIds); - -/// Step 4: build the one tool registry the compile table reads. -internal static class ToolRegistryStartup +namespace AgentCore.AspNetCore.DependencyInjection.Startup { - /// Asks every source what it serves, and holds the answers. - /// The owner every source is tracked against, the moment it is built. - /// The options the host filled. - /// The loaded document and the resolved secrets. - /// - /// What a shipped built-in runs on: the chat client factory step 3c built (it fails the boot rather - /// than returning none), the blob store step 4d opened or , the workspace - /// root, and the logger factory. + /// Everything step 4 built. + /// The registry the compile table reads. Its own Ids are every id it serves. + /// + /// Every id decision 15's reference pass may treat as satisfied: 's own + /// Ids, unioned with every declared kind: agent tool id. That kind reaches no source — + /// the compile table builds it once the agent it names has compiled — so + /// never holds it, the same reason carves it out of its + /// own "every declaration is served" check. Computed once, here, so the composition root's reference + /// pass and that check can never silently disagree about which ids count as served. /// - /// Cancels the discovery. - /// The registry, and the served-ids union decision 15's reference pass reads. - /// - /// A source's own discovery fails, an id collision is found, or the document declares a tool no - /// source serves. Every source is tracked against before discovery runs, - /// so a source that opened a client — or a child process — is closed however this fails. - /// - internal static async ValueTask BuildAsync( - AgentCoreBoot boot, - AgentCoreOptions options, - AgentCoreStartup startup, - BuiltinToolPorts ports, - CancellationToken cancellationToken) - { - var configuration = startup.Configuration; - - List sources = - [ - new BuiltinToolSource(ports), - new BindingToolSource(options.Bindings), - ]; - - foreach (var extra in options.ToolSources) - { - sources.Add(boot.Track(extra(startup))); - } + internal readonly record struct ToolRegistryBuildResult( + ToolRegistry Registry, IReadOnlySet ServedIds); - if (configuration.Mcp.Count > 0 && options.ToolSources.Count == 0) + /// Step 4: build the one tool registry the compile table reads. + internal static class ToolRegistryStartup + { + /// Asks every source what it serves, and holds the answers. + /// The owner every source is tracked against, the moment it is built. + /// The options the host filled. + /// The loaded document and the resolved secrets. + /// + /// What a shipped built-in runs on: the chat client factory step 3c built (it fails the boot rather + /// than returning none), the blob store step 4d opened or , the workspace + /// root, and the logger factory. + /// + /// Cancels the discovery. + /// The registry, and the served-ids union decision 15's reference pass reads. + /// + /// A source's own discovery fails, an id collision is found, or the document declares a tool no + /// source serves. Every source is tracked against before discovery runs, + /// so a source that opened a client — or a child process — is closed however this fails. + /// + internal static async ValueTask BuildAsync( + AgentCoreBoot boot, + AgentCoreOptions options, + AgentCoreStartup startup, + BuiltinToolPorts ports, + CancellationToken cancellationToken) { - throw ToolSourceError.Fail( - "the document declares mcp:, and nothing registered a tool source to connect to it. Conversation " - + "AddAgentCoreHost (AgentCore.Hosting), or register one yourself with " - + "options.AddToolSource(...)."); - } - - var registry = await ToolRegistryBuilder - .BuildAsync(sources, new ToolSourceContext(configuration) { Cache = options.Cache }, cancellationToken) - .ConfigureAwait(false); + AgentCoreConfiguration configuration = startup.Configuration; - var servedIds = registry.Ids.ToHashSet(StringComparer.Ordinal); + List sources = + [ + new BuiltinToolSource(ports), + new BindingToolSource(options.Bindings), + ]; - foreach (var tool in configuration.Tools) - { - if (tool.Kind != ToolKind.Agent) + foreach (Func extra in options.ToolSources) { - continue; + sources.Add(boot.Track(extra(startup))); } - if (registry.Ids.Contains(tool.Id)) + if (configuration.Mcp.Count > 0 && options.ToolSources.Count == 0) { throw ToolSourceError.Fail( - $"two tools claim the id '{tool.Id}': a discovered tool serves it, and the " - + "document's own kind: agent declaration claims it too. An id names one tool, so " - + "rename one of them."); + "the document declares mcp:, and nothing registered a tool source to connect to it. Conversation " + + "AddAgentCoreHost (AgentCore.Hosting), or register one yourself with " + + "options.AddToolSource(...)."); } - servedIds.Add(tool.Id); - } + ToolRegistry registry = await ToolRegistryBuilder + .BuildAsync(sources, new ToolSourceContext(configuration) { Cache = options.Cache }, cancellationToken) + .ConfigureAwait(false); + + HashSet servedIds = registry.Ids.ToHashSet(StringComparer.Ordinal); + + foreach (ToolConfiguration tool in configuration.Tools) + { + if (tool.Kind != ToolKind.Agent) + { + continue; + } - return new ToolRegistryBuildResult(registry, servedIds); + if (registry.Ids.Contains(tool.Id)) + { + throw ToolSourceError.Fail( + $"two tools claim the id '{tool.Id}': a discovered tool serves it, and the " + + "document's own kind: agent declaration claims it too. An id names one tool, so " + + "rename one of them."); + } + + _ = servedIds.Add(tool.Id); + } + + return new ToolRegistryBuildResult(registry, servedIds); + } } } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/StartupLog.cs b/src/AgentCore.AspNetCore/DependencyInjection/StartupLog.cs index 0941a635..ce960bb5 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/StartupLog.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/StartupLog.cs @@ -1,30 +1,31 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.DependencyInjection; - -/// -/// Every line AddAgentCoreAsync writes while it wires the container. -/// -internal static partial class StartupLog +namespace AgentCore.AspNetCore.DependencyInjection { - /// The document named no providers.audit, so the in-process store was opened. - /// The factory's logger for the audit queue. - [LoggerMessage( - EventId = 1, - Level = LogLevel.Warning, - Message = "the document names no providers.audit, so the audit chain of D23 is kept in this " - + "process. That store is not durable and it grows without a bound. Name a durable " - + "providers.audit.kind, or write kind: memory to say this was meant.")] - public static partial void AuditSinkDefaulted(ILogger logger); + /// + /// Every line AddAgentCoreAsync writes while it wires the container. + /// + internal static partial class StartupLog + { + /// The document named no providers.audit, so the in-process store was opened. + /// The factory's logger for the audit queue. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Warning, + Message = "the document names no providers.audit, so the audit chain of D23 is kept in this " + + "process. That store is not durable and it grows without a bound. Name a durable " + + "providers.audit.kind, or write kind: memory to say this was meant.")] + public static partial void AuditSinkDefaulted(ILogger logger); - /// The document named no providers.conversations, so the in-process store was opened. - /// The factory's logger for the in-process store. - [LoggerMessage( - EventId = 3, - Level = LogLevel.Warning, - Message = "the document names no providers.conversations, so a conversation's row and the words of every " - + "conversation are kept in this process. That store is not durable, it grows without a bound, " - + "and no retention window applies to it. Name a durable providers.conversations.kind, or write " - + "kind: memory to say this was meant.")] - public static partial void ConversationStoreDefaulted(ILogger logger); + /// The document named no providers.conversations, so the in-process store was opened. + /// The factory's logger for the in-process store. + [LoggerMessage( + EventId = 3, + Level = LogLevel.Warning, + Message = "the document names no providers.conversations, so a conversation's row and the words of every " + + "conversation are kept in this process. That store is not durable, it grows without a bound, " + + "and no retention window applies to it. Name a durable providers.conversations.kind, or write " + + "kind: memory to say this was meant.")] + public static partial void ConversationStoreDefaulted(ILogger logger); + } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs index 42fff0ed..0d0e3f7d 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs @@ -4,232 +4,232 @@ using AgentCore.Application.Runtime; using AgentCore.Domain; -namespace AgentCore.AspNetCore.Endpoints; - -/// -/// The wire shapes of POST /v1/responses that are ours, beside the OpenAI shape. -/// -internal static class ResponsesAgentCore +namespace AgentCore.AspNetCore.Endpoints { - /// Reads the agentcore member of one request body, if it names one. - /// The request body. - /// What the client said about this turn, or for a plain turn. - internal static ResponsesRequestInfo? ReadRequest(JsonElement body) + /// + /// The wire shapes of POST /v1/responses that are ours, beside the OpenAI shape. + /// + internal static class ResponsesAgentCore { - if (!body.TryGetProperty("agentcore", out var agentcore) - || agentcore.ValueKind != JsonValueKind.Object) + /// Reads the agentcore member of one request body, if it names one. + /// The request body. + /// What the client said about this turn, or for a plain turn. + internal static ResponsesRequestInfo? ReadRequest(JsonElement body) { - return null; - } + if (!body.TryGetProperty("agentcore", out JsonElement agentcore) + || agentcore.ValueKind != JsonValueKind.Object) + { + return null; + } - string? messageId = null; - if (agentcore.TryGetProperty("message_id", out var message) - && message.ValueKind == JsonValueKind.String) - { - messageId = message.GetString(); - } + string? messageId = null; + if (agentcore.TryGetProperty("message_id", out JsonElement message) + && message.ValueKind == JsonValueKind.String) + { + messageId = message.GetString(); + } - string? parentId = null; - var namesParent = agentcore.TryGetProperty("parent_id", out var parent); - if (namesParent && parent.ValueKind == JsonValueKind.String) - { - parentId = parent.GetString(); - } + string? parentId = null; + bool namesParent = agentcore.TryGetProperty("parent_id", out JsonElement parent); + if (namesParent && parent.ValueKind == JsonValueKind.String) + { + parentId = parent.GetString(); + } + + ResponsesApprovalAnswer? approval = null; + if (agentcore.TryGetProperty("approval", out JsonElement answer) + && answer.ValueKind == JsonValueKind.Object + && answer.TryGetProperty("request_id", out JsonElement requestId) + && requestId.ValueKind == JsonValueKind.String + && requestId.GetString() is { Length: > 0 } id + && answer.TryGetProperty("approved", out JsonElement approved) + && (approved.ValueKind == JsonValueKind.True || approved.ValueKind == JsonValueKind.False)) + { + approval = new ResponsesApprovalAnswer(id, approved.ValueKind == JsonValueKind.True); + } - ResponsesApprovalAnswer? approval = null; - if (agentcore.TryGetProperty("approval", out var answer) - && answer.ValueKind == JsonValueKind.Object - && answer.TryGetProperty("request_id", out var requestId) - && requestId.ValueKind == JsonValueKind.String - && requestId.GetString() is { Length: > 0 } id - && answer.TryGetProperty("approved", out var approved) - && (approved.ValueKind == JsonValueKind.True || approved.ValueKind == JsonValueKind.False)) - { - approval = new ResponsesApprovalAnswer(id, approved.ValueKind == JsonValueKind.True); + return messageId is null && !namesParent && approval is null + ? null + : new ResponsesRequestInfo(messageId, parentId, namesParent, approval); } - if (messageId is null && !namesParent && approval is null) + /// Builds the metadata one finished turn files onto its answer. + /// The conversation the turn ran on. + /// The finished turn. + /// String pairs: the protocol's metadata holds strings only, and at most 16. + internal static IDictionary TurnMetadata(ConversationSession conversation, TurnResult turn) { - return null; - } + Dictionary metadata = new(StringComparer.Ordinal) + { + ["call_id"] = conversation.ConversationId, + ["turn_index"] = turn.TurnIndex.ToString(System.Globalization.CultureInfo.InvariantCulture), + ["stage_before"] = turn.StageBefore, + ["stage_after"] = turn.StageAfter, + ["is_terminal"] = turn.IsTerminal ? "true" : "false", + }; + + if (conversation.LastReplyMessageId is { } messageId) + { + metadata["message_id"] = messageId; + } - return new ResponsesRequestInfo(messageId, parentId, namesParent, approval); - } + if (turn.ExtractionFailure is { } failure) + { + metadata["extraction_failure"] = failure; + } - /// Builds the metadata one finished turn files onto its answer. - /// The conversation the turn ran on. - /// The finished turn. - /// String pairs: the protocol's metadata holds strings only, and at most 16. - internal static IDictionary TurnMetadata(ConversationSession conversation, TurnResult turn) - { - Dictionary metadata = new(StringComparer.Ordinal) - { - ["call_id"] = conversation.ConversationId, - ["turn_index"] = turn.TurnIndex.ToString(System.Globalization.CultureInfo.InvariantCulture), - ["stage_before"] = turn.StageBefore, - ["stage_after"] = turn.StageAfter, - ["is_terminal"] = turn.IsTerminal ? "true" : "false", - }; + if (turn.Approvals.Count > 0) + { + metadata["approvals"] = ApprovalsJson(turn); + } - if (conversation.LastReplyMessageId is { } messageId) - { - metadata["message_id"] = messageId; + return metadata; } - if (turn.ExtractionFailure is { } failure) + /// Answers where one turn hangs, in the shape the turn loop reads. + /// What the client said, or for a plain turn. + /// The origin, or when the turn appends. + internal static ConversationTurnOrigin? OriginOf(ResponsesRequestInfo? info) { - metadata["extraction_failure"] = failure; + return info is null ? null : new ConversationTurnOrigin(info.MessageId, info.ParentId) { NamesParent = info.NamesParent }; } - if (turn.Approvals.Count > 0) + private static string ApprovalsJson(TurnResult turn) { - metadata["approvals"] = ApprovalsJson(turn); + JsonArray approvals = []; + foreach (PendingApproval approval in turn.Approvals) + { + approvals.Add(new JsonObject + { + ["request_id"] = approval.RequestId, + ["tool"] = approval.ToolName, + ["arguments"] = JsonNode.Parse(approval.Arguments.GetRawText()), + }); + } + + return approvals.ToJsonString(); } - - return metadata; } - /// Answers where one turn hangs, in the shape the turn loop reads. - /// What the client said, or for a plain turn. - /// The origin, or when the turn appends. - internal static ConversationTurnOrigin? OriginOf(ResponsesRequestInfo? info) - => info is null ? null : new ConversationTurnOrigin(info.MessageId, info.ParentId) { NamesParent = info.NamesParent }; - - private static string ApprovalsJson(TurnResult turn) + /// Where the client says its turn belongs and what it answers, beside the OpenAI shape. + /// What the client calls the message it is sending. + /// What the client calls the message this one hangs off. Null starts the conversation afresh. + /// Whether the body carried parent_id at all. + /// The approval answer this turn carries, or when it holds words. + internal sealed record ResponsesRequestInfo( + string? MessageId, + string? ParentId, + bool NamesParent, + ResponsesApprovalAnswer? Approval); + + /// One approval answer: which request the caller answers, and whether the tool may run. + /// The id of the pending request this answers. + /// Whether the tool may run. + internal sealed record ResponsesApprovalAnswer(string RequestId, bool Approved); + + /// + /// The one serializer setting the dialect uses. + /// + internal static class ResponsesJson { - System.Text.Json.Nodes.JsonArray approvals = []; - foreach (var approval in turn.Approvals) + /// The one serializer setting both directions use. + public static JsonSerializerOptions Options { get; } = new(JsonSerializerDefaults.Web) { - approvals.Add(new System.Text.Json.Nodes.JsonObject - { - ["request_id"] = approval.RequestId, - ["tool"] = approval.ToolName, - ["arguments"] = System.Text.Json.Nodes.JsonNode.Parse(approval.Arguments.GetRawText()), - }); - } - - return approvals.ToJsonString(); + PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, + }; } -} -/// Where the client says its turn belongs and what it answers, beside the OpenAI shape. -/// What the client calls the message it is sending. -/// What the client calls the message this one hangs off. Null starts the conversation afresh. -/// Whether the body carried parent_id at all. -/// The approval answer this turn carries, or when it holds words. -internal sealed record ResponsesRequestInfo( - string? MessageId, - string? ParentId, - bool NamesParent, - ResponsesApprovalAnswer? Approval); - -/// One approval answer: which request the caller answers, and whether the tool may run. -/// The id of the pending request this answers. -/// Whether the tool may run. -internal sealed record ResponsesApprovalAnswer(string RequestId, bool Approved); - -/// -/// The one serializer setting the dialect uses. -/// -internal static class ResponsesJson -{ - /// The one serializer setting both directions use. - public static JsonSerializerOptions Options { get; } = new(JsonSerializerDefaults.Web) + /// One half of one tool call, as the browser reads it. + internal sealed record ToolPayload { - PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower, - DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, - }; -} + /// Gets the id both halves of one call share. + public required string CallId { get; init; } -/// One half of one tool call, as the browser reads it. -internal sealed record ToolPayload -{ - /// Gets the id both halves of one call share. - public required string CallId { get; init; } + /// Gets the name of the tool. + public required string Name { get; init; } - /// Gets the name of the tool. - public required string Name { get; init; } + /// Gets which half this is: call or result. + public required string Phase { get; init; } - /// Gets which half this is: call or result. - public required string Phase { get; init; } + /// Gets what the model passed, on the call half only. + public JsonNode? Arguments { get; init; } - /// Gets what the model passed, on the call half only. - public JsonNode? Arguments { get; init; } + /// Gets what the tool answered, on the result half only. + public JsonNode? Result { get; init; } - /// Gets what the tool answered, on the result half only. - public JsonNode? Result { get; init; } - - /// Gets whether the tool failed, on the result half only. - public bool? Failed { get; init; } -} + /// Gets whether the tool failed, on the result half only. + public bool? Failed { get; init; } + } -/// One tool call waiting on the caller, as the browser reads it. -internal sealed record ApprovalPayload -{ - /// Gets the id the approval answer carries back. - [JsonPropertyName("request_id")] - public required string RequestId { get; init; } + /// One tool call waiting on the caller, as the browser reads it. + internal sealed record ApprovalPayload + { + /// Gets the id the approval answer carries back. + [JsonPropertyName("request_id")] + public required string RequestId { get; init; } - /// Gets the name of the tool the model asked to call. - public required string Tool { get; init; } + /// Gets the name of the tool the model asked to call. + public required string Tool { get; init; } - /// Gets what the model passed, or when it passed nothing. - public JsonNode? Arguments { get; init; } -} + /// Gets what the model passed, or when it passed nothing. + public JsonNode? Arguments { get; init; } + } -/// Where one answer came from, as the browser reads it. -internal sealed record SourcePayload -{ - /// Gets the tool call this source was cited under. - public required string CallId { get; init; } + /// Where one answer came from, as the browser reads it. + internal sealed record SourcePayload + { + /// Gets the tool call this source was cited under. + public required string CallId { get; init; } - /// Gets the id of this source, unique within one turn. - public required string Id { get; init; } + /// Gets the id of this source, unique within one turn. + public required string Id { get; init; } - /// Gets which shape it takes: document or url. - public required string SourceType { get; init; } + /// Gets which shape it takes: document or url. + public required string SourceType { get; init; } - /// Gets what the source is called. - public required string Title { get; init; } + /// Gets what the source is called. + public required string Title { get; init; } - /// Gets where inside the source it sits, such as p.27. Empty when it has none. - public required string Locator { get; init; } + /// Gets where inside the source it sits, such as p.27. Empty when it has none. + public required string Locator { get; init; } - /// Gets the link to open, or when there is nothing to open. - public string? Url { get; init; } + /// Gets the link to open, or when there is nothing to open. + public string? Url { get; init; } - /// Gets the media type of the source. - public required string MediaType { get; init; } + /// Gets the media type of the source. + public required string MediaType { get; init; } - /// Gets what produced this source, such as knowledge. - public required string Origin { get; init; } -} + /// Gets what produced this source, such as knowledge. + public required string Origin { get; init; } + } -/// One file the model published from the workspace and the store kept, as the browser reads it. -internal sealed record FilePayload -{ - /// Gets the file name the store keeps it under. - public required string Name { get; init; } + /// One file the model published from the workspace and the store kept, as the browser reads it. + internal sealed record FilePayload + { + /// Gets the file name the store keeps it under. + public required string Name { get; init; } - /// Gets the label the model gave it for the person, or . - public string? Title { get; init; } + /// Gets the label the model gave it for the person, or . + public string? Title { get; init; } - /// Gets the IANA media type, such as image/png. - public required string MediaType { get; init; } + /// Gets the IANA media type, such as image/png. + public required string MediaType { get; init; } - /// Gets how many bytes it holds. - public required long Length { get; init; } + /// Gets how many bytes it holds. + public required long Length { get; init; } - /// Gets the link to fetch it from, or when the store has no web door. - public string? Url { get; init; } -} + /// Gets the link to fetch it from, or when the store has no web door. + public string? Url { get; init; } + } -/// One thing a stream asks the browser to draw. -internal sealed record RenderedPayload -{ - /// Gets the renderer the browser looks up. - public required string Name { get; init; } + /// One thing a stream asks the browser to draw. + internal sealed record RenderedPayload + { + /// Gets the renderer the browser looks up. + public required string Name { get; init; } - /// Gets the payload that renderer reads. - public required JsonElement Data { get; init; } + /// Gets the payload that renderer reads. + public required JsonElement Data { get; init; } + } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs index af6dacec..4a6d04a8 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs @@ -12,318 +12,318 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; -namespace AgentCore.AspNetCore.Endpoints; - -/// -/// The Responses path: an OpenAI-compatible POST /v1/{entry}/responses over the turn loop, -/// with the conversation continuing across requests through the session store. -/// -public static class ResponsesEndpointRouteBuilderExtensions +namespace AgentCore.AspNetCore.Endpoints { - /// The route parameter that names the entry, as {entry} in a pattern. - public const string EntryRouteParameter = "entry"; - - /// The route every entry answers on when the host names none. - public const string DefaultPattern = "/v1/{" + EntryRouteParameter + "}/responses"; - - /// The answer header that reports the stage the machine holds. - public const string StageHeaderName = "X-AgentCore-Stage"; - /// - /// The request header that names the zone the person is in, as an IANA id such as - /// America/Chicago. + /// The Responses path: an OpenAI-compatible POST /v1/{entry}/responses over the turn loop, + /// with the conversation continuing across requests through the session store. /// - public const string TimeZoneHeaderName = "X-AgentCore-Time-Zone"; - - /// Maps every entry on , with the URL naming the entry. - /// The route builder of the host. - /// The mapped endpoint, so a host adds its own conventions. - public static IEndpointConventionBuilder MapResponses(this IEndpointRouteBuilder endpoints) - => endpoints.MapResponses(DefaultPattern); - - /// Maps every entry on one route, with the URL naming the entry. - /// The route builder of the host. - /// The route to answer on. It must carry the {entry} parameter. - /// The mapped endpoint, so a host adds its own conventions. - /// carries no {entry}. - public static IEndpointConventionBuilder MapResponses(this IEndpointRouteBuilder endpoints, string pattern) + public static class ResponsesEndpointRouteBuilderExtensions { - ArgumentNullException.ThrowIfNull(endpoints); - ArgumentException.ThrowIfNullOrEmpty(pattern); + /// The route parameter that names the entry, as {entry} in a pattern. + public const string EntryRouteParameter = "entry"; - if (!pattern.Contains("{" + EntryRouteParameter + "}", StringComparison.Ordinal)) - { - throw new ArgumentException( - $"The pattern '{pattern}' carries no {{{EntryRouteParameter}}} parameter, so no URL can name " - + "an entry.", - nameof(pattern)); - } + /// The route every entry answers on when the host names none. + public const string DefaultPattern = "/v1/{" + EntryRouteParameter + "}/responses"; - return endpoints.MapPost(pattern, HandleAsync); - } + /// The answer header that reports the stage the machine holds. + public const string StageHeaderName = "X-AgentCore-Stage"; - /// Runs one turn of one conversation, and files the session under the ids the answer carries. - /// - /// Every step answers its own refusal and returns , so this reads as - /// the happy path alone. - /// - private static async Task HandleAsync(HttpContext http) - { - var cancellationToken = http.RequestAborted; - var entry = http.Request.RouteValues[EntryRouteParameter] as string ?? string.Empty; + /// + /// The request header that names the zone the person is in, as an IANA id such as + /// America/Chicago. + /// + public const string TimeZoneHeaderName = "X-AgentCore-Time-Zone"; - if (await ResponsesRequestReader.ReadBodyAsync(http, cancellationToken).ConfigureAwait(false) is not { } body) + /// Maps every entry on , with the URL naming the entry. + /// The route builder of the host. + /// The mapped endpoint, so a host adds its own conventions. + public static IEndpointConventionBuilder MapResponses(this IEndpointRouteBuilder endpoints) { - return; + return endpoints.MapResponses(DefaultPattern); } - var agentcore = ResponsesAgentCore.ReadRequest(body); - var approval = agentcore?.Approval; - - var run = await ResponsesRequestReader - .ReadRunInputAsync(http, body, approving: approval is not null, cancellationToken) - .ConfigureAwait(false); - - if (run is null) + /// Maps every entry on one route, with the URL naming the entry. + /// The route builder of the host. + /// The route to answer on. It must carry the {entry} parameter. + /// The mapped endpoint, so a host adds its own conventions. + /// carries no {entry}. + public static IEndpointConventionBuilder MapResponses(this IEndpointRouteBuilder endpoints, string pattern) { - return; + ArgumentNullException.ThrowIfNull(endpoints); + ArgumentException.ThrowIfNullOrEmpty(pattern); + + return !pattern.Contains("{" + EntryRouteParameter + "}", StringComparison.Ordinal) + ? throw new ArgumentException( + $"The pattern '{pattern}' carries no {{{EntryRouteParameter}}} parameter, so no URL can name " + + "an entry.", + nameof(pattern)) + : endpoints.MapPost(pattern, HandleAsync); } - var entries = http.RequestServices.GetRequiredService().Entries; - if (!entries.Agents.TryGetValue(entry, out var agent)) + /// Runs one turn of one conversation, and files the session under the ids the answer carries. + /// + /// Every step answers its own refusal and returns , so this reads as + /// the happy path alone. + /// + private static async Task HandleAsync(HttpContext http) { - await ResponsesRequestReader.WriteErrorAsync( - http, - StatusCodes.Status404NotFound, - EntryRegistry.UnknownEntryMessage(entry, entries.Entries), - "unknown_entry", - cancellationToken).ConfigureAwait(false); - return; - } + CancellationToken cancellationToken = http.RequestAborted; + string entry = http.Request.RouteValues[EntryRouteParameter] as string ?? string.Empty; - var sessions = http.RequestServices.GetRequiredService(); + if (await ResponsesRequestReader.ReadBodyAsync(http, cancellationToken).ConfigureAwait(false) is not { } body) + { + return; + } - var opened = await OpenSessionAsync(http, agent, sessions, run, approving: approval is not null, cancellationToken) - .ConfigureAwait(false); + ResponsesRequestInfo? agentcore = ResponsesAgentCore.ReadRequest(body); + ResponsesApprovalAnswer? approval = agentcore?.Approval; - if (opened is null) - { - return; - } + ResponsesRunInput? run = await ResponsesRequestReader + .ReadRunInputAsync(http, body, approving: approval is not null, cancellationToken) + .ConfigureAwait(false); - var (session, conversationId) = opened.Value; + if (run is null) + { + return; + } - if (session.GetService() is not { } conversation) - { - throw new InvalidOperationException( - "The session is not one this agent created, so it names no call to run."); - } + EntryRegistry entries = http.RequestServices.GetRequiredService().Entries; + if (!entries.Agents.TryGetValue(entry, out AgentCoreAgent? agent)) + { + await ResponsesRequestReader.WriteErrorAsync( + http, + StatusCodes.Status404NotFound, + EntryRegistry.UnknownEntryMessage(entry, entries.Entries), + "unknown_entry", + cancellationToken).ConfigureAwait(false); + return; + } - var input = await ReadInputAsync(http, conversation, approval, run.Messages, cancellationToken) - .ConfigureAwait(false); + AgentCoreAgentSessionStore sessions = http.RequestServices.GetRequiredService(); - if (input is null) - { - return; - } + (AgentSession Session, string? ConversationId)? opened = await OpenSessionAsync(http, agent, sessions, run, approving: approval is not null, cancellationToken) + .ConfigureAwait(false); - // A conversation the request named stays the conversation; a keyless first turn minted - // one alongside the session above. A response id is minted every turn either way, so a - // chain can start from any answer. - ResponsesTurn turn = new( - agent, - sessions, - session, - conversation, - input, - ResponsesAgentCore.OriginOf(agentcore), - OpenAIResponses.CreateResponseId(), - conversationId); - - await RunTurnAsync(http, body, turn, dialect: agentcore is not null, cancellationToken).ConfigureAwait(false); - } + if (opened is null) + { + return; + } - /// Opens the session the turn runs on: a new one, or the one the continuation names. - /// - /// The session and the conversation id it runs under, or once a - /// refusal has been answered. - /// - private static async Task<(AgentSession Session, string? ConversationId)?> OpenSessionAsync( - HttpContext http, - AgentCoreAgent agent, - AgentCoreAgentSessionStore sessions, - ResponsesRunInput run, - bool approving, - CancellationToken cancellationToken) - { - var key = run.ContinuationKey; - var conversationId = run.ConversationId; + (AgentSession? session, string? conversationId) = opened.Value; + + if (session.GetService() is not { } conversation) + { + throw new InvalidOperationException( + "The session is not one this agent created, so it names no call to run."); + } - var known = key is not null - && await sessions.ContainsAsync(key, cancellationToken).ConfigureAwait(false); + ChatMessage? input = await ReadInputAsync(http, conversation, approval, run.Messages, cancellationToken) + .ConfigureAwait(false); - var namesNewConversation = key is not null - && !known - && string.Equals(key, conversationId, StringComparison.Ordinal) - && conversationId is not null - && !approving; + if (input is null) + { + return; + } - if (key is null) + // A conversation the request named stays the conversation; a keyless first turn minted + // one alongside the session above. A response id is minted every turn either way, so a + // chain can start from any answer. + ResponsesTurn turn = new( + agent, + sessions, + session, + conversation, + input, + ResponsesAgentCore.OriginOf(agentcore), + OpenAIResponses.CreateResponseId(), + conversationId); + + await RunTurnAsync(http, body, turn, dialect: agentcore is not null, cancellationToken).ConfigureAwait(false); + } + + /// Opens the session the turn runs on: a new one, or the one the continuation names. + /// + /// The session and the conversation id it runs under, or once a + /// refusal has been answered. + /// + private static async Task<(AgentSession Session, string? ConversationId)?> OpenSessionAsync( + HttpContext http, + AgentCoreAgent agent, + AgentCoreAgentSessionStore sessions, + ResponsesRunInput run, + bool approving, + CancellationToken cancellationToken) { - if (approving) + string? key = run.ContinuationKey; + string? conversationId = run.ConversationId; + + bool known = key is not null + && await sessions.ContainsAsync(key, cancellationToken).ConfigureAwait(false); + + bool namesNewConversation = key is not null + && !known + && string.Equals(key, conversationId, StringComparison.Ordinal) + && conversationId is not null + && !approving; + + if (key is null) { + if (approving) + { + await ResponsesRequestReader.WriteErrorAsync( + http, + StatusCodes.Status400BadRequest, + "an approval answer names the conversation it resumes. Send it with the conversation " + + "or previous response id the asking turn answered with.", + "missing_session", + cancellationToken).ConfigureAwait(false); + return null; + } + + conversationId = ResponsesRequestReader.NewConversationId(); + return (await agent.CreateSessionAsync(conversationId).ConfigureAwait(false), conversationId); + } + + if (namesNewConversation) + { + // Unknown conversation with words: start the conversation under that id, so the conversation + // and the continuation key are one id. Unknown response ids stay 404 below: they name + // a turn, not a conversation. + return (await agent.CreateSessionAsync(key).ConfigureAwait(false), conversationId); + } + + if (!known) + { + // Either an unknown response id — a turn no answer ever carried — or an unknown + // conversation beside an approval-only body the parse refused. A conversation with words + // reaches the namesNewConversation branch; an approval never starts a conversation. await ResponsesRequestReader.WriteErrorAsync( http, - StatusCodes.Status400BadRequest, - "an approval answer names the conversation it resumes. Send it with the conversation " - + "or previous response id the asking turn answered with.", - "missing_session", + StatusCodes.Status404NotFound, + $"no conversation opens under '{key}'. Send the request with neither a conversation nor a " + + "previous response id to start one.", + "continuation_not_found", cancellationToken).ConfigureAwait(false); return null; } - conversationId = ResponsesRequestReader.NewConversationId(); - return (await agent.CreateSessionAsync(conversationId, cancellationToken).ConfigureAwait(false), conversationId); - } - - if (namesNewConversation) - { - // Unknown conversation with words: start the conversation under that id, so the conversation - // and the continuation key are one id. Unknown response ids stay 404 below: they name - // a turn, not a conversation. - return (await agent.CreateSessionAsync(key, cancellationToken).ConfigureAwait(false), conversationId); + try + { + return (await sessions.GetSessionAsync(agent, key, cancellationToken).ConfigureAwait(false), conversationId); + } + catch (InvalidOperationException failure) + { + // A key minted by another entry is unknown to this one, never a cross-entry read. + await ResponsesRequestReader.WriteErrorAsync( + http, + StatusCodes.Status404NotFound, + failure.Message, + "continuation_not_found", + cancellationToken).ConfigureAwait(false); + return null; + } } - if (!known) + /// Picks what the turn runs on: the approval answer, or the last user message with words. + /// The input, or once a refusal has been answered. + private static async Task ReadInputAsync( + HttpContext http, + ConversationSession conversation, + ResponsesApprovalAnswer? approval, + IReadOnlyList messages, + CancellationToken cancellationToken) { - // Either an unknown response id — a turn no answer ever carried — or an unknown - // conversation beside an approval-only body the parse refused. A conversation with words - // reaches the namesNewConversation branch; an approval never starts a conversation. - await ResponsesRequestReader.WriteErrorAsync( - http, - StatusCodes.Status404NotFound, - $"no conversation opens under '{key}'. Send the request with neither a conversation nor a " - + "previous response id to start one.", - "continuation_not_found", - cancellationToken).ConfigureAwait(false); - return null; - } + if (approval is null) + { + if (ResponsesRequestReader.LastUserMessage(messages) is { } user) + { + return user; + } - try - { - return (await sessions.GetSessionAsync(agent, key, cancellationToken).ConfigureAwait(false), conversationId); - } - catch (InvalidOperationException failure) - { - // A key minted by another entry is unknown to this one, never a cross-entry read. - await ResponsesRequestReader.WriteErrorAsync( - http, - StatusCodes.Status404NotFound, - failure.Message, - "continuation_not_found", - cancellationToken).ConfigureAwait(false); - return null; - } - } + await ResponsesRequestReader.WriteErrorAsync( + http, + StatusCodes.Status400BadRequest, + "the request carries no user message with text, so there is no turn to run.", + "no_user_message", + cancellationToken).ConfigureAwait(false); + return null; + } - /// Picks what the turn runs on: the approval answer, or the last user message with words. - /// The input, or once a refusal has been answered. - private static async Task ReadInputAsync( - HttpContext http, - ConversationSession conversation, - ResponsesApprovalAnswer? approval, - IReadOnlyList messages, - CancellationToken cancellationToken) - { - if (approval is null) - { - if (ResponsesRequestReader.LastUserMessage(messages) is { } user) + if (ResponsesRequestReader.LastUserText(messages) is { Length: > 0 }) { - return user; + await ResponsesRequestReader.WriteErrorAsync( + http, + StatusCodes.Status400BadRequest, + "the request carries both a user message and an approval answer. One turn carries " + + "either words or an answer, never both.", + "mixed_turn", + cancellationToken).ConfigureAwait(false); + return null; } - await ResponsesRequestReader.WriteErrorAsync( - http, - StatusCodes.Status400BadRequest, - "the request carries no user message with text, so there is no turn to run.", - "no_user_message", - cancellationToken).ConfigureAwait(false); - return null; - } + // Async: a resumed conversation has run no turn in this process, so its ledger session — + // and the queue the suspending turn filed — is still closed. This opens it first. + if (await conversation.TryCreateApprovalAnswerAsync(approval.RequestId, approval.Approved, cancellationToken).ConfigureAwait(false) is { } answer) + { + return answer; + } - if (ResponsesRequestReader.LastUserText(messages) is { Length: > 0 }) - { await ResponsesRequestReader.WriteErrorAsync( http, - StatusCodes.Status400BadRequest, - "the request carries both a user message and an approval answer. One turn carries " - + "either words or an answer, never both.", - "mixed_turn", + StatusCodes.Status409Conflict, + $"the conversation queues no approval under id '{approval.RequestId}'. It was " + + "answered already, belongs to another conversation, or was never asked.", + "no_pending_approval", cancellationToken).ConfigureAwait(false); return null; } - // Async: a resumed conversation has run no turn in this process, so its ledger session — - // and the queue the suspending turn filed — is still closed. This opens it first. - if (await conversation.TryCreateApprovalAnswerAsync(approval.RequestId, approval.Approved, cancellationToken).ConfigureAwait(false) is { } answer) + /// Runs the turn on the branch the body asked for, and answers a refused turn as 409. + private static async Task RunTurnAsync( + HttpContext http, + JsonElement body, + ResponsesTurn turn, + bool dialect, + CancellationToken cancellationToken) { - return answer; - } - - await ResponsesRequestReader.WriteErrorAsync( - http, - StatusCodes.Status409Conflict, - $"the conversation queues no approval under id '{approval.RequestId}'. It was " - + "answered already, belongs to another conversation, or was never asked.", - "no_pending_approval", - cancellationToken).ConfigureAwait(false); - return null; - } - - /// Runs the turn on the branch the body asked for, and answers a refused turn as 409. - private static async Task RunTurnAsync( - HttpContext http, - JsonElement body, - ResponsesTurn turn, - bool dialect, - CancellationToken cancellationToken) - { - var streaming = body.TryGetProperty("stream", out var streamFlag) - && streamFlag.ValueKind == JsonValueKind.True; + bool streaming = body.TryGetProperty("stream", out JsonElement streamFlag) + && streamFlag.ValueKind == JsonValueKind.True; - // Only the stream has a frame to carry a drawing, so only the stream gets a screen. Binding - // one on the whole-reply branch would let the tool report a picture the caller never sees. - // Set per request, not once: the session outlives a request and the branch can differ per turn. - turn.Conversation.SetHasScreen(streaming); + // Only the stream has a frame to carry a drawing, so only the stream gets a screen. Binding + // one on the whole-reply branch would let the tool report a picture the caller never sees. + // Set per request, not once: the session outlives a request and the branch can differ per turn. + turn.Conversation.SetHasScreen(streaming); - if (CallerTimeZone.Parse(http.Request.Headers[TimeZoneHeaderName]) is { } zone) - { - CallerTimeZone.Set(turn.Session, zone); - } + if (CallerTimeZone.Parse(http.Request.Headers[TimeZoneHeaderName]) is { } zone) + { + CallerTimeZone.Set(turn.Session, zone); + } - try - { - if (streaming) + try { - // The dialect is opt-in by the member only our clients send: an OpenAI SDK - // never carries agentcore, so its stream stays the framework's pure shapes. - await ResponsesTurnStream.WriteAsync(http, turn, dialect, cancellationToken).ConfigureAwait(false); + if (streaming) + { + // The dialect is opt-in by the member only our clients send: an OpenAI SDK + // never carries agentcore, so its stream stays the framework's pure shapes. + await ResponsesTurnStream.WriteAsync(http, turn, dialect, cancellationToken).ConfigureAwait(false); + } + else + { + await ResponsesTurnReply.WriteAsync(http, turn, cancellationToken).ConfigureAwait(false); + } } - else + catch (InvalidOperationException exception) { - await ResponsesTurnReply.WriteAsync(http, turn, cancellationToken).ConfigureAwait(false); + // The turn loop refuses a turn on a finished conversation, and refuses a second turn while one + // runs. Both are a caller mistake and neither is a defect of this host. + await ResponsesRequestReader.WriteErrorAsync( + http, + StatusCodes.Status409Conflict, + exception.Message, + "turn_refused", + cancellationToken).ConfigureAwait(false); } } - catch (InvalidOperationException exception) - { - // The turn loop refuses a turn on a finished conversation, and refuses a second turn while one - // runs. Both are a caller mistake and neither is a defect of this host. - await ResponsesRequestReader.WriteErrorAsync( - http, - StatusCodes.Status409Conflict, - exception.Message, - "turn_refused", - cancellationToken).ConfigureAwait(false); - } } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesRequestReader.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesRequestReader.cs index a6e3828a..5531f2d2 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesRequestReader.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesRequestReader.cs @@ -5,166 +5,170 @@ using Microsoft.AspNetCore.Http; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Endpoints; - -/// What the Responses path reads off a request body, and how it answers a bad one. -internal static class ResponsesRequestReader +namespace AgentCore.AspNetCore.Endpoints { - /// The OpenAI error type every refused request reports. - private const string InvalidRequestError = "invalid_request_error"; - - /// Reads the request body as JSON. - /// The body, or once a 400 has been answered for a body that is not JSON. - internal static async Task ReadBodyAsync(HttpContext http, CancellationToken cancellationToken) - { - try - { - return await JsonSerializer - .DeserializeAsync(http.Request.Body, cancellationToken: cancellationToken) - .ConfigureAwait(false); - } - catch (JsonException exception) - { - await WriteErrorAsync( - http, - StatusCodes.Status400BadRequest, - "the request body is not well-formed JSON: " + exception.Message, - "malformed_body", - cancellationToken).ConfigureAwait(false); - return null; - } - } - - /// - /// Reads what the body asks to run, through the protocol parse. - /// says the body carries an approval answer, which the parse alone refuses. - /// - /// The run, or once a 400 has been answered for a body the parse refused. - /// - /// The protocol treats a conversation id and a response id as mutually exclusive, and the - /// helper prefers the response chain; the refused-parse fallback reads the same precedence off - /// the body. - /// - internal static async Task ReadRunInputAsync( - HttpContext http, - JsonElement body, - bool approving, - CancellationToken cancellationToken) + /// What the Responses path reads off a request body, and how it answers a bad one. + internal static class ResponsesRequestReader { - try - { - var runRequest = OpenAIResponses.ToAgentRunRequest(body); + /// The OpenAI error type every refused request reports. + private const string InvalidRequestError = "invalid_request_error"; - return new ResponsesRunInput( - NullIfBlank(runRequest.ConversationId), - [.. runRequest.Messages], - NullIfBlank(OpenAIResponses.GetSessionStoreId(runRequest))); - } - catch (ArgumentException exception) + /// Reads the request body as JSON. + /// The body, or once a 400 has been answered for a body that is not JSON. + internal static async Task ReadBodyAsync(HttpContext http, CancellationToken cancellationToken) { - // An approval answer carries no words, only the request it answers — and the - // protocol parse refuses a turn with no input. The continuation still names the - // conversation, so read it off the body and run the answer alone. - if (!approving) + try + { + return await JsonSerializer + .DeserializeAsync(http.Request.Body, cancellationToken: cancellationToken) + .ConfigureAwait(false); + } + catch (JsonException exception) { await WriteErrorAsync( http, StatusCodes.Status400BadRequest, - "the request is not a Responses request: " + exception.Message, - "invalid_body", + "the request body is not well-formed JSON: " + exception.Message, + "malformed_body", cancellationToken).ConfigureAwait(false); return null; } - - return new ResponsesRunInput( - NullIfBlank(ReadConversationId(body)), - [], - NullIfBlank(ReadContinuationId(body))); } - } - - private static string? NullIfBlank(string? value) - => string.IsNullOrWhiteSpace(value) ? null : value; - /// Reads the last user message that carries words, the session owning the rest. - internal static ChatMessage? LastUserMessage(IReadOnlyList messages) - { - ChatMessage? picked = null; - foreach (var message in messages) + /// + /// Reads what the body asks to run, through the protocol parse. + /// says the body carries an approval answer, which the parse alone refuses. + /// + /// The run, or once a 400 has been answered for a body the parse refused. + /// + /// The protocol treats a conversation id and a response id as mutually exclusive, and the + /// helper prefers the response chain; the refused-parse fallback reads the same precedence off + /// the body. + /// + internal static async Task ReadRunInputAsync( + HttpContext http, + JsonElement body, + bool approving, + CancellationToken cancellationToken) { - if (message.Role == ChatRole.User && message.Text is { Length: > 0 }) + try { - picked = message; + OpenAIResponsesRunRequest runRequest = OpenAIResponses.ToAgentRunRequest(body); + + return new ResponsesRunInput( + NullIfBlank(runRequest.ConversationId), + [.. runRequest.Messages], + NullIfBlank(OpenAIResponses.GetSessionStoreId(runRequest))); + } + catch (ArgumentException exception) + { + // An approval answer carries no words, only the request it answers — and the + // protocol parse refuses a turn with no input. The continuation still names the + // conversation, so read it off the body and run the answer alone. + if (!approving) + { + await WriteErrorAsync( + http, + StatusCodes.Status400BadRequest, + "the request is not a Responses request: " + exception.Message, + "invalid_body", + cancellationToken).ConfigureAwait(false); + return null; + } + + return new ResponsesRunInput( + NullIfBlank(ReadConversationId(body)), + [], + NullIfBlank(ReadContinuationId(body))); } } - return picked; - } - - /// Reads whether any user message of the run carries words. - internal static string? LastUserText(IReadOnlyList messages) - => LastUserMessage(messages)?.Text; + private static string? NullIfBlank(string? value) + { + return string.IsNullOrWhiteSpace(value) ? null : value; + } - /// Reads the conversation id off a body the protocol parse refused. - internal static string? ReadConversationId(JsonElement body) - { - if (body.TryGetProperty("conversation", out var conversation)) + /// Reads the last user message that carries words, the session owning the rest. + internal static ChatMessage? LastUserMessage(IReadOnlyList messages) { - if (conversation.ValueKind == JsonValueKind.String) + ChatMessage? picked = null; + foreach (ChatMessage message in messages) { - return conversation.GetString(); + if (message.Role == ChatRole.User && message.Text is { Length: > 0 }) + { + picked = message; + } } - if (conversation.ValueKind == JsonValueKind.Object - && conversation.TryGetProperty("id", out var id) - && id.ValueKind == JsonValueKind.String) - { - return id.GetString(); - } + return picked; } - return null; - } + /// Reads whether any user message of the run carries words. + internal static string? LastUserText(IReadOnlyList messages) + { + return LastUserMessage(messages)?.Text; + } - /// Reads the continuation off a body the protocol parse refused. - internal static string? ReadContinuationId(JsonElement body) - { - if (body.TryGetProperty("previous_response_id", out var response) - && response.ValueKind == JsonValueKind.String - && response.GetString() is { Length: > 0 } responseId) + /// Reads the conversation id off a body the protocol parse refused. + internal static string? ReadConversationId(JsonElement body) { - return responseId; + if (body.TryGetProperty("conversation", out JsonElement conversation)) + { + if (conversation.ValueKind == JsonValueKind.String) + { + return conversation.GetString(); + } + + if (conversation.ValueKind == JsonValueKind.Object + && conversation.TryGetProperty("id", out JsonElement id) + && id.ValueKind == JsonValueKind.String) + { + return id.GetString(); + } + } + + return null; } - return ReadConversationId(body); - } + /// Reads the continuation off a body the protocol parse refused. + internal static string? ReadContinuationId(JsonElement body) + { + return body.TryGetProperty("previous_response_id", out JsonElement response) + && response.ValueKind == JsonValueKind.String + && response.GetString() is { Length: > 0 } responseId + ? responseId + : ReadConversationId(body); + } - /// Answers one failure in the shape an OpenAI client reads. - internal static async Task WriteErrorAsync( - HttpContext http, - int status, - string message, - string code, - CancellationToken cancellationToken) - { - http.Response.StatusCode = status; + /// Answers one failure in the shape an OpenAI client reads. + internal static async Task WriteErrorAsync( + HttpContext http, + int status, + string message, + string code, + CancellationToken cancellationToken) + { + http.Response.StatusCode = status; - await http.Response.WriteAsJsonAsync( - new JsonObject - { - ["error"] = new JsonObject + await http.Response.WriteAsJsonAsync( + new JsonObject { - ["message"] = message, - ["type"] = InvalidRequestError, - ["code"] = code, - ["param"] = null, + ["error"] = new JsonObject + { + ["message"] = message, + ["type"] = InvalidRequestError, + ["code"] = code, + ["param"] = null, + }, }, - }, - cancellationToken).ConfigureAwait(false); - } + cancellationToken).ConfigureAwait(false); + } - /// Builds the id of one conversation. - /// The id, in the shape an OpenAI client already reads. - internal static string NewConversationId() - => string.Create(CultureInfo.InvariantCulture, $"conv_{Guid.NewGuid():N}"); + /// Builds the id of one conversation. + /// The id, in the shape an OpenAI client already reads. + internal static string NewConversationId() + { + return string.Create(CultureInfo.InvariantCulture, $"conv_{Guid.NewGuid():N}"); + } + } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesRunInput.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesRunInput.cs index 7a39271c..b71e23dc 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesRunInput.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesRunInput.cs @@ -1,15 +1,16 @@ using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Endpoints; - -/// What one Responses request asks to run, read off the body. -/// The conversation the request named, or . -/// The messages of the run. Empty for an approval-only body. -/// -/// The session-store key this turn hangs off, or for the first turn of a -/// conversation. A response id names one past turn; a conversation id names the conversation itself. -/// -internal sealed record ResponsesRunInput( - string? ConversationId, - IReadOnlyList Messages, - string? ContinuationKey); +namespace AgentCore.AspNetCore.Endpoints +{ + /// What one Responses request asks to run, read off the body. + /// The conversation the request named, or . + /// The messages of the run. Empty for an approval-only body. + /// + /// The session-store key this turn hangs off, or for the first turn of a + /// conversation. A response id names one past turn; a conversation id names the conversation itself. + /// + internal sealed record ResponsesRunInput( + string? ConversationId, + IReadOnlyList Messages, + string? ContinuationKey); +} diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesSessionFiling.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesSessionFiling.cs index 268fd0f7..197aa9d6 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesSessionFiling.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesSessionFiling.cs @@ -1,25 +1,26 @@ using AgentCore.AspNetCore.Sessions; using Microsoft.Agents.AI; -namespace AgentCore.AspNetCore.Endpoints; - -/// Files a session the Responses path just advanced, under every id that names it. -internal static class ResponsesSessionFiling +namespace AgentCore.AspNetCore.Endpoints { - /// Files the session the turn just advanced, under every id that names it now. - internal static async Task SaveAsync( - AgentCoreAgentSessionStore sessions, - AIAgent agent, - AgentSession session, - string responseId, - string? conversationId, - CancellationToken cancellationToken) + /// Files a session the Responses path just advanced, under every id that names it. + internal static class ResponsesSessionFiling { - if (conversationId is not null) + /// Files the session the turn just advanced, under every id that names it now. + internal static async Task SaveAsync( + AgentCoreAgentSessionStore sessions, + AIAgent agent, + AgentSession session, + string responseId, + string? conversationId, + CancellationToken cancellationToken) { - await sessions.SaveSessionAsync(agent, conversationId, session, cancellationToken).ConfigureAwait(false); - } + if (conversationId is not null) + { + await sessions.SaveSessionAsync(agent, conversationId, session, cancellationToken).ConfigureAwait(false); + } - await sessions.SaveSessionAsync(agent, responseId, session, cancellationToken).ConfigureAwait(false); + await sessions.SaveSessionAsync(agent, responseId, session, cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurn.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurn.cs index af6864dd..fae61c91 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurn.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurn.cs @@ -3,28 +3,31 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Endpoints; - -/// One turn the Responses path is about to run, and every id the answer files under. -/// The entry the URL named. -/// The store the session is filed in after the turn. -/// The session the turn advances. -/// The conversation inside . -/// The user words, or the approval answer, the turn runs on. -/// Where the request said the turn came from, or . -/// The id minted for this turn's answer. -/// The id of the conversation, or when none names it. -internal sealed record ResponsesTurn( - AgentCoreAgent Agent, - AgentCoreAgentSessionStore Sessions, - AgentSession Session, - ConversationSession Conversation, - ChatMessage Input, - ConversationTurnOrigin? Origin, - string ResponseId, - string? ConversationId) +namespace AgentCore.AspNetCore.Endpoints { - /// Files the session, under every id that names it now. - public Task FileAsync(CancellationToken cancellationToken) - => ResponsesSessionFiling.SaveAsync(Sessions, Agent, Session, ResponseId, ConversationId, cancellationToken); + /// One turn the Responses path is about to run, and every id the answer files under. + /// The entry the URL named. + /// The store the session is filed in after the turn. + /// The session the turn advances. + /// The conversation inside . + /// The user words, or the approval answer, the turn runs on. + /// Where the request said the turn came from, or . + /// The id minted for this turn's answer. + /// The id of the conversation, or when none names it. + internal sealed record ResponsesTurn( + AgentCoreAgent Agent, + AgentCoreAgentSessionStore Sessions, + AgentSession Session, + ConversationSession Conversation, + ChatMessage Input, + ConversationTurnOrigin? Origin, + string ResponseId, + string? ConversationId) + { + /// Files the session, under every id that names it now. + public Task FileAsync(CancellationToken cancellationToken) + { + return ResponsesSessionFiling.SaveAsync(Sessions, Agent, Session, ResponseId, ConversationId, cancellationToken); + } + } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnReply.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnReply.cs index 640f9f37..b324d1ab 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnReply.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnReply.cs @@ -1,50 +1,53 @@ +using System.Text.Json; using System.Text.Json.Nodes; +using AgentCore.Domain; using Microsoft.Agents.AI; using Microsoft.Agents.AI.Hosting.OpenAI; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Endpoints; - -/// The whole-reply branch of the Responses path: one turn, one JSON answer. -internal static class ResponsesTurnReply +namespace AgentCore.AspNetCore.Endpoints { - /// Runs one turn and answers the whole reply, filed under its ids. - internal static async Task WriteAsync(HttpContext http, ResponsesTurn turn, CancellationToken cancellationToken) + /// The whole-reply branch of the Responses path: one turn, one JSON answer. + internal static class ResponsesTurnReply { - var result = await turn.Conversation - .RunTurnMessageAtOriginAsync(turn.Input, turn.Origin, cancellationToken) - .ConfigureAwait(false); + /// Runs one turn and answers the whole reply, filed under its ids. + internal static async Task WriteAsync(HttpContext http, ResponsesTurn turn, CancellationToken cancellationToken) + { + TurnResult result = await turn.Conversation + .RunTurnMessageAtOriginAsync(turn.Input, turn.Origin, cancellationToken) + .ConfigureAwait(false); - await turn.FileAsync(cancellationToken).ConfigureAwait(false); + await turn.FileAsync(cancellationToken).ConfigureAwait(false); - var response = new AgentResponse(new ChatMessage(ChatRole.Assistant, result.ReplyText)) - { - AgentId = turn.Agent.Id, - ResponseId = turn.ResponseId, - CreatedAt = result.EndedAt, - }; + AgentResponse response = new(new ChatMessage(ChatRole.Assistant, result.ReplyText)) + { + AgentId = turn.Agent.Id, + ResponseId = turn.ResponseId, + CreatedAt = result.EndedAt, + }; - var rendered = OpenAIResponses.WriteResponse(response, turn.ResponseId, turn.ConversationId); + JsonElement rendered = OpenAIResponses.WriteResponse(response, turn.ResponseId, turn.ConversationId); - // The render is a closed JsonElement, so the turn facts go on as JSON: the object - // the framework wrote, with the metadata member replaced by ours beside its own. + // The render is a closed JsonElement, so the turn facts go on as JSON: the object + // the framework wrote, with the metadata member replaced by ours beside its own. - var node = JsonNode.Parse(rendered.GetRawText())!.AsObject(); - JsonObject metadata = node["metadata"]?.AsObject() ?? []; + JsonObject node = JsonNode.Parse(rendered.GetRawText())!.AsObject(); + JsonObject metadata = node["metadata"]?.AsObject() ?? []; - foreach (var (name, value) in ResponsesAgentCore.TurnMetadata(turn.Conversation, result)) - { - metadata[name] = value; - } + foreach ((string? name, string? value) in ResponsesAgentCore.TurnMetadata(turn.Conversation, result)) + { + metadata[name] = value; + } - node["metadata"] = metadata; + node["metadata"] = metadata; - http.Response.StatusCode = StatusCodes.Status200OK; - http.Response.Headers[ResponsesEndpointRouteBuilderExtensions.StageHeaderName] = result.StageAfter; + http.Response.StatusCode = StatusCodes.Status200OK; + http.Response.Headers[ResponsesEndpointRouteBuilderExtensions.StageHeaderName] = result.StageAfter; - await http.Response - .WriteAsJsonAsync(node, cancellationToken) - .ConfigureAwait(false); + await http.Response + .WriteAsJsonAsync(node, cancellationToken) + .ConfigureAwait(false); + } } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs index 266fcb26..e617463e 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs @@ -8,119 +8,120 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; -namespace AgentCore.AspNetCore.Endpoints; - -/// -/// The streaming half of the Responses path: one turn as server-sent events, with the dialect's -/// browser parts riding beside the framework's frames. -/// -internal static class ResponsesTurnStream +namespace AgentCore.AspNetCore.Endpoints { - /// Runs one turn and writes one Responses event for each update, filed under its ids. - /// - /// The session is filed after the enumeration ends, because the turn commits — - /// and the session only holds the turn — once the last update has left it. - /// The framework's frames carry text alone; when the request spoke the dialect, - /// each update's browser parts ride beside them as agentcore_* members, so drawings, - /// citations, tool halves, and approval asks stream. - /// - internal static async Task WriteAsync( - HttpContext http, - ResponsesTurn turn, - bool dialect, - CancellationToken cancellationToken) + /// + /// The streaming half of the Responses path: one turn as server-sent events, with the dialect's + /// browser parts riding beside the framework's frames. + /// + internal static class ResponsesTurnStream { - http.Response.StatusCode = StatusCodes.Status200OK; - http.Response.ContentType = "text/event-stream"; - http.Response.Headers.CacheControl = "no-cache"; + /// Runs one turn and writes one Responses event for each update, filed under its ids. + /// + /// The session is filed after the enumeration ends, because the turn commits — + /// and the session only holds the turn — once the last update has left it. + /// The framework's frames carry text alone; when the request spoke the dialect, + /// each update's browser parts ride beside them as agentcore_* members, so drawings, + /// citations, tool halves, and approval asks stream. + /// + internal static async Task WriteAsync( + HttpContext http, + ResponsesTurn turn, + bool dialect, + CancellationToken cancellationToken) + { + http.Response.StatusCode = StatusCodes.Status200OK; + http.Response.ContentType = "text/event-stream"; + http.Response.Headers.CacheControl = "no-cache"; - // The headers leave before the turn ends, so this one names the stage the turn speaks in. - http.Response.Headers[ResponsesEndpointRouteBuilderExtensions.StageHeaderName] = turn.Conversation.Stage; + // The headers leave before the turn ends, so this one names the stage the turn speaks in. + http.Response.Headers[ResponsesEndpointRouteBuilderExtensions.StageHeaderName] = turn.Conversation.Stage; - // One turn's worth of ids: the pairing dies with the stream. - ToolCallNames toolNames = new(); + // One turn's worth of ids: the pairing dies with the stream. + ToolCallNames toolNames = new(); - var updates = StreamAgentUpdatesAsync(http, turn, dialect, toolNames, cancellationToken); + IAsyncEnumerable updates = StreamAgentUpdatesAsync(http, turn, dialect, toolNames, cancellationToken); - await foreach (var frame in OpenAIResponses - .WriteResponseStreamAsync(updates, turn.ResponseId, turn.ConversationId, cancellationToken) - .ConfigureAwait(false)) - { - await http.Response.WriteAsync(frame, cancellationToken).ConfigureAwait(false); + await foreach (string? frame in OpenAIResponses + .WriteResponseStreamAsync(updates, turn.ResponseId, turn.ConversationId, cancellationToken) + .ConfigureAwait(false)) + { + await http.Response.WriteAsync(frame, cancellationToken).ConfigureAwait(false); - // Without this the reply arrives in one piece, which defeats the whole streaming path. - await http.Response.Body.FlushAsync(cancellationToken).ConfigureAwait(false); + // Without this the reply arrives in one piece, which defeats the whole streaming path. + await http.Response.Body.FlushAsync(cancellationToken).ConfigureAwait(false); + } + + await turn.FileAsync(cancellationToken).ConfigureAwait(false); } - await turn.FileAsync(cancellationToken).ConfigureAwait(false); - } + /// Runs one streaming turn on the conversation, wrapping each update with the agent's id. + /// + /// The framework converter sees every update untouched: it ignores the contents it + /// knows nothing of, so dialect lines duplicate nothing and pure streams lose nothing. + /// + private static async IAsyncEnumerable StreamAgentUpdatesAsync( + HttpContext http, + ResponsesTurn turn, + bool dialect, + ToolCallNames toolNames, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken) + { + TurnStreamFiles files = new(); - /// Runs one streaming turn on the conversation, wrapping each update with the agent's id. - /// - /// The framework converter sees every update untouched: it ignores the contents it - /// knows nothing of, so dialect lines duplicate nothing and pure streams lose nothing. - /// - private static async IAsyncEnumerable StreamAgentUpdatesAsync( - HttpContext http, - ResponsesTurn turn, - bool dialect, - ToolCallNames toolNames, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken) - { - TurnStreamFiles files = new(); + await foreach (ChatResponseUpdate? update in turn.Conversation + .RunTurnMessageStreamingAtOriginAsync(turn.Input, turn.Origin, cancellationToken) + .ConfigureAwait(false)) + { + if (dialect) + { + foreach (TurnStreamPart part in TurnStreamParts.From(update, toolNames)) + { + await WritePartLineAsync(http, part, cancellationToken).ConfigureAwait(false); + } + + files.Note(update); + } + + yield return new AgentResponseUpdate(update) { AgentId = turn.Agent.Id }; + } - await foreach (var update in turn.Conversation - .RunTurnMessageStreamingAtOriginAsync(turn.Input, turn.Origin, cancellationToken) - .ConfigureAwait(false)) - { if (dialect) { - foreach (var part in TurnStreamParts.From(update, toolNames)) + // The enumeration above ends only after the run has finished, and the publish tool ran + // inside it: by here the bytes are in the store or never will be. + Conversations conversations = http.RequestServices.GetRequiredService(); + + await foreach (TurnStreamFile? part in files.ResolveAsync(conversations, turn.Conversation.ConversationId, cancellationToken).ConfigureAwait(false)) { await WritePartLineAsync(http, part, cancellationToken).ConfigureAwait(false); } - - files.Note(update); } - - yield return new AgentResponseUpdate(update) { AgentId = turn.Agent.Id }; } - if (dialect) + /// Writes one dialect event: one agentcore_* member, bare. + private static async Task WritePartLineAsync( + HttpContext http, TurnStreamPart part, CancellationToken cancellationToken) { - // The enumeration above ends only after the run has finished, and the publish tool ran - // inside it: by here the bytes are in the store or never will be. - var conversations = http.RequestServices.GetRequiredService(); - - await foreach (var part in files.ResolveAsync(conversations, turn.Conversation.ConversationId, cancellationToken).ConfigureAwait(false)) + JsonObject line = part switch { - await WritePartLineAsync(http, part, cancellationToken).ConfigureAwait(false); - } + TurnStreamRender render + => new JsonObject { ["agentcore_data"] = JsonSerializer.SerializeToNode(render.Payload, ResponsesJson.Options) }, + TurnStreamSource source + => new JsonObject { ["agentcore_source"] = JsonSerializer.SerializeToNode(source.Payload, ResponsesJson.Options) }, + TurnStreamTool tool + => new JsonObject { ["agentcore_tool"] = JsonSerializer.SerializeToNode(tool.Payload, ResponsesJson.Options) }, + TurnStreamApproval approval + => new JsonObject { ["agentcore_approval"] = JsonSerializer.SerializeToNode(approval.Payload, ResponsesJson.Options) }, + TurnStreamFile file + => new JsonObject { ["agentcore_file"] = JsonSerializer.SerializeToNode(file.Payload, ResponsesJson.Options) }, + _ => throw new InvalidOperationException($"Unknown stream part: {part.GetType()}."), + }; + + await http.Response.WriteAsync("data: ", cancellationToken).ConfigureAwait(false); + await http.Response.WriteAsync(line.ToJsonString(), cancellationToken).ConfigureAwait(false); + await http.Response.WriteAsync("\n\n", cancellationToken).ConfigureAwait(false); + await http.Response.Body.FlushAsync(cancellationToken).ConfigureAwait(false); } } - - /// Writes one dialect event: one agentcore_* member, bare. - private static async Task WritePartLineAsync( - HttpContext http, TurnStreamPart part, CancellationToken cancellationToken) - { - JsonObject line = part switch - { - TurnStreamRender render - => new JsonObject { ["agentcore_data"] = JsonSerializer.SerializeToNode(render.Payload, ResponsesJson.Options) }, - TurnStreamSource source - => new JsonObject { ["agentcore_source"] = JsonSerializer.SerializeToNode(source.Payload, ResponsesJson.Options) }, - TurnStreamTool tool - => new JsonObject { ["agentcore_tool"] = JsonSerializer.SerializeToNode(tool.Payload, ResponsesJson.Options) }, - TurnStreamApproval approval - => new JsonObject { ["agentcore_approval"] = JsonSerializer.SerializeToNode(approval.Payload, ResponsesJson.Options) }, - TurnStreamFile file - => new JsonObject { ["agentcore_file"] = JsonSerializer.SerializeToNode(file.Payload, ResponsesJson.Options) }, - _ => throw new InvalidOperationException($"Unknown stream part: {part.GetType()}."), - }; - - await http.Response.WriteAsync("data: ", cancellationToken).ConfigureAwait(false); - await http.Response.WriteAsync(line.ToJsonString(), cancellationToken).ConfigureAwait(false); - await http.Response.WriteAsync("\n\n", cancellationToken).ConfigureAwait(false); - await http.Response.Body.FlushAsync(cancellationToken).ConfigureAwait(false); - } } diff --git a/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs b/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs index 0a13c50e..addb2dd7 100644 --- a/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs +++ b/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs @@ -2,52 +2,54 @@ using System.Runtime.CompilerServices; using AgentCore.Application.Conversation; using Microsoft.Extensions.AI; +using AgentCore.Application.Blobs; -namespace AgentCore.AspNetCore.Endpoints; - -/// -/// The files one turn published, linked for the browser once the turn is over. -/// -internal sealed class TurnStreamFiles +namespace AgentCore.AspNetCore.Endpoints { - private readonly List _files = []; - - /// Notes every published file one update carries. - /// One update of the stream. - internal void Note(ChatResponseUpdate update) + /// + /// The files one turn published, linked for the browser once the turn is over. + /// + internal sealed class TurnStreamFiles { - _files.AddRange(update.Contents.OfType()); - } + private readonly List _files = []; - /// Links every noted file the store kept, in the order they were noted. - /// The door to the stored conversation. - /// The conversation that owns the files. - /// Cancels the lookups. - /// One part for each file the store holds. - internal async IAsyncEnumerable ResolveAsync( - Conversations conversations, - string conversationId, - [EnumeratorCancellation] CancellationToken cancellationToken) - { - if (_files.Count == 0) + /// Notes every published file one update carries. + /// One update of the stream. + internal void Note(ChatResponseUpdate update) { - yield break; + _files.AddRange(update.Contents.OfType()); } - var links = await conversations - .LinkFilesAsync(conversationId, [new ChatMessage(ChatRole.Assistant, [.. _files])], cancellationToken) - .ConfigureAwait(false); - - foreach (var (blob, url) in links) + /// Links every noted file the store kept, in the order they were noted. + /// The door to the stored conversation. + /// The conversation that owns the files. + /// Cancels the lookups. + /// One part for each file the store holds. + internal async IAsyncEnumerable ResolveAsync( + Conversations conversations, + string conversationId, + [EnumeratorCancellation] CancellationToken cancellationToken) { - yield return new TurnStreamFile(new FilePayload + if (_files.Count == 0) + { + yield break; + } + + IReadOnlyList links = await conversations + .LinkFilesAsync(conversationId, [new ChatMessage(ChatRole.Assistant, [.. _files])], cancellationToken) + .ConfigureAwait(false); + + foreach ((BlobRef? blob, Uri? url) in links) { - Name = blob.Name, - Title = _files.LastOrDefault(file => string.Equals(file.Name, blob.Name, StringComparison.Ordinal))?.Title, - MediaType = blob.MediaType, - Length = blob.Length, - Url = url?.ToString(), - }); + yield return new TurnStreamFile(new FilePayload + { + Name = blob.Name, + Title = _files.LastOrDefault(file => string.Equals(file.Name, blob.Name, StringComparison.Ordinal))?.Title, + MediaType = blob.MediaType, + Length = blob.Length, + Url = url?.ToString(), + }); + } } } } diff --git a/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs b/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs index 78b77a3f..915e369a 100644 --- a/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs +++ b/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs @@ -4,138 +4,145 @@ using AgentCore.Domain.Sources; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Endpoints; - -/// -/// The non-text parts of one streaming update, read once for every text endpoint. -/// -/// -/// A drawing, a citation, a tool half, and an approval ask ride ChatResponseUpdate -/// contents that no OpenAI shape carries. Each endpoint frames them its own way, but what -/// they mean — and what the browser reads — is one mapping, kept here so a new content -/// kind lands in one place. Text stays endpoint-side: completions deltas it, Responses -/// leaves it to the framework converter. -/// -internal static class TurnStreamParts +namespace AgentCore.AspNetCore.Endpoints { - /// Reads one update's browser parts, in wire order: renders, sources, tools, approvals. - /// One update of the stream. - /// The pairing of call id to tool name for this turn, written and read here. - /// One part for each browser payload the update carries, possibly none. - internal static IEnumerable From(ChatResponseUpdate update, ToolCallNames toolNames) + /// + /// The non-text parts of one streaming update, read once for every text endpoint. + /// + /// + /// A drawing, a citation, a tool half, and an approval ask ride ChatResponseUpdate + /// contents that no OpenAI shape carries. Each endpoint frames them its own way, but what + /// they mean — and what the browser reads — is one mapping, kept here so a new content + /// kind lands in one place. Text stays endpoint-side: completions deltas it, Responses + /// leaves it to the framework converter. + /// + internal static class TurnStreamParts { - foreach (var drawn in update.Contents.OfType()) + /// Reads one update's browser parts, in wire order: renders, sources, tools, approvals. + /// One update of the stream. + /// The pairing of call id to tool name for this turn, written and read here. + /// One part for each browser payload the update carries, possibly none. + internal static IEnumerable From(ChatResponseUpdate update, ToolCallNames toolNames) { - yield return new TurnStreamRender(new RenderedPayload { Name = drawn.Name, Data = drawn.Data }); - } + foreach (RenderContent drawn in update.Contents.OfType()) + { + yield return new TurnStreamRender(new RenderedPayload { Name = drawn.Name, Data = drawn.Data }); + } - foreach (var cited in update.Contents.OfType()) - { - yield return new TurnStreamSource(SourcePayloadOf(cited)); - } + foreach (SourceContent cited in update.Contents.OfType()) + { + yield return new TurnStreamSource(SourcePayloadOf(cited)); + } - foreach (var tool in ToolPayloadsOf(update, toolNames)) - { - yield return new TurnStreamTool(tool); + foreach (ToolPayload tool in ToolPayloadsOf(update, toolNames)) + { + yield return new TurnStreamTool(tool); + } + + foreach (ToolApprovalRequestContent asked in update.Contents.OfType()) + { + // A request arrives with no text, so without this the update falls into the + // empty-text skip below and the caller never learns a tool waits on them. + if (asked.ToolCall is FunctionCallContent call) + { + yield return new TurnStreamApproval(new ApprovalPayload + { + RequestId = asked.RequestId, + Tool = call.Name, + Arguments = ArgumentsOf(call), + }); + } + } } - foreach (var asked in update.Contents.OfType()) + /// Reads the tool facts one update carries, in the order they appear on it. + private static IEnumerable ToolPayloadsOf( + ChatResponseUpdate update, + ToolCallNames toolNames) { - // A request arrives with no text, so without this the update falls into the - // empty-text skip below and the caller never learns a tool waits on them. - if (asked.ToolCall is FunctionCallContent call) + foreach (AIContent content in update.Contents) { - yield return new TurnStreamApproval(new ApprovalPayload + switch (content) { - RequestId = asked.RequestId, - Tool = call.Name, - Arguments = ArgumentsOf(call), - }); + case FunctionCallContent call: + toolNames.Called(call); + yield return new ToolPayload + { + CallId = call.CallId, + Name = call.Name, + Phase = "call", + Arguments = ArgumentsOf(call), + }; + break; + + case FunctionResultContent result: + // The answer has no declared shape, so it goes through the one reader that knows + // every shape it arrives in. Reading it twice would let the two disagree. + JsonNode? answer = ToolResultJson.ToNode(result.Result); + yield return new ToolPayload + { + CallId = result.CallId, + // A result that arrives with no call before it should not be possible, and + // naming it after its id beats naming it nothing if it ever is. + Name = toolNames.Of(result) ?? result.CallId, + Phase = "result", + Result = ResultOf(result, answer), + Failed = result.Exception is not null || ToolErrorResult.IsError(answer), + }; + break; + + default: + break; + } } } - } - /// Reads the tool facts one update carries, in the order they appear on it. - private static IEnumerable ToolPayloadsOf( - ChatResponseUpdate update, - ToolCallNames toolNames) - { - foreach (var content in update.Contents) + /// Reads one cited source into what the browser receives. + private static SourcePayload SourcePayloadOf(SourceContent cited) { - switch (content) + return new() { - case FunctionCallContent call: - toolNames.Called(call); - yield return new ToolPayload - { - CallId = call.CallId, - Name = call.Name, - Phase = "call", - Arguments = ArgumentsOf(call), - }; - break; - - case FunctionResultContent result: - // The answer has no declared shape, so it goes through the one reader that knows - // every shape it arrives in. Reading it twice would let the two disagree. - var answer = ToolResultJson.ToNode(result.Result); - yield return new ToolPayload - { - CallId = result.CallId, - // A result that arrives with no call before it should not be possible, and - // naming it after its id beats naming it nothing if it ever is. - Name = toolNames.Of(result) ?? result.CallId, - Phase = "result", - Result = ResultOf(result, answer), - Failed = result.Exception is not null || ToolErrorResult.IsError(answer), - }; - break; - - default: - break; - } + CallId = cited.CallId, + Id = cited.Source.SourceId, + SourceType = cited.Source.Kind == SourceKind.Url ? "url" : "document", + Title = cited.Source.Title, + Locator = cited.Source.Locator, + Url = cited.Source.Url, + MediaType = cited.Source.MediaType, + Origin = cited.Source.Origin, + }; } - } - /// Reads one cited source into what the browser receives. - private static SourcePayload SourcePayloadOf(SourceContent cited) - => new() + /// Reads what the model passed to one tool, or when it passed nothing. + private static JsonObject? ArgumentsOf(FunctionCallContent call) { - CallId = cited.CallId, - Id = cited.Source.SourceId, - SourceType = cited.Source.Kind == SourceKind.Url ? "url" : "document", - Title = cited.Source.Title, - Locator = cited.Source.Locator, - Url = cited.Source.Url, - MediaType = cited.Source.MediaType, - Origin = cited.Source.Origin, - }; - - /// Reads what the model passed to one tool, or when it passed nothing. - private static JsonObject? ArgumentsOf(FunctionCallContent call) - => call.Arguments is { Count: > 0 } arguments ? ToolArgumentJson.ToJsonObject(arguments) : null; - - /// Reads what one tool answered, as the browser receives it. - private static JsonNode? ResultOf(FunctionResultContent result, JsonNode? answer) - => result.Exception is { } failure - ? JsonValue.Create(failure.GetType().Name + ": " + failure.Message) - : answer; -} + return call.Arguments is { Count: > 0 } arguments ? ToolArgumentJson.ToJsonObject(arguments) : null; + } -/// One browser payload of a streaming update. -internal abstract record TurnStreamPart; + /// Reads what one tool answered, as the browser receives it. + private static JsonNode? ResultOf(FunctionResultContent result, JsonNode? answer) + { + return result.Exception is { } failure + ? JsonValue.Create(failure.GetType().Name + ": " + failure.Message) + : answer; + } + } + + /// One browser payload of a streaming update. + internal abstract record TurnStreamPart; -/// One thing a chunk asks the browser to draw. -internal sealed record TurnStreamRender(RenderedPayload Payload) : TurnStreamPart; + /// One thing a chunk asks the browser to draw. + internal sealed record TurnStreamRender(RenderedPayload Payload) : TurnStreamPart; -/// Where one answer came from, as the browser reads it. -internal sealed record TurnStreamSource(SourcePayload Payload) : TurnStreamPart; + /// Where one answer came from, as the browser reads it. + internal sealed record TurnStreamSource(SourcePayload Payload) : TurnStreamPart; -/// One half of one tool call, as the browser reads it. -internal sealed record TurnStreamTool(ToolPayload Payload) : TurnStreamPart; + /// One half of one tool call, as the browser reads it. + internal sealed record TurnStreamTool(ToolPayload Payload) : TurnStreamPart; -/// One tool call waiting on the caller, as the browser reads it. -internal sealed record TurnStreamApproval(ApprovalPayload Payload) : TurnStreamPart; + /// One tool call waiting on the caller, as the browser reads it. + internal sealed record TurnStreamApproval(ApprovalPayload Payload) : TurnStreamPart; -/// One file the turn produced, as the browser reads it. -internal sealed record TurnStreamFile(FilePayload Payload) : TurnStreamPart; + /// One file the turn produced, as the browser reads it. + internal sealed record TurnStreamFile(FilePayload Payload) : TurnStreamPart; +} diff --git a/src/AgentCore.AspNetCore/Sessions/AgentCoreAgentSessionStore.cs b/src/AgentCore.AspNetCore/Sessions/AgentCoreAgentSessionStore.cs index 9e906baf..d2ee08f9 100644 --- a/src/AgentCore.AspNetCore/Sessions/AgentCoreAgentSessionStore.cs +++ b/src/AgentCore.AspNetCore/Sessions/AgentCoreAgentSessionStore.cs @@ -1,76 +1,75 @@ +using System.Text.Json; using AgentCore.Application.Ports; using Microsoft.Agents.AI; using Microsoft.Agents.AI.Hosting; -namespace AgentCore.AspNetCore.Sessions; - -/// -/// The framework's session seam over the continuation map that lives in the conversation store. -/// -public sealed class AgentCoreAgentSessionStore : AgentSessionStore +namespace AgentCore.AspNetCore.Sessions { - private readonly IConversationStore _conversations; - - /// Creates the seam over one conversation store. - /// The store the continuation ids open onto. - /// The store is . - public AgentCoreAgentSessionStore(IConversationStore conversations) + /// + /// The framework's session seam over the continuation map that lives in the conversation store. + /// + public sealed class AgentCoreAgentSessionStore : AgentSessionStore { - ArgumentNullException.ThrowIfNull(conversations); - _conversations = conversations; - } + private readonly IConversationStore _conversations; - /// Reads whether anything is filed under one continuation id. - /// The conversation id or response id to look up. - /// Cancels the read. - /// when a later load would find an envelope. - public async ValueTask ContainsAsync(string sessionStoreId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(sessionStoreId); + /// Creates the seam over one conversation store. + /// The store the continuation ids open onto. + /// The store is . + public AgentCoreAgentSessionStore(IConversationStore conversations) + { + ArgumentNullException.ThrowIfNull(conversations); + _conversations = conversations; + } - return await _conversations.GetContinuationAsync(sessionStoreId, cancellationToken).ConfigureAwait(false) - is not null; - } + /// Reads whether anything is filed under one continuation id. + /// The conversation id or response id to look up. + /// Cancels the read. + /// when a later load would find an envelope. + public async ValueTask ContainsAsync(string sessionStoreId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(sessionStoreId); - /// - public override async ValueTask SaveSessionAsync( - AIAgent agent, string sessionStoreId, AgentSession session, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(sessionStoreId); - ArgumentNullException.ThrowIfNull(session); + return await _conversations.GetContinuationAsync(sessionStoreId, cancellationToken).ConfigureAwait(false) + is not null; + } - var envelope = await agent - .SerializeSessionAsync(session, cancellationToken: cancellationToken) - .ConfigureAwait(false); - await _conversations.SaveContinuationAsync(sessionStoreId, envelope, cancellationToken).ConfigureAwait(false); - } + /// + public override async ValueTask SaveSessionAsync( + AIAgent agent, string sessionStoreId, AgentSession session, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(sessionStoreId); + ArgumentNullException.ThrowIfNull(session); - /// - public override async ValueTask GetSessionAsync( - AIAgent agent, string sessionStoreId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(sessionStoreId); + JsonElement envelope = await agent + .SerializeSessionAsync(session, cancellationToken: cancellationToken) + .ConfigureAwait(false); + await _conversations.SaveContinuationAsync(sessionStoreId, envelope, cancellationToken).ConfigureAwait(false); + } - var envelope = await _conversations.GetContinuationAsync(sessionStoreId, cancellationToken).ConfigureAwait(false); - if (envelope is null) + /// + public override async ValueTask GetSessionAsync( + AIAgent agent, string sessionStoreId, CancellationToken cancellationToken = default) { - return await agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false); - } + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(sessionStoreId); - return await agent - .DeserializeSessionAsync(envelope.Value, cancellationToken: cancellationToken) - .ConfigureAwait(false); - } + JsonElement? envelope = await _conversations.GetContinuationAsync(sessionStoreId, cancellationToken).ConfigureAwait(false); + return envelope is null + ? await agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false) + : await agent + .DeserializeSessionAsync(envelope.Value, cancellationToken: cancellationToken) + .ConfigureAwait(false); + } - /// - public override ValueTask DeleteSessionAsync( - AIAgent agent, string sessionStoreId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(agent); - ArgumentNullException.ThrowIfNull(sessionStoreId); + /// + public override ValueTask DeleteSessionAsync( + AIAgent agent, string sessionStoreId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(agent); + ArgumentNullException.ThrowIfNull(sessionStoreId); - return _conversations.DeleteContinuationAsync(sessionStoreId, cancellationToken); + return _conversations.DeleteContinuationAsync(sessionStoreId, cancellationToken); + } } } diff --git a/src/AgentCore.AspNetCore/Sessions/ConversationSessionSweeper.cs b/src/AgentCore.AspNetCore/Sessions/ConversationSessionSweeper.cs index 053793a6..bea3aea4 100644 --- a/src/AgentCore.AspNetCore/Sessions/ConversationSessionSweeper.cs +++ b/src/AgentCore.AspNetCore/Sessions/ConversationSessionSweeper.cs @@ -3,72 +3,74 @@ using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; +using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.Sessions; - -/// -/// Runs the idle sweep of every for as long as the host is up. -/// -internal sealed class ConversationSessionSweeper( - IServiceProvider services, TimeProvider timeProvider, ILogger logger) : BackgroundService +namespace AgentCore.AspNetCore.Sessions { - /// How often the sweep runs. - private static readonly TimeSpan Interval = TimeSpan.FromMinutes(5); - - /// - protected override async Task ExecuteAsync(CancellationToken stoppingToken) + /// + /// Runs the idle sweep of every for as long as the host is up. + /// + internal sealed class ConversationSessionSweeper( + IServiceProvider services, TimeProvider timeProvider, ILogger logger) : BackgroundService { - var entries = services.GetRequiredService(); + /// How often the sweep runs. + private static readonly TimeSpan Interval = TimeSpan.FromMinutes(5); - using PeriodicTimer timer = new(Interval, timeProvider); - - while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false)) + /// + protected override async Task ExecuteAsync(CancellationToken stoppingToken) { - // A sweep that throws must not end the loop: the sessions it could not close are still - // held, and the next tick is the only thing that will try them again. - try + EntryRegistry entries = services.GetRequiredService(); + + using PeriodicTimer timer = new(Interval, timeProvider); + + while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false)) { - List? faults = null; - foreach (var store in entries.ConversationSessions.Values) + // A sweep that throws must not end the loop: the sessions it could not close are still + // held, and the next tick is the only thing that will try them again. + try { - if (store is not InMemoryConversationSessions memory) + List? faults = null; + foreach (IConversationSessions store in entries.ConversationSessions.Values) { - continue; - } + if (store is not InMemoryConversationSessions memory) + { + continue; + } - try - { - await memory.SweepAsync(stoppingToken).ConfigureAwait(false); + try + { + await memory.SweepAsync(stoppingToken).ConfigureAwait(false); + } + catch (Exception fault) when (fault is not OperationCanceledException) + { + faults ??= []; + faults.Add(fault); + } } - catch (Exception fault) when (fault is not OperationCanceledException) + + if (faults is { Count: > 0 }) { - faults ??= []; - faults.Add(fault); + throw new AggregateException(faults); } } - - if (faults is { Count: > 0 }) + catch (Exception fault) when (fault is not OperationCanceledException) { - throw new AggregateException(faults); + ConversationSessionSweeperLog.SweepFaulted(logger, fault); } } - catch (Exception fault) when (fault is not OperationCanceledException) - { - ConversationSessionSweeperLog.SweepFaulted(logger, fault); - } } } -} -/// Every line the idle sweep writes. -internal static partial class ConversationSessionSweeperLog -{ - /// A sweep could not end one or more of the sessions it visited. - /// The logger of the sweeper. - /// The cause, or the causes of a sweep that met more than one. - [LoggerMessage( - EventId = 1, - Level = LogLevel.Error, - Message = "the idle sweep could not end every session it visited, so those sessions are still held.")] - public static partial void SweepFaulted(ILogger logger, Exception exception); + /// Every line the idle sweep writes. + internal static partial class ConversationSessionSweeperLog + { + /// A sweep could not end one or more of the sessions it visited. + /// The logger of the sweeper. + /// The cause, or the causes of a sweep that met more than one. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Error, + Message = "the idle sweep could not end every session it visited, so those sessions are still held.")] + public static partial void SweepFaulted(ILogger logger, Exception exception); + } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConnection.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConnection.cs index 6f5f8157..7fcc6bc8 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConnection.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConnection.cs @@ -13,942 +13,963 @@ using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// One socket, one conversation. -/// -/// -/// -/// Three tasks run for the life of the socket. The read loop parses frames and never waits for a -/// turn, because a turn that blocked the loop would make the interrupt frame unreachable -/// and barge-in impossible. The write loop is the only caller of -/// , -/// because a WebSocket supports exactly one send at a time. The turn task streams the reply into -/// the write channel. -/// -/// -/// All three read one connection-scoped token, cancelled once for any reason the socket is going -/// away: the request aborted, the host is stopping, or one of the three tasks itself ended. -/// Nothing here waits on HttpContext.RequestAborted once teardown starts, because ASP.NET -/// Core recycles the context once the response completes and that token can then throw or name a -/// later request. -/// -/// -/// The adapter owns the vendor schema and the core does not, so D8 holds: this class translates -/// frames onto and nothing else. -/// -/// -/// One object fills both halves of the conversation's , because one socket -/// carries both directions for this vendor. Nothing above the ports can tell, and nothing may ask. -/// The speaking side is below: every reply reaches the write loop -/// through . The last of the two barge-in gates is this class's business -/// and nobody else's — speaks in turn ids and never hands one over, -/// so this class keeps a monotonic reply generation instead, stamps every item it queues with the -/// generation it was queued under, and raises that generation in . The write -/// loop then drops any item at or below the raised one, which is the same comparison the turn ids -/// used to answer, asked in the transport's own vocabulary. -/// -/// -/// One narrowing comes with that seam, and it is written down rather than hidden: a fragment the -/// arbiter had already decided to speak, but which only reaches after -/// raised the generation, is stamped with the new one and reaches the -/// caller. A port carries no reply identity to tell that fragment from the first fragment of the -/// next reply, and the window is the few instructions between the arbiter's own check and that conversation. -/// -/// -internal sealed class TelnyxRelayConnection : IConversationInputPort, IConversationOutputPort +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - private readonly TelnyxRelayOptions _options; + /// + /// One socket, one conversation. + /// + /// + /// + /// Three tasks run for the life of the socket. The read loop parses frames and never waits for a + /// turn, because a turn that blocked the loop would make the interrupt frame unreachable + /// and barge-in impossible. The write loop is the only caller of + /// , + /// because a WebSocket supports exactly one send at a time. The turn task streams the reply into + /// the write channel. + /// + /// + /// All three read one connection-scoped token, cancelled once for any reason the socket is going + /// away: the request aborted, the host is stopping, or one of the three tasks itself ended. + /// Nothing here waits on HttpContext.RequestAborted once teardown starts, because ASP.NET + /// Core recycles the context once the response completes and that token can then throw or name a + /// later request. + /// + /// + /// The adapter owns the vendor schema and the core does not, so D8 holds: this class translates + /// frames onto and nothing else. + /// + /// + /// One object fills both halves of the conversation's , because one socket + /// carries both directions for this vendor. Nothing above the ports can tell, and nothing may ask. + /// The speaking side is below: every reply reaches the write loop + /// through . The last of the two barge-in gates is this class's business + /// and nobody else's — speaks in turn ids and never hands one over, + /// so this class keeps a monotonic reply generation instead, stamps every item it queues with the + /// generation it was queued under, and raises that generation in . The write + /// loop then drops any item at or below the raised one, which is the same comparison the turn ids + /// used to answer, asked in the transport's own vocabulary. + /// + /// + /// One narrowing comes with that seam, and it is written down rather than hidden: a fragment the + /// arbiter had already decided to speak, but which only reaches after + /// raised the generation, is stamped with the new one and reaches the + /// caller. A port carries no reply identity to tell that fragment from the first fragment of the + /// next reply, and the window is the few instructions between the arbiter's own check and that conversation. + /// + /// + internal sealed class TelnyxRelayConnection : IConversationInputPort, IConversationOutputPort + { + private readonly TelnyxRelayOptions _options; - private readonly ILogger _logger; + private readonly ILogger _logger; - private readonly Channel _outbound; + private readonly Channel _outbound; - private readonly CancellationTokenSource _cancellation; + private readonly CancellationTokenSource _cancellation; - // The same token every loop reads, captured once. Read off the field and never off - // _cancellation.Token by anything that can outlive teardown: RunAsync disposes that source on - // its way out, and a disposed source's Token getter throws, while the struct captured here goes - // on answering "already cancelled" for as long as anyone holds it. - private readonly CancellationToken _connectionToken; + // The same token every loop reads, captured once. Read off the field and never off + // _cancellation.Token by anything that can outlive teardown: RunAsync disposes that source on + // its way out, and a disposed source's Token getter throws, while the struct captured here goes + // on answering "already cancelled" for as long as anyone holds it. + private readonly CancellationToken _connectionToken; - private readonly IHostApplicationLifetime _lifetime; + private readonly IHostApplicationLifetime _lifetime; - private readonly ConnectionTaskObserver _observer; + private readonly ConnectionTaskObserver _observer; - private readonly JsonWebSocketPump _pump; + private readonly JsonWebSocketPump _pump; - // The last of the two barge-in gates, in this connection's own vocabulary. SpeakAsync stamps - // every item it queues with this counter plus one and StopAsync raises the counter itself when a - // barge-in stops the reply; the write loop then drops anything at or below it. It lives on the - // connection, alongside the channel the write loop reads, because the write loop is the one that - // reads it and a second setup frame must not reset what a barge-in already cut off. - private long _replyGeneration; + // The last of the two barge-in gates, in this connection's own vocabulary. SpeakAsync stamps + // every item it queues with this counter plus one and StopAsync raises the counter itself when a + // barge-in stops the reply; the write loop then drops anything at or below it. It lives on the + // connection, alongside the channel the write loop reads, because the write loop is the one that + // reads it and a second setup frame must not reset what a barge-in already cut off. + private long _replyGeneration; - // Zero until something takes the inbound stream, and one afterwards, forever. ListenAsync - // promises one consumer for the life of the port, and this is what a second call trips over. - private int _listening; + // Zero until something takes the inbound stream, and one afterwards, forever. ListenAsync + // promises one consumer for the life of the port, and this is what a second call trips over. + private int _listening; - private volatile ConversationSession? _session; + private volatile ConversationSession? _session; - // Resolved once per socket from the stamped entry, then cached: every session open, touch, - // and close on this connection answers on the same entry. - private volatile IConversationSessions? _entrySessions; + // Resolved once per socket from the stamped entry, then cached: every session open, touch, + // and close on this connection answers on the same entry. + private volatile IConversationSessions? _entrySessions; - private const string BeforeSetupConversationId = "(before setup)"; + private const string BeforeSetupConversationId = "(before setup)"; - // volatile for the same reason _session is: the read loop assigns it when the setup frame - // arrives, and teardown reads it from another task to find the last turn. - private volatile ConversationTurnArbiter? _arbiter; + // volatile for the same reason _session is: the read loop assigns it when the setup frame + // arrives, and teardown reads it from another task to find the last turn. + private volatile ConversationTurnArbiter? _arbiter; - private bool _loggedPromptBeforeSetup; + private bool _loggedPromptBeforeSetup; - private bool _loggedMalformedInterrupt; + private bool _loggedMalformedInterrupt; - private bool _loggedSecondSetup; + private bool _loggedSecondSetup; - /// Reads this socket's entry session store, resolved once from the URL's entry. - /// The store for the entry the URL named. - private IConversationSessions EntrySessions() - => _entrySessions - ?? throw new InvalidOperationException("This socket resolved no session store."); + /// Reads this socket's entry session store, resolved once from the URL's entry. + /// The store for the entry the URL named. + private IConversationSessions EntrySessions() + { + return _entrySessions + ?? throw new InvalidOperationException("This socket resolved no session store."); + } - private TelnyxRelayConnection(HttpContext http, WebSocket socket, TelnyxRelayOptions options, ILogger logger) - { - _options = options; - - _logger = logger; - - // A dropped socket ends this conversation, and so does the host shutting down. Both stop the read - // loop, the write loop, and any turn the same way, through the one token everything below - // reads. IHostApplicationLifetime is resolved here, from the request's own provider, and - // never at MapTelnyxRelay time: nothing is bound to it until a conversation actually arrives. - _lifetime = http.RequestServices.GetRequiredService(); - - _cancellation = CancellationTokenSource.CreateLinkedTokenSource( - http.RequestAborted, - _lifetime.ApplicationStopping); - - _connectionToken = _cancellation.Token; - - // AddAgentCore registers this from options.TimeProvider, or TimeProvider.System when the - // host bound none — the same clock ConversationSessionFactory already reads for conversationDurationSeconds. - // Resolving it here, rather than reading TimeProvider.System directly, is what lets a test - // own the idle deadline below by binding that one option. - var timeProvider = http.RequestServices.GetRequiredService(); - - // Bounded, so a slow relay slows the turn loop instead of growing a queue without a bound. - _outbound = Channel.CreateBounded(new BoundedChannelOptions(256) + private TelnyxRelayConnection(HttpContext http, WebSocket socket, TelnyxRelayOptions options, ILogger logger) { - FullMode = BoundedChannelFullMode.Wait, - SingleReader = true, - SingleWriter = false, - }); - - // The observer is vendor-free, so the two faults that are the relay's own doing reach it - // through ClassifyTelnyxFault rather than through a catch clause of its own. The conversation id is - // a function because the session only exists once the setup frame has arrived, which is - // after this constructor and after some of the lines the observer logs. - _observer = new ConnectionTaskObserver( - () => _session?.ConversationId ?? BeforeSetupConversationId, - (conversationId, taskName) => TelnyxRelayLog.TeardownTimedOut(_logger, conversationId, taskName), - (kind, conversationId, fault) => LogFault(kind, conversationId, fault), - ClassifyTelnyxFault); - - // The pump owns the socket from here on: the read loop, the write loop, and the one close - // this connection makes are all its, and none of the three names a vendor. The three seams - // that would have are the delegates below — the exception the pump raises when the relay - // breaks the contract, so DetermineCloseStatus still recognises it off the read loop's own - // task, and the three log lines that name the relay by name. Each log callback closes over - // _session for the same reason the observer's own conversationId does: the id only exists once the - // setup frame has arrived, which is after this constructor. - _pump = new JsonWebSocketPump( - socket, - new JsonWebSocketPumpOptions( - _options.MaxFrameBytes, - _options.IdleTimeout, - _options.CloseTimeout, - (status, message) => new RelayProtocolException(status, message), - frameType => TelnyxRelayLog.UnknownFrameType(_logger, frameType, _session?.ConversationId ?? BeforeSetupConversationId), - frameType => TelnyxRelayLog.FrameBodyRefused(_logger, frameType, _session?.ConversationId ?? BeforeSetupConversationId), - () => TelnyxRelayLog.IdleTimeoutReached(_logger, _session?.ConversationId ?? BeforeSetupConversationId)), - timeProvider, - _connectionToken); - } + _options = options; - /// Runs one conversation to its end. - /// The request that carried the handshake. - /// The accepted socket. - /// What the endpoint may do. - /// A task that completes when the socket is closed. - public static Task RunAsync(HttpContext http, WebSocket socket, TelnyxRelayOptions options) - { - ArgumentNullException.ThrowIfNull(http); - ArgumentNullException.ThrowIfNull(socket); - ArgumentNullException.ThrowIfNull(options); + _logger = logger; - var logger = http.RequestServices - .GetRequiredService() - .CreateLogger("AgentCore.TelnyxRelay"); + // A dropped socket ends this conversation, and so does the host shutting down. Both stop the read + // loop, the write loop, and any turn the same way, through the one token everything below + // reads. IHostApplicationLifetime is resolved here, from the request's own provider, and + // never at MapTelnyxRelay time: nothing is bound to it until a conversation actually arrives. + _lifetime = http.RequestServices.GetRequiredService(); - TelnyxRelayConnection connection = new(http, socket, options, logger); - connection._entrySessions = http.RequestServices - .GetRequiredService() - .Entries.ForSessions(ConversationEndpointRouteBuilderExtensions.EntryOf(http)); + _cancellation = CancellationTokenSource.CreateLinkedTokenSource( + http.RequestAborted, + _lifetime.ApplicationStopping); - return connection.RunAsync(); - } + _connectionToken = _cancellation.Token; - private async Task RunAsync() - { - // Both loops belong to the pump, and both seams into this class are named methods rather - // than bodies: ParseFrame is the vendor's own reader, and DispatchAsync is what one parsed - // frame means to this conversation. The cast is safe because ParseFrame is the only thing that ever - // puts a frame into a FrameOutcome, and it only ever puts a RelayFrame there. - var reading = _pump.ReadLoopAsync(ParseFrame, frame => DispatchAsync((RelayFrame)frame)); - var writing = _pump.WriteLoopAsync(_outbound.Reader, EncodeOutbound); - - try + // AddAgentCore registers this from options.TimeProvider, or TimeProvider.System when the + // host bound none — the same clock ConversationSessionFactory already reads for conversationDurationSeconds. + // Resolving it here, rather than reading TimeProvider.System directly, is what lets a test + // own the idle deadline below by binding that one option. + TimeProvider timeProvider = http.RequestServices.GetRequiredService(); + + // Bounded, so a slow relay slows the turn loop instead of growing a queue without a bound. + _outbound = Channel.CreateBounded(new BoundedChannelOptions(256) + { + FullMode = BoundedChannelFullMode.Wait, + SingleReader = true, + SingleWriter = false, + }); + + // The observer is vendor-free, so the two faults that are the relay's own doing reach it + // through ClassifyTelnyxFault rather than through a catch clause of its own. The conversation id is + // a function because the session only exists once the setup frame has arrived, which is + // after this constructor and after some of the lines the observer logs. + _observer = new ConnectionTaskObserver( + () => _session?.ConversationId ?? BeforeSetupConversationId, + (conversationId, taskName) => TelnyxRelayLog.TeardownTimedOut(_logger, conversationId, taskName), + LogFault, + ClassifyTelnyxFault); + + // The pump owns the socket from here on: the read loop, the write loop, and the one close + // this connection makes are all its, and none of the three names a vendor. The three seams + // that would have are the delegates below — the exception the pump raises when the relay + // breaks the contract, so DetermineCloseStatus still recognises it off the read loop's own + // task, and the three log lines that name the relay by name. Each log callback closes over + // _session for the same reason the observer's own conversationId does: the id only exists once the + // setup frame has arrived, which is after this constructor. + _pump = new JsonWebSocketPump( + socket, + new JsonWebSocketPumpOptions( + _options.MaxFrameBytes, + _options.IdleTimeout, + _options.CloseTimeout, + (status, message) => new RelayProtocolException(status, message), + frameType => TelnyxRelayLog.UnknownFrameType(_logger, frameType, _session?.ConversationId ?? BeforeSetupConversationId), + frameType => TelnyxRelayLog.FrameBodyRefused(_logger, frameType, _session?.ConversationId ?? BeforeSetupConversationId), + () => TelnyxRelayLog.IdleTimeoutReached(_logger, _session?.ConversationId ?? BeforeSetupConversationId)), + timeProvider, + _connectionToken); + } + + /// Runs one conversation to its end. + /// The request that carried the handshake. + /// The accepted socket. + /// What the endpoint may do. + /// A task that completes when the socket is closed. + public static Task RunAsync(HttpContext http, WebSocket socket, TelnyxRelayOptions options) { - await Task.WhenAny(reading, writing).ConfigureAwait(false); + ArgumentNullException.ThrowIfNull(http); + ArgumentNullException.ThrowIfNull(socket); + ArgumentNullException.ThrowIfNull(options); + + ILogger logger = http.RequestServices + .GetRequiredService() + .CreateLogger("AgentCore.TelnyxRelay"); + + TelnyxRelayConnection connection = new(http, socket, options, logger) + { + _entrySessions = http.RequestServices + .GetRequiredService() + .Entries.ForSessions(ConversationEndpointRouteBuilderExtensions.EntryOf(http)) + }; + + return connection.RunAsync(); } - finally + + private async Task RunAsync() { - // The disposal below must run on every exit from here down, including a throw out of - // Cancel() itself or IConversationSessions.CloseAsync: _cancellation links to ApplicationStopping, - // which lives for the whole process, and only Dispose() releases that registration. + // Both loops belong to the pump, and both seams into this class are named methods rather + // than bodies: ParseFrame is the vendor's own reader, and DispatchAsync is what one parsed + // frame means to this conversation. The cast is safe because ParseFrame is the only thing that ever + // puts a frame into a FrameOutcome, and it only ever puts a RelayFrame there. + Task reading = _pump.ReadLoopAsync(ParseFrame, frame => DispatchAsync((RelayFrame)frame)); + Task writing = _pump.WriteLoopAsync(_outbound.Reader, EncodeOutbound); + try { - // One of the two loops just ended, for whatever reason, so the socket is going - // away. Cancelling here stops the other loop's wait and any turn still streaming, - // rather than leaving them to read a recycled HttpContext.RequestAborted after this - // method returns. Cancel() itself is guarded: it runs with throwOnFirstException: - // false, so every callback still runs and both loops are already cancelled before a - // callback fault can reach this catch, and losing the rest of teardown below would - // otherwise strand this conversation in the store for the life of the process. - try - { - await _cancellation.CancelAsync().ConfigureAwait(false); - } - catch (Exception fault) - { - ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.CancellationFaulted( - _logger, - _session?.ConversationId ?? BeforeSetupConversationId, - fault)); - } - - // The read loop must actually finish — and any session it was still creating must be - // visible on this task — before _session is read for removal below. Awaiting it here, - // rather than trusting Task.WhenAny already returned, is also what surfaces a fault - // that raced the write loop instead of leaving it unobserved. - await _observer.ObserveAsync(reading, ConnectionTaskKind.ReadLoop).ConfigureAwait(false); - - // The turn must stop writing before the channel is completed under it. Completing the - // writer first would let a write that was already in flight throw ChannelClosedException - // into a task nothing observes. Bounded: cancellation reaches a well-behaved turn, but - // a turn that honours cancellation yet takes longer than CloseTimeout to unwind — or a - // chat client that ignores its token altogether, such as BlockingChatClient in the test - // fakes — must not be able to wedge teardown forever. - // - // The last turn is read through ConversationTurnArbiter.CurrentTurn, which takes the same - // lock every writer of it takes, and never off a field directly: the arbiter's own - // RunPendingPrompt can reassign it from a turn's own task, off the read loop, so - // teardown here is no longer the only writer's own reader. That property's remarks - // carry the rest of the reasoning, including what stops the reverse case — a fresh - // turn appearing after teardown already read it. Null before the first setup frame, - // because the arbiter is built with the session. - var lastTurn = _arbiter?.CurrentTurn ?? Task.CompletedTask; - - await _observer.ObserveAsync(lastTurn, ConnectionTaskKind.Turn, _options.CloseTimeout).ConfigureAwait(false); - - _outbound.Writer.TryComplete(); - - // Both reading and lastTurn are fully observed by this point — ObserveAsync already - // awaited each of them inside its own try, which is what makes it safe to read - // .Exception here without raising a fresh UnobservedTaskException. Determined now, - // after teardown already knows how the read loop and the last turn each ended, and - // before the one CloseOutputAsync call the pump makes, because a status decided - // any later could not still change what the vendor already received. writing is not - // yet observed at this point — it is only awaited after the close below — so passing - // it in only lets DetermineCloseStatus see a fault it already has, never one that - // has not happened yet; see the remarks on that method for what this can and cannot - // catch. - var (status, description) = DetermineCloseStatus(reading, lastTurn, writing); - - // No bounded wait for the write loop here: _cancellation already cancelled above, and - // the write loop reads the channel with that same token, so it is already unblocking - // on its own. CloseAsync is what actually ends a send stuck on relay backpressure — it - // aborts the socket on its own timeout — so the write loop is observed after it, not - // waited for before it. A throw out of CloseAsync itself must not skip that - // observation or the store removal below, so it is caught and logged here instead of - // left to propagate. + _ = await Task.WhenAny(reading, writing).ConfigureAwait(false); + } + finally + { + // The disposal below must run on every exit from here down, including a throw out of + // Cancel() itself or IConversationSessions.CloseAsync: _cancellation links to ApplicationStopping, + // which lives for the whole process, and only Dispose() releases that registration. try { - await _pump.CloseAsync(status, description).ConfigureAwait(false); - } - catch (Exception fault) - { - ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.CloseFaulted( - _logger, - _session?.ConversationId ?? BeforeSetupConversationId, - fault)); - } - - await _observer.ObserveAsync(writing, ConnectionTaskKind.WriteLoop).ConfigureAwait(false); + // One of the two loops just ended, for whatever reason, so the socket is going + // away. Cancelling here stops the other loop's wait and any turn still streaming, + // rather than leaving them to read a recycled HttpContext.RequestAborted after this + // method returns. Cancel() itself is guarded: it runs with throwOnFirstException: + // false, so every callback still runs and both loops are already cancelled before a + // callback fault can reach this catch, and losing the rest of teardown below would + // otherwise strand this conversation in the store for the life of the process. + try + { + await _cancellation.CancelAsync().ConfigureAwait(false); + } + catch (Exception fault) + { + ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.CancellationFaulted( + _logger, + _session?.ConversationId ?? BeforeSetupConversationId, + fault)); + } - if (_session is { } session) - { - // The chain closes before the session leaves the store, and never after: §11 - // item 6 makes conversation.ended the last event of every conversation, and the session is what - // writes it. The reason comes from the status just decided rather than from a - // second reading of the same tasks, so the vendor's close frame and the audit - // row can never disagree about how this conversation ended. A conversation that already closed - // its own chain from a terminal stage answers false here and keeps the - // agent.completed it wrote: EndConversation is idempotent, and nothing on this path may - // give one conversation two endings. + // The read loop must actually finish — and any session it was still creating must be + // visible on this task — before _session is read for removal below. Awaiting it here, + // rather than trusting Task.WhenAny already returned, is also what surfaces a fault + // that raced the write loop instead of leaving it unobserved. + await _observer.ObserveAsync(reading, ConnectionTaskKind.ReadLoop).ConfigureAwait(false); + + // The turn must stop writing before the channel is completed under it. Completing the + // writer first would let a write that was already in flight throw ChannelClosedException + // into a task nothing observes. Bounded: cancellation reaches a well-behaved turn, but + // a turn that honours cancellation yet takes longer than CloseTimeout to unwind — or a + // chat client that ignores its token altogether, such as BlockingChatClient in the test + // fakes — must not be able to wedge teardown forever. // - // Guarded for the same reason CloseAsync above is. §7.1 forbids teardown - // throwing out of the request handler, and the close below must run whatever - // happens here — it is what waits for the words the last turn still owed - // store 1, and nothing else can. The event is - // handed to observers that swallow their own faults and the reason is a member - // of a closed set this class picks itself, so the only cause left is the clock - // the session reads; a missing last event is a gap in one chain, and losing the - // rest of teardown would be a leak in every conversation after it. + // The last turn is read through ConversationTurnArbiter.CurrentTurn, which takes the same + // lock every writer of it takes, and never off a field directly: the arbiter's own + // RunPendingPrompt can reassign it from a turn's own task, off the read loop, so + // teardown here is no longer the only writer's own reader. That property's remarks + // carry the rest of the reasoning, including what stops the reverse case — a fresh + // turn appearing after teardown already read it. Null before the first setup frame, + // because the arbiter is built with the session. + Task lastTurn = _arbiter?.CurrentTurn ?? Task.CompletedTask; + + await _observer.ObserveAsync(lastTurn, ConnectionTaskKind.Turn, _options.CloseTimeout).ConfigureAwait(false); + + _ = _outbound.Writer.TryComplete(); + + // Both reading and lastTurn are fully observed by this point — ObserveAsync already + // awaited each of them inside its own try, which is what makes it safe to read + // .Exception here without raising a fresh UnobservedTaskException. Determined now, + // after teardown already knows how the read loop and the last turn each ended, and + // before the one CloseOutputAsync call the pump makes, because a status decided + // any later could not still change what the vendor already received. writing is not + // yet observed at this point — it is only awaited after the close below — so passing + // it in only lets DetermineCloseStatus see a fault it already has, never one that + // has not happened yet; see the remarks on that method for what this can and cannot + // catch. + (WebSocketCloseStatus status, string? description) = DetermineCloseStatus(reading, lastTurn, writing); + + // No bounded wait for the write loop here: _cancellation already cancelled above, and + // the write loop reads the channel with that same token, so it is already unblocking + // on its own. CloseAsync is what actually ends a send stuck on relay backpressure — it + // aborts the socket on its own timeout — so the write loop is observed after it, not + // waited for before it. A throw out of CloseAsync itself must not skip that + // observation or the store removal below, so it is caught and logged here instead of + // left to propagate. try { - _ = session.EndConversation(EndReasonOf(status)); + await _pump.CloseAsync(status, description).ConfigureAwait(false); } catch (Exception fault) { - ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.ConversationEndFaulted( + ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.CloseFaulted( _logger, - session.ConversationId, + _session?.ConversationId ?? BeforeSetupConversationId, fault)); } - // Closing waits for the words this conversation still owes store 1 and only then drops - // the session; IConversationSessions.CloseAsync owns that order. - // - // Bounded and swallowed for the same reason the close above is: a store that - // stops answering must cost this conversation its last rows, not wedge teardown and - // strand the session in the store for the life of the process. - await _observer - .ObserveAsync( - CloseSessionAsync(session.ConversationId), - ConnectionTaskKind.SessionClose, - _options.CloseTimeout) - .ConfigureAwait(false); + await _observer.ObserveAsync(writing, ConnectionTaskKind.WriteLoop).ConfigureAwait(false); + + if (_session is { } session) + { + // The chain closes before the session leaves the store, and never after: §11 + // item 6 makes conversation.ended the last event of every conversation, and the session is what + // writes it. The reason comes from the status just decided rather than from a + // second reading of the same tasks, so the vendor's close frame and the audit + // row can never disagree about how this conversation ended. A conversation that already closed + // its own chain from a terminal stage answers false here and keeps the + // agent.completed it wrote: EndConversation is idempotent, and nothing on this path may + // give one conversation two endings. + // + // Guarded for the same reason CloseAsync above is. §7.1 forbids teardown + // throwing out of the request handler, and the close below must run whatever + // happens here — it is what waits for the words the last turn still owed + // store 1, and nothing else can. The event is + // handed to observers that swallow their own faults and the reason is a member + // of a closed set this class picks itself, so the only cause left is the clock + // the session reads; a missing last event is a gap in one chain, and losing the + // rest of teardown would be a leak in every conversation after it. + try + { + _ = session.EndConversation(EndReasonOf(status)); + } + catch (Exception fault) + { + ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.ConversationEndFaulted( + _logger, + session.ConversationId, + fault)); + } + + // Closing waits for the words this conversation still owes store 1 and only then drops + // the session; IConversationSessions.CloseAsync owns that order. + // + // Bounded and swallowed for the same reason the close above is: a store that + // stops answering must cost this conversation its last rows, not wedge teardown and + // strand the session in the store for the life of the process. + await _observer + .ObserveAsync( + CloseSessionAsync(session.ConversationId), + ConnectionTaskKind.SessionClose, + _options.CloseTimeout) + .ConfigureAwait(false); + } + } + finally + { + _cancellation.Dispose(); } - } - finally - { - _cancellation.Dispose(); } } - } - - /// Ends one conversation, as a task the observer can bound and watch. - /// The conversation that ended. - /// A task that completes once the words are written and the session is gone. - private async Task CloseSessionAsync(string conversationId) - { - await EntrySessions().CloseAsync(conversationId, CancellationToken.None).ConfigureAwait(false); - } - /// Works out the status and the description the vendor sees on the close frame. - /// - /// The read loop's task, already fully observed by . - /// - /// - /// The last turn's task, already fully observed by . - /// - /// - /// The write loop's task. Unlike and , this - /// one is not yet observed — RunAsync only awaits it after the close this method's result - /// feeds. Its is still safe to read without observing it first: - /// that flag reflects the task's current state the moment it is read, and reading it does not - /// itself count as observing the exception for the unobserved-task-exception machinery the way - /// awaiting or reading would. - /// - /// The status to close with, and the description to send alongside it. - /// - /// - /// Both and are already completed and - /// already observed by the time this runs — ObserveAsync awaited each of them inside its own - /// try — so reading their here raises nothing new; it only reads - /// what already happened. - /// - /// - /// The checks are ordered by how specific each cause is. A - /// names exactly why the endpoint refused the conversation, so it wins over everything else. A turn or - /// the write loop faulting with anything other than its own cancellation is this connection's - /// own defect, not the caller's or the vendor's, so either counts before the host-stopping check - /// below even notices that is, by this point in teardown, always - /// already cancelled for every possible reason at once. Host-stopping is checked directly - /// against rather than against which task happened to notice the - /// cancellation first, because once teardown's own call to _cancellation.Cancel() has - /// run, every task is cancelled regardless of why teardown started, and none of their own - /// completions can still tell "the host is stopping" apart from "the other loop just ended, so - /// this cancelled too." A dropped socket with no close frame — - /// — and a read loop that simply - /// returned once it saw the relay's own close frame both fall through to the same default: an - /// ordinary end of conversation. - /// - /// - /// The check only catches a write loop that has already faulted at - /// the moment this method runs. It is not exhaustive: the write loop is still running at this - /// point in the common case, and a fault it raises after this line — right up through the - /// SendAsync the close itself makes — cannot change a status already chosen and already - /// on its way to the vendor. That gap is an accepted limit of observing - /// before the close rather than after it, which the teardown order this method must not disturb - /// already requires. - /// - /// - private (WebSocketCloseStatus Status, string? Description) DetermineCloseStatus( - Task reading, - Task lastTurn, - Task writing) - { - if (reading.IsFaulted && reading.Exception.GetBaseException() is RelayProtocolException protocol) + /// Ends one conversation, as a task the observer can bound and watch. + /// The conversation that ended. + /// A task that completes once the words are written and the session is gone. + private async Task CloseSessionAsync(string conversationId) { - return (protocol.Status, protocol.Message); + await EntrySessions().CloseAsync(conversationId, CancellationToken.None).ConfigureAwait(false); } - if (lastTurn.IsFaulted || writing.IsFaulted) + /// Works out the status and the description the vendor sees on the close frame. + /// + /// The read loop's task, already fully observed by . + /// + /// + /// The last turn's task, already fully observed by . + /// + /// + /// The write loop's task. Unlike and , this + /// one is not yet observed — RunAsync only awaits it after the close this method's result + /// feeds. Its is still safe to read without observing it first: + /// that flag reflects the task's current state the moment it is read, and reading it does not + /// itself count as observing the exception for the unobserved-task-exception machinery the way + /// awaiting or reading would. + /// + /// The status to close with, and the description to send alongside it. + /// + /// + /// Both and are already completed and + /// already observed by the time this runs — ObserveAsync awaited each of them inside its own + /// try — so reading their here raises nothing new; it only reads + /// what already happened. + /// + /// + /// The checks are ordered by how specific each cause is. A + /// names exactly why the endpoint refused the conversation, so it wins over everything else. A turn or + /// the write loop faulting with anything other than its own cancellation is this connection's + /// own defect, not the caller's or the vendor's, so either counts before the host-stopping check + /// below even notices that is, by this point in teardown, always + /// already cancelled for every possible reason at once. Host-stopping is checked directly + /// against rather than against which task happened to notice the + /// cancellation first, because once teardown's own call to _cancellation.Cancel() has + /// run, every task is cancelled regardless of why teardown started, and none of their own + /// completions can still tell "the host is stopping" apart from "the other loop just ended, so + /// this cancelled too." A dropped socket with no close frame — + /// — and a read loop that simply + /// returned once it saw the relay's own close frame both fall through to the same default: an + /// ordinary end of conversation. + /// + /// + /// The check only catches a write loop that has already faulted at + /// the moment this method runs. It is not exhaustive: the write loop is still running at this + /// point in the common case, and a fault it raises after this line — right up through the + /// SendAsync the close itself makes — cannot change a status already chosen and already + /// on its way to the vendor. That gap is an accepted limit of observing + /// before the close rather than after it, which the teardown order this method must not disturb + /// already requires. + /// + /// + private (WebSocketCloseStatus Status, string? Description) DetermineCloseStatus( + Task reading, + Task lastTurn, + Task writing) { - return (WebSocketCloseStatus.InternalServerError, null); - } + if (reading.IsFaulted && reading.Exception.GetBaseException() is RelayProtocolException protocol) + { + return (protocol.Status, protocol.Message); + } - if (_lifetime.ApplicationStopping.IsCancellationRequested) - { - return (WebSocketCloseStatus.EndpointUnavailable, null); - } + if (lastTurn.IsFaulted || writing.IsFaulted) + { + return (WebSocketCloseStatus.InternalServerError, null); + } - if (reading.IsFaulted - && reading.Exception.GetBaseException() is not WebSocketException + if (_lifetime.ApplicationStopping.IsCancellationRequested) { - WebSocketErrorCode: WebSocketError.ConnectionClosedPrematurely, - }) - { - return (WebSocketCloseStatus.InternalServerError, null); - } + return (WebSocketCloseStatus.EndpointUnavailable, null); + } - return (WebSocketCloseStatus.NormalClosure, null); - } + if (reading.IsFaulted + && reading.Exception.GetBaseException() is not WebSocketException + { + WebSocketErrorCode: WebSocketError.ConnectionClosedPrematurely, + }) + { + return (WebSocketCloseStatus.InternalServerError, null); + } - /// Reads the ending one close status reports, as one member of the closed set. - /// What already decided this conversation closes with. - /// The reason the last event of the chain carries. - /// - /// - /// §11 item 6 and T55/T56 ask every call to end its chain in conversation.ended with a reason from - /// the closed set of four, and only this adapter can supply two of them: the turn loop closes its - /// own chain with when the stage machine reaches a - /// terminal stage, and belongs to the Conversation Control - /// path of §4.3 that voice slice 2 adds and this build does not have. What is left for a socket - /// that ended is the caller, or a fault. - /// - /// - /// The answer is read off the status rather than recomputed from the three tasks, so one decision - /// serves both the close frame the vendor sees and the row a report reads years later. That also - /// keeps this method total over a status set only chooses from. - /// - /// - /// is a hang-up, not a fault, and that - /// is the load-bearing decision here. A socket that stopped with no close frame is what - /// already folds into - /// alongside a read loop that saw the relay's own close frame — its remarks conversation both "an ordinary - /// end of conversation" — and what already logs through - /// at Information rather than as a defect. - /// This method agrees with both, and it has to: a caller who hangs up and a caller whose phone - /// loses signal look identical on this socket, the vendor never reconnects either of them, and - /// the audit table would be worth very little if the ordinary way a conversation ends were counted as a - /// system fault. §7.1's rule that a bad frame must never drop a conversation points the same way — the - /// adapter's default reading of an ended socket is the conversation ending, not the endpoint failing. - /// The one place this reading is contradicted is the remark on - /// itself, which lists "a dropped relay socket" among its causes; that sentence predates the - /// close-status reasoning above, and it is left alone here rather than edited, because the enum is - /// the core's and this decision is the adapter's. - /// - /// - /// The idle deadline lands here too, and for the same reason. A read loop that ends on - /// IdleTimeout returns rather than throwing, so it reaches - /// and is recorded as a hang-up — which is - /// exactly what already says a silent socket is: - /// a conversation that is already over. - /// - /// - /// Everything else is , and that includes two endings worth - /// naming. A protocol violation closes with the status - /// carries: the relay broke the contract and this endpoint refused the conversation, which no caller - /// chose. A host that stops closes with : - /// the process went away underneath a live conversation, which no caller chose either. Neither is a - /// hang-up, neither is the agent finishing, and neither is a transfer, so within a set of four - /// the honest answer is the fault — recorded as one rather than quietly counted as a caller who - /// decided to leave. - /// - /// - private static ConversationEndReason EndReasonOf(WebSocketCloseStatus status) - => status is WebSocketCloseStatus.NormalClosure - ? ConversationEndReason.CallerHungUp - : ConversationEndReason.Faulted; - - /// Logs the two faults that are the vendor's doing rather than this endpoint's defect. - /// The exception a loop or a turn ended with. - /// Which task faulted. - /// The id of the conversation, or a placeholder before setup. - /// - /// when this method logged itself, and - /// to leave it to . - /// - /// - /// The classify hook conversations before its own general clause. - /// Both causes below name a vendor type, which is why they stay here rather than moving into - /// that observer with the rest of the teardown machinery. - /// - private bool ClassifyTelnyxFault(Exception fault, ConnectionTaskKind kind, string conversationId) - { - switch (fault) + return (WebSocketCloseStatus.NormalClosure, null); + } + + /// Reads the ending one close status reports, as one member of the closed set. + /// What already decided this conversation closes with. + /// The reason the last event of the chain carries. + /// + /// + /// §11 item 6 and T55/T56 ask every call to end its chain in conversation.ended with a reason from + /// the closed set of four, and only this adapter can supply two of them: the turn loop closes its + /// own chain with when the stage machine reaches a + /// terminal stage, and belongs to the Conversation Control + /// path of §4.3 that voice slice 2 adds and this build does not have. What is left for a socket + /// that ended is the caller, or a fault. + /// + /// + /// The answer is read off the status rather than recomputed from the three tasks, so one decision + /// serves both the close frame the vendor sees and the row a report reads years later. That also + /// keeps this method total over a status set only chooses from. + /// + /// + /// is a hang-up, not a fault, and that + /// is the load-bearing decision here. A socket that stopped with no close frame is what + /// already folds into + /// alongside a read loop that saw the relay's own close frame — its remarks conversation both "an ordinary + /// end of conversation" — and what already logs through + /// at Information rather than as a defect. + /// This method agrees with both, and it has to: a caller who hangs up and a caller whose phone + /// loses signal look identical on this socket, the vendor never reconnects either of them, and + /// the audit table would be worth very little if the ordinary way a conversation ends were counted as a + /// system fault. §7.1's rule that a bad frame must never drop a conversation points the same way — the + /// adapter's default reading of an ended socket is the conversation ending, not the endpoint failing. + /// The one place this reading is contradicted is the remark on + /// itself, which lists "a dropped relay socket" among its causes; that sentence predates the + /// close-status reasoning above, and it is left alone here rather than edited, because the enum is + /// the core's and this decision is the adapter's. + /// + /// + /// The idle deadline lands here too, and for the same reason. A read loop that ends on + /// IdleTimeout returns rather than throwing, so it reaches + /// and is recorded as a hang-up — which is + /// exactly what already says a silent socket is: + /// a conversation that is already over. + /// + /// + /// Everything else is , and that includes two endings worth + /// naming. A protocol violation closes with the status + /// carries: the relay broke the contract and this endpoint refused the conversation, which no caller + /// chose. A host that stops closes with : + /// the process went away underneath a live conversation, which no caller chose either. Neither is a + /// hang-up, neither is the agent finishing, and neither is a transfer, so within a set of four + /// the honest answer is the fault — recorded as one rather than quietly counted as a caller who + /// decided to leave. + /// + /// + private static ConversationEndReason EndReasonOf(WebSocketCloseStatus status) { - case RelayProtocolException protocol: - // Malformed JSON or an oversized frame: the relay broke the contract, not a defect - // this endpoint owns. DetermineCloseStatus reads this same exception straight off - // the task afterward for the close status, so this line only has to log it — every - // other malformed-input line in this file (PromptBeforeSetup, FrameRefused, - // MalformedInterruptFrame) already logs at Warning, and LogFault's generic path - // would otherwise report this at Error, the same level as an unhandled bug. - TelnyxRelayLog.RelayProtocolViolation(_logger, conversationId, protocol.Message); - return true; - - case WebSocketException { WebSocketErrorCode: WebSocketError.ConnectionClosedPrematurely } - when kind == ConnectionTaskKind.ReadLoop: - // The conversation dropped with no close frame. Section "close statuses" of task 7: that is - // an ordinary end of a conversation, not a fault, so it is worth a line but not an error one. - TelnyxRelayLog.ConversationDroppedWithNoCloseFrame(_logger, conversationId); - return true; - - default: - return false; + return status is WebSocketCloseStatus.NormalClosure + ? ConversationEndReason.CallerHungUp + : ConversationEndReason.Faulted; } - } - /// Logs the fault of a read loop, a turn, or a write loop, whichever names. - /// Which task faulted. - /// The id of the conversation, or a placeholder before setup. - /// The cause. - /// - /// The logFault hook of , which calls it from - /// directly and from the fault-only - /// continuation that method attaches on a timeout. That continuation runs with nothing above it - /// to catch a throw, so the observer wraps every call to this method in - /// ; nothing here has to guard itself again. - /// - private void LogFault(ConnectionTaskKind kind, string conversationId, Exception fault) - { - switch (kind) + /// Logs the two faults that are the vendor's doing rather than this endpoint's defect. + /// The exception a loop or a turn ended with. + /// Which task faulted. + /// The id of the conversation, or a placeholder before setup. + /// + /// when this method logged itself, and + /// to leave it to . + /// + /// + /// The classify hook conversations before its own general clause. + /// Both causes below name a vendor type, which is why they stay here rather than moving into + /// that observer with the rest of the teardown machinery. + /// + private bool ClassifyTelnyxFault(Exception fault, ConnectionTaskKind kind, string conversationId) { - case ConnectionTaskKind.Turn: - TelnyxRelayLog.TurnFaulted(_logger, conversationId, fault); - break; + switch (fault) + { + case RelayProtocolException protocol: + // Malformed JSON or an oversized frame: the relay broke the contract, not a defect + // this endpoint owns. DetermineCloseStatus reads this same exception straight off + // the task afterward for the close status, so this line only has to log it — every + // other malformed-input line in this file (PromptBeforeSetup, FrameRefused, + // MalformedInterruptFrame) already logs at Warning, and LogFault's generic path + // would otherwise report this at Error, the same level as an unhandled bug. + TelnyxRelayLog.RelayProtocolViolation(_logger, conversationId, protocol.Message); + return true; + + case WebSocketException { WebSocketErrorCode: WebSocketError.ConnectionClosedPrematurely } + when kind == ConnectionTaskKind.ReadLoop: + // The conversation dropped with no close frame. Section "close statuses" of task 7: that is + // an ordinary end of a conversation, not a fault, so it is worth a line but not an error one. + TelnyxRelayLog.ConversationDroppedWithNoCloseFrame(_logger, conversationId); + return true; + + default: + return false; + } + } - case ConnectionTaskKind.WriteLoop: - TelnyxRelayLog.WriteLoopFaulted(_logger, conversationId, fault); - break; + /// Logs the fault of a read loop, a turn, or a write loop, whichever names. + /// Which task faulted. + /// The id of the conversation, or a placeholder before setup. + /// The cause. + /// + /// The logFault hook of , which calls it from + /// directly and from the fault-only + /// continuation that method attaches on a timeout. That continuation runs with nothing above it + /// to catch a throw, so the observer wraps every call to this method in + /// ; nothing here has to guard itself again. + /// + private void LogFault(ConnectionTaskKind kind, string conversationId, Exception fault) + { + switch (kind) + { + case ConnectionTaskKind.Turn: + TelnyxRelayLog.TurnFaulted(_logger, conversationId, fault); + break; - case ConnectionTaskKind.SessionClose: - TelnyxRelayLog.ConversationCloseFaulted(_logger, conversationId, fault); - break; + case ConnectionTaskKind.WriteLoop: + TelnyxRelayLog.WriteLoopFaulted(_logger, conversationId, fault); + break; - default: - TelnyxRelayLog.ReadLoopFaulted(_logger, conversationId, fault); - break; - } - } + case ConnectionTaskKind.SessionClose: + TelnyxRelayLog.ConversationCloseFaulted(_logger, conversationId, fault); + break; - /// Reads one inbound message with the vendor's own reader. - /// The whole message, already reassembled by the pump. - /// The frame, the name of a type this build does not model, or the name of one whose body would not bind. - /// - /// The parse seam of . says the - /// same three things does, so the - /// carries nothing the outcome does not: a frame is present exactly when that method returned - /// . - /// - private static FrameOutcome ParseFrame(ReadOnlySpan utf8) - { - _ = TelnyxRelayFrameReader.TryRead(utf8, out var frame, out var unknownType, out var refusedType); - return new FrameOutcome(frame, unknownType, refusedType); - } + case ConnectionTaskKind.ReadLoop: + TelnyxRelayLog.ReadLoopFaulted(_logger, conversationId, fault); + break; - /// Writes one queued item as the frame to send, or drops it. - /// What a reply queued, and the generation it was queued under. - /// The write loop's own writer, already reset for this frame. - /// - /// when a whole frame was written, and to drop - /// without sending anything. - /// - /// - /// The encode seam of , which runs it immediately before - /// its one send. The gate below stays here, on this side of that seam, because a stale item is - /// stale in this connection's own vocabulary and in no transport's. The writer belongs to that - /// loop and is reused for every frame of the conversation, so nothing here keeps it, flushes it, or - /// holds what it wrote: the bytes are the loop's to send and the loop's to overwrite. - /// - private bool EncodeOutbound(OutboundItem item, Utf8JsonWriter writer) - { - // The write loop is the last gate, immediately before the one SendAsync call the pump - // makes for this connection. ConversationTurnArbiter's own check only narrows the race — it cannot - // stop a token already past it at the moment a barge-in raises the reply generation: - // one already queued, one a bounded channel's backpressure was about to release into the gap - // StopAsync's own drain just made, or one this loop had already dequeued and was about to - // send. All three carry the generation they were queued under, the same counter that drain - // raises, so whichever of them let a stale item this far, it stops here instead of reaching - // the caller. The gate is expressed in generations and never in the arbiter's turn ids: an - // item from a turn that simply ended, with a newer one already under way, is not stale, and - // a turn id alone cannot tell the two apart — a generation only ever moves when a barge-in - // actually stopped the audio. - // - // >=, not ==. _replyGeneration and every item's own Generation both only ever increase, - // so "the highest generation a barge-in has cut off is at or above this item's own" is - // the question that actually matches a conversation across two barge-ins: with == alone, an item of - // generation N already dequeued here, then gated after a second, later barge-in raises - // the mark to N+1, would compare N+1 != N, pass, and reach the caller — exactly the - // straggler this gate exists to stop. With no interrupt at all _replyGeneration stays - // 0, and a queued item's generation is always at least 1, so nothing is dropped that - // this comparison would not already drop with ==. The one behaviour change is a prior - // turn's trailing last: true frame, still queued when a later barge-in lands: it now - // drops instead of reaching the caller, which is exactly what StopAsync's own - // unconditional drain already does to that same frame whenever it is still queued at the - // moment of the interrupt rather than sent moments later. - if (item.Generation is { } generation && Interlocked.Read(ref _replyGeneration) >= generation) - { - return false; + default: + throw new ArgumentOutOfRangeException(nameof(kind), kind, "The connection task vocabulary is closed, and this value is not in it."); + } } - // The same options SerializeToUtf8Bytes was given, and the same bytes: TelnyxRelayJson sets - // no encoder and no indentation, so a default Utf8JsonWriter escapes and lays out this frame - // exactly as the writer JsonSerializer used to build per conversation did. - JsonSerializer.Serialize(writer, item.Frame, item.Frame.GetType(), TelnyxRelayJson.Options); - return true; - } - - private async Task DispatchAsync(RelayFrame frame) - { - switch (frame) + /// Reads one inbound message with the vendor's own reader. + /// The whole message, already reassembled by the pump. + /// The frame, the name of a type this build does not model, or the name of one whose body would not bind. + /// + /// The parse seam of . says the + /// same three things does, so the + /// carries nothing the outcome does not: a frame is present exactly when that method returned + /// . + /// + private static FrameOutcome ParseFrame(ReadOnlySpan utf8) { - case RelayFrame.Setup setup: - await StartConversationAsync(setup).ConfigureAwait(false); - break; - - case RelayFrame.Prompt { Last: true } prompt: - await StartTurnAsync(prompt.VoicePrompt).ConfigureAwait(false); - break; - - case RelayFrame.Prompt: - // An interim transcript. The turn starts on the final one. - break; - - case RelayFrame.Interrupt interrupt: - HandleInterrupt(interrupt); - break; - - case RelayFrame.Dtmf: - // Never the digit itself. A keypad carries card numbers, PINs, and dates of birth, - // and the house rule in Log.cs is that no line carries what the caller said. - TelnyxRelayLog.DtmfReceived(_logger); - break; - - case RelayFrame.Error error: - // The vendor refused a frame this endpoint sent. That is our defect. - TelnyxRelayLog.FrameRefused(_logger, _session?.ConversationId ?? BeforeSetupConversationId, error.Description); - break; + _ = TelnyxRelayFrameReader.TryRead(utf8, out RelayFrame? frame, out string? unknownType, out string? refusedType); + return new FrameOutcome(frame, unknownType, refusedType); } - } - private async Task StartConversationAsync(RelayFrame.Setup setup) - { - var sessions = EntrySessions(); - - // One socket carries one conversation, and the vendor sends one setup frame. A second one replaces - // the session rather than refusing the socket, because section 7.1 forbids dropping a conversation - // over a frame the vendor got wrong, and because the vendor's latest word about the conversation is - // the one to answer. The first session is closed here and not left behind: teardown only - // ever closes the session this connection currently holds, so this is the last moment - // anything waits for the words the replaced conversation still owed store 1. - // CancellationToken.None, because the close must still run while the connection is - // tearing down. - if (_session is { } replaced) + /// Writes one queued item as the frame to send, or drops it. + /// What a reply queued, and the generation it was queued under. + /// The write loop's own writer, already reset for this frame. + /// + /// when a whole frame was written, and to drop + /// without sending anything. + /// + /// + /// The encode seam of , which runs it immediately before + /// its one send. The gate below stays here, on this side of that seam, because a stale item is + /// stale in this connection's own vocabulary and in no transport's. The writer belongs to that + /// loop and is reused for every frame of the conversation, so nothing here keeps it, flushes it, or + /// holds what it wrote: the bytes are the loop's to send and the loop's to overwrite. + /// + private bool EncodeOutbound(OutboundItem item, Utf8JsonWriter writer) { - if (!_loggedSecondSetup) + // The write loop is the last gate, immediately before the one SendAsync call the pump + // makes for this connection. ConversationTurnArbiter's own check only narrows the race — it cannot + // stop a token already past it at the moment a barge-in raises the reply generation: + // one already queued, one a bounded channel's backpressure was about to release into the gap + // StopAsync's own drain just made, or one this loop had already dequeued and was about to + // send. All three carry the generation they were queued under, the same counter that drain + // raises, so whichever of them let a stale item this far, it stops here instead of reaching + // the caller. The gate is expressed in generations and never in the arbiter's turn ids: an + // item from a turn that simply ended, with a newer one already under way, is not stale, and + // a turn id alone cannot tell the two apart — a generation only ever moves when a barge-in + // actually stopped the audio. + // + // >=, not ==. _replyGeneration and every item's own Generation both only ever increase, + // so "the highest generation a barge-in has cut off is at or above this item's own" is + // the question that actually matches a conversation across two barge-ins: with == alone, an item of + // generation N already dequeued here, then gated after a second, later barge-in raises + // the mark to N+1, would compare N+1 != N, pass, and reach the caller — exactly the + // straggler this gate exists to stop. With no interrupt at all _replyGeneration stays + // 0, and a queued item's generation is always at least 1, so nothing is dropped that + // this comparison would not already drop with ==. The one behaviour change is a prior + // turn's trailing last: true frame, still queued when a later barge-in lands: it now + // drops instead of reaching the caller, which is exactly what StopAsync's own + // unconditional drain already does to that same frame whenever it is still queued at the + // moment of the interrupt rather than sent moments later. + if (item.Generation is { } generation && Interlocked.Read(ref _replyGeneration) >= generation) { - _loggedSecondSetup = true; - TelnyxRelayLog.SecondSetupFrame(_logger, replaced.ConversationId); + return false; } - // Teardown will later close the session that replaced this one and never this one, so - // this is the last moment anything can wait for the writes it queued. Bounded and - // swallowed by the observer, so a store that stopped answering costs the replaced conversation - // its last rows rather than stalling the read loop for the rest of the connection. - // Through CloseSessionAsync, and never CloseAsync(...).AsTask(): a store that throws - // synchronously throws before AsTask() is ever reached, so the observer would not see - // it and §7.1's rule against dropping a conversation over a bad frame would be broken by the - // very frame that rule is about. An async method turns that throw into the task the - // observer bounds. - await _observer - .ObserveAsync( - CloseSessionAsync(replaced.ConversationId), - ConnectionTaskKind.SessionClose, - _options.CloseTimeout) - .ConfigureAwait(false); + // The same options SerializeToUtf8Bytes was given, and the same bytes: TelnyxRelayJson sets + // no encoder and no indentation, so a default Utf8JsonWriter escapes and lays out this frame + // exactly as the writer JsonSerializer used to build per conversation did. + JsonSerializer.Serialize(writer, item.Frame, item.Frame.GetType(), TelnyxRelayJson.Options); + return true; } - // conversationSessionId groups the legs of one logical conversation, so the id survives the warm transfer - // that slice 2 adds. A leg id would break there. - _session = await sessions.OpenAsync(setup.ConversationSessionId, _cancellation.Token).ConfigureAwait(false); - - // Built on the first setup frame and never again: a later one only tells the arbiter which - // call to answer from now on. One socket runs one turn at a time, and that promise belongs - // to this connection rather than to any one session of it — a second arbiter would bring - // its own _turnActive, its own held prompt, its own ids, and its own log-once flag, so a - // prompt arriving while the replaced session's turn still ran would find nothing in flight - // and start a second reply into the same channel. Rebinding keeps every one of those - // exactly where the old, connection-held state kept them. - if (_arbiter is { } arbiter) + private async Task DispatchAsync(RelayFrame frame) { - arbiter.Rebind(_session); - return; + switch (frame) + { + case RelayFrame.Setup setup: + await StartConversationAsync(setup).ConfigureAwait(false); + break; + + case RelayFrame.Prompt { Last: true } prompt: + await StartTurnAsync(prompt.VoicePrompt).ConfigureAwait(false); + break; + + case RelayFrame.Prompt: + // An interim transcript. The turn starts on the final one. + break; + + case RelayFrame.Interrupt interrupt: + HandleInterrupt(interrupt); + break; + + case RelayFrame.Dtmf: + // Never the digit itself. A keypad carries card numbers, PINs, and dates of birth, + // and the house rule in Log.cs is that no line carries what the caller said. + TelnyxRelayLog.DtmfReceived(_logger); + break; + + case RelayFrame.Error error: + // The vendor refused a frame this endpoint sent. That is our defect. + TelnyxRelayLog.FrameRefused(_logger, _session?.ConversationId ?? BeforeSetupConversationId, error.Description); + break; + + default: + // The reader hands back only the frames this build models; see TelnyxRelayFrameReader.TryRead. + break; + } } - // Not in the constructor: the arbiter runs turns against a session, and no session exists - // until this frame arrives. The output port handed over is this connection itself — one - // socket is both halves of this vendor's channel — and the arbiter cannot tell that from a - // port belonging to a separate synthesizer, which is the whole of D8. - // The two log callbacks are this vendor's own lines, bound here: the arbiter decides when a - // prompt is held and when a further one is dropped, and names no log event of its own. - _arbiter = new ConversationTurnArbiter( - _session, - this, - _observer, - conversationId => TelnyxRelayLog.PromptHeld(_logger, conversationId), - conversationId => TelnyxRelayLog.PendingPromptDropped(_logger, conversationId), - _connectionToken); - } - - private async Task StartTurnAsync(string text) - { - if (_arbiter is not { } arbiter) + private async Task StartConversationAsync(RelayFrame.Setup setup) { - // Log once for the conversation, not once for the frame. Same rule as the unknown-frame line. - if (!_loggedPromptBeforeSetup) + IConversationSessions sessions = EntrySessions(); + + // One socket carries one conversation, and the vendor sends one setup frame. A second one replaces + // the session rather than refusing the socket, because section 7.1 forbids dropping a conversation + // over a frame the vendor got wrong, and because the vendor's latest word about the conversation is + // the one to answer. The first session is closed here and not left behind: teardown only + // ever closes the session this connection currently holds, so this is the last moment + // anything waits for the words the replaced conversation still owed store 1. + // CancellationToken.None, because the close must still run while the connection is + // tearing down. + if (_session is { } replaced) + { + if (!_loggedSecondSetup) + { + _loggedSecondSetup = true; + TelnyxRelayLog.SecondSetupFrame(_logger, replaced.ConversationId); + } + + // Teardown will later close the session that replaced this one and never this one, so + // this is the last moment anything can wait for the writes it queued. Bounded and + // swallowed by the observer, so a store that stopped answering costs the replaced conversation + // its last rows rather than stalling the read loop for the rest of the connection. + // Through CloseSessionAsync, and never CloseAsync(...).AsTask(): a store that throws + // synchronously throws before AsTask() is ever reached, so the observer would not see + // it and §7.1's rule against dropping a conversation over a bad frame would be broken by the + // very frame that rule is about. An async method turns that throw into the task the + // observer bounds. + await _observer + .ObserveAsync( + CloseSessionAsync(replaced.ConversationId), + ConnectionTaskKind.SessionClose, + _options.CloseTimeout) + .ConfigureAwait(false); + } + + // conversationSessionId groups the legs of one logical conversation, so the id survives the warm transfer + // that slice 2 adds. A leg id would break there. + _session = await sessions.OpenAsync(setup.ConversationSessionId, _cancellation.Token).ConfigureAwait(false); + + // Built on the first setup frame and never again: a later one only tells the arbiter which + // call to answer from now on. One socket runs one turn at a time, and that promise belongs + // to this connection rather than to any one session of it — a second arbiter would bring + // its own _turnActive, its own held prompt, its own ids, and its own log-once flag, so a + // prompt arriving while the replaced session's turn still ran would find nothing in flight + // and start a second reply into the same channel. Rebinding keeps every one of those + // exactly where the old, connection-held state kept them. + if (_arbiter is { } arbiter) { - _loggedPromptBeforeSetup = true; - TelnyxRelayLog.PromptBeforeSetup(_logger); + arbiter.Rebind(_session); + return; } - return; + // Not in the constructor: the arbiter runs turns against a session, and no session exists + // until this frame arrives. The output port handed over is this connection itself — one + // socket is both halves of this vendor's channel — and the arbiter cannot tell that from a + // port belonging to a separate synthesizer, which is the whole of D8. + // The two log callbacks are this vendor's own lines, bound here: the arbiter decides when a + // prompt is held and when a further one is dropped, and names no log event of its own. + _arbiter = new ConversationTurnArbiter( + _session, + this, + _observer, + conversationId => TelnyxRelayLog.PromptHeld(_logger, conversationId), + conversationId => TelnyxRelayLog.PendingPromptDropped(_logger, conversationId), + _connectionToken); } - await KeepSessionAliveAsync().ConfigureAwait(false); + private async Task StartTurnAsync(string text) + { + if (_arbiter is not { } arbiter) + { + // Log once for the conversation, not once for the frame. Same rule as the unknown-frame line. + if (!_loggedPromptBeforeSetup) + { + _loggedPromptBeforeSetup = true; + TelnyxRelayLog.PromptBeforeSetup(_logger); + } - // Discarded, never awaited. The arbiter's own task follows the turn to its end, and the read - // loop is what calls this: a read loop that waited for a turn could not receive the - // interrupt frame that ends it. The turn itself stays visible on CurrentTurn, which the next - // turn and teardown both observe. - _ = arbiter.StartTurnAsync(text); - } + return; + } - /// Tells the store this conversation is still being had. - /// A task that completes once the store has been read. - /// - /// This connection opens its session once and holds it for the whole conversation, so nothing else ever - /// reads it back. A store that expires an idle session counts a read as the one sign the conversation is - /// still live, so without this a conversation longer than that timeout is swept out from under the turn - /// about to run: its words are flushed, its session is dropped, and every turn after it runs on - /// an object no close can reach. A conversation nobody speaks on is ended by this socket's own - /// IdleTimeout instead, which is a real end and closes the chain. - /// The result is not used. It is the read itself that matters, and the session this connection - /// holds is the one the arbiter must keep running whatever the store answers. - /// - private async Task KeepSessionAliveAsync() - { - if (_session is not { } session) - { - return; - } + await KeepSessionAliveAsync().ConfigureAwait(false); - // §7.1 forbids dropping a conversation over one frame, and this runs on the read loop. A store that - // throws costs this conversation its place in the sweep, never the conversation itself. - try - { - _ = await EntrySessions().TryGetAsync(session.ConversationId, _connectionToken).ConfigureAwait(false); + // Discarded, never awaited. The arbiter's own task follows the turn to its end, and the read + // loop is what calls this: a read loop that waited for a turn could not receive the + // interrupt frame that ends it. The turn itself stays visible on CurrentTurn, which the next + // turn and teardown both observe. + _ = arbiter.StartTurnAsync(text); } - catch (Exception fault) when (fault is not OperationCanceledException) - { - ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.SessionTouchFaulted( - _logger, session.ConversationId, fault)); - } - } - private void HandleInterrupt(RelayFrame.Interrupt interrupt) - { - if (_arbiter is not { } arbiter || _session is not { } session) + /// Tells the store this conversation is still being had. + /// A task that completes once the store has been read. + /// + /// This connection opens its session once and holds it for the whole conversation, so nothing else ever + /// reads it back. A store that expires an idle session counts a read as the one sign the conversation is + /// still live, so without this a conversation longer than that timeout is swept out from under the turn + /// about to run: its words are flushed, its session is dropped, and every turn after it runs on + /// an object no close can reach. A conversation nobody speaks on is ended by this socket's own + /// IdleTimeout instead, which is a real end and closes the chain. + /// The result is not used. It is the read itself that matters, and the session this connection + /// holds is the one the arbiter must keep running whatever the store answers. + /// + private async Task KeepSessionAliveAsync() { - return; + if (_session is not { } session) + { + return; + } + + // §7.1 forbids dropping a conversation over one frame, and this runs on the read loop. A store that + // throws costs this conversation its place in the sweep, never the conversation itself. + try + { + _ = await EntrySessions().TryGetAsync(session.ConversationId, _connectionToken).ConfigureAwait(false); + } + catch (Exception fault) when (fault is not OperationCanceledException) + { + ConnectionTaskObserver.SafeLog(() => TelnyxRelayLog.SessionTouchFaulted( + _logger, session.ConversationId, fault)); + } } - // Section 7.1's rule for an unknown frame type and for a prompt before setup applies here - // too: a frame the vendor got wrong must not drop the conversation. System.Text.Json enforces - // neither a missing property nor a negative number at run time, so a frame missing - // utteranceUntilInterrupt, or carrying a negative durationUntilInterruptMs, would otherwise - // reach ConversationSession.Interrupt's own ArgumentNullException or ArgumentOutOfRangeException - // uncaught and take the read loop down with it. Nothing here clamps the duration — a clamp - // is an estimate, and D28 exists to keep estimates out of this path. This guard stays here, - // and never moves into the arbiter: validating these two values is reading a vendor frame. - if (interrupt.UtteranceUntilInterrupt is null || interrupt.DurationUntilInterruptMs < 0) + private void HandleInterrupt(RelayFrame.Interrupt interrupt) { - if (!_loggedMalformedInterrupt) + if (_arbiter is not { } arbiter || _session is not { } session) { - _loggedMalformedInterrupt = true; - TelnyxRelayLog.MalformedInterruptFrame(_logger, session.ConversationId); + return; } - return; - } + // Section 7.1's rule for an unknown frame type and for a prompt before setup applies here + // too: a frame the vendor got wrong must not drop the conversation. System.Text.Json enforces + // neither a missing property nor a negative number at run time, so a frame missing + // utteranceUntilInterrupt, or carrying a negative durationUntilInterruptMs, would otherwise + // reach ConversationSession.Interrupt's own ArgumentNullException or ArgumentOutOfRangeException + // uncaught and take the read loop down with it. Nothing here clamps the duration — a clamp + // is an estimate, and D28 exists to keep estimates out of this path. This guard stays here, + // and never moves into the arbiter: validating these two values is reading a vendor frame. + if (interrupt.UtteranceUntilInterrupt is null || interrupt.DurationUntilInterruptMs < 0) + { + if (!_loggedMalformedInterrupt) + { + _loggedMalformedInterrupt = true; + TelnyxRelayLog.MalformedInterruptFrame(_logger, session.ConversationId); + } - // The vendor measured both values itself. D28 and item 6a: nothing here estimates either - // one. - arbiter.Interrupt( - interrupt.UtteranceUntilInterrupt, - TimeSpan.FromMilliseconds(interrupt.DurationUntilInterruptMs)); + return; + } - // Logged last, once the raised id, the conversation to Interrupt, and the drain behind - // IConversationOutputPort.StopAsync have all already happened, so this line is proof the whole - // guard is in place — never the words the caller said or heard. - TelnyxRelayLog.InterruptReceived(_logger, session.ConversationId); - } + // The vendor measured both values itself. D28 and item 6a: nothing here estimates either + // one. + _ = arbiter.Interrupt( + interrupt.UtteranceUntilInterrupt, + TimeSpan.FromMilliseconds(interrupt.DurationUntilInterruptMs)); - /// - public ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default) - => _outbound.Writer.WriteAsync( - new OutboundItem(CurrentGeneration() + 1, new RelayToken(fragment, Last: false)), - cancellationToken); - - /// - public ValueTask CompleteAsync(CancellationToken cancellationToken = default) - // The vendor closes a reply on last: true, and the sample uses an empty final token when - // the stream ended with no trailing text. - => _outbound.Writer.WriteAsync( - new OutboundItem(CurrentGeneration() + 1, new RelayToken(string.Empty, Last: true)), - cancellationToken); - - /// - public ValueTask StopAsync(CancellationToken cancellationToken = default) - { - // Raised before the drain, and the write loop's own gate reads the same field. The relay - // already stopped its own audio. Conversation Relay carries no clear frame, so anything - // still queued here is the only audio left that could start it playing again, and this - // queue is the only thing this process still controls. - Interlocked.Increment(ref _replyGeneration); + // Logged last, once the raised id, the conversation to Interrupt, and the drain behind + // IConversationOutputPort.StopAsync have all already happened, so this line is proof the whole + // guard is in place — never the words the caller said or heard. + TelnyxRelayLog.InterruptReceived(_logger, session.ConversationId); + } - while (_outbound.Reader.TryRead(out _)) + /// + public ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default) { - // Drained, never sent: the barge-in above already cut off everything still queued. + return _outbound.Writer.WriteAsync( + new OutboundItem(CurrentGeneration() + 1, new RelayToken(fragment, Last: false)), + cancellationToken); } - return ValueTask.CompletedTask; - } - - /// - /// - /// - /// This stream yields nothing today, and that is deliberate rather than a defect. The - /// read loop still drives DispatchAsync directly, so every inbound frame of this conversation - /// already reaches the arbiter by that path; rerouting it through this stream is a later change - /// that no current caller needs. Until then this half of the channel exists so the shape is - /// honest — one object really does fill both slots — and it completes when the connection does, - /// so an await foreach over it ends with the conversation rather than at once. A consumer that - /// cancels its own read gets instead, which is the rule - /// sets for every implementation of this port. - /// - /// - /// One consumer for the life of the port, and the guard is here rather than inside the iterator - /// below: an iterator's body does not run until something enumerates it, so a second call would - /// otherwise hand back a stream that throws late, or never at all if nobody enumerates it. - /// - /// - public IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default) - { - if (Interlocked.CompareExchange(ref _listening, 1, 0) != 0) + /// + public ValueTask CompleteAsync(CancellationToken cancellationToken = default) { - throw new InvalidOperationException("This relay connection is already being read."); + // The vendor closes a reply on last: true, and the sample uses an empty final token when + // the stream ended with no trailing text. + return _outbound.Writer.WriteAsync( + new OutboundItem(CurrentGeneration() + 1, new RelayToken(string.Empty, Last: true)), + cancellationToken); } - return ListenCoreAsync(cancellationToken); - } + /// + public ValueTask StopAsync(CancellationToken cancellationToken = default) + { + // Raised before the drain, and the write loop's own gate reads the same field. The relay + // already stopped its own audio. Conversation Relay carries no clear frame, so anything + // still queued here is the only audio left that could start it playing again, and this + // queue is the only thing this process still controls. + _ = Interlocked.Increment(ref _replyGeneration); - /// - /// - /// Nothing to release here, and disposing a port must not tear this connection down. The - /// channel, the linked cancellation source, and the socket all belong to RunAsync, which - /// releases them in its own teardown once the last turn has stopped writing — and for this - /// vendor the conversation ends when that method returns, not when whoever holds the - /// lets go of it. - /// - public ValueTask DisposeAsync() => ValueTask.CompletedTask; + while (_outbound.Reader.TryRead(out _)) + { + // Drained, never sent: the barge-in above already cut off everything still queued. + } - /// Yields nothing, and completes when this connection ends. - /// Ends the stream early, ahead of the connection itself. - /// An empty stream, deliberately. 's remarks say why. - private async IAsyncEnumerable ListenCoreAsync( - [EnumeratorCancellation] CancellationToken cancellationToken) - { - // Linked, so the caller's own token ends the stream too, and built from the captured - // connection token rather than from _cancellation.Token for the reason that field records. - using var linked = CancellationTokenSource.CreateLinkedTokenSource(_connectionToken, cancellationToken); + return ValueTask.CompletedTask; + } - try + /// + /// + /// + /// This stream yields nothing today, and that is deliberate rather than a defect. The + /// read loop still drives DispatchAsync directly, so every inbound frame of this conversation + /// already reaches the arbiter by that path; rerouting it through this stream is a later change + /// that no current caller needs. Until then this half of the channel exists so the shape is + /// honest — one object really does fill both slots — and it completes when the connection does, + /// so an await foreach over it ends with the conversation rather than at once. A consumer that + /// cancels its own read gets instead, which is the rule + /// sets for every implementation of this port. + /// + /// + /// One consumer for the life of the port, and the guard is here rather than inside the iterator + /// below: an iterator's body does not run until something enumerates it, so a second call would + /// otherwise hand back a stream that throws late, or never at all if nobody enumerates it. + /// + /// + public IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default) { - await Task.Delay(Timeout.InfiniteTimeSpan, linked.Token).ConfigureAwait(false); + return Interlocked.CompareExchange(ref _listening, 1, 0) != 0 + ? throw new InvalidOperationException("This relay connection is already being read.") + : ListenCoreAsync(cancellationToken); } - catch (OperationCanceledException) + + /// + /// + /// Nothing to release here, and disposing a port must not tear this connection down. The + /// channel, the linked cancellation source, and the socket all belong to RunAsync, which + /// releases them in its own teardown once the last turn has stopped writing — and for this + /// vendor the conversation ends when that method returns, not when whoever holds the + /// lets go of it. + /// + public ValueTask DisposeAsync() + { + return ValueTask.CompletedTask; + } + + /// Yields nothing, and completes when this connection ends. + /// Ends the stream early, ahead of the connection itself. + /// An empty stream, deliberately. 's remarks say why. + private async IAsyncEnumerable ListenCoreAsync( + [EnumeratorCancellation] CancellationToken cancellationToken) { - // Which token fired is the whole difference, and IConversationInputPort.ListenAsync settles - // it: the connection ending is the ordinary end of the conversation and completes this stream, - // while the consumer's own cancellation throws, as any cancelled await does. Rethrown - // through the caller's token rather than by letting the linked one out, so the exception - // names the token the caller actually cancelled. Both fired at once counts as - // cancellation: the consumer asked to stop, and it gets the answer it asked for. - cancellationToken.ThrowIfCancellationRequested(); + // Linked, so the caller's own token ends the stream too, and built from the captured + // connection token rather than from _cancellation.Token for the reason that field records. + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(_connectionToken, cancellationToken); + + try + { + await Task.Delay(Timeout.InfiniteTimeSpan, linked.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + // Which token fired is the whole difference, and IConversationInputPort.ListenAsync settles + // it: the connection ending is the ordinary end of the conversation and completes this stream, + // while the consumer's own cancellation throws, as any cancelled await does. Rethrown + // through the caller's token rather than by letting the linked one out, so the exception + // names the token the caller actually cancelled. Both fired at once counts as + // cancellation: the consumer asked to stop, and it gets the answer it asked for. + cancellationToken.ThrowIfCancellationRequested(); + } + + yield break; } - yield break; + /// Reads the newest reply generation a barge-in has cut off, or 0 when none has. + /// The counter, read the same way the write loop's own gate reads it. + private long CurrentGeneration() + { + return Interlocked.Read(ref _replyGeneration); + } } - /// Reads the newest reply generation a barge-in has cut off, or 0 when none has. - /// The counter, read the same way the write loop's own gate reads it. - private long CurrentGeneration() => Interlocked.Read(ref _replyGeneration); -} + /// The relay broke the contract, and the socket must close with a reason. + /// The close status the vendor should see. + /// Why the endpoint refused. + internal sealed class RelayProtocolException(WebSocketCloseStatus status, string message) + : Exception(message) + { + /// Gets the status the socket closes with. + public WebSocketCloseStatus Status { get; } = status; + } -/// The relay broke the contract, and the socket must close with a reason. -/// The close status the vendor should see. -/// Why the endpoint refused. -internal sealed class RelayProtocolException(WebSocketCloseStatus status, string message) - : Exception(message) -{ - /// Gets the status the socket closes with. - public WebSocketCloseStatus Status { get; } = status; + /// One item queued for the write loop, carrying the reply generation it was written under. + /// + /// The reply generation was queued under, or for a + /// frame no reply owns — nothing writes one of those yet, but the write loop's gate only applies + /// when a generation is present, so a future frame outside the reply lifecycle (a close handoff, + /// for one) can opt out by carrying none. This type never reaches : + /// only is serialized, so nothing here changes the wire. + /// + /// The frame to serialize and send: a today. + internal readonly record struct OutboundItem(long? Generation, object Frame); } - -/// One item queued for the write loop, carrying the reply generation it was written under. -/// -/// The reply generation was queued under, or for a -/// frame no reply owns — nothing writes one of those yet, but the write loop's gate only applies -/// when a generation is present, so a future frame outside the reply lifecycle (a close handoff, -/// for one) can opt out by carrying none. This type never reaches : -/// only is serialized, so nothing here changes the wire. -/// -/// The frame to serialize and send: a today. -internal readonly record struct OutboundItem(long? Generation, object Frame); diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayContracts.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayContracts.cs index 525003ad..b8c7fc04 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayContracts.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayContracts.cs @@ -1,89 +1,90 @@ -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// One frame of the Telnyx Conversation Relay socket, inbound. -/// -/// -/// -/// Section 7.1 makes this a wire format and not a port. The vendor boundary moved from audio to -/// text with D28, so no frame here carries a buffer, a codec, a sample rate, or a playback clock. -/// Item 6c of section 11 asks for exactly that, and this file is where it holds. -/// -/// -/// One discriminator names the frame, as section 3.2 taught: model the field, not one type for -/// each value. These records stay in the adapter, and D8 keeps them out of the core. -/// -/// -internal abstract record RelayFrame +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// The first frame of a conversation. It names every id the conversation will need. - /// The relay session. - /// The conversation, in the vendor vocabulary. - /// - /// The handle the Conversation Control API accepts. Slice 2 needs it for the conference warm transfer - /// of section 4.3, and this frame is the only place it reaches the socket. - /// - /// - /// The group of legs that belong to one logical conversation. It becomes the AgentCore conversation id, - /// because it survives a transfer and a single leg id does not. - /// - /// The caller number. - /// The number the caller dialled. - /// Per-conversation values the host attached, or null. - internal sealed record Setup( - string SessionId, - string CallSid, - string CallControlId, - string ConversationSessionId, - string From, - string To, - IReadOnlyDictionary? CustomParameters) : RelayFrame; + /// + /// One frame of the Telnyx Conversation Relay socket, inbound. + /// + /// + /// + /// Section 7.1 makes this a wire format and not a port. The vendor boundary moved from audio to + /// text with D28, so no frame here carries a buffer, a codec, a sample rate, or a playback clock. + /// Item 6c of section 11 asks for exactly that, and this file is where it holds. + /// + /// + /// One discriminator names the frame, as section 3.2 taught: model the field, not one type for + /// each value. These records stay in the adapter, and D8 keeps them out of the core. + /// + /// + internal abstract record RelayFrame + { + /// The first frame of a conversation. It names every id the conversation will need. + /// The relay session. + /// The conversation, in the vendor vocabulary. + /// + /// The handle the Conversation Control API accepts. Slice 2 needs it for the conference warm transfer + /// of section 4.3, and this frame is the only place it reaches the socket. + /// + /// + /// The group of legs that belong to one logical conversation. It becomes the AgentCore conversation id, + /// because it survives a transfer and a single leg id does not. + /// + /// The caller number. + /// The number the caller dialled. + /// Per-conversation values the host attached, or null. + internal sealed record Setup( + string SessionId, + string CallSid, + string CallControlId, + string ConversationSessionId, + string From, + string To, + IReadOnlyDictionary? CustomParameters) : RelayFrame; - /// The caller spoke. - /// What the recognizer heard. - /// The language it reported, for example en. - /// - /// marks the end of the turn. is an interim - /// transcript, and the relay sends many of those. The connection drops every interim frame, - /// because one turn for each partial word would run the model many times over. - /// - internal sealed record Prompt(string VoicePrompt, string Lang, bool Last) : RelayFrame; + /// The caller spoke. + /// What the recognizer heard. + /// The language it reported, for example en. + /// + /// marks the end of the turn. is an interim + /// transcript, and the relay sends many of those. The connection drops every interim frame, + /// because one turn for each partial word would run the model many times over. + /// + internal sealed record Prompt(string VoicePrompt, string Lang, bool Last) : RelayFrame; - /// The caller spoke over the reply. THIS IS THE TRUNCATION RECORD. - /// The text the caller actually heard. - /// - /// How much of the reply played, in milliseconds, as the vendor measured it. Neither value is - /// estimated, which is the whole of D28. Item 6a of section 11 asks for the first one. - /// - internal sealed record Interrupt(string UtteranceUntilInterrupt, int DurationUntilInterruptMs) : RelayFrame; + /// The caller spoke over the reply. THIS IS THE TRUNCATION RECORD. + /// The text the caller actually heard. + /// + /// How much of the reply played, in milliseconds, as the vendor measured it. Neither value is + /// estimated, which is the whole of D28. Item 6a of section 11 asks for the first one. + /// + internal sealed record Interrupt(string UtteranceUntilInterrupt, int DurationUntilInterruptMs) : RelayFrame; - /// The caller pressed one key. - /// The key. The wire field is singular. - internal sealed record Dtmf(string Digit) : RelayFrame; + /// The caller pressed one key. + /// The key. The wire field is singular. + internal sealed record Dtmf(string Digit) : RelayFrame; - /// The vendor refused a frame this application sent. - /// Why it refused. This reports our defect, not a conversation fault. - internal sealed record Error(string Description) : RelayFrame; -} + /// The vendor refused a frame this application sent. + /// Why it refused. This reports our defect, not a conversation fault. + internal sealed record Error(string Description) : RelayFrame; + } -/// One piece of the reply, outbound. -/// The text to speak. -/// Whether this piece closes the reply. -/// -/// The vendor needs the discriminator on every outbound frame, and it counts a frame without one -/// as malformed. Repeated malformed frames make the vendor close the socket, so -/// is a property and not a caller's responsibility. -/// -internal sealed record RelayToken(string Token, bool Last) -{ - /// Gets the wire discriminator. - public string Type { get; } = "text"; -} + /// One piece of the reply, outbound. + /// The text to speak. + /// Whether this piece closes the reply. + /// + /// The vendor needs the discriminator on every outbound frame, and it counts a frame without one + /// as malformed. Repeated malformed frames make the vendor close the socket, so + /// is a property and not a caller's responsibility. + /// + internal sealed record RelayToken(string Token, bool Last) + { + /// Gets the wire discriminator. + public string Type { get; } = "text"; + } -/// Hands the conversation back to the vendor, outbound. -/// Anything the next step should read, or null. -internal sealed record RelayEnd(string? HandoffData) -{ - /// Gets the wire discriminator. - public string Type { get; } = "end"; + /// Hands the conversation back to the vendor, outbound. + /// Anything the next step should read, or null. + internal sealed record RelayEnd(string? HandoffData) + { + /// Gets the wire discriminator. + public string Type { get; } = "end"; + } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationAdapter.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationAdapter.cs index 48e7e23e..c6ca5676 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationAdapter.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationAdapter.cs @@ -3,130 +3,133 @@ using AgentCore.AspNetCore.Conversation; using Microsoft.AspNetCore.Http; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// The Telnyx Conversation Relay as a conversation transport: it owns the socket and speaks Telnyx frames. -/// -/// -/// -/// D28 buys the whole speech layer — recognition, turn detection, synthesis, and interruption — -/// inside the relay, so is and both speech roles, -/// providers.speech.stt and providers.speech.tts, must name this same vendor. -/// -/// -/// This owns only the route. TelnyxRelayConnection is still what a conversation runs on, and -/// TelnyxRelayConversationChannelFactory is still what hands out its two ports. -/// -/// -public sealed class TelnyxRelayConversationAdapter : IConversationTransportAdapter +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// The one providers.conversation.kind value this vendor answers to. - public const string TelnyxRelayKind = "telnyx-relay"; - - /// The longest delay Task.Delay, CancelAfter, and Task.WaitAsync all accept. + /// + /// The Telnyx Conversation Relay as a conversation transport: it owns the socket and speaks Telnyx frames. + /// /// - /// One millisecond short of — about 49.7 days — confirmed on net10 - /// for all three. The schema caps the document at 4294967 whole seconds for the same reason; - /// this check stays because the schema cannot express the ceiling without duplicating the - /// runtime constant. + /// + /// D28 buys the whole speech layer — recognition, turn detection, synthesis, and interruption — + /// inside the relay, so is and both speech roles, + /// providers.speech.stt and providers.speech.tts, must name this same vendor. + /// + /// + /// This owns only the route. TelnyxRelayConnection is still what a conversation runs on, and + /// TelnyxRelayConversationChannelFactory is still what hands out its two ports. + /// /// - private static readonly TimeSpan MaximumBoundedDelay = TimeSpan.FromMilliseconds(uint.MaxValue - 1); - - /// - public string Kind => TelnyxRelayKind; - - /// - /// The relay's frames carry text: the vendor performs recognition and synthesis itself. - public bool CarriesText => true; - - /// - public RequestDelegate CreateHandler(ConversationProviderConfiguration configuration) + public sealed class TelnyxRelayConversationAdapter : IConversationTransportAdapter { - ArgumentNullException.ThrowIfNull(configuration); + /// The one providers.conversation.kind value this vendor answers to. + public const string TelnyxRelayKind = "telnyx-relay"; + + /// The longest delay Task.Delay, CancelAfter, and Task.WaitAsync all accept. + /// + /// One millisecond short of — about 49.7 days — confirmed on net10 + /// for all three. The schema caps the document at 4294967 whole seconds for the same reason; + /// this check stays because the schema cannot express the ceiling without duplicating the + /// runtime constant. + /// + private static readonly TimeSpan MaximumBoundedDelay = TimeSpan.FromMilliseconds(uint.MaxValue - 1); + + /// + public string Kind => TelnyxRelayKind; + + /// + /// The relay's frames carry text: the vendor performs recognition and synthesis itself. + public bool CarriesText => true; + + /// + public RequestDelegate CreateHandler(ConversationProviderConfiguration configuration) + { + ArgumentNullException.ThrowIfNull(configuration); - var options = BuildOptions(configuration); - return http => TelnyxRelayEndpointRouteBuilderExtensions.HandleAsync(http, options); - } + TelnyxRelayOptions options = BuildOptions(configuration); + return http => TelnyxRelayEndpointRouteBuilderExtensions.HandleAsync(http, options); + } - /// Turns the document's limits into the options the endpoint runs on. - /// The providers.conversation block. - /// The options, with the shipped default kept for every value the document omits. - /// - /// A value would be refused at run time by Task.Delay, CancelAfter, or - /// Task.WaitAsync, or a frame cap is not positive. The pointer names the exact field. - /// - /// - /// It throws and not - /// because the value came from a document rather than - /// from a C# caller, and a reader needs the line to fix rather than a property name. - /// - internal static TelnyxRelayOptions BuildOptions(ConversationProviderConfiguration configuration) - { - ArgumentNullException.ThrowIfNull(configuration); + /// Turns the document's limits into the options the endpoint runs on. + /// The providers.conversation block. + /// The options, with the shipped default kept for every value the document omits. + /// + /// A value would be refused at run time by Task.Delay, CancelAfter, or + /// Task.WaitAsync, or a frame cap is not positive. The pointer names the exact field. + /// + /// + /// It throws and not + /// because the value came from a document rather than + /// from a C# caller, and a reader needs the line to fix rather than a property name. + /// + internal static TelnyxRelayOptions BuildOptions(ConversationProviderConfiguration configuration) + { + ArgumentNullException.ThrowIfNull(configuration); - var options = new TelnyxRelayOptions(); + TelnyxRelayOptions options = new(); - if (configuration.MaxFrameBytes is { } frame) - { - // Every frame is measured against this before it is written into the message buffer. - // Zero or less would refuse the first byte of every message forever, which is not a - // limit — it is a conversation nobody could ever place. - if (frame <= 0) + if (configuration.MaxFrameBytes is { } frame) { - throw Fail("maxFrameBytes", $"must be positive, and it is {frame}."); + // Every frame is measured against this before it is written into the message buffer. + // Zero or less would refuse the first byte of every message forever, which is not a + // limit — it is a conversation nobody could ever place. + if (frame <= 0) + { + throw Fail("maxFrameBytes", $"must be positive, and it is {frame}."); + } + + options.MaxFrameBytes = frame; } - options.MaxFrameBytes = frame; - } + if (configuration.IdleTimeoutSeconds is { } idle) + { + options.IdleTimeout = ToTimeSpan("idleTimeoutSeconds", idle); + } - if (configuration.IdleTimeoutSeconds is { } idle) - { - options.IdleTimeout = ToTimeSpan("idleTimeoutSeconds", idle); + if (configuration.CloseTimeoutSeconds is { } close) + { + options.CloseTimeout = ToTimeSpan("closeTimeoutSeconds", close); + } + + return options; } - if (configuration.CloseTimeoutSeconds is { } close) + /// Turns whole seconds from the document into the span a bounded wait accepts. + /// The providers.conversation field the value came from, for the pointer. + /// The whole seconds the document wrote. + /// The span, or for -1. + private static TimeSpan ToTimeSpan(string field, int seconds) { - options.CloseTimeout = ToTimeSpan("closeTimeoutSeconds", close); - } + if (seconds == -1) + { + return Timeout.InfiniteTimeSpan; + } - return options; - } + if (seconds < 0) + { + throw Fail(field, $"must be -1 for never, or zero or more seconds, and it is {seconds}."); + } - /// Turns whole seconds from the document into the span a bounded wait accepts. - /// The providers.conversation field the value came from, for the pointer. - /// The whole seconds the document wrote. - /// The span, or for -1. - private static TimeSpan ToTimeSpan(string field, int seconds) - { - if (seconds == -1) - { - return Timeout.InfiniteTimeSpan; + TimeSpan value = TimeSpan.FromSeconds(seconds); + return value <= MaximumBoundedDelay + ? value + : throw Fail( + field, + $"is {seconds} seconds, which Task.Delay, CancelAfter, and Task.WaitAsync all " + + $"refuse at run time. The longest a timer can hold is {MaximumBoundedDelay}."); } - if (seconds < 0) + /// Builds the one failure every check here raises, pointed at the field. + /// The providers.conversation field that is wrong. + /// What is wrong with it, in the words a reader can act on. + /// The failure to throw. + private static ConfigurationLoadException Fail(string field, string problem) { - throw Fail(field, $"must be -1 for never, or zero or more seconds, and it is {seconds}."); + return new(new ConfigurationError + { + Pointer = $"/providers/conversation/{field}", + Message = $"providers.conversation.{field} {problem}", + Check = ConfigurationCheck.ReferenceResolution, + }); } - - var value = TimeSpan.FromSeconds(seconds); - return value <= MaximumBoundedDelay - ? value - : throw Fail( - field, - $"is {seconds} seconds, which Task.Delay, CancelAfter, and Task.WaitAsync all " - + $"refuse at run time. The longest a timer can hold is {MaximumBoundedDelay}."); } - - /// Builds the one failure every check here raises, pointed at the field. - /// The providers.conversation field that is wrong. - /// What is wrong with it, in the words a reader can act on. - /// The failure to throw. - private static ConfigurationLoadException Fail(string field, string problem) - => new(new ConfigurationError - { - Pointer = $"/providers/conversation/{field}", - Message = $"providers.conversation.{field} {problem}", - Check = ConfigurationCheck.ReferenceResolution, - }); } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationChannelFactory.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationChannelFactory.cs index da0caaf1..ae5e047f 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationChannelFactory.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayConversationChannelFactory.cs @@ -1,47 +1,48 @@ using AgentCore.Application.Conversation; using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// Opens a Telnyx relay channel, where one connection is both halves. -/// -/// -/// Which of the two shapes this is, and why. A relay connection is born from an accepted -/// WebSocket rather than from a caller, so there is no moment at which something above asks this -/// factory to go and open a conversation: by the time a channel could exist, the socket is already up and -/// the connection already owns it. The other shape on offer was to reach the connection through -/// , and that context carries a conversation id and the host's own -/// per-conversation values and no vendor field at all — which is exactly what makes D8 hold, and exactly -/// why it cannot smuggle a connection through. So the entry point stays -/// , -/// app.MapCall() is untouched, and this factory is built with the connection it hands out. -/// -/// -/// Nothing wires it into the container yet, and nothing can even construct it yet: the connection -/// it takes has a private constructor and -/// keeps the only instance to itself. That is deliberate, not an oversight. The caller that will -/// need a factory is the split adapter — a recognizer on one side and a synthesizer on the other — -/// which does open its channel on request; whichever of the two arrives first, that adapter or a -/// reason for this connection to hand itself out, is the change that gives this type its first -/// caller. It exists now so that adapter meets an interface with a bundled implementation already -/// behind it, and so the bundled case is written down as the ordinary one rather than the exception. -/// -/// -/// The connection that accepted this conversation's socket, and that is both halves of it. -internal sealed class TelnyxRelayConversationChannelFactory(TelnyxRelayConnection connection) : IConversationChannelFactory +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// + /// Opens a Telnyx relay channel, where one connection is both halves. /// - /// is read for nothing, and the conversation id in it least of all: this - /// vendor names the conversation on its own setup frame, and the connection is already answering that - /// conversation by the time anything here could run. A future factory that really does open a conversation — - /// the split adapter's — is where those values start to matter. + /// + /// Which of the two shapes this is, and why. A relay connection is born from an accepted + /// WebSocket rather than from a caller, so there is no moment at which something above asks this + /// factory to go and open a conversation: by the time a channel could exist, the socket is already up and + /// the connection already owns it. The other shape on offer was to reach the connection through + /// , and that context carries a conversation id and the host's own + /// per-conversation values and no vendor field at all — which is exactly what makes D8 hold, and exactly + /// why it cannot smuggle a connection through. So the entry point stays + /// , + /// app.MapCall() is untouched, and this factory is built with the connection it hands out. + /// + /// + /// Nothing wires it into the container yet, and nothing can even construct it yet: the connection + /// it takes has a private constructor and + /// keeps the only instance to itself. That is deliberate, not an oversight. The caller that will + /// need a factory is the split adapter — a recognizer on one side and a synthesizer on the other — + /// which does open its channel on request; whichever of the two arrives first, that adapter or a + /// reason for this connection to hand itself out, is the change that gives this type its first + /// caller. It exists now so that adapter meets an interface with a bundled implementation already + /// behind it, and so the bundled case is written down as the ordinary one rather than the exception. + /// /// - public ValueTask OpenAsync( - ConversationChannelContext context, - CancellationToken cancellationToken = default) + /// The connection that accepted this conversation's socket, and that is both halves of it. + internal sealed class TelnyxRelayConversationChannelFactory(TelnyxRelayConnection connection) : IConversationChannelFactory { - // The same object in both slots. Nothing above this line can tell, and nothing may ask. - return ValueTask.FromResult(new ConversationChannel(connection, connection)); + /// + /// + /// is read for nothing, and the conversation id in it least of all: this + /// vendor names the conversation on its own setup frame, and the connection is already answering that + /// conversation by the time anything here could run. A future factory that really does open a conversation — + /// the split adapter's — is where those values start to matter. + /// + public ValueTask OpenAsync( + ConversationChannelContext context, + CancellationToken cancellationToken = default) + { + // The same object in both slots. Nothing above this line can tell, and nothing may ask. + return ValueTask.FromResult(new ConversationChannel(connection, connection)); + } } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayEndpoints.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayEndpoints.cs index 05ac9dc9..a041ac99 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayEndpoints.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayEndpoints.cs @@ -1,93 +1,95 @@ +using System.Net.WebSockets; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Http.Features; using Microsoft.AspNetCore.Routing; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// Maps the Telnyx Conversation Relay socket onto the turn loop. -/// -/// -/// -/// This is the second inbound adapter onto , and -/// the first one that carries a conversation. The /v1/responses endpoint is the other. Both -/// read the same contract, so D8 holds and the core never learns a vendor frame schema. -/// -/// -/// Nothing here decides whether this transport is in use. The composition root reads -/// providers.conversation while the host starts, picks the one transport it names, and asks it for a -/// handler through ; -/// -/// owns only the route string. This type maps whatever it is handed, and it is -/// so that is the only thing that -/// hands it anything, apart from the test host, through InternalsVisibleTo: a host names its -/// route once and changes vendors in the document. -/// -/// -/// The host owns the WebSocket middleware, and its defaults suit a browser rather than a conversation. -/// Conversation app.UseWebSockets with a KeepAliveInterval and a KeepAliveTimeout of -/// about 20 seconds. The shipped default is two minutes with no timeout, which lets a dead conversation -/// hold a session for two minutes. -/// -/// -internal static class TelnyxRelayEndpointRouteBuilderExtensions +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// The route the test host maps this endpoint on. - /// - /// It is no longer a fallback: MapCall always supplies a pattern, so no production path - /// reaches this value. It is kept because the relay suite maps its host through - /// directly and needs one route string both sides agree on. - /// - public const string DefaultPattern = "/v1/{" + Conversation.ConversationEndpointRouteBuilderExtensions.EntryRouteParameter + "}/telnyx/relay"; - - /// Maps the socket on one route, with the limits the host chose. - /// The route builder of the host. - /// The route to answer on. It must carry the {entry} parameter. - /// What the endpoint may do, and for how long. - /// The mapped endpoint, so a host adds its own conventions. + /// + /// Maps the Telnyx Conversation Relay socket onto the turn loop. + /// /// - /// The options are not checked here. is what - /// builds them out of providers.conversation, and it refuses a value Task.Delay, - /// CancelAfter, or Task.WaitAsync would reject before that value is ever written - /// into a — with a - /// naming the field of - /// the document rather than a C# property. Checking again here would only repeat that work in - /// the wrong vocabulary. + /// + /// This is the second inbound adapter onto , and + /// the first one that carries a conversation. The /v1/responses endpoint is the other. Both + /// read the same contract, so D8 holds and the core never learns a vendor frame schema. + /// + /// + /// Nothing here decides whether this transport is in use. The composition root reads + /// providers.conversation while the host starts, picks the one transport it names, and asks it for a + /// handler through ; + /// + /// owns only the route string. This type maps whatever it is handed, and it is + /// so that is the only thing that + /// hands it anything, apart from the test host, through InternalsVisibleTo: a host names its + /// route once and changes vendors in the document. + /// + /// + /// The host owns the WebSocket middleware, and its defaults suit a browser rather than a conversation. + /// Conversation app.UseWebSockets with a KeepAliveInterval and a KeepAliveTimeout of + /// about 20 seconds. The shipped default is two minutes with no timeout, which lets a dead conversation + /// hold a session for two minutes. + /// /// - public static IEndpointConventionBuilder MapTelnyxRelay( - this IEndpointRouteBuilder endpoints, - string pattern, - TelnyxRelayOptions options) + internal static class TelnyxRelayEndpointRouteBuilderExtensions { - ArgumentNullException.ThrowIfNull(endpoints); - ArgumentException.ThrowIfNullOrEmpty(pattern); - ArgumentNullException.ThrowIfNull(options); - - // Map, and not MapGet. An HTTP/2 WebSocket arrives as CONNECT rather than GET, and MapGet - // would answer 405 to it. - return endpoints.Map(pattern, (HttpContext http) => HandleAsync(http, options)); - } + /// The route the test host maps this endpoint on. + /// + /// It is no longer a fallback: MapCall always supplies a pattern, so no production path + /// reaches this value. It is kept because the relay suite maps its host through + /// directly and needs one route string both sides agree on. + /// + public const string DefaultPattern = "/v1/{" + Conversation.ConversationEndpointRouteBuilderExtensions.EntryRouteParameter + "}/telnyx/relay"; - internal static async Task HandleAsync(HttpContext http, TelnyxRelayOptions options) - { - if (http.Features.Get() is null) + /// Maps the socket on one route, with the limits the host chose. + /// The route builder of the host. + /// The route to answer on. It must carry the {entry} parameter. + /// What the endpoint may do, and for how long. + /// The mapped endpoint, so a host adds its own conventions. + /// + /// The options are not checked here. is what + /// builds them out of providers.conversation, and it refuses a value Task.Delay, + /// CancelAfter, or Task.WaitAsync would reject before that value is ever written + /// into a — with a + /// naming the field of + /// the document rather than a C# property. Checking again here would only repeat that work in + /// the wrong vocabulary. + /// + public static IEndpointConventionBuilder MapTelnyxRelay( + this IEndpointRouteBuilder endpoints, + string pattern, + TelnyxRelayOptions options) { - throw new InvalidOperationException( - "the relay endpoint needs the WebSocket middleware. Call app.UseWebSockets() before " - + "app.MapCall()."); + ArgumentNullException.ThrowIfNull(endpoints); + ArgumentException.ThrowIfNullOrEmpty(pattern); + ArgumentNullException.ThrowIfNull(options); + + // Map, and not MapGet. An HTTP/2 WebSocket arrives as CONNECT rather than GET, and MapGet + // would answer 405 to it. + return endpoints.Map(pattern, http => HandleAsync(http, options)); } - if (!http.WebSockets.IsWebSocketRequest) + internal static async Task HandleAsync(HttpContext http, TelnyxRelayOptions options) { - http.Response.StatusCode = StatusCodes.Status400BadRequest; - return; - } + if (http.Features.Get() is null) + { + throw new InvalidOperationException( + "the relay endpoint needs the WebSocket middleware. Call app.UseWebSockets() before " + + "app.MapCall()."); + } - using var socket = await http.WebSockets.AcceptWebSocketAsync().ConfigureAwait(false); + if (!http.WebSockets.IsWebSocketRequest) + { + http.Response.StatusCode = StatusCodes.Status400BadRequest; + return; + } - // The pipeline must stay on the stack for the whole life of the socket. A handler that - // returns early gets "Cannot write to the response body, the response has completed". - await TelnyxRelayConnection.RunAsync(http, socket, options).ConfigureAwait(false); + using WebSocket socket = await http.WebSockets.AcceptWebSocketAsync().ConfigureAwait(false); + + // The pipeline must stay on the stack for the whole life of the socket. A handler that + // returns early gets "Cannot write to the response body, the response has completed". + await TelnyxRelayConnection.RunAsync(http, socket, options).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayFrameReader.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayFrameReader.cs index b14dc09c..db4e9897 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayFrameReader.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayFrameReader.cs @@ -1,112 +1,113 @@ using System.Text.Json; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// Reads one inbound relay frame, and never throws on what the vendor sent. -/// -/// -/// -/// The switch below is written by hand on purpose. System.Text.Json polymorphic deserialization -/// cannot express the rule of section 7.1, because its ignore option reverts to the contract of -/// the base type and is abstract. It also wants the discriminator first, -/// and nothing in the vendor contract promises that. -/// -/// -/// A vendor that adds a frame must not be able to drop a conversation, so an unmodelled type is refused -/// and named rather than thrown. The caller logs the name once for the conversation, not once for the -/// frame, per section 3.1. -/// -/// -/// A vendor that changes a frame must not be able to drop one either, and section 7.1 draws -/// no line between the two. A known type whose body will not bind is therefore a third -/// answer, apart from both "here is your frame" and "these bytes are not readable at all": the -/// frame is refused, the socket lives, and the conversation goes on. Two shapes reach it from the live -/// wire — a decimal durationUntilInterruptMs, which would otherwise end a conversation at the exact -/// moment of a barge-in, and a non-string value inside customParameters, which would -/// otherwise end it on the setup frame before it began. -/// -/// -internal static class TelnyxRelayFrameReader +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// Reads one frame from the bytes of one WebSocket message. - /// The whole message, already reassembled. - /// The frame, or when this build did not read one. - /// - /// The type value that no case matched, or when the type was one - /// this build models or the bytes carried no readable type at all. - /// - /// - /// The type value whose body would not bind, or when the body bound - /// or there was no readable type. A caller tells this apart from - /// because the two need different answers: an unmodelled type is a frame from a later version of - /// the vendor, and a refused body is a field of a frame this build does know. - /// - /// when holds a frame. + /// + /// Reads one inbound relay frame, and never throws on what the vendor sent. + /// /// - /// A answer with both names is the only - /// unreadable case: the bytes are not JSON, not an object, or carry no string type. That - /// is the one the caller may close the socket over. + /// + /// The switch below is written by hand on purpose. System.Text.Json polymorphic deserialization + /// cannot express the rule of section 7.1, because its ignore option reverts to the contract of + /// the base type and is abstract. It also wants the discriminator first, + /// and nothing in the vendor contract promises that. + /// + /// + /// A vendor that adds a frame must not be able to drop a conversation, so an unmodelled type is refused + /// and named rather than thrown. The caller logs the name once for the conversation, not once for the + /// frame, per section 3.1. + /// + /// + /// A vendor that changes a frame must not be able to drop one either, and section 7.1 draws + /// no line between the two. A known type whose body will not bind is therefore a third + /// answer, apart from both "here is your frame" and "these bytes are not readable at all": the + /// frame is refused, the socket lives, and the conversation goes on. Two shapes reach it from the live + /// wire — a decimal durationUntilInterruptMs, which would otherwise end a conversation at the exact + /// moment of a barge-in, and a non-string value inside customParameters, which would + /// otherwise end it on the setup frame before it began. + /// /// - public static bool TryRead( - ReadOnlySpan utf8, - out RelayFrame? frame, - out string? unknownType, - out string? refusedType) + internal static class TelnyxRelayFrameReader { - frame = null; - unknownType = null; - refusedType = null; - - JsonDocument document; - try - { - // A vendor payload never throws across this seam. - var reader = new Utf8JsonReader(utf8); - document = JsonDocument.ParseValue(ref reader); - } - catch (JsonException) - { - return false; - } - - using (document) + /// Reads one frame from the bytes of one WebSocket message. + /// The whole message, already reassembled. + /// The frame, or when this build did not read one. + /// + /// The type value that no case matched, or when the type was one + /// this build models or the bytes carried no readable type at all. + /// + /// + /// The type value whose body would not bind, or when the body bound + /// or there was no readable type. A caller tells this apart from + /// because the two need different answers: an unmodelled type is a frame from a later version of + /// the vendor, and a refused body is a field of a frame this build does know. + /// + /// when holds a frame. + /// + /// A answer with both names is the only + /// unreadable case: the bytes are not JSON, not an object, or carry no string type. That + /// is the one the caller may close the socket over. + /// + public static bool TryRead( + ReadOnlySpan utf8, + out RelayFrame? frame, + out string? unknownType, + out string? refusedType) { - if (document.RootElement.ValueKind != JsonValueKind.Object - || !document.RootElement.TryGetProperty("type", out var type) - || type.ValueKind != JsonValueKind.String) - { - return false; - } + frame = null; + unknownType = null; + refusedType = null; - var name = type.GetString()!; + JsonDocument document; try { - frame = name switch - { - "setup" => document.Deserialize(TelnyxRelayJson.Options), - "prompt" => document.Deserialize(TelnyxRelayJson.Options), - "interrupt" => document.Deserialize(TelnyxRelayJson.Options), - "dtmf" => document.Deserialize(TelnyxRelayJson.Options), - "error" => document.Deserialize(TelnyxRelayJson.Options), - _ => null, - }; + // A vendor payload never throws across this seam. + Utf8JsonReader reader = new(utf8); + document = JsonDocument.ParseValue(ref reader); } catch (JsonException) { - // The type is one this build knows, so the bytes are readable and only a field is - // wrong. Section 7.1: that is a refused frame, never a refused conversation. - refusedType = name; return false; } - if (frame is null) + using (document) { - unknownType = name; - return false; - } + if (document.RootElement.ValueKind != JsonValueKind.Object + || !document.RootElement.TryGetProperty("type", out JsonElement type) + || type.ValueKind != JsonValueKind.String) + { + return false; + } + + string name = type.GetString()!; + try + { + frame = name switch + { + "setup" => document.Deserialize(TelnyxRelayJson.Options), + "prompt" => document.Deserialize(TelnyxRelayJson.Options), + "interrupt" => document.Deserialize(TelnyxRelayJson.Options), + "dtmf" => document.Deserialize(TelnyxRelayJson.Options), + "error" => document.Deserialize(TelnyxRelayJson.Options), + _ => null, + }; + } + catch (JsonException) + { + // The type is one this build knows, so the bytes are readable and only a field is + // wrong. Section 7.1: that is a refused frame, never a refused conversation. + refusedType = name; + return false; + } - return true; + if (frame is null) + { + unknownType = name; + return false; + } + + return true; + } } } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayJson.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayJson.cs index b0ba31d0..9d075c77 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayJson.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayJson.cs @@ -1,21 +1,22 @@ using System.Text.Json; using System.Text.Json.Serialization; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// The one serializer setting of the relay wire. -/// -/// -/// gives camelCase names and case-insensitive reads, -/// which is exactly what the vendor sends and expects. One shared instance avoids the per-conversation -/// options cache that a fresh instance would rebuild for every frame. -/// -internal static class TelnyxRelayJson +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// Gets the options every read and every write of this wire uses. - public static JsonSerializerOptions Options { get; } = new(JsonSerializerDefaults.Web) + /// + /// The one serializer setting of the relay wire. + /// + /// + /// gives camelCase names and case-insensitive reads, + /// which is exactly what the vendor sends and expects. One shared instance avoids the per-conversation + /// options cache that a fresh instance would rebuild for every frame. + /// + internal static class TelnyxRelayJson { - DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, - }; + /// Gets the options every read and every write of this wire uses. + public static JsonSerializerOptions Options { get; } = new(JsonSerializerDefaults.Web) + { + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, + }; + } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayLog.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayLog.cs index e32851d5..b1d3cd8a 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayLog.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayLog.cs @@ -1,323 +1,324 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// Every line the relay connection writes. -/// -/// -/// -/// The methods are source-generated by , so a line that nobody -/// listens to costs one level check and allocates nothing. CA1848 asks for exactly this shape -/// rather than a direct conversation on . -/// -/// -/// No line here carries what the caller said or pressed. The audit chain of D23 is the record of a -/// conversation, and a log is not; a keypad in particular carries card numbers, PINs, and dates of birth. -/// -/// -internal static partial class TelnyxRelayLog +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// Section 3.1. An unmodelled frame type, logged once for the conversation. - /// The logger of the connection. - /// The type value no case matched. - /// The id of the conversation, or a placeholder before setup. - [LoggerMessage( - EventId = 1, - Level = LogLevel.Information, - Message = "the relay sent an unmodelled frame type '{FrameType}' on conversation {ConversationId}.")] - public static partial void UnknownFrameType(ILogger logger, string frameType, string conversationId); + /// + /// Every line the relay connection writes. + /// + /// + /// + /// The methods are source-generated by , so a line that nobody + /// listens to costs one level check and allocates nothing. CA1848 asks for exactly this shape + /// rather than a direct conversation on . + /// + /// + /// No line here carries what the caller said or pressed. The audit chain of D23 is the record of a + /// conversation, and a log is not; a keypad in particular carries card numbers, PINs, and dates of birth. + /// + /// + internal static partial class TelnyxRelayLog + { + /// Section 3.1. An unmodelled frame type, logged once for the conversation. + /// The logger of the connection. + /// The type value no case matched. + /// The id of the conversation, or a placeholder before setup. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Information, + Message = "the relay sent an unmodelled frame type '{FrameType}' on conversation {ConversationId}.")] + public static partial void UnknownFrameType(ILogger logger, string frameType, string conversationId); - /// The caller pressed one key. The key itself never reaches a log line. - /// The logger of the connection. - [LoggerMessage( - EventId = 2, - Level = LogLevel.Information, - Message = "the caller pressed a key.")] - public static partial void DtmfReceived(ILogger logger); + /// The caller pressed one key. The key itself never reaches a log line. + /// The logger of the connection. + [LoggerMessage( + EventId = 2, + Level = LogLevel.Information, + Message = "the caller pressed a key.")] + public static partial void DtmfReceived(ILogger logger); - /// The vendor refused a frame this endpoint sent. That is our defect. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// Why the vendor refused it. - [LoggerMessage( - EventId = 3, - Level = LogLevel.Warning, - Message = "the relay refused a frame on conversation {ConversationId}: {Description}")] - public static partial void FrameRefused(ILogger logger, string conversationId, string description); + /// The vendor refused a frame this endpoint sent. That is our defect. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// Why the vendor refused it. + [LoggerMessage( + EventId = 3, + Level = LogLevel.Warning, + Message = "the relay refused a frame on conversation {ConversationId}: {Description}")] + public static partial void FrameRefused(ILogger logger, string conversationId, string description); - /// A prompt arrived before any setup frame, logged once for the conversation. - /// The logger of the connection. - [LoggerMessage( - EventId = 4, - Level = LogLevel.Warning, - Message = "the relay sent a prompt before any setup frame. Every prompt before setup is dropped.")] - public static partial void PromptBeforeSetup(ILogger logger); + /// A prompt arrived before any setup frame, logged once for the conversation. + /// The logger of the connection. + [LoggerMessage( + EventId = 4, + Level = LogLevel.Warning, + Message = "the relay sent a prompt before any setup frame. Every prompt before setup is dropped.")] + public static partial void PromptBeforeSetup(ILogger logger); - /// The read loop ended in a fault rather than a clean close. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// The cause. - /// - /// states the house rule: on a voice conversation, silence is - /// the failure, so this line makes sure a read loop fault is never silent. It fires for anything - /// the read loop throws other than the two causes that have their own, quieter case: a - /// logs through at - /// Warning instead, because it is a protocol violation this endpoint already refused and closed - /// on, not an unhandled defect; and a dropped socket with no close frame logs through - /// at Information. Everything else reaching this line - /// is this endpoint's own bug. - /// - [LoggerMessage( - EventId = 5, - Level = LogLevel.Error, - Message = "the relay read loop of conversation {ConversationId} ended in a fault.")] - public static partial void ReadLoopFaulted(ILogger logger, string conversationId, Exception exception); + /// The read loop ended in a fault rather than a clean close. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// The cause. + /// + /// states the house rule: on a voice conversation, silence is + /// the failure, so this line makes sure a read loop fault is never silent. It fires for anything + /// the read loop throws other than the two causes that have their own, quieter case: a + /// logs through at + /// Warning instead, because it is a protocol violation this endpoint already refused and closed + /// on, not an unhandled defect; and a dropped socket with no close frame logs through + /// at Information. Everything else reaching this line + /// is this endpoint's own bug. + /// + [LoggerMessage( + EventId = 5, + Level = LogLevel.Error, + Message = "the relay read loop of conversation {ConversationId} ended in a fault.")] + public static partial void ReadLoopFaulted(ILogger logger, string conversationId, Exception exception); - /// A turn faulted rather than finishing or being cancelled by the connection itself. - /// The logger of the connection. - /// The id of the conversation. - /// The cause. - [LoggerMessage( - EventId = 6, - Level = LogLevel.Error, - Message = "a turn of conversation {ConversationId} faulted.")] - public static partial void TurnFaulted(ILogger logger, string conversationId, Exception exception); + /// A turn faulted rather than finishing or being cancelled by the connection itself. + /// The logger of the connection. + /// The id of the conversation. + /// The cause. + [LoggerMessage( + EventId = 6, + Level = LogLevel.Error, + Message = "a turn of conversation {ConversationId} faulted.")] + public static partial void TurnFaulted(ILogger logger, string conversationId, Exception exception); - /// The write loop ended in a fault rather than a clean close. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// The cause. - /// - /// The write loop is the only task that touches the socket, so its fault — typically a - /// the relay caused, or an - /// racing teardown — is the most useful of the three to - /// see, and the one round 1 left unobserved. - /// - [LoggerMessage( - EventId = 7, - Level = LogLevel.Error, - Message = "the relay write loop of conversation {ConversationId} ended in a fault.")] - public static partial void WriteLoopFaulted(ILogger logger, string conversationId, Exception exception); + /// The write loop ended in a fault rather than a clean close. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// The cause. + /// + /// The write loop is the only task that touches the socket, so its fault — typically a + /// the relay caused, or an + /// racing teardown — is the most useful of the three to + /// see, and the one round 1 left unobserved. + /// + [LoggerMessage( + EventId = 7, + Level = LogLevel.Error, + Message = "the relay write loop of conversation {ConversationId} ended in a fault.")] + public static partial void WriteLoopFaulted(ILogger logger, string conversationId, Exception exception); - /// A bounded teardown wait expired before the task it was watching stopped. - /// The logger of the connection. - /// The id of the conversation. - /// Which task did not stop in time, for example "the last turn". - /// - /// Cancellation reaches a well-behaved task, but this line is not proof of one that ignored its - /// token — a task that honours cancellation yet takes longer than CloseTimeout to unwind, - /// a slow completion step or a slow sink, reaches it the same way. Left unbounded, either case - /// would otherwise wedge teardown forever: the session would stay in the store, and the Kestrel - /// request behind it would never complete. - /// - [LoggerMessage( - EventId = 8, - Level = LogLevel.Error, - Message = "{What} of conversation {ConversationId} did not stop before the close timeout.")] - public static partial void TeardownTimedOut(ILogger logger, string conversationId, string what); + /// A bounded teardown wait expired before the task it was watching stopped. + /// The logger of the connection. + /// The id of the conversation. + /// Which task did not stop in time, for example "the last turn". + /// + /// Cancellation reaches a well-behaved task, but this line is not proof of one that ignored its + /// token — a task that honours cancellation yet takes longer than CloseTimeout to unwind, + /// a slow completion step or a slow sink, reaches it the same way. Left unbounded, either case + /// would otherwise wedge teardown forever: the session would stay in the store, and the Kestrel + /// request behind it would never complete. + /// + [LoggerMessage( + EventId = 8, + Level = LogLevel.Error, + Message = "{What} of conversation {ConversationId} did not stop before the close timeout.")] + public static partial void TeardownTimedOut(ILogger logger, string conversationId, string what); - /// The close handshake faulted for a reason other than its own deadline or a dead peer. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// The cause. - /// - /// Logged and swallowed rather than left to propagate, because a throw here must not skip the - /// write-loop observation or the session close that follow it in RunAsync. A close that - /// never runs leaves the conversation to wait out its idle timeout, and nothing waits for the words its - /// last turn still owed store 1. - /// - [LoggerMessage( - EventId = 9, - Level = LogLevel.Error, - Message = "the close handshake of conversation {ConversationId} faulted.")] - public static partial void CloseFaulted(ILogger logger, string conversationId, Exception exception); + /// The close handshake faulted for a reason other than its own deadline or a dead peer. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// The cause. + /// + /// Logged and swallowed rather than left to propagate, because a throw here must not skip the + /// write-loop observation or the session close that follow it in RunAsync. A close that + /// never runs leaves the conversation to wait out its idle timeout, and nothing waits for the words its + /// last turn still owed store 1. + /// + [LoggerMessage( + EventId = 9, + Level = LogLevel.Error, + Message = "the close handshake of conversation {ConversationId} faulted.")] + public static partial void CloseFaulted(ILogger logger, string conversationId, Exception exception); - /// Cancelling the connection's own token faulted, from a registered callback. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// The cause. - /// - /// Logged and swallowed rather than left to propagate, because Cancel() runs with - /// throwOnFirstException: false: every callback still ran and both loops are already - /// cancelled by the time this fires, so the only thing a throw here would still cost is the - /// rest of teardown — the write-loop observation, the close, and the session removal. - /// - [LoggerMessage( - EventId = 10, - Level = LogLevel.Error, - Message = "cancelling the connection token of conversation {ConversationId} faulted.")] - public static partial void CancellationFaulted(ILogger logger, string conversationId, Exception exception); + /// Cancelling the connection's own token faulted, from a registered callback. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// The cause. + /// + /// Logged and swallowed rather than left to propagate, because Cancel() runs with + /// throwOnFirstException: false: every callback still ran and both loops are already + /// cancelled by the time this fires, so the only thing a throw here would still cost is the + /// rest of teardown — the write-loop observation, the close, and the session removal. + /// + [LoggerMessage( + EventId = 10, + Level = LogLevel.Error, + Message = "cancelling the connection token of conversation {ConversationId} faulted.")] + public static partial void CancellationFaulted(ILogger logger, string conversationId, Exception exception); - /// A third final prompt arrived while one turn ran, logged once for the conversation. - /// The logger of the connection. - /// The id of the conversation. - /// - /// Item 6a of section 11 holds one pending prompt so a caller's second sentence is not lost. - /// A third would queue a prompt behind a question the caller has already moved past, so it is - /// dropped, and this line says so without repeating the words dropped. - /// - [LoggerMessage( - EventId = 11, - Level = LogLevel.Information, - Message = "a further prompt arrived on conversation {ConversationId} while one turn was already held. It is dropped.")] - public static partial void PendingPromptDropped(ILogger logger, string conversationId); + /// A third final prompt arrived while one turn ran, logged once for the conversation. + /// The logger of the connection. + /// The id of the conversation. + /// + /// Item 6a of section 11 holds one pending prompt so a caller's second sentence is not lost. + /// A third would queue a prompt behind a question the caller has already moved past, so it is + /// dropped, and this line says so without repeating the words dropped. + /// + [LoggerMessage( + EventId = 11, + Level = LogLevel.Information, + Message = "a further prompt arrived on conversation {ConversationId} while one turn was already held. It is dropped.")] + public static partial void PendingPromptDropped(ILogger logger, string conversationId); - /// The relay reported a barge-in. Never the words the caller said. - /// The logger of the connection. - /// The id of the conversation. - [LoggerMessage( - EventId = 12, - Level = LogLevel.Information, - Message = "the relay reported a barge-in on conversation {ConversationId}.")] - public static partial void InterruptReceived(ILogger logger, string conversationId); + /// The relay reported a barge-in. Never the words the caller said. + /// The logger of the connection. + /// The id of the conversation. + [LoggerMessage( + EventId = 12, + Level = LogLevel.Information, + Message = "the relay reported a barge-in on conversation {ConversationId}.")] + public static partial void InterruptReceived(ILogger logger, string conversationId); - /// A malformed interrupt frame was refused. Section 7.1: a bad frame must not drop the conversation. - /// The logger of the connection. - /// The id of the conversation. - /// - /// Fires when utteranceUntilInterrupt is missing or durationUntilInterruptMs is - /// negative, logged once for the conversation the same way an unmodelled frame type is. - /// - [LoggerMessage( - EventId = 13, - Level = LogLevel.Warning, - Message = "the relay sent a malformed interrupt frame on conversation {ConversationId}. It is dropped.")] - public static partial void MalformedInterruptFrame(ILogger logger, string conversationId); + /// A malformed interrupt frame was refused. Section 7.1: a bad frame must not drop the conversation. + /// The logger of the connection. + /// The id of the conversation. + /// + /// Fires when utteranceUntilInterrupt is missing or durationUntilInterruptMs is + /// negative, logged once for the conversation the same way an unmodelled frame type is. + /// + [LoggerMessage( + EventId = 13, + Level = LogLevel.Warning, + Message = "the relay sent a malformed interrupt frame on conversation {ConversationId}. It is dropped.")] + public static partial void MalformedInterruptFrame(ILogger logger, string conversationId); - /// A second final prompt arrived while one turn ran, and is held for when it ends. - /// The logger of the connection. - /// The id of the conversation. - [LoggerMessage( - EventId = 14, - Level = LogLevel.Information, - Message = "a further prompt arrived on conversation {ConversationId} while one turn ran. It is held.")] - public static partial void PromptHeld(ILogger logger, string conversationId); + /// A second final prompt arrived while one turn ran, and is held for when it ends. + /// The logger of the connection. + /// The id of the conversation. + [LoggerMessage( + EventId = 14, + Level = LogLevel.Information, + Message = "a further prompt arrived on conversation {ConversationId} while one turn ran. It is held.")] + public static partial void PromptHeld(ILogger logger, string conversationId); - /// The relay dropped the socket with no close frame. Task 7: an ordinary end of a conversation. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// - /// Fires instead of for exactly one cause: a - /// whose code is - /// . The vendor - /// never reconnects, so this is a finished conversation, not a defect this endpoint owns. - /// - [LoggerMessage( - EventId = 15, - Level = LogLevel.Information, - Message = "conversation {ConversationId} ended without a close frame from the relay.")] - public static partial void ConversationDroppedWithNoCloseFrame(ILogger logger, string conversationId); + /// The relay dropped the socket with no close frame. Task 7: an ordinary end of a conversation. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// + /// Fires instead of for exactly one cause: a + /// whose code is + /// . The vendor + /// never reconnects, so this is a finished conversation, not a defect this endpoint owns. + /// + [LoggerMessage( + EventId = 15, + Level = LogLevel.Information, + Message = "conversation {ConversationId} ended without a close frame from the relay.")] + public static partial void ConversationDroppedWithNoCloseFrame(ILogger logger, string conversationId); - /// The read loop refused a frame and the connection is closing because of it. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// - /// The fixed, vendor-free message carries — never the - /// bytes the relay actually sent. - /// - /// - /// Malformed JSON and an oversized frame both reach here. Neither is this endpoint's own - /// defect — the relay broke the contract, this endpoint already refused the frame, and - /// DetermineCloseStatus already carries the right close status from the same exception — - /// so this logs at Warning, the same level , - /// , and already use for a bad - /// frame, not at the Error level uses for this endpoint's own bug. - /// - [LoggerMessage( - EventId = 16, - Level = LogLevel.Warning, - Message = "the relay read loop of conversation {ConversationId} closed the socket over a protocol violation: {Reason}")] - public static partial void RelayProtocolViolation(ILogger logger, string conversationId, string reason); + /// The read loop refused a frame and the connection is closing because of it. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// + /// The fixed, vendor-free message carries — never the + /// bytes the relay actually sent. + /// + /// + /// Malformed JSON and an oversized frame both reach here. Neither is this endpoint's own + /// defect — the relay broke the contract, this endpoint already refused the frame, and + /// DetermineCloseStatus already carries the right close status from the same exception — + /// so this logs at Warning, the same level , + /// , and already use for a bad + /// frame, not at the Error level uses for this endpoint's own bug. + /// + [LoggerMessage( + EventId = 16, + Level = LogLevel.Warning, + Message = "the relay read loop of conversation {ConversationId} closed the socket over a protocol violation: {Reason}")] + public static partial void RelayProtocolViolation(ILogger logger, string conversationId, string reason); - /// No inbound frame arrived within IdleTimeout. Task 8: an ordinary end of a conversation. - /// The logger of the connection. - /// The id of the conversation, or a placeholder before setup. - /// - /// The vendor never reconnects, so a silent socket is a conversation that is already over, not a fault - /// this endpoint owns. This fires only when the idle deadline itself is the cause: the read - /// loop checks that the connection's own teardown token has not also fired before it logs this - /// line, so a socket closed for some other reason never gets this one instead. - /// - [LoggerMessage( - EventId = 17, - Level = LogLevel.Information, - Message = "conversation {ConversationId} ended: no inbound frame arrived before the idle deadline.")] - public static partial void IdleTimeoutReached(ILogger logger, string conversationId); + /// No inbound frame arrived within IdleTimeout. Task 8: an ordinary end of a conversation. + /// The logger of the connection. + /// The id of the conversation, or a placeholder before setup. + /// + /// The vendor never reconnects, so a silent socket is a conversation that is already over, not a fault + /// this endpoint owns. This fires only when the idle deadline itself is the cause: the read + /// loop checks that the connection's own teardown token has not also fired before it logs this + /// line, so a socket closed for some other reason never gets this one instead. + /// + [LoggerMessage( + EventId = 17, + Level = LogLevel.Information, + Message = "conversation {ConversationId} ended: no inbound frame arrived before the idle deadline.")] + public static partial void IdleTimeoutReached(ILogger logger, string conversationId); - /// A frame of a known type carried a field that would not bind, logged once for the conversation. - /// The logger of the connection. - /// The type value whose body was refused. - /// The id of the conversation, or a placeholder before setup. - /// - /// Section 7.1 gives a vendor that adds a frame and a vendor that changes one the same rule: - /// neither may drop a conversation. A decimal durationUntilInterruptMs and a non-string value in - /// customParameters both reach here. This is the vendor's defect and not this endpoint's, - /// so it logs at Warning, beside and - /// , and never at the Error level a bug of ours gets. The - /// field that would not bind is not named: a value the vendor sent may carry what the caller - /// said. - /// - [LoggerMessage( - EventId = 18, - Level = LogLevel.Warning, - Message = "the relay sent a '{FrameType}' frame on conversation {ConversationId} whose body this build cannot " - + "read. It is dropped, and the conversation continues.")] - public static partial void FrameBodyRefused(ILogger logger, string frameType, string conversationId); + /// A frame of a known type carried a field that would not bind, logged once for the conversation. + /// The logger of the connection. + /// The type value whose body was refused. + /// The id of the conversation, or a placeholder before setup. + /// + /// Section 7.1 gives a vendor that adds a frame and a vendor that changes one the same rule: + /// neither may drop a conversation. A decimal durationUntilInterruptMs and a non-string value in + /// customParameters both reach here. This is the vendor's defect and not this endpoint's, + /// so it logs at Warning, beside and + /// , and never at the Error level a bug of ours gets. The + /// field that would not bind is not named: a value the vendor sent may carry what the caller + /// said. + /// + [LoggerMessage( + EventId = 18, + Level = LogLevel.Warning, + Message = "the relay sent a '{FrameType}' frame on conversation {ConversationId} whose body this build cannot " + + "read. It is dropped, and the conversation continues.")] + public static partial void FrameBodyRefused(ILogger logger, string frameType, string conversationId); - /// A second setup frame arrived on one socket, logged once for the conversation. - /// The logger of the connection. - /// The id of the conversation the first setup frame started. - /// - /// One socket carries one conversation, and the vendor sends one setup. A second one is the - /// vendor's defect, and section 7.1 forbids dropping a conversation over one, so the frame replaces the - /// session rather than refusing the socket. The first session is closed as it goes, because - /// teardown only ever closes the session the connection currently holds — so this is the last - /// moment anything waits for the words the replaced conversation still owed store 1. - /// - [LoggerMessage( - EventId = 19, - Level = LogLevel.Warning, - Message = "the relay sent a second setup frame on conversation {ConversationId}. The first session is " - + "released and the new one replaces it.")] - public static partial void SecondSetupFrame(ILogger logger, string conversationId); + /// A second setup frame arrived on one socket, logged once for the conversation. + /// The logger of the connection. + /// The id of the conversation the first setup frame started. + /// + /// One socket carries one conversation, and the vendor sends one setup. A second one is the + /// vendor's defect, and section 7.1 forbids dropping a conversation over one, so the frame replaces the + /// session rather than refusing the socket. The first session is closed as it goes, because + /// teardown only ever closes the session the connection currently holds — so this is the last + /// moment anything waits for the words the replaced conversation still owed store 1. + /// + [LoggerMessage( + EventId = 19, + Level = LogLevel.Warning, + Message = "the relay sent a second setup frame on conversation {ConversationId}. The first session is " + + "released and the new one replaces it.")] + public static partial void SecondSetupFrame(ILogger logger, string conversationId); - /// Closing the audit chain of a conversation faulted, so that call has no conversation.ended event. - /// The logger of the connection. - /// The id of the conversation whose chain did not close. - /// The cause. - /// - /// This is worth an Error line and not a quieter one. §9 makes the chain of D23 the only - /// long-term record of a conversation, and §11 item 6 says every chain ends in conversation.ended, so a - /// chain that stops without one is a permanent gap in that record rather than a passing - /// inconvenience. Logged and swallowed all the same: §7.1 forbids teardown throwing out of the - /// request handler, and the session close that follows it in RunAsync must still run — a - /// close that never runs leaves the conversation to wait out its idle timeout with its last words never - /// waited for. - /// - [LoggerMessage( - EventId = 20, - Level = LogLevel.Error, - Message = "the audit chain of conversation {ConversationId} could not be closed, so it has no conversation.ended event.")] - public static partial void ConversationEndFaulted(ILogger logger, string conversationId, Exception exception); + /// Closing the audit chain of a conversation faulted, so that call has no conversation.ended event. + /// The logger of the connection. + /// The id of the conversation whose chain did not close. + /// The cause. + /// + /// This is worth an Error line and not a quieter one. §9 makes the chain of D23 the only + /// long-term record of a conversation, and §11 item 6 says every chain ends in conversation.ended, so a + /// chain that stops without one is a permanent gap in that record rather than a passing + /// inconvenience. Logged and swallowed all the same: §7.1 forbids teardown throwing out of the + /// request handler, and the session close that follows it in RunAsync must still run — a + /// close that never runs leaves the conversation to wait out its idle timeout with its last words never + /// waited for. + /// + [LoggerMessage( + EventId = 20, + Level = LogLevel.Error, + Message = "the audit chain of conversation {ConversationId} could not be closed, so it has no conversation.ended event.")] + public static partial void ConversationEndFaulted(ILogger logger, string conversationId, Exception exception); - /// The session of a conversation could not be closed at the end of that conversation. - /// The logger. - /// The id of the conversation. - /// The cause. - [LoggerMessage( - EventId = 22, - Level = LogLevel.Error, - Message = "the session of conversation {ConversationId} could not be closed, so its last words may never reach store 1 and it waits out the idle timeout.")] - public static partial void ConversationCloseFaulted(ILogger logger, string conversationId, Exception exception); + /// The session of a conversation could not be closed at the end of that conversation. + /// The logger. + /// The id of the conversation. + /// The cause. + [LoggerMessage( + EventId = 22, + Level = LogLevel.Error, + Message = "the session of conversation {ConversationId} could not be closed, so its last words may never reach store 1 and it waits out the idle timeout.")] + public static partial void ConversationCloseFaulted(ILogger logger, string conversationId, Exception exception); - /// The store could not be told that a conversation is still being had. - /// The logger. - /// The id of the conversation. - /// The cause. - [LoggerMessage( - EventId = 23, - Level = LogLevel.Warning, - Message = "the store could not be read for conversation {ConversationId}, so that call may be dropped by the idle sweep while it is still running.")] - public static partial void SessionTouchFaulted(ILogger logger, string conversationId, Exception exception); + /// The store could not be told that a conversation is still being had. + /// The logger. + /// The id of the conversation. + /// The cause. + [LoggerMessage( + EventId = 23, + Level = LogLevel.Warning, + Message = "the store could not be read for conversation {ConversationId}, so that call may be dropped by the idle sweep while it is still running.")] + public static partial void SessionTouchFaulted(ILogger logger, string conversationId, Exception exception); + } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayOptions.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayOptions.cs index 58c8dd95..7927d71e 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayOptions.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelayOptions.cs @@ -1,44 +1,45 @@ -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// What the relay endpoint may do, and for how long. -/// -/// -/// Every default here is chosen for a phone conversation. A conversation is short, it is quiet in bytes, and a -/// dead one must be noticed in seconds rather than minutes. -/// -internal sealed class TelnyxRelayOptions +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// Gets or sets the largest inbound frame the endpoint accepts, in bytes. + /// + /// What the relay endpoint may do, and for how long. + /// /// - /// The WebSocket middleware turns the request timeout off once it accepts, so nothing else - /// bounds a frame. A real setup frame is under 2 KB, and 64 KB leaves room for custom - /// parameters without letting one message exhaust the host. + /// Every default here is chosen for a phone conversation. A conversation is short, it is quiet in bytes, and a + /// dead one must be noticed in seconds rather than minutes. /// - public int MaxFrameBytes { get; set; } = 64 * 1024; + internal sealed class TelnyxRelayOptions + { + /// Gets or sets the largest inbound frame the endpoint accepts, in bytes. + /// + /// The WebSocket middleware turns the request timeout off once it accepts, so nothing else + /// bounds a frame. A real setup frame is under 2 KB, and 64 KB leaves room for custom + /// parameters without letting one message exhaust the host. + /// + public int MaxFrameBytes { get; set; } = 64 * 1024; - /// Gets or sets how long teardown gives a stuck task before it moves on. - /// - /// Every wait that could otherwise wedge a connection shares this one bound: how long the last - /// turn of a conversation may take to unwind once teardown cancels it, how long the close handshake may - /// take before the socket is aborted, and how long the words of a conversation may take to reach store 1 - /// before its session is dropped. A telephony conversation that already dropped never answers a close - /// frame, a chat client is not guaranteed to honour cancellation promptly, and a transcript - /// store talks to a database, so each wait needs a bound or any one of them could wedge the - /// connection forever. Because they run one after another rather than together, one wedged - /// connection can spend this value several times over — longer than Kestrel's own five-second - /// default shutdown timeout. That trade is intentional: a slow, bounded teardown beats one with - /// no bound at all. - /// - public TimeSpan CloseTimeout { get; set; } = TimeSpan.FromSeconds(5); + /// Gets or sets how long teardown gives a stuck task before it moves on. + /// + /// Every wait that could otherwise wedge a connection shares this one bound: how long the last + /// turn of a conversation may take to unwind once teardown cancels it, how long the close handshake may + /// take before the socket is aborted, and how long the words of a conversation may take to reach store 1 + /// before its session is dropped. A telephony conversation that already dropped never answers a close + /// frame, a chat client is not guaranteed to honour cancellation promptly, and a transcript + /// store talks to a database, so each wait needs a bound or any one of them could wedge the + /// connection forever. Because they run one after another rather than together, one wedged + /// connection can spend this value several times over — longer than Kestrel's own five-second + /// default shutdown timeout. That trade is intentional: a slow, bounded teardown beats one with + /// no bound at all. + /// + public TimeSpan CloseTimeout { get; set; } = TimeSpan.FromSeconds(5); - /// Gets or sets how long the endpoint waits with no inbound frame before it ends the conversation. - /// - /// The vendor never reconnects, so a silent socket is a conversation that is already over. The clock - /// is a , resolved from the request's own service provider rather - /// than a property of this class: - /// when the host bound one, otherwise . A test that wants a - /// deterministic idle deadline binds that same property to a fake clock. - /// - public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromMinutes(5); + /// Gets or sets how long the endpoint waits with no inbound frame before it ends the conversation. + /// + /// The vendor never reconnects, so a silent socket is a conversation that is already over. The clock + /// is a , resolved from the request's own service provider rather + /// than a property of this class: + /// when the host bound one, otherwise . A test that wants a + /// deterministic idle deadline binds that same property to a fake clock. + /// + public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromMinutes(5); + } } diff --git a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelaySpeechAdapter.cs b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelaySpeechAdapter.cs index a1715e36..76a03f81 100644 --- a/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelaySpeechAdapter.cs +++ b/src/AgentCore.AspNetCore/Vendors/TelnyxRelay/TelnyxRelaySpeechAdapter.cs @@ -1,32 +1,33 @@ using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.Vendors.TelnyxRelay; - -/// -/// The selection face of the one speech vendor this solution bundles. -/// -/// -/// -/// D28 buys the whole speech layer — speech to text, turn detection, text to speech, and -/// interruption — inside Telnyx Conversation Relay, so this vendor is a transport rather than a -/// service the process dials. A host registers this through -/// AgentCoreOptions.UseSpeech, and a document that names it under providers.speech.stt -/// and providers.speech.tts then selects it — both roles, because it sells both. The socket -/// itself belongs to providers.conversation, which app.MapCall() reads — and because this -/// vendor bundles the pipe with the ears and the mouth, all three names must agree or the start -/// fails. -/// -/// -/// It carries a kind and nothing else, because does. A relay conversation -/// is born from a socket the host already accepted, so there is nothing here to create at selection -/// time: the frames arriving on that socket are the channel. -/// -/// -public sealed class TelnyxRelaySpeechAdapter : ISpeechAdapter +namespace AgentCore.AspNetCore.Vendors.TelnyxRelay { - /// The one kind value, under either speech role, this vendor answers to. - public const string TelnyxRelayKind = "telnyx-relay"; + /// + /// The selection face of the one speech vendor this solution bundles. + /// + /// + /// + /// D28 buys the whole speech layer — speech to text, turn detection, text to speech, and + /// interruption — inside Telnyx Conversation Relay, so this vendor is a transport rather than a + /// service the process dials. A host registers this through + /// AgentCoreOptions.UseSpeech, and a document that names it under providers.speech.stt + /// and providers.speech.tts then selects it — both roles, because it sells both. The socket + /// itself belongs to providers.conversation, which app.MapCall() reads — and because this + /// vendor bundles the pipe with the ears and the mouth, all three names must agree or the start + /// fails. + /// + /// + /// It carries a kind and nothing else, because does. A relay conversation + /// is born from a socket the host already accepted, so there is nothing here to create at selection + /// time: the frames arriving on that socket are the channel. + /// + /// + public sealed class TelnyxRelaySpeechAdapter : ISpeechAdapter + { + /// The one kind value, under either speech role, this vendor answers to. + public const string TelnyxRelayKind = "telnyx-relay"; - /// - public string Kind => TelnyxRelayKind; + /// + public string Kind => TelnyxRelayKind; + } } diff --git a/src/AgentCore.Domain/Audit/AuditEvent.cs b/src/AgentCore.Domain/Audit/AuditEvent.cs index e708abd5..45d4f3a1 100644 --- a/src/AgentCore.Domain/Audit/AuditEvent.cs +++ b/src/AgentCore.Domain/Audit/AuditEvent.cs @@ -1,43 +1,44 @@ -namespace AgentCore.Domain.Audit; - -/// -/// One append-only audit event. It is what a conversation wrote at one moment, and nothing edits it. -/// -public sealed record AuditEvent +namespace AgentCore.Domain.Audit { - private static readonly IReadOnlyDictionary EmptyPayload = - new Dictionary(StringComparer.Ordinal); - - /// Gets the id of the conversation the event belongs to. - public required string ConversationId { get; init; } - - /// Gets what the event records. - public required AuditEventKind Kind { get; init; } - - /// Gets when the event happened. - public required DateTimeOffset OccurredAt { get; init; } - /// - /// Gets the zero-based index of the turn the event belongs to, or when the - /// event belongs to the conversation rather than to one turn. + /// One append-only audit event. It is what a conversation wrote at one moment, and nothing edits it. /// - public int? TurnIndex { get; init; } - - /// Gets the identity of the event. The conversation allocates it, and it never orders anything. - /// - /// It is a UUID v7, so it is unique without a round trip and an amendment can name the event it - /// corrects the instant that event is raised. It is not an order: v7 is random within a - /// millisecond, and a turn raises three events inside one. The order of a conversation is the - /// sequence the store assigns, and nothing sorts by this value. - /// - public required Guid EventId { get; init; } - - /// - /// Gets the of the earlier event in the same conversation that this event corrects, - /// or when the event corrects nothing. - /// - public Guid? AmendsEventId { get; init; } - - /// Gets the facts the event carries, keyed by name. - public IReadOnlyDictionary Payload { get; init; } = EmptyPayload; + public sealed record AuditEvent + { + private static readonly IReadOnlyDictionary EmptyPayload = + new Dictionary(StringComparer.Ordinal); + + /// Gets the id of the conversation the event belongs to. + public required string ConversationId { get; init; } + + /// Gets what the event records. + public required AuditEventKind Kind { get; init; } + + /// Gets when the event happened. + public required DateTimeOffset OccurredAt { get; init; } + + /// + /// Gets the zero-based index of the turn the event belongs to, or when the + /// event belongs to the conversation rather than to one turn. + /// + public int? TurnIndex { get; init; } + + /// Gets the identity of the event. The conversation allocates it, and it never orders anything. + /// + /// It is a UUID v7, so it is unique without a round trip and an amendment can name the event it + /// corrects the instant that event is raised. It is not an order: v7 is random within a + /// millisecond, and a turn raises three events inside one. The order of a conversation is the + /// sequence the store assigns, and nothing sorts by this value. + /// + public required Guid EventId { get; init; } + + /// + /// Gets the of the earlier event in the same conversation that this event corrects, + /// or when the event corrects nothing. + /// + public Guid? AmendsEventId { get; init; } + + /// Gets the facts the event carries, keyed by name. + public IReadOnlyDictionary Payload { get; init; } = EmptyPayload; + } } diff --git a/src/AgentCore.Domain/Audit/AuditEventKind.cs b/src/AgentCore.Domain/Audit/AuditEventKind.cs index 0b91f461..ebb7bd25 100644 --- a/src/AgentCore.Domain/Audit/AuditEventKind.cs +++ b/src/AgentCore.Domain/Audit/AuditEventKind.cs @@ -1,29 +1,30 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The closed set of things one conversation writes into the audit chain. -/// -public enum AuditEventKind +namespace AgentCore.Domain.Audit { - /// A session of the conversation started. It is the first event of every session, not of every conversation. - ConversationStarted = 0, + /// + /// The closed set of things one conversation writes into the audit chain. + /// + public enum AuditEventKind + { + /// A session of the conversation started. It is the first event of every session, not of every conversation. + ConversationStarted = 0, - /// One turn ran to the end, and the caller heard the whole reply. - TurnCompleted = 1, + /// One turn ran to the end, and the caller heard the whole reply. + TurnCompleted = 1, - /// The caller spoke over a reply, so the reply stopped early. - ReplyInterrupted = 2, + /// The caller spoke over a reply, so the reply stopped early. + ReplyInterrupted = 2, - /// A tool call failed, and the turn continued without its answer. + /// A tool call failed, and the turn continued without its answer. - ToolFailed = 3, + ToolFailed = 3, - /// The host ended the conversation. It is the last event of the session that ended it, not of the chain. - ConversationEnded = 5, + /// The host ended the conversation. It is the last event of the session that ended it, not of the chain. + ConversationEnded = 5, - /// Moderation flagged what the CALLER said, so the agent refused to answer that turn. - PromptFlagged = 6, + /// Moderation flagged what the CALLER said, so the agent refused to answer that turn. + PromptFlagged = 6, - /// A caller replaced an earlier message, so the turns after it were withdrawn. - TurnSuperseded = 7, + /// A caller replaced an earlier message, so the turns after it were withdrawn. + TurnSuperseded = 7, + } } diff --git a/src/AgentCore.Domain/Audit/AuditEventKinds.cs b/src/AgentCore.Domain/Audit/AuditEventKinds.cs index 582ac6d4..55e79f44 100644 --- a/src/AgentCore.Domain/Audit/AuditEventKinds.cs +++ b/src/AgentCore.Domain/Audit/AuditEventKinds.cs @@ -1,42 +1,46 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The wire token of each . -/// -public static class AuditEventKinds +namespace AgentCore.Domain.Audit { - /// Reads the wire token of one kind. - /// The kind to name. - /// The token the canonical form writes. - /// The value is not a member of the closed set. - public static string ToToken(AuditEventKind kind) => kind switch + /// + /// The wire token of each . + /// + public static class AuditEventKinds { - AuditEventKind.ConversationStarted => "conversation.started", - AuditEventKind.TurnCompleted => "turn.completed", - AuditEventKind.ReplyInterrupted => "reply.interrupted", - AuditEventKind.ToolFailed => "tool.failed", - AuditEventKind.ConversationEnded => "conversation.ended", - AuditEventKind.PromptFlagged => "prompt.flagged", - AuditEventKind.TurnSuperseded => "turn.superseded", - _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "The audit event vocabulary is closed, and this value is not in it."), - }; + /// Reads the wire token of one kind. + /// The kind to name. + /// The token the canonical form writes. + /// The value is not a member of the closed set. + public static string ToToken(AuditEventKind kind) + { + return kind switch + { + AuditEventKind.ConversationStarted => "conversation.started", + AuditEventKind.TurnCompleted => "turn.completed", + AuditEventKind.ReplyInterrupted => "reply.interrupted", + AuditEventKind.ToolFailed => "tool.failed", + AuditEventKind.ConversationEnded => "conversation.ended", + AuditEventKind.PromptFlagged => "prompt.flagged", + AuditEventKind.TurnSuperseded => "turn.superseded", + _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "The audit event vocabulary is closed, and this value is not in it."), + }; + } - /// Reads the kind behind one wire token. - /// The token a stored row holds. - /// The kind, when the token is known. - /// when the token names a kind. - public static bool TryParse(string? token, out AuditEventKind kind) - { - switch (token) + /// Reads the kind behind one wire token. + /// The token a stored row holds. + /// The kind, when the token is known. + /// when the token names a kind. + public static bool TryParse(string? token, out AuditEventKind kind) { - case "conversation.started": kind = AuditEventKind.ConversationStarted; return true; - case "turn.completed": kind = AuditEventKind.TurnCompleted; return true; - case "reply.interrupted": kind = AuditEventKind.ReplyInterrupted; return true; - case "tool.failed": kind = AuditEventKind.ToolFailed; return true; - case "conversation.ended": kind = AuditEventKind.ConversationEnded; return true; - case "prompt.flagged": kind = AuditEventKind.PromptFlagged; return true; - case "turn.superseded": kind = AuditEventKind.TurnSuperseded; return true; - default: kind = default; return false; + switch (token) + { + case "conversation.started": kind = AuditEventKind.ConversationStarted; return true; + case "turn.completed": kind = AuditEventKind.TurnCompleted; return true; + case "reply.interrupted": kind = AuditEventKind.ReplyInterrupted; return true; + case "tool.failed": kind = AuditEventKind.ToolFailed; return true; + case "conversation.ended": kind = AuditEventKind.ConversationEnded; return true; + case "prompt.flagged": kind = AuditEventKind.PromptFlagged; return true; + case "turn.superseded": kind = AuditEventKind.TurnSuperseded; return true; + default: kind = default; return false; + } } } } diff --git a/src/AgentCore.Domain/Audit/AuditEventVocabulary.cs b/src/AgentCore.Domain/Audit/AuditEventVocabulary.cs index 15ce395c..ae672a94 100644 --- a/src/AgentCore.Domain/Audit/AuditEventVocabulary.cs +++ b/src/AgentCore.Domain/Audit/AuditEventVocabulary.cs @@ -1,162 +1,163 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The rules an audit event must satisfy before a sink accepts it. -/// -public static class AuditEventVocabulary +namespace AgentCore.Domain.Audit { - - /// Refuses an event the vocabulary does not permit. - public static void Validate(AuditEvent auditEvent) + /// + /// The rules an audit event must satisfy before a sink accepts it. + /// + public static class AuditEventVocabulary { - if (string.IsNullOrEmpty(auditEvent.ConversationId)) - { - throw new ArgumentException("An audit event carries a conversation id.", nameof(auditEvent)); - } - - if (auditEvent.EventId == Guid.Empty) - { - throw new ArgumentException("An audit event carries an identity.", nameof(auditEvent)); - } - - // The token lookup refuses a value outside the closed set. - _ = AuditEventKinds.ToToken(auditEvent.Kind); - - // The chain is ordered by the sequence the STORE assigns, so "earlier" is not a fact this - // record can check: an id is an identity and never a position. What is checkable here is the - // one shape that is always wrong, and the store enforces the rest. - if (auditEvent.AmendsEventId == auditEvent.EventId) - { - throw new ArgumentException( - $"An amendment names another event. Event {auditEvent.EventId} names itself.", - nameof(auditEvent)); - } - - RequireReplyInterrupted(auditEvent); - if (auditEvent.Payload.TryGetValue(AuditPayloadKeys.ReplyTextSha256, out string? replyText)) + /// Refuses an event the vocabulary does not permit. + public static void Validate(AuditEvent auditEvent) { - // An empty value here is the one thing that cannot be true: every text hashes to 64 - // characters, the empty string included, so an empty hash proves nothing and would leave - // the row unverifiable against store 1 forever. - RequireHash(AuditPayloadKeys.ReplyTextSha256, replyText, nameof(auditEvent)); - } - - RequirePromptFlagged(auditEvent); - - RequireConversationEnded(auditEvent); - - foreach (KeyValuePair entry in auditEvent.Payload) - { - if (string.IsNullOrEmpty(entry.Key)) + if (string.IsNullOrEmpty(auditEvent.ConversationId)) { - throw new ArgumentException("An audit payload key is not empty.", nameof(auditEvent)); + throw new ArgumentException("An audit event carries a conversation id.", nameof(auditEvent)); } - if (entry.Value is null) + if (auditEvent.EventId == Guid.Empty) { - throw new ArgumentException( - $"The audit payload value of '{entry.Key}' is null. A missing fact is an absent key.", - nameof(auditEvent)); + throw new ArgumentException("An audit event carries an identity.", nameof(auditEvent)); } - } - } + // The token lookup refuses a value outside the closed set. + _ = AuditEventKinds.ToToken(auditEvent.Kind); - /// Refuses a barge-in that names no turn, or proves no heard text. - private static void RequireReplyInterrupted(AuditEvent auditEvent) - { - if (auditEvent.Kind == AuditEventKind.ReplyInterrupted) - { - // T23: the chain is append-only, so a barge-in is a second event that references the - // turn event. An interruption that amends nothing loses the turn it belongs to. - if (auditEvent.AmendsEventId is null) + // The chain is ordered by the sequence the STORE assigns, so "earlier" is not a fact this + // record can check: an id is an identity and never a position. What is checkable here is the + // one shape that is always wrong, and the store enforces the rest. + if (auditEvent.AmendsEventId == auditEvent.EventId) { throw new ArgumentException( - "A reply.interrupted event amends the turn.completed event of the same turn, so it sets AmendsEventId. See T23.", + $"An amendment names another event. Event {auditEvent.EventId} names itself.", nameof(auditEvent)); } - // Section 11, item 6a: the event proves the text the caller ACTUALLY HEARD. The words - // are in store 1, where they stay erasable, so what is required here is the digest. - if (!auditEvent.Payload.TryGetValue(AuditPayloadKeys.UtteranceUntilInterruptSha256, out string? utterance)) + RequireReplyInterrupted(auditEvent); + + if (auditEvent.Payload.TryGetValue(AuditPayloadKeys.ReplyTextSha256, out string? replyText)) { - throw new ArgumentException( - $"A reply.interrupted event carries '{AuditPayloadKeys.UtteranceUntilInterruptSha256}', the SHA-256 of the text the caller actually heard. See section 11, item 6a.", - nameof(auditEvent)); + // An empty value here is the one thing that cannot be true: every text hashes to 64 + // characters, the empty string included, so an empty hash proves nothing and would leave + // the row unverifiable against store 1 forever. + RequireHash(AuditPayloadKeys.ReplyTextSha256, replyText, nameof(auditEvent)); } - RequireHash(AuditPayloadKeys.UtteranceUntilInterruptSha256, utterance, nameof(auditEvent)); + RequirePromptFlagged(auditEvent); + + RequireConversationEnded(auditEvent); + + foreach (KeyValuePair entry in auditEvent.Payload) + { + if (string.IsNullOrEmpty(entry.Key)) + { + throw new ArgumentException("An audit payload key is not empty.", nameof(auditEvent)); + } + + if (entry.Value is null) + { + throw new ArgumentException( + $"The audit payload value of '{entry.Key}' is null. A missing fact is an absent key.", + nameof(auditEvent)); + } + } } - } - /// Refuses a flag verdict that carries no categories. - private static void RequirePromptFlagged(AuditEvent auditEvent) - { - // §9 makes this chain the only long-term record. The kind alone says something flagged - // the caller, and the categories are the only other fact the event carries, so the fact - // goes in with the event or it is lost. This is the argument the chain already makes for - // utteranceUntilInterrupt above. No AmendsEventId rule stands here: the verdict is known - // BEFORE the model runs, so the event is written before the turn.completed event of the - // same turn and amends nothing. TurnIndex names the turn. - if (auditEvent.Kind == AuditEventKind.PromptFlagged - && (!auditEvent.Payload.TryGetValue(AuditPayloadKeys.ModerationCategories, out string? categories) - || !IsCommaSeparatedListWithNoEmptyMember(categories))) + /// Refuses a barge-in that names no turn, or proves no heard text. + private static void RequireReplyInterrupted(AuditEvent auditEvent) { - throw new ArgumentException( - $"A prompt.flagged event carries '{AuditPayloadKeys.ModerationCategories}', a comma-separated list with no empty member. See section 11, item 11.", - nameof(auditEvent)); + if (auditEvent.Kind == AuditEventKind.ReplyInterrupted) + { + // T23: the chain is append-only, so a barge-in is a second event that references the + // turn event. An interruption that amends nothing loses the turn it belongs to. + if (auditEvent.AmendsEventId is null) + { + throw new ArgumentException( + "A reply.interrupted event amends the turn.completed event of the same turn, so it sets AmendsEventId. See T23.", + nameof(auditEvent)); + } + + // Section 11, item 6a: the event proves the text the caller ACTUALLY HEARD. The words + // are in store 1, where they stay erasable, so what is required here is the digest. + if (!auditEvent.Payload.TryGetValue(AuditPayloadKeys.UtteranceUntilInterruptSha256, out string? utterance)) + { + throw new ArgumentException( + $"A reply.interrupted event carries '{AuditPayloadKeys.UtteranceUntilInterruptSha256}', the SHA-256 of the text the caller actually heard. See section 11, item 6a.", + nameof(auditEvent)); + } + + RequireHash(AuditPayloadKeys.UtteranceUntilInterruptSha256, utterance, nameof(auditEvent)); + } } - } - /// Refuses a conversation end that carries no reason from the closed set. - private static void RequireConversationEnded(AuditEvent auditEvent) - { - // The reason is countable, so the chain refuses free text here. §9 makes this table the - // only long-term record, and a report that counts the endings of one year reads the - // token. Detail belongs under another key. See ConversationEndReason. - if (auditEvent.Kind == AuditEventKind.ConversationEnded - && (!auditEvent.Payload.TryGetValue(AuditPayloadKeys.EndReason, out string? endReason) - || !ConversationEndReasons.TryParse(endReason, out _))) + /// Refuses a flag verdict that carries no categories. + private static void RequirePromptFlagged(AuditEvent auditEvent) { - throw new ArgumentException( - $"A conversation.ended event carries '{AuditPayloadKeys.EndReason}', and the value is one token of the closed set. See ConversationEndReason.", - nameof(auditEvent)); + // §9 makes this chain the only long-term record. The kind alone says something flagged + // the caller, and the categories are the only other fact the event carries, so the fact + // goes in with the event or it is lost. This is the argument the chain already makes for + // utteranceUntilInterrupt above. No AmendsEventId rule stands here: the verdict is known + // BEFORE the model runs, so the event is written before the turn.completed event of the + // same turn and amends nothing. TurnIndex names the turn. + if (auditEvent.Kind == AuditEventKind.PromptFlagged + && (!auditEvent.Payload.TryGetValue(AuditPayloadKeys.ModerationCategories, out string? categories) + || !IsCommaSeparatedListWithNoEmptyMember(categories))) + { + throw new ArgumentException( + $"A prompt.flagged event carries '{AuditPayloadKeys.ModerationCategories}', a comma-separated list with no empty member. See section 11, item 11.", + nameof(auditEvent)); + } } - } - /// Reads whether a value is a comma-separated list in which no member is empty. - private static bool IsCommaSeparatedListWithNoEmptyMember(string? value) - { - if (string.IsNullOrEmpty(value)) + /// Refuses a conversation end that carries no reason from the closed set. + private static void RequireConversationEnded(AuditEvent auditEvent) { - return false; + // The reason is countable, so the chain refuses free text here. §9 makes this table the + // only long-term record, and a report that counts the endings of one year reads the + // token. Detail belongs under another key. See ConversationEndReason. + if (auditEvent.Kind == AuditEventKind.ConversationEnded + && (!auditEvent.Payload.TryGetValue(AuditPayloadKeys.EndReason, out string? endReason) + || !ConversationEndReasons.TryParse(endReason, out _))) + { + throw new ArgumentException( + $"A conversation.ended event carries '{AuditPayloadKeys.EndReason}', and the value is one token of the closed set. See ConversationEndReason.", + nameof(auditEvent)); + } } - foreach (string member in value.Split(',')) + + /// Reads whether a value is a comma-separated list in which no member is empty. + private static bool IsCommaSeparatedListWithNoEmptyMember(string? value) { - if (member.Length == 0) + if (string.IsNullOrEmpty(value)) { return false; } - } - return true; - } + foreach (string member in value.Split(',')) + { + if (member.Length == 0) + { + return false; + } + } - /// - /// Refuses a payload value that is not a SHA-256 digest. - /// - private static void RequireHash(string key, string? value, string paramName) - { - if (!AuditHash.TryParse(value, out _)) + return true; + } + + /// + /// Refuses a payload value that is not a SHA-256 digest. + /// + private static void RequireHash(string key, string? value, string paramName) { - throw new ArgumentException( - $"The audit payload value of '{key}' is {AuditHash.Length} lowercase hexadecimal characters. This one is '{value}'.", - paramName); + if (!AuditHash.TryParse(value, out _)) + { + throw new ArgumentException( + $"The audit payload value of '{key}' is {AuditHash.Length} lowercase hexadecimal characters. This one is '{value}'.", + paramName); + } } } } diff --git a/src/AgentCore.Domain/Audit/AuditHash.cs b/src/AgentCore.Domain/Audit/AuditHash.cs index 4e2151ee..bef56e41 100644 --- a/src/AgentCore.Domain/Audit/AuditHash.cs +++ b/src/AgentCore.Domain/Audit/AuditHash.cs @@ -2,101 +2,102 @@ using System.Security.Cryptography; using System.Text; -namespace AgentCore.Domain.Audit; - -/// -/// One SHA-256 digest of the audit chain, as 64 lowercase hexadecimal characters. -/// -public sealed record AuditHash +namespace AgentCore.Domain.Audit { - /// The number of characters in a hexadecimal SHA-256 digest. - public const int Length = 64; - - private AuditHash(string value) => Value = value; - - /// Gets the 64 lowercase hexadecimal characters of the digest. - public string Value { get; } - - /// Reads a hash from its hexadecimal text. - /// 64 lowercase hexadecimal characters. - /// The hash. - /// The text is not 64 lowercase hexadecimal characters. - public static AuditHash Parse(string value) + /// + /// One SHA-256 digest of the audit chain, as 64 lowercase hexadecimal characters. + /// + public sealed record AuditHash { - ArgumentNullException.ThrowIfNull(value); + /// The number of characters in a hexadecimal SHA-256 digest. + public const int Length = 64; - if (!TryParse(value, out AuditHash? hash)) + private AuditHash(string value) { - throw new ArgumentException( - $"An audit hash is {Length} lowercase hexadecimal characters. This value is '{value}'.", - nameof(value)); + Value = value; } - return hash; - } + /// Gets the 64 lowercase hexadecimal characters of the digest. + public string Value { get; } - /// Reads a hash from its hexadecimal text, and reports a bad shape instead of throwing. - /// The text to read. - /// The hash, when the text has the right shape. - /// when the text is 64 lowercase hexadecimal characters. - public static bool TryParse(string? value, [NotNullWhen(true)] out AuditHash? hash) - { - hash = null; - if (value is null || value.Length != Length) + /// Reads a hash from its hexadecimal text. + /// 64 lowercase hexadecimal characters. + /// The hash. + /// The text is not 64 lowercase hexadecimal characters. + public static AuditHash Parse(string value) { - return false; + ArgumentNullException.ThrowIfNull(value); + + return !TryParse(value, out AuditHash? hash) + ? throw new ArgumentException( + $"An audit hash is {Length} lowercase hexadecimal characters. This value is '{value}'.", + nameof(value)) + : hash; } - foreach (char character in value) + /// Reads a hash from its hexadecimal text, and reports a bad shape instead of throwing. + /// The text to read. + /// The hash, when the text has the right shape. + /// when the text is 64 lowercase hexadecimal characters. + public static bool TryParse(string? value, [NotNullWhen(true)] out AuditHash? hash) { - bool isHexDigit = character is (>= '0' and <= '9') or (>= 'a' and <= 'f'); - if (!isHexDigit) + hash = null; + if (value is null || value.Length != Length) { return false; } - } - hash = new AuditHash(value); - return true; - } + foreach (char character in value) + { + bool isHexDigit = character is (>= '0' and <= '9') or (>= 'a' and <= 'f'); + if (!isHexDigit) + { + return false; + } + } - /// Builds a hash from the 32 bytes of a digest. - /// The 32 bytes SHA-256 produced. - /// The hash. - /// The digest is not 32 bytes long. - public static AuditHash FromDigest(ReadOnlySpan digest) - { - if (digest.Length != Length / 2) + hash = new AuditHash(value); + return true; + } + + /// Builds a hash from the 32 bytes of a digest. + /// The 32 bytes SHA-256 produced. + /// The hash. + /// The digest is not 32 bytes long. + public static AuditHash FromDigest(ReadOnlySpan digest) { - throw new ArgumentException( - $"A SHA-256 digest is {Length / 2} bytes. This one is {digest.Length}.", - nameof(digest)); + return digest.Length != Length / 2 + ? throw new ArgumentException( + $"A SHA-256 digest is {Length / 2} bytes. This one is {digest.Length}.", + nameof(digest)) + : new AuditHash(Convert.ToHexStringLower(digest)); } - return new AuditHash(Convert.ToHexStringLower(digest)); - } + /// Hashes one text, so the chain can prove words it does not hold. + /// The text to hash. The empty string is legal and hashes to a full digest. + /// The SHA-256 of the UTF-8 bytes of the text. + /// + /// The spoken words of a conversation live in store 1, where they stay erasable, and the chain stores + /// this instead. The bytes are UTF-8 with no byte-order mark, which is the same input + /// encode(sha256(convert_to(t, 'UTF8')), 'hex') reads in PostgreSQL, so a reviewer can + /// recompute the proof in either place. + /// + /// is . + public static AuditHash OfText(string text) + { + ArgumentNullException.ThrowIfNull(text); - /// Hashes one text, so the chain can prove words it does not hold. - /// The text to hash. The empty string is legal and hashes to a full digest. - /// The SHA-256 of the UTF-8 bytes of the text. - /// - /// The spoken words of a conversation live in store 1, where they stay erasable, and the chain stores - /// this instead. The bytes are UTF-8 with no byte-order mark, which is the same input - /// encode(sha256(convert_to(t, 'UTF8')), 'hex') reads in PostgreSQL, so a reviewer can - /// recompute the proof in either place. - /// - /// is . - public static AuditHash OfText(string text) - { - ArgumentNullException.ThrowIfNull(text); + byte[] bytes = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(text); + Span digest = stackalloc byte[SHA256.HashSizeInBytes]; + _ = SHA256.HashData(bytes, digest); + return FromDigest(digest); + } - byte[] bytes = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(text); - Span digest = stackalloc byte[SHA256.HashSizeInBytes]; - SHA256.HashData(bytes, digest); - return FromDigest(digest); + /// Reads the hexadecimal text of the hash. + /// The 64 characters. + public override string ToString() + { + return Value; + } } - - /// Reads the hexadecimal text of the hash. - /// The 64 characters. - public override string ToString() => Value; } diff --git a/src/AgentCore.Domain/Audit/AuditPayloadKeys.cs b/src/AgentCore.Domain/Audit/AuditPayloadKeys.cs index 61a72d06..98c00217 100644 --- a/src/AgentCore.Domain/Audit/AuditPayloadKeys.cs +++ b/src/AgentCore.Domain/Audit/AuditPayloadKeys.cs @@ -1,76 +1,77 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The payload keys the audit vocabulary knows by name. -/// -public static class AuditPayloadKeys +namespace AgentCore.Domain.Audit { /// - /// The SHA-256 of the text the caller ACTUALLY HEARD before the barge-in cut the reply, as 64 - /// lowercase hexadecimal characters. + /// The payload keys the audit vocabulary knows by name. /// - public const string UtteranceUntilInterruptSha256 = "utteranceUntilInterruptSha256"; + public static class AuditPayloadKeys + { + /// + /// The SHA-256 of the text the caller ACTUALLY HEARD before the barge-in cut the reply, as 64 + /// lowercase hexadecimal characters. + /// + public const string UtteranceUntilInterruptSha256 = "utteranceUntilInterruptSha256"; - /// - /// How long the caller heard, in milliseconds, before the barge-in cut the reply. - /// - public const string DurationUntilInterruptMs = "durationUntilInterruptMs"; + /// + /// How long the caller heard, in milliseconds, before the barge-in cut the reply. + /// + public const string DurationUntilInterruptMs = "durationUntilInterruptMs"; - /// - /// The SHA-256 of the whole reply text the model produced, as 64 lowercase hexadecimal - /// characters. - /// - public const string ReplyTextSha256 = "replyTextSha256"; + /// + /// The SHA-256 of the whole reply text the model produced, as 64 lowercase hexadecimal + /// characters. + /// + public const string ReplyTextSha256 = "replyTextSha256"; - /// - /// The stage the turn ran in. - /// - public const string StageBefore = "stageBefore"; + /// + /// The stage the turn ran in. + /// + public const string StageBefore = "stageBefore"; - /// - /// The stage the machine holds after the turn. - /// - public const string StageAfter = "stageAfter"; + /// + /// The stage the machine holds after the turn. + /// + public const string StageAfter = "stageAfter"; - /// - /// The name of the tool that failed. - /// - public const string ToolName = "toolName"; + /// + /// The name of the tool that failed. + /// + public const string ToolName = "toolName"; - /// - /// The id the model gave the one tool call that failed, so two calls to the same tool in one turn - /// are two records and not one. - /// - public const string ToolCallId = "toolCallId"; + /// + /// The id the model gave the one tool call that failed, so two calls to the same tool in one turn + /// are two records and not one. + /// + public const string ToolCallId = "toolCallId"; - /// - /// Which of the two ways a tool call fails this one was. - /// - public const string ToolFailureKind = "toolFailureKind"; + /// + /// Which of the two ways a tool call fails this one was. + /// + public const string ToolFailureKind = "toolFailureKind"; - /// - /// Why the tool failed, in the words the tool gave. - /// - public const string ToolError = "toolError"; + /// + /// Why the tool failed, in the words the tool gave. + /// + public const string ToolError = "toolError"; - /// - /// The moderation categories that flagged the caller's spoken input, comma-separated and in the - /// order the endpoint returned. - /// - public const string ModerationCategories = "moderationCategories"; + /// + /// The moderation categories that flagged the caller's spoken input, comma-separated and in the + /// order the endpoint returned. + /// + public const string ModerationCategories = "moderationCategories"; - /// - /// Why the conversation ended. - /// - public const string EndReason = "endReason"; + /// + /// Why the conversation ended. + /// + public const string EndReason = "endReason"; - /// - /// The lowest turn index an edit withdrew. - /// - public const string WithdrewFromTurnIndex = "withdrewFromTurnIndex"; + /// + /// The lowest turn index an edit withdrew. + /// + public const string WithdrewFromTurnIndex = "withdrewFromTurnIndex"; - /// - /// The highest turn index an edit withdrew, included. - /// - public const string WithdrewThroughTurnIndex = "withdrewThroughTurnIndex"; + /// + /// The highest turn index an edit withdrew, included. + /// + public const string WithdrewThroughTurnIndex = "withdrewThroughTurnIndex"; + } } diff --git a/src/AgentCore.Domain/Audit/ConversationEndReason.cs b/src/AgentCore.Domain/Audit/ConversationEndReason.cs index f3b0fc0b..381ffa97 100644 --- a/src/AgentCore.Domain/Audit/ConversationEndReason.cs +++ b/src/AgentCore.Domain/Audit/ConversationEndReason.cs @@ -1,64 +1,65 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The closed set of ways one conversation ends. -/// -/// -/// -/// The set is closed for the reason the chain exists. D23 makes the audit table the record of the -/// conversation, and D26 buys 14 days of free retention on every other signal, so §9 calls this chain the -/// only long-term record. A report written years later reads this table and nothing else. A -/// free-text reason cannot be counted: one path writes -/// hangup, a second writes caller hung up, and a third writes HANGUP, and the -/// three are one fact under three names. -/// -/// -/// Section 4 names every way a conversation ends, and there are four. The caller hangs up, and only the -/// vendor adapter sees it. The stage machine reaches a terminal stage, and the agent finished the -/// work. The agent hands the conversation to a human through the conference pattern of section 4.3, which is -/// item 5 of section 11. Or a fault ends the conversation. -/// -/// -/// A caller that holds more detail puts it in another payload key. The vendor hang-up cause, the -/// terminal stage under , and the message of a fault are all -/// facts beside the reason, and none of them is the reason. The reason stays countable. -/// -/// -/// The set is small on purpose, and it stays small. A new reason is a change to this enum, a change -/// to , and a new row in the public API file. -/// -/// -public enum ConversationEndReason +namespace AgentCore.Domain.Audit { - /// The caller hung up. + /// + /// The closed set of ways one conversation ends. + /// /// - /// Only the telephony adapter sees this, because the hang-up arrives on a Conversation Control webhook - /// and never on the relay socket. The vendor reports a cause with it, and that cause is detail - /// beside the reason rather than the reason. + /// + /// The set is closed for the reason the chain exists. D23 makes the audit table the record of the + /// conversation, and D26 buys 14 days of free retention on every other signal, so §9 calls this chain the + /// only long-term record. A report written years later reads this table and nothing else. A + /// free-text reason cannot be counted: one path writes + /// hangup, a second writes caller hung up, and a third writes HANGUP, and the + /// three are one fact under three names. + /// + /// + /// Section 4 names every way a conversation ends, and there are four. The caller hangs up, and only the + /// vendor adapter sees it. The stage machine reaches a terminal stage, and the agent finished the + /// work. The agent hands the conversation to a human through the conference pattern of section 4.3, which is + /// item 5 of section 11. Or a fault ends the conversation. + /// + /// + /// A caller that holds more detail puts it in another payload key. The vendor hang-up cause, the + /// terminal stage under , and the message of a fault are all + /// facts beside the reason, and none of them is the reason. The reason stays countable. + /// + /// + /// The set is small on purpose, and it stays small. A new reason is a change to this enum, a change + /// to , and a new row in the public API file. + /// /// - CallerHungUp = 0, + public enum ConversationEndReason + { + /// The caller hung up. + /// + /// Only the telephony adapter sees this, because the hang-up arrives on a Conversation Control webhook + /// and never on the relay socket. The vendor reports a cause with it, and that cause is detail + /// beside the reason rather than the reason. + /// + CallerHungUp = 0, - /// The stage machine reached a terminal stage, and the agent finished the conversation. - /// - /// The turn loop closes the chain itself here, because it is the only place that knows the stage - /// the machine reached. The event carries that stage under - /// , so a reader still learns which ending it was. - /// - AgentCompleted = 1, + /// The stage machine reached a terminal stage, and the agent finished the conversation. + /// + /// The turn loop closes the chain itself here, because it is the only place that knows the stage + /// the machine reached. The event carries that stage under + /// , so a reader still learns which ending it was. + /// + AgentCompleted = 1, - /// The conversation went to a human through the conference pattern. - /// - /// Section 11, item 5, and section 4.3: the adapter joins the conversation to a conference and never - /// sends the Telnyx transfer command, which costs $0.10 for each invocation (T27). The - /// conversation leaves the agent at this point, so this is the last event of its chain. - /// - TransferredToHuman = 2, + /// The conversation went to a human through the conference pattern. + /// + /// Section 11, item 5, and section 4.3: the adapter joins the conversation to a conference and never + /// sends the Telnyx transfer command, which costs $0.10 for each invocation (T27). The + /// conversation leaves the agent at this point, so this is the last event of its chain. + /// + TransferredToHuman = 2, - /// A fault ended the conversation. - /// - /// This is the ending section 8.7 works to prevent, so it is rare. A tool that fails and a run - /// that answers with no text both speak the fallback line and keep the conversation, and neither reaches - /// here. A dropped relay socket and a stage that names no agent do. - /// - Faulted = 3, + /// A fault ended the conversation. + /// + /// This is the ending section 8.7 works to prevent, so it is rare. A tool that fails and a run + /// that answers with no text both speak the fallback line and keep the conversation, and neither reaches + /// here. A dropped relay socket and a stage that names no agent do. + /// + Faulted = 3, + } } diff --git a/src/AgentCore.Domain/Audit/ConversationEndReasons.cs b/src/AgentCore.Domain/Audit/ConversationEndReasons.cs index af580f16..dedb6398 100644 --- a/src/AgentCore.Domain/Audit/ConversationEndReasons.cs +++ b/src/AgentCore.Domain/Audit/ConversationEndReasons.cs @@ -1,55 +1,59 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The wire token of each . -/// -/// -/// -/// The conversation.ended payload holds this token under , and -/// never the .NET member name, and never the numeric value of the enum. This is the treatment -/// already gives an event kind, and it is the same argument: a rename -/// of a C# member must not change a hash PostgreSQL already stored, and the CHECK constraint -/// of D23 recomputes the same SHA-256 inside the engine, where no enum exists. -/// -/// -/// A token is stable forever. Add a token beside the old one, and never edit one in place. The -/// report that counts the endings of one year runs over these tokens, so a token that changes breaks -/// every count that came before it. -/// -/// -/// A token reads <who ended it>.<what they did>. caller.hangup takes the -/// vendor's own word, because the Conversation Control webhook that reports it is named conversation.hangup -/// and the adapter maps one to the other. -/// -/// -public static class ConversationEndReasons +namespace AgentCore.Domain.Audit { - /// Reads the wire token of one reason. - /// The reason to name. - /// The token the conversation.ended payload writes. - /// The value is not a member of the closed set. - public static string ToToken(ConversationEndReason reason) => reason switch + /// + /// The wire token of each . + /// + /// + /// + /// The conversation.ended payload holds this token under , and + /// never the .NET member name, and never the numeric value of the enum. This is the treatment + /// already gives an event kind, and it is the same argument: a rename + /// of a C# member must not change a hash PostgreSQL already stored, and the CHECK constraint + /// of D23 recomputes the same SHA-256 inside the engine, where no enum exists. + /// + /// + /// A token is stable forever. Add a token beside the old one, and never edit one in place. The + /// report that counts the endings of one year runs over these tokens, so a token that changes breaks + /// every count that came before it. + /// + /// + /// A token reads <who ended it>.<what they did>. caller.hangup takes the + /// vendor's own word, because the Conversation Control webhook that reports it is named conversation.hangup + /// and the adapter maps one to the other. + /// + /// + public static class ConversationEndReasons { - ConversationEndReason.CallerHungUp => "caller.hangup", - ConversationEndReason.AgentCompleted => "agent.completed", - ConversationEndReason.TransferredToHuman => "agent.transferred", - ConversationEndReason.Faulted => "conversation.faulted", - _ => throw new ArgumentOutOfRangeException(nameof(reason), reason, "The end-reason vocabulary is closed, and this value is not in it."), - }; + /// Reads the wire token of one reason. + /// The reason to name. + /// The token the conversation.ended payload writes. + /// The value is not a member of the closed set. + public static string ToToken(ConversationEndReason reason) + { + return reason switch + { + ConversationEndReason.CallerHungUp => "caller.hangup", + ConversationEndReason.AgentCompleted => "agent.completed", + ConversationEndReason.TransferredToHuman => "agent.transferred", + ConversationEndReason.Faulted => "conversation.faulted", + _ => throw new ArgumentOutOfRangeException(nameof(reason), reason, "The end-reason vocabulary is closed, and this value is not in it."), + }; + } - /// Reads the reason behind one wire token. - /// The token a stored row holds. - /// The reason, when the token is known. - /// when the token names a reason. - public static bool TryParse(string? token, out ConversationEndReason reason) - { - switch (token) + /// Reads the reason behind one wire token. + /// The token a stored row holds. + /// The reason, when the token is known. + /// when the token names a reason. + public static bool TryParse(string? token, out ConversationEndReason reason) { - case "caller.hangup": reason = ConversationEndReason.CallerHungUp; return true; - case "agent.completed": reason = ConversationEndReason.AgentCompleted; return true; - case "agent.transferred": reason = ConversationEndReason.TransferredToHuman; return true; - case "conversation.faulted": reason = ConversationEndReason.Faulted; return true; - default: reason = default; return false; + switch (token) + { + case "caller.hangup": reason = ConversationEndReason.CallerHungUp; return true; + case "agent.completed": reason = ConversationEndReason.AgentCompleted; return true; + case "agent.transferred": reason = ConversationEndReason.TransferredToHuman; return true; + case "conversation.faulted": reason = ConversationEndReason.Faulted; return true; + default: reason = default; return false; + } } } } diff --git a/src/AgentCore.Domain/Audit/ToolFailureKind.cs b/src/AgentCore.Domain/Audit/ToolFailureKind.cs index 8191b548..43ebb29a 100644 --- a/src/AgentCore.Domain/Audit/ToolFailureKind.cs +++ b/src/AgentCore.Domain/Audit/ToolFailureKind.cs @@ -1,52 +1,53 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The closed set of ways one tool call fails. -/// -/// -/// -/// The set is closed for the reason gives. D23 makes the audit table the -/// record of the conversation and §9 makes it the only long-term record, so a report written years later -/// counts these two facts apart and reads nothing else. Free text cannot be counted. -/// -/// -/// The two facts are genuinely different failures with different owners. A tool that threw is a fault -/// in the tool or in what it reached, and it is read beside the endpoint's own signals. -/// is a fault in the MODEL: it named a tool the document does not declare, so -/// nothing ran and nothing could have run. Today that fact is recorded nowhere, and it is the one a -/// prompt change fixes. -/// -/// -/// This set is OURS, and it is deliberately narrower than the framework's. -/// FunctionInvokingChatClient.FunctionInvocationStatus is Microsoft's, it is marked as an open -/// set, and it already carries a third member the chain has no fact for. The rule this chain follows -/// is the one states in the other direction: a -/// vendor's open set stays open and unchecked, and a set the design owns is closed and checked. A -/// framework status that maps to neither of these two is dropped rather than written, because a -/// vocabulary that grows by one string on every framework release cannot be read a year later. -/// -/// -/// The set is small on purpose, and it stays small. A new kind is a change to this enum, a change to -/// , and a new row in the public API file. -/// -/// -public enum ToolFailureKind +namespace AgentCore.Domain.Audit { - /// The model called a tool the document does not declare, so nothing ran. + /// + /// The closed set of ways one tool call fails. + /// /// - /// The model invented the name. The framework answers it with - /// Error: Requested function "…" not found. and carries no exception with it, so this - /// failure spends none of the consecutive-error budget and the turn goes on. That is correct — the - /// model can recover by calling a tool that exists — but it means nothing else would ever record - /// that it happened. + /// + /// The set is closed for the reason gives. D23 makes the audit table the + /// record of the conversation and §9 makes it the only long-term record, so a report written years later + /// counts these two facts apart and reads nothing else. Free text cannot be counted. + /// + /// + /// The two facts are genuinely different failures with different owners. A tool that threw is a fault + /// in the tool or in what it reached, and it is read beside the endpoint's own signals. + /// is a fault in the MODEL: it named a tool the document does not declare, so + /// nothing ran and nothing could have run. Today that fact is recorded nowhere, and it is the one a + /// prompt change fixes. + /// + /// + /// This set is OURS, and it is deliberately narrower than the framework's. + /// FunctionInvokingChatClient.FunctionInvocationStatus is Microsoft's, it is marked as an open + /// set, and it already carries a third member the chain has no fact for. The rule this chain follows + /// is the one states in the other direction: a + /// vendor's open set stays open and unchecked, and a set the design owns is closed and checked. A + /// framework status that maps to neither of these two is dropped rather than written, because a + /// vocabulary that grows by one string on every framework release cannot be read a year later. + /// + /// + /// The set is small on purpose, and it stays small. A new kind is a change to this enum, a change to + /// , and a new row in the public API file. + /// /// - Undeclared = 0, + public enum ToolFailureKind + { + /// The model called a tool the document does not declare, so nothing ran. + /// + /// The model invented the name. The framework answers it with + /// Error: Requested function "…" not found. and carries no exception with it, so this + /// failure spends none of the consecutive-error budget and the turn goes on. That is correct — the + /// model can recover by calling a tool that exists — but it means nothing else would ever record + /// that it happened. + /// + Undeclared = 0, - /// A declared tool ran and threw. - /// - /// The message of the fault rides beside this under . A - /// tool that ANSWERED with an error result is not this: it returned, the model read the answer, - /// and nothing failed as far as the framework is concerned. See ToolErrorResult. - /// - Faulted = 1, + /// A declared tool ran and threw. + /// + /// The message of the fault rides beside this under . A + /// tool that ANSWERED with an error result is not this: it returned, the model read the answer, + /// and nothing failed as far as the framework is concerned. See ToolErrorResult. + /// + Faulted = 1, + } } diff --git a/src/AgentCore.Domain/Audit/ToolFailureKinds.cs b/src/AgentCore.Domain/Audit/ToolFailureKinds.cs index 583faf87..ff35d8a5 100644 --- a/src/AgentCore.Domain/Audit/ToolFailureKinds.cs +++ b/src/AgentCore.Domain/Audit/ToolFailureKinds.cs @@ -1,50 +1,54 @@ -namespace AgentCore.Domain.Audit; - -/// -/// The wire token of each . -/// -/// -/// -/// The tool.failed payload holds this token under , -/// and never the .NET member name, and never the numeric value of the enum. This is the treatment -/// already gives an end reason, and it is the same argument: a rename of a -/// C# member must not change a hash PostgreSQL already stored, and the CHECK constraint of D23 -/// recomputes the same SHA-256 inside the engine, where no enum exists. -/// -/// -/// A token is stable forever. Add a token beside the old one, and never edit one in place. -/// -/// -/// A token reads tool.<what happened to it>, which is the -/// <subject>.<what happened> shape uses. The tokens are -/// deliberately NOT the framework's NotFound and Exception: those name a C# enum whose -/// stability Microsoft does not promise, and a stored row must not depend on it. -/// -/// -public static class ToolFailureKinds +namespace AgentCore.Domain.Audit { - /// Reads the wire token of one kind. - /// The kind to name. - /// The token the tool.failed payload writes. - /// The value is not a member of the closed set. - public static string ToToken(ToolFailureKind kind) => kind switch + /// + /// The wire token of each . + /// + /// + /// + /// The tool.failed payload holds this token under , + /// and never the .NET member name, and never the numeric value of the enum. This is the treatment + /// already gives an end reason, and it is the same argument: a rename of a + /// C# member must not change a hash PostgreSQL already stored, and the CHECK constraint of D23 + /// recomputes the same SHA-256 inside the engine, where no enum exists. + /// + /// + /// A token is stable forever. Add a token beside the old one, and never edit one in place. + /// + /// + /// A token reads tool.<what happened to it>, which is the + /// <subject>.<what happened> shape uses. The tokens are + /// deliberately NOT the framework's NotFound and Exception: those name a C# enum whose + /// stability Microsoft does not promise, and a stored row must not depend on it. + /// + /// + public static class ToolFailureKinds { - ToolFailureKind.Undeclared => "tool.undeclared", - ToolFailureKind.Faulted => "tool.faulted", - _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "The tool-failure vocabulary is closed, and this value is not in it."), - }; + /// Reads the wire token of one kind. + /// The kind to name. + /// The token the tool.failed payload writes. + /// The value is not a member of the closed set. + public static string ToToken(ToolFailureKind kind) + { + return kind switch + { + ToolFailureKind.Undeclared => "tool.undeclared", + ToolFailureKind.Faulted => "tool.faulted", + _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "The tool-failure vocabulary is closed, and this value is not in it."), + }; + } - /// Reads the kind behind one wire token. - /// The token a stored row holds. - /// The kind, when the token is known. - /// when the token names a kind. - public static bool TryParse(string? token, out ToolFailureKind kind) - { - switch (token) + /// Reads the kind behind one wire token. + /// The token a stored row holds. + /// The kind, when the token is known. + /// when the token names a kind. + public static bool TryParse(string? token, out ToolFailureKind kind) { - case "tool.undeclared": kind = ToolFailureKind.Undeclared; return true; - case "tool.faulted": kind = ToolFailureKind.Faulted; return true; - default: kind = default; return false; + switch (token) + { + case "tool.undeclared": kind = ToolFailureKind.Undeclared; return true; + case "tool.faulted": kind = ToolFailureKind.Faulted; return true; + default: kind = default; return false; + } } } } diff --git a/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs b/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs index f65ae97c..5c2edb41 100644 --- a/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs +++ b/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs @@ -1,38 +1,39 @@ -namespace AgentCore.Domain.Knowledge; - -/// -/// One card the knowledge base returned, whole. It carries its own citation. -/// -public sealed record KnowledgeCard +namespace AgentCore.Domain.Knowledge { - /// The empty payload, for a mapper that carries nothing extra. - private static readonly IReadOnlyDictionary NoExtras = - new Dictionary(StringComparer.Ordinal); + /// + /// One card the knowledge base returned, whole. It carries its own citation. + /// + public sealed record KnowledgeCard + { + /// The empty payload, for a mapper that carries nothing extra. + private static readonly IReadOnlyDictionary NoExtras = + new Dictionary(StringComparer.Ordinal); - /// Gets the card id, as the collection stores it. - public required string CardId { get; init; } + /// Gets the card id, as the collection stores it. + public required string CardId { get; init; } - /// Gets the card body, as the model will read it. - public required string Text { get; init; } + /// Gets the card body, as the model will read it. + public required string Text { get; init; } - /// Gets whether a link pulled this card in rather than the ranking. - public required bool ViaLink { get; init; } + /// Gets whether a link pulled this card in rather than the ranking. + public required bool ViaLink { get; init; } - /// Gets what this card came from, such as a document id. Empty when nothing maps it. - public string SourceRef { get; init; } = string.Empty; + /// Gets what this card came from, such as a document id. Empty when nothing maps it. + public string SourceRef { get; init; } = string.Empty; - /// Gets where in that source it sits, such as a page or a section. - /// Empty when the store maps no such field. - public string SourceLocator { get; init; } = string.Empty; + /// Gets where in that source it sits, such as a page or a section. + /// Empty when the store maps no such field. + public string SourceLocator { get; init; } = string.Empty; - /// Gets how much the source is trusted: higher is more trusted. - public int? Authority { get; init; } + /// Gets how much the source is trusted: higher is more trusted. + public int? Authority { get; init; } - /// Gets the retrieval score — cosine similarity under one leg, a fused rank score under several — or when a link pulled this card in. - public double? Score { get; init; } + /// Gets the retrieval score — cosine similarity under one leg, a fused rank score under several — or when a link pulled this card in. + public double? Score { get; init; } - /// - /// Gets whatever else the point carried, keyed the way the collection keys it. - /// - public IReadOnlyDictionary Extras { get; init; } = NoExtras; + /// + /// Gets whatever else the point carried, keyed the way the collection keys it. + /// + public IReadOnlyDictionary Extras { get; init; } = NoExtras; + } } diff --git a/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs b/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs index d77d4525..f999e691 100644 --- a/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs +++ b/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs @@ -1,34 +1,35 @@ -namespace AgentCore.Domain.Knowledge; - -/// Where one facet's value came from. -public enum KnowledgeFacetOrigin +namespace AgentCore.Domain.Knowledge { - /// The host resolved it and opened it on the turn. - Host, - - /// The extractor read it out of what the caller said. - Extractor, + /// Where one facet's value came from. + public enum KnowledgeFacetOrigin + { + /// The host resolved it and opened it on the turn. + Host, - /// Nothing knew it, so the facet holds the wildcard and narrows nothing. - Wildcard, + /// The extractor read it out of what the caller said. + Extractor, - /// The search tool's filters argument carried it. - Tool, -} + /// Nothing knew it, so the facet holds the wildcard and narrows nothing. + Wildcard, -/// -/// What one turn is allowed to see of the knowledge base. -/// -public sealed record KnowledgeScope -{ - private static readonly IReadOnlyDictionary NoOrigins = - new Dictionary(StringComparer.Ordinal); - - /// Gets the facet key to required value. Every entry is ANDed into the search filter. - public required IReadOnlyDictionary Facets { get; init; } + /// The search tool's filters argument carried it. + Tool, + } /// - /// Gets where each facet's value came from, or empty when nothing recorded it. + /// What one turn is allowed to see of the knowledge base. /// - public IReadOnlyDictionary Origins { get; init; } = NoOrigins; + public sealed record KnowledgeScope + { + private static readonly IReadOnlyDictionary NoOrigins = + new Dictionary(StringComparer.Ordinal); + + /// Gets the facet key to required value. Every entry is ANDed into the search filter. + public required IReadOnlyDictionary Facets { get; init; } + + /// + /// Gets where each facet's value came from, or empty when nothing recorded it. + /// + public IReadOnlyDictionary Origins { get; init; } = NoOrigins; + } } diff --git a/src/AgentCore.Domain/Knowledge/PayloadPath.cs b/src/AgentCore.Domain/Knowledge/PayloadPath.cs index 695b71ec..7986e6da 100644 --- a/src/AgentCore.Domain/Knowledge/PayloadPath.cs +++ b/src/AgentCore.Domain/Knowledge/PayloadPath.cs @@ -1,39 +1,40 @@ -namespace AgentCore.Domain.Knowledge; - -/// Reads one value out of a neutral payload, walking a dotted path into nested maps. -/// -/// Every path it walks comes from the document. This class knows no field name of its own. -/// -public static class PayloadPath +namespace AgentCore.Domain.Knowledge { - /// Walks a dotted path into a nested payload. - /// The payload to read, such as a card's . - /// The dotted path, or for a role the document never mapped. - /// - /// The value at the path, or where the path names no value, leaves the - /// map partway, or is itself empty. A missing path and a stored null are indistinguishable, which - /// every caller so far treats the same way. - /// - /// is . - public static object? Read(IReadOnlyDictionary payload, string? path) + /// Reads one value out of a neutral payload, walking a dotted path into nested maps. + /// + /// Every path it walks comes from the document. This class knows no field name of its own. + /// + public static class PayloadPath { - ArgumentNullException.ThrowIfNull(payload); - - if (path is not { Length: > 0 }) + /// Walks a dotted path into a nested payload. + /// The payload to read, such as a card's . + /// The dotted path, or for a role the document never mapped. + /// + /// The value at the path, or where the path names no value, leaves the + /// map partway, or is itself empty. A missing path and a stored null are indistinguishable, which + /// every caller so far treats the same way. + /// + /// is . + public static object? Read(IReadOnlyDictionary payload, string? path) { - return null; - } + ArgumentNullException.ThrowIfNull(payload); - object? current = payload; - - foreach (var part in path.Split('.')) - { - if (current is not IReadOnlyDictionary fields || !fields.TryGetValue(part, out current)) + if (path is not { Length: > 0 }) { return null; } - } - return current; + object? current = payload; + + foreach (string part in path.Split('.')) + { + if (current is not IReadOnlyDictionary fields || !fields.TryGetValue(part, out current)) + { + return null; + } + } + + return current; + } } } diff --git a/src/AgentCore.Domain/PendingApproval.cs b/src/AgentCore.Domain/PendingApproval.cs index 8d6609bf..4aee82ed 100644 --- a/src/AgentCore.Domain/PendingApproval.cs +++ b/src/AgentCore.Domain/PendingApproval.cs @@ -1,12 +1,13 @@ using System.Text.Json; -namespace AgentCore.Domain; - -/// -/// One tool call waiting on a human answer: what the model wanted to run, and the id the -/// answer names. -/// -/// The id the approval answer carries back. -/// The tool the model asked to call. -/// The arguments the model produced, as it produced them. -public sealed record PendingApproval(string RequestId, string ToolName, JsonElement Arguments); +namespace AgentCore.Domain +{ + /// + /// One tool call waiting on a human answer: what the model wanted to run, and the id the + /// answer names. + /// + /// The id the approval answer carries back. + /// The tool the model asked to call. + /// The arguments the model produced, as it produced them. + public sealed record PendingApproval(string RequestId, string ToolName, JsonElement Arguments); +} diff --git a/src/AgentCore.Domain/Sources/SourceKind.cs b/src/AgentCore.Domain/Sources/SourceKind.cs index 5318a4d6..24dca833 100644 --- a/src/AgentCore.Domain/Sources/SourceKind.cs +++ b/src/AgentCore.Domain/Sources/SourceKind.cs @@ -1,11 +1,12 @@ -namespace AgentCore.Domain.Sources; - -/// Which of the two shapes a source takes on screen. -public enum SourceKind +namespace AgentCore.Domain.Sources { - /// Something with a title and a place inside it, such as a manual and a page. - Document = 0, + /// Which of the two shapes a source takes on screen. + public enum SourceKind + { + /// Something with a title and a place inside it, such as a manual and a page. + Document = 0, - /// Something with a link the caller can open. - Url = 1, + /// Something with a link the caller can open. + Url = 1, + } } diff --git a/src/AgentCore.Domain/Sources/SourceReference.cs b/src/AgentCore.Domain/Sources/SourceReference.cs index e43c6af7..d10dede9 100644 --- a/src/AgentCore.Domain/Sources/SourceReference.cs +++ b/src/AgentCore.Domain/Sources/SourceReference.cs @@ -1,28 +1,29 @@ -namespace AgentCore.Domain.Sources; - -/// -/// One thing the caller is shown as the origin of an answer. -/// -public sealed record SourceReference +namespace AgentCore.Domain.Sources { - /// Gets the id of this source, unique within one turn. Publishing it twice shows it once. - public required string SourceId { get; init; } + /// + /// One thing the caller is shown as the origin of an answer. + /// + public sealed record SourceReference + { + /// Gets the id of this source, unique within one turn. Publishing it twice shows it once. + public required string SourceId { get; init; } - /// Gets which of the two shapes this source takes. - public required SourceKind Kind { get; init; } + /// Gets which of the two shapes this source takes. + public required SourceKind Kind { get; init; } - /// Gets what this source is called, as the caller should read it. - public required string Title { get; init; } + /// Gets what this source is called, as the caller should read it. + public required string Title { get; init; } - /// Gets what produced this source, such as knowledge. Free text the screen may group by. - public required string Origin { get; init; } + /// Gets what produced this source, such as knowledge. Free text the screen may group by. + public required string Origin { get; init; } - /// Gets where inside the source it sits, such as p.27. Empty when the producer has none. - public string Locator { get; init; } = string.Empty; + /// Gets where inside the source it sits, such as p.27. Empty when the producer has none. + public string Locator { get; init; } = string.Empty; - /// Gets the link the caller may open, or when there is nothing to open. - public string? Url { get; init; } + /// Gets the link the caller may open, or when there is nothing to open. + public string? Url { get; init; } - /// Gets the media type of the source, for a producer that knows one. - public string MediaType { get; init; } = "text/plain"; + /// Gets the media type of the source, for a producer that knows one. + public string MediaType { get; init; } = "text/plain"; + } } diff --git a/src/AgentCore.Domain/TurnResult.cs b/src/AgentCore.Domain/TurnResult.cs index 36298664..7d45fd98 100644 --- a/src/AgentCore.Domain/TurnResult.cs +++ b/src/AgentCore.Domain/TurnResult.cs @@ -1,80 +1,81 @@ -namespace AgentCore.Domain; - -/// -/// What one finished turn did to one conversation. -/// -/// -/// -/// The turn loop produces one of these for each turn, and the host reads it. It is a pure record and -/// it holds no live object, so it crosses a process boundary and a log line unchanged. -/// -/// -/// A failed extraction is reported here and never thrown. The extractor has no retry, so a turn that -/// filled no slot still ends, the machine still picks a stage, and the caller still hears the reply. -/// -/// -/// A failed turn is reported the same way. Section 8.7 gives the turn loop two failures it must -/// survive: a run that returns an empty reply after 40 tool rounds, and a tool that fails four times -/// in a row. Both end the turn with a spoken fallback, both fill , and neither -/// drops the conversation. -/// -/// -/// is always the text the caller heard. It is the fallback when the turn -/// failed, and it is utteranceUntilInterrupt when the caller spoke over the reply. Nothing -/// here is estimated: section 7.1 says the relay reports both truncation values, so the audit row of -/// item 6a reads them and never computes them. -/// -/// -/// The id of the conversation this turn belongs to. -/// The zero-based index of the turn that just ran. -/// -/// The stage the turn ran in. It is empty when the document declares no policy:. -/// -/// -/// The stage the machine holds after the turn. It equals when no exit -/// guard is true, and when the document declares no policy:. -/// -/// -/// The text the caller heard. It is what the agent spoke, the spoken fallback when -/// is set, and the truncated reply when -/// is set. -/// -/// Whether the stage after the turn ends the conversation. -/// -/// The reason the extractor produced nothing, or when it ran or did not run. -/// -/// -/// The reason the turn spoke the fallback instead of a reply, or when the turn -/// answered. It names the row of section 8.7 that the turn met. -/// -/// -/// How long the caller heard the reply before speaking over it, or when the -/// caller did not interrupt. The relay reports it at 1 ms, so it is never estimated. -/// -/// -/// The moment the turn ended, read from the clock the turn loop was given. The audit chain of D23 -/// stamps occurred_at from it. The sink runs behind a bounded Channel and a background -/// writer, so a writer that read its own clock would stamp the event one enqueue late and a slow -/// queue would move the record of the conversation. The turn loop reads the clock once, when the turn ends, -/// and every event of that turn carries the same moment. A record a caller builds by hand and leaves -/// unset reads default. -/// -public sealed record TurnResult( - string ConversationId, - int TurnIndex, - string StageBefore, - string StageAfter, - string ReplyText, - bool IsTerminal, - string? ExtractionFailure, - string? Failure = null, - TimeSpan? InterruptedAfter = null, - DateTimeOffset EndedAt = default) +namespace AgentCore.Domain { /// - /// Gets the tool calls still waiting on a human answer when the turn ended, oldest first. - /// Empty on every other turn. A pending turn is not a failure: stays - /// and stays empty while these are set. + /// What one finished turn did to one conversation. /// - public IReadOnlyList Approvals { get; init; } = []; + /// + /// + /// The turn loop produces one of these for each turn, and the host reads it. It is a pure record and + /// it holds no live object, so it crosses a process boundary and a log line unchanged. + /// + /// + /// A failed extraction is reported here and never thrown. The extractor has no retry, so a turn that + /// filled no slot still ends, the machine still picks a stage, and the caller still hears the reply. + /// + /// + /// A failed turn is reported the same way. Section 8.7 gives the turn loop two failures it must + /// survive: a run that returns an empty reply after 40 tool rounds, and a tool that fails four times + /// in a row. Both end the turn with a spoken fallback, both fill , and neither + /// drops the conversation. + /// + /// + /// is always the text the caller heard. It is the fallback when the turn + /// failed, and it is utteranceUntilInterrupt when the caller spoke over the reply. Nothing + /// here is estimated: section 7.1 says the relay reports both truncation values, so the audit row of + /// item 6a reads them and never computes them. + /// + /// + /// The id of the conversation this turn belongs to. + /// The zero-based index of the turn that just ran. + /// + /// The stage the turn ran in. It is empty when the document declares no policy:. + /// + /// + /// The stage the machine holds after the turn. It equals when no exit + /// guard is true, and when the document declares no policy:. + /// + /// + /// The text the caller heard. It is what the agent spoke, the spoken fallback when + /// is set, and the truncated reply when + /// is set. + /// + /// Whether the stage after the turn ends the conversation. + /// + /// The reason the extractor produced nothing, or when it ran or did not run. + /// + /// + /// The reason the turn spoke the fallback instead of a reply, or when the turn + /// answered. It names the row of section 8.7 that the turn met. + /// + /// + /// How long the caller heard the reply before speaking over it, or when the + /// caller did not interrupt. The relay reports it at 1 ms, so it is never estimated. + /// + /// + /// The moment the turn ended, read from the clock the turn loop was given. The audit chain of D23 + /// stamps occurred_at from it. The sink runs behind a bounded Channel and a background + /// writer, so a writer that read its own clock would stamp the event one enqueue late and a slow + /// queue would move the record of the conversation. The turn loop reads the clock once, when the turn ends, + /// and every event of that turn carries the same moment. A record a caller builds by hand and leaves + /// unset reads default. + /// + public sealed record TurnResult( + string ConversationId, + int TurnIndex, + string StageBefore, + string StageAfter, + string ReplyText, + bool IsTerminal, + string? ExtractionFailure, + string? Failure = null, + TimeSpan? InterruptedAfter = null, + DateTimeOffset EndedAt = default) + { + /// + /// Gets the tool calls still waiting on a human answer when the turn ended, oldest first. + /// Empty on every other turn. A pending turn is not a failure: stays + /// and stays empty while these are set. + /// + public IReadOnlyList Approvals { get; init; } = []; + } } diff --git a/src/AgentCore.Hosting/AgentCoreHostBuilderExtensions.cs b/src/AgentCore.Hosting/AgentCoreHostBuilderExtensions.cs index 6f6532c5..0b55aa01 100644 --- a/src/AgentCore.Hosting/AgentCoreHostBuilderExtensions.cs +++ b/src/AgentCore.Hosting/AgentCoreHostBuilderExtensions.cs @@ -17,202 +17,203 @@ using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; -namespace AgentCore.Hosting; - -/// -/// Registers everything AgentCore needs to run, in one conversation. -/// -public static class AgentCoreHostBuilderExtensions +namespace AgentCore.Hosting { - /// The configuration key that names the document to load. - public const string ConfigurationPathKey = "AgentCore:ConfigurationPath"; - - /// The document loaded when names none. - public const string DefaultConfigurationPath = "config/example.yaml"; - - /// The binds: name the shipped example document declares. - public const string CreateCaseBinding = "CreateCase"; - - /// The name a transport: http MCP server's handler chain is opened under. - public const string McpHttpClientName = "agentcore.mcp"; - - /// Registers every vendor seam, and loads the document when the host starts. - /// The host being built. - /// - /// The host's own word on the options, run after the defaults below and therefore winning over - /// every one of them. A host uses it to bind a kind: binding delegate, to add a vendor - /// this library does not name, or to replace the document, the secret resolver, the logger - /// factory, or any vendor seam. - /// - /// The same builder, so a host chains its conversations. - /// is . - public static WebApplicationBuilder AddAgentCoreHost( - this WebApplicationBuilder builder, - Action? configure = null) + /// + /// Registers everything AgentCore needs to run, in one conversation. + /// + public static class AgentCoreHostBuilderExtensions { - ArgumentNullException.ThrowIfNull(builder); - - builder.Logging.AddConsole(); - - builder.Services.AddSingleton(provider => new AgentCoreHttpClients( - loggers: provider.GetRequiredService())); - - builder.Services - .AddOptions() - .Configure( - (options, httpClients, hostConfiguration, loggers) => - Configure(hostConfiguration, options, httpClients, loggers)); + /// The configuration key that names the document to load. + public const string ConfigurationPathKey = "AgentCore:ConfigurationPath"; + + /// The document loaded when names none. + public const string DefaultConfigurationPath = "config/example.yaml"; + + /// The binds: name the shipped example document declares. + public const string CreateCaseBinding = "CreateCase"; + + /// The name a transport: http MCP server's handler chain is opened under. + public const string McpHttpClientName = "agentcore.mcp"; + + /// Registers every vendor seam, and loads the document when the host starts. + /// The host being built. + /// + /// The host's own word on the options, run after the defaults below and therefore winning over + /// every one of them. A host uses it to bind a kind: binding delegate, to add a vendor + /// this library does not name, or to replace the document, the secret resolver, the logger + /// factory, or any vendor seam. + /// + /// The same builder, so a host chains its conversations. + /// is . + public static WebApplicationBuilder AddAgentCoreHost( + this WebApplicationBuilder builder, + Action? configure = null) + { + ArgumentNullException.ThrowIfNull(builder); - builder.Services.AddAgentCore(options => configure?.Invoke(options)); + _ = builder.Logging.AddConsole(); - builder.Services.PostConfigure(FinishConfiguring); + _ = builder.Services.AddSingleton(provider => new AgentCoreHttpClients( + loggers: provider.GetRequiredService())); - builder.Services.AddAgentCoreWebSockets(); + _ = builder.Services + .AddOptions() + .Configure( + (options, httpClients, hostConfiguration, loggers) => + Configure(hostConfiguration, options, httpClients, loggers)); - return builder; - } + _ = builder.Services.AddAgentCore(options => configure?.Invoke(options)); - /// Fills the options with this library's defaults. - /// The host's own configuration, read for the document path and for secrets. - /// The options registered. - /// The one outbound pipeline every adapter shares. - /// The host's own logging, for the adapters that report what they are doing. - /// - /// The host's own configure callback is registered after this one, and configure - /// callbacks run in registration order — so the host still has the last word, which it has to - /// have: every Use* seam is a setter rather than a list, so whoever writes last wins. - /// - private static void Configure( - IConfiguration hostConfiguration, - AgentCoreOptions options, - AgentCoreHttpClients httpClients, - ILoggerFactory loggers) - { - options.ConfigurationPath = - hostConfiguration[ConfigurationPathKey] ?? DefaultConfigurationPath; + _ = builder.Services.PostConfigure(FinishConfiguring); - options.SecretResolver = new ChainedSecretResolver( - [ - new EnvironmentSecretResolver(), - new FileSecretResolver(), - new ConfigurationSecretResolver(hostConfiguration), - ]); + _ = builder.Services.AddAgentCoreWebSockets(); - // providers.llm[].kind picks the adapter for each entry. - options.UseChatClients(new OpenAiChatClientAdapter()); + return builder; + } - // providers.embeddings.kind picks the adapter. - options.UseEmbeddings(new OpenAiEmbeddingGeneratorAdapter()); + /// Fills the options with this library's defaults. + /// The host's own configuration, read for the document path and for secrets. + /// The options registered. + /// The one outbound pipeline every adapter shares. + /// The host's own logging, for the adapters that report what they are doing. + /// + /// The host's own configure callback is registered after this one, and configure + /// callbacks run in registration order — so the host still has the last word, which it has to + /// have: every Use* seam is a setter rather than a list, so whoever writes last wins. + /// + private static void Configure( + IConfiguration hostConfiguration, + AgentCoreOptions options, + AgentCoreHttpClients httpClients, + ILoggerFactory loggers) + { + options.ConfigurationPath = + hostConfiguration[ConfigurationPathKey] ?? DefaultConfigurationPath; - // providers.knowledge.kind picks the adapter. - options.UseKnowledgeStores(new QdrantKnowledgeAdapter()); + options.SecretResolver = new ChainedSecretResolver( + [ + new EnvironmentSecretResolver(), + new FileSecretResolver(), + new ConfigurationSecretResolver(hostConfiguration), + ]); - // providers.moderation.kind picks the adapter. - options.UseModeration(new OpenAiModerationAdapter(httpClients)); + // providers.llm[].kind picks the adapter for each entry. + _ = options.UseChatClients(new OpenAiChatClientAdapter()); - // providers.telemetry.kind picks the adapter. - options.UseTelemetry(new GrafanaOtlpTelemetryAdapter()); + // providers.embeddings.kind picks the adapter. + _ = options.UseEmbeddings(new OpenAiEmbeddingGeneratorAdapter()); - // providers.conversation.kind picks one. - options.UseConversation(new TelnyxRelayConversationAdapter()); + // providers.knowledge.kind picks the adapter. + _ = options.UseKnowledgeStores(new QdrantKnowledgeAdapter()); - // The speech vendor. - options.UseSpeech(new TelnyxRelaySpeechAdapter()); + // providers.moderation.kind picks the adapter. + _ = options.UseModeration(new OpenAiModerationAdapter(httpClients)); - // kind: http. Every header resolved at startup, so no tool call costs a lookup. - options.AddToolSource(startup => - new HttpToolSource(httpClients.CreateClient(HttpToolSource.HttpClientName), startup.Secrets)); + // providers.telemetry.kind picks the adapter. + _ = options.UseTelemetry(new GrafanaOtlpTelemetryAdapter()); - // mcp:. headers: and env: resolved at startup like every other credential. - options.AddToolSource(startup => new McpToolSource( - startup.Secrets, () => McpHttpClient(httpClients), loggers)); + // providers.conversation.kind picks one. + _ = options.UseConversation(new TelnyxRelayConversationAdapter()); - // providers.audit.kind picks the adapter. - options.UseAuditSinks(new PostgresAuditSinkAdapter()); + // The speech vendor. + _ = options.UseSpeech(new TelnyxRelaySpeechAdapter()); - // providers.conversations.kind picks the adapter. - options.UseConversationStores(new PostgresConversationStoreAdapter()); + // kind: http. Every header resolved at startup, so no tool call costs a lookup. + _ = options.AddToolSource(startup => + new HttpToolSource(httpClients.CreateClient(HttpToolSource.HttpClientName), startup.Secrets)); - // providers.blobs.kind picks the adapter. - options.UseBlobStores(new S3BlobStoreAdapter()); - } + // mcp:. headers: and env: resolved at startup like every other credential. + _ = options.AddToolSource(startup => new McpToolSource( + startup.Secrets, () => McpHttpClient(httpClients), loggers)); - /// Opens the client a transport: http MCP server is reached on. - /// The one outbound pipeline every adapter shares. - /// The client. The pipeline owns the handler under it, so nothing here disposes it. - internal static HttpClient McpHttpClient(AgentCoreHttpClients pipeline) - { - ArgumentNullException.ThrowIfNull(pipeline); + // providers.audit.kind picks the adapter. + _ = options.UseAuditSinks(new PostgresAuditSinkAdapter()); - return new HttpClient(pipeline.CreateHandler(McpHttpClientName), disposeHandler: false) - { - Timeout = Timeout.InfiniteTimeSpan, - }; - } + // providers.conversations.kind picks the adapter. + _ = options.UseConversationStores(new PostgresConversationStoreAdapter()); - /// Settles what only the last word can decide, once every seam has been written. - /// The options every configure callback has now filled. - private static void FinishConfiguring(AgentCoreOptions options) - { - if (options.Configuration is not null) - { - options.ConfigurationPath = null; + // providers.blobs.kind picks the adapter. + _ = options.UseBlobStores(new S3BlobStoreAdapter()); } - AddCreateCaseStub(options); - ApplyKnowledgeQueryAnalyzers(options); - ApplyKnowledgePointMappers(options); - } - - /// - /// Hands a host's call to the - /// the defaults registered. - /// - private static void ApplyKnowledgeQueryAnalyzers(AgentCoreOptions options) - { - if (options.KnowledgeAnalyzers.Count == 0) + /// Opens the client a transport: http MCP server is reached on. + /// The one outbound pipeline every adapter shares. + /// The client. The pipeline owns the handler under it, so nothing here disposes it. + internal static HttpClient McpHttpClient(AgentCoreHttpClients pipeline) { - return; - } + ArgumentNullException.ThrowIfNull(pipeline); - if (options.KnowledgeStores?.OfType().FirstOrDefault() is { } knowledge) - { - knowledge.UseAnalyzers([.. options.KnowledgeAnalyzers]); + return new HttpClient(pipeline.CreateHandler(McpHttpClientName), disposeHandler: false) + { + Timeout = Timeout.InfiniteTimeSpan, + }; } - } - /// - /// Hands a host's call to the - /// the defaults registered. Same post-configure timing - /// rationale as . - /// - private static void ApplyKnowledgePointMappers(AgentCoreOptions options) - { - if (options.KnowledgeMappers.Count == 0) + /// Settles what only the last word can decide, once every seam has been written. + /// The options every configure callback has now filled. + private static void FinishConfiguring(AgentCoreOptions options) { - return; + if (options.Configuration is not null) + { + options.ConfigurationPath = null; + } + + AddCreateCaseStub(options); + ApplyKnowledgeQueryAnalyzers(options); + ApplyKnowledgePointMappers(options); } - if (options.KnowledgeStores?.OfType().FirstOrDefault() is { } knowledge) + /// + /// Hands a host's call to the + /// the defaults registered. + /// + private static void ApplyKnowledgeQueryAnalyzers(AgentCoreOptions options) { - knowledge.UseMappers([.. options.KnowledgeMappers]); + if (options.KnowledgeAnalyzers.Count == 0) + { + return; + } + + if (options.KnowledgeStores?.OfType().FirstOrDefault() is { } knowledge) + { + _ = knowledge.UseAnalyzers([.. options.KnowledgeAnalyzers]); + } } - } - /// Registers the example document's binding, when the host registered none. - /// The options to bind the name on. - private static void AddCreateCaseStub(AgentCoreOptions options) - { - if (options.Bindings.Names.Contains(CreateCaseBinding, StringComparer.Ordinal)) + /// + /// Hands a host's call to the + /// the defaults registered. Same post-configure timing + /// rationale as . + /// + private static void ApplyKnowledgePointMappers(AgentCoreOptions options) { - return; + if (options.KnowledgeMappers.Count == 0) + { + return; + } + + if (options.KnowledgeStores?.OfType().FirstOrDefault() is { } knowledge) + { + _ = knowledge.UseMappers([.. options.KnowledgeMappers]); + } } - options.Bind(CreateCaseBinding, (arguments, _) => ValueTask.FromResult(new JsonObject + /// Registers the example document's binding, when the host registered none. + /// The options to bind the name on. + private static void AddCreateCaseStub(AgentCoreOptions options) { - ["opened"] = false, - ["summary"] = arguments["summary"]?.DeepClone(), - ["reason"] = "this host has no case system bound. Register a CreateCase delegate that opens one.", - })); + if (options.Bindings.Names.Contains(CreateCaseBinding, StringComparer.Ordinal)) + { + return; + } + + _ = options.Bind(CreateCaseBinding, (arguments, _) => ValueTask.FromResult(new JsonObject + { + ["opened"] = false, + ["summary"] = arguments["summary"]?.DeepClone(), + ["reason"] = "this host has no case system bound. Register a CreateCase delegate that opens one.", + })); + } } } diff --git a/src/AgentCore.Hosting/AgentCoreHostEndpointExtensions.cs b/src/AgentCore.Hosting/AgentCoreHostEndpointExtensions.cs index 85c73739..60bec7e9 100644 --- a/src/AgentCore.Hosting/AgentCoreHostEndpointExtensions.cs +++ b/src/AgentCore.Hosting/AgentCoreHostEndpointExtensions.cs @@ -3,42 +3,43 @@ using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; -namespace AgentCore.Hosting; - -/// -/// Maps every route AgentCore answers on, in one conversation. -/// -public static class AgentCoreHostEndpointExtensions +namespace AgentCore.Hosting { - /// The route the liveness check answers on. - public const string HealthPattern = "/health"; - - /// Installs the WebSocket middleware and maps health, the Responses endpoint, and the conversation socket. - /// The application to map on. - /// - /// The route the OpenAI-compatible Responses endpoint answers on, with {entry} naming - /// the entry, or for - /// . - /// - /// - /// The route the conversation socket answers on, with {entry} naming the entry, or - /// for . - /// - /// The same application, so a host chains its conversations. - /// is . - public static WebApplication MapAgentCoreHost( - this WebApplication app, string? responsesPattern = null, string? conversationPattern = null) + /// + /// Maps every route AgentCore answers on, in one conversation. + /// + public static class AgentCoreHostEndpointExtensions { - ArgumentNullException.ThrowIfNull(app); - - app.MapGet(HealthPattern, () => Results.Ok("ok")); - - app.UseWebSockets(); - - app.MapResponses(responsesPattern ?? ResponsesEndpointRouteBuilderExtensions.DefaultPattern); - - app.MapCall(conversationPattern ?? ConversationEndpointRouteBuilderExtensions.DefaultPattern); - - return app; + /// The route the liveness check answers on. + public const string HealthPattern = "/health"; + + /// Installs the WebSocket middleware and maps health, the Responses endpoint, and the conversation socket. + /// The application to map on. + /// + /// The route the OpenAI-compatible Responses endpoint answers on, with {entry} naming + /// the entry, or for + /// . + /// + /// + /// The route the conversation socket answers on, with {entry} naming the entry, or + /// for . + /// + /// The same application, so a host chains its conversations. + /// is . + public static WebApplication MapAgentCoreHost( + this WebApplication app, string? responsesPattern = null, string? conversationPattern = null) + { + ArgumentNullException.ThrowIfNull(app); + + _ = app.MapGet(HealthPattern, () => Results.Ok("ok")); + + _ = app.UseWebSockets(); + + _ = app.MapResponses(responsesPattern ?? ResponsesEndpointRouteBuilderExtensions.DefaultPattern); + + _ = app.MapCall(conversationPattern ?? ConversationEndpointRouteBuilderExtensions.DefaultPattern); + + return app; + } } } diff --git a/src/AgentCore.Hosting/Secrets/ConfigurationSecretResolver.cs b/src/AgentCore.Hosting/Secrets/ConfigurationSecretResolver.cs index 06e85f5c..00bd9160 100644 --- a/src/AgentCore.Hosting/Secrets/ConfigurationSecretResolver.cs +++ b/src/AgentCore.Hosting/Secrets/ConfigurationSecretResolver.cs @@ -2,47 +2,51 @@ using AgentCore.Infrastructure.Secrets; using Microsoft.Extensions.Configuration; -namespace AgentCore.Hosting.Secrets; - -/// -/// Reads a secret from one section of the host's own configuration. -/// -internal sealed class ConfigurationSecretResolver : ISecretResolverPort +namespace AgentCore.Hosting.Secrets { - /// The section a secret is read from. Nothing outside it is read at all. - internal const string SectionKey = "AgentCore:Secrets"; - - private readonly IConfiguration _configuration; - - /// Creates a resolver over one configuration root. - /// The host's configuration. - public ConfigurationSecretResolver(IConfiguration configuration) + /// + /// Reads a secret from one section of the host's own configuration. + /// + internal sealed class ConfigurationSecretResolver : ISecretResolverPort { - ArgumentNullException.ThrowIfNull(configuration); - _configuration = configuration; - } + /// The section a secret is read from. Nothing outside it is read at all. + internal const string SectionKey = "AgentCore:Secrets"; - /// Reads the value of one secret. - /// The name the document wrote. - /// Cancels the read. - /// The value, or when the section holds neither form. - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(name); - cancellationToken.ThrowIfCancellationRequested(); + private readonly IConfiguration _configuration; - if (name.Length == 0) + /// Creates a resolver over one configuration root. + /// The host's configuration. + public ConfigurationSecretResolver(IConfiguration configuration) { - return ValueTask.FromResult(null); + ArgumentNullException.ThrowIfNull(configuration); + _configuration = configuration; } - var section = _configuration.GetSection(SectionKey); + /// Reads the value of one secret. + /// The name the document wrote. + /// Cancels the read. + /// The value, or when the section holds neither form. + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(name); + cancellationToken.ThrowIfCancellationRequested(); - var value = Empty(section[name]) ?? Empty(section[EnvironmentSecretResolver.ToVariableName(name)]); + if (name.Length == 0) + { + return ValueTask.FromResult(null); + } - return ValueTask.FromResult(value); - } + IConfigurationSection section = _configuration.GetSection(SectionKey); - /// Reads an empty setting as an unset one, so the chain goes on. - private static string? Empty(string? value) => value is { Length: > 0 } ? value : null; + string? value = Empty(section[name]) ?? Empty(section[EnvironmentSecretResolver.ToVariableName(name)]); + + return ValueTask.FromResult(value); + } + + /// Reads an empty setting as an unset one, so the chain goes on. + private static string? Empty(string? value) + { + return value is { Length: > 0 } ? value : null; + } + } } diff --git a/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSink.cs b/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSink.cs index 3af62ab6..436fcba4 100644 --- a/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSink.cs +++ b/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSink.cs @@ -7,20 +7,20 @@ using Npgsql; using NpgsqlTypes; -namespace AgentCore.Infrastructure.Audit.Postgres; - -/// -/// Store 3, in PostgreSQL. It appends and it never updates. -/// -internal sealed class PostgresAuditSink : IAuditSinkPort, IAsyncDisposable +namespace AgentCore.Infrastructure.Audit.Postgres { - private const string Schema = PostgresSchema.SchemaName; + /// + /// Store 3, in PostgreSQL. It appends and it never updates. + /// + internal sealed class PostgresAuditSink : IAuditSinkPort, IAsyncDisposable + { + private const string Schema = PostgresSchema.SchemaName; - /// Serialises the writers of one conversation so two of them cannot pick the same sequence. - internal const string LockSql = "SELECT pg_advisory_xact_lock(hashtext($1))"; + /// Serialises the writers of one conversation so two of them cannot pick the same sequence. + internal const string LockSql = "SELECT pg_advisory_xact_lock(hashtext($1))"; - /// Appends one conversation's run, numbering only the rows that will actually survive. - internal const string AppendSql = $""" + /// Appends one conversation's run, numbering only the rows that will actually survive. + internal const string AppendSql = $""" INSERT INTO {Schema}.audit_event ( conversation_id, event_id, sequence, kind, occurred_at, turn_index, amends_event_id, payload) SELECT $1, @@ -37,137 +37,141 @@ WHERE NOT EXISTS ( ON CONFLICT (conversation_id, event_id) DO NOTHING """; - private readonly NpgsqlDataSource _dataSource; - - /// Creates the sink over a data source it then owns. - /// The pool every append runs on. Disposing the sink disposes it. - /// The data source is . - public PostgresAuditSink(NpgsqlDataSource dataSource) - { - ArgumentNullException.ThrowIfNull(dataSource); - _dataSource = dataSource; - } - - /// - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(auditEvent); - return AppendManyAsync([auditEvent], cancellationToken); - } - - /// - public async ValueTask AppendManyAsync( - IReadOnlyList auditEvents, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(auditEvents); + private readonly NpgsqlDataSource _dataSource; - if (auditEvents.Count == 0) + /// Creates the sink over a data source it then owns. + /// The pool every append runs on. Disposing the sink disposes it. + /// The data source is . + public PostgresAuditSink(NpgsqlDataSource dataSource) { - return; + ArgumentNullException.ThrowIfNull(dataSource); + _dataSource = dataSource; } - // Every event is checked before any of them is written, so a run that holds one malformed - // event writes none of it and the caller learns which rule it broke. - foreach (AuditEvent auditEvent in auditEvents) + /// + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { - AuditEventVocabulary.Validate(auditEvent); + ArgumentNullException.ThrowIfNull(auditEvent); + return AppendManyAsync([auditEvent], cancellationToken); } - await using var connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); - await using var transaction = await connection.BeginTransactionAsync(cancellationToken).ConfigureAwait(false); - await using NpgsqlBatch batch = new(connection, transaction); - - // Grouped, because the queue in front of this sink batches across conversations, and a conversation is the - // unit the sequence counts within. Ordered by conversation id, because two transactions that each - // hold two conversations would otherwise be able to take the two locks in opposite orders and wait - // on each other forever. Best effort, and only that: the lock is on hashtext(conversation_id), so a - // consistent order on ids is a consistent order on locks only while the hash is injective - // over the ids in play. See the remarks on LockSql for what a collision costs. - foreach (var conversation in auditEvents - .GroupBy(item => item.ConversationId, StringComparer.Ordinal) - .OrderBy(group => group.Key, StringComparer.Ordinal)) + /// + public async ValueTask AppendManyAsync( + IReadOnlyList auditEvents, + CancellationToken cancellationToken = default) { - NpgsqlBatchCommand lockCommand = new(LockSql); - lockCommand.Parameters.Add(new NpgsqlParameter { Value = conversation.Key }); - batch.BatchCommands.Add(lockCommand); + ArgumentNullException.ThrowIfNull(auditEvents); - batch.BatchCommands.Add(AppendCommand(conversation.Key, [.. conversation])); - } + if (auditEvents.Count == 0) + { + return; + } - // One round trip for the run. A durable insert is ~13 ms, so twenty apart cost 260 ms and - // twenty together cost 13 ms. - await batch.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - await transaction.CommitAsync(cancellationToken).ConfigureAwait(false); - } + // Every event is checked before any of them is written, so a run that holds one malformed + // event writes none of it and the caller learns which rule it broke. + foreach (AuditEvent auditEvent in auditEvents) + { + AuditEventVocabulary.Validate(auditEvent); + } - /// - /// Disposes the pool this sink was given. - /// - /// A task that completes when the pool is closed. - public ValueTask DisposeAsync() => _dataSource.DisposeAsync(); - - [SuppressMessage( - "csharpsquid", - "S3265", - Justification = "Npgsql documents Array combined with an element type via bit OR, and the enum omits Flags only upstream.")] - private static NpgsqlBatchCommand AppendCommand(string conversationId, IReadOnlyList run) - { - NpgsqlBatchCommand command = new(AppendSql); + await using NpgsqlConnection connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); + await using NpgsqlTransaction transaction = await connection.BeginTransactionAsync(cancellationToken).ConfigureAwait(false); + await using NpgsqlBatch batch = new(connection, transaction); + + // Grouped, because the queue in front of this sink batches across conversations, and a conversation is the + // unit the sequence counts within. Ordered by conversation id, because two transactions that each + // hold two conversations would otherwise be able to take the two locks in opposite orders and wait + // on each other forever. Best effort, and only that: the lock is on hashtext(conversation_id), so a + // consistent order on ids is a consistent order on locks only while the hash is injective + // over the ids in play. See the remarks on LockSql for what a collision costs. + foreach (IGrouping? conversation in auditEvents + .GroupBy(item => item.ConversationId, StringComparer.Ordinal) + .OrderBy(group => group.Key, StringComparer.Ordinal)) + { + NpgsqlBatchCommand lockCommand = new(LockSql); + _ = lockCommand.Parameters.Add(new NpgsqlParameter { Value = conversation.Key }); + batch.BatchCommands.Add(lockCommand); + + batch.BatchCommands.Add(AppendCommand(conversation.Key, [.. conversation])); + } - // Two events in the same batch sharing an EventId would both survive the NOT EXISTS filter - // (neither is in the table yet), so row_number() would number the duplicate too and - // ON CONFLICT would then silently drop it — reserving a sequence for a row that never lands. - // One survivor per EventId keeps the numbering dense. - AuditEvent[] distinct = [.. run.DistinctBy(item => item.EventId)]; + // One round trip for the run. A durable insert is ~13 ms, so twenty apart cost 260 ms and + // twenty together cost 13 ms. + _ = await batch.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + await transaction.CommitAsync(cancellationToken).ConfigureAwait(false); + } - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. distinct.Select(item => item.EventId)], - }); - command.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. distinct.Select(item => AuditEventKinds.ToToken(item.Kind))], - }); - command.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. distinct.Select(item => item.OccurredAt)], - }); - command.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. distinct.Select(item => item.TurnIndex)], - }); - command.Parameters.Add(new NpgsqlParameter + /// + /// Disposes the pool this sink was given. + /// + /// A task that completes when the pool is closed. + public ValueTask DisposeAsync() { - TypedValue = [.. distinct.Select(item => item.AmendsEventId)], - }); - command.Parameters.Add(new NpgsqlParameter + return _dataSource.DisposeAsync(); + } + + [SuppressMessage( + "csharpsquid", + "S3265", + Justification = "Npgsql documents Array combined with an element type via bit OR, and the enum omits Flags only upstream.")] + private static NpgsqlBatchCommand AppendCommand(string conversationId, IReadOnlyList run) { - Value = distinct.Select(item => PayloadJson(item.Payload)).ToArray(), - NpgsqlDbType = NpgsqlDbType.Array | NpgsqlDbType.Jsonb, - }); + NpgsqlBatchCommand command = new(AppendSql); - return command; - } + // Two events in the same batch sharing an EventId would both survive the NOT EXISTS filter + // (neither is in the table yet), so row_number() would number the duplicate too and + // ON CONFLICT would then silently drop it — reserving a sequence for a row that never lands. + // One survivor per EventId keeps the numbering dense. + AuditEvent[] distinct = [.. run.DistinctBy(item => item.EventId)]; - /// - /// Writes the payload as a flat JSON object of strings. - /// - private static string PayloadJson(IReadOnlyDictionary payload) - { - using MemoryStream buffer = new(); - using (Utf8JsonWriter writer = new(buffer)) + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. distinct.Select(item => item.EventId)], + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. distinct.Select(item => AuditEventKinds.ToToken(item.Kind))], + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. distinct.Select(item => item.OccurredAt)], + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. distinct.Select(item => item.TurnIndex)], + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. distinct.Select(item => item.AmendsEventId)], + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + Value = distinct.Select(item => PayloadJson(item.Payload)).ToArray(), + NpgsqlDbType = NpgsqlDbType.Array | NpgsqlDbType.Jsonb, + }); + + return command; + } + + /// + /// Writes the payload as a flat JSON object of strings. + /// + private static string PayloadJson(IReadOnlyDictionary payload) { - writer.WriteStartObject(); - foreach (KeyValuePair entry in payload) + using MemoryStream buffer = new(); + using (Utf8JsonWriter writer = new(buffer)) { - writer.WriteString(entry.Key, entry.Value); + writer.WriteStartObject(); + foreach (KeyValuePair entry in payload) + { + writer.WriteString(entry.Key, entry.Value); + } + + writer.WriteEndObject(); } - writer.WriteEndObject(); + return Encoding.UTF8.GetString(buffer.ToArray()); } - - return Encoding.UTF8.GetString(buffer.ToArray()); } } diff --git a/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSinkAdapter.cs b/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSinkAdapter.cs index cb12fc76..cc0156dd 100644 --- a/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSinkAdapter.cs +++ b/src/AgentCore.Infrastructure/Audit/Postgres/PostgresAuditSinkAdapter.cs @@ -3,36 +3,37 @@ using AgentCore.Infrastructure.Database.Postgres; using Npgsql; -namespace AgentCore.Infrastructure.Audit.Postgres; - -/// -/// The postgres audit vendor behind . -/// -public sealed class PostgresAuditSinkAdapter : IAuditSinkAdapter +namespace AgentCore.Infrastructure.Audit.Postgres { /// - /// The one kind value this adapter serves. + /// The postgres audit vendor behind . /// - public const string ProviderKind = "postgres"; + public sealed class PostgresAuditSinkAdapter : IAuditSinkAdapter + { + /// + /// The one kind value this adapter serves. + /// + public const string ProviderKind = "postgres"; - /// - /// Gets the one kind value this adapter serves. - /// - public string Kind => ProviderKind; + /// + /// Gets the one kind value this adapter serves. + /// + public string Kind => ProviderKind; - /// - public async ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - NpgsqlDataSource dataSource = await PostgresDataSourceFactory - .OpenMigratedAsync( - secrets, - "The audit chain of providers.audit is written to PostgreSQL.", - cancellationToken) - .ConfigureAwait(false); + /// + public async ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + NpgsqlDataSource dataSource = await PostgresDataSourceFactory + .OpenMigratedAsync( + secrets, + "The audit chain of providers.audit is written to PostgreSQL.", + cancellationToken) + .ConfigureAwait(false); - return new PostgresAuditSink(dataSource); + return new PostgresAuditSink(dataSource); + } } } diff --git a/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStore.cs b/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStore.cs index 8d3b1f9d..f851a125 100644 --- a/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStore.cs +++ b/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStore.cs @@ -4,196 +4,196 @@ using Amazon.S3; using Amazon.S3.Model; -namespace AgentCore.Infrastructure.Blobs.S3; - -/// -/// on any S3-compatible bucket: Backblaze B2 today, Tigris or AWS tomorrow. -/// -public sealed class S3BlobStore : IBlobStore, IDisposable +namespace AgentCore.Infrastructure.Blobs.S3 { - /// The most keys one DeleteObjects call accepts. - private const int DeleteBatchSize = 1000; - - private readonly IAmazonS3 _client; - - private readonly string _bucket; - - /// Wraps an S3 client the store then owns. - /// The client. Disposed with the store. - /// The bucket every blob is written into. - public S3BlobStore(IAmazonS3 client, string bucket) + /// + /// on any S3-compatible bucket: Backblaze B2 today, Tigris or AWS tomorrow. + /// + public sealed class S3BlobStore : IBlobStore, IDisposable { - ArgumentNullException.ThrowIfNull(client); - ArgumentException.ThrowIfNullOrWhiteSpace(bucket); + /// The most keys one DeleteObjects call accepts. + private const int DeleteBatchSize = 1000; - _client = client; - _bucket = bucket; - } - - /// - public async ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(write); - ArgumentNullException.ThrowIfNull(write.Content); + private readonly IAmazonS3 _client; - var key = KeyOf(write.OwnerId, write.Name); + private readonly string _bucket; - PutObjectRequest request = new() + /// Wraps an S3 client the store then owns. + /// The client. Disposed with the store. + /// The bucket every blob is written into. + public S3BlobStore(IAmazonS3 client, string bucket) { - BucketName = _bucket, - Key = key, - InputStream = write.Content, - ContentType = write.MediaType, - AutoCloseStream = false, - AutoResetStreamPosition = false, - }; + ArgumentNullException.ThrowIfNull(client); + ArgumentException.ThrowIfNullOrWhiteSpace(bucket); + + _client = client; + _bucket = bucket; + } - request.Headers.ContentLength = write.Length; + /// + public async ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(write); + ArgumentNullException.ThrowIfNull(write.Content); - await _client.PutObjectAsync(request, cancellationToken).ConfigureAwait(false); + string key = KeyOf(write.OwnerId, write.Name); - return new BlobRef(write.OwnerId, write.Name, write.MediaType, write.Length); - } + PutObjectRequest request = new() + { + BucketName = _bucket, + Key = key, + InputStream = write.Content, + ContentType = write.MediaType, + AutoCloseStream = false, + AutoResetStreamPosition = false, + }; - /// - public async ValueTask OpenReadAsync( - string ownerId, - string name, - CancellationToken cancellationToken = default) - { - var key = KeyOf(ownerId, name); + request.Headers.ContentLength = write.Length; - GetObjectResponse response; + _ = await _client.PutObjectAsync(request, cancellationToken).ConfigureAwait(false); - try - { - response = await _client.GetObjectAsync(_bucket, key, cancellationToken).ConfigureAwait(false); - } - catch (AmazonS3Exception e) when (e.StatusCode == HttpStatusCode.NotFound) - { - return null; + return new BlobRef(write.OwnerId, write.Name, write.MediaType, write.Length); } - return new BlobRead(response.Headers.ContentType, response.ContentLength, response.ResponseStream); - } + /// + public async ValueTask OpenReadAsync( + string ownerId, + string name, + CancellationToken cancellationToken = default) + { + string key = KeyOf(ownerId, name); - /// - public async ValueTask StatAsync( - string ownerId, - string name, - CancellationToken cancellationToken = default) - { - var key = KeyOf(ownerId, name); + GetObjectResponse response; - GetObjectMetadataResponse head; + try + { + response = await _client.GetObjectAsync(_bucket, key, cancellationToken).ConfigureAwait(false); + } + catch (AmazonS3Exception e) when (e.StatusCode == HttpStatusCode.NotFound) + { + return null; + } - try - { - head = await _client.GetObjectMetadataAsync(_bucket, key, cancellationToken).ConfigureAwait(false); - } - catch (AmazonS3Exception e) when (e.StatusCode == HttpStatusCode.NotFound) - { - return null; + return new BlobRead(response.Headers.ContentType, response.ContentLength, response.ResponseStream); } - return new BlobRef(ownerId, name, head.Headers.ContentType, head.ContentLength); - } + /// + public async ValueTask StatAsync( + string ownerId, + string name, + CancellationToken cancellationToken = default) + { + string key = KeyOf(ownerId, name); - /// - public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(blob); + GetObjectMetadataResponse head; - GetPreSignedUrlRequest request = new() - { - BucketName = _bucket, - Key = KeyOf(blob.OwnerId, blob.Name), - Verb = HttpVerb.GET, - Protocol = LinkProtocol(), - Expires = DateTime.UtcNow.Add(lifetime), - ResponseHeaderOverrides = + try + { + head = await _client.GetObjectMetadataAsync(_bucket, key, cancellationToken).ConfigureAwait(false); + } + catch (AmazonS3Exception e) when (e.StatusCode == HttpStatusCode.NotFound) { - ContentType = blob.MediaType, - ContentDisposition = BlobLink.DispositionOf(blob.MediaType, blob.Name), - }, - }; + return null; + } - return new(new Uri(_client.GetPreSignedURL(request))); - } + return new BlobRef(ownerId, name, head.Headers.ContentType, head.ContentLength); + } - /// - public async ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) - { - var prefix = OwnerPrefix(ownerId); + /// + public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(blob); - ListObjectsV2Request list = new() { BucketName = _bucket, Prefix = prefix }; + GetPreSignedUrlRequest request = new() + { + BucketName = _bucket, + Key = KeyOf(blob.OwnerId, blob.Name), + Verb = HttpVerb.GET, + Protocol = LinkProtocol(), + Expires = DateTime.UtcNow.Add(lifetime), + ResponseHeaderOverrides = + { + ContentType = blob.MediaType, + ContentDisposition = BlobLink.DispositionOf(blob.MediaType, blob.Name), + }, + }; - List batch = new(DeleteBatchSize); + return new(new Uri(_client.GetPreSignedURL(request))); + } - do + /// + public async ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) { - var page = await _client.ListObjectsV2Async(list, cancellationToken).ConfigureAwait(false); + string prefix = OwnerPrefix(ownerId); - foreach (var found in page.S3Objects ?? []) + ListObjectsV2Request list = new() { BucketName = _bucket, Prefix = prefix }; + + List batch = new(DeleteBatchSize); + + do { - batch.Add(new KeyVersion { Key = found.Key }); + ListObjectsV2Response page = await _client.ListObjectsV2Async(list, cancellationToken).ConfigureAwait(false); - if (batch.Count == DeleteBatchSize) + foreach (S3Object? found in page.S3Objects ?? []) { - await DeleteBatchAsync(batch, cancellationToken).ConfigureAwait(false); + batch.Add(new KeyVersion { Key = found.Key }); + + if (batch.Count == DeleteBatchSize) + { + await DeleteBatchAsync(batch, cancellationToken).ConfigureAwait(false); + } } + + list.ContinuationToken = page.NextContinuationToken; } + while (list.ContinuationToken is not null); - list.ContinuationToken = page.NextContinuationToken; + await DeleteBatchAsync(batch, cancellationToken).ConfigureAwait(false); } - while (list.ContinuationToken is not null); - await DeleteBatchAsync(batch, cancellationToken).ConfigureAwait(false); - } - - /// - public void Dispose() => _client.Dispose(); - - /// The endpoint's scheme, or https when the client was given a region and no URL. - private Protocol LinkProtocol() - => Uri.TryCreate(_client.Config.ServiceURL, UriKind.Absolute, out var endpoint) - && string.Equals(endpoint.Scheme, Uri.UriSchemeHttp, StringComparison.OrdinalIgnoreCase) - ? Protocol.HTTP - : Protocol.HTTPS; + /// + public void Dispose() + { + _client.Dispose(); + } - private async ValueTask DeleteBatchAsync(List batch, CancellationToken cancellationToken) - { - if (batch.Count == 0) + /// The endpoint's scheme, or https when the client was given a region and no URL. + private Protocol LinkProtocol() { - return; + return Uri.TryCreate(_client.Config.ServiceURL, UriKind.Absolute, out Uri? endpoint) + && string.Equals(endpoint.Scheme, Uri.UriSchemeHttp, StringComparison.OrdinalIgnoreCase) + ? Protocol.HTTP + : Protocol.HTTPS; } - DeleteObjectsRequest request = new() { BucketName = _bucket, Objects = [.. batch] }; + private async ValueTask DeleteBatchAsync(List batch, CancellationToken cancellationToken) + { + if (batch.Count == 0) + { + return; + } - await _client.DeleteObjectsAsync(request, cancellationToken).ConfigureAwait(false); + DeleteObjectsRequest request = new() { BucketName = _bucket, Objects = [.. batch] }; - batch.Clear(); - } + _ = await _client.DeleteObjectsAsync(request, cancellationToken).ConfigureAwait(false); - private static string KeyOf(string ownerId, string name) - { - if (!BlobName.IsSafe(name)) - { - throw new ArgumentException("A blob name must pass BlobName.IsSafe.", nameof(name)); + batch.Clear(); } - return OwnerPrefix(ownerId) + name; - } - - private static string OwnerPrefix(string ownerId) - { - ArgumentException.ThrowIfNullOrWhiteSpace(ownerId); - - if (ownerId.Contains('/', StringComparison.Ordinal)) + private static string KeyOf(string ownerId, string name) { - throw new ArgumentException("An owner id may not hold a slash.", nameof(ownerId)); + return !BlobName.IsSafe(name) + ? throw new ArgumentException("A blob name must pass BlobName.IsSafe.", nameof(name)) + : OwnerPrefix(ownerId) + name; } - return ownerId + "/"; + private static string OwnerPrefix(string ownerId) + { + ArgumentException.ThrowIfNullOrWhiteSpace(ownerId); + + return ownerId.Contains('/', StringComparison.Ordinal) + ? throw new ArgumentException("An owner id may not hold a slash.", nameof(ownerId)) + : ownerId + "/"; + } } } diff --git a/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStoreAdapter.cs b/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStoreAdapter.cs index 8ae554bf..a896a79b 100644 --- a/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStoreAdapter.cs +++ b/src/AgentCore.Infrastructure/Blobs/S3/S3BlobStoreAdapter.cs @@ -5,79 +5,82 @@ using Amazon.Runtime; using Amazon.S3; -namespace AgentCore.Infrastructure.Blobs.S3; - -/// -/// The s3 blob vendor behind . -/// -public sealed class S3BlobStoreAdapter : IBlobStoreAdapter +namespace AgentCore.Infrastructure.Blobs.S3 { - /// The one kind value this adapter serves. - public const string ProviderKind = "s3"; + /// + /// The s3 blob vendor behind . + /// + public sealed class S3BlobStoreAdapter : IBlobStoreAdapter + { + /// The one kind value this adapter serves. + public const string ProviderKind = "s3"; - /// The region signed when the document names none and the host does not say. - public const string DefaultRegion = "us-east-1"; + /// The region signed when the document names none and the host does not say. + public const string DefaultRegion = "us-east-1"; - /// - public string Kind => ProviderKind; + /// + public string Kind => ProviderKind; - /// - public async ValueTask OpenAsync( - BlobProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); - - if (entry.Endpoint is not { Length: > 0 } endpoint) + /// + public async ValueTask OpenAsync( + BlobProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) { - throw Fail("/providers/blobs/endpoint", "providers.blobs: { kind: s3 } names no endpoint. Write the service URL, such as https://s3.us-west-004.backblazeb2.com."); - } + ArgumentNullException.ThrowIfNull(entry); - if (entry.Bucket is not { Length: > 0 } bucket) - { - throw Fail("/providers/blobs/bucket", "providers.blobs: { kind: s3 } names no bucket. Write the bucket every blob is written into."); - } + if (entry.Endpoint is not { Length: > 0 } endpoint) + { + throw Fail("/providers/blobs/endpoint", "providers.blobs: { kind: s3 } names no endpoint. Write the service URL, such as https://s3.us-west-004.backblazeb2.com."); + } - const string because = "A sandbox file under providers.blobs is written to an S3 bucket."; + if (entry.Bucket is not { Length: > 0 } bucket) + { + throw Fail("/providers/blobs/bucket", "providers.blobs: { kind: s3 } names no bucket. Write the bucket every blob is written into."); + } - var keyId = await secrets.RequireAsync(KnownSecrets.S3AccessKeyId, because, cancellationToken).ConfigureAwait(false); - var secret = await secrets.RequireAsync(KnownSecrets.S3SecretAccessKey, because, cancellationToken).ConfigureAwait(false); + const string because = "A sandbox file under providers.blobs is written to an S3 bucket."; - AmazonS3Config config = new() - { - ServiceURL = endpoint, - AuthenticationRegion = entry.Region ?? RegionOf(endpoint), - ForcePathStyle = true, - RequestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED, - ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED, - }; + string keyId = await secrets.RequireAsync(KnownSecrets.S3AccessKeyId, because, cancellationToken).ConfigureAwait(false); + string secret = await secrets.RequireAsync(KnownSecrets.S3SecretAccessKey, because, cancellationToken).ConfigureAwait(false); - return new S3BlobStore(new AmazonS3Client(new BasicAWSCredentials(keyId, secret), config), bucket); - } + AmazonS3Config config = new() + { + ServiceURL = endpoint, + AuthenticationRegion = entry.Region ?? RegionOf(endpoint), + ForcePathStyle = true, + RequestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED, + ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED, + }; - /// Reads the region off a host shaped s3.{region}.{rest}, as B2's are. - /// The service URL. - /// The region label, or when the host is not shaped that way. - internal static string RegionOf(string endpoint) - { - if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var uri)) - { - return DefaultRegion; + return new S3BlobStore(new AmazonS3Client(new BasicAWSCredentials(keyId, secret), config), bucket); } - var labels = uri.Host.Split('.'); + /// Reads the region off a host shaped s3.{region}.{rest}, as B2's are. + /// The service URL. + /// The region label, or when the host is not shaped that way. + internal static string RegionOf(string endpoint) + { + if (!Uri.TryCreate(endpoint, UriKind.Absolute, out Uri? uri)) + { + return DefaultRegion; + } - return labels.Length >= 3 && labels[0].Equals("s3", StringComparison.OrdinalIgnoreCase) - ? labels[1] - : DefaultRegion; - } + string[] labels = uri.Host.Split('.'); - private static ConfigurationLoadException Fail(string pointer, string message) - => new(new ConfigurationError + return labels.Length >= 3 && labels[0].Equals("s3", StringComparison.OrdinalIgnoreCase) + ? labels[1] + : DefaultRegion; + } + + private static ConfigurationLoadException Fail(string pointer, string message) { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.ReferenceResolution, - }); + return new(new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.ReferenceResolution, + }); + } + } } diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationRows.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationRows.cs index 45559047..a110fd3a 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationRows.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationRows.cs @@ -5,62 +5,76 @@ using Npgsql; using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationStoreSql; -namespace AgentCore.Infrastructure.Conversation.Postgres; - -/// How a Postgres row becomes a or , and back. -internal static class PostgresConversationRows +namespace AgentCore.Infrastructure.Conversation.Postgres { - /// - /// One conversation's row from , whose ninth column is the state a - /// resume reads back and whose tenth is its ordinal counter. - /// - internal static ConversationRecord Read(NpgsqlDataReader reader) => - ReadListing(reader) with - { - State = reader.IsDBNull(8) ? null : ReadState(reader.GetString(8)), - NextOrdinal = reader.GetInt32(9), - }; - - /// Reads one conversation's resume blob, or nothing when the blob cannot be read. - /// The JSON in conversation.state. - /// The state, or when it did not parse into one. - internal static ConversationSessionState? ReadState(string blob) + /// How a Postgres row becomes a or , and back. + internal static class PostgresConversationRows { - try + /// + /// One conversation's row from , whose ninth column is the state a + /// resume reads back and whose tenth is its ordinal counter. + /// + internal static ConversationRecord Read(NpgsqlDataReader reader) { - return JsonSerializer.Deserialize(blob, ConversationStateJson.Options); + return ReadListing(reader) with + { + State = reader.IsDBNull(8) ? null : ReadState(reader.GetString(8)), + NextOrdinal = reader.GetInt32(9), + }; } - catch (JsonException) + + /// Reads one conversation's resume blob, or nothing when the blob cannot be read. + /// The JSON in conversation.state. + /// The state, or when it did not parse into one. + internal static ConversationSessionState? ReadState(string blob) { - return null; + try + { + return JsonSerializer.Deserialize(blob, ConversationStateJson.Options); + } + catch (JsonException) + { + return null; + } } - } - /// - /// One conversation's row from , which projects - /// alone. It has no ninth or tenth column to read, so - /// and are left at their - /// defaults — and 0 — rather than paying for what a listing never shows. - /// - internal static ConversationRecord ReadListing(NpgsqlDataReader reader) => - new( - reader.GetString(0), - reader.IsDBNull(1) ? null : reader.GetString(1), - ToStatus(reader.GetString(2)), - reader.IsDBNull(3) ? null : reader.GetString(3), - reader.IsDBNull(4) ? null : JsonDocument.Parse(reader.GetString(4)).RootElement.Clone(), - reader.GetFieldValue(5), - reader.IsDBNull(7) ? null : reader.GetFieldValue(7)); + /// + /// One conversation's row from , which projects + /// alone. It has no ninth or tenth column to read, so + /// and are left at their + /// defaults — and 0 — rather than paying for what a listing never shows. + /// + internal static ConversationRecord ReadListing(NpgsqlDataReader reader) + { + return new( + reader.GetString(0), + reader.IsDBNull(1) ? null : reader.GetString(1), + ToStatus(reader.GetString(2)), + reader.IsDBNull(3) ? null : reader.GetString(3), + reader.IsDBNull(4) ? null : JsonDocument.Parse(reader.GetString(4)).RootElement.Clone(), + reader.GetFieldValue(5), + reader.IsDBNull(7) ? null : reader.GetFieldValue(7)); + } - internal static string ToText(ConversationStatus status) => status == ConversationStatus.Archived ? Archived : Regular; + internal static string ToText(ConversationStatus status) + { + return status == ConversationStatus.Archived ? Archived : Regular; + } - internal static ConversationStatus ToStatus(string text) => - text == Archived ? ConversationStatus.Archived : ConversationStatus.Regular; + internal static ConversationStatus ToStatus(string text) + { + return text == Archived ? ConversationStatus.Archived : ConversationStatus.Regular; + } - internal static string Serialise(ChatMessage message) - => JsonSerializer.Serialize(message, TranscriptJson.Options); + internal static string Serialise(ChatMessage message) + { + return JsonSerializer.Serialize(message, TranscriptJson.Options); + } - internal static ChatMessage Deserialise(string content) - => JsonSerializer.Deserialize(content, TranscriptJson.Options) - ?? throw new InvalidOperationException("A conversation_message row holds JSON null in content."); + internal static ChatMessage Deserialise(string content) + { + return JsonSerializer.Deserialize(content, TranscriptJson.Options) + ?? throw new InvalidOperationException("A conversation_message row holds JSON null in content."); + } + } } diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs index 420e9d27..a225a2ae 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStore.cs @@ -8,327 +8,344 @@ using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationRows; using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationStoreSql; -namespace AgentCore.Infrastructure.Conversation.Postgres; - -/// The store, in PostgreSQL: a conversation, who may see it, and its words. -internal sealed class PostgresConversationStore : IConversationStore, IAsyncDisposable +namespace AgentCore.Infrastructure.Conversation.Postgres { - private readonly NpgsqlDataSource _dataSource; - - private readonly PostgresConversationWords _words; - - /// Creates the store over a data source it then owns. - /// The pool every statement runs on. Disposing the store disposes it. - /// The data source is . - public PostgresConversationStore(NpgsqlDataSource dataSource) + /// The store, in PostgreSQL: a conversation, who may see it, and its words. + internal sealed class PostgresConversationStore : IConversationStore, IAsyncDisposable { - ArgumentNullException.ThrowIfNull(dataSource); - _dataSource = dataSource; - _words = new PostgresConversationWords(dataSource); - } + private readonly NpgsqlDataSource _dataSource; - /// - public async ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + private readonly PostgresConversationWords _words; - await using (var command = _dataSource.CreateCommand(CreateSql)) + /// Creates the store over a data source it then owns. + /// The pool every statement runs on. Disposing the store disposes it. + /// The data source is . + public PostgresConversationStore(NpgsqlDataSource dataSource) { - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + ArgumentNullException.ThrowIfNull(dataSource); + _dataSource = dataSource; + _words = new PostgresConversationWords(dataSource); } - return await GetAsync(conversationId, cancellationToken).ConfigureAwait(false) - ?? throw new InvalidOperationException($"Store 0 lost conversation '{conversationId}' between its write and its read."); - } + /// + public async ValueTask CreateAsync(string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - /// - public async ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + await using (NpgsqlCommand command = _dataSource.CreateCommand(CreateSql)) + { + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - await using var command = _dataSource.CreateCommand(GetSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + return await GetAsync(conversationId, cancellationToken).ConfigureAwait(false) + ?? throw new InvalidOperationException($"Store 0 lost conversation '{conversationId}' between its write and its read."); + } - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - return await reader.ReadAsync(cancellationToken).ConfigureAwait(false) ? Read(reader) : null; - } + /// + public async ValueTask GetAsync(string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - /// - public ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(title); + await using NpgsqlCommand command = _dataSource.CreateCommand(GetSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - return AmendAsync(RenameSql, conversationId, new NpgsqlParameter { Value = title }, cancellationToken); - } + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + return await reader.ReadAsync(cancellationToken).ConfigureAwait(false) ? Read(reader) : null; + } - /// - public ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + public ValueTask RenameAsync(string conversationId, string title, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(title); - return AmendAsync(StatusSql, conversationId, new NpgsqlParameter { Value = ToText(status) }, cancellationToken); - } + return AmendAsync(RenameSql, conversationId, new NpgsqlParameter { Value = title }, cancellationToken); + } - /// - public ValueTask SetCustomAsync( - string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + public ValueTask SetStatusAsync(string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - NpgsqlParameter parameter = new() + return AmendAsync(StatusSql, conversationId, new NpgsqlParameter { Value = ToText(status) }, cancellationToken); + } + + /// + public ValueTask SetCustomAsync( + string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) { - NpgsqlDbType = NpgsqlDbType.Jsonb, - Value = custom is { } element ? element.GetRawText() : DBNull.Value, - }; + ArgumentNullException.ThrowIfNull(conversationId); - return AmendAsync(CustomSql, conversationId, parameter, cancellationToken); - } + NpgsqlParameter parameter = new() + { + NpgsqlDbType = NpgsqlDbType.Jsonb, + Value = custom is { } element ? element.GetRawText() : DBNull.Value, + }; - /// - public ValueTask SetExternalIdAsync( - string conversationId, string? externalId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + return AmendAsync(CustomSql, conversationId, parameter, cancellationToken); + } - NpgsqlParameter parameter = new() + /// + public ValueTask SetExternalIdAsync( + string conversationId, string? externalId, CancellationToken cancellationToken = default) { - NpgsqlDbType = NpgsqlDbType.Text, - Value = externalId is null ? DBNull.Value : externalId, - }; + ArgumentNullException.ThrowIfNull(conversationId); - return AmendAsync(ExternalIdSql, conversationId, parameter, cancellationToken); - } - - /// - public async ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + NpgsqlParameter parameter = new() + { + NpgsqlDbType = NpgsqlDbType.Text, + Value = externalId is null ? DBNull.Value : externalId, + }; - await using var command = _dataSource.CreateCommand(DeleteSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + return AmendAsync(ExternalIdSql, conversationId, parameter, cancellationToken); + } - await using var continuation = _dataSource.CreateCommand(DeleteContinuationSql); - continuation.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - await continuation.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + /// + public async ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - /// - public async ValueTask ListAsync( - string principalKey, - string? after, - int limit, - ConversationStatus? status = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(principalKey); - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(limit); + await using NpgsqlCommand command = _dataSource.CreateCommand(DeleteSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - var hasCursor = ConversationCursor.TryDecode(after, out var sortAt, out var cursorId); + await using NpgsqlCommand continuation = _dataSource.CreateCommand(DeleteContinuationSql); + _ = continuation.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = await continuation.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - await using var command = _dataSource.CreateCommand(ListSql); - command.Parameters.Add(new NpgsqlParameter { Value = principalKey }); - command.Parameters.Add(new NpgsqlParameter - { - NpgsqlDbType = NpgsqlDbType.Text, - Value = status is { } narrowed ? ToText(narrowed) : DBNull.Value, - }); - command.Parameters.Add(new NpgsqlParameter + /// + public async ValueTask ListAsync( + string principalKey, + string? after, + int limit, + ConversationStatus? status = null, + CancellationToken cancellationToken = default) { - NpgsqlDbType = NpgsqlDbType.TimestampTz, - Value = hasCursor ? sortAt : DBNull.Value, - }); - command.Parameters.Add(new NpgsqlParameter - { - NpgsqlDbType = NpgsqlDbType.Text, - Value = hasCursor ? cursorId : DBNull.Value, - }); - command.Parameters.Add(new NpgsqlParameter { Value = limit }); + ArgumentNullException.ThrowIfNull(principalKey); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(limit); - List rows = []; - DateTimeOffset lastSortAt = default; + bool hasCursor = ConversationCursor.TryDecode(after, out DateTimeOffset sortAt, out string? cursorId); - await using (var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false)) - { - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + await using NpgsqlCommand command = _dataSource.CreateCommand(ListSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = principalKey }); + _ = command.Parameters.Add(new NpgsqlParameter + { + NpgsqlDbType = NpgsqlDbType.Text, + Value = status is { } narrowed ? ToText(narrowed) : DBNull.Value, + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + NpgsqlDbType = NpgsqlDbType.TimestampTz, + Value = hasCursor ? sortAt : DBNull.Value, + }); + _ = command.Parameters.Add(new NpgsqlParameter + { + NpgsqlDbType = NpgsqlDbType.Text, + Value = hasCursor ? cursorId : DBNull.Value, + }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = limit }); + + List rows = []; + DateTimeOffset lastSortAt = default; + + await using (NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false)) { - rows.Add(ReadListing(reader)); - lastSortAt = reader.GetFieldValue(6); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + { + rows.Add(ReadListing(reader)); + lastSortAt = reader.GetFieldValue(6); + } } + + string? next = rows.Count == limit + ? ConversationCursor.Encode(lastSortAt, rows[^1].ConversationId) + : null; + + return new ConversationPage(rows, next); } - var next = rows.Count == limit - ? ConversationCursor.Encode(lastSortAt, rows[^1].ConversationId) - : null; + /// + public async ValueTask SweepAsync( + TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) + { + ArgumentOutOfRangeException.ThrowIfLessThan(retention, TimeSpan.Zero); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(batchSize); - return new ConversationPage(rows, next); - } + int swept = 0; - /// - public async ValueTask SweepAsync( - TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) - { - ArgumentOutOfRangeException.ThrowIfLessThan(retention, TimeSpan.Zero); - ArgumentOutOfRangeException.ThrowIfNegativeOrZero(batchSize); + while (true) + { + await using NpgsqlCommand continuations = _dataSource.CreateCommand(SweepContinuationsSql); - var swept = 0; + _ = continuations.Parameters.Add( + new NpgsqlParameter { Value = retention, NpgsqlDbType = NpgsqlDbType.Interval }); - while (true) - { - await using var continuations = _dataSource.CreateCommand(SweepContinuationsSql); + _ = continuations.Parameters.Add(new NpgsqlParameter { Value = batchSize }); + _ = await continuations.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - continuations.Parameters.Add( - new NpgsqlParameter { Value = retention, NpgsqlDbType = NpgsqlDbType.Interval }); + await using NpgsqlCommand command = _dataSource.CreateCommand(SweepSql); - continuations.Parameters.Add(new NpgsqlParameter { Value = batchSize }); - await continuations.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + _ = command.Parameters.Add( + new NpgsqlParameter { Value = retention, NpgsqlDbType = NpgsqlDbType.Interval }); - await using var command = _dataSource.CreateCommand(SweepSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = batchSize }); - command.Parameters.Add( - new NpgsqlParameter { Value = retention, NpgsqlDbType = NpgsqlDbType.Interval }); - - command.Parameters.Add(new NpgsqlParameter { Value = batchSize }); + int deleted = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + if (deleted == 0) + { + return swept; + } - var deleted = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - if (deleted == 0) - { - return swept; + swept += deleted; } + } - swept += deleted; + /// + public async ValueTask AttachPrincipalAsync( + string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(principalKey); + ArgumentNullException.ThrowIfNull(role); + + await using NpgsqlCommand command = _dataSource.CreateCommand(AttachSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = principalKey }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = role }); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); } - } - /// - public async ValueTask AttachPrincipalAsync( - string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(principalKey); - ArgumentNullException.ThrowIfNull(role); - - await using var command = _dataSource.CreateCommand(AttachSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = principalKey }); - command.Parameters.Add(new NpgsqlParameter { Value = role }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + /// + public async ValueTask DetachPrincipalAsync( + string conversationId, string principalKey, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(principalKey); - /// - public async ValueTask DetachPrincipalAsync( - string conversationId, string principalKey, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(principalKey); + await using NpgsqlCommand command = _dataSource.CreateCommand(DetachSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = principalKey }); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - await using var command = _dataSource.CreateCommand(DetachSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = principalKey }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + /// Disposes the pool this store was given. + /// A task that completes when the pool is closed. + public ValueTask DisposeAsync() + { + return _dataSource.DisposeAsync(); + } - /// Disposes the pool this store was given. - /// A task that completes when the pool is closed. - public ValueTask DisposeAsync() => _dataSource.DisposeAsync(); + private async ValueTask AmendAsync( + string sql, string conversationId, NpgsqlParameter value, CancellationToken cancellationToken) + { + await using NpgsqlCommand command = _dataSource.CreateCommand(sql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(value); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - private async ValueTask AmendAsync( - string sql, string conversationId, NpgsqlParameter value, CancellationToken cancellationToken) - { - await using var command = _dataSource.CreateCommand(sql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(value); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + /// + public ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + return _words.AppendAsync(conversationId, messages, state, cancellationToken); + } - /// - public ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - => _words.AppendAsync(conversationId, messages, state, cancellationToken); - - /// - public ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - => _words.RewriteAsync(conversationId, messageId, content, cancellationToken); - - /// - public ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - => _words.ReadForSessionAsync(conversationId, cancellationToken); - - /// - public ValueTask> ReadWindowAsync( - string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) - => _words.ReadWindowAsync(conversationId, window, cancellationToken); - - /// - public ValueTask OrdinalOfAsync( - string conversationId, string messageId, CancellationToken cancellationToken = default) - => _words.OrdinalOfAsync(conversationId, messageId, cancellationToken); - - /// - public ValueTask TruncateAsync( - string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) - => _words.TruncateAsync(conversationId, fromOrdinal, cancellationToken); - - /// - public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - => _words.EraseAsync(conversationId, cancellationToken); - - /// - public async ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(continuationId); + /// + public ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + return _words.RewriteAsync(conversationId, messageId, content, cancellationToken); + } - await using var command = _dataSource.CreateCommand(SaveContinuationSql); - command.Parameters.Add(new NpgsqlParameter { Value = continuationId }); - command.Parameters.Add(new NpgsqlParameter + /// + public ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) { - NpgsqlDbType = NpgsqlDbType.Jsonb, - Value = envelope.GetRawText(), - }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + return _words.ReadForSessionAsync(conversationId, cancellationToken); + } - /// - public async ValueTask GetContinuationAsync(string continuationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(continuationId); + /// + public ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + return _words.ReadWindowAsync(conversationId, window, cancellationToken); + } - await using var command = _dataSource.CreateCommand(GetContinuationSql); - command.Parameters.Add(new NpgsqlParameter { Value = continuationId }); + /// + public ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) + { + return _words.OrdinalOfAsync(conversationId, messageId, cancellationToken); + } - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - if (!await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + /// + public ValueTask TruncateAsync( + string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) { - return null; + return _words.TruncateAsync(conversationId, fromOrdinal, cancellationToken); } - return JsonDocument.Parse(reader.GetString(0)).RootElement.Clone(); - } + /// + public ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + return _words.EraseAsync(conversationId, cancellationToken); + } - /// - public async ValueTask DeleteContinuationAsync(string continuationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(continuationId); + /// + public async ValueTask SaveContinuationAsync(string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(continuationId); - await using var command = _dataSource.CreateCommand(DeleteContinuationSql); - command.Parameters.Add(new NpgsqlParameter { Value = continuationId }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + await using NpgsqlCommand command = _dataSource.CreateCommand(SaveContinuationSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = continuationId }); + _ = command.Parameters.Add(new NpgsqlParameter + { + NpgsqlDbType = NpgsqlDbType.Jsonb, + Value = envelope.GetRawText(), + }); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } + /// + public async ValueTask GetContinuationAsync(string continuationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(continuationId); + + await using NpgsqlCommand command = _dataSource.CreateCommand(GetContinuationSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = continuationId }); + + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + return !await reader.ReadAsync(cancellationToken).ConfigureAwait(false) + ? null + : JsonDocument.Parse(reader.GetString(0)).RootElement.Clone(); + } + + /// + public async ValueTask DeleteContinuationAsync(string continuationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(continuationId); - /// Reads one conversation's spoken turns beside the hashes the audit chain holds for them. - /// The conversation to check. - /// Cancels the read. - /// One row for each spoken turn, oldest turn first. - /// The conversation id is . - public Task> ReadSpokenTurnsAsync( - string conversationId, CancellationToken cancellationToken = default) - => PostgresConversationVerification.ReadSpokenTurnsAsync(_dataSource, conversationId, cancellationToken); + await using NpgsqlCommand command = _dataSource.CreateCommand(DeleteContinuationSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = continuationId }); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } + + + /// Reads one conversation's spoken turns beside the hashes the audit chain holds for them. + /// The conversation to check. + /// Cancels the read. + /// One row for each spoken turn, oldest turn first. + /// The conversation id is . + public Task> ReadSpokenTurnsAsync( + string conversationId, CancellationToken cancellationToken = default) + { + return PostgresConversationVerification.ReadSpokenTurnsAsync(_dataSource, conversationId, cancellationToken); + } + } } diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreAdapter.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreAdapter.cs index be25fd5f..51baaf93 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreAdapter.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreAdapter.cs @@ -3,36 +3,37 @@ using AgentCore.Infrastructure.Database.Postgres; using Npgsql; -namespace AgentCore.Infrastructure.Conversation.Postgres; - -/// -/// The postgres conversation vendor behind . -/// -public sealed class PostgresConversationStoreAdapter : IConversationStoreAdapter +namespace AgentCore.Infrastructure.Conversation.Postgres { /// - /// The one kind value this adapter serves. + /// The postgres conversation vendor behind . /// - public const string ProviderKind = "postgres"; + public sealed class PostgresConversationStoreAdapter : IConversationStoreAdapter + { + /// + /// The one kind value this adapter serves. + /// + public const string ProviderKind = "postgres"; - /// - /// Gets the one kind value this adapter serves. - /// - public string Kind => ProviderKind; + /// + /// Gets the one kind value this adapter serves. + /// + public string Kind => ProviderKind; - /// - public async ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - NpgsqlDataSource dataSource = await PostgresDataSourceFactory - .OpenMigratedAsync( - secrets, - "A conversation's row in providers.conversations is written to PostgreSQL.", - cancellationToken) - .ConfigureAwait(false); + /// + public async ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + NpgsqlDataSource dataSource = await PostgresDataSourceFactory + .OpenMigratedAsync( + secrets, + "A conversation's row in providers.conversations is written to PostgreSQL.", + cancellationToken) + .ConfigureAwait(false); - return new PostgresConversationStore(dataSource); + return new PostgresConversationStore(dataSource); + } } } diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs index 5c726881..157d815b 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationStoreSql.cs @@ -1,72 +1,72 @@ using AgentCore.Infrastructure.Database.Postgres; -namespace AgentCore.Infrastructure.Conversation.Postgres; - -/// Every statement runs. -internal static class PostgresConversationStoreSql +namespace AgentCore.Infrastructure.Conversation.Postgres { - private const string Schema = PostgresSchema.SchemaName; + /// Every statement runs. + internal static class PostgresConversationStoreSql + { + private const string Schema = PostgresSchema.SchemaName; - internal const string Regular = "regular"; + internal const string Regular = "regular"; - internal const string Archived = "archived"; + internal const string Archived = "archived"; - /// The value a listing sorts and pages by. - internal const string SortAt = "COALESCE(m.last_message_at, c.created_at)"; + /// The value a listing sorts and pages by. + internal const string SortAt = "COALESCE(m.last_message_at, c.created_at)"; - /// - /// The columns a row is read through, and the derived activity time beside them. - /// - internal const string Projection = - $""" + /// + /// The columns a row is read through, and the derived activity time beside them. + /// + internal const string Projection = + $""" c.conversation_id, c.title, c.status, c.external_id, c.custom, c.created_at, {SortAt} AS sort_at, m.last_message_at """; - internal const string ActivityJoin = - $""" + internal const string ActivityJoin = + $""" LEFT JOIN LATERAL ( SELECT max(updated_at) AS last_message_at FROM {Schema}.conversation_message x WHERE x.conversation_id = c.conversation_id ) m ON true """; - internal const string CreateSql = - $"INSERT INTO {Schema}.conversation (conversation_id) VALUES ($1) ON CONFLICT (conversation_id) DO NOTHING"; + internal const string CreateSql = + $"INSERT INTO {Schema}.conversation (conversation_id) VALUES ($1) ON CONFLICT (conversation_id) DO NOTHING"; - /// One conversation's row, with the session state a resume reads back and its ordinal counter. - internal static readonly string GetSql = - $"SELECT {Projection}, c.state, c.next_ordinal FROM {Schema}.conversation c {ActivityJoin} WHERE c.conversation_id = $1"; + /// One conversation's row, with the session state a resume reads back and its ordinal counter. + internal static readonly string GetSql = + $"SELECT {Projection}, c.state, c.next_ordinal FROM {Schema}.conversation c {ActivityJoin} WHERE c.conversation_id = $1"; - internal const string StateSql = - $"UPDATE {Schema}.conversation SET state = $2, updated_at = now() WHERE conversation_id = $1"; + internal const string StateSql = + $"UPDATE {Schema}.conversation SET state = $2, updated_at = now() WHERE conversation_id = $1"; - internal const string RenameSql = - $"UPDATE {Schema}.conversation SET title = $2, updated_at = now() WHERE conversation_id = $1"; + internal const string RenameSql = + $"UPDATE {Schema}.conversation SET title = $2, updated_at = now() WHERE conversation_id = $1"; - internal const string StatusSql = - $"UPDATE {Schema}.conversation SET status = $2, updated_at = now() WHERE conversation_id = $1"; + internal const string StatusSql = + $"UPDATE {Schema}.conversation SET status = $2, updated_at = now() WHERE conversation_id = $1"; - internal const string CustomSql = - $"UPDATE {Schema}.conversation SET custom = $2, updated_at = now() WHERE conversation_id = $1"; + internal const string CustomSql = + $"UPDATE {Schema}.conversation SET custom = $2, updated_at = now() WHERE conversation_id = $1"; - internal const string ExternalIdSql = - $"UPDATE {Schema}.conversation SET external_id = $2, updated_at = now() WHERE conversation_id = $1"; + internal const string ExternalIdSql = + $"UPDATE {Schema}.conversation SET external_id = $2, updated_at = now() WHERE conversation_id = $1"; - internal const string DeleteSql = $"DELETE FROM {Schema}.conversation WHERE conversation_id = $1"; + internal const string DeleteSql = $"DELETE FROM {Schema}.conversation WHERE conversation_id = $1"; - internal const string AttachSql = - $""" + internal const string AttachSql = + $""" INSERT INTO {Schema}.conversation_principal (conversation_id, principal_key, role) VALUES ($1, $2, $3) ON CONFLICT (principal_key, conversation_id) DO NOTHING """; - internal const string DetachSql = - $"DELETE FROM {Schema}.conversation_principal WHERE conversation_id = $1 AND principal_key = $2"; + internal const string DetachSql = + $"DELETE FROM {Schema}.conversation_principal WHERE conversation_id = $1 AND principal_key = $2"; - /// One page of one principal's conversations. - internal static readonly string ListSql = - $""" + /// One page of one principal's conversations. + internal static readonly string ListSql = + $""" SELECT {Projection} FROM {Schema}.conversation_principal p JOIN {Schema}.conversation c USING (conversation_id) @@ -79,16 +79,16 @@ ON CONFLICT (principal_key, conversation_id) DO NOTHING LIMIT $5 """; - /// - /// Numbers and inserts every row of one append in a single statement. $5 (the message ids) - /// doubles as the count the whole batch numbers from: cardinality($5::text[]) is how many - /// ordinals mark reserves, and RETURNING on the UPDATE sees the bumped - /// next_ordinal, so subtracting that same count back off it gives the first one this batch - /// may use. A null element of $2 (turn_index) takes the conversation's own next turn index instead - /// of naming one, which is what an append from outside any turn asks for. $6 is the - /// covers_up_to of each row: null for every row somebody said. - /// - internal const string AppendSql = $""" + /// + /// Numbers and inserts every row of one append in a single statement. $5 (the message ids) + /// doubles as the count the whole batch numbers from: cardinality($5::text[]) is how many + /// ordinals mark reserves, and RETURNING on the UPDATE sees the bumped + /// next_ordinal, so subtracting that same count back off it gives the first one this batch + /// may use. A null element of $2 (turn_index) takes the conversation's own next turn index instead + /// of naming one, which is what an append from outside any turn asks for. $6 is the + /// covers_up_to of each row: null for every row somebody said. + /// + internal const string AppendSql = $""" WITH mark AS ( UPDATE {Schema}.conversation SET next_ordinal = next_ordinal + cardinality($5::text[]), updated_at = now() @@ -103,15 +103,15 @@ AS d(turn_index, role, content, message_id, covers_up_to, position) RETURNING ordinal, turn_index, message_id """; - /// The columns every row read returns, in the order PostgresConversationWords.ReadRowsAsync reads them. - private const string RowColumns = "ordinal, turn_index, content, message_id, covers_up_to"; + /// The columns every row read returns, in the order PostgresConversationWords.ReadRowsAsync reads them. + private const string RowColumns = "ordinal, turn_index, content, message_id, covers_up_to"; - /// - /// Reads a conversation as its session opens it: the newest summary row, and every row somebody - /// said above what it covers. With no summary, every row. - /// - internal const string ReadForSessionSql = - $""" + /// + /// Reads a conversation as its session opens it: the newest summary row, and every row somebody + /// said above what it covers. With no summary, every row. + /// + internal const string ReadForSessionSql = + $""" WITH summary AS ( SELECT ordinal, covers_up_to FROM {Schema}.conversation_message WHERE conversation_id = $1 AND covers_up_to IS NOT NULL @@ -125,12 +125,12 @@ ORDER BY ordinal DESC LIMIT 1 ORDER BY m.ordinal """; - /// - /// Reads the newest turns of a conversation before a given one, whole. $2 is the turn to - /// read before, or null for the newest; $3 is how many turns at most. - /// - internal const string ReadWindowSql = - $""" + /// + /// Reads the newest turns of a conversation before a given one, whole. $2 is the turn to + /// read before, or null for the newest; $3 is how many turns at most. + /// + internal const string ReadWindowSql = + $""" SELECT {RowColumns} FROM {Schema}.conversation_message WHERE conversation_id = $1 @@ -142,12 +142,12 @@ SELECT DISTINCT turn_index FROM {Schema}.conversation_message ORDER BY ordinal """; - /// - /// Withdraws the tail of a conversation, from one ordinal onward. A summary row goes only when - /// the cut reaches a row it covers. - /// - internal const string TruncateSql = - $""" + /// + /// Withdraws the tail of a conversation, from one ordinal onward. A summary row goes only when + /// the cut reaches a row it covers. + /// + internal const string TruncateSql = + $""" WITH gone AS ( DELETE FROM {Schema}.conversation_message WHERE conversation_id = $1 AND ordinal >= $2 AND (covers_up_to IS NULL OR covers_up_to >= $2) @@ -158,39 +158,39 @@ SELECT count(*)::int, FROM gone """; - /// Finds the ordinal of one spoken row by its message id. Summary rows are not found. - internal const string OrdinalOfSql = - $""" + /// Finds the ordinal of one spoken row by its message id. Summary rows are not found. + internal const string OrdinalOfSql = + $""" SELECT ordinal FROM {Schema}.conversation_message WHERE conversation_id = $1 AND message_id = $2 AND covers_up_to IS NULL """; - internal const string RewriteSql = $""" + internal const string RewriteSql = $""" UPDATE {Schema}.conversation_message SET content = $3, updated_at = now() WHERE conversation_id = $1 AND message_id = $2 """; - internal const string EraseSql = $"DELETE FROM {Schema}.conversation_message WHERE conversation_id = $1"; + internal const string EraseSql = $"DELETE FROM {Schema}.conversation_message WHERE conversation_id = $1"; - /// Files one session envelope under one continuation id, replacing any envelope already there. - internal const string SaveContinuationSql = - $""" + /// Files one session envelope under one continuation id, replacing any envelope already there. + internal const string SaveContinuationSql = + $""" INSERT INTO {Schema}.response_continuation (store_id, envelope) VALUES ($1, $2) ON CONFLICT (store_id) DO UPDATE SET envelope = EXCLUDED.envelope """; - /// Reads the envelope one continuation id names. - internal const string GetContinuationSql = - $"SELECT envelope FROM {Schema}.response_continuation WHERE store_id = $1"; + /// Reads the envelope one continuation id names. + internal const string GetContinuationSql = + $"SELECT envelope FROM {Schema}.response_continuation WHERE store_id = $1"; - /// Withdraws whatever one continuation id names, if anything. - internal const string DeleteContinuationSql = - $"DELETE FROM {Schema}.response_continuation WHERE store_id = $1"; + /// Withdraws whatever one continuation id names, if anything. + internal const string DeleteContinuationSql = + $"DELETE FROM {Schema}.response_continuation WHERE store_id = $1"; - /// - /// Reads what store 1 holds for each spoken turn of one conversation, beside what store 3 proves. - /// - internal const string VerifySql = $$""" + /// + /// Reads what store 1 holds for each spoken turn of one conversation, beside what store 3 proves. + /// + internal const string VerifySql = $$""" WITH spoken AS ( SELECT DISTINCT ON (conversation_id, turn_index) conversation_id, turn_index, @@ -216,9 +216,9 @@ FROM spoken m JOIN completed a USING (conversation_id, turn_index) ORDER BY m.turn_index """; - /// Deletes one batch of conversations that have aged out whole. - internal static readonly string SweepContinuationsSql = - $""" + /// Deletes one batch of conversations that have aged out whole. + internal static readonly string SweepContinuationsSql = + $""" DELETE FROM {Schema}.response_continuation WHERE store_id IN ( SELECT conversation_id FROM ( @@ -230,9 +230,9 @@ SELECT c.conversation_id ) q) """; - /// Deletes one batch of conversations that have aged out whole. - internal static readonly string SweepSql = - $""" + /// Deletes one batch of conversations that have aged out whole. + internal static readonly string SweepSql = + $""" DELETE FROM {Schema}.conversation WHERE conversation_id IN ( SELECT conversation_id FROM ( @@ -243,4 +243,5 @@ SELECT c.conversation_id LIMIT $2 ) q) """; + } } diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationVerification.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationVerification.cs index a6806d0c..698633e9 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationVerification.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationVerification.cs @@ -1,44 +1,45 @@ using Npgsql; using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationStoreSql; -namespace AgentCore.Infrastructure.Conversation.Postgres; - -/// Reads store 1's words beside the hashes store 3 holds for them, for a retroactive check. -internal static class PostgresConversationVerification +namespace AgentCore.Infrastructure.Conversation.Postgres { - /// Reads one conversation's spoken turns beside the hashes the audit chain holds for them. - /// The pool the read runs on. - /// The conversation to check. - /// Cancels the read. - /// One row for each spoken turn, oldest turn first. - /// The conversation id is . - public static async Task> ReadSpokenTurnsAsync( - NpgsqlDataSource dataSource, string conversationId, CancellationToken cancellationToken = default) + /// Reads store 1's words beside the hashes store 3 holds for them, for a retroactive check. + internal static class PostgresConversationVerification { - ArgumentNullException.ThrowIfNull(conversationId); + /// Reads one conversation's spoken turns beside the hashes the audit chain holds for them. + /// The pool the read runs on. + /// The conversation to check. + /// Cancels the read. + /// One row for each spoken turn, oldest turn first. + /// The conversation id is . + public static async Task> ReadSpokenTurnsAsync( + NpgsqlDataSource dataSource, string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - await using var command = dataSource.CreateCommand(VerifySql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + await using NpgsqlCommand command = dataSource.CreateCommand(VerifySql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - List turns = []; + List turns = []; - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) - { - turns.Add(new TranscriptTurnDigest( - reader.GetInt32(0), - reader.GetString(1), - reader.IsDBNull(2) ? null : reader.GetString(2))); - } + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + { + turns.Add(new TranscriptTurnDigest( + reader.GetInt32(0), + reader.GetString(1), + reader.IsDBNull(2) ? null : reader.GetString(2))); + } - return turns; + return turns; + } } -} -/// One spoken turn, as store 1 holds it and as store 3 proves it. -/// The turn, which is the join between the two stores. -/// The words store 1 holds. A barge-in cut them down to what the caller heard. -/// -/// The digest the chain holds for the turn, or when its event carried none. -/// -internal sealed record TranscriptTurnDigest(int TurnIndex, string Spoken, string? ReplyTextSha256); + /// One spoken turn, as store 1 holds it and as store 3 proves it. + /// The turn, which is the join between the two stores. + /// The words store 1 holds. A barge-in cut them down to what the caller heard. + /// + /// The digest the chain holds for the turn, or when its event carried none. + /// + internal sealed record TranscriptTurnDigest(int TurnIndex, string Spoken, string? ReplyTextSha256); +} diff --git a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs index 3ca4deed..5919aa64 100644 --- a/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs +++ b/src/AgentCore.Infrastructure/Conversation/Postgres/PostgresConversationWords.cs @@ -9,211 +9,207 @@ using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationRows; using static AgentCore.Infrastructure.Conversation.Postgres.PostgresConversationStoreSql; -namespace AgentCore.Infrastructure.Conversation.Postgres; - -/// The words of every conversation, in PostgreSQL: store 1's rows, and what a turn writes beside them. -internal sealed class PostgresConversationWords +namespace AgentCore.Infrastructure.Conversation.Postgres { - private readonly NpgsqlDataSource _dataSource; - - /// Binds the words to the pool every statement runs on. The store owns the pool; this does not. + /// The words of every conversation, in PostgreSQL: store 1's rows, and what a turn writes beside them. + /// Binds the words to the pool every statement runs on. The store owns the pool; this does not. /// The pool. - public PostgresConversationWords(NpgsqlDataSource dataSource) => _dataSource = dataSource; - - /// - [SuppressMessage( - "csharpsquid", - "S3265", - Justification = "Npgsql documents Array combined with an element type via bit OR, and the enum omits Flags only upstream.")] - public async ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) + internal sealed class PostgresConversationWords(NpgsqlDataSource dataSource) { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentNullException.ThrowIfNull(messages); - - if (messages.Count == 0) + private readonly NpgsqlDataSource _dataSource = dataSource; + + /// + [SuppressMessage( + "csharpsquid", + "S3265", + Justification = "Npgsql documents Array combined with an element type via bit OR, and the enum omits Flags only upstream.")] + public async ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) { - return []; - } + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentNullException.ThrowIfNull(messages); - await using var connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); - await using NpgsqlBatch batch = new(connection); + if (messages.Count == 0) + { + return []; + } - NpgsqlBatchCommand appendCommand = new(AppendSql); - appendCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.TurnIndex)], - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.Content.Role.Value)], - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - Value = messages.Select(message => Serialise(message.Content)).ToArray(), - NpgsqlDbType = NpgsqlDbType.Array | NpgsqlDbType.Jsonb, - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.MessageId)], - }); - appendCommand.Parameters.Add(new NpgsqlParameter - { - TypedValue = [.. messages.Select(message => message.CoversUpTo)], - }); - batch.BatchCommands.Add(appendCommand); + await using NpgsqlConnection connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); + await using NpgsqlBatch batch = new(connection); - if (state is not null) - { - NpgsqlBatchCommand stateCommand = new(StateSql); - stateCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - stateCommand.Parameters.Add(new NpgsqlParameter + NpgsqlBatchCommand appendCommand = new(AppendSql); + _ = appendCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.TurnIndex)], + }); + _ = appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.Content.Role.Value)], + }); + _ = appendCommand.Parameters.Add(new NpgsqlParameter { - Value = JsonSerializer.Serialize(state, ConversationStateJson.Options), - NpgsqlDbType = NpgsqlDbType.Jsonb, + Value = messages.Select(message => Serialise(message.Content)).ToArray(), + NpgsqlDbType = NpgsqlDbType.Array | NpgsqlDbType.Jsonb, }); + _ = appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.MessageId)], + }); + _ = appendCommand.Parameters.Add(new NpgsqlParameter + { + TypedValue = [.. messages.Select(message => message.CoversUpTo)], + }); + batch.BatchCommands.Add(appendCommand); - batch.BatchCommands.Add(stateCommand); - } + if (state is not null) + { + NpgsqlBatchCommand stateCommand = new(StateSql); + _ = stateCommand.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = stateCommand.Parameters.Add(new NpgsqlParameter + { + Value = JsonSerializer.Serialize(state, ConversationStateJson.Options), + NpgsqlDbType = NpgsqlDbType.Jsonb, + }); + + batch.BatchCommands.Add(stateCommand); + } - // AppendSql is the only command with a RETURNING clause, so its result set is the only one - // this reads. Matched by message_id and not by row order: PostgreSQL makes no promise that a - // multi-row INSERT ... SELECT returns in the order its source rows arrived. - Dictionary written = []; + // AppendSql is the only command with a RETURNING clause, so its result set is the only one + // this reads. Matched by message_id and not by row order: PostgreSQL makes no promise that a + // multi-row INSERT ... SELECT returns in the order its source rows arrived. + Dictionary written = []; - await using (var reader = await batch.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false)) - { - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + await using (NpgsqlDataReader reader = await batch.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false)) { - written[reader.GetString(2)] = (reader.GetInt32(0), reader.GetInt32(1)); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + { + written[reader.GetString(2)] = (reader.GetInt32(0), reader.GetInt32(1)); + } } - } - if (written.Count == 0) - { - throw new InvalidOperationException($"Store 0 holds no conversation '{conversationId}' to append words to."); + return written.Count == 0 + ? throw new InvalidOperationException($"Store 0 holds no conversation '{conversationId}' to append words to.") + : [.. messages.Select(draft => + { + (int ordinal, int turnIndex) = written[draft.MessageId]; + return new ConversationMessage(conversationId, ordinal, turnIndex, draft.Content, draft.MessageId) { CoversUpTo = draft.CoversUpTo }; + })]; } - return [.. messages.Select(draft => + /// + public async ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) { - var (ordinal, turnIndex) = written[draft.MessageId]; - return new ConversationMessage(conversationId, ordinal, turnIndex, draft.Content, draft.MessageId) { CoversUpTo = draft.CoversUpTo }; - })]; - } - - /// - public async ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentException.ThrowIfNullOrEmpty(messageId); - ArgumentNullException.ThrowIfNull(content); + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); + ArgumentNullException.ThrowIfNull(content); - await using var command = _dataSource.CreateCommand(RewriteSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = messageId }); - command.Parameters.Add(new NpgsqlParameter { Value = Serialise(content), NpgsqlDbType = NpgsqlDbType.Jsonb }); + await using NpgsqlCommand command = _dataSource.CreateCommand(RewriteSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = messageId }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = Serialise(content), NpgsqlDbType = NpgsqlDbType.Jsonb }); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } - - private static async ValueTask> ReadRowsAsync( - string conversationId, NpgsqlCommand command, CancellationToken cancellationToken) - { - List rows = []; + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + private static async ValueTask> ReadRowsAsync( + string conversationId, NpgsqlCommand command, CancellationToken cancellationToken) { - rows.Add(new ConversationMessage( - conversationId, - reader.GetInt32(0), - reader.GetInt32(1), - Deserialise(reader.GetString(2)), - reader.GetString(3)) + List rows = []; + + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { - CoversUpTo = reader.IsDBNull(4) ? null : reader.GetInt32(4), - }); - } + rows.Add(new ConversationMessage( + conversationId, + reader.GetInt32(0), + reader.GetInt32(1), + Deserialise(reader.GetString(2)), + reader.GetString(3)) + { + CoversUpTo = reader.IsDBNull(4) ? null : reader.GetInt32(4), + }); + } - return rows; - } + return rows; + } - /// - /// The conversation id is . - public async ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + /// The conversation id is . + public async ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - await using var command = _dataSource.CreateCommand(ReadForSessionSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + await using NpgsqlCommand command = _dataSource.CreateCommand(ReadForSessionSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - return await ReadRowsAsync(conversationId, command, cancellationToken).ConfigureAwait(false); - } + return await ReadRowsAsync(conversationId, command, cancellationToken).ConfigureAwait(false); + } - /// - /// The conversation id is . - public async ValueTask> ReadWindowAsync( - string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + /// The conversation id is . + public async ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - await using var command = _dataSource.CreateCommand(ReadWindowSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { TypedValue = window.BeforeTurn, NpgsqlDbType = NpgsqlDbType.Integer }); - command.Parameters.Add(new NpgsqlParameter { Value = window.Turns }); + await using NpgsqlCommand command = _dataSource.CreateCommand(ReadWindowSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter { TypedValue = window.BeforeTurn, NpgsqlDbType = NpgsqlDbType.Integer }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = window.Turns }); - return await ReadRowsAsync(conversationId, command, cancellationToken).ConfigureAwait(false); - } + return await ReadRowsAsync(conversationId, command, cancellationToken).ConfigureAwait(false); + } - /// - /// The conversation id is . - /// The message id is or empty. - public async ValueTask OrdinalOfAsync( - string conversationId, string messageId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); - ArgumentException.ThrowIfNullOrEmpty(messageId); + /// + /// The conversation id is . + /// The message id is or empty. + public async ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); + ArgumentException.ThrowIfNullOrEmpty(messageId); - await using var command = _dataSource.CreateCommand(OrdinalOfSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = messageId }); + await using NpgsqlCommand command = _dataSource.CreateCommand(OrdinalOfSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = messageId }); - return await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false) is int ordinal ? ordinal : null; - } + return await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false) is int ordinal ? ordinal : null; + } - /// - /// The conversation id is . - public async ValueTask TruncateAsync( - string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + /// The conversation id is . + public async ValueTask TruncateAsync( + string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - await using var command = _dataSource.CreateCommand(TruncateSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - command.Parameters.Add(new NpgsqlParameter { Value = fromOrdinal }); + await using NpgsqlCommand command = _dataSource.CreateCommand(TruncateSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + _ = command.Parameters.Add(new NpgsqlParameter { Value = fromOrdinal }); - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - await reader.ReadAsync(cancellationToken).ConfigureAwait(false); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + _ = await reader.ReadAsync(cancellationToken).ConfigureAwait(false); - WithdrawnTurns? turns = reader.IsDBNull(1) ? null : new(reader.GetInt32(1), reader.GetInt32(2)); - return new(reader.GetInt32(0), turns); - } + WithdrawnTurns? turns = reader.IsDBNull(1) ? null : new(reader.GetInt32(1), reader.GetInt32(2)); + return new(reader.GetInt32(0), turns); + } - /// - /// The conversation id is . - public async ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(conversationId); + /// + /// The conversation id is . + public async ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(conversationId); - await using var command = _dataSource.CreateCommand(EraseSql); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + await using NpgsqlCommand command = _dataSource.CreateCommand(EraseSql); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - return await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + return await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } } } diff --git a/src/AgentCore.Infrastructure/Database/Postgres/PostgresDataSourceFactory.cs b/src/AgentCore.Infrastructure/Database/Postgres/PostgresDataSourceFactory.cs index 87f67519..61475ff6 100644 --- a/src/AgentCore.Infrastructure/Database/Postgres/PostgresDataSourceFactory.cs +++ b/src/AgentCore.Infrastructure/Database/Postgres/PostgresDataSourceFactory.cs @@ -2,54 +2,55 @@ using AgentCore.Application.Secrets; using Npgsql; -namespace AgentCore.Infrastructure.Database.Postgres; - -/// -/// Opens a migrated pool for the vendors that keep something in PostgreSQL. -/// -/// -/// The audit chain and the transcript are two stores and one database, and each adapter opened it the -/// same way: resolve the one connection-string secret, create the pool, apply the schema, and drop the -/// pool if the schema will not apply. That sequence lives here so a third store cannot get it subtly -/// different, and so the failure a deployment sees is one failure and not two. -/// -internal static class PostgresDataSourceFactory +namespace AgentCore.Infrastructure.Database.Postgres { - /// Resolves the connection string, opens the pool, and applies the schema to it. - /// The chain the credential resolves through, or . - /// - /// What this pool is for, written into the failure a deployment reads when the secret is missing. - /// - /// Cancels the resolve and the migration. - /// The pool, which the caller then owns and disposes. - /// The connection string resolves to nothing. + /// + /// Opens a migrated pool for the vendors that keep something in PostgreSQL. + /// /// - /// This runs once, while the host starts, so a missing credential or an unreachable database stops - /// the host and never a conversation. + /// The audit chain and the transcript are two stores and one database, and each adapter opened it the + /// same way: resolve the one connection-string secret, create the pool, apply the schema, and drop the + /// pool if the schema will not apply. That sequence lives here so a third store cannot get it subtly + /// different, and so the failure a deployment sees is one failure and not two. /// - internal static async ValueTask OpenMigratedAsync( - ISecretResolverPort? secrets, - string purpose, - CancellationToken cancellationToken) + internal static class PostgresDataSourceFactory { - var connectionString = await secrets - .RequireAsync(KnownSecrets.PostgresConnectionString, purpose, cancellationToken) - .ConfigureAwait(false); + /// Resolves the connection string, opens the pool, and applies the schema to it. + /// The chain the credential resolves through, or . + /// + /// What this pool is for, written into the failure a deployment reads when the secret is missing. + /// + /// Cancels the resolve and the migration. + /// The pool, which the caller then owns and disposes. + /// The connection string resolves to nothing. + /// + /// This runs once, while the host starts, so a missing credential or an unreachable database stops + /// the host and never a conversation. + /// + internal static async ValueTask OpenMigratedAsync( + ISecretResolverPort? secrets, + string purpose, + CancellationToken cancellationToken) + { + string connectionString = await secrets + .RequireAsync(KnownSecrets.PostgresConnectionString, purpose, cancellationToken) + .ConfigureAwait(false); - NpgsqlDataSource dataSource = NpgsqlDataSource.Create(connectionString); + NpgsqlDataSource dataSource = NpgsqlDataSource.Create(connectionString); - try - { - await PostgresSchema.ApplyAsync(dataSource, cancellationToken).ConfigureAwait(false); - } - catch - { - // The store that would have owned this pool was never built. - await dataSource.DisposeAsync().ConfigureAwait(false); + try + { + _ = await PostgresSchema.ApplyAsync(dataSource, cancellationToken).ConfigureAwait(false); + } + catch + { + // The store that would have owned this pool was never built. + await dataSource.DisposeAsync().ConfigureAwait(false); - throw; - } + throw; + } - return dataSource; + return dataSource; + } } } diff --git a/src/AgentCore.Infrastructure/Database/Postgres/PostgresSchema.cs b/src/AgentCore.Infrastructure/Database/Postgres/PostgresSchema.cs index a440ed38..e71f6449 100644 --- a/src/AgentCore.Infrastructure/Database/Postgres/PostgresSchema.cs +++ b/src/AgentCore.Infrastructure/Database/Postgres/PostgresSchema.cs @@ -1,167 +1,168 @@ +using System.Reflection; using Npgsql; -namespace AgentCore.Infrastructure.Database.Postgres; - -/// -/// The PostgreSQL schema store, and the applier that puts it in place. -/// -public static class PostgresSchema +namespace AgentCore.Infrastructure.Database.Postgres { - private const string ResourcePrefix = "AgentCore.Infrastructure.Database.Postgres.Migrations."; + /// + /// The PostgreSQL schema store, and the applier that puts it in place. + /// + public static class PostgresSchema + { + private const string ResourcePrefix = "AgentCore.Infrastructure.Database.Postgres.Migrations."; - /// The schema every AgentCore table lives in. - internal const string SchemaName = "agentcore"; + /// The schema every AgentCore table lives in. + internal const string SchemaName = "agentcore"; - /// Guards two processes migrating one database at the same moment. - /// - /// The value is arbitrary. It only has to be the same in every process that migrates, so it is a - /// constant here rather than anything derived. - /// - private const long ApplyLockKey = 0x41C05CE700000001; + /// Guards two processes migrating one database at the same moment. + /// + /// The value is arbitrary. It only has to be the same in every process that migrates, so it is a + /// constant here rather than anything derived. + /// + private const long ApplyLockKey = 0x41C05CE700000001; - private const string LedgerName = $"{SchemaName}.schema_migration"; + private const string LedgerName = $"{SchemaName}.schema_migration"; - private const string LedgerDdl = $""" + private const string LedgerDdl = $""" CREATE TABLE {LedgerName} ( version text NOT NULL PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now() ) """; - /// Every migration this assembly carries, in the order it is applied. - internal static IReadOnlyList Versions { get; } = ReadVersions().AsReadOnly(); - - /// Reads one migration's SQL out of the assembly. - /// A value from . - /// The script text. - /// No migration carries that version. - private static string Read(string version) - { - ArgumentNullException.ThrowIfNull(version); - - var assembly = typeof(PostgresSchema).Assembly; - using var stream = assembly.GetManifestResourceStream(ResourcePrefix + version + ".sql") - ?? throw new ArgumentException($"No migration is named '{version}'.", nameof(version)); - using var reader = new StreamReader(stream); - return reader.ReadToEnd(); - } + /// Every migration this assembly carries, in the order it is applied. + internal static IReadOnlyList Versions { get; } = ReadVersions().AsReadOnly(); - /// Applies every migration the database has not seen yet. - /// A data source whose role may create the agentcore schema and tables in it. - /// Cancels the work. - /// The versions this conversation applied, oldest first. Empty when the schema was current. - /// - /// The connecting role also needs CREATEROLE the first time, because migration 001 creates - /// agentcore_writer. The running system connects as a member of that role, not as this one. - /// - public static async Task> ApplyAsync( - NpgsqlDataSource dataSource, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(dataSource); + /// Reads one migration's SQL out of the assembly. + /// A value from . + /// The script text. + /// No migration carries that version. + private static string Read(string version) + { + ArgumentNullException.ThrowIfNull(version); - await using var connection = await dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); - await using var transaction = await connection.BeginTransactionAsync(cancellationToken).ConfigureAwait(false); + Assembly assembly = typeof(PostgresSchema).Assembly; + using Stream stream = assembly.GetManifestResourceStream(ResourcePrefix + version + ".sql") + ?? throw new ArgumentException($"No migration is named '{version}'.", nameof(version)); + using StreamReader reader = new(stream); + return reader.ReadToEnd(); + } - // The lock comes first. Two sessions creating the ledger at once race in the catalogue, and - // the loser reports a duplicate key on pg_type rather than a clean no-op. - await using (NpgsqlCommand serialise = new("SELECT pg_advisory_xact_lock($1)", connection, transaction)) + /// Applies every migration the database has not seen yet. + /// A data source whose role may create the agentcore schema and tables in it. + /// Cancels the work. + /// The versions this conversation applied, oldest first. Empty when the schema was current. + /// + /// The connecting role also needs CREATEROLE the first time, because migration 001 creates + /// agentcore_writer. The running system connects as a member of that role, not as this one. + /// + public static async Task> ApplyAsync( + NpgsqlDataSource dataSource, + CancellationToken cancellationToken = default) { - serialise.Parameters.Add(new NpgsqlParameter { Value = ApplyLockKey }); - await serialise.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + ArgumentNullException.ThrowIfNull(dataSource); - var schemaExists = await ScalarAsync( - connection, transaction, $"SELECT to_regnamespace('{SchemaName}') IS NOT NULL", cancellationToken).ConfigureAwait(false); + await using NpgsqlConnection connection = await dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false); + await using NpgsqlTransaction transaction = await connection.BeginTransactionAsync(cancellationToken).ConfigureAwait(false); - if (!schemaExists) - { - await ExecuteAsync(connection, transaction, $"CREATE SCHEMA {SchemaName}", cancellationToken).ConfigureAwait(false); - } + // The lock comes first. Two sessions creating the ledger at once race in the catalogue, and + // the loser reports a duplicate key on pg_type rather than a clean no-op. + await using (NpgsqlCommand serialise = new("SELECT pg_advisory_xact_lock($1)", connection, transaction)) + { + _ = serialise.Parameters.Add(new NpgsqlParameter { Value = ApplyLockKey }); + _ = await serialise.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - // Ask whether the ledger is there rather than issuing CREATE TABLE IF NOT EXISTS. The running - // system starts as agentcore_writer, which may create nothing; on an already-migrated database - // this path then reads twice and writes no DDL, and only the first, privileged run creates. - // to_regclass answers for a role that holds no right on the table at all. - var ledgerExists = await ScalarAsync( - connection, transaction, $"SELECT to_regclass('{LedgerName}') IS NOT NULL", cancellationToken).ConfigureAwait(false); + bool schemaExists = await ScalarAsync( + connection, transaction, $"SELECT to_regnamespace('{SchemaName}') IS NOT NULL", cancellationToken).ConfigureAwait(false); - if (!ledgerExists) - { - await ExecuteAsync(connection, transaction, LedgerDdl, cancellationToken).ConfigureAwait(false); - } + if (!schemaExists) + { + await ExecuteAsync(connection, transaction, $"CREATE SCHEMA {SchemaName}", cancellationToken).ConfigureAwait(false); + } - var applied = await ReadAppliedAsync(connection, transaction, cancellationToken).ConfigureAwait(false); - List ran = []; + // Ask whether the ledger is there rather than issuing CREATE TABLE IF NOT EXISTS. The running + // system starts as agentcore_writer, which may create nothing; on an already-migrated database + // this path then reads twice and writes no DDL, and only the first, privileged run creates. + // to_regclass answers for a role that holds no right on the table at all. + bool ledgerExists = await ScalarAsync( + connection, transaction, $"SELECT to_regclass('{LedgerName}') IS NOT NULL", cancellationToken).ConfigureAwait(false); - foreach (var version in Versions) - { - if (applied.Contains(version)) + if (!ledgerExists) { - continue; + await ExecuteAsync(connection, transaction, LedgerDdl, cancellationToken).ConfigureAwait(false); } - await ExecuteAsync(connection, transaction, Read(version), cancellationToken).ConfigureAwait(false); + HashSet applied = await ReadAppliedAsync(connection, transaction, cancellationToken).ConfigureAwait(false); + List ran = []; - await using var record = new NpgsqlCommand( - $"INSERT INTO {LedgerName} (version) VALUES ($1)", connection, transaction); - record.Parameters.AddWithValue(version); - await record.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + foreach (string version in Versions) + { + if (applied.Contains(version)) + { + continue; + } - ran.Add(version); - } + await ExecuteAsync(connection, transaction, Read(version), cancellationToken).ConfigureAwait(false); - await transaction.CommitAsync(cancellationToken).ConfigureAwait(false); - return ran; - } + await using NpgsqlCommand record = new( + $"INSERT INTO {LedgerName} (version) VALUES ($1)", connection, transaction); + _ = record.Parameters.AddWithValue(version); + _ = await record.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - private static async Task> ReadAppliedAsync( - NpgsqlConnection connection, - NpgsqlTransaction transaction, - CancellationToken cancellationToken) - { - HashSet applied = new(StringComparer.Ordinal); + ran.Add(version); + } + + await transaction.CommitAsync(cancellationToken).ConfigureAwait(false); + return ran; + } - await using var command = new NpgsqlCommand($"SELECT version FROM {LedgerName}", connection, transaction); - await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + private static async Task> ReadAppliedAsync( + NpgsqlConnection connection, + NpgsqlTransaction transaction, + CancellationToken cancellationToken) { - applied.Add(reader.GetString(0)); + HashSet applied = new(StringComparer.Ordinal); + + await using NpgsqlCommand command = new($"SELECT version FROM {LedgerName}", connection, transaction); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) + { + _ = applied.Add(reader.GetString(0)); + } + + return applied; } - return applied; - } + private static async Task ScalarAsync( + NpgsqlConnection connection, + NpgsqlTransaction transaction, + string sql, + CancellationToken cancellationToken) + { + await using NpgsqlCommand command = new(sql, connection, transaction); + return (T)(await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false))!; + } - private static async Task ScalarAsync( - NpgsqlConnection connection, - NpgsqlTransaction transaction, - string sql, - CancellationToken cancellationToken) - { - await using var command = new NpgsqlCommand(sql, connection, transaction); - return (T)(await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false))!; - } + private static async Task ExecuteAsync( + NpgsqlConnection connection, + NpgsqlTransaction transaction, + string sql, + CancellationToken cancellationToken) + { + await using NpgsqlCommand command = new(sql, connection, transaction); + _ = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); + } - private static async Task ExecuteAsync( - NpgsqlConnection connection, - NpgsqlTransaction transaction, - string sql, - CancellationToken cancellationToken) - { - await using var command = new NpgsqlCommand(sql, connection, transaction); - await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); - } + private static List ReadVersions() + { + List names = [.. typeof(PostgresSchema).Assembly.GetManifestResourceNames() + .Where(name => name.StartsWith(ResourcePrefix, StringComparison.Ordinal) + && name.EndsWith(".sql", StringComparison.Ordinal)) + .Select(name => name[ResourcePrefix.Length..^".sql".Length])]; - private static List ReadVersions() - { - var names = typeof(PostgresSchema).Assembly.GetManifestResourceNames() - .Where(name => name.StartsWith(ResourcePrefix, StringComparison.Ordinal) - && name.EndsWith(".sql", StringComparison.Ordinal)) - .Select(name => name[ResourcePrefix.Length..^".sql".Length]) - .ToList(); - - names.Sort(StringComparer.Ordinal); - return names; + names.Sort(StringComparer.Ordinal); + return names; + } } } diff --git a/src/AgentCore.Infrastructure/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapter.cs b/src/AgentCore.Infrastructure/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapter.cs index 4b82712b..07a9e830 100644 --- a/src/AgentCore.Infrastructure/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapter.cs +++ b/src/AgentCore.Infrastructure/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapter.cs @@ -5,45 +5,46 @@ using Microsoft.Extensions.AI; using OpenAI; -namespace AgentCore.Infrastructure.Embeddings.OpenAI; - -/// -/// The OpenAI adapter behind . -/// -public sealed class OpenAiEmbeddingGeneratorAdapter : IEmbeddingGeneratorAdapter +namespace AgentCore.Infrastructure.Embeddings.OpenAI { - /// The one providers.embeddings.kind value this adapter serves. - public const string ProviderKind = "openai"; - - /// The ${secret:name} name the resolver chain is asked for. - public const string ApiKeySecretName = KnownSecrets.OpenAiApiKeyName; - - /// The standard OpenAI environment variable, read when the chain holds no name. - public const string ApiKeyVariableName = KnownSecrets.OpenAiApiKeyVariable; - - /// - public string Kind => ProviderKind; - - /// Builds the generator of the one providers.embeddings block. - /// The block, whose kind named this adapter. - /// The resolver chain, or to read the environment only. - /// Cancels the key read. - /// The generator. The host owns and disposes it. - /// Neither the chain nor the environment holds a key. - public async ValueTask>> CreateGeneratorAsync( - EmbeddingProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) + /// + /// The OpenAI adapter behind . + /// + public sealed class OpenAiEmbeddingGeneratorAdapter : IEmbeddingGeneratorAdapter { - ArgumentNullException.ThrowIfNull(entry); - - var client = new OpenAIClient(new ApiKeyCredential( - await secrets - .RequireAsync(KnownSecrets.OpenAi, cancellationToken: cancellationToken) - .ConfigureAwait(false))); - - return client - .GetEmbeddingClient(entry.Model) - .AsIEmbeddingGenerator(entry.Dimensions); + /// The one providers.embeddings.kind value this adapter serves. + public const string ProviderKind = "openai"; + + /// The ${secret:name} name the resolver chain is asked for. + public const string ApiKeySecretName = KnownSecrets.OpenAiApiKeyName; + + /// The standard OpenAI environment variable, read when the chain holds no name. + public const string ApiKeyVariableName = KnownSecrets.OpenAiApiKeyVariable; + + /// + public string Kind => ProviderKind; + + /// Builds the generator of the one providers.embeddings block. + /// The block, whose kind named this adapter. + /// The resolver chain, or to read the environment only. + /// Cancels the key read. + /// The generator. The host owns and disposes it. + /// Neither the chain nor the environment holds a key. + public async ValueTask>> CreateGeneratorAsync( + EmbeddingProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(entry); + + OpenAIClient client = new(new ApiKeyCredential( + await secrets + .RequireAsync(KnownSecrets.OpenAi, cancellationToken: cancellationToken) + .ConfigureAwait(false))); + + return client + .GetEmbeddingClient(entry.Model) + .AsIEmbeddingGenerator(entry.Dimensions); + } } } diff --git a/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationAdapter.cs b/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationAdapter.cs index 4d7fbb74..fc3fc520 100644 --- a/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationAdapter.cs +++ b/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationAdapter.cs @@ -2,36 +2,39 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Infrastructure.Evaluation.OpenAiModeration; - -/// -/// The openai moderation vendor: the OpenAI Moderation endpoint behind . -/// -public sealed class OpenAiModerationAdapter : IModerationAdapter +namespace AgentCore.Infrastructure.Evaluation.OpenAiModeration { - /// The one kind value this adapter serves. - public const string ProviderKind = "openai"; + /// + /// The openai moderation vendor: the OpenAI Moderation endpoint behind . + /// + public sealed class OpenAiModerationAdapter : IModerationAdapter + { + /// The one kind value this adapter serves. + public const string ProviderKind = "openai"; - private readonly IHttpMessageHandlerFactory _handlers; + private readonly IHttpMessageHandlerFactory _handlers; - /// Creates the adapter over the outbound pipeline of the host. - /// The pipeline that holds the connection lifetime, the deadline, and the retry. - /// The pipeline is . - public OpenAiModerationAdapter(IHttpMessageHandlerFactory handlers) - { - ArgumentNullException.ThrowIfNull(handlers); - _handlers = handlers; - } + /// Creates the adapter over the outbound pipeline of the host. + /// The pipeline that holds the connection lifetime, the deadline, and the retry. + /// The pipeline is . + public OpenAiModerationAdapter(IHttpMessageHandlerFactory handlers) + { + ArgumentNullException.ThrowIfNull(handlers); + _handlers = handlers; + } - /// Gets the one kind value this adapter serves. - public string Kind => ProviderKind; + /// Gets the one kind value this adapter serves. + public string Kind => ProviderKind; - /// - public async ValueTask CreateAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => await OpenAiModerationEvaluator - .CreateAsync(_handlers, secrets, cancellationToken) - .ConfigureAwait(false); + /// + public async ValueTask CreateAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return await OpenAiModerationEvaluator + .CreateAsync(_handlers, secrets, cancellationToken) + .ConfigureAwait(false); + } + } } diff --git a/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationEvaluator.cs b/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationEvaluator.cs index e8e16d7c..1a0c1ab1 100644 --- a/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationEvaluator.cs +++ b/src/AgentCore.Infrastructure/Evaluation/OpenAiModeration/OpenAiModerationEvaluator.cs @@ -12,369 +12,373 @@ using OpenAI; using OpenAI.Moderations; -namespace AgentCore.Infrastructure.Evaluation.OpenAiModeration; - -/// -/// Checks one piece of text against the OpenAI moderations endpoint. -/// -public sealed class OpenAiModerationEvaluator : IEvaluator +namespace AgentCore.Infrastructure.Evaluation.OpenAiModeration { - /// The name this evaluator is registered under, beside fault_code. - public const string EvaluatorName = PromptModerator.ModerationEvaluatorName; - - /// The name of the one metric this evaluator produces. - public const string ContentSafetyMetricName = "Content Safety"; - - /// The moderation model D13 names. Its price is nothing, at any volume. - public const string ModerationModel = "omni-moderation-latest"; - - /// The route one check posts to. - public const string ModerationPath = "/v1/moderations"; - - /// The name this evaluator opens its client under, on the pipeline of the host. - - public const string HttpClientName = "agentcore.openai.moderation"; - - /// The host every moderation request goes to. - public static readonly Uri ApiEndpoint = new("https://api.openai.com", UriKind.Absolute); - - /// The deadline of one check, over every attempt the pipeline makes. - public static readonly TimeSpan ModerationDeadline = TimeSpan.FromSeconds(10); - - /// The thirteen category names D13 counts, in the order the endpoint writes them. - public static readonly IReadOnlyList Categories = - [ - "harassment", - "harassment/threatening", - "hate", - "hate/threatening", - "illicit", - "illicit/violent", - "self-harm", - "self-harm/instructions", - "self-harm/intent", - "sexual", - "sexual/minors", - "violence", - "violence/graphic", - ]; - - /// The metadata key that records which model answered. - private const string ModelMetadataKey = "model"; - - /// The reason every inconclusive metric of this evaluator carries. - private const string UncheckedReason = "the moderation endpoint did not answer, so the text is unchecked."; - - /// The score format one flagged category is recorded in. - private const string ScoreFormat = "0.####"; - - private readonly ModerationClient _client; - private readonly TimeSpan _deadline; - - /// Opens the evaluator over one SDK client. - /// - /// The client. carries the key, the deadline, and the pipeline of the - /// host onto it; this constructor trusts whatever it is given. - /// - /// - /// The deadline was built with, read back by . - /// - internal OpenAiModerationEvaluator(ModerationClient client, TimeSpan deadline) - { - ArgumentNullException.ThrowIfNull(client); - - _client = client; - _deadline = deadline; - } - - /// Gets the name of the one metric this evaluator produces. - public IReadOnlyCollection EvaluationMetricNames => [ContentSafetyMetricName]; - - /// Gets the deadline of one check, which set on the client. - internal TimeSpan Deadline => _deadline; - - /// Builds the evaluator, over the pipeline the host built. - /// - /// The outbound HTTP pipeline. This evaluator asks it for . - /// - /// The chain the key resolves through, or . - /// Cancels the key read. - /// The evaluator. - /// is . - /// Neither the chain nor the environment holds a key. - public static async ValueTask CreateAsync( - IHttpMessageHandlerFactory handlers, - ISecretResolverPort? secrets = null, - CancellationToken cancellationToken = default) + /// + /// Checks one piece of text against the OpenAI moderations endpoint. + /// + public sealed class OpenAiModerationEvaluator : IEvaluator { - ArgumentNullException.ThrowIfNull(handlers); - - var apiKey = await secrets - .RequireAsync( - KnownSecrets.OpenAi, - "The moderation evaluator checks every turn against " + ModerationModel + ".", - cancellationToken) - .ConfigureAwait(false); + /// The name this evaluator is registered under, beside fault_code. + public const string EvaluatorName = PromptModerator.ModerationEvaluatorName; + + /// The name of the one metric this evaluator produces. + public const string ContentSafetyMetricName = "Content Safety"; + + /// The moderation model D13 names. Its price is nothing, at any volume. + public const string ModerationModel = "omni-moderation-latest"; + + /// The route one check posts to. + public const string ModerationPath = "/v1/moderations"; + + /// The name this evaluator opens its client under, on the pipeline of the host. + + public const string HttpClientName = "agentcore.openai.moderation"; + + /// The host every moderation request goes to. + public static readonly Uri ApiEndpoint = new("https://api.openai.com", UriKind.Absolute); + + /// The deadline of one check, over every attempt the pipeline makes. + public static readonly TimeSpan ModerationDeadline = TimeSpan.FromSeconds(10); + + /// The thirteen category names D13 counts, in the order the endpoint writes them. + public static readonly IReadOnlyList Categories = + [ + "harassment", + "harassment/threatening", + "hate", + "hate/threatening", + "illicit", + "illicit/violent", + "self-harm", + "self-harm/instructions", + "self-harm/intent", + "sexual", + "sexual/minors", + "violence", + "violence/graphic", + ]; + + /// The metadata key that records which model answered. + private const string ModelMetadataKey = "model"; + + /// The reason every inconclusive metric of this evaluator carries. + private const string UncheckedReason = "the moderation endpoint did not answer, so the text is unchecked."; + + /// The score format one flagged category is recorded in. + private const string ScoreFormat = "0.####"; + + private readonly ModerationClient _client; + + /// Opens the evaluator over one SDK client. + /// + /// The client. carries the key, the deadline, and the pipeline of the + /// host onto it; this constructor trusts whatever it is given. + /// + /// + /// The deadline was built with, read back by . + /// + internal OpenAiModerationEvaluator(ModerationClient client, TimeSpan deadline) + { + ArgumentNullException.ThrowIfNull(client); - // The pipeline owns the chain below this transport, and other clients send on the same - // chain, so this client disposes nothing. - HttpClient transport = new(handlers.CreateHandler(HttpClientName), disposeHandler: false); + _client = client; + Deadline = deadline; + } - OpenAIClientOptions options = new() + /// Gets the name of the one metric this evaluator produces. + public IReadOnlyCollection EvaluationMetricNames => [ContentSafetyMetricName]; + + /// Gets the deadline of one check, which set on the client. + internal TimeSpan Deadline { get; } + + /// Builds the evaluator, over the pipeline the host built. + /// + /// The outbound HTTP pipeline. This evaluator asks it for . + /// + /// The chain the key resolves through, or . + /// Cancels the key read. + /// The evaluator. + /// is . + /// Neither the chain nor the environment holds a key. + public static async ValueTask CreateAsync( + IHttpMessageHandlerFactory handlers, + ISecretResolverPort? secrets = null, + CancellationToken cancellationToken = default) { - Endpoint = new Uri(ApiEndpoint, "/v1"), - Transport = new HttpClientPipelineTransport(transport), - NetworkTimeout = ModerationDeadline, - RetryPolicy = new ClientRetryPolicy(maxRetries: 0), - }; + ArgumentNullException.ThrowIfNull(handlers); - // The key is handed to the SDK's own credential here, while the host starts, and no class - // that builds a body or reads an answer holds it from this point on. - var client = new OpenAIClient(new ApiKeyCredential(apiKey), options).GetModerationClient(ModerationModel); + string apiKey = await secrets + .RequireAsync( + KnownSecrets.OpenAi, + "The moderation evaluator checks every turn against " + ModerationModel + ".", + cancellationToken) + .ConfigureAwait(false); - return new OpenAiModerationEvaluator(client, ModerationDeadline); - } + // The pipeline owns the chain below this transport, and other clients send on the same + // chain, so this client disposes nothing. + HttpClient transport = new(handlers.CreateHandler(HttpClientName), disposeHandler: false); - /// - /// - /// - /// The text is modelResponse.Text, and the caller decides which text it puts there. The - /// , , and - /// arguments are unread: this endpoint takes one string and - /// no history. - /// - /// - /// Text that is empty or blank sends no request and passes. The endpoint refuses an empty - /// input, and a check that asks about nothing costs nothing. - /// - /// - /// A vendor problem gives an inconclusive metric and no exception. A cancel by - /// still throws, because that is the decision of the caller - /// and not a failure of the endpoint. - /// - /// - /// is . - /// was cancelled. - public async ValueTask EvaluateAsync( - IEnumerable messages, - ChatResponse modelResponse, - ChatConfiguration? chatConfiguration = null, - IEnumerable? additionalContext = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(modelResponse); - cancellationToken.ThrowIfCancellationRequested(); + OpenAIClientOptions options = new() + { + Endpoint = new Uri(ApiEndpoint, "/v1"), + Transport = new HttpClientPipelineTransport(transport), + NetworkTimeout = ModerationDeadline, + RetryPolicy = new ClientRetryPolicy(maxRetries: 0), + }; - var text = modelResponse.Text; - if (string.IsNullOrWhiteSpace(text)) - { - return new EvaluationResult(NothingToCheck()); + // The key is handed to the SDK's own credential here, while the host starts, and no class + // that builds a body or reads an answer holds it from this point on. + ModerationClient client = new OpenAIClient(new ApiKeyCredential(apiKey), options).GetModerationClient(ModerationModel); + + return new OpenAiModerationEvaluator(client, ModerationDeadline); } - string payload; - try + /// + /// + /// + /// The text is modelResponse.Text, and the caller decides which text it puts there. The + /// , , and + /// arguments are unread: this endpoint takes one string and + /// no history. + /// + /// + /// Text that is empty or blank sends no request and passes. The endpoint refuses an empty + /// input, and a check that asks about nothing costs nothing. + /// + /// + /// A vendor problem gives an inconclusive metric and no exception. A cancel by + /// still throws, because that is the decision of the caller + /// and not a failure of the endpoint. + /// + /// + /// is . + /// was cancelled. + public async ValueTask EvaluateAsync( + IEnumerable messages, + ChatResponse modelResponse, + ChatConfiguration? chatConfiguration = null, + IEnumerable? additionalContext = null, + CancellationToken cancellationToken = default) { - RequestOptions options = new() - { - CancellationToken = cancellationToken, - - // This class decides what a non-2xx status means, the same way it always has: Read() - // below never runs on one. Left at the SDK's default, ClassifyTextAsync would throw - // instead of handing back the response this class needs to build that message from. - ErrorOptions = ClientErrorBehaviors.NoThrow, - }; + ArgumentNullException.ThrowIfNull(modelResponse); + cancellationToken.ThrowIfCancellationRequested(); - // The key rides on the ApiKeyCredential this client was built with, so no credential - // passes through here. - var response = await _client - .ClassifyTextAsync(BinaryContent.CreateJson(Body(text)), options) - .ConfigureAwait(false); + string text = modelResponse.Text; + if (string.IsNullOrWhiteSpace(text)) + { + return new EvaluationResult(NothingToCheck()); + } - var raw = response.GetRawResponse(); - if (raw.Status is < 200 or >= 300) + string payload; + try + { + RequestOptions options = new() + { + CancellationToken = cancellationToken, + + // This class decides what a non-2xx status means, the same way it always has: Read() + // below never runs on one. Left at the SDK's default, ClassifyTextAsync would throw + // instead of handing back the response this class needs to build that message from. + ErrorOptions = ClientErrorBehaviors.NoThrow, + }; + + // The key rides on the ApiKeyCredential this client was built with, so no credential + // passes through here. + ClientResult response = await _client + .ClassifyTextAsync(BinaryContent.CreateJson(Body(text)), options) + .ConfigureAwait(false); + + PipelineResponse raw = response.GetRawResponse(); + if (raw.Status is < 200 or >= 300) + { + return new EvaluationResult(Unchecked( + "the moderation endpoint answered HTTP " + + raw.Status.ToString(CultureInfo.InvariantCulture) + + " " + (HttpStatusCode)raw.Status + ".")); + } + + payload = raw.Content.ToString(); + } + catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + { + // The deadline ran out. A cancel by the caller leaves the token cancelled, so the filter + // above is false and that exception travels on. + return new EvaluationResult(Unchecked( + "the moderation endpoint did not answer inside " + + Deadline.TotalSeconds.ToString(CultureInfo.InvariantCulture) + " seconds.")); + } + catch (ClientResultException error) { + // ErrorOptions.NoThrow above means this fires only when the transport never got a + // response at all — a DNS failure, a refused connection — not for a status the endpoint + // answered. return new EvaluationResult(Unchecked( - "the moderation endpoint answered HTTP " - + raw.Status.ToString(CultureInfo.InvariantCulture) - + " " + (HttpStatusCode)raw.Status + ".")); + "the moderation endpoint could not be reached: " + error.Message)); } - payload = raw.Content.ToString(); - } - catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) - { - // The deadline ran out. A cancel by the caller leaves the token cancelled, so the filter - // above is false and that exception travels on. - return new EvaluationResult(Unchecked( - "the moderation endpoint did not answer inside " - + _deadline.TotalSeconds.ToString(CultureInfo.InvariantCulture) + " seconds.")); - } - catch (ClientResultException error) - { - // ErrorOptions.NoThrow above means this fires only when the transport never got a - // response at all — a DNS failure, a refused connection — not for a status the endpoint - // answered. - return new EvaluationResult(Unchecked( - "the moderation endpoint could not be reached: " + error.Message)); + return new EvaluationResult(Read(payload)); } - return new EvaluationResult(Read(payload)); - } - - /// Writes the body the moderations route expects. - /// The text to check. - /// The JSON body. - private static string Body(string text) - { - JsonObject body = new() + /// Writes the body the moderations route expects. + /// The text to check. + /// The JSON body. + private static string Body(string text) { - [ModelMetadataKey] = ModerationModel, - ["input"] = text, - }; - - return body.ToJsonString(); - } + JsonObject body = new() + { + [ModelMetadataKey] = ModerationModel, + ["input"] = text, + }; - /// Reads the answer of one check. - /// The body the endpoint answered. - /// The metric, which is inconclusive when the body cannot be read. - private static BooleanMetric Read(string payload) - { - JsonDocument document; - try - { - document = JsonDocument.Parse(payload); - } - catch (JsonException) - { - return Unchecked("the moderation endpoint answered a body that is not JSON."); + return body.ToJsonString(); } - using (document) + /// Reads the answer of one check. + /// The body the endpoint answered. + /// The metric, which is inconclusive when the body cannot be read. + private static BooleanMetric Read(string payload) { - var root = document.RootElement; - if (root.ValueKind != JsonValueKind.Object) + JsonDocument document; + try { - return Unchecked("the moderation endpoint answered a body that is not a JSON object."); + document = JsonDocument.Parse(payload); } - - if (!root.TryGetProperty("results", out var results) || results.ValueKind != JsonValueKind.Array) + catch (JsonException) { - return Unchecked("the moderation endpoint answered no results array."); + return Unchecked("the moderation endpoint answered a body that is not JSON."); } - // One input gives one element. An empty array is no evidence about the text. - if (results.GetArrayLength() == 0) + using (document) { - return Unchecked("the moderation endpoint answered an empty results array."); + JsonElement root = document.RootElement; + if (root.ValueKind != JsonValueKind.Object) + { + return Unchecked("the moderation endpoint answered a body that is not a JSON object."); + } + + if (!root.TryGetProperty("results", out JsonElement results) || results.ValueKind != JsonValueKind.Array) + { + return Unchecked("the moderation endpoint answered no results array."); + } + + // One input gives one element. An empty array is no evidence about the text. + if (results.GetArrayLength() == 0) + { + return Unchecked("the moderation endpoint answered an empty results array."); + } + + JsonElement first = results[0]; + if (first.ValueKind != JsonValueKind.Object + || !first.TryGetProperty("flagged", out JsonElement reported) + || (reported.ValueKind != JsonValueKind.True && reported.ValueKind != JsonValueKind.False)) + { + return Unchecked("the moderation endpoint answered a result with no flagged field."); + } + + // The endpoint owns the verdict, at its own thresholds. Recomputing it from the flags + // would drift the day OpenAI moves one. + bool flagged = reported.ValueKind == JsonValueKind.True; + + return Measure(first, flagged, Flags(first)); } + } - var first = results[0]; - if (first.ValueKind != JsonValueKind.Object - || !first.TryGetProperty("flagged", out var reported) - || (reported.ValueKind != JsonValueKind.True && reported.ValueKind != JsonValueKind.False)) + /// Collects the names the endpoint flagged, in the order it returned them. + /// The first element of results. + /// The names. + private static List Flags(JsonElement result) + { + List names = []; + if (!result.TryGetProperty("categories", out JsonElement categories) || categories.ValueKind != JsonValueKind.Object) { - return Unchecked("the moderation endpoint answered a result with no flagged field."); + return names; } - // The endpoint owns the verdict, at its own thresholds. Recomputing it from the flags - // would drift the day OpenAI moves one. - var flagged = reported.ValueKind == JsonValueKind.True; - - return Measure(first, flagged, Flags(first)); - } - } + foreach (JsonProperty category in categories.EnumerateObject()) + { + if (category.Value.ValueKind == JsonValueKind.True) + { + names.Add(category.Name); + } + } - /// Collects the names the endpoint flagged, in the order it returned them. - /// The first element of results. - /// The names. - private static List Flags(JsonElement result) - { - List names = []; - if (!result.TryGetProperty("categories", out var categories) || categories.ValueKind != JsonValueKind.Object) - { return names; } - foreach (var category in categories.EnumerateObject()) + /// Builds the metric one answered check produces. + /// The first element of results, read for the scores. + /// What the endpoint answered. + /// The names the endpoint flagged, in its order. + /// The metric, with the verdict on it. + private static BooleanMetric Measure(JsonElement result, bool flagged, List names) { - if (category.Value.ValueKind == JsonValueKind.True) - { - names.Add(category.Name); - } - } + string reason = names.Count == 0 ? ModerationVerdict.NothingFlagged : string.Join(", ", names); - return names; - } + // True means safe. FaultCodeEvaluator reads the same way, where true means the reply is right. + BooleanMetric metric = new(ContentSafetyMetricName, value: !flagged, reason) + { + Interpretation = new EvaluationMetricInterpretation( + flagged ? EvaluationRating.Unacceptable : EvaluationRating.Exceptional, + failed: flagged, + reason: reason) + }; - /// Builds the metric one answered check produces. - /// The first element of results, read for the scores. - /// What the endpoint answered. - /// The names the endpoint flagged, in its order. - /// The metric, with the verdict on it. - private static BooleanMetric Measure(JsonElement result, bool flagged, List names) - { - var reason = names.Count == 0 ? ModerationVerdict.NothingFlagged : string.Join(", ", names); + metric.AddOrUpdateContext(new ModerationVerdict(flagged, names)); + metric.AddOrUpdateMetadata(ModelMetadataKey, ModerationModel); - // True means safe. FaultCodeEvaluator reads the same way, where true means the reply is right. - BooleanMetric metric = new(ContentSafetyMetricName, value: !flagged, reason); - metric.Interpretation = new EvaluationMetricInterpretation( - flagged ? EvaluationRating.Unacceptable : EvaluationRating.Exceptional, - failed: flagged, - reason: reason); + // The scores of the flagged categories only. OpenAI does not present them as comparable + // across categories, so nothing here aggregates them into one number. + if (!result.TryGetProperty("category_scores", out JsonElement scores) || scores.ValueKind != JsonValueKind.Object) + { + return metric; + } - metric.AddOrUpdateContext(new ModerationVerdict(flagged, names)); - metric.AddOrUpdateMetadata(ModelMetadataKey, ModerationModel); + foreach (string name in names) + { + if (scores.TryGetProperty(name, out JsonElement score) && score.ValueKind == JsonValueKind.Number) + { + metric.AddOrUpdateMetadata( + name, + score.GetDouble().ToString(ScoreFormat, CultureInfo.InvariantCulture)); + } + } - // The scores of the flagged categories only. OpenAI does not present them as comparable - // across categories, so nothing here aggregates them into one number. - if (!result.TryGetProperty("category_scores", out var scores) || scores.ValueKind != JsonValueKind.Object) - { return metric; } - foreach (var name in names) + /// Builds the metric text with nothing in it produces. + /// The metric, with a verdict that flags nothing. + private static BooleanMetric NothingToCheck() { - if (scores.TryGetProperty(name, out var score) && score.ValueKind == JsonValueKind.Number) - { - metric.AddOrUpdateMetadata( - name, - score.GetDouble().ToString(ScoreFormat, CultureInfo.InvariantCulture)); - } - } + const string reason = "the text is empty, so nothing was posted."; - return metric; - } - - /// Builds the metric text with nothing in it produces. - /// The metric, with a verdict that flags nothing. - private static BooleanMetric NothingToCheck() - { - const string reason = "the text is empty, so nothing was posted."; + BooleanMetric metric = new(ContentSafetyMetricName, value: true, reason) + { + Interpretation = new EvaluationMetricInterpretation( + EvaluationRating.Exceptional, + failed: false, + reason: reason) + }; - BooleanMetric metric = new(ContentSafetyMetricName, value: true, reason); - metric.Interpretation = new EvaluationMetricInterpretation( - EvaluationRating.Exceptional, - failed: false, - reason: reason); + metric.AddOrUpdateContext(new ModerationVerdict(flagged: false, [])); - metric.AddOrUpdateContext(new ModerationVerdict(flagged: false, [])); + return metric; + } - return metric; - } + /// Builds the metric every failure of this evaluator produces. + /// What went wrong, named for the diagnostic. + /// The metric, with no value and no verdict. + private static BooleanMetric Unchecked(string what) + { + BooleanMetric metric = new(ContentSafetyMetricName, value: null); + metric.AddDiagnostics(EvaluationDiagnostic.Error(what)); + metric.Interpretation = new EvaluationMetricInterpretation( + EvaluationRating.Inconclusive, + failed: false, + reason: UncheckedReason); - /// Builds the metric every failure of this evaluator produces. - /// What went wrong, named for the diagnostic. - /// The metric, with no value and no verdict. - private static BooleanMetric Unchecked(string what) - { - BooleanMetric metric = new(ContentSafetyMetricName, value: null); - metric.AddDiagnostics(EvaluationDiagnostic.Error(what)); - metric.Interpretation = new EvaluationMetricInterpretation( - EvaluationRating.Inconclusive, - failed: false, - reason: UncheckedReason); - - return metric; + return metric; + } } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs index 879d5e21..6142134b 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs @@ -2,53 +2,56 @@ using AgentCore.Application.Knowledge; using AgentCore.Domain.Knowledge; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// The built-in mapper: the fields: block, applied to one neutral point. -public sealed class FieldsPointMapper : IKnowledgePointMapper +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - /// The name the built-in mapping answers to. - public const string MapperName = "fields"; - - private readonly KnowledgeFieldsConfiguration _fields; - - /// Creates the mapper over one fields: block. - /// The payload paths this collection's roles sit at. - /// is . - public FieldsPointMapper(KnowledgeFieldsConfiguration fields) + /// The built-in mapper: the fields: block, applied to one neutral point. + public sealed class FieldsPointMapper : IKnowledgePointMapper { - ArgumentNullException.ThrowIfNull(fields); + /// The name the built-in mapping answers to. + public const string MapperName = "fields"; - _fields = fields; - } + private readonly KnowledgeFieldsConfiguration _fields; - /// Gets the name providers.knowledge.mapper selects this by. + /// Creates the mapper over one fields: block. + /// The payload paths this collection's roles sit at. + /// is . + public FieldsPointMapper(KnowledgeFieldsConfiguration fields) + { + ArgumentNullException.ThrowIfNull(fields); - public string Name => MapperName; + _fields = fields; + } - /// - /// is . - public KnowledgeCard? Map(KnowledgePoint point) - { - ArgumentNullException.ThrowIfNull(point); + /// Gets the name providers.knowledge.mapper selects this by. + + public string Name => MapperName; - return new KnowledgeCard + /// + /// is . + public KnowledgeCard? Map(KnowledgePoint point) { - CardId = ReadString(point.Payload, _fields.Id) is { Length: > 0 } id ? id : point.PointId, - Text = ReadString(point.Payload, _fields.Body) ?? string.Empty, - SourceRef = ReadString(point.Payload, _fields.Source) ?? string.Empty, - SourceLocator = ReadString(point.Payload, _fields.Locator) ?? string.Empty, - Authority = PayloadPath.Read(point.Payload, _fields.Authority) is long authority ? (int)authority : null, - Score = point.Score, - ViaLink = false, - - // The whole payload, not the leftovers. The six roles above are what AgentCore acts on; - // a deployment's own citation wording, or anything else reading a card downstream, needs - // the fields this block never named, and there is no second round trip to fetch them. - Extras = point.Payload, - }; + ArgumentNullException.ThrowIfNull(point); + + return new KnowledgeCard + { + CardId = ReadString(point.Payload, _fields.Id) is { Length: > 0 } id ? id : point.PointId, + Text = ReadString(point.Payload, _fields.Body) ?? string.Empty, + SourceRef = ReadString(point.Payload, _fields.Source) ?? string.Empty, + SourceLocator = ReadString(point.Payload, _fields.Locator) ?? string.Empty, + Authority = PayloadPath.Read(point.Payload, _fields.Authority) is long authority ? (int)authority : null, + Score = point.Score, + ViaLink = false, + + // The whole payload, not the leftovers. The six roles above are what AgentCore acts on; + // a deployment's own citation wording, or anything else reading a card downstream, needs + // the fields this block never named, and there is no second round trip to fetch them. + Extras = point.Payload, + }; + } + + private static string? ReadString(IReadOnlyDictionary payload, string? path) + { + return PayloadPath.Read(payload, path) as string; + } } - - private static string? ReadString(IReadOnlyDictionary payload, string? path) - => PayloadPath.Read(payload, path) as string; } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs index e36b523d..da28bcf8 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs @@ -1,41 +1,42 @@ using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// One query, ready to send. -/// The collection, always an alias. -/// The legs the top-level query draws its candidates from. -/// What ranks those candidates: a fusion over several legs, or a nearest re-score over one. -/// How many results to return. -/// The named vector the top-level query scores with, or for the collection's anonymous vector. Qdrant refuses it beside a fusion. -internal sealed record SearchQuery( - string Collection, IReadOnlyList Prefetch, Query Query, ulong Limit, string? Using = null); - -/// -/// The seam between the store and the wire. -/// -internal interface IQdrantSearchChannel +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - /// Sends one fused query. - /// The query. - /// Cancels the conversation. The store links its deadline into this. - /// The scored points, best first. - Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken); + /// One query, ready to send. + /// The collection, always an alias. + /// The legs the top-level query draws its candidates from. + /// What ranks those candidates: a fusion over several legs, or a nearest re-score over one. + /// How many results to return. + /// The named vector the top-level query scores with, or for the collection's anonymous vector. Qdrant refuses it beside a fusion. + internal sealed record SearchQuery( + string Collection, IReadOnlyList Prefetch, Query Query, ulong Limit, string? Using = null); + + /// + /// The seam between the store and the wire. + /// + internal interface IQdrantSearchChannel + { + /// Sends one fused query. + /// The query. + /// Cancels the conversation. The store links its deadline into this. + /// The scored points, best first. + Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken); - /// Fetches whole points by key, in one call. - /// The collection. - /// The keys. - /// Cancels the conversation. - /// The points that exist. An unknown key is left out; it does not throw. - Task> RetrieveAsync( - string collection, IReadOnlyList ids, CancellationToken cancellationToken); + /// Fetches whole points by key, in one call. + /// The collection. + /// The keys. + /// Cancels the conversation. + /// The points that exist. An unknown key is left out; it does not throw. + Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken); - /// Fetches whole points by a payload filter, in one call. - /// The collection. - /// What the points must match. - /// The most points to return. - /// Cancels the conversation. - /// The points that matched. An empty result is not an error. - Task> ScrollAsync( - string collection, Filter filter, uint limit, CancellationToken cancellationToken); + /// Fetches whole points by a payload filter, in one call. + /// The collection. + /// What the points must match. + /// The most points to return. + /// Cancels the conversation. + /// The points that matched. An empty result is not an error. + Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken); + } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantCollectionProof.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantCollectionProof.cs index 6909a6ed..0514162e 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantCollectionProof.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantCollectionProof.cs @@ -1,275 +1,273 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; +using AgentCore.Domain.Knowledge; using Google.Protobuf.Collections; using Microsoft.Extensions.AI; using Qdrant.Client; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// -/// The startup proof of one collection: it exists, its vector is as wide as this host embeds, and -/// one point read back carries what the store reads off it. Every failure is a refusal to start -/// rather than a deployment that silently returns nothing. -/// -internal static class QdrantCollectionProof +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - // Embedded once at startup, only to measure the deployment's embedder width against the - // collection's own. Its content is never a real query and is never sent to Qdrant. - private const string DimensionProbeText = "agentcore-qdrant-startup-probe"; - - /// Runs every proof against the live collection. - /// One proof failed. - internal static async ValueTask AssertAsync( - QdrantClient client, - KnowledgeProviderConfiguration entry, - IEmbeddingGenerator> embedder, - IKnowledgePointMapper? mapper, - Guid linkNamespace, - CancellationToken cancellationToken) + /// + /// The startup proof of one collection: it exists, its vector is as wide as this host embeds, and + /// one point read back carries what the store reads off it. Every failure is a refusal to start + /// rather than a deployment that silently returns nothing. + /// + internal static class QdrantCollectionProof { - if (!await client.CollectionExistsAsync(entry.Collection, cancellationToken).ConfigureAwait(false)) - { - throw new InvalidOperationException( - $"providers.knowledge.collection names '{entry.Collection}', and no such collection or " - + "alias exists on this cluster. AgentCore reads a knowledge base and never creates " - + "one: run whatever ingests your cards, or correct the name."); - } + // Embedded once at startup, only to measure the deployment's embedder width against the + // collection's own. Its content is never a real query and is never sent to Qdrant. + private const string DimensionProbeText = "agentcore-qdrant-startup-probe"; - var info = await client.GetCollectionInfoAsync(entry.Collection, cancellationToken).ConfigureAwait(false); - var width = VectorWidth(info.Config.Params.VectorsConfig, entry); - var dimensions = await EmbedderWidthAsync(embedder, entry, cancellationToken).ConfigureAwait(false); - - if (width != dimensions) + /// Runs every proof against the live collection. + /// One proof failed. + internal static async ValueTask AssertAsync( + QdrantClient client, + KnowledgeProviderConfiguration entry, + IEmbeddingGenerator> embedder, + IKnowledgePointMapper? mapper, + Guid linkNamespace, + CancellationToken cancellationToken) { - var label = entry.Vector is { Length: > 0 } named ? $"a '{named}' vector" : "an anonymous vector"; - throw new InvalidOperationException( - $"'{entry.Collection}' has {label} of {width} dimensions and this " - + $"host embeds at {dimensions}. Every score would be meaningless. Either set " - + "providers.embeddings to the model this collection was built with, or rebuild the " - + "collection with this host's model."); - } + if (!await client.CollectionExistsAsync(entry.Collection, cancellationToken).ConfigureAwait(false)) + { + throw new InvalidOperationException( + $"providers.knowledge.collection names '{entry.Collection}', and no such collection or " + + "alias exists on this cluster. AgentCore reads a knowledge base and never creates " + + "one: run whatever ingests your cards, or correct the name."); + } - await AssertPayloadAsync(client, entry, mapper, linkNamespace, cancellationToken).ConfigureAwait(false); - } + CollectionInfo info = await client.GetCollectionInfoAsync(entry.Collection, cancellationToken).ConfigureAwait(false); + ulong width = VectorWidth(info.Config.Params.VectorsConfig, entry); + ulong dimensions = await EmbedderWidthAsync(embedder, entry, cancellationToken).ConfigureAwait(false); - /// Reads the width of the vector the document names, or of the one anonymous vector. - private static ulong VectorWidth(VectorsConfig vectors, KnowledgeProviderConfiguration entry) - { - if (entry.Vector is { Length: > 0 } vectorName) - { - if (vectors.ConfigCase != VectorsConfig.ConfigOneofCase.ParamsMap - || !vectors.ParamsMap.Map.TryGetValue(vectorName, out var dense)) + if (width != dimensions) { + string label = entry.Vector is { Length: > 0 } named ? $"a '{named}' vector" : "an anonymous vector"; throw new InvalidOperationException( - $"'{entry.Collection}' carries no named vector '{vectorName}'. A collection whose " - + "vector is unnamed, or named something else, misses every point on search with no " - + "error — and it still fetches by key, so a smoke test would not notice. Set " - + "providers.knowledge.vector to the name the collection was built with, or drop " - + "the setting for a collection with a single anonymous vector."); + $"'{entry.Collection}' has {label} of {width} dimensions and this " + + $"host embeds at {dimensions}. Every score would be meaningless. Either set " + + "providers.embeddings to the model this collection was built with, or rebuild the " + + "collection with this host's model."); } - return dense.Size; + await AssertPayloadAsync(client, entry, mapper, linkNamespace, cancellationToken).ConfigureAwait(false); } - if (vectors.ConfigCase != VectorsConfig.ConfigOneofCase.Params) + /// Reads the width of the vector the document names, or of the one anonymous vector. + private static ulong VectorWidth(VectorsConfig vectors, KnowledgeProviderConfiguration entry) { - throw new InvalidOperationException( - $"'{entry.Collection}' carries named vectors and providers.knowledge.vector names " - + "none, so every query would search an anonymous vector this collection does not " - + "have and miss every point with no error. Set providers.knowledge.vector to the " - + "name the collection was built with."); - } - - return vectors.Params.Size; - } + if (entry.Vector is { Length: > 0 } vectorName) + { + return vectors.ConfigCase == VectorsConfig.ConfigOneofCase.ParamsMap + && vectors.ParamsMap.Map.TryGetValue(vectorName, out VectorParams? dense) + ? dense.Size + : throw new InvalidOperationException( + $"'{entry.Collection}' carries no named vector '{vectorName}'. A collection whose " + + "vector is unnamed, or named something else, misses every point on search with no " + + "error — and it still fetches by key, so a smoke test would not notice. Set " + + "providers.knowledge.vector to the name the collection was built with, or drop " + + "the setting for a collection with a single anonymous vector."); + } - /// Embeds the probe text once, only to measure how wide this host's vectors are. - private static async ValueTask EmbedderWidthAsync( - IEmbeddingGenerator> embedder, - KnowledgeProviderConfiguration entry, - CancellationToken cancellationToken) - { - try - { - var probe = await embedder - .GenerateAsync(DimensionProbeText, cancellationToken: cancellationToken) - .ConfigureAwait(false); - return (ulong)probe.Vector.Length; + return vectors.ConfigCase == VectorsConfig.ConfigOneofCase.Params + ? vectors.Params.Size + : throw new InvalidOperationException( + $"'{entry.Collection}' carries named vectors and providers.knowledge.vector names " + + "none, so every query would search an anonymous vector this collection does not " + + "have and miss every point with no error. Set providers.knowledge.vector to the " + + "name the collection was built with."); } - catch (Exception ex) when (ex is not OperationCanceledException) + + /// Embeds the probe text once, only to measure how wide this host's vectors are. + private static async ValueTask EmbedderWidthAsync( + IEmbeddingGenerator> embedder, + KnowledgeProviderConfiguration entry, + CancellationToken cancellationToken) { - throw new InvalidOperationException( - $"'{entry.Collection}' could not be checked against this host's embedder: the startup " - + "width probe failed before it produced a vector. This is not a schema problem with " - + "the collection; check the embedding generator's own configuration and credentials.", - ex); + try + { + Embedding probe = await embedder + .GenerateAsync(DimensionProbeText, cancellationToken: cancellationToken) + .ConfigureAwait(false); + return (ulong)probe.Vector.Length; + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + throw new InvalidOperationException( + $"'{entry.Collection}' could not be checked against this host's embedder: the startup " + + "width probe failed before it produced a vector. This is not a schema problem with " + + "the collection; check the embedding generator's own configuration and credentials.", + ex); + } } - } - - /// - /// Reads one point back and proves the payload still carries what the store reads off it. - /// - private static async ValueTask AssertPayloadAsync( - QdrantClient client, - KnowledgeProviderConfiguration entry, - IKnowledgePointMapper? mapper, - Guid linkNamespace, - CancellationToken cancellationToken) - { - var scrolled = await client - .ScrollAsync(entry.Collection, limit: 1, cancellationToken: cancellationToken) - .ConfigureAwait(false); - if (scrolled.Result.Count == 0) + /// + /// Reads one point back and proves the payload still carries what the store reads off it. + /// + private static async ValueTask AssertPayloadAsync( + QdrantClient client, + KnowledgeProviderConfiguration entry, + IKnowledgePointMapper? mapper, + Guid linkNamespace, + CancellationToken cancellationToken) { - return; - } + ScrollResponse scrolled = await client + .ScrollAsync(entry.Collection, limit: 1, cancellationToken: cancellationToken) + .ConfigureAwait(false); - var point = scrolled.Result[0]; + if (scrolled.Result.Count == 0) + { + return; + } - if (mapper is not null) - { - // A custom mapper owns the payload shape, so no key list can be asserted — but the - // refuse-to-start property survives: map the one scrolled point and demand text. - var card = mapper.Map(QdrantPointConverter.ToPoint(point.Id, point.Payload, score: null)); - if (card is not { Text.Length: > 0 }) + RetrievedPoint point = scrolled.Result[0]; + + if (mapper is not null) { - throw new InvalidOperationException( - $"'{entry.Collection}' holds points that mapper '{mapper.Name}' reads as empty: it " - + "returned no card, or a card with no text, for a point scrolled at startup. " - + "AgentCore would then inject blank cards into every turn without failing anything. " - + "Correct the mapper, or point this host at the collection it was written for."); + // A custom mapper owns the payload shape, so no key list can be asserted — but the + // refuse-to-start property survives: map the one scrolled point and demand text. + KnowledgeCard? card = mapper.Map(QdrantPointConverter.ToPoint(point.Id, point.Payload, score: null)); + if (card is not { Text.Length: > 0 }) + { + throw new InvalidOperationException( + $"'{entry.Collection}' holds points that mapper '{mapper.Name}' reads as empty: it " + + "returned no card, or a card with no text, for a point scrolled at startup. " + + "AgentCore would then inject blank cards into every turn without failing anything. " + + "Correct the mapper, or point this host at the collection it was written for."); + } + + return; } - return; - } + foreach ((string? role, string? key, bool numeric) in DeclaredKeys(entry.Fields!)) + { + if (!Carries(point.Payload, key, numeric)) + { + throw new InvalidOperationException( + $"'{entry.Collection}' holds points whose payload has no {(numeric ? "numeric" : "non-empty")} " + + $"'{key}', which providers.knowledge.fields.{role} names. AgentCore reads every field " + + "that block maps off every point and treats a missing key as absent, so this role " + + "would be silently empty on every card. Map the path this collection really uses, " + + "declare the role with an explicit null if the collection does not carry it, or " + + "point this host at the collection whose payload matches."); + } + } - foreach (var (role, key, numeric) in DeclaredKeys(entry.Fields!)) - { - if (!Carries(point.Payload, key, numeric)) + if (entry.Links is { } links && links.Lookup != KnowledgeLinkLookup.Filter) { - throw new InvalidOperationException( - $"'{entry.Collection}' holds points whose payload has no {(numeric ? "numeric" : "non-empty")} " - + $"'{key}', which providers.knowledge.fields.{role} names. AgentCore reads every field " - + "that block maps off every point and treats a missing key as absent, so this role " - + "would be silently empty on every card. Map the path this collection really uses, " - + "declare the role with an explicit null if the collection does not carry it, or " - + "point this host at the collection whose payload matches."); + AssertPointKey(point, entry, links, linkNamespace); } } - if (entry.Links is { } links && links.Lookup != KnowledgeLinkLookup.Filter) + /// + /// Every payload key the document actually mapped, with the role that named it and whether that + /// role holds a number rather than text. + /// + /// + /// All six roles, not the two the built-in mapping cannot do without. A wrong path under + /// source, locator or authority throws nothing and returns nothing: the + /// citation is simply blank on every card, on every turn, for the life of the deployment. That is + /// exactly the failure a startup proof exists to convert into a refusal to start. + /// + private static IEnumerable<(string Role, string Key, bool Numeric)> DeclaredKeys( + KnowledgeFieldsConfiguration fields) { - AssertPointKey(point, entry, links, linkNamespace); - } - } + if (fields.Body is { Length: > 0 } body) + { + yield return ("body", body, false); + } - /// - /// Every payload key the document actually mapped, with the role that named it and whether that - /// role holds a number rather than text. - /// - /// - /// All six roles, not the two the built-in mapping cannot do without. A wrong path under - /// source, locator or authority throws nothing and returns nothing: the - /// citation is simply blank on every card, on every turn, for the life of the deployment. That is - /// exactly the failure a startup proof exists to convert into a refusal to start. - /// - private static IEnumerable<(string Role, string Key, bool Numeric)> DeclaredKeys( - KnowledgeFieldsConfiguration fields) - { - if (fields.Body is { Length: > 0 } body) - { - yield return ("body", body, false); - } + if (fields.Id is { Length: > 0 } id) + { + yield return ("id", id, false); + } - if (fields.Id is { Length: > 0 } id) - { - yield return ("id", id, false); - } + if (fields.Lexical is { Length: > 0 } lexical) + { + yield return ("lexical", lexical, false); + } - if (fields.Lexical is { Length: > 0 } lexical) - { - yield return ("lexical", lexical, false); - } + if (fields.Source is { Length: > 0 } source) + { + yield return ("source", source, false); + } - if (fields.Source is { Length: > 0 } source) - { - yield return ("source", source, false); - } + if (fields.Locator is { Length: > 0 } locator) + { + yield return ("locator", locator, false); + } - if (fields.Locator is { Length: > 0 } locator) - { - yield return ("locator", locator, false); + // Authority ranks trust, so a collection writes it as an integer. Demanding a string here + // would refuse every correctly built collection there is. + if (fields.Authority is { Length: > 0 } authority) + { + yield return ("authority", authority, true); + } } - // Authority ranks trust, so a collection writes it as an integer. Demanding a string here - // would refuse every correctly built collection there is. - if (fields.Authority is { Length: > 0 } authority) + /// Whether one point really carries the role a mapped key claims. + private static bool Carries(MapField payload, string key, bool numeric) { - yield return ("authority", authority, true); + return QdrantPayload.Read(payload, key) switch + { + { KindCase: Value.KindOneofCase.StringValue } value => !numeric && value.StringValue.Length > 0, + { KindCase: Value.KindOneofCase.IntegerValue } => numeric, + { KindCase: Value.KindOneofCase.DoubleValue } => numeric, + _ => false, + }; } - } - /// Whether one point really carries the role a mapped key claims. - private static bool Carries(MapField payload, string key, bool numeric) - => QdrantPayload.Read(payload, key) switch + /// Proves a linked id resolves back to the point that holds it. + private static void AssertPointKey( + RetrievedPoint point, + KnowledgeProviderConfiguration entry, + KnowledgeLinksConfiguration links, + Guid linkNamespace) { - { KindCase: Value.KindOneofCase.StringValue } value => !numeric && value.StringValue.Length > 0, - { KindCase: Value.KindOneofCase.IntegerValue } => numeric, - { KindCase: Value.KindOneofCase.DoubleValue } => numeric, - _ => false, - }; + if (QdrantPayload.Read(point.Payload, links.Field!) is null) + { + return; + } - /// Proves a linked id resolves back to the point that holds it. - private static void AssertPointKey( - RetrievedPoint point, - KnowledgeProviderConfiguration entry, - KnowledgeLinksConfiguration links, - Guid linkNamespace) - { - if (QdrantPayload.Read(point.Payload, links.Field!) is null) - { - return; - } + string cardId = QdrantPayload.Read(point.Payload, entry.Fields!.Id!)!.StringValue; - var cardId = QdrantPayload.Read(point.Payload, entry.Fields!.Id!)!.StringValue; + if (point.Id.PointIdOptionsCase != PointId.PointIdOptionsOneofCase.Uuid) + { + throw new InvalidOperationException( + $"'{entry.Collection}' holds points keyed by number, and providers.knowledge.links.lookup " + + $"is {links.Lookup.ToString().ToLowerInvariant()}, which builds a UUID key. Every " + + "link expansion would silently return nothing. Set links.lookup: filter to match on " + + $"'{entry.Fields.Id}' instead."); + } - if (point.Id.PointIdOptionsCase != PointId.PointIdOptionsOneofCase.Uuid) - { - throw new InvalidOperationException( - $"'{entry.Collection}' holds points keyed by number, and providers.knowledge.links.lookup " - + $"is {links.Lookup.ToString().ToLowerInvariant()}, which builds a UUID key. Every " - + "link expansion would silently return nothing. Set links.lookup: filter to match on " - + $"'{entry.Fields.Id}' instead."); - } + Guid expected; + if (links.Lookup == KnowledgeLinkLookup.Direct) + { + if (!Guid.TryParse(cardId, out expected)) + { + throw new InvalidOperationException( + $"'{entry.Collection}' holds a point whose '{entry.Fields.Id}' is '{cardId}', which is " + + "not a GUID, but providers.knowledge.links.lookup is direct. Qdrant's point key is a " + + "GUID or an unsigned integer, so a free-form id cannot be one. Set links.lookup: " + + $"filter to match on '{entry.Fields.Id}' instead."); + } + } + else + { + expected = Uuid5PointId.For(cardId, linkNamespace, links.Prefix); + } - Guid expected; - if (links.Lookup == KnowledgeLinkLookup.Direct) - { - if (!Guid.TryParse(cardId, out expected)) + if (Guid.Parse(point.Id.Uuid) != expected) { throw new InvalidOperationException( - $"'{entry.Collection}' holds a point whose '{entry.Fields.Id}' is '{cardId}', which is " - + "not a GUID, but providers.knowledge.links.lookup is direct. Qdrant's point key is a " - + "GUID or an unsigned integer, so a free-form id cannot be one. Set links.lookup: " - + $"filter to match on '{entry.Fields.Id}' instead."); + $"'{entry.Collection}' holds a point whose '{entry.Fields.Id}' is '{cardId}' and whose " + + $"point key is {point.Id.Uuid}, but providers.knowledge.links.lookup is " + + $"{links.Lookup.ToString().ToLowerInvariant()} with namespace " + + $"'{links.Namespace}' and prefix '{links.Prefix}', which derives {expected}. " + + $"Every '{links.Field}' expansion would silently return nothing. Correct the " + + $"namespace or prefix, or set links.lookup: filter to match on '{entry.Fields.Id}'."); } } - else - { - expected = Uuid5PointId.For(cardId, linkNamespace, links.Prefix); - } - - if (Guid.Parse(point.Id.Uuid) != expected) - { - throw new InvalidOperationException( - $"'{entry.Collection}' holds a point whose '{entry.Fields.Id}' is '{cardId}' and whose " - + $"point key is {point.Id.Uuid}, but providers.knowledge.links.lookup is " - + $"{links.Lookup.ToString().ToLowerInvariant()} with namespace " - + $"'{links.Namespace}' and prefix '{links.Prefix}', which derives {expected}. " - + $"Every '{links.Field}' expansion would silently return nothing. Correct the " - + $"namespace or prefix, or set links.lookup: filter to match on '{entry.Fields.Id}'."); - } } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs index 55cbd46f..f070651b 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs @@ -6,278 +6,283 @@ using Microsoft.Extensions.AI; using Qdrant.Client; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// -/// The qdrant knowledge vendor: a read-only Qdrant collection behind the ranking port. -/// -public sealed class QdrantKnowledgeAdapter : IKnowledgeStoreAdapter +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - /// The one kind value this adapter serves. - public const string ProviderKind = "qdrant"; - - /// The ${secret:name} name the resolver chain is asked for. - public const string ApiKeySecretName = KnownSecrets.QdrantApiKeyName; - - /// The standard Qdrant environment variable, read when the chain holds no name. - public const string ApiKeyVariableName = KnownSecrets.QdrantApiKeyVariable; - - // The JSON Pointer a missing or unreadable cluster URL reports. - private const string EndpointPointer = "/providers/knowledge/endpoint"; - - // The JSON Pointer a missing embedding generator reports. - private const string EmbeddingsPointer = "/providers/embeddings"; - - // The deadline of one gRPC call. The connector never sets one on its own. - private static readonly TimeSpan CallDeadline = TimeSpan.FromSeconds(30); - - private readonly Func? _clientFactory; - - private readonly IEmbeddingGenerator>? _embeddings; - - private IReadOnlyList _analyzers = [new NoQueryAnalyzer()]; - - private IKnowledgePointMapper[] _mappers = []; - /// - /// Creates the adapter that embeds through the generator providers.embeddings builds. + /// The qdrant knowledge vendor: a read-only Qdrant collection behind the ranking port. /// - public QdrantKnowledgeAdapter() + public sealed class QdrantKnowledgeAdapter : IKnowledgeStoreAdapter { - } + /// The one kind value this adapter serves. + public const string ProviderKind = "qdrant"; - /// Creates the adapter over a generator the caller builds. - public QdrantKnowledgeAdapter(IEmbeddingGenerator> embeddings) - { - ArgumentNullException.ThrowIfNull(embeddings); + /// The ${secret:name} name the resolver chain is asked for. + public const string ApiKeySecretName = KnownSecrets.QdrantApiKeyName; - _embeddings = embeddings; - } + /// The standard Qdrant environment variable, read when the chain holds no name. + public const string ApiKeyVariableName = KnownSecrets.QdrantApiKeyVariable; - /// Creates the adapter over a client the caller builds. - internal QdrantKnowledgeAdapter( - Func clientFactory, - IEmbeddingGenerator> embeddings) - { - ArgumentNullException.ThrowIfNull(clientFactory); - ArgumentNullException.ThrowIfNull(embeddings); + // The JSON Pointer a missing or unreadable cluster URL reports. + private const string EndpointPointer = "/providers/knowledge/endpoint"; - _clientFactory = clientFactory; - _embeddings = embeddings; - } + // The JSON Pointer a missing embedding generator reports. + private const string EmbeddingsPointer = "/providers/embeddings"; - /// Creates the adapter over a client the caller builds, embedding through the port. - internal QdrantKnowledgeAdapter(Func clientFactory) - { - ArgumentNullException.ThrowIfNull(clientFactory); + // The deadline of one gRPC call. The connector never sets one on its own. + private static readonly TimeSpan CallDeadline = TimeSpan.FromSeconds(30); - _clientFactory = clientFactory; - } + private readonly Func? _clientFactory; - /// Gets the one kind value this adapter serves. - public string Kind => ProviderKind; + private readonly IEmbeddingGenerator>? _embeddings; - /// Gets : a Qdrant collection is what ranks. - public bool CanServeSearch => true; + private IReadOnlyList _analyzers = [new NoQueryAnalyzer()]; - /// Gets : a facet filter narrows the query before it ranks. - public bool CanScope => true; + private IKnowledgePointMapper[] _mappers = []; - /// Replaces the analyzers providers.knowledge.analyzer may name. - public QdrantKnowledgeAdapter UseAnalyzers(params IKnowledgeQueryAnalyzer[] analyzers) - { - ArgumentNullException.ThrowIfNull(analyzers); + /// + /// Creates the adapter that embeds through the generator providers.embeddings builds. + /// + public QdrantKnowledgeAdapter() + { + } - _analyzers = analyzers; - return this; - } + /// Creates the adapter over a generator the caller builds. + public QdrantKnowledgeAdapter(IEmbeddingGenerator> embeddings) + { + ArgumentNullException.ThrowIfNull(embeddings); - /// Registers the mappers providers.knowledge.mapper may name. - public QdrantKnowledgeAdapter UseMappers(params IKnowledgePointMapper[] mappers) - { - ArgumentNullException.ThrowIfNull(mappers); + _embeddings = embeddings; + } - _mappers = mappers; - return this; - } + /// Creates the adapter over a client the caller builds. + internal QdrantKnowledgeAdapter( + Func clientFactory, + IEmbeddingGenerator> embeddings) + { + ArgumentNullException.ThrowIfNull(clientFactory); + ArgumentNullException.ThrowIfNull(embeddings); - /// - public async ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); + _clientFactory = clientFactory; + _embeddings = embeddings; + } - var embedder = _embeddings ?? embeddings ?? throw Fail( - EmbeddingsPointer, - "providers.knowledge is kind: " + ProviderKind + ", which ranks by vector and needs an " - + "embedding generator. Write a providers.embeddings block, such as " - + "{ kind: openai, model: text-embedding-3-small }, or construct QdrantKnowledgeAdapter " - + "with a generator."); + /// Creates the adapter over a client the caller builds, embedding through the port. + internal QdrantKnowledgeAdapter(Func clientFactory) + { + ArgumentNullException.ThrowIfNull(clientFactory); - var analyzer = ResolveAnalyzer(entry.Analyzer); - var mapper = ResolveMapper(entry.Mapper); + _clientFactory = clientFactory; + } - AssertFieldsMapped(entry); - var linkNamespace = LinkNamespace(entry); + /// Gets the one kind value this adapter serves. + public string Kind => ProviderKind; - var client = _clientFactory is not null - ? _clientFactory(entry) - : await BuildClientAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + /// Gets : a Qdrant collection is what ranks. + public bool CanServeSearch => true; - try + /// Gets : a facet filter narrows the query before it ranks. + public bool CanScope => true; + + /// Replaces the analyzers providers.knowledge.analyzer may name. + public QdrantKnowledgeAdapter UseAnalyzers(params IKnowledgeQueryAnalyzer[] analyzers) { - await QdrantCollectionProof - .AssertAsync(client, entry, embedder, mapper, linkNamespace, cancellationToken) - .ConfigureAwait(false); - - return new QdrantKnowledgeStore( - new QdrantSearchChannel(client), - embedder, - new QdrantKnowledgeStoreOptions - { - Collection = entry.Collection, - Scoped = requireScope, - VectorName = entry.Vector, - Fields = entry.Fields, - ScopeTemplate = entry.Scope.Template, - ScopeWildcard = entry.Scope.Wildcard?.Value, - ScopeWildcardFacets = entry.Scope.Wildcard?.Facets ?? [], - Links = entry.Links, - LinkNamespace = linkNamespace, - Analyzer = analyzer, - Mapper = mapper, - ScoreFloor = entry.ScoreFloor, - Limit = AgentKnowledgeConfiguration.MaximumLimit, - }); + ArgumentNullException.ThrowIfNull(analyzers); + + _analyzers = analyzers; + return this; } - catch + + /// Registers the mappers providers.knowledge.mapper may name. + public QdrantKnowledgeAdapter UseMappers(params IKnowledgePointMapper[] mappers) { - client.Dispose(); - throw; + ArgumentNullException.ThrowIfNull(mappers); + + _mappers = mappers; + return this; } - } - /// Refuses a document whose fields: block cannot feed what the rest of it asks for. - private static void AssertFieldsMapped(KnowledgeProviderConfiguration entry) - { - if (entry.Mapper is null && entry.Fields?.Body is not { Length: > 0 }) + /// + public async ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) { - throw Fail( - "/providers/knowledge/fields/body", - "providers.knowledge names no mapper, so the built-in fields: mapping reads every " - + "card, and it maps no body. AgentCore has no default field names, so every card " - + "would reach the model empty. Map providers.knowledge.fields.body, or name an " - + "IKnowledgePointMapper with mapper:."); + ArgumentNullException.ThrowIfNull(entry); + + IEmbeddingGenerator> embedder = _embeddings ?? embeddings ?? throw Fail( + EmbeddingsPointer, + "providers.knowledge is kind: " + ProviderKind + ", which ranks by vector and needs an " + + "embedding generator. Write a providers.embeddings block, such as " + + "{ kind: openai, model: text-embedding-3-small }, or construct QdrantKnowledgeAdapter " + + "with a generator."); + + IKnowledgeQueryAnalyzer analyzer = ResolveAnalyzer(entry.Analyzer); + IKnowledgePointMapper? mapper = ResolveMapper(entry.Mapper); + + AssertFieldsMapped(entry); + Guid linkNamespace = LinkNamespace(entry); + + QdrantClient client = _clientFactory is not null + ? _clientFactory(entry) + : await BuildClientAsync(entry, secrets, cancellationToken).ConfigureAwait(false); + + try + { + await QdrantCollectionProof + .AssertAsync(client, entry, embedder, mapper, linkNamespace, cancellationToken) + .ConfigureAwait(false); + + return new QdrantKnowledgeStore( + new QdrantSearchChannel(client), + embedder, + new QdrantKnowledgeStoreOptions + { + Collection = entry.Collection, + Scoped = requireScope, + VectorName = entry.Vector, + Fields = entry.Fields, + ScopeTemplate = entry.Scope.Template, + ScopeWildcard = entry.Scope.Wildcard?.Value, + ScopeWildcardFacets = entry.Scope.Wildcard?.Facets ?? [], + Links = entry.Links, + LinkNamespace = linkNamespace, + Analyzer = analyzer, + Mapper = mapper, + ScoreFloor = entry.ScoreFloor, + Limit = AgentKnowledgeConfiguration.MaximumLimit, + }); + } + catch + { + client.Dispose(); + throw; + } } - if (entry.Links is not null && entry.Fields?.Id is not { Length: > 0 }) + /// Refuses a document whose fields: block cannot feed what the rest of it asks for. + private static void AssertFieldsMapped(KnowledgeProviderConfiguration entry) { - throw Fail( - "/providers/knowledge/fields/id", - "providers.knowledge.links is configured, and every links.lookup mode resolves a " - + "linked id through providers.knowledge.fields.id, which this document does not map. " - + "Map the id field, or remove the links block."); + if (entry.Mapper is null && entry.Fields?.Body is not { Length: > 0 }) + { + throw Fail( + "/providers/knowledge/fields/body", + "providers.knowledge names no mapper, so the built-in fields: mapping reads every " + + "card, and it maps no body. AgentCore has no default field names, so every card " + + "would reach the model empty. Map providers.knowledge.fields.body, or name an " + + "IKnowledgePointMapper with mapper:."); + } + + if (entry.Links is not null && entry.Fields?.Id is not { Length: > 0 }) + { + throw Fail( + "/providers/knowledge/fields/id", + "providers.knowledge.links is configured, and every links.lookup mode resolves a " + + "linked id through providers.knowledge.fields.id, which this document does not map. " + + "Map the id field, or remove the links block."); + } + + if (entry.Links is { } declaredLinks && declaredLinks.Field is not { Length: > 0 }) + { + throw Fail( + "/providers/knowledge/links/field", + "providers.knowledge.links is configured and names no field. AgentCore has no default " + + "link field: it cannot guess which payload key holds this collection's outbound ids. " + + "Write links.field, or remove the links block."); + } } - if (entry.Links is { } declaredLinks && declaredLinks.Field is not { Length: > 0 }) + /// The UUID5 namespace the links block names, or when links do not use one. + private static Guid LinkNamespace(KnowledgeProviderConfiguration entry) { - throw Fail( - "/providers/knowledge/links/field", - "providers.knowledge.links is configured and names no field. AgentCore has no default " - + "link field: it cannot guess which payload key holds this collection's outbound ids. " - + "Write links.field, or remove the links block."); + if (entry.Links is not { Lookup: KnowledgeLinkLookup.Uuid5 } uuid5Links) + { + return Guid.Empty; + } + + try + { + return Uuid5PointId.Namespace(uuid5Links.Namespace); + } + catch (FormatException) + { + throw Fail( + "/providers/knowledge/links/namespace", + $"providers.knowledge.links.namespace is '{uuid5Links.Namespace}', which is neither a " + + "known name (url, dns, oid, x500) nor a GUID."); + } } - } - /// The UUID5 namespace the links block names, or when links do not use one. - private static Guid LinkNamespace(KnowledgeProviderConfiguration entry) - { - if (entry.Links is not { Lookup: KnowledgeLinkLookup.Uuid5 } uuid5Links) + /// Picks the analyzer the document named. + /// No registered analyzer answers to that name. + private IKnowledgeQueryAnalyzer ResolveAnalyzer(string name) { - return Guid.Empty; + return _analyzers.FirstOrDefault(analyzer => string.Equals(analyzer.Name, name, StringComparison.Ordinal)) + ?? throw Fail( + "/providers/knowledge/analyzer", + $"providers.knowledge.analyzer is '{name}', and no registered IKnowledgeQueryAnalyzer " + + $"answers to it. This host registers {string.Join(", ", _analyzers.Select(a => $"'{a.Name}'"))}. " + + "Register one with QdrantKnowledgeAdapter.UseAnalyzers, or name one of those."); } - try + /// Picks the mapper the document named, or for the built-in fields: mapping. + /// No registered mapper answers to that name. + private IKnowledgePointMapper? ResolveMapper(string? name) { - return Uuid5PointId.Namespace(uuid5Links.Namespace); + if (name is not { Length: > 0 }) + { + return null; + } + + return _mappers.FirstOrDefault(mapper => string.Equals(mapper.Name, name, StringComparison.Ordinal)) + ?? throw Fail( + "/providers/knowledge/mapper", + $"providers.knowledge.mapper is '{name}', and no registered IKnowledgePointMapper " + + $"answers to it. This host registers " + + $"{(_mappers.Length == 0 ? "none" : string.Join(", ", _mappers.Select(m => $"'{m.Name}'")))}. " + + "Register one with QdrantKnowledgeAdapter.UseMappers, or drop the setting."); } - catch (FormatException) + + /// Parses the endpoint and resolves the API key, then builds the production client. + private static async ValueTask BuildClientAsync( + KnowledgeProviderConfiguration entry, ISecretResolverPort? secrets, CancellationToken cancellationToken) { - throw Fail( - "/providers/knowledge/links/namespace", - $"providers.knowledge.links.namespace is '{uuid5Links.Namespace}', which is neither a " - + "known name (url, dns, oid, x500) nor a GUID."); + Uri endpoint = Endpoint(entry); + string? apiKey = await secrets.TryReadAsync(KnownSecrets.Qdrant, cancellationToken).ConfigureAwait(false); + + return new QdrantClient(endpoint, apiKey, grpcTimeout: CallDeadline); } - } - /// Picks the analyzer the document named. - /// No registered analyzer answers to that name. - private IKnowledgeQueryAnalyzer ResolveAnalyzer(string name) - => _analyzers.FirstOrDefault(analyzer => string.Equals(analyzer.Name, name, StringComparison.Ordinal)) - ?? throw Fail( - "/providers/knowledge/analyzer", - $"providers.knowledge.analyzer is '{name}', and no registered IKnowledgeQueryAnalyzer " - + $"answers to it. This host registers {string.Join(", ", _analyzers.Select(a => $"'{a.Name}'"))}. " - + "Register one with QdrantKnowledgeAdapter.UseAnalyzers, or name one of those."); - - /// Picks the mapper the document named, or for the built-in fields: mapping. - /// No registered mapper answers to that name. - private IKnowledgePointMapper? ResolveMapper(string? name) - { - if (name is not { Length: > 0 }) + /// Reads the cluster URL out of the document. + private static Uri Endpoint(KnowledgeProviderConfiguration entry) { - return null; + if (entry.Endpoint is not { Length: > 0 } endpoint || string.IsNullOrWhiteSpace(endpoint)) + { + throw Fail( + EndpointPointer, + "providers.knowledge is kind: " + ProviderKind + ", and that store needs " + + "providers.knowledge.endpoint. Write the Qdrant cluster URL there, such as " + + "https://qdrant.example.com:6334."); + } + + return Uri.TryCreate(endpoint, UriKind.Absolute, out Uri? url) + ? url + : throw Fail( + EndpointPointer, + "providers.knowledge.endpoint is '" + endpoint + "', which is not an absolute URL. Write " + + "the Qdrant cluster URL, such as https://qdrant.example.com:6334."); } - return _mappers.FirstOrDefault(mapper => string.Equals(mapper.Name, name, StringComparison.Ordinal)) - ?? throw Fail( - "/providers/knowledge/mapper", - $"providers.knowledge.mapper is '{name}', and no registered IKnowledgePointMapper " - + $"answers to it. This host registers " - + $"{(_mappers.Length == 0 ? "none" : string.Join(", ", _mappers.Select(m => $"'{m.Name}'")))}. " - + "Register one with QdrantKnowledgeAdapter.UseMappers, or drop the setting."); - } - - /// Parses the endpoint and resolves the API key, then builds the production client. - private static async ValueTask BuildClientAsync( - KnowledgeProviderConfiguration entry, ISecretResolverPort? secrets, CancellationToken cancellationToken) - { - var endpoint = Endpoint(entry); - var apiKey = await secrets.TryReadAsync(KnownSecrets.Qdrant, cancellationToken).ConfigureAwait(false); - - return new QdrantClient(endpoint, apiKey, grpcTimeout: CallDeadline); - } - - /// Reads the cluster URL out of the document. - private static Uri Endpoint(KnowledgeProviderConfiguration entry) - { - if (entry.Endpoint is not { Length: > 0 } endpoint || string.IsNullOrWhiteSpace(endpoint)) + /// Builds the one exception every configuration failure of this adapter uses. + private static ConfigurationLoadException Fail(string pointer, string message) { - throw Fail( - EndpointPointer, - "providers.knowledge is kind: " + ProviderKind + ", and that store needs " - + "providers.knowledge.endpoint. Write the Qdrant cluster URL there, such as " - + "https://qdrant.example.com:6334."); + return new(new ConfigurationError + { + Pointer = pointer, + Message = message, + Check = ConfigurationCheck.ReferenceResolution, + }); } - - return Uri.TryCreate(endpoint, UriKind.Absolute, out var url) - ? url - : throw Fail( - EndpointPointer, - "providers.knowledge.endpoint is '" + endpoint + "', which is not an absolute URL. Write " - + "the Qdrant cluster URL, such as https://qdrant.example.com:6334."); } - - /// Builds the one exception every configuration failure of this adapter uses. - private static ConfigurationLoadException Fail(string pointer, string message) - => new(new ConfigurationError - { - Pointer = pointer, - Message = message, - Check = ConfigurationCheck.ReferenceResolution, - }); -} \ No newline at end of file +} diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs index dffd31cb..eb91ea5d 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs @@ -7,331 +7,340 @@ using Microsoft.Extensions.AI; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// -/// The whole knowledge base over one Qdrant collection. -/// -internal sealed class QdrantKnowledgeStore - : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort, IDisposable +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - private readonly IQdrantSearchChannel _channel; - private readonly IEmbeddingGenerator> _embeddings; - private readonly QdrantKnowledgeStoreOptions _options; - private readonly IKnowledgePointMapper _mapper; - private readonly QdrantScopeMatcher _scope; - - /// Binds one channel, one embedder and one collection. - public QdrantKnowledgeStore( - IQdrantSearchChannel channel, - IEmbeddingGenerator> embeddings, - QdrantKnowledgeStoreOptions options) - { - ArgumentNullException.ThrowIfNull(channel); - ArgumentNullException.ThrowIfNull(embeddings); - ArgumentNullException.ThrowIfNull(options); - - _channel = channel; - _embeddings = embeddings; - _options = options; - _scope = new QdrantScopeMatcher(options, ScopeTemplate.Parse(options.ScopeTemplate)); - // A links block with no field names no payload key to read outbound ids from. The adapter - // rejects that in the document; this rejects it for a store built in code, where the - // alternative is a null dereference on the first search that ranks anything. - if (options.Links is { } links && links.Field is not { Length: > 0 }) - { - throw new ArgumentException( - "these options carry a links block that names no field, so there is no payload key to " - + "read outbound ids from. AgentCore has no default link field; name one, or leave " - + "Links null to turn link expansion off.", - nameof(options)); - } - - // Every lookup mode resolves a linked id through the mapped id field: filter matches on it, - // and uuid5 and direct derive the key from it. Unmapped, the filter path used to reach - // protobuf with a null key and die there with nothing about the document in the message. - if (options.Links is not null && options.Fields?.Id is not { Length: > 0 }) - { - throw new ArgumentException( - "these options carry a links block and map no fields.id. Every links.lookup mode " - + "resolves a linked id through that field, so no link could ever be followed. Map " - + "the id field, or leave Links null to turn link expansion off.", - nameof(options)); - } - - _mapper = options.Mapper - ?? (options.Fields is { Body.Length: > 0 } fields - ? new FieldsPointMapper(fields) - : throw new ArgumentException( - "these options name neither a mapper nor a fields.body, so no point could be read " - + "into a card and every turn would see an empty knowledge base. AgentCore has no " - + "default field names; set one of the two.", - nameof(options))); - } - /// - /// Closes the channel, when it owns something closeable. + /// The whole knowledge base over one Qdrant collection. /// - public void Dispose() => (_channel as IDisposable)?.Dispose(); - - /// Refuses an unscoped search when this deployment scopes every query. - /// The scope the search arrived with, or for none. - /// The search is unscoped, or its scope names no facets. - private void RequireScope(KnowledgeScope? scope) + internal sealed class QdrantKnowledgeStore + : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort, IDisposable { - if (!_options.Scoped) + private readonly IQdrantSearchChannel _channel; + private readonly IEmbeddingGenerator> _embeddings; + private readonly QdrantKnowledgeStoreOptions _options; + private readonly IKnowledgePointMapper _mapper; + private readonly QdrantScopeMatcher _scope; + + /// Binds one channel, one embedder and one collection. + public QdrantKnowledgeStore( + IQdrantSearchChannel channel, + IEmbeddingGenerator> embeddings, + QdrantKnowledgeStoreOptions options) { - return; + ArgumentNullException.ThrowIfNull(channel); + ArgumentNullException.ThrowIfNull(embeddings); + ArgumentNullException.ThrowIfNull(options); + + _channel = channel; + _embeddings = embeddings; + _options = options; + _scope = new QdrantScopeMatcher(options, ScopeTemplate.Parse(options.ScopeTemplate)); + // A links block with no field names no payload key to read outbound ids from. The adapter + // rejects that in the document; this rejects it for a store built in code, where the + // alternative is a null dereference on the first search that ranks anything. + if (options.Links is { } links && links.Field is not { Length: > 0 }) + { + throw new ArgumentException( + "these options carry a links block that names no field, so there is no payload key to " + + "read outbound ids from. AgentCore has no default link field; name one, or leave " + + "Links null to turn link expansion off.", + nameof(options)); + } + + // Every lookup mode resolves a linked id through the mapped id field: filter matches on it, + // and uuid5 and direct derive the key from it. Unmapped, the filter path used to reach + // protobuf with a null key and die there with nothing about the document in the message. + if (options.Links is not null && options.Fields?.Id is not { Length: > 0 }) + { + throw new ArgumentException( + "these options carry a links block and map no fields.id. Every links.lookup mode " + + "resolves a linked id through that field, so no link could ever be followed. Map " + + "the id field, or leave Links null to turn link expansion off.", + nameof(options)); + } + + _mapper = options.Mapper + ?? (options.Fields is { Body.Length: > 0 } fields + ? new FieldsPointMapper(fields) + : throw new ArgumentException( + "these options name neither a mapper nor a fields.body, so no point could be read " + + "into a card and every turn would see an empty knowledge base. AgentCore has no " + + "default field names; set one of the two.", + nameof(options))); } - // Two different host bugs, so two different messages. An empty facet map filters - // nothing, which is the same leak as no scope at all: a host that reads a customer - // record with no product on it builds one without noticing. - if (scope is null) + /// + /// Closes the channel, when it owns something closeable. + /// + public void Dispose() { - throw new InvalidOperationException( - "This deployment declares scoped: true and the search arrived without a KnowledgeScope. " - + "An unscoped search serves every customer every card, so it fails instead. Pass the " - + "scope to SearchAsync, or set scoped: false on the agent."); + (_channel as IDisposable)?.Dispose(); } - if (scope.Facets.Count == 0) + /// Refuses an unscoped search when this deployment scopes every query. + /// The scope the search arrived with, or for none. + /// The search is unscoped, or its scope names no facets. + private void RequireScope(KnowledgeScope? scope) { - throw new InvalidOperationException( - "This deployment declares scoped: true and the open KnowledgeScope names no facets. " - + "An empty facet map filters nothing, so the search would serve every customer every " - + "card, and it fails instead. Give the scope the facets the customer record names, " - + "or set scoped: false on the agent."); + if (!_options.Scoped) + { + return; + } + + // Two different host bugs, so two different messages. An empty facet map filters + // nothing, which is the same leak as no scope at all: a host that reads a customer + // record with no product on it builds one without noticing. + if (scope is null) + { + throw new InvalidOperationException( + "This deployment declares scoped: true and the search arrived without a KnowledgeScope. " + + "An unscoped search serves every customer every card, so it fails instead. Pass the " + + "scope to SearchAsync, or set scoped: false on the agent."); + } + + if (scope.Facets.Count == 0) + { + throw new InvalidOperationException( + "This deployment declares scoped: true and the open KnowledgeScope names no facets. " + + "An empty facet map filters nothing, so the search would serve every customer every " + + "card, and it fails instead. Give the scope the facets the customer record names, " + + "or set scoped: false on the agent."); + } } - } - public async ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(query); + public async ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(query); - RequireScope(scope); + RequireScope(scope); - using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - deadline.CancelAfter(_options.Deadline); + using CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + deadline.CancelAfter(_options.Deadline); - var embedding = await _embeddings - .GenerateAsync(query, cancellationToken: deadline.Token).ConfigureAwait(false); + Embedding embedding = await _embeddings + .GenerateAsync(query, cancellationToken: deadline.Token).ConfigureAwait(false); - var points = await _channel - .QueryAsync(BuildQuery(query, embedding.Vector, scope), deadline.Token).ConfigureAwait(false); + IReadOnlyList points = await _channel + .QueryAsync(BuildQuery(query, embedding.Vector, scope), deadline.Token).ConfigureAwait(false); - List cards = []; + List cards = []; - foreach (var point in points) - { - if (Map(point.Id, point.Payload, point.Score, viaLink: false) is { } card) + foreach (ScoredPoint point in points) { - cards.Add(card); + if (Map(point.Id, point.Payload, point.Score, viaLink: false) is { } card) + { + cards.Add(card); + } } - } - if (points.Count == 0 || _options.Links is not { } linksConfiguration) - { - return cards; - } + if (points.Count == 0 || _options.Links is not { } linksConfiguration) + { + return cards; + } - var have = cards.Select(card => card.CardId).ToHashSet(StringComparer.Ordinal); + HashSet have = cards.Select(card => card.CardId).ToHashSet(StringComparer.Ordinal); - // The adapter refuses a links block that names no field, so this is never null here. - var links = QdrantPayload.ReadList(points[0].Payload, linksConfiguration.Field!) - .Where(id => !have.Contains(id)) - .Distinct(StringComparer.Ordinal) - .ToList(); + // The adapter refuses a links block that names no field, so this is never null here. + List links = [.. QdrantPayload.ReadList(points[0].Payload, linksConfiguration.Field!) + .Where(id => !have.Contains(id)) + .Distinct(StringComparer.Ordinal)]; - if (links.Count > 0) - { - var linked = await FetchLinkedAsync(linksConfiguration, links, deadline.Token).ConfigureAwait(false); - - foreach (var point in linked) + if (links.Count > 0) { - if (_scope.Matches(point.Payload, scope) - && Map(point.Id, point.Payload, score: null, viaLink: true) is { } card) + IReadOnlyList linked = await FetchLinkedAsync(linksConfiguration, links, deadline.Token).ConfigureAwait(false); + + foreach (RetrievedPoint point in linked) { - cards.Add(card); + if (_scope.Matches(point.Payload, scope) + && Map(point.Id, point.Payload, score: null, viaLink: true) is { } card) + { + cards.Add(card); + } } } - } - - return cards; - } - /// - /// - /// The value is matched exactly, and never widened by scope.wildcard the way a scoped - /// search widens one. A caller asking for the cards of one model year wants that year, not that - /// year plus every card shared across all of them. - /// - public async ValueTask> ReadByFacetAsync( - string path, string value, int limit, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(path); - ArgumentNullException.ThrowIfNull(value); - ArgumentOutOfRangeException.ThrowIfNegative(limit); + return cards; + } - var filter = new Filter(); - filter.Must.Add(new Condition + /// + /// + /// The value is matched exactly, and never widened by scope.wildcard the way a scoped + /// search widens one. A caller asking for the cards of one model year wants that year, not that + /// year plus every card shared across all of them. + /// + public async ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) { - Field = new FieldCondition { Key = path, Match = new Match { Keyword = value } }, - }); + ArgumentNullException.ThrowIfNull(path); + ArgumentNullException.ThrowIfNull(value); + ArgumentOutOfRangeException.ThrowIfNegative(limit); - var points = await _channel - .ScrollAsync(_options.Collection, filter, (uint)limit, cancellationToken) - .ConfigureAwait(false); + Filter filter = new(); + filter.Must.Add(new Condition + { + Field = new FieldCondition { Key = path, Match = new Match { Keyword = value } }, + }); - // A scroll carries no vector, so no score floor applies and every point that matched is a - // card. Score stays null: nothing ranked these. - List cards = []; - foreach (var point in points) - { - if (Map(point.Id, point.Payload, score: null, viaLink: false) is { } card) + IReadOnlyList points = await _channel + .ScrollAsync(_options.Collection, filter, (uint)limit, cancellationToken) + .ConfigureAwait(false); + + // A scroll carries no vector, so no score floor applies and every point that matched is a + // card. Score stays null: nothing ranked these. + List cards = []; + foreach (RetrievedPoint point in points) { - cards.Add(card); + if (Map(point.Id, point.Payload, score: null, viaLink: false) is { } card) + { + cards.Add(card); + } } - } - return cards; - } + return cards; + } - private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, KnowledgeScope? scope) - { - var scopeFilter = new Filter(); - foreach (var (facet, value) in QdrantScopeMatcher.Facets(scope)) + private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, KnowledgeScope? scope) { - scopeFilter.Must.Add(new Condition + Filter scopeFilter = new(); + foreach ((string? facet, string? value) in QdrantScopeMatcher.Facets(scope)) { - // Whatever scope.template produced, verbatim. A dotted path walks into a nested - // struct; a flat key does not. Getting that wrong matches nothing at all, silently, - // which is why the template is the deployment's to write and never AgentCore's to - // guess. - Field = new FieldCondition { Key = _scope.Path(facet), Match = _scope.MatchFor(facet, value) }, - }); - } + scopeFilter.Must.Add(new Condition + { + // Whatever scope.template produced, verbatim. A dotted path walks into a nested + // struct; a flat key does not. Getting that wrong matches nothing at all, silently, + // which is why the template is the deployment's to write and never AgentCore's to + // guess. + Field = new FieldCondition { Key = _scope.Path(facet), Match = _scope.MatchFor(facet, value) }, + }); + } - // The prefetch depth scales with the limit. Hardcoding it caps the fused result far below - // what the caller asked for, and the shortfall is silent. - var depth = (ulong)Math.Max(_options.Limit * 2, 20); + // The prefetch depth scales with the limit. Hardcoding it caps the fused result far below + // what the caller asked for, and the shortfall is silent. + ulong depth = (ulong)Math.Max(_options.Limit * 2, 20); - var prefetch = new List { Dense(vector, scopeFilter.Clone(), depth) }; + List prefetch = [Dense(vector, scopeFilter.Clone(), depth)]; - if (_options.Fields?.Lexical is { Length: > 0 } lexical) - { - var identifiers = _options.Analyzer.RequiredTerms(query); - if (identifiers.Count > 0) + if (_options.Fields?.Lexical is { Length: > 0 } lexical) { - var identifierFilter = scopeFilter.Clone(); - foreach (var token in identifiers) + IReadOnlyList identifiers = _options.Analyzer.RequiredTerms(query); + if (identifiers.Count > 0) { - // Must, never a nested Should. Under Should a card holding any one identifier is - // lifted in, which is the semantics measured to rank by storage order. - identifierFilter.Must.Add(new Condition + Filter identifierFilter = scopeFilter.Clone(); + foreach (string token in identifiers) { - Field = new FieldCondition { Key = lexical, Match = new Match { Text = token } }, - }); + // Must, never a nested Should. Under Should a card holding any one identifier is + // lifted in, which is the semantics measured to rank by storage order. + identifierFilter.Must.Add(new Condition + { + Field = new FieldCondition { Key = lexical, Match = new Match { Text = token } }, + }); + } + + prefetch.Add(Dense(vector, identifierFilter, depth)); } - - prefetch.Add(Dense(vector, identifierFilter, depth)); } - } - // One leg has nothing to fuse, and fusing it anyway replaces every score with 1/(rank+1). - // Re-scoring the prefetch with the same vector keeps a card's score a similarity, on the - // scale the floor was written in. - // Qdrant refuses "using" beside a fusion — the legs already name their vectors — so the - // name rides the top level only when the top level is itself a nearest query. - return prefetch.Count == 1 - ? new SearchQuery( - _options.Collection, - prefetch, - new Query { Nearest = new VectorInput { Dense = new DenseVector { Data = { vector.ToArray() } } } }, - (ulong)_options.Limit, - VectorName) - : new SearchQuery(_options.Collection, prefetch, new Query { Fusion = Fusion.Rrf }, (ulong)_options.Limit); - } + // One leg has nothing to fuse, and fusing it anyway replaces every score with 1/(rank+1). + // Re-scoring the prefetch with the same vector keeps a card's score a similarity, on the + // scale the floor was written in. + // Qdrant refuses "using" beside a fusion — the legs already name their vectors — so the + // name rides the top level only when the top level is itself a nearest query. + return prefetch.Count == 1 + ? new SearchQuery( + _options.Collection, + prefetch, + new Query { Nearest = new VectorInput { Dense = new DenseVector { Data = { vector.ToArray() } } } }, + (ulong)_options.Limit, + VectorName) + : new SearchQuery(_options.Collection, prefetch, new Query { Fusion = Fusion.Rrf }, (ulong)_options.Limit); + } - private PrefetchQuery Dense(ReadOnlyMemory vector, Filter filter, ulong depth) - { - var leg = new PrefetchQuery + private PrefetchQuery Dense(ReadOnlyMemory vector, Filter filter, ulong depth) { - Filter = filter, - Limit = depth, - Query = new Query + PrefetchQuery leg = new() { - Nearest = new VectorInput { Dense = new DenseVector { Data = { vector.ToArray() } } }, - }, - }; - - // The floor belongs here, on the leg, where the score is still a cosine similarity. Applying - // it to what comes back is a different cut whenever the legs were fused: RRF replaces every - // score with 1/(rank+1), so a floor on that number is a fixed rank cut whatever was asked. - // - // A floor of 0 means no floor: every cosine similarity is >= 0, so a threshold of 0 would - // never cut anything, but it would still ride the wire and show up in a captured query. - if (_options.ScoreFloor > 0) - { - leg.ScoreThreshold = (float)_options.ScoreFloor; - } + Filter = filter, + Limit = depth, + Query = new Query + { + Nearest = new VectorInput { Dense = new DenseVector { Data = { vector.ToArray() } } }, + }, + }; + + // The floor belongs here, on the leg, where the score is still a cosine similarity. Applying + // it to what comes back is a different cut whenever the legs were fused: RRF replaces every + // score with 1/(rank+1), so a floor on that number is a fixed rank cut whatever was asked. + // + // A floor of 0 means no floor: every cosine similarity is >= 0, so a threshold of 0 would + // never cut anything, but it would still ride the wire and show up in a captured query. + if (_options.ScoreFloor > 0) + { + leg.ScoreThreshold = (float)_options.ScoreFloor; + } - // "using" left unset queries the collection's anonymous vector; protobuf refuses null. - if (VectorName is { } name) - { - leg.Using = name; - } + // "using" left unset queries the collection's anonymous vector; protobuf refuses null. + if (VectorName is { } name) + { + leg.Using = name; + } - return leg; - } + return leg; + } - /// - /// The named vector every query scores with, or for the collection's - /// anonymous vector. An unset name and a blank one mean the same collection shape, and the - /// prefetch leg and the top-level query have to agree on which. - /// - private string? VectorName => _options.VectorName is { Length: > 0 } name ? name : null; + /// + /// The named vector every query scores with, or for the collection's + /// anonymous vector. An unset name and a blank one mean the same collection shape, and the + /// prefetch leg and the top-level query have to agree on which. + /// + private string? VectorName => _options.VectorName is { Length: > 0 } name ? name : null; - /// Fetches the cards a link named, under this deployment's lookup mode. - private Task> FetchLinkedAsync( - KnowledgeLinksConfiguration links, List ids, CancellationToken cancellationToken) - { - if (links.Lookup == KnowledgeLinkLookup.Filter) + /// Fetches the cards a link named, under this deployment's lookup mode. + private Task> FetchLinkedAsync( + KnowledgeLinksConfiguration links, List ids, CancellationToken cancellationToken) { - var filter = new Filter(); - filter.Must.Add(new Condition + if (links.Lookup == KnowledgeLinkLookup.Filter) { - // The adapter refuses a links block without a mapped id, so this is never null here. - Field = new FieldCondition + Filter filter = new(); + filter.Must.Add(new Condition { - Key = _options.Fields!.Id!, - Match = new Match { Keywords = new RepeatedStrings { Strings = { ids } } }, - }, - }); + // The adapter refuses a links block without a mapped id, so this is never null here. + Field = new FieldCondition + { + Key = _options.Fields!.Id!, + Match = new Match { Keywords = new RepeatedStrings { Strings = { ids } } }, + }, + }); + + return _channel.ScrollAsync(_options.Collection, filter, (uint)ids.Count, cancellationToken); + } - return _channel.ScrollAsync(_options.Collection, filter, (uint)ids.Count, cancellationToken); + return _channel.RetrieveAsync(_options.Collection, [.. ids.Select(id => PointKey(links, id))], cancellationToken); } - return _channel.RetrieveAsync(_options.Collection, [.. ids.Select(id => PointKey(links, id))], cancellationToken); - } + /// Turns one card id into the point key that holds it. + private Guid PointKey(KnowledgeLinksConfiguration links, string cardId) + { + return links.Lookup switch + { + KnowledgeLinkLookup.Direct => Guid.TryParse(cardId, out Guid id) + ? id + : throw new InvalidOperationException( + $"links.lookup is direct and the card id '{cardId}' is not a GUID. Qdrant's point key " + + "is a GUID or an unsigned integer, so a free-form id cannot be one. Use " + + "links.lookup: filter to match on the id field instead."), + KnowledgeLinkLookup.Uuid5 => Uuid5PointId.For(cardId, _options.LinkNamespace, links.Prefix), + KnowledgeLinkLookup.Filter => throw new InvalidOperationException( + "links.lookup is filter, which scrolls on the id field and never builds a point key."), + _ => throw new ArgumentOutOfRangeException(nameof(links), links.Lookup, "The link lookup vocabulary is closed, and this value is not in it."), + }; + } - /// Turns one card id into the point key that holds it. - private Guid PointKey(KnowledgeLinksConfiguration links, string cardId) => links.Lookup switch - { - KnowledgeLinkLookup.Direct => Guid.TryParse(cardId, out var id) - ? id - : throw new InvalidOperationException( - $"links.lookup is direct and the card id '{cardId}' is not a GUID. Qdrant's point key " - + "is a GUID or an unsigned integer, so a free-form id cannot be one. Use " - + "links.lookup: filter to match on the id field instead."), - _ => Uuid5PointId.For(cardId, _options.LinkNamespace, links.Prefix), - }; - - /// Maps one point, letting the mapper skip it, then stamps how it arrived. - private KnowledgeCard? Map(PointId id, MapField payload, double? score, bool viaLink) - { - var card = _mapper.Map(QdrantPointConverter.ToPoint(id, payload, score)); - return card is null ? null : card with { Score = score, ViaLink = viaLink }; + /// Maps one point, letting the mapper skip it, then stamps how it arrived. + private KnowledgeCard? Map(PointId id, MapField payload, double? score, bool viaLink) + { + KnowledgeCard? card = _mapper.Map(QdrantPointConverter.ToPoint(id, payload, score)); + return card is null ? null : card with { Score = score, ViaLink = viaLink }; + } } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs index 44a74736..44412790 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs @@ -1,57 +1,58 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// What one bound store reads. The document sets these once, at startup. -internal sealed record QdrantKnowledgeStoreOptions +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - /// Gets the collection to read. Always the alias. - public required string Collection { get; init; } + /// What one bound store reads. The document sets these once, at startup. + internal sealed record QdrantKnowledgeStoreOptions + { + /// Gets the collection to read. Always the alias. + public required string Collection { get; init; } - /// Gets whether this deployment confines searches to a scope. - public required bool Scoped { get; init; } + /// Gets whether this deployment confines searches to a scope. + public required bool Scoped { get; init; } - /// Gets the vector name every query searches, or for the single anonymous vector. - public string? VectorName { get; init; } + /// Gets the vector name every query searches, or for the single anonymous vector. + public string? VectorName { get; init; } - /// Gets how a card's payload is named, or when a mapper owns the shape. - public KnowledgeFieldsConfiguration? Fields { get; init; } + /// Gets how a card's payload is named, or when a mapper owns the shape. + public KnowledgeFieldsConfiguration? Fields { get; init; } - /// Gets what turns one point into a card, or for the fields: mapping. - public IKnowledgePointMapper? Mapper { get; init; } + /// Gets what turns one point into a card, or for the fields: mapping. + public IKnowledgePointMapper? Mapper { get; init; } - /// - /// Gets the payload path each facet key becomes, with {key} for the key, or - /// when the document names none. There is no default: a template is a - /// claim about one collection's layout, and an unscoped deployment never needs one. - /// - public string? ScopeTemplate { get; init; } + /// + /// Gets the payload path each facet key becomes, with {key} for the key, or + /// when the document names none. There is no default: a template is a + /// claim about one collection's layout, and an unscoped deployment never needs one. + /// + public string? ScopeTemplate { get; init; } - /// Gets the payload value that satisfies any scope on a named facet, or null for exact match. - public string? ScopeWildcard { get; init; } + /// Gets the payload value that satisfies any scope on a named facet, or null for exact match. + public string? ScopeWildcard { get; init; } - /// Gets the facet keys the wildcard widens. Every other facet stays exact match. - public IReadOnlyList ScopeWildcardFacets { get; init; } = []; + /// Gets the facet keys the wildcard widens. Every other facet stays exact match. + public IReadOnlyList ScopeWildcardFacets { get; init; } = []; - /// Gets how links between cards are read and followed, or for no expansion. - public KnowledgeLinksConfiguration? Links { get; init; } + /// Gets how links between cards are read and followed, or for no expansion. + public KnowledgeLinksConfiguration? Links { get; init; } - /// Gets the uuid5 namespace, already resolved from . - public Guid LinkNamespace { get; init; } = Uuid5PointId.Namespace(KnowledgeLinksConfiguration.DefaultNamespace); + /// Gets the uuid5 namespace, already resolved from . + public Guid LinkNamespace { get; init; } = Uuid5PointId.Namespace(KnowledgeLinksConfiguration.DefaultNamespace); - /// Gets what picks the terms a result must contain. - public IKnowledgeQueryAnalyzer Analyzer { get; init; } = new NoQueryAnalyzer(); + /// Gets what picks the terms a result must contain. + public IKnowledgeQueryAnalyzer Analyzer { get; init; } = new NoQueryAnalyzer(); - /// Gets how many fused results to return. This is the deployment's ceiling, not an agent's. - public int Limit { get; init; } = 5; + /// Gets how many fused results to return. This is the deployment's ceiling, not an agent's. + public int Limit { get; init; } = 5; - /// - /// Gets the cosine similarity a card must score strictly above, in the range 0 to 1. Applied on - /// the dense prefetch as Qdrant's score_threshold, never to a fused score. 0 disables the floor. - /// - public double ScoreFloor { get; init; } = KnowledgeProviderConfiguration.DefaultScoreFloor; + /// + /// Gets the cosine similarity a card must score strictly above, in the range 0 to 1. Applied on + /// the dense prefetch as Qdrant's score_threshold, never to a fused score. 0 disables the floor. + /// + public double ScoreFloor { get; init; } = KnowledgeProviderConfiguration.DefaultScoreFloor; - /// Gets how long a search may take before it is abandoned. - public TimeSpan Deadline { get; init; } = TimeSpan.FromSeconds(10); + /// Gets how long a search may take before it is abandoned. + public TimeSpan Deadline { get; init; } = TimeSpan.FromSeconds(10); + } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPayload.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPayload.cs index f1e0ba53..20d76ba8 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPayload.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPayload.cs @@ -1,38 +1,43 @@ using Google.Protobuf.Collections; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// Reads a field out of one point's payload, walking a dotted path into nested structs. -/// Every path it walks comes from the document. This class knows no field name of its own. -internal static class QdrantPayload +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - /// Walks a dotted path into a nested payload struct. - public static Value? Read(MapField payload, string path) + /// Reads a field out of one point's payload, walking a dotted path into nested structs. + /// Every path it walks comes from the document. This class knows no field name of its own. + internal static class QdrantPayload { - Value? current = null; - var fields = payload; - - foreach (var part in path.Split('.')) + /// Walks a dotted path into a nested payload struct. + public static Value? Read(MapField payload, string path) { - if (fields is null || !fields.TryGetValue(part, out current)) + Value? current = null; + MapField? fields = payload; + + foreach (string part in path.Split('.')) { - return null; + if (fields is null || !fields.TryGetValue(part, out current)) + { + return null; + } + + fields = current.KindCase == Value.KindOneofCase.StructValue ? current.StructValue.Fields : null; } - fields = current.KindCase == Value.KindOneofCase.StructValue ? current.StructValue.Fields : null; + return current; } - return current; - } - - /// Reads a dotted path as a string, or empty when it is missing or not a string. - public static string ReadString(MapField payload, string path) => - Read(payload, path)?.StringValue ?? string.Empty; + /// Reads a dotted path as a string, or empty when it is missing or not a string. + public static string ReadString(MapField payload, string path) + { + return Read(payload, path)?.StringValue ?? string.Empty; + } - /// Reads a dotted path as a list of strings, or empty when it is missing or not a list. - public static List ReadList(MapField payload, string path) => - Read(payload, path) is { KindCase: Value.KindOneofCase.ListValue } value - ? [.. value.ListValue.Values.Select(item => item.StringValue)] - : []; + /// Reads a dotted path as a list of strings, or empty when it is missing or not a list. + public static List ReadList(MapField payload, string path) + { + return Read(payload, path) is { KindCase: Value.KindOneofCase.ListValue } value + ? [.. value.ListValue.Values.Select(item => item.StringValue)] + : []; + } + } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPointConverter.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPointConverter.cs index 32f9eff4..43336085 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPointConverter.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantPointConverter.cs @@ -3,31 +3,41 @@ using Google.Protobuf.Collections; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// Reads one wire point into the vendor-free . -internal static class QdrantPointConverter +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - public static KnowledgePoint ToPoint(PointId id, MapField payload, double? score) => new() + /// Reads one wire point into the vendor-free . + internal static class QdrantPointConverter { - PointId = id.PointIdOptionsCase == PointId.PointIdOptionsOneofCase.Uuid - ? id.Uuid - : id.Num.ToString(CultureInfo.InvariantCulture), - Score = score, - Payload = Convert(payload), - }; + public static KnowledgePoint ToPoint(PointId id, MapField payload, double? score) + { + return new() + { + PointId = id.PointIdOptionsCase == PointId.PointIdOptionsOneofCase.Uuid + ? id.Uuid + : id.Num.ToString(CultureInfo.InvariantCulture), + Score = score, + Payload = Convert(payload), + }; + } - private static Dictionary Convert(MapField fields) - => fields.ToDictionary(entry => entry.Key, entry => Convert(entry.Value), StringComparer.Ordinal); + private static Dictionary Convert(MapField fields) + { + return fields.ToDictionary(entry => entry.Key, entry => Convert(entry.Value), StringComparer.Ordinal); + } - private static object? Convert(Value value) => value.KindCase switch - { - Value.KindOneofCase.StringValue => value.StringValue, - Value.KindOneofCase.IntegerValue => value.IntegerValue, - Value.KindOneofCase.DoubleValue => value.DoubleValue, - Value.KindOneofCase.BoolValue => value.BoolValue, - Value.KindOneofCase.StructValue => Convert(value.StructValue.Fields), - Value.KindOneofCase.ListValue => (IReadOnlyList)[.. value.ListValue.Values.Select(Convert)], - _ => null, - }; + private static object? Convert(Value value) + { + return value.KindCase switch + { + Value.KindOneofCase.StringValue => value.StringValue, + Value.KindOneofCase.IntegerValue => value.IntegerValue, + Value.KindOneofCase.DoubleValue => value.DoubleValue, + Value.KindOneofCase.BoolValue => value.BoolValue, + Value.KindOneofCase.StructValue => Convert(value.StructValue.Fields), + Value.KindOneofCase.ListValue => (IReadOnlyList)[.. value.ListValue.Values.Select(Convert)], + Value.KindOneofCase.NullValue or Value.KindOneofCase.None => null, + _ => null, + }; + } + } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs index ffc9a573..d6fb9574 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs @@ -5,91 +5,98 @@ using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// -/// What a means against one collection's payload. -/// -/// -/// One scope is asked two different ways, and both have to agree. A search sends Qdrant a filter, -/// and Qdrant decides. A card fetched by a see_also link never passes that filter, so the -/// same decision is made here, in process, against the payload. Splitting those two readings apart -/// is how a linked card ends up in an answer the scope should have kept out. -/// -/// The store's options, for the wildcard value and the facets it covers. -/// -/// The parsed scope.template, or when the document names none. -/// -internal sealed class QdrantScopeMatcher(QdrantKnowledgeStoreOptions options, ScopeTemplate? template) +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - /// The facets one scope names, in a fixed order. - /// The turn's scope, or when nothing is scoped. - /// The facets, by key, ordinally ordered so one scope always builds one filter. - public static IEnumerable> Facets(KnowledgeScope? scope) => - scope is null ? [] : scope.Facets.OrderBy(entry => entry.Key, StringComparer.Ordinal); - - /// Turns one facet key into the payload path this collection keeps it at. - /// The facet key, as a scope names it. - /// The payload path. - /// - /// Only reached once a scope names a facet, which is why an unset template is an error here and - /// not at startup: a deployment whose agents never scope legitimately names no template. - /// - /// No scope.template was configured. - public string Path(string facet) - => template is { } resolved - ? resolved.Resolve(facet) - : throw new InvalidOperationException( - $"a KnowledgeScope names the facet '{facet}' and providers.knowledge.scope.template is " - + "unset, so AgentCore does not know what payload path that key becomes. " - + ScopeTemplate.WriteOneAdvice); - - /// Builds the match one facet condition carries. - /// The facet key. - /// The value the turn's scope holds for it. - /// The match message. + /// + /// What a means against one collection's payload. + /// /// - /// Keyword and Keywords are different oneof cases, so a single-value Keywords list is a - /// different message from today's. A deployment that configures no wildcard has to emit the - /// message it emits now, or every stored query plan and every filter assertion changes under it. + /// One scope is asked two different ways, and both have to agree. A search sends Qdrant a filter, + /// and Qdrant decides. A card fetched by a see_also link never passes that filter, so the + /// same decision is made here, in process, against the payload. Splitting those two readings apart + /// is how a linked card ends up in an answer the scope should have kept out. /// - public Match MatchFor(string facet, string value) + /// The store's options, for the wildcard value and the facets it covers. + /// + /// The parsed scope.template, or when the document names none. + /// + internal sealed class QdrantScopeMatcher(QdrantKnowledgeStoreOptions options, ScopeTemplate? template) { - var values = Values(facet, value); + /// The facets one scope names, in a fixed order. + /// The turn's scope, or when nothing is scoped. + /// The facets, by key, ordinally ordered so one scope always builds one filter. + public static IEnumerable> Facets(KnowledgeScope? scope) + { + return scope is null ? [] : scope.Facets.OrderBy(entry => entry.Key, StringComparer.Ordinal); + } - return values.Count == 1 - ? new Match { Keyword = values[0] } - : new Match { Keywords = new RepeatedStrings { Strings = { values } } }; - } + /// Turns one facet key into the payload path this collection keeps it at. + /// The facet key, as a scope names it. + /// The payload path. + /// + /// Only reached once a scope names a facet, which is why an unset template is an error here and + /// not at startup: a deployment whose agents never scope legitimately names no template. + /// + /// No scope.template was configured. + public string Path(string facet) + { + return template is { } resolved + ? resolved.Resolve(facet) + : throw new InvalidOperationException( + $"a KnowledgeScope names the facet '{facet}' and providers.knowledge.scope.template is " + + "unset, so AgentCore does not know what payload path that key becomes. " + + ScopeTemplate.WriteOneAdvice); + } - /// Whether a card the ranking never chose is still inside the turn's scope. - /// The point's payload. - /// The turn's scope, or when nothing is scoped. - /// when every facet the scope names is satisfied. - public bool Matches(MapField payload, KnowledgeScope? scope) => - Facets(scope).All(entry => - Holds(QdrantPayload.Read(payload, Path(entry.Key)), Values(entry.Key, entry.Value))); + /// Builds the match one facet condition carries. + /// The facet key. + /// The value the turn's scope holds for it. + /// The match message. + /// + /// Keyword and Keywords are different oneof cases, so a single-value Keywords list is a + /// different message from today's. A deployment that configures no wildcard has to emit the + /// message it emits now, or every stored query plan and every filter assertion changes under it. + /// + public Match MatchFor(string facet, string value) + { + IReadOnlyList values = Values(facet, value); - /// The values one facet accepts: its own, and the wildcard when this facet is named. - private IReadOnlyList Values(string facet, string value) - { - if (options.ScopeWildcard is not { Length: > 0 } wildcard - || !options.ScopeWildcardFacets.Contains(facet, StringComparer.Ordinal) - || string.Equals(value, wildcard, StringComparison.Ordinal)) + return values.Count == 1 + ? new Match { Keyword = values[0] } + : new Match { Keywords = new RepeatedStrings { Strings = { values } } }; + } + + /// Whether a card the ranking never chose is still inside the turn's scope. + /// The point's payload. + /// The turn's scope, or when nothing is scoped. + /// when every facet the scope names is satisfied. + public bool Matches(MapField payload, KnowledgeScope? scope) { - return [value]; + return Facets(scope).All(entry => + Holds(QdrantPayload.Read(payload, Path(entry.Key)), Values(entry.Key, entry.Value))); } - return [.. new[] { value, wildcard }.Order(StringComparer.Ordinal)]; - } + /// The values one facet accepts: its own, and the wildcard when this facet is named. + private IReadOnlyList Values(string facet, string value) + { + return options.ScopeWildcard is not { Length: > 0 } wildcard + || !options.ScopeWildcardFacets.Contains(facet, StringComparer.Ordinal) + || string.Equals(value, wildcard, StringComparison.Ordinal) + ? [value] + : (IReadOnlyList)[.. new[] { value, wildcard }.Order(StringComparer.Ordinal)]; + } - /// Mirrors Qdrant keyword matching, where a list facet matches when any element does. - private static bool Holds(Value? facet, IReadOnlyList wanted) => facet switch - { - { KindCase: Value.KindOneofCase.StringValue } value => - wanted.Contains(value.StringValue, StringComparer.Ordinal), - { KindCase: Value.KindOneofCase.ListValue } value => - value.ListValue.Values.Any(item => wanted.Contains(item.StringValue, StringComparer.Ordinal)), - _ => false, - }; + /// Mirrors Qdrant keyword matching, where a list facet matches when any element does. + private static bool Holds(Value? facet, IReadOnlyList wanted) + { + return facet switch + { + { KindCase: Value.KindOneofCase.StringValue } value => + wanted.Contains(value.StringValue, StringComparer.Ordinal), + { KindCase: Value.KindOneofCase.ListValue } value => + value.ListValue.Values.Any(item => wanted.Contains(item.StringValue, StringComparer.Ordinal)), + _ => false, + }; + } + } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs index ea95300e..04a54830 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs @@ -2,88 +2,92 @@ using Qdrant.Client; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// The real channel, over one . -internal sealed class QdrantSearchChannel : IQdrantSearchChannel, IDisposable +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - private readonly QdrantClient _client; - - /// Binds one client. - public QdrantSearchChannel(QdrantClient client) + /// The real channel, over one . + internal sealed class QdrantSearchChannel : IQdrantSearchChannel, IDisposable { - ArgumentNullException.ThrowIfNull(client); + private readonly QdrantClient _client; - _client = client; - } + /// Binds one client. + public QdrantSearchChannel(QdrantClient client) + { + ArgumentNullException.ThrowIfNull(client); - /// Closes the client. - public void Dispose() => _client.Dispose(); + _client = client; + } - /// - public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(query); + /// Closes the client. + public void Dispose() + { + _client.Dispose(); + } - return RunAsync( - () => _client.QueryAsync( - query.Collection, - prefetch: query.Prefetch, - query: query.Query, - usingVector: query.Using, - limit: query.Limit, - payloadSelector: new WithPayloadSelector { Enable = true }, - cancellationToken: cancellationToken), - cancellationToken); - } + /// + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(query); - /// - public Task> RetrieveAsync( - string collection, IReadOnlyList ids, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(ids); + return RunAsync( + () => _client.QueryAsync( + query.Collection, + prefetch: query.Prefetch, + query: query.Query, + usingVector: query.Using, + limit: query.Limit, + payloadSelector: new WithPayloadSelector { Enable = true }, + cancellationToken: cancellationToken), + cancellationToken); + } - return RunAsync( - () => _client.RetrieveAsync( - collection, - [.. ids.Select(id => new PointId { Uuid = id.ToString() })], - withPayload: true, - withVectors: false, - cancellationToken: cancellationToken), - cancellationToken); - } + /// + public Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(ids); - /// - public async Task> ScrollAsync( - string collection, Filter filter, uint limit, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(filter); + return RunAsync( + () => _client.RetrieveAsync( + collection, + [.. ids.Select(id => new PointId { Uuid = id.ToString() })], + withPayload: true, + withVectors: false, + cancellationToken: cancellationToken), + cancellationToken); + } - var response = await RunAsync( - () => _client.ScrollAsync( - collection, - filter: filter, - limit: limit, - payloadSelector: new WithPayloadSelector { Enable = true }, - vectorsSelector: new WithVectorsSelector { Enable = false }, - cancellationToken: cancellationToken), - cancellationToken).ConfigureAwait(false); + /// + public async Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(filter); - return response.Result; - } + ScrollResponse response = await RunAsync( + () => _client.ScrollAsync( + collection, + filter: filter, + limit: limit, + payloadSelector: new WithPayloadSelector { Enable = true }, + vectorsSelector: new WithVectorsSelector { Enable = false }, + cancellationToken: cancellationToken), + cancellationToken).ConfigureAwait(false); - /// - /// Runs one gRPC call and converts a client-side cancellation into . - /// - private static async Task RunAsync(Func> conversation, CancellationToken cancellationToken) - { - try - { - return await conversation().ConfigureAwait(false); + return response.Result; } - catch (RpcException ex) when (ex.StatusCode == StatusCode.Cancelled && cancellationToken.IsCancellationRequested) + + /// + /// Runs one gRPC call and converts a client-side cancellation into . + /// + private static async Task RunAsync(Func> conversation, CancellationToken cancellationToken) { - throw new OperationCanceledException(ex.Message, ex, cancellationToken); + try + { + return await conversation().ConfigureAwait(false); + } + catch (RpcException ex) when (ex.StatusCode == StatusCode.Cancelled && cancellationToken.IsCancellationRequested) + { + throw new OperationCanceledException(ex.Message, ex, cancellationToken); + } } } } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/Uuid5PointId.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/Uuid5PointId.cs index c9d2355c..e313e037 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/Uuid5PointId.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/Uuid5PointId.cs @@ -2,63 +2,64 @@ using System.Security.Cryptography; using System.Text; -namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; - -/// -/// The RFC 4122 version 5 point key of one card: uuid5(namespace, prefix + id). -/// -/// -/// Only links.lookup: uuid5 reaches this. Both the namespace and the prefix come from the -/// document, because they belong to whichever ingester built the collection: this class knows the -/// formula, never one deployment's parameters for it. -/// -internal static class Uuid5PointId +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant { - private static readonly Guid DnsNamespace = new("6ba7b810-9dad-11d1-80b4-00c04fd430c8"); - private static readonly Guid UrlNamespace = new("6ba7b811-9dad-11d1-80b4-00c04fd430c8"); - private static readonly Guid OidNamespace = new("6ba7b812-9dad-11d1-80b4-00c04fd430c8"); - private static readonly Guid X500Namespace = new("6ba7b814-9dad-11d1-80b4-00c04fd430c8"); - - /// Reads the namespace links.namespace names. - public static Guid Namespace(string name) + /// + /// The RFC 4122 version 5 point key of one card: uuid5(namespace, prefix + id). + /// + /// + /// Only links.lookup: uuid5 reaches this. Both the namespace and the prefix come from the + /// document, because they belong to whichever ingester built the collection: this class knows the + /// formula, never one deployment's parameters for it. + /// + internal static class Uuid5PointId { - ArgumentNullException.ThrowIfNull(name); + private static readonly Guid DnsNamespace = new("6ba7b810-9dad-11d1-80b4-00c04fd430c8"); + private static readonly Guid UrlNamespace = new("6ba7b811-9dad-11d1-80b4-00c04fd430c8"); + private static readonly Guid OidNamespace = new("6ba7b812-9dad-11d1-80b4-00c04fd430c8"); + private static readonly Guid X500Namespace = new("6ba7b814-9dad-11d1-80b4-00c04fd430c8"); - return name.ToLowerInvariant() switch + /// Reads the namespace links.namespace names. + public static Guid Namespace(string name) { - "url" => UrlNamespace, - "dns" => DnsNamespace, - "oid" => OidNamespace, - "x500" => X500Namespace, - _ => Guid.Parse(name), - }; - } + ArgumentNullException.ThrowIfNull(name); - /// Builds the point key of one card. - /// The id the collection stores at fields.id. - /// The uuid5 namespace links.namespace resolved to. - /// What links.prefix puts in front of the id. May be empty. - /// The key. - [SuppressMessage( - "Security", - "CA5350:Do Not Use Weak Cryptographic Algorithms", - Justification = "RFC 4122 version 5 specifies SHA-1. This is an identifier, not a security boundary.")] - [SuppressMessage( - "Security", - "S4790", - Justification = "RFC 4122 version 5 specifies SHA-1, pinned by Uuid5PointIdTests. Identifier, not a security boundary.")] - public static Guid For(string cardId, Guid @namespace, string prefix) - { - ArgumentNullException.ThrowIfNull(cardId); - ArgumentNullException.ThrowIfNull(prefix); + return name.ToLowerInvariant() switch + { + "url" => UrlNamespace, + "dns" => DnsNamespace, + "oid" => OidNamespace, + "x500" => X500Namespace, + _ => Guid.Parse(name), + }; + } + + /// Builds the point key of one card. + /// The id the collection stores at fields.id. + /// The uuid5 namespace links.namespace resolved to. + /// What links.prefix puts in front of the id. May be empty. + /// The key. + [SuppressMessage( + "Security", + "CA5350:Do Not Use Weak Cryptographic Algorithms", + Justification = "RFC 4122 version 5 specifies SHA-1. This is an identifier, not a security boundary.")] + [SuppressMessage( + "Security", + "S4790", + Justification = "RFC 4122 version 5 specifies SHA-1, pinned by Uuid5PointIdTests. Identifier, not a security boundary.")] + public static Guid For(string cardId, Guid @namespace, string prefix) + { + ArgumentNullException.ThrowIfNull(cardId); + ArgumentNullException.ThrowIfNull(prefix); - var name = Encoding.UTF8.GetBytes(prefix + cardId); - var hash = SHA1.HashData([.. @namespace.ToByteArray(bigEndian: true), .. name]); + byte[] name = Encoding.UTF8.GetBytes(prefix + cardId); + byte[] hash = SHA1.HashData([.. @namespace.ToByteArray(bigEndian: true), .. name]); - var bytes = hash[..16]; - bytes[6] = (byte)((bytes[6] & 0x0F) | 0x50); - bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80); + byte[] bytes = hash[..16]; + bytes[6] = (byte)((bytes[6] & 0x0F) | 0x50); + bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80); - return new Guid(bytes, bigEndian: true); + return new Guid(bytes, bigEndian: true); + } } } diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs index 38f57ecc..7d50bec4 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs @@ -13,126 +13,129 @@ using OpenAI; using OpenAI.Responses; -namespace AgentCore.Infrastructure.Llm.OpenAI; - -/// -/// The OpenAI adapter behind . -/// -public sealed class OpenAiChatClientAdapter : IChatClientAdapter +namespace AgentCore.Infrastructure.Llm.OpenAI { - /// The one providers.llm[].kind value this adapter serves. - public const string ProviderKind = "openai"; - - /// The ${secret:name} name the resolver chain is asked for. - public const string ApiKeySecretName = KnownSecrets.OpenAiApiKeyName; + /// + /// The OpenAI adapter behind . + /// + public sealed class OpenAiChatClientAdapter : IChatClientAdapter + { + /// The one providers.llm[].kind value this adapter serves. + public const string ProviderKind = "openai"; - /// The standard OpenAI environment variable, read when the chain holds no name. - public const string ApiKeyVariableName = KnownSecrets.OpenAiApiKeyVariable; + /// The ${secret:name} name the resolver chain is asked for. + public const string ApiKeySecretName = KnownSecrets.OpenAiApiKeyName; - private OpenAIClient? _client; + /// The standard OpenAI environment variable, read when the chain holds no name. + public const string ApiKeyVariableName = KnownSecrets.OpenAiApiKeyVariable; - /// - public string Kind => ProviderKind; + private OpenAIClient? _client; - /// Builds the client of one entry, reading the key on the first build only. - public async ValueTask CreateClientAsync( - LlmProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); + /// + public string Kind => ProviderKind; - _client ??= new OpenAIClient(new ApiKeyCredential( - await secrets - .RequireAsync(KnownSecrets.OpenAi, cancellationToken: cancellationToken) - .ConfigureAwait(false))); + /// Builds the client of one entry, reading the key on the first build only. + public async ValueTask CreateClientAsync( + LlmProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(entry); - var client = _client.GetResponsesClient().AsIChatClient(entry.Model); + _client ??= new OpenAIClient(new ApiKeyCredential( + await secrets + .RequireAsync(KnownSecrets.OpenAi, cancellationToken: cancellationToken) + .ConfigureAwait(false))); - return WithResponseDefaults(client, entry.ReasoningEffort); - } + IChatClient client = _client.GetResponsesClient().AsIChatClient(entry.Model); - /// - public AITool? ResolveHostedTool(AITool marker, LlmProviderConfiguration entry) - { - ArgumentNullException.ThrowIfNull(marker); - ArgumentNullException.ThrowIfNull(entry); + return WithResponseDefaults(client, entry.ReasoningEffort); + } - return marker switch + /// + public AITool? ResolveHostedTool(AITool marker, LlmProviderConfiguration entry) { - HostedWebSearchTool when entry.WebSearch != false => marker, - _ => null, - }; - } + ArgumentNullException.ThrowIfNull(marker); + ArgumentNullException.ThrowIfNull(entry); - /// - public int? GetContextWindow(LlmProviderConfiguration entry) - { - ArgumentNullException.ThrowIfNull(entry); + return marker switch + { + HostedWebSearchTool when entry.WebSearch != false => marker, + _ => null, + }; + } - return OpenAiContextWindows.Lookup(entry.Model); - } + /// + public int? GetContextWindow(LlmProviderConfiguration entry) + { + ArgumentNullException.ThrowIfNull(entry); - /// Puts store, reasoning_effort and prompt_cache_key on every request this client sends. - internal static IChatClient WithResponseDefaults(IChatClient client, string? effort) - { - var level = effort is { Length: > 0 } value ? Level(value) : (ResponseReasoningEffortLevel?)null; + return OpenAiContextWindows.Lookup(entry.Model); + } - return client - .AsBuilder() - .ConfigureOptions(options => - { - var caller = options.RawRepresentationFactory; + /// Puts store, reasoning_effort and prompt_cache_key on every request this client sends. + internal static IChatClient WithResponseDefaults(IChatClient client, string? effort) + { + ResponseReasoningEffortLevel? level = effort is { Length: > 0 } value ? Level(value) : (ResponseReasoningEffortLevel?)null; - options.RawRepresentationFactory = inner => + return client + .AsBuilder() + .ConfigureOptions(options => { - if (caller?.Invoke(inner) is not CreateResponseOptions raw) - { - raw = new CreateResponseOptions(); - } - - raw.StoredOutputEnabled ??= false; + Func? caller = options.RawRepresentationFactory; - if (options.AdditionalProperties?.TryGetValue(ChatRequestProperties.ConversationId, out string? conversationId) == true) + options.RawRepresentationFactory = inner => { - raw.PromptCacheKey ??= conversationId; - } + if (caller?.Invoke(inner) is not CreateResponseOptions raw) + { + raw = new CreateResponseOptions(); + } - if (level is { } chosen) - { - raw.ReasoningOptions ??= new ResponseReasoningOptions + raw.StoredOutputEnabled ??= false; + + if (options.AdditionalProperties?.TryGetValue(ChatRequestProperties.ConversationId, out string? conversationId) == true) { - ReasoningEffortLevel = chosen, - }; - } - - return raw; - }; - }) - .Build(); - } + raw.PromptCacheKey ??= conversationId; + } - /// Reads one reasoningEffort value. - /// The value the document wrote. - /// The vendor level. - /// The value is not one this vendor knows. - private static ResponseReasoningEffortLevel Level(string effort) - => effort.ToLowerInvariant() switch + if (level is { } chosen) + { + raw.ReasoningOptions ??= new ResponseReasoningOptions + { + ReasoningEffortLevel = chosen, + }; + } + + return raw; + }; + }) + .Build(); + } + + /// Reads one reasoningEffort value. + /// The value the document wrote. + /// The vendor level. + /// The value is not one this vendor knows. + private static ResponseReasoningEffortLevel Level(string effort) { - "none" => ResponseReasoningEffortLevel.None, - "minimal" => ResponseReasoningEffortLevel.Minimal, - "low" => ResponseReasoningEffortLevel.Low, - "medium" => ResponseReasoningEffortLevel.Medium, - "high" => ResponseReasoningEffortLevel.High, - _ => throw new ConfigurationLoadException(new ConfigurationError + return effort.ToLowerInvariant() switch { - Pointer = "/providers/llm", - Message = string.Format( - CultureInfo.InvariantCulture, - "reasoningEffort '{0}' is not one this vendor knows. Write none, minimal, low, " - + "medium or high.", - effort), - Check = ConfigurationCheck.ReferenceResolution, - }), - }; + "none" => ResponseReasoningEffortLevel.None, + "minimal" => ResponseReasoningEffortLevel.Minimal, + "low" => ResponseReasoningEffortLevel.Low, + "medium" => ResponseReasoningEffortLevel.Medium, + "high" => ResponseReasoningEffortLevel.High, + _ => throw new ConfigurationLoadException(new ConfigurationError + { + Pointer = "/providers/llm", + Message = string.Format( + CultureInfo.InvariantCulture, + "reasoningEffort '{0}' is not one this vendor knows. Write none, minimal, low, " + + "medium or high.", + effort), + Check = ConfigurationCheck.ReferenceResolution, + }), + }; + } + } } diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs index eb5036d4..813147be 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiContextWindows.cs @@ -1,45 +1,46 @@ -namespace AgentCore.Infrastructure.Llm.OpenAI; - -/// -/// A built-in table of OpenAI model context windows, keyed by model id prefix. -/// -internal static class OpenAiContextWindows +namespace AgentCore.Infrastructure.Llm.OpenAI { - private static readonly (string Prefix, int Tokens)[] Table = - [ - ("gpt-6-astra", 1_050_000), - ("gpt-5.6-sol", 1_050_000), - ("gpt-5.6-terra", 1_050_000), - ("gpt-5.6-luna", 1_050_000), - ("gpt-5.6-cyber", 400_000), - ("gpt-daybreak-red-latest", 400_000), - ("gpt-daybreak-blue-latest", 1_050_000), - ("gpt-5.4-nano", 400_000), - ("gpt-5.4", 1_050_000), - ("gpt-4.1-mini", 1_047_576), - ("gpt-4.1-nano", 1_047_576), - ("gpt-4.1", 1_047_576), - ]; - - /// Looks up a model id's context window by its longest matching prefix. - /// The providers.llm[].model value, such as gpt-4.1-mini-2025-04-14. - /// The window in tokens, or when no entry's prefix matches. - internal static int? Lookup(string modelId) + /// + /// A built-in table of OpenAI model context windows, keyed by model id prefix. + /// + internal static class OpenAiContextWindows { - ArgumentException.ThrowIfNullOrEmpty(modelId); + private static readonly (string Prefix, int Tokens)[] Table = + [ + ("gpt-6-astra", 1_050_000), + ("gpt-5.6-sol", 1_050_000), + ("gpt-5.6-terra", 1_050_000), + ("gpt-5.6-luna", 1_050_000), + ("gpt-5.6-cyber", 400_000), + ("gpt-daybreak-red-latest", 400_000), + ("gpt-daybreak-blue-latest", 1_050_000), + ("gpt-5.4-nano", 400_000), + ("gpt-5.4", 1_050_000), + ("gpt-4.1-mini", 1_047_576), + ("gpt-4.1-nano", 1_047_576), + ("gpt-4.1", 1_047_576), + ]; - var best = -1; - int? tokens = null; - - foreach (var (prefix, value) in Table) + /// Looks up a model id's context window by its longest matching prefix. + /// The providers.llm[].model value, such as gpt-4.1-mini-2025-04-14. + /// The window in tokens, or when no entry's prefix matches. + internal static int? Lookup(string modelId) { - if (prefix.Length > best && modelId.StartsWith(prefix, StringComparison.Ordinal)) + ArgumentException.ThrowIfNullOrEmpty(modelId); + + int best = -1; + int? tokens = null; + + foreach ((string? prefix, int value) in Table) { - best = prefix.Length; - tokens = value; + if (prefix.Length > best && modelId.StartsWith(prefix, StringComparison.Ordinal)) + { + best = prefix.Length; + tokens = value; + } } - } - return tokens; + return tokens; + } } } diff --git a/src/AgentCore.Infrastructure/Secrets/ChainedSecretResolver.cs b/src/AgentCore.Infrastructure/Secrets/ChainedSecretResolver.cs index cf5dcc79..d1b30ca5 100644 --- a/src/AgentCore.Infrastructure/Secrets/ChainedSecretResolver.cs +++ b/src/AgentCore.Infrastructure/Secrets/ChainedSecretResolver.cs @@ -2,70 +2,71 @@ using AgentCore.Application.Ports; using AgentCore.Application.Secrets; -namespace AgentCore.Infrastructure.Secrets; - -/// -/// Asks each resolver in order, and takes the first hit. -/// -/// -/// -/// The host lists the links it wants and the order it wants them in. A link that does not hold the -/// name answers , so the next link reads. The first value wins, and no later -/// link is asked. When no link holds the name, the chain answers and -/// turns that into the one startup failure. -/// -/// -/// The chain is open: a vault, a parameter store, or a test double joins by taking a place in the -/// list. Nothing here fixes the number of links, and no link knows about any other. -/// -/// -/// A typical order runs the most specific store first and the most general last. A host that mounts -/// its credentials as files usually writes [ FileSecretResolver, EnvironmentSecretResolver ], -/// so an operator overrides one name by writing one file. -/// -/// -public sealed class ChainedSecretResolver : ISecretResolverPort +namespace AgentCore.Infrastructure.Secrets { - private readonly ISecretResolverPort[] _links; - - /// Creates the chain. - /// The resolvers, in the order the chain asks them. - [SuppressMessage( - "csharpsquid", - "S3236", - Justification = "The name identifies the validated constructor parameter, not the loop variable; it carries no caller information.")] - public ChainedSecretResolver(IEnumerable links) + /// + /// Asks each resolver in order, and takes the first hit. + /// + /// + /// + /// The host lists the links it wants and the order it wants them in. A link that does not hold the + /// name answers , so the next link reads. The first value wins, and no later + /// link is asked. When no link holds the name, the chain answers and + /// turns that into the one startup failure. + /// + /// + /// The chain is open: a vault, a parameter store, or a test double joins by taking a place in the + /// list. Nothing here fixes the number of links, and no link knows about any other. + /// + /// + /// A typical order runs the most specific store first and the most general last. A host that mounts + /// its credentials as files usually writes [ FileSecretResolver, EnvironmentSecretResolver ], + /// so an operator overrides one name by writing one file. + /// + /// + public sealed class ChainedSecretResolver : ISecretResolverPort { - ArgumentNullException.ThrowIfNull(links); + private readonly ISecretResolverPort[] _links; - _links = [.. links]; - foreach (var link in _links) + /// Creates the chain. + /// The resolvers, in the order the chain asks them. + [SuppressMessage( + "csharpsquid", + "S3236", + Justification = "The name identifies the validated constructor parameter, not the loop variable; it carries no caller information.")] + public ChainedSecretResolver(IEnumerable links) { - ArgumentNullException.ThrowIfNull(link, nameof(links)); - } - } + ArgumentNullException.ThrowIfNull(links); - /// Gets the number of links. - public int Count => _links.Length; + _links = [.. links]; + foreach (ISecretResolverPort link in _links) + { + ArgumentNullException.ThrowIfNull(link, nameof(links)); + } + } - /// Reads the value of one secret from the first link that holds it. - /// The name the document wrote. - /// Cancels the read. - /// The value, or when no link holds the name. - public async ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(name); + /// Gets the number of links. + public int Count => _links.Length; - foreach (var link in _links) + /// Reads the value of one secret from the first link that holds it. + /// The name the document wrote. + /// Cancels the read. + /// The value, or when no link holds the name. + public async ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) { - cancellationToken.ThrowIfCancellationRequested(); + ArgumentNullException.ThrowIfNull(name); - if (await link.TryResolveAsync(name, cancellationToken).ConfigureAwait(false) is { } value) + foreach (ISecretResolverPort link in _links) { - return value; + cancellationToken.ThrowIfCancellationRequested(); + + if (await link.TryResolveAsync(name, cancellationToken).ConfigureAwait(false) is { } value) + { + return value; + } } - } - return null; + return null; + } } } diff --git a/src/AgentCore.Infrastructure/Secrets/EnvironmentSecretResolver.cs b/src/AgentCore.Infrastructure/Secrets/EnvironmentSecretResolver.cs index 262e4e03..f1b8799a 100644 --- a/src/AgentCore.Infrastructure/Secrets/EnvironmentSecretResolver.cs +++ b/src/AgentCore.Infrastructure/Secrets/EnvironmentSecretResolver.cs @@ -2,74 +2,78 @@ using AgentCore.Application.Ports; using AgentCore.Application.Secrets; -namespace AgentCore.Infrastructure.Secrets; - -/// -/// Reads a secret from a process environment variable. -/// -/// -/// -/// It tries the name the document wrote first, then the shouting form of it: orders-api-key -/// becomes ORDERS_API_KEY. A document therefore keeps its own vocabulary, and a deployment -/// keeps the variable names every shell and container runtime already writes. -/// -/// -/// The value never reaches a log. This adapter reads it and hands it straight to -/// . -/// -/// -public sealed class EnvironmentSecretResolver : ISecretResolverPort +namespace AgentCore.Infrastructure.Secrets { - private readonly Func _read; - - /// Creates a resolver over the process environment. - public EnvironmentSecretResolver() - : this(Environment.GetEnvironmentVariable) - { - } - - /// Creates a resolver over any variable source. The tests use this. - /// Reads one variable, and answers null when it is not set. - internal EnvironmentSecretResolver(Func read) + /// + /// Reads a secret from a process environment variable. + /// + /// + /// + /// It tries the name the document wrote first, then the shouting form of it: orders-api-key + /// becomes ORDERS_API_KEY. A document therefore keeps its own vocabulary, and a deployment + /// keeps the variable names every shell and container runtime already writes. + /// + /// + /// The value never reaches a log. This adapter reads it and hands it straight to + /// . + /// + /// + public sealed class EnvironmentSecretResolver : ISecretResolverPort { - ArgumentNullException.ThrowIfNull(read); - _read = read; - } + private readonly Func _read; - /// Reads the value of one secret. - /// The name the document wrote. - /// Cancels the read. - /// The value, or when neither form is set. - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(name); - cancellationToken.ThrowIfCancellationRequested(); + /// Creates a resolver over the process environment. + public EnvironmentSecretResolver() + : this(Environment.GetEnvironmentVariable) + { + } - if (name.Length == 0) + /// Creates a resolver over any variable source. The tests use this. + /// Reads one variable, and answers null when it is not set. + internal EnvironmentSecretResolver(Func read) { - return ValueTask.FromResult(null); + ArgumentNullException.ThrowIfNull(read); + _read = read; } - var value = Empty(_read(name)) ?? Empty(_read(ToVariableName(name))); - return ValueTask.FromResult(value); - } + /// Reads the value of one secret. + /// The name the document wrote. + /// Cancels the read. + /// The value, or when neither form is set. + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(name); + cancellationToken.ThrowIfCancellationRequested(); - /// Turns a document name into the environment variable form of it. - /// The name the document wrote. - /// The name in upper case, with every separator written as an underscore. - public static string ToVariableName(string name) - { - ArgumentNullException.ThrowIfNull(name); + if (name.Length == 0) + { + return ValueTask.FromResult(null); + } - StringBuilder builder = new(name.Length); - foreach (var character in name) + string? value = Empty(_read(name)) ?? Empty(_read(ToVariableName(name))); + return ValueTask.FromResult(value); + } + + /// Turns a document name into the environment variable form of it. + /// The name the document wrote. + /// The name in upper case, with every separator written as an underscore. + public static string ToVariableName(string name) { - builder.Append(char.IsLetterOrDigit(character) ? char.ToUpperInvariant(character) : '_'); + ArgumentNullException.ThrowIfNull(name); + + StringBuilder builder = new(name.Length); + foreach (char character in name) + { + _ = builder.Append(char.IsLetterOrDigit(character) ? char.ToUpperInvariant(character) : '_'); + } + + return builder.ToString(); } - return builder.ToString(); + /// Reads an empty variable as an unset one. + private static string? Empty(string? value) + { + return value is { Length: > 0 } ? value : null; + } } - - /// Reads an empty variable as an unset one. - private static string? Empty(string? value) => value is { Length: > 0 } ? value : null; } diff --git a/src/AgentCore.Infrastructure/Secrets/FileSecretResolver.cs b/src/AgentCore.Infrastructure/Secrets/FileSecretResolver.cs index 2813e211..b8203011 100644 --- a/src/AgentCore.Infrastructure/Secrets/FileSecretResolver.cs +++ b/src/AgentCore.Infrastructure/Secrets/FileSecretResolver.cs @@ -1,79 +1,80 @@ using AgentCore.Application.Ports; -namespace AgentCore.Infrastructure.Secrets; - -/// -/// Reads a secret from one file of a directory. -/// -/// -/// -/// This is the /run/secrets convention: one file for each name, and the file holds the value -/// and nothing else. Docker, Podman, and Kubernetes all mount a secret this way, so a deployment -/// keeps the credential out of the process environment and out of the image. -/// -/// -/// A trailing line break is not part of the value, because an editor writes one and a credential -/// does not hold one. A name that holds a directory separator reads nothing at all: a secret name is -/// a file name and never a path. -/// -/// -/// A file that is not there is a miss, so the next link of the chain answers. A file that is there -/// and does not read raises the input failure, because a store that is present and broken is a -/// startup failure and never a miss. -/// -/// -public sealed class FileSecretResolver : ISecretResolverPort +namespace AgentCore.Infrastructure.Secrets { - /// The directory a container runtime mounts a secret into. - public const string DefaultDirectory = "/run/secrets"; - - private readonly string _directory; - - /// Creates a resolver over . - public FileSecretResolver() - : this(DefaultDirectory) + /// + /// Reads a secret from one file of a directory. + /// + /// + /// + /// This is the /run/secrets convention: one file for each name, and the file holds the value + /// and nothing else. Docker, Podman, and Kubernetes all mount a secret this way, so a deployment + /// keeps the credential out of the process environment and out of the image. + /// + /// + /// A trailing line break is not part of the value, because an editor writes one and a credential + /// does not hold one. A name that holds a directory separator reads nothing at all: a secret name is + /// a file name and never a path. + /// + /// + /// A file that is not there is a miss, so the next link of the chain answers. A file that is there + /// and does not read raises the input failure, because a store that is present and broken is a + /// startup failure and never a miss. + /// + /// + public sealed class FileSecretResolver : ISecretResolverPort { - } + /// The directory a container runtime mounts a secret into. + public const string DefaultDirectory = "/run/secrets"; - /// Creates a resolver over one directory. - /// The directory that holds one file for each secret. - public FileSecretResolver(string directory) - { - ArgumentException.ThrowIfNullOrEmpty(directory); - _directory = directory; - } + /// Creates a resolver over . + public FileSecretResolver() + : this(DefaultDirectory) + { + } - /// Gets the directory this resolver reads. - public string Directory => _directory; + /// Creates a resolver over one directory. + /// The directory that holds one file for each secret. + public FileSecretResolver(string directory) + { + ArgumentException.ThrowIfNullOrEmpty(directory); + Directory = directory; + } - /// Reads the value of one secret. - /// The name the document wrote. It is a file name. - /// Cancels the read. - /// The value, or when the directory holds no such file. - public async ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(name); - cancellationToken.ThrowIfCancellationRequested(); + /// Gets the directory this resolver reads. + public string Directory { get; } - if (!IsFileName(name)) + /// Reads the value of one secret. + /// The name the document wrote. It is a file name. + /// Cancels the read. + /// The value, or when the directory holds no such file. + public async ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) { - return null; + ArgumentNullException.ThrowIfNull(name); + cancellationToken.ThrowIfCancellationRequested(); + + if (!IsFileName(name)) + { + return null; + } + + string path = Path.Combine(Directory, name); + if (!File.Exists(path)) + { + return null; + } + + string text = await File.ReadAllTextAsync(path, cancellationToken).ConfigureAwait(false); + return text.TrimEnd('\r', '\n'); } - var path = Path.Combine(_directory, name); - if (!File.Exists(path)) + /// Reports whether one secret name names a file inside the directory and nothing else. + private static bool IsFileName(string name) { - return null; + return name.Length > 0 + && name.IndexOfAny(['/', '\\']) < 0 + && !name.Contains("..", StringComparison.Ordinal) + && name.IndexOfAny(Path.GetInvalidFileNameChars()) < 0; } - - var text = await File.ReadAllTextAsync(path, cancellationToken).ConfigureAwait(false); - return text.TrimEnd('\r', '\n'); } - - /// Reports whether one secret name names a file inside the directory and nothing else. - private static bool IsFileName(string name) - => name.Length > 0 - && name.IndexOfAny(['/', '\\']) < 0 - && !name.Contains("..", StringComparison.Ordinal) - && name.IndexOfAny(Path.GetInvalidFileNameChars()) < 0; } diff --git a/src/AgentCore.Infrastructure/Telemetry/Grafana/GrafanaOtlpTelemetryAdapter.cs b/src/AgentCore.Infrastructure/Telemetry/Grafana/GrafanaOtlpTelemetryAdapter.cs index a2299711..60147662 100644 --- a/src/AgentCore.Infrastructure/Telemetry/Grafana/GrafanaOtlpTelemetryAdapter.cs +++ b/src/AgentCore.Infrastructure/Telemetry/Grafana/GrafanaOtlpTelemetryAdapter.cs @@ -11,202 +11,206 @@ using OpenTelemetry.Resources; using OpenTelemetry.Trace; -namespace AgentCore.Infrastructure.Telemetry.Grafana; - -/// -/// Exports traces, metrics, and logs to Grafana Cloud over OTLP. kind: grafana. -/// -/// -/// -/// D26 sends every signal to Grafana Cloud, and this is the one file that knows it. The library above -/// writes to an ActivitySource and a Meter and knows nothing about where they go, so a -/// deployment that exports somewhere else writes a sibling of this file and changes one line of its -/// document. -/// -/// -/// What makes this Grafana rather than plain OTLP is one thing: the credential. Grafana Cloud -/// authenticates OTLP with HTTP basic, where the instance id is the user and the token is the -/// password. Everything else here is the vendor-neutral OTLP setup, which is why the class is named -/// for both. -/// -/// -/// No instrumentation package is referenced, on purpose. .NET 10 emits the ASP.NET Core and -/// HttpClient signals from the framework itself, so listening to them costs a name in -/// providers.telemetry.sources and providers.telemetry.meters. Referencing -/// OpenTelemetry.Instrumentation.AspNetCore here would pull a web dependency into the outbound -/// adapter project for signals the framework already produces. -/// -/// -/// T61 is enforced twice, and this is the second place. The library keeps no conversation id on a -/// metric attribute; this keeps the export interval at a minute or more, because Grafana Cloud bills -/// the greater of active series and data points a minute. The floor lives on -/// , so a document cannot -/// write its way under it. -/// -/// -public sealed class GrafanaOtlpTelemetryAdapter : ITelemetryAdapter +namespace AgentCore.Infrastructure.Telemetry.Grafana { - /// The providers.telemetry.kind value this adapter serves. - public const string GrafanaKind = "grafana"; - - /// The path traces are posted to, under the base endpoint. - internal const string TracesPath = "/v1/traces"; - - /// The path metrics are posted to, under the base endpoint. - internal const string MetricsPath = "/v1/metrics"; - - /// The path log records are posted to, under the base endpoint. - internal const string LogsPath = "/v1/logs"; - - /// - public string Kind => GrafanaKind; - - /// Joins the base endpoint of the document to one signal's path. - /// The providers.telemetry.endpoint value. - /// One of the three signal paths, each starting with a slash. - /// The full URL this signal is posted to. + /// + /// Exports traces, metrics, and logs to Grafana Cloud over OTLP. kind: grafana. + /// /// /// - /// This has to be done by hand, and getting it wrong is silent. The OpenTelemetry .NET - /// exporter appends /v1/traces and its siblings for you only when the endpoint came from - /// the OTEL_EXPORTER_OTLP_ENDPOINT variable. Assigning - /// OtlpExporterOptions.Endpoint in code sets AppendSignalPathToEndpoint to false, - /// on the reasoning that code that names an endpoint names the whole of it. So a document that - /// writes the gateway root would otherwise post all three signals to the root and read nothing - /// back but a rejection. + /// D26 sends every signal to Grafana Cloud, and this is the one file that knows it. The library above + /// writes to an ActivitySource and a Meter and knows nothing about where they go, so a + /// deployment that exports somewhere else writes a sibling of this file and changes one line of its + /// document. /// /// - /// A document that writes no endpoint takes the other path: nothing is assigned, the variable - /// answers, and the SDK does the appending. That is why this runs only when the document wrote - /// one. + /// What makes this Grafana rather than plain OTLP is one thing: the credential. Grafana Cloud + /// authenticates OTLP with HTTP basic, where the instance id is the user and the token is the + /// password. Everything else here is the vendor-neutral OTLP setup, which is why the class is named + /// for both. + /// + /// + /// No instrumentation package is referenced, on purpose. .NET 10 emits the ASP.NET Core and + /// HttpClient signals from the framework itself, so listening to them costs a name in + /// providers.telemetry.sources and providers.telemetry.meters. Referencing + /// OpenTelemetry.Instrumentation.AspNetCore here would pull a web dependency into the outbound + /// adapter project for signals the framework already produces. + /// + /// + /// T61 is enforced twice, and this is the second place. The library keeps no conversation id on a + /// metric attribute; this keeps the export interval at a minute or more, because Grafana Cloud bills + /// the greater of active series and data points a minute. The floor lives on + /// , so a document cannot + /// write its way under it. /// /// - internal static string SignalEndpoint(string baseEndpoint, string signalPath) + public sealed class GrafanaOtlpTelemetryAdapter : ITelemetryAdapter { - var root = baseEndpoint.TrimEnd('/'); - - // A document that already wrote the signal path is taken at its word rather than given a - // second copy of it. - return root.EndsWith(signalPath, StringComparison.OrdinalIgnoreCase) ? root : root + signalPath; - } - - /// - public async ValueTask StartAsync( - TelemetryProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); + /// The providers.telemetry.kind value this adapter serves. + public const string GrafanaKind = "grafana"; + + /// The path traces are posted to, under the base endpoint. + internal const string TracesPath = "/v1/traces"; + + /// The path metrics are posted to, under the base endpoint. + internal const string MetricsPath = "/v1/metrics"; + + /// The path log records are posted to, under the base endpoint. + internal const string LogsPath = "/v1/logs"; + + /// + public string Kind => GrafanaKind; + + /// Joins the base endpoint of the document to one signal's path. + /// The providers.telemetry.endpoint value. + /// One of the three signal paths, each starting with a slash. + /// The full URL this signal is posted to. + /// + /// + /// This has to be done by hand, and getting it wrong is silent. The OpenTelemetry .NET + /// exporter appends /v1/traces and its siblings for you only when the endpoint came from + /// the OTEL_EXPORTER_OTLP_ENDPOINT variable. Assigning + /// OtlpExporterOptions.Endpoint in code sets AppendSignalPathToEndpoint to false, + /// on the reasoning that code that names an endpoint names the whole of it. So a document that + /// writes the gateway root would otherwise post all three signals to the root and read nothing + /// back but a rejection. + /// + /// + /// A document that writes no endpoint takes the other path: nothing is assigned, the variable + /// answers, and the SDK does the appending. That is why this runs only when the document wrote + /// one. + /// + /// + internal static string SignalEndpoint(string baseEndpoint, string signalPath) + { + string root = baseEndpoint.TrimEnd('/'); - string? headers = await CredentialAsync(secrets, cancellationToken).ConfigureAwait(false); + // A document that already wrote the signal path is taken at its word rather than given a + // second copy of it. + return root.EndsWith(signalPath, StringComparison.OrdinalIgnoreCase) ? root : root + signalPath; + } - Action ConfigureExporter(string signalPath) => options => + /// + public async ValueTask StartAsync( + TelemetryProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) { - // The Grafana Cloud OTLP gateway speaks HTTP with protobuf bodies, and it does not - // answer gRPC. The OpenTelemetry .NET default on this target framework IS gRPC, so - // leaving this alone sends every signal at a protocol the gateway never replies to. - options.Protocol = OtlpExportProtocol.HttpProtobuf; + ArgumentNullException.ThrowIfNull(entry); - if (entry.Endpoint is { Length: > 0 } endpoint) + string? headers = await CredentialAsync(secrets, cancellationToken).ConfigureAwait(false); + + Action ConfigureExporter(string signalPath) + { + return options => { - options.Endpoint = new Uri(SignalEndpoint(endpoint, signalPath)); + // The Grafana Cloud OTLP gateway speaks HTTP with protobuf bodies, and it does not + // answer gRPC. The OpenTelemetry .NET default on this target framework IS gRPC, so + // leaving this alone sends every signal at a protocol the gateway never replies to. + options.Protocol = OtlpExportProtocol.HttpProtobuf; + + if (entry.Endpoint is { Length: > 0 } endpoint) + { + options.Endpoint = new Uri(SignalEndpoint(endpoint, signalPath)); + } + + // Only overwrite the headers when a Grafana credential resolved. Leaving them alone is + // what lets the standard OTEL_EXPORTER_OTLP_HEADERS variable still serve a collector that + // authenticates some other way, or none at all. + if (headers is not null) + { + options.Headers = headers; + } + }; } - // Only overwrite the headers when a Grafana credential resolved. Leaving them alone is - // what lets the standard OTEL_EXPORTER_OTLP_HEADERS variable still serve a collector that - // authenticates some other way, or none at all. - if (headers is not null) + // One resource for all three signals, so a reader in Grafana joins a log line to the span it + // was written under without a second lookup. + ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(entry.ServiceName); + + TracerProviderBuilder tracerBuilder = Sdk.CreateTracerProviderBuilder() + .SetResourceBuilder(resource) + .AddSource(AgentCoreTelemetry.ActivitySourceName); + + foreach (string source in entry.Sources) { - options.Headers = headers; + _ = tracerBuilder.AddSource(source); } - }; - // One resource for all three signals, so a reader in Grafana joins a log line to the span it - // was written under without a second lookup. - var resource = ResourceBuilder.CreateDefault().AddService(entry.ServiceName); + MeterProviderBuilder meterBuilder = Sdk.CreateMeterProviderBuilder() + .SetResourceBuilder(resource) + .AddMeter(AgentCoreTelemetry.MeterName); - var tracerBuilder = Sdk.CreateTracerProviderBuilder() - .SetResourceBuilder(resource) - .AddSource(AgentCoreTelemetry.ActivitySourceName); - - foreach (var source in entry.Sources) - { - tracerBuilder.AddSource(source); - } + foreach (string meter in entry.Meters) + { + _ = meterBuilder.AddMeter(meter); + } - var meterBuilder = Sdk.CreateMeterProviderBuilder() - .SetResourceBuilder(resource) - .AddMeter(AgentCoreTelemetry.MeterName); + TracerProvider tracer = tracerBuilder.AddOtlpExporter(ConfigureExporter(TracesPath)).Build() + ?? throw new InvalidOperationException("the OpenTelemetry SDK built no tracer provider."); - foreach (var meter in entry.Meters) - { - meterBuilder.AddMeter(meter); - } + Action configureMetrics = ConfigureExporter(MetricsPath); - var tracer = tracerBuilder.AddOtlpExporter(ConfigureExporter(TracesPath)).Build() - ?? throw new InvalidOperationException("the OpenTelemetry SDK built no tracer provider."); + MeterProvider meters = meterBuilder + .AddOtlpExporter((exporter, reader) => + { + configureMetrics(exporter); + reader.PeriodicExportingMetricReaderOptions.ExportIntervalMilliseconds = + entry.ExportIntervalMilliseconds; + }) + .Build() + ?? throw new InvalidOperationException("the OpenTelemetry SDK built no meter provider."); - var configureMetrics = ConfigureExporter(MetricsPath); - - var meters = meterBuilder - .AddOtlpExporter((exporter, reader) => + ILoggerFactory logs = LoggerFactory.Create(builder => builder.AddOpenTelemetry(options => { - configureMetrics(exporter); - reader.PeriodicExportingMetricReaderOptions.ExportIntervalMilliseconds = - entry.ExportIntervalMilliseconds; - }) - .Build() - ?? throw new InvalidOperationException("the OpenTelemetry SDK built no meter provider."); - - var logs = LoggerFactory.Create(builder => builder.AddOpenTelemetry(options => - { - // Without these two the exported record carries the message template and the arguments - // separately, and no scope at all, so a reader sees "{Stage} refused {Tool}" beside a - // call it cannot place. - options.IncludeFormattedMessage = true; - options.IncludeScopes = true; - options.SetResourceBuilder(resource); - options.AddOtlpExporter(ConfigureExporter(LogsPath)); - })); - - return new OtlpTelemetrySession(tracer, meters, logs); - } - - /// Reads the Grafana Cloud credential and renders it as one OTLP header. - /// The chain a credential resolves through, or . - /// Cancels the read. - /// - /// The Authorization header, or when this deployment names no - /// Grafana instance and therefore exports with no credential. - /// - /// - /// An instance id resolved and the token beside it did not. - /// - /// - /// The instance id is the switch. A collector running beside this process needs neither half, and - /// a deployment that names Grafana fails at startup rather than sending telemetry that Grafana - /// answers 401 to and nobody notices. - /// - private static async ValueTask CredentialAsync( - ISecretResolverPort? secrets, - CancellationToken cancellationToken) - { - string? instanceId = await secrets - .TryReadAsync(KnownSecrets.GrafanaCloudInstanceId, cancellationToken) - .ConfigureAwait(false); + // Without these two the exported record carries the message template and the arguments + // separately, and no scope at all, so a reader sees "{Stage} refused {Tool}" beside a + // call it cannot place. + options.IncludeFormattedMessage = true; + options.IncludeScopes = true; + _ = options.SetResourceBuilder(resource); + _ = options.AddOtlpExporter(ConfigureExporter(LogsPath)); + })); + + return new OtlpTelemetrySession(tracer, meters, logs); + } - if (instanceId is not { Length: > 0 }) + /// Reads the Grafana Cloud credential and renders it as one OTLP header. + /// The chain a credential resolves through, or . + /// Cancels the read. + /// + /// The Authorization header, or when this deployment names no + /// Grafana instance and therefore exports with no credential. + /// + /// + /// An instance id resolved and the token beside it did not. + /// + /// + /// The instance id is the switch. A collector running beside this process needs neither half, and + /// a deployment that names Grafana fails at startup rather than sending telemetry that Grafana + /// answers 401 to and nobody notices. + /// + private static async ValueTask CredentialAsync( + ISecretResolverPort? secrets, + CancellationToken cancellationToken) { - return null; - } + string? instanceId = await secrets + .TryReadAsync(KnownSecrets.GrafanaCloudInstanceId, cancellationToken) + .ConfigureAwait(false); - string token = await secrets.RequireAsync( - KnownSecrets.GrafanaCloudApiToken, - "This deployment named a Grafana Cloud instance, and OTLP export there needs the token beside it.", - cancellationToken).ConfigureAwait(false); + if (instanceId is not { Length: > 0 }) + { + return null; + } - string basic = Convert.ToBase64String(Encoding.UTF8.GetBytes(instanceId + ":" + token)); + string token = await secrets.RequireAsync( + KnownSecrets.GrafanaCloudApiToken, + "This deployment named a Grafana Cloud instance, and OTLP export there needs the token beside it.", + cancellationToken).ConfigureAwait(false); - return "Authorization=Basic " + basic; + string basic = Convert.ToBase64String(Encoding.UTF8.GetBytes(instanceId + ":" + token)); + + return "Authorization=Basic " + basic; + } } } diff --git a/src/AgentCore.Infrastructure/Telemetry/Grafana/OtlpTelemetrySession.cs b/src/AgentCore.Infrastructure/Telemetry/Grafana/OtlpTelemetrySession.cs index 30cc645b..4c8da8e4 100644 --- a/src/AgentCore.Infrastructure/Telemetry/Grafana/OtlpTelemetrySession.cs +++ b/src/AgentCore.Infrastructure/Telemetry/Grafana/OtlpTelemetrySession.cs @@ -4,77 +4,81 @@ using OpenTelemetry.Metrics; using OpenTelemetry.Trace; -namespace AgentCore.Infrastructure.Telemetry.Grafana; - -/// -/// The three OpenTelemetry signals of one export, held together and shut down together. -/// -/// -/// -/// Traces and metrics are built standalone, through , rather than registered into a -/// service collection. That is what keeps every dependency-injection type out of -/// AgentCore.Application: the port hands back this object, and the object holds the providers. -/// -/// -/// Logs take a different route on purpose. The standalone log builder, -/// Sdk.CreateLoggerProviderBuilder, is marked experimental under OTEL1000, and this -/// repository builds warnings as errors. A private carrying the -/// OpenTelemetry provider does the same job through the stable surface, and -/// forwards to it. Disposing that factory disposes the -/// exporter beneath it, which is the flush. -/// -/// -/// Disposal is the flush. Each provider batches onto a background thread, so a process that -/// exited without disposing would drop whatever had not been sent. Each signal gets a bounded moment -/// to drain, because a host that is stopping has a shutdown budget and a collector that has gone away -/// must not hold it. -/// -/// -/// The span provider. -/// The measurement provider. -/// The factory carrying the OpenTelemetry log provider. -internal sealed class OtlpTelemetrySession( - TracerProvider tracer, - MeterProvider meter, - ILoggerFactory logs) : ITelemetrySession, ILoggerProvider +namespace AgentCore.Infrastructure.Telemetry.Grafana { - /// How long each signal is given to drain on the way out, in milliseconds. - private const int FlushTimeoutMilliseconds = 5_000; - - /// - public ILoggerProvider Logs => this; - - /// - /// - /// The host's own factory calls this once for each category and holds what it gets, so the - /// forwarded logger lives as long as the category does and nothing is created for each line. - /// - public ILogger CreateLogger(string categoryName) => logs.CreateLogger(categoryName); - - /// Does nothing, because the host's logger factory owns no part of this session. + /// + /// The three OpenTelemetry signals of one export, held together and shut down together. + /// /// - /// disposes the providers it was given. This session is handed to one - /// as a provider and is also owned by the composition root, so honouring that call would shut the - /// export down whenever the host factory went away and leave flushing - /// something already gone. Disposal happens in one place, below. + /// + /// Traces and metrics are built standalone, through , rather than registered into a + /// service collection. That is what keeps every dependency-injection type out of + /// AgentCore.Application: the port hands back this object, and the object holds the providers. + /// + /// + /// Logs take a different route on purpose. The standalone log builder, + /// Sdk.CreateLoggerProviderBuilder, is marked experimental under OTEL1000, and this + /// repository builds warnings as errors. A private carrying the + /// OpenTelemetry provider does the same job through the stable surface, and + /// forwards to it. Disposing that factory disposes the + /// exporter beneath it, which is the flush. + /// + /// + /// Disposal is the flush. Each provider batches onto a background thread, so a process that + /// exited without disposing would drop whatever had not been sent. Each signal gets a bounded moment + /// to drain, because a host that is stopping has a shutdown budget and a collector that has gone away + /// must not hold it. + /// /// - void IDisposable.Dispose() + /// The span provider. + /// The measurement provider. + /// The factory carrying the OpenTelemetry log provider. + internal sealed class OtlpTelemetrySession( + TracerProvider tracer, + MeterProvider meter, + ILoggerFactory logs) : ITelemetrySession, ILoggerProvider { - } + /// How long each signal is given to drain on the way out, in milliseconds. + private const int FlushTimeoutMilliseconds = 5_000; - /// - public ValueTask DisposeAsync() - { - // Logs first: the factory stops accepting lines before the exporters under the other two - // signals go away, so nothing is written into a provider that has already shut down. - logs.Dispose(); + /// + public ILoggerProvider Logs => this; + + /// + /// + /// The host's own factory calls this once for each category and holds what it gets, so the + /// forwarded logger lives as long as the category does and nothing is created for each line. + /// + public ILogger CreateLogger(string categoryName) + { + return logs.CreateLogger(categoryName); + } + + /// Does nothing, because the host's logger factory owns no part of this session. + /// + /// disposes the providers it was given. This session is handed to one + /// as a provider and is also owned by the composition root, so honouring that call would shut the + /// export down whenever the host factory went away and leave flushing + /// something already gone. Disposal happens in one place, below. + /// + void IDisposable.Dispose() + { + } + + /// + public ValueTask DisposeAsync() + { + // Logs first: the factory stops accepting lines before the exporters under the other two + // signals go away, so nothing is written into a provider that has already shut down. + logs.Dispose(); - meter.ForceFlush(FlushTimeoutMilliseconds); - meter.Dispose(); + _ = meter.ForceFlush(FlushTimeoutMilliseconds); + meter.Dispose(); - tracer.ForceFlush(FlushTimeoutMilliseconds); - tracer.Dispose(); + _ = tracer.ForceFlush(FlushTimeoutMilliseconds); + tracer.Dispose(); - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } } diff --git a/src/AgentCore.Infrastructure/Tools/HttpToolSource.cs b/src/AgentCore.Infrastructure/Tools/HttpToolSource.cs index 77471a15..aa64e98b 100644 --- a/src/AgentCore.Infrastructure/Tools/HttpToolSource.cs +++ b/src/AgentCore.Infrastructure/Tools/HttpToolSource.cs @@ -9,175 +9,178 @@ using AgentCore.Application.Tools.Registry; using Microsoft.Extensions.AI; -namespace AgentCore.Infrastructure.Tools; - -/// -/// Serves the kind: http tools. -/// -public sealed class HttpToolSource : IToolSource +namespace AgentCore.Infrastructure.Tools { - /// The name a host opens the client of these tools under, on its HTTP pipeline. - public const string HttpClientName = "agentcore.tools"; - - private readonly HttpClient _client; + /// + /// Serves the kind: http tools. + /// + public sealed class HttpToolSource : IToolSource + { + /// The name a host opens the client of these tools under, on its HTTP pipeline. + public const string HttpClientName = "agentcore.tools"; - private readonly ResolvedSecrets _secrets; + private readonly HttpClient _client; - /// Creates the source. - /// The client every tool of this source sends on. The source never disposes it. - /// The values startup already resolved. - public HttpToolSource(HttpClient client, ResolvedSecrets secrets) - { - ArgumentNullException.ThrowIfNull(client); - ArgumentNullException.ThrowIfNull(secrets); + private readonly ResolvedSecrets _secrets; - _client = client; - _secrets = secrets; - } + /// Creates the source. + /// The client every tool of this source sends on. The source never disposes it. + /// The values startup already resolved. + public HttpToolSource(HttpClient client, ResolvedSecrets secrets) + { + ArgumentNullException.ThrowIfNull(client); + ArgumentNullException.ThrowIfNull(secrets); - /// - /// A kind: http tool declares no request:. - /// A header references a secret startup did not resolve. - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); + _client = client; + _secrets = secrets; + } - List registrations = []; - foreach (var declared in context.DeclarationsOf(ToolKind.Http)) + /// + /// A kind: http tool declares no request:. + /// A header references a secret startup did not resolve. + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) { - if (declared.Request is not { } request) - { - throw ToolSourceError.Fail( - $"the tool '{declared.Id}' is kind: http and declares no request:, so there is no " - + "call to make."); - } + ArgumentNullException.ThrowIfNull(context); - List> headers = []; - foreach (var header in request.Headers) + List registrations = []; + foreach (ToolConfiguration declared in context.DeclarationsOf(ToolKind.Http)) { - headers.Add(new KeyValuePair(header.Key, _secrets.Format(header.Value))); + if (declared.Request is not { } request) + { + throw ToolSourceError.Fail( + $"the tool '{declared.Id}' is kind: http and declares no request:, so there is no " + + "call to make."); + } + + List> headers = []; + foreach (KeyValuePair header in request.Headers) + { + headers.Add(new KeyValuePair(header.Key, _secrets.Format(header.Value))); + } + + registrations.Add(new ToolRegistration( + declared.Id, + declared.Description ?? string.Empty, + () => new HttpTool(declared, request, headers, _client))); } - registrations.Add(new ToolRegistration( - declared.Id, - declared.Description ?? string.Empty, - () => new HttpTool(declared, request, headers, _client))); + return ValueTask.FromResult>(registrations); } - - return ValueTask.FromResult>(registrations); - } -} - -/// One kind: http tool: one request, one answer. -internal sealed class HttpTool : DeclaredTool -{ - /// The number of characters of a failing body the error result quotes. - private const int BodyQuoteLimit = 500; - - private readonly HttpRequestConfiguration _request; - - private readonly List> _headers; - - private readonly HttpClient _client; - - internal HttpTool( - ToolConfiguration tool, - HttpRequestConfiguration request, - List> headers, - HttpClient client) - : base(tool) - { - _request = request; - _headers = headers; - _client = client; } - protected override async ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) + /// One kind: http tool: one request, one answer. + internal sealed class HttpTool : DeclaredTool { - if (!TryFillUrl(arguments, out var url, out var missing)) - { - return Failed($"the conversation filled no '{missing}', and the URL needs it."); - } + /// The number of characters of a failing body the error result quotes. + private const int BodyQuoteLimit = 500; - using HttpRequestMessage message = new(new HttpMethod(_request.Method), url); + private readonly HttpRequestConfiguration _request; - foreach (var header in _headers) - { - // TryAddWithoutValidation: a document writes the header the endpoint asks for, and the - // client never rewrites it. - message.Headers.TryAddWithoutValidation(header.Key, header.Value); - } + private readonly List> _headers; - using var response = await _client.SendAsync(message, cancellationToken).ConfigureAwait(false); - var body = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false); + private readonly HttpClient _client; - if (!response.IsSuccessStatusCode) + internal HttpTool( + ToolConfiguration tool, + HttpRequestConfiguration request, + List> headers, + HttpClient client) + : base(tool) { - // The status and the body, and never a request header: the header holds the credential. - return Failed( - $"the endpoint answered {((int)response.StatusCode).ToString(CultureInfo.InvariantCulture)} " - + $"{response.StatusCode}. {Quote(body)}"); + _request = request; + _headers = headers; + _client = client; } - // A tool result has no declared shape, and the state layer reads a path into it, so a JSON - // body stays a node tree. Anything else comes back as the text the endpoint wrote. - return TryParse(body, out var node) ? node : body; - } + protected override async ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + if (!TryFillUrl(arguments, out string? url, out string? missing)) + { + return Failed($"the conversation filled no '{missing}', and the URL needs it."); + } - /// Fills every {name} placeholder of the URL from the arguments. - private bool TryFillUrl(AIFunctionArguments arguments, out string url, out string missing) - { - url = _request.Url; - missing = string.Empty; + using HttpRequestMessage message = new(new HttpMethod(_request.Method), url); - var open = url.IndexOf('{', StringComparison.Ordinal); - while (open >= 0) - { - var close = url.IndexOf('}', open + 1); - if (close < 0) + foreach (KeyValuePair header in _headers) { - break; + // TryAddWithoutValidation: a document writes the header the endpoint asks for, and the + // client never rewrites it. + _ = message.Headers.TryAddWithoutValidation(header.Key, header.Value); } - var name = url[(open + 1)..close]; - if (ArgumentText(arguments, name) is not { Length: > 0 } value) + using HttpResponseMessage response = await _client.SendAsync(message, cancellationToken).ConfigureAwait(false); + string body = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false); + + if (!response.IsSuccessStatusCode) { - missing = name; - return false; + // The status and the body, and never a request header: the header holds the credential. + return Failed( + $"the endpoint answered {((int)response.StatusCode).ToString(CultureInfo.InvariantCulture)} " + + $"{response.StatusCode}. {Quote(body)}"); } - var replacement = Uri.EscapeDataString(value); - url = url[..open] + replacement + url[(close + 1)..]; - open = url.IndexOf('{', open + replacement.Length); + // A tool result has no declared shape, and the state layer reads a path into it, so a JSON + // body stays a node tree. Anything else comes back as the text the endpoint wrote. + return TryParse(body, out JsonNode? node) ? node : body; } - return true; - } - - /// Reads a body as JSON, and reports whether it is JSON at all. - private static bool TryParse(string body, out JsonNode? node) - { - node = null; - if (body.Length == 0) + /// Fills every {name} placeholder of the URL from the arguments. + private bool TryFillUrl(AIFunctionArguments arguments, out string url, out string missing) { - return false; + url = _request.Url; + missing = string.Empty; + + int open = url.IndexOf('{', StringComparison.Ordinal); + while (open >= 0) + { + int close = url.IndexOf('}', open + 1); + if (close < 0) + { + break; + } + + string name = url[(open + 1)..close]; + if (ArgumentText(arguments, name) is not { Length: > 0 } value) + { + missing = name; + return false; + } + + string replacement = Uri.EscapeDataString(value); + url = url[..open] + replacement + url[(close + 1)..]; + open = url.IndexOf('{', open + replacement.Length); + } + + return true; } - try + /// Reads a body as JSON, and reports whether it is JSON at all. + private static bool TryParse(string body, out JsonNode? node) { - node = JsonNode.Parse(body); - return true; + node = null; + if (body.Length == 0) + { + return false; + } + + try + { + node = JsonNode.Parse(body); + return true; + } + catch (JsonException) + { + return false; + } } - catch (JsonException) + + /// Cuts a failing body down to the part the model reads. + private static string Quote(string body) { - return false; + return body.Length <= BodyQuoteLimit ? body : body[..BodyQuoteLimit] + "..."; } } - - /// Cuts a failing body down to the part the model reads. - private static string Quote(string body) - => body.Length <= BodyQuoteLimit ? body : body[..BodyQuoteLimit] + "..."; } diff --git a/src/AgentCore.Infrastructure/Tools/Mcp/McpConnectionFactory.cs b/src/AgentCore.Infrastructure/Tools/Mcp/McpConnectionFactory.cs index b9d5e0a0..88de4ab5 100644 --- a/src/AgentCore.Infrastructure/Tools/Mcp/McpConnectionFactory.cs +++ b/src/AgentCore.Infrastructure/Tools/Mcp/McpConnectionFactory.cs @@ -4,99 +4,100 @@ using Microsoft.Extensions.Logging; using ModelContextProtocol.Client; -namespace AgentCore.Infrastructure.Tools.Mcp; - -/// -/// Opens the real connection to one declared MCP server. -/// -internal sealed class McpConnectionFactory +namespace AgentCore.Infrastructure.Tools.Mcp { - private readonly ResolvedSecrets _secrets; + /// + /// Opens the real connection to one declared MCP server. + /// + internal sealed class McpConnectionFactory + { + private readonly ResolvedSecrets _secrets; - private readonly Func? _httpClients; + private readonly Func? _httpClients; - private readonly ILoggerFactory? _loggers; + private readonly ILoggerFactory? _loggers; - /// Creates the factory. - /// The values startup already resolved. - /// - /// Opens the client a transport: http server is reached on, or to - /// let the SDK build its own. A host that passes one keeps its proxy settings, its certificate - /// configuration, and its logging on MCP traffic too, rather than leaving the transport to build - /// an that shares none of them. - /// - /// Where the SDK writes its own lines, or for nowhere. - public McpConnectionFactory( - ResolvedSecrets secrets, - Func? httpClients = null, - ILoggerFactory? loggers = null) - { - ArgumentNullException.ThrowIfNull(secrets); + /// Creates the factory. + /// The values startup already resolved. + /// + /// Opens the client a transport: http server is reached on, or to + /// let the SDK build its own. A host that passes one keeps its proxy settings, its certificate + /// configuration, and its logging on MCP traffic too, rather than leaving the transport to build + /// an that shares none of them. + /// + /// Where the SDK writes its own lines, or for nowhere. + public McpConnectionFactory( + ResolvedSecrets secrets, + Func? httpClients = null, + ILoggerFactory? loggers = null) + { + ArgumentNullException.ThrowIfNull(secrets); - _secrets = secrets; - _httpClients = httpClients; - _loggers = loggers; - } + _secrets = secrets; + _httpClients = httpClients; + _loggers = loggers; + } - /// Opens one connection to one server. - /// The declaration. - /// How long the handshake gets. - /// Cancels the attempt. - /// The connected client. - /// A header or environment value references a name startup did not resolve. - public async ValueTask ConnectAsync( - McpServerConfiguration server, TimeSpan timeout, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(server); + /// Opens one connection to one server. + /// The declaration. + /// How long the handshake gets. + /// Cancels the attempt. + /// The connected client. + /// A header or environment value references a name startup did not resolve. + public async ValueTask ConnectAsync( + McpServerConfiguration server, TimeSpan timeout, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(server); - var transport = Build(server, timeout); - var options = new McpClientOptions { InitializationTimeout = timeout }; + IClientTransport transport = Build(server, timeout); + McpClientOptions options = new() { InitializationTimeout = timeout }; - return await McpClient.CreateAsync(transport, options, _loggers, cancellationToken).ConfigureAwait(false); - } + return await McpClient.CreateAsync(transport, options, _loggers, cancellationToken).ConfigureAwait(false); + } - /// Resolves one map of templates into the plain strings a transport takes. - private Dictionary Resolve(IReadOnlyDictionary entries) - { - Dictionary resolved = new(StringComparer.Ordinal); - foreach (var entry in entries) + /// Resolves one map of templates into the plain strings a transport takes. + private Dictionary Resolve(IReadOnlyDictionary entries) { - resolved[entry.Key] = _secrets.Format(entry.Value); - } + Dictionary resolved = new(StringComparer.Ordinal); + foreach (KeyValuePair entry in entries) + { + resolved[entry.Key] = _secrets.Format(entry.Value); + } - return resolved; - } + return resolved; + } - private IClientTransport Build(McpServerConfiguration server, TimeSpan timeout) - { - if (server.Transport is McpTransport.Http) + private IClientTransport Build(McpServerConfiguration server, TimeSpan timeout) { - var options = new HttpClientTransportOptions + if (server.Transport is McpTransport.Http) { - Endpoint = new Uri(server.Url!), - Name = server.Id, - ConnectionTimeout = timeout, - AdditionalHeaders = Resolve(server.Headers), - }; + HttpClientTransportOptions options = new() + { + Endpoint = new Uri(server.Url!), + Name = server.Id, + ConnectionTimeout = timeout, + AdditionalHeaders = Resolve(server.Headers), + }; - return _httpClients is null - ? new HttpClientTransport(options, _loggers) + return _httpClients is null + ? new HttpClientTransport(options, _loggers) - // ownsClient: false — the pipeline that opened it owns it, and disposing it here - // would take down a handler chain shared with every other vendor call. - : new HttpClientTransport(options, _httpClients(), _loggers, false); - } + // ownsClient: false — the pipeline that opened it owns it, and disposing it here + // would take down a handler chain shared with every other vendor call. + : new HttpClientTransport(options, _httpClients(), _loggers, false); + } - return new StdioClientTransport( - new StdioClientTransportOptions - { - Name = server.Id, - Command = server.Command[0], - Arguments = [.. server.Command.Skip(1)], - EnvironmentVariables = Resolve(server.Env) - .ToDictionary(entry => entry.Key, entry => (string?)entry.Value, StringComparer.Ordinal), - InheritEnvironmentVariables = server.InheritEnv, - }, - _loggers); + return new StdioClientTransport( + new StdioClientTransportOptions + { + Name = server.Id, + Command = server.Command[0], + Arguments = [.. server.Command.Skip(1)], + EnvironmentVariables = Resolve(server.Env) + .ToDictionary(entry => entry.Key, entry => (string?)entry.Value, StringComparer.Ordinal), + InheritEnvironmentVariables = server.InheritEnv, + }, + _loggers); + } } } diff --git a/src/AgentCore.Infrastructure/Tools/Mcp/McpLog.cs b/src/AgentCore.Infrastructure/Tools/Mcp/McpLog.cs index 49f134a1..c9da8359 100644 --- a/src/AgentCore.Infrastructure/Tools/Mcp/McpLog.cs +++ b/src/AgentCore.Infrastructure/Tools/Mcp/McpLog.cs @@ -1,86 +1,87 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.Infrastructure.Tools.Mcp; - -/// -/// Every line an MCP session writes. -/// -/// -/// Source-generated by , so a line nobody listens to costs one -/// level check and allocates nothing. No line carries a header value or an environment value: those -/// are the credentials the document went to the trouble of keeping out of command:. -/// -internal static partial class McpLog +namespace AgentCore.Infrastructure.Tools.Mcp { - /// One connection attempt failed and another is coming. - /// The logger of the session. - /// The mcp: id. - /// The one-based attempt that just failed. - /// How many attempts there are in total. - /// The wait before the next attempt. - /// What went wrong. - [LoggerMessage( - EventId = 100, - Level = LogLevel.Warning, - Message = "MCP server {Server}: connection attempt {Attempt} of {Attempts} failed. " - + "Retrying in {BackoffMs}ms.")] - public static partial void ConnectAttemptFailed( - ILogger logger, string server, int attempt, int attempts, double backoffMs, Exception error); + /// + /// Every line an MCP session writes. + /// + /// + /// Source-generated by , so a line nobody listens to costs one + /// level check and allocates nothing. No line carries a header value or an environment value: those + /// are the credentials the document went to the trouble of keeping out of command:. + /// + internal static partial class McpLog + { + /// One connection attempt failed and another is coming. + /// The logger of the session. + /// The mcp: id. + /// The one-based attempt that just failed. + /// How many attempts there are in total. + /// The wait before the next attempt. + /// What went wrong. + [LoggerMessage( + EventId = 100, + Level = LogLevel.Warning, + Message = "MCP server {Server}: connection attempt {Attempt} of {Attempts} failed. " + + "Retrying in {BackoffMs}ms.")] + public static partial void ConnectAttemptFailed( + ILogger logger, string server, int attempt, int attempts, double backoffMs, Exception error); - /// A tool call failed on the connection, and the session is about to replace it. - /// The logger of the session. - /// The mcp: id. - /// The remote tool name. - /// What went wrong. - [LoggerMessage( - EventId = 101, - Level = LogLevel.Warning, - Message = "MCP server {Server}: the conversation to '{Tool}' failed on the connection. " - + "Reconnecting once and repeating it.")] - public static partial void ConversationFailedReconnecting(ILogger logger, string server, string tool, Exception error); + /// A tool call failed on the connection, and the session is about to replace it. + /// The logger of the session. + /// The mcp: id. + /// The remote tool name. + /// What went wrong. + [LoggerMessage( + EventId = 101, + Level = LogLevel.Warning, + Message = "MCP server {Server}: the conversation to '{Tool}' failed on the connection. " + + "Reconnecting once and repeating it.")] + public static partial void ConversationFailedReconnecting(ILogger logger, string server, string tool, Exception error); - /// A connection would not close cleanly. - /// The logger of the session. - /// The mcp: id. - /// What went wrong. - [LoggerMessage( - EventId = 102, - Level = LogLevel.Warning, - Message = "MCP server {Server}: closing the connection failed. If it is a stdio server, its " - + "child process may still be running.")] - public static partial void CloseFailed(ILogger logger, string server, Exception error); + /// A connection would not close cleanly. + /// The logger of the session. + /// The mcp: id. + /// What went wrong. + [LoggerMessage( + EventId = 102, + Level = LogLevel.Warning, + Message = "MCP server {Server}: closing the connection failed. If it is a stdio server, its " + + "child process may still be running.")] + public static partial void CloseFailed(ILogger logger, string server, Exception error); - /// The server withdrew tools this service is still serving ids for. - /// The logger of the session. - /// The mcp: id. - /// The remote tool names the server stopped offering. - [LoggerMessage( - EventId = 103, - Level = LogLevel.Warning, - Message = "MCP server {Server}: stopped offering {Dropped}. The served tool set is fixed at boot " - + "and does not shrink, so calls to those ids now return an error the model can read.")] - public static partial void ToolsDropped(ILogger logger, string server, string dropped); + /// The server withdrew tools this service is still serving ids for. + /// The logger of the session. + /// The mcp: id. + /// The remote tool names the server stopped offering. + [LoggerMessage( + EventId = 103, + Level = LogLevel.Warning, + Message = "MCP server {Server}: stopped offering {Dropped}. The served tool set is fixed at boot " + + "and does not shrink, so calls to those ids now return an error the model can read.")] + public static partial void ToolsDropped(ILogger logger, string server, string dropped); - /// The server changed the arguments of a tool this service is already serving. - /// The logger of the session. - /// The mcp: id. - /// The remote tool names whose schema no longer matches. - [LoggerMessage( - EventId = 105, - Level = LogLevel.Warning, - Message = "MCP server {Server}: changed the arguments of {Drifted}. The model keeps the schema it " - + "was given at boot, because rewriting a prompt during a live conversation is worse than a stale " - + "one. Restart this service to pick the new schema up.")] - public static partial void ToolSchemasDrifted(ILogger logger, string server, string drifted); + /// The server changed the arguments of a tool this service is already serving. + /// The logger of the session. + /// The mcp: id. + /// The remote tool names whose schema no longer matches. + [LoggerMessage( + EventId = 105, + Level = LogLevel.Warning, + Message = "MCP server {Server}: changed the arguments of {Drifted}. The model keeps the schema it " + + "was given at boot, because rewriting a prompt during a live conversation is worse than a stale " + + "one. Restart this service to pick the new schema up.")] + public static partial void ToolSchemasDrifted(ILogger logger, string server, string drifted); - /// The re-list after a tools/list_changed notification failed. - /// The logger of the session. - /// The mcp: id. - /// What went wrong. - [LoggerMessage( - EventId = 104, - Level = LogLevel.Warning, - Message = "MCP server {Server}: re-listing tools after a tools/list_changed notification failed. " - + "The record of what it offers is now stale.")] - public static partial void ReListFailed(ILogger logger, string server, Exception error); + /// The re-list after a tools/list_changed notification failed. + /// The logger of the session. + /// The mcp: id. + /// What went wrong. + [LoggerMessage( + EventId = 104, + Level = LogLevel.Warning, + Message = "MCP server {Server}: re-listing tools after a tools/list_changed notification failed. " + + "The record of what it offers is now stale.")] + public static partial void ReListFailed(ILogger logger, string server, Exception error); + } } diff --git a/src/AgentCore.Infrastructure/Tools/Mcp/McpServerSession.cs b/src/AgentCore.Infrastructure/Tools/Mcp/McpServerSession.cs index 0ea93d08..68d0fda0 100644 --- a/src/AgentCore.Infrastructure/Tools/Mcp/McpServerSession.cs +++ b/src/AgentCore.Infrastructure/Tools/Mcp/McpServerSession.cs @@ -4,452 +4,458 @@ using ModelContextProtocol.Client; using ModelContextProtocol.Protocol; -namespace AgentCore.Infrastructure.Tools.Mcp; - -/// -/// Raised when a call names a tool the server has since stopped offering. -/// -/// The remote tool name. -internal sealed class McpToolGoneException(string toolName) - : InvalidOperationException($"the server no longer offers a tool named '{toolName}'") +namespace AgentCore.Infrastructure.Tools.Mcp { - /// Gets the remote tool name the server dropped. - public string ToolName { get; } = toolName; -} - -/// -/// One declared mcp: server, for as long as the process runs. -/// -internal sealed class McpServerSession : IAsyncDisposable -{ - /// How long one connection attempt gets when the document names nothing. - internal static readonly TimeSpan DefaultConnectTimeout = TimeSpan.FromSeconds(10); + /// + /// Raised when a call names a tool the server has since stopped offering. + /// + /// The remote tool name. + internal sealed class McpToolGoneException(string toolName) + : InvalidOperationException($"the server no longer offers a tool named '{toolName}'") + { + /// Gets the remote tool name the server dropped. + public string ToolName { get; } = toolName; + } - /// How long one tool call gets when the document names nothing. - internal static readonly TimeSpan DefaultCallTimeout = TimeSpan.FromSeconds(30); + /// + /// One declared mcp: server, for as long as the process runs. + /// + internal sealed class McpServerSession : IAsyncDisposable + { + /// How long one connection attempt gets when the document names nothing. + internal static readonly TimeSpan DefaultConnectTimeout = TimeSpan.FromSeconds(10); - /// The number of connection attempts, including the first, when the document names none. - internal const int DefaultRetryAttempts = 3; + /// How long one tool call gets when the document names nothing. + internal static readonly TimeSpan DefaultCallTimeout = TimeSpan.FromSeconds(30); - /// The wait before the second connection attempt when the document names none. - internal static readonly TimeSpan DefaultRetryBackoff = TimeSpan.FromSeconds(1); + /// The number of connection attempts, including the first, when the document names none. + internal const int DefaultRetryAttempts = 3; - private readonly McpServerConfiguration _server; + /// The wait before the second connection attempt when the document names none. + internal static readonly TimeSpan DefaultRetryBackoff = TimeSpan.FromSeconds(1); - private readonly Func> _connect; + private readonly McpServerConfiguration _server; - private readonly ILogger _log; + private readonly Func> _connect; - private readonly SemaphoreSlim _gate = new(1, 1); + private readonly ILogger _log; - private McpClient? _client; + private readonly SemaphoreSlim _gate = new(1, 1); - /// Guards , which is replaced wholesale rather than mutated. - private readonly Lock _offeredSync = new(); + private McpClient? _client; - /// What the server still answers for, by remote name, against the schema it last gave. - private Dictionary _offered = new(StringComparer.Ordinal); + /// Guards , which is replaced wholesale rather than mutated. + private readonly Lock _offeredSync = new(); - private bool _disposed; + /// What the server still answers for, by remote name, against the schema it last gave. + private Dictionary _offered = new(StringComparer.Ordinal); - /// Creates the session over a connect step a test substitutes. - /// The declaration this session is the one server of. - /// - /// Opens one connection, within the timeout given. It is called once per attempt, and again on - /// every reconnect, so it must build a fresh transport each time — a transport that has already - /// carried a session cannot carry another. - /// - /// Where the reconnect and drop lines are written, or for nowhere. - internal McpServerSession( - McpServerConfiguration server, - Func> connect, - ILoggerFactory? loggers = null) - { - ArgumentNullException.ThrowIfNull(server); - ArgumentNullException.ThrowIfNull(connect); + private bool _disposed; - _server = server; - _connect = connect; - _log = loggers?.CreateLogger() ?? NullLogger.Instance; - } + /// Creates the session over a connect step a test substitutes. + /// The declaration this session is the one server of. + /// + /// Opens one connection, within the timeout given. It is called once per attempt, and again on + /// every reconnect, so it must build a fresh transport each time — a transport that has already + /// carried a session cannot carry another. + /// + /// Where the reconnect and drop lines are written, or for nowhere. + internal McpServerSession( + McpServerConfiguration server, + Func> connect, + ILoggerFactory? loggers = null) + { + ArgumentNullException.ThrowIfNull(server); + ArgumentNullException.ThrowIfNull(connect); - /// Gets the id the document declares this server under. - public string Id => _server.Id; - - /// Gets how long one tool call on this server may take. - public TimeSpan CallTimeout => Seconds(_server.CallTimeoutSeconds) ?? DefaultCallTimeout; - - /// Connects, and reports every tool the server offers. - /// Cancels the whole attempt sequence. - /// One descriptor per offered tool, in the order the server listed them. - /// Every attempt ran out of time. - /// - /// A failed attempt is retried with a doubling backoff, because the case this exists for is a - /// cold start — npx fetching a package, a container still warming up — where a healthy - /// server answers nothing at all on the first try. The last attempt's failure is what leaves. - /// - public async ValueTask> OpenAsync( - CancellationToken cancellationToken = default) - { - var attempts = _server.Retry?.Attempts ?? DefaultRetryAttempts; + _server = server; + _connect = connect; + _log = loggers?.CreateLogger() ?? NullLogger.Instance; + } - var backoff = _server.Retry?.BackoffMs is { } ms - ? TimeSpan.FromMilliseconds(ms) - : DefaultRetryBackoff; + /// Gets the id the document declares this server under. + public string Id => _server.Id; + + /// Gets how long one tool call on this server may take. + public TimeSpan CallTimeout => Seconds(_server.CallTimeoutSeconds) ?? DefaultCallTimeout; + + /// Connects, and reports every tool the server offers. + /// Cancels the whole attempt sequence. + /// One descriptor per offered tool, in the order the server listed them. + /// Every attempt ran out of time. + /// + /// A failed attempt is retried with a doubling backoff, because the case this exists for is a + /// cold start — npx fetching a package, a container still warming up — where a healthy + /// server answers nothing at all on the first try. The last attempt's failure is what leaves. + /// + public async ValueTask> OpenAsync( + CancellationToken cancellationToken = default) + { + int attempts = _server.Retry?.Attempts ?? DefaultRetryAttempts; - Exception? last = null; + TimeSpan backoff = _server.Retry?.BackoffMs is { } ms + ? TimeSpan.FromMilliseconds(ms) + : DefaultRetryBackoff; - for (var attempt = 1; attempt <= attempts; attempt++) - { - cancellationToken.ThrowIfCancellationRequested(); + Exception? last = null; - try - { - return await ConnectAndListAsync(cancellationToken).ConfigureAwait(false); - } - catch (Exception ex) when (ex is not OperationCanceledException) + for (int attempt = 1; attempt <= attempts; attempt++) { - last = ex; + cancellationToken.ThrowIfCancellationRequested(); - if (attempt == attempts) + try { - break; + return await ConnectAndListAsync(cancellationToken).ConfigureAwait(false); } + catch (Exception ex) when (ex is not OperationCanceledException) + { + last = ex; - McpLog.ConnectAttemptFailed(_log, _server.Id, attempt, attempts, backoff.TotalMilliseconds, ex); - - await Task.Delay(backoff, cancellationToken).ConfigureAwait(false); + if (attempt == attempts) + { + break; + } - backoff += backoff; - } - } + McpLog.ConnectAttemptFailed(_log, _server.Id, attempt, attempts, backoff.TotalMilliseconds, ex); - throw last!; - } + await Task.Delay(backoff, cancellationToken).ConfigureAwait(false); - /// Calls one tool, reconnecting once if the connection has died since the last conversation. - /// The name the server offers the tool under, never the served id. - /// The arguments the model filled. - /// Cancels the conversation. - /// Whatever the server answered, error results included. - /// The server has stopped offering the tool. - /// The session is closed. - /// - /// One reconnect and one repeat, so a server that died between two turns of a telephone conversation - /// costs the caller a pause rather than the turn. A second failure is the caller's answer: a - /// server that is down stays down, and repeating past that only spends the call timeout. - /// - public async ValueTask CallAsync( - string toolName, - IReadOnlyDictionary arguments, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(toolName); - ArgumentNullException.ThrowIfNull(arguments); - ObjectDisposedException.ThrowIf(_disposed, this); + backoff += backoff; + } + } - if (!Offers(toolName)) - { - throw new McpToolGoneException(toolName); + throw last!; } - var client = await CurrentAsync(cancellationToken).ConfigureAwait(false); - - Exception? died; - - try - { - return await SendAsync(client, toolName, arguments, cancellationToken).ConfigureAwait(false); - } - catch (Exception ex) when (ex is not OperationCanceledException and not McpToolGoneException) + /// Calls one tool, reconnecting once if the connection has died since the last conversation. + /// The name the server offers the tool under, never the served id. + /// The arguments the model filled. + /// Cancels the conversation. + /// Whatever the server answered, error results included. + /// The server has stopped offering the tool. + /// The session is closed. + /// + /// One reconnect and one repeat, so a server that died between two turns of a telephone conversation + /// costs the caller a pause rather than the turn. A second failure is the caller's answer: a + /// server that is down stays down, and repeating past that only spends the call timeout. + /// + public async ValueTask CallAsync( + string toolName, + IReadOnlyDictionary arguments, + CancellationToken cancellationToken = default) { - // The connection, not the tool: a tool that fails on its own terms answers with - // CallToolResult.IsError and never throws. - died = ex; - } + ArgumentNullException.ThrowIfNull(toolName); + ArgumentNullException.ThrowIfNull(arguments); + ObjectDisposedException.ThrowIf(_disposed, this); - McpLog.ConversationFailedReconnecting(_log, _server.Id, toolName, died); + if (!Offers(toolName)) + { + throw new McpToolGoneException(toolName); + } - var reopened = await ReconnectAsync(client, cancellationToken).ConfigureAwait(false); + McpClient client = await CurrentAsync(cancellationToken).ConfigureAwait(false); - // The reconnect re-listed, so the tool may have gone in the meantime — a server that came - // back offering less is exactly the case a raw protocol fault must not reach the model. - if (!Offers(toolName)) - { - throw new McpToolGoneException(toolName); - } + Exception? died; - return await SendAsync(reopened, toolName, arguments, cancellationToken).ConfigureAwait(false); - } + try + { + return await SendAsync(client, toolName, arguments, cancellationToken).ConfigureAwait(false); + } + catch (Exception ex) when (ex is not OperationCanceledException and not McpToolGoneException) + { + // The connection, not the tool: a tool that fails on its own terms answers with + // CallToolResult.IsError and never throws. + died = ex; + } - /// Sends one call, and gives up the moment the session behind it ends. - private static async ValueTask SendAsync( - McpClient client, - string toolName, - IReadOnlyDictionary arguments, - CancellationToken cancellationToken) - { - var conversation = client.CallToolAsync(toolName, arguments, cancellationToken: cancellationToken).AsTask(); - var finished = await Task.WhenAny(conversation, client.Completion).ConfigureAwait(false); + McpLog.ConversationFailedReconnecting(_log, _server.Id, toolName, died); - if (ReferenceEquals(finished, conversation)) - { - return await conversation.ConfigureAwait(false); - } + McpClient reopened = await ReconnectAsync(client, cancellationToken).ConfigureAwait(false); - // The conversation is never going to be answered now, but it is still a live task holding an - // exception nobody has looked at. Observing it keeps that from surfacing later as an - // unhandled fault on a finalizer thread, with no context left to say where it came from. - Observe(conversation); + // The reconnect re-listed, so the tool may have gone in the meantime — a server that came + // back offering less is exactly the case a raw protocol fault must not reach the model. + return !Offers(toolName) + ? throw new McpToolGoneException(toolName) + : await SendAsync(reopened, toolName, arguments, cancellationToken).ConfigureAwait(false); + } - throw Ended(await client.Completion.ConfigureAwait(false)); - } + /// Sends one call, and gives up the moment the session behind it ends. + private static async ValueTask SendAsync( + McpClient client, + string toolName, + IReadOnlyDictionary arguments, + CancellationToken cancellationToken) + { + Task conversation = client.CallToolAsync(toolName, arguments, cancellationToken: cancellationToken).AsTask(); + Task finished = await Task.WhenAny(conversation, client.Completion).ConfigureAwait(false); - /// Swallows the outcome of a task that has already lost its race. - private static void Observe(Task task) - => _ = task.ContinueWith( - static finished => _ = finished.Exception, - CancellationToken.None, - TaskContinuationOptions.OnlyOnFaulted | TaskContinuationOptions.ExecuteSynchronously, - TaskScheduler.Default); + if (ReferenceEquals(finished, conversation)) + { + return await conversation.ConfigureAwait(false); + } - /// Turns a finished session into the exception the conversation itself never threw. - private static IOException Ended(ClientCompletionDetails details) - { - var why = details.Exception?.Message ?? "it closed the connection"; - if (details is StdioClientCompletionDetails stdio) - { - var exit = stdio.ExitCode is { } code ? $" (exit code {code})" : string.Empty; - var tail = stdio.StandardErrorTail is { Count: > 0 } lines - ? $" Its last standard error was: {string.Join(" ", lines)}" - : string.Empty; + // The conversation is never going to be answered now, but it is still a live task holding an + // exception nobody has looked at. Observing it keeps that from surfacing later as an + // unhandled fault on a finalizer thread, with no context left to say where it came from. + Observe(conversation); - return new IOException($"the server process ended{exit}: {why}.{tail}", details.Exception); + throw Ended(await client.Completion.ConfigureAwait(false)); } - return new IOException($"the server session ended: {why}.", details.Exception); - } - - /// - public async ValueTask DisposeAsync() - { - if (_disposed) + /// Swallows the outcome of a task that has already lost its race. + private static void Observe(Task task) { - return; + _ = task.ContinueWith( + static finished => _ = finished.Exception, + CancellationToken.None, + TaskContinuationOptions.OnlyOnFaulted | TaskContinuationOptions.ExecuteSynchronously, + TaskScheduler.Default); } - _disposed = true; - - await CloseAsync(Interlocked.Exchange(ref _client, null)).ConfigureAwait(false); + /// Turns a finished session into the exception the conversation itself never threw. + private static IOException Ended(ClientCompletionDetails details) + { + string why = details.Exception?.Message ?? "it closed the connection"; + if (details is StdioClientCompletionDetails stdio) + { + string exit = stdio.ExitCode is { } code ? $" (exit code {code})" : string.Empty; + string tail = stdio.StandardErrorTail is { Count: > 0 } lines + ? $" Its last standard error was: {string.Join(" ", lines)}" + : string.Empty; - _gate.Dispose(); - } + return new IOException($"the server process ended{exit}: {why}.{tail}", details.Exception); + } - /// Reads a seconds value the document wrote, if it wrote one. - private static TimeSpan? Seconds(int? value) - => value is { } seconds ? TimeSpan.FromSeconds(seconds) : null; + return new IOException($"the server session ended: {why}.", details.Exception); + } - private bool Offers(string toolName) - { - lock (_offeredSync) + /// + public async ValueTask DisposeAsync() { - return _offered.ContainsKey(toolName); - } - } + if (_disposed) + { + return; + } - /// Opens one connection, lists what it offers, and keeps both. - private async ValueTask> ConnectAndListAsync(CancellationToken cancellationToken) - { - var timeout = Seconds(_server.ConnectTimeoutSeconds) ?? DefaultConnectTimeout; + _disposed = true; - using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - deadline.CancelAfter(timeout); + await CloseAsync(Interlocked.Exchange(ref _client, null)).ConfigureAwait(false); - McpClient? opened = null; - McpClient client; - IList offered; + _gate.Dispose(); + } - try + /// Reads a seconds value the document wrote, if it wrote one. + private static TimeSpan? Seconds(int? value) { - client = opened = await _connect(timeout, deadline.Token).ConfigureAwait(false); - offered = await client.ListToolsAsync(cancellationToken: deadline.Token).ConfigureAwait(false); + return value is { } seconds ? TimeSpan.FromSeconds(seconds) : null; } - catch (OperationCanceledException) when (deadline.IsCancellationRequested && !cancellationToken.IsCancellationRequested) - { - await CloseAsync(opened).ConfigureAwait(false); - throw TimedOut(timeout); - } - catch (TimeoutException) + private bool Offers(string toolName) { - // The SDK's InitializationTimeout runs the same length as the deadline, so either clock - // can fire first. The SDK's message does not name the knob, so it is replaced. - await CloseAsync(opened).ConfigureAwait(false); - - throw TimedOut(timeout); + lock (_offeredSync) + { + return _offered.ContainsKey(toolName); + } } - catch + + /// Opens one connection, lists what it offers, and keeps both. + private async ValueTask> ConnectAndListAsync(CancellationToken cancellationToken) { - await CloseAsync(opened).ConfigureAwait(false); + TimeSpan timeout = Seconds(_server.ConnectTimeoutSeconds) ?? DefaultConnectTimeout; - throw; - } + using CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + deadline.CancelAfter(timeout); + + McpClient? opened = null; + McpClient client; + IList offered; - var descriptors = offered.Select(Describe).ToArray(); + try + { + client = opened = await _connect(timeout, deadline.Token).ConfigureAwait(false); + offered = await client.ListToolsAsync(cancellationToken: deadline.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested && !cancellationToken.IsCancellationRequested) + { + await CloseAsync(opened).ConfigureAwait(false); - Remember(descriptors); - Subscribe(client); + throw TimedOut(timeout); + } + catch (TimeoutException) + { + // The SDK's InitializationTimeout runs the same length as the deadline, so either clock + // can fire first. The SDK's message does not name the knob, so it is replaced. + await CloseAsync(opened).ConfigureAwait(false); - // The replaced client is already known to be broken — that is why it is being replaced. It is - // closed only so a stdio server's child process is not left running. - await CloseAsync(Interlocked.Exchange(ref _client, client)).ConfigureAwait(false); + throw TimedOut(timeout); + } + catch + { + await CloseAsync(opened).ConfigureAwait(false); - return descriptors; - } + throw; + } - /// Names the timeout and the knob that raises it, whichever clock noticed first. - private TimeoutException TimedOut(TimeSpan timeout) - => new( - $"the MCP server '{_server.Id}' did not finish connecting within {timeout.TotalSeconds:0.###}s. " - + "Raise connectTimeoutSeconds if the server is simply slow to start."); + McpToolDescriptor[] descriptors = [.. offered.Select(Describe)]; - /// Closes one connection, and never lets the closing itself become the failure. - private async ValueTask CloseAsync(McpClient? client) - { - if (client is null) - { - return; - } + _ = Remember(descriptors); + Subscribe(client); - try - { - await client.DisposeAsync().ConfigureAwait(false); + // The replaced client is already known to be broken — that is why it is being replaced. It is + // closed only so a stdio server's child process is not left running. + await CloseAsync(Interlocked.Exchange(ref _client, client)).ConfigureAwait(false); + + return descriptors; } - catch (Exception ex) + + /// Names the timeout and the knob that raises it, whichever clock noticed first. + private TimeoutException TimedOut(TimeSpan timeout) { - McpLog.CloseFailed(_log, _server.Id, ex); + return new( + $"the MCP server '{_server.Id}' did not finish connecting within {timeout.TotalSeconds:0.###}s. " + + "Raise connectTimeoutSeconds if the server is simply slow to start."); } - } - /// Replaces the connection, unless another caller already did. - /// The client the caller found broken. - /// Cancels the reconnect. - /// The live client. - private async ValueTask ReconnectAsync(McpClient dead, CancellationToken cancellationToken) - { - await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); - try + /// Closes one connection, and never lets the closing itself become the failure. + private async ValueTask CloseAsync(McpClient? client) { - ObjectDisposedException.ThrowIf(_disposed, this); - - // Two conversations can fail against one dead client at once. The first through here replaces it; - // the second must use that replacement rather than open a third connection. - if (!ReferenceEquals(_client, dead)) + if (client is null) { - return _client ?? throw new ObjectDisposedException(nameof(McpServerSession)); + return; } - await ConnectAndListAsync(cancellationToken).ConfigureAwait(false); - return _client; - } - finally - { - _gate.Release(); + try + { + await client.DisposeAsync().ConfigureAwait(false); + } + catch (Exception ex) + { + McpLog.CloseFailed(_log, _server.Id, ex); + } } - } - /// Returns the live connection, opening one if the session has none. - /// - /// A client whose has already finished is replaced before it - /// is handed out, rather than after a conversation has been spent discovering it. That is the ordinary - /// case for a stdio server whose child crashed between two turns of a conversation. - /// - private async ValueTask CurrentAsync(CancellationToken cancellationToken) - { - if (_client is { } live && !live.Completion.IsCompleted) + /// Replaces the connection, unless another caller already did. + /// The client the caller found broken. + /// Cancels the reconnect. + /// The live client. + private async ValueTask ReconnectAsync(McpClient dead, CancellationToken cancellationToken) { - return live; - } + await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); + try + { + ObjectDisposedException.ThrowIf(_disposed, this); - if (_client is { } dead) - { - return await ReconnectAsync(dead, cancellationToken).ConfigureAwait(false); - } + // Two conversations can fail against one dead client at once. The first through here replaces it; + // the second must use that replacement rather than open a third connection. + if (!ReferenceEquals(_client, dead)) + { + return _client ?? throw new ObjectDisposedException(nameof(McpServerSession)); + } - await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); + _ = await ConnectAndListAsync(cancellationToken).ConfigureAwait(false); + return _client; + } + finally + { + _ = _gate.Release(); + } + } - try + /// Returns the live connection, opening one if the session has none. + /// + /// A client whose has already finished is replaced before it + /// is handed out, rather than after a conversation has been spent discovering it. That is the ordinary + /// case for a stdio server whose child crashed between two turns of a conversation. + /// + private async ValueTask CurrentAsync(CancellationToken cancellationToken) { - ObjectDisposedException.ThrowIf(_disposed, this); - if (_client is { } opened) + if (_client is { } live && !live.Completion.IsCompleted) { - return opened; + return live; } - await ConnectAndListAsync(cancellationToken).ConfigureAwait(false); - return _client!; - } - finally - { - _gate.Release(); - } - } + if (_client is { } dead) + { + return await ReconnectAsync(dead, cancellationToken).ConfigureAwait(false); + } - /// Records what the server currently answers for, and reports what changed. - /// The tools the server just listed. - /// The names that have gone, and the names whose schema no longer matches. - private (string[] Dropped, string[] Drifted) Remember(IEnumerable offered) - { - Dictionary current = new(StringComparer.Ordinal); - foreach (var tool in offered) - { - current[tool.Name] = tool.JsonSchema.GetRawText(); + await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); + + try + { + ObjectDisposedException.ThrowIf(_disposed, this); + if (_client is { } opened) + { + return opened; + } + + _ = await ConnectAndListAsync(cancellationToken).ConfigureAwait(false); + return _client!; + } + finally + { + _ = _gate.Release(); + } } - lock (_offeredSync) + /// Records what the server currently answers for, and reports what changed. + /// The tools the server just listed. + /// The names that have gone, and the names whose schema no longer matches. + private (string[] Dropped, string[] Drifted) Remember(IEnumerable offered) { - var previous = _offered; - _offered = current; - - return ( - [.. previous.Keys.Where(name => !current.ContainsKey(name))], - [.. previous - .Where(was => current.TryGetValue(was.Key, out var now) && !string.Equals(was.Value, now, StringComparison.Ordinal)) - .Select(was => was.Key)]); - } - } + Dictionary current = new(StringComparer.Ordinal); + foreach (McpToolDescriptor tool in offered) + { + current[tool.Name] = tool.JsonSchema.GetRawText(); + } - /// Follows tools/list_changed, so a dropped tool fails as itself. - private void Subscribe(McpClient client) - { - client.RegisterNotificationHandler( - NotificationMethods.ToolListChangedNotification, - async (_, ct) => + lock (_offeredSync) { - try - { - var offered = await client.ListToolsAsync(cancellationToken: ct).ConfigureAwait(false); - var (dropped, drifted) = Remember(offered.Select(Describe)); + Dictionary previous = _offered; + _offered = current; + + return ( + [.. previous.Keys.Where(name => !current.ContainsKey(name))], + [.. previous + .Where(was => current.TryGetValue(was.Key, out string? now) && !string.Equals(was.Value, now, StringComparison.Ordinal)) + .Select(was => was.Key)]); + } + } - if (dropped.Length > 0) + /// Follows tools/list_changed, so a dropped tool fails as itself. + private void Subscribe(McpClient client) + { + _ = client.RegisterNotificationHandler( + NotificationMethods.ToolListChangedNotification, + async (_, ct) => + { + try { - McpLog.ToolsDropped(_log, _server.Id, string.Join(", ", dropped)); + IList offered = await client.ListToolsAsync(cancellationToken: ct).ConfigureAwait(false); + (string[]? dropped, string[]? drifted) = Remember(offered.Select(Describe)); + + if (dropped.Length > 0) + { + McpLog.ToolsDropped(_log, _server.Id, string.Join(", ", dropped)); + } + + if (drifted.Length > 0) + { + McpLog.ToolSchemasDrifted(_log, _server.Id, string.Join(", ", drifted)); + } } - - if (drifted.Length > 0) + catch (Exception ex) when (ex is not OperationCanceledException) { - McpLog.ToolSchemasDrifted(_log, _server.Id, string.Join(", ", drifted)); + // A notification handler that throws would take down the connection's read loop, + // which is a far worse outcome than a stale list. + McpLog.ReListFailed(_log, _server.Id, ex); } - } - catch (Exception ex) when (ex is not OperationCanceledException) - { - // A notification handler that throws would take down the connection's read loop, - // which is a far worse outcome than a stale list. - McpLog.ReListFailed(_log, _server.Id, ex); - } - }); - } + }); + } - private static McpToolDescriptor Describe(McpClientTool tool) - => new(tool.Name, tool.Description, tool.JsonSchema); + private static McpToolDescriptor Describe(McpClientTool tool) + { + return new(tool.Name, tool.Description, tool.JsonSchema); + } + } } diff --git a/src/AgentCore.Infrastructure/Tools/Mcp/McpTool.cs b/src/AgentCore.Infrastructure/Tools/Mcp/McpTool.cs index 86659e0e..14b895d1 100644 --- a/src/AgentCore.Infrastructure/Tools/Mcp/McpTool.cs +++ b/src/AgentCore.Infrastructure/Tools/Mcp/McpTool.cs @@ -9,137 +9,143 @@ // serializer cannot hold — forwarding everything faulted every call. Revisit if the SDK ever lets a // conversation exclude entries, or if the turn stops riding along in tool arguments. -namespace AgentCore.Infrastructure.Tools.Mcp; - -/// -/// One tool an MCP server serves, under the id the document gives it. -/// -internal sealed class McpTool : AIFunction +namespace AgentCore.Infrastructure.Tools.Mcp { - private readonly McpServerSession _session; - - private readonly McpToolDescriptor _descriptor; + /// + /// One tool an MCP server serves, under the id the document gives it. + /// + internal sealed class McpTool : AIFunction + { + private readonly McpServerSession _session; - private readonly string _id; + private readonly McpToolDescriptor _descriptor; - private readonly HashSet? _declared; + private readonly string _id; - /// Creates the tool. - /// The server this tool is called on. - /// The tool as the server described it when the session opened. - /// The served id: <server>.<tool>, or the as: alias. - public McpTool(McpServerSession session, McpToolDescriptor descriptor, string id) - { - ArgumentNullException.ThrowIfNull(session); - ArgumentNullException.ThrowIfNull(descriptor); - ArgumentNullException.ThrowIfNull(id); - - _session = session; - _descriptor = descriptor; - _id = id; - _declared = DeclaredProperties(descriptor.JsonSchema); - } + private readonly HashSet? _declared; - /// Reads the property names one tool schema declares, if it declares any. - /// The schema the server listed for this tool. - /// The names, or when the schema names none. - private static HashSet? DeclaredProperties(JsonElement schema) - { - if (schema.ValueKind is not JsonValueKind.Object - || !schema.TryGetProperty("properties", out var properties) - || properties.ValueKind is not JsonValueKind.Object) + /// Creates the tool. + /// The server this tool is called on. + /// The tool as the server described it when the session opened. + /// The served id: <server>.<tool>, or the as: alias. + public McpTool(McpServerSession session, McpToolDescriptor descriptor, string id) { - return null; + ArgumentNullException.ThrowIfNull(session); + ArgumentNullException.ThrowIfNull(descriptor); + ArgumentNullException.ThrowIfNull(id); + + _session = session; + _descriptor = descriptor; + _id = id; + _declared = DeclaredProperties(descriptor.JsonSchema); } - HashSet names = new(StringComparer.Ordinal); - foreach (var property in properties.EnumerateObject()) + /// Reads the property names one tool schema declares, if it declares any. + /// The schema the server listed for this tool. + /// The names, or when the schema names none. + private static HashSet? DeclaredProperties(JsonElement schema) { - names.Add(property.Name); - } + if (schema.ValueKind is not JsonValueKind.Object + || !schema.TryGetProperty("properties", out JsonElement properties) + || properties.ValueKind is not JsonValueKind.Object) + { + return null; + } - return names; - } + HashSet names = new(StringComparer.Ordinal); + foreach (JsonProperty property in properties.EnumerateObject()) + { + _ = names.Add(property.Name); + } - /// - public override string Name => _id; + return names; + } - /// - public override string Description => _descriptor.Description; + /// + public override string Name => _id; - /// - public override JsonElement JsonSchema => _descriptor.JsonSchema; + /// + public override string Description => _descriptor.Description; - /// - protected override async ValueTask InvokeCoreAsync( - AIFunctionArguments arguments, CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(arguments); + /// + public override JsonElement JsonSchema => _descriptor.JsonSchema; - try + /// + protected override async ValueTask InvokeCoreAsync( + AIFunctionArguments arguments, CancellationToken cancellationToken) { - // The model is built against this schema, so anything outside it is harness - // residue rather than model intent: the filed turn carries delegates no JSON - // writer can hold. A schema that names no properties keeps the old passthrough. - var outgoing = arguments; - if (_declared is { } declared) + ArgumentNullException.ThrowIfNull(arguments); + + try { - outgoing = []; - foreach (var entry in arguments.Where(candidate => declared.Contains(candidate.Key))) + // The model is built against this schema, so anything outside it is harness + // residue rather than model intent: the filed turn carries delegates no JSON + // writer can hold. A schema that names no properties keeps the old passthrough. + AIFunctionArguments outgoing = arguments; + if (_declared is { } declared) { - outgoing[entry.Key] = entry.Value; + outgoing = []; + foreach (KeyValuePair entry in arguments.Where(candidate => declared.Contains(candidate.Key))) + { + outgoing[entry.Key] = entry.Value; + } } - } - var answer = await _session.CallAsync(_descriptor.Name, outgoing, cancellationToken) - .ConfigureAwait(false); + CallToolResult answer = await _session.CallAsync(_descriptor.Name, outgoing, cancellationToken) + .ConfigureAwait(false); - return Unwrap(answer); - } - catch (McpToolGoneException) - { - return Failed( - $"the MCP server '{_session.Id}' no longer offers this tool. It was offered when this " - + "service started, and the server has since withdrawn it."); + return Unwrap(answer); + } + catch (McpToolGoneException) + { + return Failed( + $"the MCP server '{_session.Id}' no longer offers this tool. It was offered when this " + + "service started, and the server has since withdrawn it."); + } + catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + { + return Failed($"the call to the MCP server '{_session.Id}' ran out of time."); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + return Failed($"the MCP server '{_session.Id}' could not be reached: {ex.GetBaseException().Message}"); + } } - catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + + /// Reads the answer out of the envelope the protocol wraps it in. + /// What the server sent back. + /// The answer itself, or an error result when the tool failed on its own terms. + private object? Unwrap(CallToolResult answer) { - return Failed($"the call to the MCP server '{_session.Id}' ran out of time."); + string text = TextOf(answer); + + // A tool that fails answers in the one error shape, whichever way it failed. + // The protocol's own failure flag is not that shape, so it is carried into it here. + if (answer.IsError == true) + { + return Failed(text is { Length: > 0 } + ? $"the MCP server '{_session.Id}' answered with a failure: {text}" + : $"the MCP server '{_session.Id}' answered with a failure and said nothing about it."); + } + + // A server that fills the spec's own structured field means that to be the answer, so it + // beats reading the same answer back out of the text blocks. + return answer.StructuredContent is { } structured ? structured : text; } - catch (Exception ex) when (ex is not OperationCanceledException) + + /// Joins the text blocks of one answer, and names every block that is not text. + /// What the server sent back. + /// The text, which is empty when the server sent no blocks. + private static string TextOf(CallToolResult answer) { - return Failed($"the MCP server '{_session.Id}' could not be reached: {ex.GetBaseException().Message}"); + return string.Join( + "\n", + answer.Content.Select(block => block is TextContentBlock text ? text.Text : $"[{block.Type}]")); } - } - /// Reads the answer out of the envelope the protocol wraps it in. - /// What the server sent back. - /// The answer itself, or an error result when the tool failed on its own terms. - private object? Unwrap(CallToolResult answer) - { - var text = TextOf(answer); - - // A tool that fails answers in the one error shape, whichever way it failed. - // The protocol's own failure flag is not that shape, so it is carried into it here. - if (answer.IsError == true) + private JsonObject Failed(string message) { - return Failed(text is { Length: > 0 } - ? $"the MCP server '{_session.Id}' answered with a failure: {text}" - : $"the MCP server '{_session.Id}' answered with a failure and said nothing about it."); + return ToolErrorResult.Create(_id, message); } - - // A server that fills the spec's own structured field means that to be the answer, so it - // beats reading the same answer back out of the text blocks. - return answer.StructuredContent is { } structured ? structured : text; } - - /// Joins the text blocks of one answer, and names every block that is not text. - /// What the server sent back. - /// The text, which is empty when the server sent no blocks. - private static string TextOf(CallToolResult answer) - => string.Join( - "\n", - answer.Content.Select(block => block is TextContentBlock text ? text.Text : $"[{block.Type}]")); - - private JsonObject Failed(string message) => ToolErrorResult.Create(_id, message); } diff --git a/src/AgentCore.Infrastructure/Tools/Mcp/McpToolDescriptor.cs b/src/AgentCore.Infrastructure/Tools/Mcp/McpToolDescriptor.cs index 1d70ca08..490b6ae2 100644 --- a/src/AgentCore.Infrastructure/Tools/Mcp/McpToolDescriptor.cs +++ b/src/AgentCore.Infrastructure/Tools/Mcp/McpToolDescriptor.cs @@ -1,16 +1,17 @@ using System.Text.Json; -namespace AgentCore.Infrastructure.Tools.Mcp; - -/// -/// One tool an MCP server offered, as it stood when the session opened. -/// -/// -/// This is a copy, not a handle. An is bound -/// to the one client that listed it, so holding one past a reconnect would hold a dead connection. -/// The session hands out these instead, and routes every call by . -/// -/// The name the server offers the tool under. It is never the served id. -/// The sentence the model reads. -/// The raw JSON Schema of the arguments, as the server wrote it. -internal sealed record McpToolDescriptor(string Name, string Description, JsonElement JsonSchema); +namespace AgentCore.Infrastructure.Tools.Mcp +{ + /// + /// One tool an MCP server offered, as it stood when the session opened. + /// + /// + /// This is a copy, not a handle. An is bound + /// to the one client that listed it, so holding one past a reconnect would hold a dead connection. + /// The session hands out these instead, and routes every call by . + /// + /// The name the server offers the tool under. It is never the served id. + /// The sentence the model reads. + /// The raw JSON Schema of the arguments, as the server wrote it. + internal sealed record McpToolDescriptor(string Name, string Description, JsonElement JsonSchema); +} diff --git a/src/AgentCore.Infrastructure/Tools/McpToolSource.cs b/src/AgentCore.Infrastructure/Tools/McpToolSource.cs index d275ecaa..4bf34bdd 100644 --- a/src/AgentCore.Infrastructure/Tools/McpToolSource.cs +++ b/src/AgentCore.Infrastructure/Tools/McpToolSource.cs @@ -7,243 +7,240 @@ using Microsoft.Extensions.Logging; using ModelContextProtocol.Client; -namespace AgentCore.Infrastructure.Tools; - -/// -/// Connects to every declared mcp: server, discovers what it offers, and serves the tools -/// allow: pins. -/// -public sealed class McpToolSource : IToolSource, IAsyncDisposable +namespace AgentCore.Infrastructure.Tools { - private readonly Func _sessions; - - private readonly List _open = []; - - /// Creates the source, connecting to the real servers the document declares. - /// The values startup already resolved, for headers: and env:. - /// - /// Opens the client a transport: http server is reached on, or to - /// let the SDK build its own. See for what a host gains by - /// passing one. - /// - /// Where reconnects and dropped tools are reported, or for nowhere. - public McpToolSource( - ResolvedSecrets secrets, - Func? httpClients = null, - ILoggerFactory? loggers = null) - { - ArgumentNullException.ThrowIfNull(secrets); - - McpConnectionFactory connections = new(secrets, httpClients, loggers); - - _sessions = server => new McpServerSession( - server, - (timeout, cancellationToken) => connections.ConnectAsync(server, timeout, cancellationToken), - loggers); - } - - /// Creates the source over a transport a test substitutes. - /// - /// Builds the transport for one declared server. It is called once per connection attempt, so a - /// test that expects a reconnect must return a fresh transport each time — one that has already - /// carried a session cannot carry another. - /// - /// Where reconnects and dropped tools are reported. - internal McpToolSource( - Func transports, - ILoggerFactory? loggers = null) - : this( - (server, timeout, cancellationToken) => Open(transports(server), timeout, loggers, cancellationToken), - loggers) - { - ArgumentNullException.ThrowIfNull(transports); - } - - /// Creates the source over a connect step a test substitutes. - /// - /// Opens one connection to one server, within the timeout given. It is called once per attempt - /// and again on every reconnect, so it must build a fresh transport each time. A test takes this - /// form rather than the transport one when it needs to hold the clients themselves — whether one - /// was closed is only visible on the client. - /// - /// Where reconnects and dropped tools are reported. - internal McpToolSource( - Func> connect, - ILoggerFactory? loggers = null) + /// + /// Connects to every declared mcp: server, discovers what it offers, and serves the tools + /// allow: pins. + /// + public sealed class McpToolSource : IToolSource, IAsyncDisposable { - ArgumentNullException.ThrowIfNull(connect); + private readonly Func _sessions; + + private readonly List _open = []; + + /// Creates the source, connecting to the real servers the document declares. + /// The values startup already resolved, for headers: and env:. + /// + /// Opens the client a transport: http server is reached on, or to + /// let the SDK build its own. See for what a host gains by + /// passing one. + /// + /// Where reconnects and dropped tools are reported, or for nowhere. + public McpToolSource( + ResolvedSecrets secrets, + Func? httpClients = null, + ILoggerFactory? loggers = null) + { + ArgumentNullException.ThrowIfNull(secrets); - _sessions = server => new McpServerSession( - server, - (timeout, cancellationToken) => connect(server, timeout, cancellationToken), - loggers); - } + McpConnectionFactory connections = new(secrets, httpClients, loggers); - /// Opens one client over one transport, under the session's own timeout. - private static async ValueTask Open( - IClientTransport transport, TimeSpan timeout, ILoggerFactory? loggers, CancellationToken cancellationToken) - => await McpClient.CreateAsync( - transport, - new McpClientOptions { InitializationTimeout = timeout }, - loggers, - cancellationToken).ConfigureAwait(false); - - /// - /// - /// A server cannot be reached within its own retry and timeout; an allow: entry names a - /// tool the server does not offer, is empty, or writes "*" alongside another entry or with - /// an as:; or a kept tool has no description. Every one of these names the server id, so a - /// deployer knows which mcp: entry is wrong. On any failure, every session this conversation - /// already opened is closed before the exception leaves — a partly-booted document leaves no - /// child process behind. - /// - public async ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(context); + _sessions = server => new McpServerSession( + server, + (timeout, cancellationToken) => connections.ConnectAsync(server, timeout, cancellationToken), + loggers); + } - try + /// Creates the source over a transport a test substitutes. + /// + /// Builds the transport for one declared server. It is called once per connection attempt, so a + /// test that expects a reconnect must return a fresh transport each time — one that has already + /// carried a session cannot carry another. + /// + /// Where reconnects and dropped tools are reported. + internal McpToolSource( + Func transports, + ILoggerFactory? loggers = null) + : this( + (server, timeout, cancellationToken) => Open(transports(server), timeout, loggers, cancellationToken), + loggers) { - List registrations = []; + ArgumentNullException.ThrowIfNull(transports); + } - foreach (var server in context.Configuration.Mcp) - { - registrations.AddRange(await DiscoverAsync(server, cancellationToken).ConfigureAwait(false)); - } + /// Creates the source over a connect step a test substitutes. + /// + /// Opens one connection to one server, within the timeout given. It is called once per attempt + /// and again on every reconnect, so it must build a fresh transport each time. A test takes this + /// form rather than the transport one when it needs to hold the clients themselves — whether one + /// was closed is only visible on the client. + /// + /// Where reconnects and dropped tools are reported. + internal McpToolSource( + Func> connect, + ILoggerFactory? loggers = null) + { + ArgumentNullException.ThrowIfNull(connect); - return registrations; + _sessions = server => new McpServerSession( + server, + (timeout, cancellationToken) => connect(server, timeout, cancellationToken), + loggers); } - catch + + /// Opens one client over one transport, under the session's own timeout. + private static async ValueTask Open( + IClientTransport transport, TimeSpan timeout, ILoggerFactory? loggers, CancellationToken cancellationToken) { - await DisposeAsync().ConfigureAwait(false); - throw; + return await McpClient.CreateAsync( + transport, + new McpClientOptions { InitializationTimeout = timeout }, + loggers, + cancellationToken).ConfigureAwait(false); } - } - /// - public async ValueTask DisposeAsync() - { - // Each dispose is guarded on its own, so one server's failure to close cannot abandon the - // rest, and _open.Clear() always runs — the host's second call must find nothing left to - // re-touch. - foreach (var session in _open) + /// + /// + /// A server cannot be reached within its own retry and timeout; an allow: entry names a + /// tool the server does not offer, is empty, or writes "*" alongside another entry or with + /// an as:; or a kept tool has no description. Every one of these names the server id, so a + /// deployer knows which mcp: entry is wrong. On any failure, every session this conversation + /// already opened is closed before the exception leaves — a partly-booted document leaves no + /// child process behind. + /// + public async ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) { + ArgumentNullException.ThrowIfNull(context); + try { - await session.DisposeAsync().ConfigureAwait(false); + List registrations = []; + + foreach (McpServerConfiguration server in context.Configuration.Mcp) + { + registrations.AddRange(await DiscoverAsync(server, cancellationToken).ConfigureAwait(false)); + } + + return registrations; } catch { - // One server's failure to close must not abandon the rest. + await DisposeAsync().ConfigureAwait(false); + throw; } } - _open.Clear(); - } + /// + public async ValueTask DisposeAsync() + { + // Each dispose is guarded on its own, so one server's failure to close cannot abandon the + // rest, and _open.Clear() always runs — the host's second call must find nothing left to + // re-touch. + foreach (McpServerSession session in _open) + { + try + { + await session.DisposeAsync().ConfigureAwait(false); + } + catch + { + // One server's failure to close must not abandon the rest. + } + } - /// Opens one server, and applies its allow: to what it offers. - private async ValueTask> DiscoverAsync( - McpServerConfiguration server, CancellationToken cancellationToken) - { - ValidateAllow(server); + _open.Clear(); + } - var session = _sessions(server); + /// Opens one server, and applies its allow: to what it offers. + private async ValueTask> DiscoverAsync( + McpServerConfiguration server, CancellationToken cancellationToken) + { + ValidateAllow(server); - _open.Add(session); + McpServerSession session = _sessions(server); - var opened = false; + _open.Add(session); - try - { - var offered = await session.OpenAsync(cancellationToken).ConfigureAwait(false); + bool opened = false; - opened = true; + try + { + IReadOnlyList offered = await session.OpenAsync(cancellationToken).ConfigureAwait(false); - var byName = offered.ToDictionary(tool => tool.Name, StringComparer.Ordinal); + opened = true; - return server.Allow.Any(entry => entry.Name == "*") - ? [.. offered.Select(tool => Register(session, server, tool, $"{server.Id}.{tool.Name}"))] - : [.. server.Allow.Select(entry => RegisterAllowed(session, server, byName, entry))]; - } - catch (ConfigurationLoadException) - { - throw; - } - catch (Exception ex) when (ex is not OperationCanceledException) - { - throw ToolSourceError.Fail(opened - ? $"the MCP server '{server.Id}' listed its tools, but failed before it could serve " - + $"them: {Describe(ex)}" - : $"the MCP server '{server.Id}' could not be reached: {Describe(ex)}"); + Dictionary byName = offered.ToDictionary(tool => tool.Name, StringComparer.Ordinal); + + return server.Allow.Any(entry => entry.Name == "*") + ? [.. offered.Select(tool => Register(session, server, tool, $"{server.Id}.{tool.Name}"))] + : [.. server.Allow.Select(entry => RegisterAllowed(session, server, byName, entry))]; + } + catch (ConfigurationLoadException) + { + throw; + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + throw ToolSourceError.Fail(opened + ? $"the MCP server '{server.Id}' listed its tools, but failed before it could serve " + + $"them: {Describe(ex)}" + : $"the MCP server '{server.Id}' could not be reached: {Describe(ex)}"); + } } - } - /// Checks the shape of allow: itself, before any connection is opened. - private static void ValidateAllow(McpServerConfiguration server) - { - if (server.Allow.Count == 0) + /// Checks the shape of allow: itself, before any connection is opened. + private static void ValidateAllow(McpServerConfiguration server) { - throw ToolSourceError.Fail( - $"the MCP server '{server.Id}' declares no allow:, so it would serve nothing. Pin at " - + "least one tool, or write allow: [\"*\"] to take every tool it offers."); - } + if (server.Allow.Count == 0) + { + throw ToolSourceError.Fail( + $"the MCP server '{server.Id}' declares no allow:, so it would serve nothing. Pin at " + + "least one tool, or write allow: [\"*\"] to take every tool it offers."); + } - var star = server.Allow.FirstOrDefault(entry => entry.Name == "*"); + McpAllowEntry? star = server.Allow.FirstOrDefault(entry => entry.Name == "*"); - if (star is not null && (server.Allow.Count > 1 || star.As is not null)) - { - throw ToolSourceError.Fail( - $"the MCP server '{server.Id}' writes \"*\" in allow: alongside another entry, or " - + "gives \"*\" an as:. \"*\" is the explicit opt-out for every tool the server offers, " - + "so it must stand alone with no alias."); + if (star is not null && (server.Allow.Count > 1 || star.As is not null)) + { + throw ToolSourceError.Fail( + $"the MCP server '{server.Id}' writes \"*\" in allow: alongside another entry, or " + + "gives \"*\" an as:. \"*\" is the explicit opt-out for every tool the server offers, " + + "so it must stand alone with no alias."); + } } - } - private static ToolRegistration RegisterAllowed( - McpServerSession session, - McpServerConfiguration server, - Dictionary offered, - McpAllowEntry entry) - { - if (!offered.TryGetValue(entry.Name, out var tool)) + private static ToolRegistration RegisterAllowed( + McpServerSession session, + McpServerConfiguration server, + Dictionary offered, + McpAllowEntry entry) { - throw ToolSourceError.Fail( - $"the MCP server '{server.Id}' does not offer a tool named '{entry.Name}', which its " - + "allow: list names."); + return !offered.TryGetValue(entry.Name, out McpToolDescriptor? tool) + ? throw ToolSourceError.Fail( + $"the MCP server '{server.Id}' does not offer a tool named '{entry.Name}', which its " + + "allow: list names.") + : Register(session, server, tool, entry.As ?? $"{server.Id}.{tool.Name}"); } - return Register(session, server, tool, entry.As ?? $"{server.Id}.{tool.Name}"); - } - - /// - /// Builds the registration for one kept tool, under its final served id. - /// - private static ToolRegistration Register( - McpServerSession session, McpServerConfiguration server, McpToolDescriptor tool, string id) - { - if (tool.Description.Length == 0) + /// + /// Builds the registration for one kept tool, under its final served id. + /// + private static ToolRegistration Register( + McpServerSession session, McpServerConfiguration server, McpToolDescriptor tool, string id) { - throw ToolSourceError.Fail( - $"the MCP server '{server.Id}' offers a tool '{tool.Name}' with no description, so " - + "the model has nothing to read when it decides whether to call it. Take it out of " - + "allow: (or, under allow: [\"*\"], replace \"*\" with an explicit list that leaves it " - + "out), or ask whoever runs that server to describe it."); + return tool.Description.Length == 0 + ? throw ToolSourceError.Fail( + $"the MCP server '{server.Id}' offers a tool '{tool.Name}' with no description, so " + + "the model has nothing to read when it decides whether to call it. Take it out of " + + "allow: (or, under allow: [\"*\"], replace \"*\" with an explicit list that leaves it " + + "out), or ask whoever runs that server to describe it.") + : new ToolRegistration( + id, tool.Description, () => new McpTool(session, tool, id), session.CallTimeout); } - return new ToolRegistration( - id, tool.Description, () => new McpTool(session, tool, id), session.CallTimeout); - } - - /// Names the innermost cause, so a wrapped SDK message never buries the real one. - /// The exception a transport or connection step threw. - /// - /// 's own message, plus 's message - /// when that differs — the SDK's own text ("Failed to connect transport.") names no cause, and - /// the actual one (a missing executable, a refused socket) is what a deployer needs to fix. - /// - private static string Describe(Exception ex) - { - var cause = ex.GetBaseException(); - return ReferenceEquals(cause, ex) ? ex.Message : $"{ex.Message} ({cause.Message})"; + /// Names the innermost cause, so a wrapped SDK message never buries the real one. + /// The exception a transport or connection step threw. + /// + /// 's own message, plus 's message + /// when that differs — the SDK's own text ("Failed to connect transport.") names no cause, and + /// the actual one (a missing executable, a refused socket) is what a deployer needs to fix. + /// + private static string Describe(Exception ex) + { + Exception cause = ex.GetBaseException(); + return ReferenceEquals(cause, ex) ? ex.Message : $"{ex.Message} ({cause.Message})"; + } } } diff --git a/tests/AgentCore.Application.Tests/Audit/AuditConversationObserverTests.cs b/tests/AgentCore.Application.Tests/Audit/AuditConversationObserverTests.cs index 59378be5..1ea973a8 100644 --- a/tests/AgentCore.Application.Tests/Audit/AuditConversationObserverTests.cs +++ b/tests/AgentCore.Application.Tests/Audit/AuditConversationObserverTests.cs @@ -5,245 +5,268 @@ using Xunit; using Xunit.Sdk; -namespace AgentCore.Application.Tests.Audit; - -/// -/// The one place that knows both vocabularies: a neutral fact of a conversation, and a row of the chain of D23. -/// -public sealed class AuditConversationObserverTests +namespace AgentCore.Application.Tests.Audit { - private const string ConversationId = "conversation-1"; - - private static readonly DateTimeOffset Moment = new(2026, 8, 15, 9, 30, 0, TimeSpan.Zero); - - /// The six kinds that are counted or logged or both, and stored nowhere. - public static TheoryData DiagnosticKinds => - [ - ConversationEventKind.ModerationUnavailable, - ConversationEventKind.ModerationClean, - ConversationEventKind.EmptyReply, - ConversationEventKind.ExtractionFailed, - ConversationEventKind.TranscriptWriteFailed, - ConversationEventKind.StateRestorePartial, - ConversationEventKind.TranscriptResyncFailed, - ]; - - /// Every kind, once, across the two tables above. - [Fact] - public void TheTwoTables_BetweenThemNameEveryKind() + /// + /// The one place that knows both vocabularies: a neutral fact of a conversation, and a row of the chain of D23. + /// + public sealed class AuditConversationObserverTests { - IEnumerable named = + private const string ConversationId = "conversation-1"; + + private static readonly DateTimeOffset Moment = new(2026, 8, 15, 9, 30, 0, TimeSpan.Zero); + + /// The six kinds that are counted or logged or both, and stored nowhere. + public static TheoryData DiagnosticKinds => [ - .. DiagnosticKinds.Select(row => (ConversationEventKind)((ITheoryDataRow)row).GetData()[0]!), - .. StoredKinds.Select(row => (ConversationEventKind)((ITheoryDataRow)row).GetData()[0]!), + ConversationEventKind.ModerationUnavailable, + ConversationEventKind.ModerationClean, + ConversationEventKind.EmptyReply, + ConversationEventKind.ExtractionFailed, + ConversationEventKind.TranscriptWriteFailed, + ConversationEventKind.StateRestorePartial, + ConversationEventKind.TranscriptResyncFailed, ]; - Assert.Equal([.. Enum.GetValues().Order()], [.. named.Order()]); - } - - /// The seven kinds the store keeps, beside the token each one writes. - public static TheoryData StoredKinds => - new() + /// Every kind, once, across the two tables above. + [Fact] + public void TheTwoTables_BetweenThemNameEveryKind() { - { ConversationEventKind.ConversationStarted, AuditEventKind.ConversationStarted }, - { ConversationEventKind.PromptFlagged, AuditEventKind.PromptFlagged }, - { ConversationEventKind.ToolFailed, AuditEventKind.ToolFailed }, - { ConversationEventKind.TurnCompleted, AuditEventKind.TurnCompleted }, - { ConversationEventKind.ReplyInterrupted, AuditEventKind.ReplyInterrupted }, - { ConversationEventKind.ConversationEnded, AuditEventKind.ConversationEnded }, - { ConversationEventKind.TurnSuperseded, AuditEventKind.TurnSuperseded }, - }; - - [Theory] - [MemberData(nameof(DiagnosticKinds))] - public async Task AFactWithNoEventId_WritesNoRow(ConversationEventKind kind) - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); + IEnumerable named = + [ + .. DiagnosticKinds.Select(row => (ConversationEventKind)((ITheoryDataRow)row).GetData()[0]!), + .. StoredKinds.Select(row => (ConversationEventKind)((ITheoryDataRow)row).GetData()[0]!), + ]; + + Assert.Equal([.. Enum.GetValues().Order()], [.. named.Order()]); + } + + /// The seven kinds the store keeps, beside the token each one writes. + public static TheoryData StoredKinds => + new() + { + { ConversationEventKind.ConversationStarted, AuditEventKind.ConversationStarted }, + { ConversationEventKind.PromptFlagged, AuditEventKind.PromptFlagged }, + { ConversationEventKind.ToolFailed, AuditEventKind.ToolFailed }, + { ConversationEventKind.TurnCompleted, AuditEventKind.TurnCompleted }, + { ConversationEventKind.ReplyInterrupted, AuditEventKind.ReplyInterrupted }, + { ConversationEventKind.ConversationEnded, AuditEventKind.ConversationEnded }, + { ConversationEventKind.TurnSuperseded, AuditEventKind.TurnSuperseded }, + }; + + [Theory] + [MemberData(nameof(DiagnosticKinds))] + public async Task AFactWithNoEventId_WritesNoRow(ConversationEventKind kind) + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); - // A diagnostic-only event leaves EventId null precisely because it takes no row. - await observer.OnConversationEventAsync(Event(kind), TestContext.Current.CancellationToken); + // A diagnostic-only event leaves EventId null precisely because it takes no row. + await observer.OnConversationEventAsync(Event(kind), TestContext.Current.CancellationToken); - Assert.Empty(sink.Events); - } + Assert.Empty(sink.Events); + } - [Theory] - [MemberData(nameof(StoredKinds))] - public async Task AStoredFact_BecomesARowOfItsOwnKind(ConversationEventKind kind, AuditEventKind expected) - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); + [Theory] + [MemberData(nameof(StoredKinds))] + public async Task AStoredFact_BecomesARowOfItsOwnKind(ConversationEventKind kind, AuditEventKind expected) + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); - await observer.OnConversationEventAsync( - Event(kind, eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7()), - TestContext.Current.CancellationToken); + await observer.OnConversationEventAsync( + Event(kind, eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7()), + TestContext.Current.CancellationToken); - var written = Assert.Single(sink.Events); - Assert.Equal(expected, written.Kind); - } + AuditEvent written = Assert.Single(sink.Events); + Assert.Equal(expected, written.Kind); + } - [Fact] - public async Task ItCopiesTheIdentityStraightThrough() - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); - var id = Guid.CreateVersion7(); + [Fact] + public async Task ItCopiesTheIdentityStraightThrough() + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); + Guid id = Guid.CreateVersion7(); - await observer.OnConversationEventAsync( - new ConversationEvent - { - ConversationId = ConversationId, - Kind = ConversationEventKind.ConversationStarted, - OccurredAt = DateTimeOffset.UnixEpoch, - EventId = id, - }, - CancellationToken.None); + await observer.OnConversationEventAsync( + new ConversationEvent + { + ConversationId = ConversationId, + Kind = ConversationEventKind.ConversationStarted, + OccurredAt = DateTimeOffset.UnixEpoch, + EventId = id, + }, + CancellationToken.None); - Assert.Equal(id, Assert.Single(sink.EventsOf(ConversationId)).EventId); - } + Assert.Equal(id, Assert.Single(sink.EventsOf(ConversationId)).EventId); + } - [Fact] - public async Task ItCopiesTheAmendmentStraightThrough() - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); - var turn = Guid.CreateVersion7(); - var cut = Guid.CreateVersion7(); + [Fact] + public async Task ItCopiesTheAmendmentStraightThrough() + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); + Guid turn = Guid.CreateVersion7(); + Guid cut = Guid.CreateVersion7(); - await observer.OnConversationEventAsync( - new ConversationEvent - { - ConversationId = ConversationId, - Kind = ConversationEventKind.ReplyInterrupted, - OccurredAt = DateTimeOffset.UnixEpoch, - EventId = cut, - AmendsEventId = turn, - TurnIndex = 0, - Payload = new Dictionary(StringComparer.Ordinal) + await observer.OnConversationEventAsync( + new ConversationEvent { - [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText("heard").Value, - [AuditPayloadKeys.DurationUntilInterruptMs] = "120", + ConversationId = ConversationId, + Kind = ConversationEventKind.ReplyInterrupted, + OccurredAt = DateTimeOffset.UnixEpoch, + EventId = cut, + AmendsEventId = turn, + TurnIndex = 0, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText("heard").Value, + [AuditPayloadKeys.DurationUntilInterruptMs] = "120", + }, }, - }, - CancellationToken.None); + CancellationToken.None); - var written = Assert.Single(sink.EventsOf(ConversationId)); - Assert.Equal(cut, written.EventId); - Assert.Equal(turn, written.AmendsEventId); - } + AuditEvent written = Assert.Single(sink.EventsOf(ConversationId)); + Assert.Equal(cut, written.EventId); + Assert.Equal(turn, written.AmendsEventId); + } - [Fact] - public async Task AFactThatCorrectsNothing_LeavesTheAmendmentUnset() - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); + [Fact] + public async Task AFactThatCorrectsNothing_LeavesTheAmendmentUnset() + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); - await observer.OnConversationEventAsync( - Event(ConversationEventKind.TurnCompleted, eventId: Guid.CreateVersion7()), - TestContext.Current.CancellationToken); + await observer.OnConversationEventAsync( + Event(ConversationEventKind.TurnCompleted, eventId: Guid.CreateVersion7()), + TestContext.Current.CancellationToken); - Assert.Null(Assert.Single(sink.Events).AmendsEventId); - } + Assert.Null(Assert.Single(sink.Events).AmendsEventId); + } - [Fact] - public async Task TheRow_CarriesTheConversationTheTurnAndTheMomentUnchanged() - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); - Dictionary payload = new(StringComparer.Ordinal) + [Fact] + public async Task TheRow_CarriesTheConversationTheTurnAndTheMomentUnchanged() { - [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText("hello there.").Value, - [AuditPayloadKeys.StageBefore] = "greeting", - [AuditPayloadKeys.StageAfter] = "triage", - }; - - await observer.OnConversationEventAsync( - Event(ConversationEventKind.TurnCompleted, eventId: Guid.CreateVersion7(), turnIndex: 5, payload: payload), - TestContext.Current.CancellationToken); - - var written = Assert.Single(sink.Events); - Assert.Equal(ConversationId, written.ConversationId); - Assert.Equal(5, written.TurnIndex); - Assert.Equal(Moment, written.OccurredAt); - Assert.Equal(payload, written.Payload); - } - - [Fact] - public async Task AFactAboutTheConversationItself_CarriesNoTurn() - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); - - await observer.OnConversationEventAsync( - Event(ConversationEventKind.ConversationStarted, eventId: Guid.CreateVersion7()), - TestContext.Current.CancellationToken); + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); + Dictionary payload = new(StringComparer.Ordinal) + { + [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText("hello there.").Value, + [AuditPayloadKeys.StageBefore] = "greeting", + [AuditPayloadKeys.StageAfter] = "triage", + }; + + await observer.OnConversationEventAsync( + Event(ConversationEventKind.TurnCompleted, eventId: Guid.CreateVersion7(), turnIndex: 5, payload: payload), + TestContext.Current.CancellationToken); + + AuditEvent written = Assert.Single(sink.Events); + Assert.Equal(ConversationId, written.ConversationId); + Assert.Equal(5, written.TurnIndex); + Assert.Equal(Moment, written.OccurredAt); + Assert.Equal(payload, written.Payload); + } + + [Fact] + public async Task AFactAboutTheConversationItself_CarriesNoTurn() + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); - Assert.Null(Assert.Single(sink.Events).TurnIndex); - } + await observer.OnConversationEventAsync( + Event(ConversationEventKind.ConversationStarted, eventId: Guid.CreateVersion7()), + TestContext.Current.CancellationToken); - [Fact] - public async Task ManyFacts_ReachTheSinkInTheOrderTheConversationRaisedThem() - { - InMemoryAuditSink sink = new(); - AuditConversationObserver observer = new(sink); - var token = TestContext.Current.CancellationToken; - - await observer.OnConversationEventAsync(Event(ConversationEventKind.ConversationStarted, eventId: Guid.CreateVersion7()), token); - - // The two diagnostic facts between them take no identity, so they write no row. - await observer.OnConversationEventAsync(Event(ConversationEventKind.ModerationClean), token); - await observer.OnConversationEventAsync( - Event(ConversationEventKind.TurnCompleted, eventId: Guid.CreateVersion7(), turnIndex: 0), token); - await observer.OnConversationEventAsync(Event(ConversationEventKind.EmptyReply, turnIndex: 0), token); - await observer.OnConversationEventAsync(Event(ConversationEventKind.ConversationEnded, eventId: Guid.CreateVersion7()), token); - - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted, AuditEventKind.ConversationEnded], - sink.EventsOf(ConversationId).Select(item => item.Kind).ToArray()); - } + Assert.Null(Assert.Single(sink.Events).TurnIndex); + } - [Fact] - public void NoSink_IsRefused() => Assert.Throws(() => new AuditConversationObserver(null!)); - - [Fact] - public async Task NoEvent_IsRefused() - => await Assert.ThrowsAsync(async () => - await new AuditConversationObserver(new InMemoryAuditSink()) - .OnConversationEventAsync(null!, TestContext.Current.CancellationToken)); - - private static ConversationEvent Event( - ConversationEventKind kind, - Guid? eventId = null, - int? turnIndex = null, - Guid? amends = null, - IReadOnlyDictionary? payload = null) => new() + [Fact] + public async Task ManyFacts_ReachTheSinkInTheOrderTheConversationRaisedThem() + { + InMemoryAuditSink sink = new(); + AuditConversationObserver observer = new(sink); + CancellationToken token = TestContext.Current.CancellationToken; + + await observer.OnConversationEventAsync(Event(ConversationEventKind.ConversationStarted, eventId: Guid.CreateVersion7()), token); + + // The two diagnostic facts between them take no identity, so they write no row. + await observer.OnConversationEventAsync(Event(ConversationEventKind.ModerationClean), token); + await observer.OnConversationEventAsync( + Event(ConversationEventKind.TurnCompleted, eventId: Guid.CreateVersion7(), turnIndex: 0), token); + await observer.OnConversationEventAsync(Event(ConversationEventKind.EmptyReply, turnIndex: 0), token); + await observer.OnConversationEventAsync(Event(ConversationEventKind.ConversationEnded, eventId: Guid.CreateVersion7()), token); + + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted, AuditEventKind.ConversationEnded], + sink.EventsOf(ConversationId).Select(item => item.Kind).ToArray()); + } + + [Fact] + public void NoSink_IsRefused() { - ConversationId = ConversationId, - Kind = kind, - OccurredAt = Moment, - EventId = eventId, - TurnIndex = turnIndex, - AmendsEventId = amends, - Payload = payload ?? RequiredPayload(kind), - }; + _ = Assert.Throws(() => new AuditConversationObserver(null!)); + } - /// - /// The payload each kind must carry to be a legal event, per . - /// - private static Dictionary RequiredPayload(ConversationEventKind kind) => kind switch - { - ConversationEventKind.ReplyInterrupted => new Dictionary(StringComparer.Ordinal) + [Fact] + public async Task NoEvent_IsRefused() { - [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText("the belt ships").Value, - }, - ConversationEventKind.PromptFlagged => new Dictionary(StringComparer.Ordinal) + _ = await Assert.ThrowsAsync(async () => + await new AuditConversationObserver(new InMemoryAuditSink()) + .OnConversationEventAsync(null!, TestContext.Current.CancellationToken)); + } + + private static ConversationEvent Event( + ConversationEventKind kind, + Guid? eventId = null, + int? turnIndex = null, + Guid? amends = null, + IReadOnlyDictionary? payload = null) { - [AuditPayloadKeys.ModerationCategories] = "harassment", - }, - ConversationEventKind.ConversationEnded => new Dictionary(StringComparer.Ordinal) + return new() + { + ConversationId = ConversationId, + Kind = kind, + OccurredAt = Moment, + EventId = eventId, + TurnIndex = turnIndex, + AmendsEventId = amends, + Payload = payload ?? RequiredPayload(kind), + }; + } + + /// + /// The payload each kind must carry to be a legal event, per . + /// + private static Dictionary RequiredPayload(ConversationEventKind kind) { - [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.CallerHungUp), - }, - _ => new Dictionary(StringComparer.Ordinal), - }; + return kind switch + { + ConversationEventKind.ReplyInterrupted => new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText("the belt ships").Value, + }, + ConversationEventKind.PromptFlagged => new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ModerationCategories] = "harassment", + }, + ConversationEventKind.ConversationEnded => new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.CallerHungUp), + }, + ConversationEventKind.ConversationStarted + or ConversationEventKind.ModerationUnavailable + or ConversationEventKind.ModerationClean + or ConversationEventKind.ToolFailed + or ConversationEventKind.EmptyReply + or ConversationEventKind.ExtractionFailed + or ConversationEventKind.TurnCompleted + or ConversationEventKind.TurnSuperseded + or ConversationEventKind.TranscriptWriteFailed + or ConversationEventKind.StateRestorePartial + or ConversationEventKind.TranscriptResyncFailed => new Dictionary(StringComparer.Ordinal), + _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "The conversation event vocabulary is closed, and this value is not in it."), + }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Audit/AuditSinkFactoryTests.cs b/tests/AgentCore.Application.Tests/Audit/AuditSinkFactoryTests.cs index 3151946e..d1a7b062 100644 --- a/tests/AgentCore.Application.Tests/Audit/AuditSinkFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Audit/AuditSinkFactoryTests.cs @@ -6,216 +6,221 @@ using AgentCore.Domain.Audit; using Xunit; -namespace AgentCore.Application.Tests.Audit; - -/// -/// The fifth vendor seam: providers.audit, and what a document that names none gets. -/// -/// -/// -/// This seam differs from the other four in what an absent block means. Telemetry names no collector -/// and exports nothing, because nobody asked for an export; audit cannot do the same, because the -/// turn loop raises the D23 events whether or not the document chose a home for them, and the -/// alternative to a sink is dropping them on the floor. So the answer is never : -/// a document that names nothing gets . -/// -/// -/// These tests pin the parts that are this project's and not a vendor's: that there is always a sink, -/// that memory is this library's own name and a host cannot rebind it, and that every other -/// kind goes through the same shared selector as the four seams before it. -/// -/// -public sealed class AuditSinkFactoryTests +namespace AgentCore.Application.Tests.Audit { - // --------------------------------------------------------------------------------------------- - // There is always a sink. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task NoAuditBlock_GetsTheInProcessSinkAndAsksNoAdapter() + /// + /// The fifth vendor seam: providers.audit, and what a document that names none gets. + /// + /// + /// + /// This seam differs from the other four in what an absent block means. Telemetry names no collector + /// and exports nothing, because nobody asked for an export; audit cannot do the same, because the + /// turn loop raises the D23 events whether or not the document chose a home for them, and the + /// alternative to a sink is dropping them on the floor. So the answer is never : + /// a document that names nothing gets . + /// + /// + /// These tests pin the parts that are this project's and not a vendor's: that there is always a sink, + /// that memory is this library's own name and a host cannot rebind it, and that every other + /// kind goes through the same shared selector as the four seams before it. + /// + /// + public sealed class AuditSinkFactoryTests { - var configuration = ConfigurationLoader.LoadYaml(Document()); - FakeAuditSinkAdapter adapter = new("postgres"); - - var sink = await AuditSinkFactory.OpenAsync( - configuration, - secrets: null, - [adapter], - TestContext.Current.CancellationToken); - - // The whole point of the seam. A document that chose no store still records the conversation, so the - // events of D23 have somewhere to go and a host with no database still starts. - Assert.IsType(sink); - Assert.Equal(0, adapter.Opens); - } + // --------------------------------------------------------------------------------------------- + // There is always a sink. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task NoAuditBlock_GetsTheInProcessSinkAndAsksNoAdapter() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document()); + FakeAuditSinkAdapter adapter = new("postgres"); - [Fact] - public async Task TheMemoryKind_GetsTheInProcessSinkWithNoAdapterRegistered() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); + IAuditSinkPort sink = await AuditSinkFactory.OpenAsync( + configuration, + secrets: null, + [adapter], + TestContext.Current.CancellationToken); - var sink = await AuditSinkFactory.OpenAsync( - configuration, - secrets: null, - [], - TestContext.Current.CancellationToken); + // The whole point of the seam. A document that chose no store still records the conversation, so the + // events of D23 have somewhere to go and a host with no database still starts. + _ = Assert.IsType(sink); + Assert.Equal(0, adapter.Opens); + } - // Naming the built-in out loud is the same document as naming nothing, and it is served by - // this library rather than by a vendor. A host that registered no adapter at all still starts. - Assert.IsType(sink); - } + [Fact] + public async Task TheMemoryKind_GetsTheInProcessSinkWithNoAdapterRegistered() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); - [Fact] - public async Task TheMemoryKind_MatchesWithoutRegardToCase() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: Memory")); + IAuditSinkPort sink = await AuditSinkFactory.OpenAsync( + configuration, + secrets: null, + [], + TestContext.Current.CancellationToken); - var sink = await AuditSinkFactory.OpenAsync( - configuration, - secrets: null, - [], - TestContext.Current.CancellationToken); + // Naming the built-in out loud is the same document as naming nothing, and it is served by + // this library rather than by a vendor. A host that registered no adapter at all still starts. + _ = Assert.IsType(sink); + } - // A vendor name is written by a human, so a capital letter is not a different vendor. The - // built-in name follows the same rule the shared selector applies to every other kind. - Assert.IsType(sink); - } + [Fact] + public async Task TheMemoryKind_MatchesWithoutRegardToCase() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: Memory")); - // --------------------------------------------------------------------------------------------- - // Every other kind picks an adapter. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheKind_PicksOneAdapterAndLeavesTheOthersAlone() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: fake")); - FakeAuditSinkAdapter fake = new("fake"); - FakeAuditSinkAdapter other = new("postgres"); - - var sink = await AuditSinkFactory.OpenAsync( - configuration, - secrets: null, - [other, fake], - TestContext.Current.CancellationToken); - - Assert.Same(fake.Sink, sink); - Assert.Equal(1, fake.Opens); - Assert.Equal(0, other.Opens); - } + IAuditSinkPort sink = await AuditSinkFactory.OpenAsync( + configuration, + secrets: null, + [], + TestContext.Current.CancellationToken); - [Fact] - public async Task AnAdapterThatClaimsTheMemoryKind_DoesNotTakeOverTheBuiltIn() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); - FakeAuditSinkAdapter impostor = new("memory"); - - var sink = await AuditSinkFactory.OpenAsync( - configuration, - secrets: null, - [impostor], - TestContext.Current.CancellationToken); - - // memory is this library's own name and is answered before the selector runs, so a document - // that writes it means one fixed thing on every host that reads it. A host with a second - // in-process store gives it a name of its own instead. - Assert.IsType(sink); - Assert.Equal(0, impostor.Opens); - } + // A vendor name is written by a human, so a capital letter is not a different vendor. The + // built-in name follows the same rule the shared selector applies to every other kind. + _ = Assert.IsType(sink); + } - // --------------------------------------------------------------------------------------------- - // A kind nobody serves fails the start, and says what is registered. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindNoAdapterServes_FailsTheStartAndNamesWhatIsRegistered() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); - FakeAuditSinkAdapter adapter = new("fake"); + // --------------------------------------------------------------------------------------------- + // Every other kind picks an adapter. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheKind_PicksOneAdapterAndLeavesTheOthersAlone() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: fake")); + FakeAuditSinkAdapter fake = new("fake"); + FakeAuditSinkAdapter other = new("postgres"); - var failure = await Assert.ThrowsAsync( - async () => await AuditSinkFactory.OpenAsync( + IAuditSinkPort sink = await AuditSinkFactory.OpenAsync( configuration, secrets: null, - [adapter], - TestContext.Current.CancellationToken)); + [other, fake], + TestContext.Current.CancellationToken); - // A document that asked for something this host cannot give. The failure belongs to the - // start and never to a conversation, which is what item 9 of section 11 asks for. - Assert.Contains("postgres", failure.Message, StringComparison.Ordinal); - Assert.Contains("'fake'", failure.Message, StringComparison.Ordinal); - Assert.Equal("/providers/audit/kind", failure.Errors[0].Pointer); - } + Assert.Same(fake.Sink, sink); + Assert.Equal(1, fake.Opens); + Assert.Equal(0, other.Opens); + } - [Fact] - public async Task TwoAdaptersOnOneKind_FailTheStart() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); + [Fact] + public async Task AnAdapterThatClaimsTheMemoryKind_DoesNotTakeOverTheBuiltIn() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); + FakeAuditSinkAdapter impostor = new("memory"); - var failure = await Assert.ThrowsAsync( - async () => await AuditSinkFactory.OpenAsync( + IAuditSinkPort sink = await AuditSinkFactory.OpenAsync( configuration, secrets: null, - [new FakeAuditSinkAdapter("postgres"), new FakeAuditSinkAdapter("postgres")], - TestContext.Current.CancellationToken)); + [impostor], + TestContext.Current.CancellationToken); + + // memory is this library's own name and is answered before the selector runs, so a document + // that writes it means one fixed thing on every host that reads it. A host with a second + // in-process store gives it a name of its own instead. + _ = Assert.IsType(sink); + Assert.Equal(0, impostor.Opens); + } - // One kind names one store. Two adapters answering to it means the chain of D23 silently - // went to whichever was registered first, which is the one thing an audit trail cannot do. - Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + // --------------------------------------------------------------------------------------------- + // A kind nobody serves fails the start, and says what is registered. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindNoAdapterServes_FailsTheStartAndNamesWhatIsRegistered() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); + FakeAuditSinkAdapter adapter = new("fake"); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await AuditSinkFactory.OpenAsync( + configuration, + secrets: null, + [adapter], + TestContext.Current.CancellationToken)); + + // A document that asked for something this host cannot give. The failure belongs to the + // start and never to a conversation, which is what item 9 of section 11 asks for. + Assert.Contains("postgres", failure.Message, StringComparison.Ordinal); + Assert.Contains("'fake'", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/audit/kind", failure.Errors[0].Pointer); + } - // And the noun is this seam's own. VendorSeam.Plural exists to keep each seam's wording - // through one shared selector, so audit's "sinks" is pinned here — without this, the - // argument could be dropped and nothing would fail. - Assert.Contains("sinks", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task TwoAdaptersOnOneKind_FailTheStart() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await AuditSinkFactory.OpenAsync( + configuration, + secrets: null, + [new FakeAuditSinkAdapter("postgres"), new FakeAuditSinkAdapter("postgres")], + TestContext.Current.CancellationToken)); + + // One kind names one store. Two adapters answering to it means the chain of D23 silently + // went to whichever was registered first, which is the one thing an audit trail cannot do. + Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + + // And the noun is this seam's own. VendorSeam.Plural exists to keep each seam's wording + // through one shared selector, so audit's "sinks" is pinned here — without this, the + // argument could be dropped and nothing would fail. + Assert.Contains("sinks", failure.Message, StringComparison.Ordinal); + } - /// The providers.knowledge line the audit block is written after. - private const string KnowledgeLine = Configuration.ExampleDocument.LastProviderLine; + /// The providers.knowledge line the audit block is written after. + private const string KnowledgeLine = Configuration.ExampleDocument.LastProviderLine; + + /// Builds the section 8.1 document with one audit block written into it. + /// + /// The keys under providers.audit, one for each line and without indentation. No entry at + /// all leaves the block out, which is the case that must still produce a sink. + /// + /// + /// The raw string in ExampleDocument strips its common indentation, so inside + /// providers: a key sits at two spaces and its own keys at four. Every line is written here + /// rather than by the caller, because YAML indentation written by hand at a conversation site is how the + /// first draft of the telemetry tests failed. + /// + private static string Document(params string[] entries) + { + return entries.Length == 0 + ? Configuration.ExampleDocument.Yaml + : Configuration.ExampleDocument.Yaml.Replace( + KnowledgeLine, + KnowledgeLine + "\n audit:\n" + string.Join("\n", entries.Select(entry => " " + entry)), + StringComparison.Ordinal); + } - /// Builds the section 8.1 document with one audit block written into it. - /// - /// The keys under providers.audit, one for each line and without indentation. No entry at - /// all leaves the block out, which is the case that must still produce a sink. - /// - /// - /// The raw string in ExampleDocument strips its common indentation, so inside - /// providers: a key sits at two spaces and its own keys at four. Every line is written here - /// rather than by the caller, because YAML indentation written by hand at a conversation site is how the - /// first draft of the telemetry tests failed. - /// - private static string Document(params string[] entries) - => entries.Length == 0 - ? Configuration.ExampleDocument.Yaml - : Configuration.ExampleDocument.Yaml.Replace( - KnowledgeLine, - KnowledgeLine + "\n audit:\n" + string.Join("\n", entries.Select(entry => " " + entry)), - StringComparison.Ordinal); - - /// An adapter that opens nothing and records that it was asked. - private sealed class FakeAuditSinkAdapter(string kind) : IAuditSinkAdapter - { - public string Kind => kind; + /// An adapter that opens nothing and records that it was asked. + private sealed class FakeAuditSinkAdapter(string kind) : IAuditSinkAdapter + { + public string Kind => kind; - public int Opens { get; private set; } + public int Opens { get; private set; } - /// The store this adapter hands over. It is raw, and carries no queue of its own. - public IAuditSinkPort Sink { get; } = new FakeAuditSink(); + /// The store this adapter hands over. It is raw, and carries no queue of its own. + public IAuditSinkPort Sink { get; } = new FakeAuditSink(); - public ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - Opens++; - return ValueTask.FromResult(Sink); + public ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + Opens++; + return ValueTask.FromResult(Sink); + } } - } - /// A store that keeps nothing, and is a different type from the built-in one. - /// - /// It is deliberately not an . A vendor's store answering to a - /// vendor's kind and the built-in answering to memory must be told apart by type, or the - /// test that the built-in wins would pass against a factory that never had a built-in. - /// - private sealed class FakeAuditSink : IAuditSinkPort - { - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - => ValueTask.CompletedTask; + /// A store that keeps nothing, and is a different type from the built-in one. + /// + /// It is deliberately not an . A vendor's store answering to a + /// vendor's kind and the built-in answering to memory must be told apart by type, or the + /// test that the built-in wins would pass against a factory that never had a built-in. + /// + private sealed class FakeAuditSink : IAuditSinkPort + { + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) + { + return ValueTask.CompletedTask; + } + } } } diff --git a/tests/AgentCore.Application.Tests/Audit/ConversationSessionAuditTests.cs b/tests/AgentCore.Application.Tests/Audit/ConversationSessionAuditTests.cs index 04d2b1e4..d257cc72 100644 --- a/tests/AgentCore.Application.Tests/Audit/ConversationSessionAuditTests.cs +++ b/tests/AgentCore.Application.Tests/Audit/ConversationSessionAuditTests.cs @@ -1,6 +1,5 @@ using AgentCore.TestSupport; using AgentCore.Application.Audit.Memory; -using AgentCore.Application.Audit; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -14,20 +13,21 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Audit; - -/// -/// The turn loop writes the audit chain of D23, and the sink never sits on the turn. -/// -/// -/// The session is the only place that knows the turn index, both stages, and the identity a later -/// amendment must name, so it is the only place that produces an event. -/// -public sealed class ConversationSessionAuditTests +namespace AgentCore.Application.Tests.Audit { - private const string PolicyYaml = - """ + /// + /// The turn loop writes the audit chain of D23, and the sink never sits on the turn. + /// + /// + /// The session is the only place that knows the turn index, both stages, and the identity a later + /// amendment must name, so it is the only place that produces an event. + /// + public sealed class ConversationSessionAuditTests + { + private const string PolicyYaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: { type: boolean, default: false, writer: extractor } @@ -51,8 +51,8 @@ public sealed class ConversationSessionAuditTests - { id: close, agent: closer, terminal: true } """; - private const string ToolYaml = - """ + private const string ToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: lookup_order, kind: builtin, uses: orders.read, description: "Look up an order by its id." } @@ -66,562 +66,563 @@ public sealed class ConversationSessionAuditTests agent: only """; - private const string StayingNull = """{ "callerSaidGoodbye": null }"""; - private const string SaidGoodbye = """{ "callerSaidGoodbye": true }"""; + private const string StayingNull = /*lang=json,strict*/ """{ "callerSaidGoodbye": null }"""; + private const string SaidGoodbye = /*lang=json,strict*/ """{ "callerSaidGoodbye": true }"""; - // ------------------------------------------------------------------------------------------- - // The events, and the identity a later amendment names. - // ------------------------------------------------------------------------------------------- - [Fact] - public void ANewSession_WritesTheConversationStartedEvent() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - - var started = Assert.Single(sink.EventsOf("conversation-1")); - Assert.Equal(AuditEventKind.ConversationStarted, started.Kind); - Assert.NotEqual(Guid.Empty, started.EventId); - Assert.Null(started.TurnIndex); - Assert.Null(started.AmendsEventId); - Assert.Equal(session.ConversationId, started.ConversationId); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_CollidesWithNothing() - { - using SequencedChatClient reply = new("hello there.", "still here."); - using SequencedChatClient fill = new(StayingNull, StayingNull); - InMemoryAuditSink sink = new(); - - // One factory, so both sessions share one compiled agent and one store — which is what a host - // holds, and what makes the second session a resume rather than a different conversation. - var factory = Build(PolicyYaml, reply, fill, auditSink: sink); - - var first = factory.Create("conversation-1"); - await first.RunTurnAsync("hello", TestContext.Current.CancellationToken); - await first.FlushTranscriptAsync(); - - var second = factory.Create("conversation-1"); - await second.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - await second.FlushTranscriptAsync(); - - var written = sink.EventsOf("conversation-1"); - - // The shape is the assertion, and both halves of it are the point. - // - // ARRIVAL: before this change the second session restarted its counter at zero, store 3 - // refused every event it raised, and a resumed conversation lost its whole audit trail. The proof of - // the fix is that the second session's two events are HERE — distinctness proves nothing, - // because InMemoryAuditSink enforces no key and Guid.CreateVersion7 is unique by - // construction, so that assertion passed just as well over the two events that never arrived. - // - // A SECOND conversation.started: a session opening onto a conversation that already has words raises one, and - // it is kept rather than suppressed. See AuditEventKind.ConversationStarted for why. This is where - // that decision is visible, so a build that quietly stopped raising it fails here. - Assert.Equal( - [ - AuditEventKind.ConversationStarted, - AuditEventKind.TurnCompleted, - AuditEventKind.ConversationStarted, - AuditEventKind.TurnCompleted, - ], - written.Select(item => item.Kind).ToArray()); - - var ids = written.Select(item => item.EventId).ToArray(); - Assert.Equal(ids.Length, ids.Distinct().Count()); - Assert.DoesNotContain(Guid.Empty, ids); - } - - [Fact] - public async Task AFinishedTurn_WritesOneTurnCompletedEventWithBothStages() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - TestTimeProvider clock = new(); - var session = Build(PolicyYaml, reply, fill, timeProvider: clock, auditSink: sink).Create("conversation-1"); - - clock.Advance(TimeSpan.FromSeconds(12)); - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var completed = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.TurnCompleted); - Assert.Same(completed, sink.EventsOf("conversation-1")[1]); - Assert.Equal(0, completed.TurnIndex); - Assert.Equal(AuditHash.OfText("hello there.").Value, completed.Payload[AuditPayloadKeys.ReplyTextSha256]); - Assert.Equal("greeting", completed.Payload[AuditPayloadKeys.StageBefore]); - Assert.Equal("greeting", completed.Payload[AuditPayloadKeys.StageAfter]); - - // The moment comes from the injected clock and not from the sink. A background writer would - // stamp it one enqueue late. - Assert.Equal(clock.GetUtcNow(), completed.OccurredAt); - Assert.Equal(completed.OccurredAt, turn.EndedAt); - } - - [Fact] - public async Task ABargeIn_WritesASecondEventThatAmendsTheTurnEvent() - { - using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - - // The streaming shape, because only an audible turn is cut in flight: the caller heard the - // first fragment, then spoke over the rest. A turn that never streamed is never audible and - // its frame amends the turn before it instead — see AnInterruption_NeverCutsATurnThatDoesNotStream. - await using (var updates = session - .RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken) - .GetAsyncEnumerator(TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // The events, and the identity a later amendment names. + // ------------------------------------------------------------------------------------------- + [Fact] + public void ANewSession_WritesTheConversationStartedEvent() { - Assert.True(await updates.MoveNextAsync()); - Assert.True(session.Interrupt("hel", TimeSpan.FromMilliseconds(120))); - Assert.False(await updates.MoveNextAsync()); + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + + AuditEvent started = Assert.Single(sink.EventsOf("conversation-1")); + Assert.Equal(AuditEventKind.ConversationStarted, started.Kind); + Assert.NotEqual(Guid.Empty, started.EventId); + Assert.Null(started.TurnIndex); + Assert.Null(started.AmendsEventId); + Assert.Equal(session.ConversationId, started.ConversationId); } - var events = sink.EventsOf("conversation-1"); - var completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); - var cut = Assert.Single(events, item => item.Kind == AuditEventKind.ReplyInterrupted); + [Fact] + public async Task ASecondSessionOfOneConversation_CollidesWithNothing() + { + using SequencedChatClient reply = new("hello there.", "still here."); + using SequencedChatClient fill = new(StayingNull, StayingNull); + InMemoryAuditSink sink = new(); + + // One factory, so both sessions share one compiled agent and one store — which is what a host + // holds, and what makes the second session a resume rather than a different conversation. + ConversationSessionFactory factory = Build(PolicyYaml, reply, fill, auditSink: sink); + + ConversationSession first = factory.Create("conversation-1"); + _ = await first.RunTurnAsync("hello", TestContext.Current.CancellationToken); + await first.FlushTranscriptAsync(); + + ConversationSession second = factory.Create("conversation-1"); + _ = await second.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + await second.FlushTranscriptAsync(); + + IReadOnlyList written = sink.EventsOf("conversation-1"); + + // The shape is the assertion, and both halves of it are the point. + // + // ARRIVAL: before this change the second session restarted its counter at zero, store 3 + // refused every event it raised, and a resumed conversation lost its whole audit trail. The proof of + // the fix is that the second session's two events are HERE — distinctness proves nothing, + // because InMemoryAuditSink enforces no key and Guid.CreateVersion7 is unique by + // construction, so that assertion passed just as well over the two events that never arrived. + // + // A SECOND conversation.started: a session opening onto a conversation that already has words raises one, and + // it is kept rather than suppressed. See AuditEventKind.ConversationStarted for why. This is where + // that decision is visible, so a build that quietly stopped raising it fails here. + Assert.Equal( + [ + AuditEventKind.ConversationStarted, + AuditEventKind.TurnCompleted, + AuditEventKind.ConversationStarted, + AuditEventKind.TurnCompleted, + ], + written.Select(item => item.Kind).ToArray()); + + Guid[] ids = [.. written.Select(item => item.EventId)]; + Assert.Equal(ids.Length, ids.Distinct().Count()); + Assert.DoesNotContain(Guid.Empty, ids); + } - // T23: the chain is append-only, so an amendment is a second event that references the first. - var chain = sink.EventsOf("conversation-1"); - Assert.Equal(completed.EventId, cut.AmendsEventId); - Assert.True(chain.ToList().IndexOf(cut) > chain.ToList().IndexOf(completed)); - Assert.Equal(completed.TurnIndex, cut.TurnIndex); + [Fact] + public async Task AFinishedTurn_WritesOneTurnCompletedEventWithBothStages() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + TestTimeProvider clock = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, timeProvider: clock, auditSink: sink).Create("conversation-1"); + + clock.Advance(TimeSpan.FromSeconds(12)); + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + AuditEvent completed = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.TurnCompleted); + Assert.Same(completed, sink.EventsOf("conversation-1")[1]); + Assert.Equal(0, completed.TurnIndex); + Assert.Equal(AuditHash.OfText("hello there.").Value, completed.Payload[AuditPayloadKeys.ReplyTextSha256]); + Assert.Equal("greeting", completed.Payload[AuditPayloadKeys.StageBefore]); + Assert.Equal("greeting", completed.Payload[AuditPayloadKeys.StageAfter]); + + // The moment comes from the injected clock and not from the sink. A background writer would + // stamp it one enqueue late. + Assert.Equal(clock.GetUtcNow(), completed.OccurredAt); + Assert.Equal(completed.OccurredAt, turn.EndedAt); + } - // Item 6a: the event records the text the caller ACTUALLY HEARD. Nothing here is estimated, - // because the relay reported both values on its interrupt frame. - Assert.Equal(AuditHash.OfText("hel").Value, cut.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); - Assert.Equal("120", cut.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); - } + [Fact] + public async Task ABargeIn_WritesASecondEventThatAmendsTheTurnEvent() + { + using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + + // The streaming shape, because only an audible turn is cut in flight: the caller heard the + // first fragment, then spoke over the rest. A turn that never streamed is never audible and + // its frame amends the turn before it instead — see AnInterruption_NeverCutsATurnThatDoesNotStream. + await using (IAsyncEnumerator updates = session + .RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken) + .GetAsyncEnumerator(TestContext.Current.CancellationToken)) + { + Assert.True(await updates.MoveNextAsync()); + Assert.True(session.Interrupt("hel", TimeSpan.FromMilliseconds(120))); + Assert.False(await updates.MoveNextAsync()); + } + + IReadOnlyList events = sink.EventsOf("conversation-1"); + AuditEvent completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); + AuditEvent cut = Assert.Single(events, item => item.Kind == AuditEventKind.ReplyInterrupted); + + // T23: the chain is append-only, so an amendment is a second event that references the first. + IReadOnlyList chain = sink.EventsOf("conversation-1"); + Assert.Equal(completed.EventId, cut.AmendsEventId); + Assert.True(chain.ToList().IndexOf(cut) > chain.ToList().IndexOf(completed)); + Assert.Equal(completed.TurnIndex, cut.TurnIndex); + + // Item 6a: the event records the text the caller ACTUALLY HEARD. Nothing here is estimated, + // because the relay reported both values on its interrupt frame. + Assert.Equal(AuditHash.OfText("hel").Value, cut.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); + Assert.Equal("120", cut.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); + } - [Fact] - public async Task TheFourthConsecutiveToolFailure_WritesAToolFailedEventBeforeTheTurnEvent() - { - using LoopingToolCallingChatClient reply = new(); - InMemoryAuditSink sink = new(); - var session = Build(ToolYaml, reply, null, new ThrowingToolBuilder().Create, auditSink: sink).Create("conversation-1"); - - await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - var events = sink.EventsOf("conversation-1"); - var failures = events.Where(item => item.Kind == AuditEventKind.ToolFailed).ToArray(); - var completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); - - // The kind is raised at two altitudes and both are here: one row for each conversation that failed, - // and one for the turn that ended because of them. Five in all, and every one of them before - // the turn event. - Assert.Equal(5, failures.Length); - var order = sink.EventsOf("conversation-1").ToList(); - Assert.All(failures, failure => Assert.True(order.IndexOf(failure) < order.IndexOf(completed))); - Assert.All(failures, failure => Assert.Equal(0, failure.TurnIndex)); - - // The turn-level row is the one section 8.7 row six has always written, and it is unchanged: - // no tool is named, because the fault reaches the session with no function name on it, and a - // missing fact is an absent key rather than the word "unknown". - var turnLevel = Assert.Single( - failures, - failure => !failure.Payload.ContainsKey(AuditPayloadKeys.ToolCallId)); - Assert.False(turnLevel.Payload.ContainsKey(AuditPayloadKeys.ToolName)); - Assert.Contains( - ThrowingToolBuilder.Message, - turnLevel.Payload[AuditPayloadKeys.ToolError], - StringComparison.Ordinal); - - // The four call-level rows are the new fact, and each one names its tool. The fourth is the - // one that spent the budget: the framework does not capture that exception at all, so it never - // reaches CreateResponseMessages, and only the invocation hook sees it. - var conversations = failures.Where(failure => failure.Payload.ContainsKey(AuditPayloadKeys.ToolCallId)).ToArray(); - Assert.Equal(4, conversations.Length); - Assert.All(conversations, conversation => Assert.Equal("lookup_order", conversation.Payload[AuditPayloadKeys.ToolName])); - Assert.All( - conversations, - conversation => Assert.Equal( - ToolFailureKinds.ToToken(ToolFailureKind.Faulted), - conversation.Payload[AuditPayloadKeys.ToolFailureKind])); - Assert.All( - conversations, - conversation => Assert.Contains( + [Fact] + public async Task TheFourthConsecutiveToolFailure_WritesAToolFailedEventBeforeTheTurnEvent() + { + using LoopingToolCallingChatClient reply = new(); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(ToolYaml, reply, null, new ThrowingToolBuilder().Create, auditSink: sink).Create("conversation-1"); + + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + IReadOnlyList events = sink.EventsOf("conversation-1"); + AuditEvent[] failures = [.. events.Where(item => item.Kind == AuditEventKind.ToolFailed)]; + AuditEvent completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); + + // The kind is raised at two altitudes and both are here: one row for each conversation that failed, + // and one for the turn that ended because of them. Five in all, and every one of them before + // the turn event. + Assert.Equal(5, failures.Length); + List order = [.. sink.EventsOf("conversation-1")]; + Assert.All(failures, failure => Assert.True(order.IndexOf(failure) < order.IndexOf(completed))); + Assert.All(failures, failure => Assert.Equal(0, failure.TurnIndex)); + + // The turn-level row is the one section 8.7 row six has always written, and it is unchanged: + // no tool is named, because the fault reaches the session with no function name on it, and a + // missing fact is an absent key rather than the word "unknown". + AuditEvent turnLevel = Assert.Single( + failures, + failure => !failure.Payload.ContainsKey(AuditPayloadKeys.ToolCallId)); + Assert.False(turnLevel.Payload.ContainsKey(AuditPayloadKeys.ToolName)); + Assert.Contains( ThrowingToolBuilder.Message, - conversation.Payload[AuditPayloadKeys.ToolError], - StringComparison.Ordinal)); - - // Four conversations, four ids, and none of them repeated. The name alone could never have told them - // apart, and the chain used to hold neither. - var ids = conversations.Select(conversation => conversation.Payload[AuditPayloadKeys.ToolCallId]).ToArray(); - Assert.Equal(4, ids.Distinct(StringComparer.Ordinal).Count()); - - // The chain still verifies over every one of the new keys. - Assert.All(events, AuditEventVocabulary.Validate); - } + turnLevel.Payload[AuditPayloadKeys.ToolError], + StringComparison.Ordinal); + + // The four call-level rows are the new fact, and each one names its tool. The fourth is the + // one that spent the budget: the framework does not capture that exception at all, so it never + // reaches CreateResponseMessages, and only the invocation hook sees it. + AuditEvent[] conversations = [.. failures.Where(failure => failure.Payload.ContainsKey(AuditPayloadKeys.ToolCallId))]; + Assert.Equal(4, conversations.Length); + Assert.All(conversations, conversation => Assert.Equal("lookup_order", conversation.Payload[AuditPayloadKeys.ToolName])); + Assert.All( + conversations, + conversation => Assert.Equal( + ToolFailureKinds.ToToken(ToolFailureKind.Faulted), + conversation.Payload[AuditPayloadKeys.ToolFailureKind])); + Assert.All( + conversations, + conversation => Assert.Contains( + ThrowingToolBuilder.Message, + conversation.Payload[AuditPayloadKeys.ToolError], + StringComparison.Ordinal)); + + // Four conversations, four ids, and none of them repeated. The name alone could never have told them + // apart, and the chain used to hold neither. + string[] ids = [.. conversations.Select(conversation => conversation.Payload[AuditPayloadKeys.ToolCallId])]; + Assert.Equal(4, ids.Distinct(StringComparer.Ordinal).Count()); + + // The chain still verifies over every one of the new keys. + Assert.All(events, AuditEventVocabulary.Validate); + } - // ------------------------------------------------------------------------------------------- - // The facts of one tool call. §8.7 row six is the turn-level fact; these are the conversation-level ones. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AToolThatFaults_NamesTheToolAndTheConversationIdInTheChain() - { - // One failing round, then the model answers, so the turn ends normally and the only thing - // that could ever have recorded the tool is the observer. - using NamedToolCallingChatClient reply = new("lookup_order", "I could not reach the order system."); - InMemoryAuditSink sink = new(); - UnreachableEndpointToolBuilder tools = new(); - var session = Build(ToolYaml, reply, null, tools.Create, auditSink: sink).Create("conversation-1"); - - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - var failed = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ToolFailed); - Assert.Equal("lookup_order", failed.Payload[AuditPayloadKeys.ToolName]); - Assert.Equal(reply.CallIds[0], failed.Payload[AuditPayloadKeys.ToolCallId]); - Assert.Equal( - ToolFailureKinds.ToToken(ToolFailureKind.Faulted), - failed.Payload[AuditPayloadKeys.ToolFailureKind]); - Assert.Contains( - UnreachableEndpointToolBuilder.Message, - failed.Payload[AuditPayloadKeys.ToolError], - StringComparison.Ordinal); - - // One failure is under the budget, so the turn is an ordinary turn that spoke. - Assert.Null(turn.Failure); - Assert.Equal(0, failed.TurnIndex); - } + // ------------------------------------------------------------------------------------------- + // The facts of one tool call. §8.7 row six is the turn-level fact; these are the conversation-level ones. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AToolThatFaults_NamesTheToolAndTheConversationIdInTheChain() + { + // One failing round, then the model answers, so the turn ends normally and the only thing + // that could ever have recorded the tool is the observer. + using NamedToolCallingChatClient reply = new("lookup_order", "I could not reach the order system."); + InMemoryAuditSink sink = new(); + UnreachableEndpointToolBuilder tools = new(); + ConversationSession session = Build(ToolYaml, reply, null, tools.Create, auditSink: sink).Create("conversation-1"); - [Fact] - public async Task AHallucinatedToolName_ReachesTheChain() - { - // The model invented the name. The framework answers it with a message and NO exception, so - // it spends none of the error budget and the turn goes on — which is correct, and is exactly - // why nothing else in the system would ever have recorded that it happened. - using NamedToolCallingChatClient reply = new("lookup_ordar", "Let me try that again."); - InMemoryAuditSink sink = new(); - var session = Build(ToolYaml, reply, null, new StubToolBuilder("""{"status":"shipped"}""").Create, auditSink: sink) - .Create("conversation-1"); - - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - var failed = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ToolFailed); - - // The name recorded is the name the MODEL called, so a reader that joins it to tools[].id - // finds nothing — which is the finding. - Assert.Equal("lookup_ordar", failed.Payload[AuditPayloadKeys.ToolName]); - Assert.Equal(reply.CallIds[0], failed.Payload[AuditPayloadKeys.ToolCallId]); - Assert.Equal( - ToolFailureKinds.ToToken(ToolFailureKind.Undeclared), - failed.Payload[AuditPayloadKeys.ToolFailureKind]); - - // The turn is unharmed: no exception, no budget spent, and the caller heard a real reply. - Assert.Null(turn.Failure); - Assert.Equal("Let me try that again.", turn.ReplyText); - } + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - [Fact] - public async Task TwoParallelCallsToTheSameTool_AreTwoDistinguishableRecords() - { - // One assistant message, two calls, one tool name. Without the call id these are one fact - // written twice, and a reader cannot tell which call failed. - using NamedToolCallingChatClient reply = new("lookup_order", "Both lookups failed.", callsPerTurn: 2); - InMemoryAuditSink sink = new(); - var session = Build(ToolYaml, reply, null, new UnreachableEndpointToolBuilder().Create, auditSink: sink) - .Create("conversation-1"); + AuditEvent failed = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ToolFailed); + Assert.Equal("lookup_order", failed.Payload[AuditPayloadKeys.ToolName]); + Assert.Equal(reply.CallIds[0], failed.Payload[AuditPayloadKeys.ToolCallId]); + Assert.Equal( + ToolFailureKinds.ToToken(ToolFailureKind.Faulted), + failed.Payload[AuditPayloadKeys.ToolFailureKind]); + Assert.Contains( + UnreachableEndpointToolBuilder.Message, + failed.Payload[AuditPayloadKeys.ToolError], + StringComparison.Ordinal); + + // One failure is under the budget, so the turn is an ordinary turn that spoke. + Assert.Null(turn.Failure); + Assert.Equal(0, failed.TurnIndex); + } - await session.RunTurnAsync("where are my two orders", TestContext.Current.CancellationToken); + [Fact] + public async Task AHallucinatedToolName_ReachesTheChain() + { + // The model invented the name. The framework answers it with a message and NO exception, so + // it spends none of the error budget and the turn goes on — which is correct, and is exactly + // why nothing else in the system would ever have recorded that it happened. + using NamedToolCallingChatClient reply = new("lookup_ordar", "Let me try that again."); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(ToolYaml, reply, null, new StubToolBuilder(/*lang=json,strict*/ """{"status":"shipped"}""").Create, auditSink: sink) + .Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + AuditEvent failed = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ToolFailed); + + // The name recorded is the name the MODEL called, so a reader that joins it to tools[].id + // finds nothing — which is the finding. + Assert.Equal("lookup_ordar", failed.Payload[AuditPayloadKeys.ToolName]); + Assert.Equal(reply.CallIds[0], failed.Payload[AuditPayloadKeys.ToolCallId]); + Assert.Equal( + ToolFailureKinds.ToToken(ToolFailureKind.Undeclared), + failed.Payload[AuditPayloadKeys.ToolFailureKind]); - var failures = sink.EventsOf("conversation-1").Where(item => item.Kind == AuditEventKind.ToolFailed).ToArray(); + // The turn is unharmed: no exception, no budget spent, and the caller heard a real reply. + Assert.Null(turn.Failure); + Assert.Equal("Let me try that again.", turn.ReplyText); + } - Assert.Equal(2, failures.Length); - Assert.All(failures, failure => Assert.Equal("lookup_order", failure.Payload[AuditPayloadKeys.ToolName])); - Assert.Equal( - reply.CallIds.ToArray(), - failures.Select(failure => failure.Payload[AuditPayloadKeys.ToolCallId]).Order(StringComparer.Ordinal).ToArray()); + [Fact] + public async Task TwoParallelCallsToTheSameTool_AreTwoDistinguishableRecords() + { + // One assistant message, two calls, one tool name. Without the call id these are one fact + // written twice, and a reader cannot tell which call failed. + using NamedToolCallingChatClient reply = new("lookup_order", "Both lookups failed.", callsPerTurn: 2); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(ToolYaml, reply, null, new UnreachableEndpointToolBuilder().Create, auditSink: sink) + .Create("conversation-1"); - // Two records, and the chain still verifies over them. - Assert.All(sink.EventsOf("conversation-1"), AuditEventVocabulary.Validate); - } + _ = await session.RunTurnAsync("where are my two orders", TestContext.Current.CancellationToken); - [Fact] - public async Task AToolWhoseFaultTheModelCanAnswer_WritesNoToolFailedEventAtAll() - { - // The converged design, from the chain's side: the tool ANSWERED. The framework sees a result - // and no exception, so nothing failed as far as it is concerned and no row is written. - using NamedToolCallingChatClient reply = new("lookup_order", "That order is already closed."); - InMemoryAuditSink sink = new(); - var session = Build(ToolYaml, reply, null, new RefusedRequestToolBuilder().Create, auditSink: sink) - .Create("conversation-1"); - - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - Assert.DoesNotContain(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ToolFailed); - Assert.Null(turn.Failure); - Assert.Equal("That order is already closed.", turn.ReplyText); - } + AuditEvent[] failures = [.. sink.EventsOf("conversation-1").Where(item => item.Kind == AuditEventKind.ToolFailed)]; - /// T44: one compiled agent serves every conversation, so nothing per conversation may live on it. - [Fact] - public async Task TwoConversationsAtOnce_DoNotPolluteEachOthersRecords() - { - const int FanOut = 8; - InMemoryAuditSink sink = new(); + Assert.Equal(2, failures.Length); + Assert.All(failures, failure => Assert.Equal("lookup_order", failure.Payload[AuditPayloadKeys.ToolName])); + Assert.Equal( + reply.CallIds.ToArray(), + failures.Select(failure => failure.Payload[AuditPayloadKeys.ToolCallId]).Order(StringComparer.Ordinal).ToArray()); - // One factory, one document, one compiled agent behind the sessions — the shape T44 pins. - using NamedToolCallingChatClient reply = new("lookup_order", "I could not reach the order system."); - var factory = Build(ToolYaml, reply, null, new UnreachableEndpointToolBuilder().Create, auditSink: sink); + // Two records, and the chain still verifies over them. + Assert.All(sink.EventsOf("conversation-1"), AuditEventVocabulary.Validate); + } - var token = TestContext.Current.CancellationToken; - using Barrier gate = new(FanOut); + [Fact] + public async Task AToolWhoseFaultTheModelCanAnswer_WritesNoToolFailedEventAtAll() + { + // The converged design, from the chain's side: the tool ANSWERED. The framework sees a result + // and no exception, so nothing failed as far as it is concerned and no row is written. + using NamedToolCallingChatClient reply = new("lookup_order", "That order is already closed."); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(ToolYaml, reply, null, new RefusedRequestToolBuilder().Create, auditSink: sink) + .Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + Assert.DoesNotContain(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ToolFailed); + Assert.Null(turn.Failure); + Assert.Equal("That order is already closed.", turn.ReplyText); + } - await Task.WhenAll(Enumerable.Range(0, FanOut).Select(index => Task.Run( - async () => + /// T44: one compiled agent serves every conversation, so nothing per conversation may live on it. + [Fact] + public async Task TwoConversationsAtOnce_DoNotPolluteEachOthersRecords() + { + const int FanOut = 8; + InMemoryAuditSink sink = new(); + + // One factory, one document, one compiled agent behind the sessions — the shape T44 pins. + using NamedToolCallingChatClient reply = new("lookup_order", "I could not reach the order system."); + ConversationSessionFactory factory = Build(ToolYaml, reply, null, new UnreachableEndpointToolBuilder().Create, auditSink: sink); + + CancellationToken token = TestContext.Current.CancellationToken; + using Barrier gate = new(FanOut); + + await Task.WhenAll(Enumerable.Range(0, FanOut).Select(index => Task.Run( + async () => + { + ConversationSession session = factory.Create($"conversation-{index}"); + gate.SignalAndWait(token); + _ = await session.RunTurnAsync("where is my order", token).ConfigureAwait(false); + }, + token))); + + for (int index = 0; index < FanOut; index++) { - var session = factory.Create($"conversation-{index}"); - gate.SignalAndWait(token); - await session.RunTurnAsync("where is my order", token).ConfigureAwait(false); - }, - token))); + IReadOnlyList events = sink.EventsOf($"conversation-{index}"); + + // Each conversation recorded exactly its own failure, under its own id, and its three events kept + // their own order. A record that had leaked between two flows would show up as a second + // tool.failed here or as one of these kinds out of place. + AuditEvent failed = Assert.Single(events, item => item.Kind == AuditEventKind.ToolFailed); + Assert.Equal("lookup_order", failed.Payload[AuditPayloadKeys.ToolName]); + Assert.NotEmpty(failed.Payload[AuditPayloadKeys.ToolCallId]); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.ToolFailed, AuditEventKind.TurnCompleted], + events.Select(item => item.Kind).ToArray()); + Assert.All(events, AuditEventVocabulary.Validate); + } + } - for (var index = 0; index < FanOut; index++) + [Fact] + public async Task ATerminalStage_ClosesTheChainWithOneConversationEndedEvent() { - var events = sink.EventsOf($"conversation-{index}"); + using SequencedChatClient reply = new("goodbye."); + using SequencedChatClient fill = new(SaidGoodbye); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - // Each conversation recorded exactly its own failure, under its own id, and its three events kept - // their own order. A record that had leaked between two flows would show up as a second - // tool.failed here or as one of these kinds out of place. - var failed = Assert.Single(events, item => item.Kind == AuditEventKind.ToolFailed); - Assert.Equal("lookup_order", failed.Payload[AuditPayloadKeys.ToolName]); - Assert.NotEmpty(failed.Payload[AuditPayloadKeys.ToolCallId]); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.ToolFailed, AuditEventKind.TurnCompleted], - events.Select(item => item.Kind).ToArray()); - Assert.All(events, AuditEventVocabulary.Validate); - } - } + _ = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); - [Fact] - public async Task ATerminalStage_ClosesTheChainWithOneConversationEndedEvent() - { - using SequencedChatClient reply = new("goodbye."); - using SequencedChatClient fill = new(SaidGoodbye); - InMemoryAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + Assert.True(session.IsComplete); + AuditEvent ended = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); + Assert.Null(ended.TurnIndex); - await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); + // The reason is one token of the closed set, so a report can count it. The terminal stage is + // detail beside it, and it is not the reason. + Assert.Equal("agent.completed", ended.Payload[AuditPayloadKeys.EndReason]); + Assert.Equal("close", ended.Payload[AuditPayloadKeys.StageAfter]); - Assert.True(session.IsComplete); - var ended = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); - Assert.Null(ended.TurnIndex); + // A hang-up frame that arrives after the machine already closed the conversation writes nothing. + Assert.False(session.EndConversation(ConversationEndReason.CallerHungUp)); + } - // The reason is one token of the closed set, so a report can count it. The terminal stage is - // detail beside it, and it is not the reason. - Assert.Equal("agent.completed", ended.Payload[AuditPayloadKeys.EndReason]); - Assert.Equal("close", ended.Payload[AuditPayloadKeys.StageAfter]); + [Fact] + public void AHostThatEndsTheConversation_ClosesTheChainOnce() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - // A hang-up frame that arrives after the machine already closed the conversation writes nothing. - Assert.False(session.EndConversation(ConversationEndReason.CallerHungUp)); - } + Assert.True(session.EndConversation(ConversationEndReason.CallerHungUp)); + Assert.False(session.EndConversation(ConversationEndReason.CallerHungUp)); - [Fact] - public void AHostThatEndsTheConversation_ClosesTheChainOnce() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + AuditEvent ended = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); + Assert.Equal("caller.hangup", ended.Payload[AuditPayloadKeys.EndReason]); - Assert.True(session.EndConversation(ConversationEndReason.CallerHungUp)); - Assert.False(session.EndConversation(ConversationEndReason.CallerHungUp)); + // The machine never ran, so no stage closed the conversation and no stage rides on the event. + Assert.False(ended.Payload.ContainsKey(AuditPayloadKeys.StageAfter)); + Assert.True(session.IsComplete); + } - var ended = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); - Assert.Equal("caller.hangup", ended.Payload[AuditPayloadKeys.EndReason]); + /// Section 11, item 5: the conversation goes to a human through the conference pattern. + [Fact] + public void ATransferToAHuman_ClosesTheChainWithItsOwnReason() + { + using SequencedChatClient reply = new("one moment please."); + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - // The machine never ran, so no stage closed the conversation and no stage rides on the event. - Assert.False(ended.Payload.ContainsKey(AuditPayloadKeys.StageAfter)); - Assert.True(session.IsComplete); - } + // The adapter joins the conversation to a conference and never sends the transfer command (T27). + Assert.True(session.EndConversation(ConversationEndReason.TransferredToHuman)); - /// Section 11, item 5: the conversation goes to a human through the conference pattern. - [Fact] - public void ATransferToAHuman_ClosesTheChainWithItsOwnReason() - { - using SequencedChatClient reply = new("one moment please."); - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + AuditEvent ended = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); + Assert.Equal("agent.transferred", ended.Payload[AuditPayloadKeys.EndReason]); + } - // The adapter joins the conversation to a conference and never sends the transfer command (T27). - Assert.True(session.EndConversation(ConversationEndReason.TransferredToHuman)); + [Fact] + public void AReasonOutsideTheClosedSet_EndsNoConversation() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - var ended = Assert.Single(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); - Assert.Equal("agent.transferred", ended.Payload[AuditPayloadKeys.EndReason]); - } + _ = Assert.Throws(() => session.EndConversation((ConversationEndReason)99)); - [Fact] - public void AReasonOutsideTheClosedSet_EndsNoConversation() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + // Nothing moved. The conversation still runs, and the chain still holds only its first event. + Assert.False(session.IsComplete); + Assert.DoesNotContain(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); + } - Assert.Throws(() => session.EndConversation((ConversationEndReason)99)); + // ------------------------------------------------------------------------------------------- + // Item 6: the chain the events form verifies. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheEventsOfOneConversation_FormAChainThatVerifies() + { + using SequencedChatClient reply = new("hello there.", "goodbye."); + using SequencedChatClient fill = new(StayingNull, SaidGoodbye); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - // Nothing moved. The conversation still runs, and the chain still holds only its first event. - Assert.False(session.IsComplete); - Assert.DoesNotContain(sink.EventsOf("conversation-1"), item => item.Kind == AuditEventKind.ConversationEnded); - } + CancellationToken token = TestContext.Current.CancellationToken; + _ = await session.RunTurnAsync("hi", token); + _ = await session.RunTurnAsync("goodbye", token); - // ------------------------------------------------------------------------------------------- - // Item 6: the chain the events form verifies. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheEventsOfOneConversation_FormAChainThatVerifies() - { - using SequencedChatClient reply = new("hello there.", "goodbye."); - using SequencedChatClient fill = new(StayingNull, SaidGoodbye); - InMemoryAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + IReadOnlyList events = sink.EventsOf("conversation-1"); - var token = TestContext.Current.CancellationToken; - await session.RunTurnAsync("hi", token); - await session.RunTurnAsync("goodbye", token); + // Four facts, four identities, none of them repeated. What orders them is + // audit_event.sequence, which the store assigns and which this test never sees. + Assert.Equal(4, events.Count); + Assert.Equal(events.Count, events.Select(item => item.EventId).Distinct().Count()); - var events = sink.EventsOf("conversation-1"); + // This is chain_check of section 11, item 6, run over what the turn loop produced. + Assert.All(events, AuditEventVocabulary.Validate); + } - // Four facts, four identities, none of them repeated. What orders them is - // audit_event.sequence, which the store assigns and which this test never sees. - Assert.Equal(4, events.Count); - Assert.Equal(events.Count, events.Select(item => item.EventId).Distinct().Count()); + // ------------------------------------------------------------------------------------------- + // D23: the write never sits on the turn. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheTurn_FinishesWhileTheAppendIsStillOpen() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + BlockingAuditSink sink = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); - // This is chain_check of section 11, item 6, run over what the turn loop produced. - Assert.All(events, AuditEventVocabulary.Validate); - } + // Section 7: a durable insert costs 13 ms at p50 and 32 ms at p99, against 91 nanoseconds to + // enqueue. The turn therefore finishes with no append complete at all. + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // D23: the write never sits on the turn. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheTurn_FinishesWhileTheAppendIsStillOpen() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - BlockingAuditSink sink = new(); - var session = Build(PolicyYaml, reply, fill, auditSink: sink).Create("conversation-1"); + Assert.Equal("hello there.", turn.ReplyText); - // Section 7: a durable insert costs 13 ms at p50 and 32 ms at p99, against 91 nanoseconds to - // enqueue. The turn therefore finishes with no append complete at all. - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + // The whole turn ran and returned while conversation.started is still inside the sink. The + // turn.completed event is queued behind it rather than racing past it, because the events of + // one conversation reach an observer in the order the conversation raised them, so exactly one has arrived. + _ = Assert.Single(sink.Events); - Assert.Equal("hello there.", turn.ReplyText); + sink.Release(); - // The whole turn ran and returned while conversation.started is still inside the sink. The - // turn.completed event is queued behind it rather than racing past it, because the events of - // one conversation reach an observer in the order the conversation raised them, so exactly one has arrived. - Assert.Single(sink.Events); + // Off the turn, and only now. The queued event lands on the dispatcher's own task, which is + // where a slow sink is paid for. + DateTimeOffset deadline = DateTimeOffset.UtcNow + TimeSpan.FromSeconds(10); + while (sink.Events.Count < 2 && DateTimeOffset.UtcNow < deadline) + { + await Task.Delay(10, TestContext.Current.CancellationToken); + } - sink.Release(); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], + sink.Events.Select(item => item.Kind).ToArray()); + } - // Off the turn, and only now. The queued event lands on the dispatcher's own task, which is - // where a slow sink is paid for. - var deadline = DateTimeOffset.UtcNow + TimeSpan.FromSeconds(10); - while (sink.Events.Count < 2 && DateTimeOffset.UtcNow < deadline) + [Fact] + public async Task ASinkThatRefusesAnEvent_IsLoggedAndTheTurnGoesOn() { - await Task.Delay(10, TestContext.Current.CancellationToken); + RecordingLogger logger = new(); + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: new ThrowingAuditSink(), logger: logger) + .Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // Audit is a record of the conversation and never a part of it. + Assert.Equal("hello there.", turn.ReplyText); + Assert.NotEmpty(logger.Of(5)); + Assert.All(logger.Of(5), line => Assert.Equal(LogLevel.Error, line.Level)); } - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], - sink.Events.Select(item => item.Kind).ToArray()); - } - - [Fact] - public async Task ASinkThatRefusesAnEvent_IsLoggedAndTheTurnGoesOn() - { - RecordingLogger logger = new(); - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill, auditSink: new ThrowingAuditSink(), logger: logger) - .Create("conversation-1"); - - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // Audit is a record of the conversation and never a part of it. - Assert.Equal("hello there.", turn.ReplyText); - Assert.NotEmpty(logger.Of(5)); - Assert.All(logger.Of(5), line => Assert.Equal(LogLevel.Error, line.Level)); - } - - [Fact] - public async Task ASessionWithNoSink_RunsATurnAndThrowsNothing() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create("conversation-1"); - - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + [Fact] + public async Task ASessionWithNoSink_RunsATurnAndThrowsNothing() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create("conversation-1"); - Assert.Equal("hello there.", turn.ReplyText); - } + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // The in-memory sink. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheInMemorySink_KeepsTheConversationsApart() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - InMemoryAuditSink sink = new(); - var factory = Build(PolicyYaml, reply, fill, auditSink: sink); - - var first = factory.Create("conversation-1"); - var second = factory.Create("conversation-2"); - await first.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // One sink serves every conversation, because a session names itself on every event. - Assert.Equal(2, sink.EventsOf("conversation-1").Count); - Assert.Single(sink.EventsOf("conversation-2")); - Assert.Equal(3, sink.Events.Count); - Assert.Equal("conversation-2", second.ConversationId); - } + Assert.Equal("hello there.", turn.ReplyText); + } - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IChatClient? fill, - Func? tools = null, - TimeProvider? timeProvider = null, - IAuditSinkPort? auditSink = null, - ILogger? logger = null) - { - // There is always a sink now: ConversationObservers.Standard takes a required one, because the - // composition root resolves providers.audit for every host and falls back to the in-process - // memory kind. An optional parameter has to be a compile-time constant, so the default is - // spelled here instead — a fact that does not care where its events land gets a fresh - // in-memory sink and reads exactly as it did when it passed nothing. - IAuditSinkPort sink = auditSink ?? new InMemoryAuditSink(); - - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(reply); - if (fill is not null) + // ------------------------------------------------------------------------------------------- + // The in-memory sink. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheInMemorySink_KeepsTheConversationsApart() { - chatClients.Route("fill", fill); + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + InMemoryAuditSink sink = new(); + ConversationSessionFactory factory = Build(PolicyYaml, reply, fill, auditSink: sink); + + ConversationSession first = factory.Create("conversation-1"); + ConversationSession second = factory.Create("conversation-2"); + _ = await first.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // One sink serves every conversation, because a session names itself on every event. + Assert.Equal(2, sink.EventsOf("conversation-1").Count); + _ = Assert.Single(sink.EventsOf("conversation-2")); + Assert.Equal(3, sink.Events.Count); + Assert.Equal("conversation-2", second.ConversationId); } - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IChatClient? fill, + Func? tools = null, + TimeProvider? timeProvider = null, + IAuditSinkPort? auditSink = null, + ILogger? logger = null) + { + // There is always a sink now: ConversationObservers.Standard takes a required one, because the + // composition root resolves providers.audit for every host and falls back to the in-process + // memory kind. An optional parameter has to be a compile-time constant, so the default is + // spelled here instead — a fact that does not care where its events land gets a fresh + // in-memory sink and reads exactly as it did when it passed nothing. + IAuditSinkPort sink = auditSink ?? new InMemoryAuditSink(); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + if (fill is not null) { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - timeProvider, - logger, - ConversationObservers.Standard(sink, logger)); + _ = chatClients.Route("fill", fill); + } + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + timeProvider, + logger, + ConversationObservers.Standard(sink, logger)); + } } } diff --git a/tests/AgentCore.Application.Tests/Audit/ConversationSessionModerationTests.cs b/tests/AgentCore.Application.Tests/Audit/ConversationSessionModerationTests.cs index 18f14ea9..9fd33f85 100644 --- a/tests/AgentCore.Application.Tests/Audit/ConversationSessionModerationTests.cs +++ b/tests/AgentCore.Application.Tests/Audit/ConversationSessionModerationTests.cs @@ -1,6 +1,5 @@ using AgentCore.TestSupport; using AgentCore.Application.Audit.Memory; -using AgentCore.Application.Audit; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -15,29 +14,30 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Audit; - -/// -/// Moderation reads what the caller said before the model runs, and refuses a flagged turn. -/// -/// -/// -/// The owner decided this on 2026-08-13. It departs from section 11 item 11, which asked for the -/// agent's REPLY to be moderated and recorded. Recording a harmful reply protects nobody, because -/// the caller already heard it. Reply moderation is withdrawn, because the model carries its own -/// safety training, so prompt.flagged is the only moderation kind the chain has. -/// -/// -/// The one rule that separates prompt.flagged from reply.interrupted is here: the -/// verdict is known BEFORE the model runs, so the event is written before turn.completed and -/// amends nothing. -/// -/// -public sealed class ConversationSessionModerationTests +namespace AgentCore.Application.Tests.Audit { - private const string PlainYaml = - """ + /// + /// Moderation reads what the caller said before the model runs, and refuses a flagged turn. + /// + /// + /// + /// The owner decided this on 2026-08-13. It departs from section 11 item 11, which asked for the + /// agent's REPLY to be moderated and recorded. Recording a harmful reply protects nobody, because + /// the caller already heard it. Reply moderation is withdrawn, because the model carries its own + /// safety training, so prompt.flagged is the only moderation kind the chain has. + /// + /// + /// The one rule that separates prompt.flagged from reply.interrupted is here: the + /// verdict is known BEFORE the model runs, so the event is written before turn.completed and + /// amends nothing. + /// + /// + public sealed class ConversationSessionModerationTests + { + private const string PlainYaml = + """ apiVersion: agentcore/v1 refusalReply: "I am sorry. I cannot help with that request." agents: @@ -50,8 +50,8 @@ public sealed class ConversationSessionModerationTests agent: only """; - private const string ExtractingYaml = - """ + private const string ExtractingYaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: { type: boolean, default: false, writer: extractor } @@ -68,311 +68,312 @@ public sealed class ConversationSessionModerationTests agent: only """; - // ------------------------------------------------------------------------------------------- - // A flagged prompt. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AFlaggedPrompt_WritesTheFlagBeforeTheTurnEvent() - { - InMemoryAuditSink sink = new(); - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, - moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); - - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + // ------------------------------------------------------------------------------------------- + // A flagged prompt. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AFlaggedPrompt_WritesTheFlagBeforeTheTurnEvent() + { + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, + moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); - var events = sink.EventsOf("conversation-1"); - var flagged = Assert.Single(events, e => e.Kind == AuditEventKind.PromptFlagged); - var completed = Assert.Single(events, e => e.Kind == AuditEventKind.TurnCompleted); + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - // The verdict precedes the model, so the flag precedes the turn event and amends nothing. - var order = events.ToList(); - Assert.True(order.IndexOf(flagged) < order.IndexOf(completed)); - Assert.Null(flagged.AmendsEventId); - Assert.Equal(0, flagged.TurnIndex); - } + IReadOnlyList events = sink.EventsOf("conversation-1"); + AuditEvent flagged = Assert.Single(events, e => e.Kind == AuditEventKind.PromptFlagged); + AuditEvent completed = Assert.Single(events, e => e.Kind == AuditEventKind.TurnCompleted); - [Fact] - public async Task AFlaggedPrompt_CarriesTheCategoriesInTheOrderTheEndpointReturnedThem() - { - InMemoryAuditSink sink = new(); - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, - moderation: ScriptedModerationEvaluator.Flagging("violence", "harassment")).Create("conversation-1"); + // The verdict precedes the model, so the flag precedes the turn event and amends nothing. + List order = [.. events]; + Assert.True(order.IndexOf(flagged) < order.IndexOf(completed)); + Assert.Null(flagged.AmendsEventId); + Assert.Equal(0, flagged.TurnIndex); + } - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_CarriesTheCategoriesInTheOrderTheEndpointReturnedThem() + { + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, + moderation: ScriptedModerationEvaluator.Flagging("violence", "harassment")).Create("conversation-1"); - var flagged = Assert.Single(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); - Assert.Equal("violence,harassment", flagged.Payload[AuditPayloadKeys.ModerationCategories]); - } + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AFlaggedPrompt_NeverReachesTheModel() - { - var model = new SequencedChatClient("never spoken"); - var session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Flagging("hate")) - .Create("conversation-1"); + AuditEvent flagged = Assert.Single(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); + Assert.Equal("violence,harassment", flagged.Payload[AuditPayloadKeys.ModerationCategories]); + } - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_NeverReachesTheModel() + { + SequencedChatClient model = new("never spoken"); + ConversationSession session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Flagging("hate")) + .Create("conversation-1"); - // Nothing was generated, so nothing harmful was ever produced to be recorded. - Assert.Equal(0, model.Calls); - } + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AFlaggedPrompt_SpeaksTheRefusalLineAndNotTheFallback() - { - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), - moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); + // Nothing was generated, so nothing harmful was ever produced to be recorded. + Assert.Equal(0, model.Calls); + } - var result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_SpeaksTheRefusalLineAndNotTheFallback() + { + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), + moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); - Assert.Equal("I am sorry. I cannot help with that request.", result.ReplyText); - Assert.NotEqual(AgentCoreConfiguration.DefaultFallbackReply, result.ReplyText); - } + TurnResult result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AFlaggedPrompt_IsNotAFailure() - { - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), - moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); + Assert.Equal("I am sorry. I cannot help with that request.", result.ReplyText); + Assert.NotEqual(AgentCoreConfiguration.DefaultFallbackReply, result.ReplyText); + } - var result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_IsNotAFailure() + { + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), + moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); - // A refusal is not a section 8.7 failure. Nothing broke, and the model was never asked. - Assert.Null(result.Failure); - } + TurnResult result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AFlaggedPrompt_RecordsTheRefusalAsTheTextTheCallerHeard() - { - InMemoryAuditSink sink = new(); - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, - moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); + // A refusal is not a section 8.7 failure. Nothing broke, and the model was never asked. + Assert.Null(result.Failure); + } - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_RecordsTheRefusalAsTheTextTheCallerHeard() + { + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, + moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); - var completed = Assert.Single(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.TurnCompleted); - Assert.Equal( - AuditHash.OfText("I am sorry. I cannot help with that request.").Value, - completed.Payload[AuditPayloadKeys.ReplyTextSha256]); - } + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AFlaggedPrompt_RunsNoExtractor() - { - // The extractor's only input is the words moderation flagged. A slot filled from them would - // carry the flagged content into the state document and into every later prompt. - var fill = new SequencedChatClient("""{ "callerSaidGoodbye": true }"""); - var session = Build(ExtractingYaml, new SequencedChatClient("never spoken"), fill: fill, - moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); + AuditEvent completed = Assert.Single(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.TurnCompleted); + Assert.Equal( + AuditHash.OfText("I am sorry. I cannot help with that request.").Value, + completed.Payload[AuditPayloadKeys.ReplyTextSha256]); + } - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_RunsNoExtractor() + { + // The extractor's only input is the words moderation flagged. A slot filled from them would + // carry the flagged content into the state document and into every later prompt. + SequencedChatClient fill = new(/*lang=json,strict*/ """{ "callerSaidGoodbye": true }"""); + ConversationSession session = Build(ExtractingYaml, new SequencedChatClient("never spoken"), fill: fill, + moderation: ScriptedModerationEvaluator.Flagging("hate")).Create("conversation-1"); - Assert.Equal(0, fill.Calls); - } + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AFlaggedPrompt_IsLoggedOnceAndNeverCarriesTheWordsThatWereFlagged() - { - RecordingLogger logger = new(); - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), logger: logger, - moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); + Assert.Equal(0, fill.Calls); + } - await session.RunTurnAsync("the words that were flagged", TestContext.Current.CancellationToken); + [Fact] + public async Task AFlaggedPrompt_IsLoggedOnceAndNeverCarriesTheWordsThatWereFlagged() + { + RecordingLogger logger = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), logger: logger, + moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); - var entry = Assert.Single(logger.Of(6)); - Assert.Equal(LogLevel.Warning, entry.Level); - Assert.Contains("harassment", entry.Message, StringComparison.Ordinal); + _ = await session.RunTurnAsync("the words that were flagged", TestContext.Current.CancellationToken); - // The flagged words are the content. A log store holds none of the three defences of D23, - // so the categories travel and the words do not. - Assert.DoesNotContain("the words that were flagged", entry.Message, StringComparison.Ordinal); - } + LogLine entry = Assert.Single(logger.Of(6)); + Assert.Equal(LogLevel.Warning, entry.Level); + Assert.Contains("harassment", entry.Message, StringComparison.Ordinal); - [Fact] - public async Task TheEventsOfAModeratedConversation_FormAChainThatVerifies() - { - InMemoryAuditSink sink = new(); - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, - moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); + // The flagged words are the content. A log store holds none of the three defences of D23, + // so the categories travel and the words do not. + Assert.DoesNotContain("the words that were flagged", entry.Message, StringComparison.Ordinal); + } - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task TheEventsOfAModeratedConversation_FormAChainThatVerifies() + { + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, + moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); - var events = sink.EventsOf("conversation-1"); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.PromptFlagged, AuditEventKind.TurnCompleted], - events.Select(e => e.Kind).ToArray()); - Assert.All(events, AuditEventVocabulary.Validate); - } + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // A clean prompt, and the fail-open rule. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ACleanPrompt_ReachesTheModelAndWritesNoFlag() - { - InMemoryAuditSink sink = new(); - var model = new SequencedChatClient("the ordinary reply"); - var session = Build(PlainYaml, model, sink: sink, moderation: ScriptedModerationEvaluator.Clean()) - .Create("conversation-1"); + IReadOnlyList events = sink.EventsOf("conversation-1"); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.PromptFlagged, AuditEventKind.TurnCompleted], + events.Select(e => e.Kind).ToArray()); + Assert.All(events, AuditEventVocabulary.Validate); + } - var result = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + // ------------------------------------------------------------------------------------------- + // A clean prompt, and the fail-open rule. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task ACleanPrompt_ReachesTheModelAndWritesNoFlag() + { + InMemoryAuditSink sink = new(); + SequencedChatClient model = new("the ordinary reply"); + ConversationSession session = Build(PlainYaml, model, sink: sink, moderation: ScriptedModerationEvaluator.Clean()) + .Create("conversation-1"); - Assert.Equal(1, model.Calls); - Assert.Equal("the ordinary reply", result.ReplyText); + TurnResult result = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - // The vocabulary holds no reply.cleared. A turn.completed that no flag precedes is the record. - Assert.DoesNotContain(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); - } + Assert.Equal(1, model.Calls); + Assert.Equal("the ordinary reply", result.ReplyText); - [Fact] - public async Task TheModeratedText_IsWhatTheCallerSaid() - { - var endpoint = ScriptedModerationEvaluator.Clean(); - var session = Build(PlainYaml, new SequencedChatClient("hello"), moderation: endpoint).Create("conversation-1"); + // The vocabulary holds no reply.cleared. A turn.completed that no flag precedes is the record. + Assert.DoesNotContain(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); + } - await session.RunTurnAsync("how do I reset the console", TestContext.Current.CancellationToken); + [Fact] + public async Task TheModeratedText_IsWhatTheCallerSaid() + { + ScriptedModerationEvaluator endpoint = ScriptedModerationEvaluator.Clean(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("hello"), moderation: endpoint).Create("conversation-1"); - Assert.Equal(["how do I reset the console"], endpoint.Moderated); - } + _ = await session.RunTurnAsync("how do I reset the console", TestContext.Current.CancellationToken); - [Fact] - public async Task AnEndpointThatDidNotAnswer_LetsTheTurnThrough() - { - // Fail open. A vendor outage must not refuse every caller on a support line. - InMemoryAuditSink sink = new(); - var model = new SequencedChatClient("the ordinary reply"); - var session = Build(PlainYaml, model, sink: sink, moderation: ScriptedModerationEvaluator.Unanswered()) - .Create("conversation-1"); + Assert.Equal(["how do I reset the console"], endpoint.Moderated); + } - var result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AnEndpointThatDidNotAnswer_LetsTheTurnThrough() + { + // Fail open. A vendor outage must not refuse every caller on a support line. + InMemoryAuditSink sink = new(); + SequencedChatClient model = new("the ordinary reply"); + ConversationSession session = Build(PlainYaml, model, sink: sink, moderation: ScriptedModerationEvaluator.Unanswered()) + .Create("conversation-1"); - Assert.Equal(1, model.Calls); - Assert.Equal("the ordinary reply", result.ReplyText); - Assert.DoesNotContain(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); - } + TurnResult result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task AnEndpointThatThrows_LetsTheTurnThroughAndLogsOnce() - { - RecordingLogger logger = new(); - var model = new SequencedChatClient("the ordinary reply"); - var session = Build(PlainYaml, model, logger: logger, - moderation: ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))) - .Create("conversation-1"); + Assert.Equal(1, model.Calls); + Assert.Equal("the ordinary reply", result.ReplyText); + Assert.DoesNotContain(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); + } - var result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AnEndpointThatThrows_LetsTheTurnThroughAndLogsOnce() + { + RecordingLogger logger = new(); + SequencedChatClient model = new("the ordinary reply"); + ConversationSession session = Build(PlainYaml, model, logger: logger, + moderation: ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))) + .Create("conversation-1"); - Assert.Equal("the ordinary reply", result.ReplyText); - Assert.Equal(1, model.Calls); + TurnResult result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - var entry = Assert.Single(logger.Of(7)); - Assert.Equal(LogLevel.Warning, entry.Level); - } + Assert.Equal("the ordinary reply", result.ReplyText); + Assert.Equal(1, model.Calls); - [Fact] - public async Task AnEndpointThatFails_WritesNoFlagAndNeverTheWordUnknown() - { - InMemoryAuditSink sink = new(); - var session = Build(PlainYaml, new SequencedChatClient("the ordinary reply"), sink: sink, - moderation: ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))) - .Create("conversation-1"); + LogLine entry = Assert.Single(logger.Of(7)); + Assert.Equal(LogLevel.Warning, entry.Level); + } - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task AnEndpointThatFails_WritesNoFlagAndNeverTheWordUnknown() + { + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("the ordinary reply"), sink: sink, + moderation: ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))) + .Create("conversation-1"); - // A missing fact is an absent event, never an event carrying "unknown". The chain rule would - // refuse a prompt.flagged with no category anyway. - Assert.DoesNotContain(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); - } + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - [Fact] - public async Task ASessionWithNoModerator_RunsATurnAndWritesNoFlag() - { - InMemoryAuditSink sink = new(); - var model = new SequencedChatClient("the ordinary reply"); - var session = Build(PlainYaml, model, sink: sink).Create("conversation-1"); + // A missing fact is an absent event, never an event carrying "unknown". The chain rule would + // refuse a prompt.flagged with no category anyway. + Assert.DoesNotContain(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); + } - var result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task ASessionWithNoModerator_RunsATurnAndWritesNoFlag() + { + InMemoryAuditSink sink = new(); + SequencedChatClient model = new("the ordinary reply"); + ConversationSession session = Build(PlainYaml, model, sink: sink).Create("conversation-1"); - Assert.Equal("the ordinary reply", result.ReplyText); - Assert.Equal(2, sink.EventsOf("conversation-1").Count); - } + TurnResult result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // The streaming path takes the same decision. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AFlaggedPrompt_StreamsTheRefusalAndOpensNoModelStream() - { - InMemoryAuditSink sink = new(); - var model = new SequencedChatClient("never spoken"); - var session = Build(PlainYaml, model, sink: sink, - moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); + Assert.Equal("the ordinary reply", result.ReplyText); + Assert.Equal(2, sink.EventsOf("conversation-1").Count); + } - List spoken = []; - await foreach (var update in session.RunTurnStreamingAsync("...", TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // The streaming path takes the same decision. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AFlaggedPrompt_StreamsTheRefusalAndOpensNoModelStream() { - spoken.Add(update.Text); - } + InMemoryAuditSink sink = new(); + SequencedChatClient model = new("never spoken"); + ConversationSession session = Build(PlainYaml, model, sink: sink, + moderation: ScriptedModerationEvaluator.Flagging("harassment")).Create("conversation-1"); - Assert.Equal(["I am sorry. I cannot help with that request."], spoken); - Assert.Equal(0, model.Calls); - Assert.Contains(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); - } + List spoken = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("...", TestContext.Current.CancellationToken)) + { + spoken.Add(update.Text); + } - [Fact] - public async Task ACleanPromptOnTheStreamingPath_ReachesTheModel() - { - var model = new SequencedChatClient("the ordinary reply"); - var session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Clean()).Create("conversation-1"); + Assert.Equal(["I am sorry. I cannot help with that request."], spoken); + Assert.Equal(0, model.Calls); + Assert.Contains(sink.EventsOf("conversation-1"), e => e.Kind == AuditEventKind.PromptFlagged); + } - await foreach (var _ in session.RunTurnStreamingAsync("hello", TestContext.Current.CancellationToken)) + [Fact] + public async Task ACleanPromptOnTheStreamingPath_ReachesTheModel() { - // Drain it. - } + SequencedChatClient model = new("the ordinary reply"); + ConversationSession session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Clean()).Create("conversation-1"); - Assert.Equal(1, model.Calls); - } + await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("hello", TestContext.Current.CancellationToken)) + { + // Drain it. + } - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IChatClient? fill = null, - IAuditSinkPort? sink = null, - ILogger? logger = null, - ScriptedModerationEvaluator? moderation = null) - { - // There is always a sink now: ConversationObservers.Standard takes a required one, because the - // composition root resolves providers.audit for every host and falls back to the in-process - // memory kind. An optional parameter has to be a compile-time constant, so the default is - // spelled here instead — a fact that does not care where its events land gets a fresh - // in-memory sink and reads exactly as it did when it passed nothing. - IAuditSinkPort auditSink = sink ?? new InMemoryAuditSink(); - - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(reply); - if (fill is not null) - { - chatClients.Route("fill", fill); + Assert.Equal(1, model.Calls); } - // R3 puts moderation in the chat pipeline of every compiled agent, so the moderator is - // bound at compile time and not on the session factory. - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IChatClient? fill = null, + IAuditSinkPort? sink = null, + ILogger? logger = null, + ScriptedModerationEvaluator? moderation = null) + { + // There is always a sink now: ConversationObservers.Standard takes a required one, because the + // composition root resolves providers.audit for every host and falls back to the in-process + // memory kind. An optional parameter has to be a compile-time constant, so the default is + // spelled here instead — a fact that does not care where its events land gets a fresh + // in-memory sink and reads exactly as it did when it passed nothing. + IAuditSinkPort auditSink = sink ?? new InMemoryAuditSink(); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + if (fill is not null) { - Moderation = moderation is null ? null : new PromptModerator(moderation), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - timeProvider: null, - logger, - ConversationObservers.Standard(auditSink, logger)); + _ = chatClients.Route("fill", fill); + } + + // R3 puts moderation in the chat pipeline of every compiled agent, so the moderator is + // bound at compile time and not on the session factory. + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Moderation = moderation is null ? null : new PromptModerator(moderation), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + timeProvider: null, + logger, + ConversationObservers.Standard(auditSink, logger)); + } } } diff --git a/tests/AgentCore.Application.Tests/Audit/QueuedAuditSinkTests.cs b/tests/AgentCore.Application.Tests/Audit/QueuedAuditSinkTests.cs index 9508de83..8c3c6752 100644 --- a/tests/AgentCore.Application.Tests/Audit/QueuedAuditSinkTests.cs +++ b/tests/AgentCore.Application.Tests/Audit/QueuedAuditSinkTests.cs @@ -5,222 +5,231 @@ using AgentCore.Domain.Audit; using Xunit; -namespace AgentCore.Application.Tests.Audit; - -/// -/// The one queue every audit sink sits behind. -/// -/// -/// Section 7 measures a durable insert at 13 ms p50 and 32 ms p99, against 91 nanoseconds to enqueue, -/// and turns that into a rule: an append completes when the event is -/// ACCEPTED and never when it is DURABLE. Before this class the rule was a doc comment, and an -/// adapter that awaited its database broke it silently. These tests fix the rule in one place, so a -/// blocking adapter behind this queue is a correct adapter. -/// -public sealed class QueuedAuditSinkTests +namespace AgentCore.Application.Tests.Audit { - private const string ConversationId = "conversation-1"; - - /// The id Log.AuditQueueFull carries. - private const int AuditQueueFullEventId = 8; + /// + /// The one queue every audit sink sits behind. + /// + /// + /// Section 7 measures a durable insert at 13 ms p50 and 32 ms p99, against 91 nanoseconds to enqueue, + /// and turns that into a rule: an append completes when the event is + /// ACCEPTED and never when it is DURABLE. Before this class the rule was a doc comment, and an + /// adapter that awaited its database broke it silently. These tests fix the rule in one place, so a + /// blocking adapter behind this queue is a correct adapter. + /// + public sealed class QueuedAuditSinkTests + { + private const string ConversationId = "conversation-1"; - /// The id Log.AuditAppendFailed carries. It is unchanged by the queue. - private const int AuditAppendFailedEventId = 5; + /// The id Log.AuditQueueFull carries. + private const int AuditQueueFullEventId = 8; - [Fact] - public async Task AnAppend_CompletesWhileTheInnerSinkIsStillWriting() - { - BlockingAuditSink inner = new(); - await using QueuedAuditSink sink = new(inner); + /// The id Log.AuditAppendFailed carries. It is unchanged by the queue. + private const int AuditAppendFailedEventId = 5; - ValueTask append = sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); + [Fact] + public async Task AnAppend_CompletesWhileTheInnerSinkIsStillWriting() + { + BlockingAuditSink inner = new(); + await using QueuedAuditSink sink = new(inner); - // The whole point. The inner sink holds every write open, and the caller is already done: - // 91 nanoseconds to enqueue, and the 13 ms belongs to a thread the turn never sees. - Assert.True(append.IsCompleted); - await append; + ValueTask append = sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); - inner.Release(); - } + // The whole point. The inner sink holds every write open, and the caller is already done: + // 91 nanoseconds to enqueue, and the 13 ms belongs to a thread the turn never sees. + Assert.True(append.IsCompleted); + await append; - [Fact] - public async Task EveryEvent_ReachesTheInnerSink_InTheOrderItWasAppended() - { - InMemoryAuditSink inner = new(); - await using QueuedAuditSink sink = new(inner); + inner.Release(); + } - List ids = []; - for (long sequence = 1; sequence <= 5; sequence++) + [Fact] + public async Task EveryEvent_ReachesTheInnerSink_InTheOrderItWasAppended() { - var id = Guid.CreateVersion7(); - ids.Add(id); - await sink.AppendAsync(Event(sequence, id), TestContext.Current.CancellationToken); + InMemoryAuditSink inner = new(); + await using QueuedAuditSink sink = new(inner); + + List ids = []; + for (long sequence = 1; sequence <= 5; sequence++) + { + Guid id = Guid.CreateVersion7(); + ids.Add(id); + await sink.AppendAsync(Event(sequence, id), TestContext.Current.CancellationToken); + } + + await sink.FlushAsync(TestContext.Current.CancellationToken); + + // One reader drains the channel, so the chain of D23 reaches the store in the order the conversation + // produced it. That ordering is now a property of this class and not of each adapter. + Assert.Equal(ids, inner.Events.Select(item => item.EventId).ToArray()); } - await sink.FlushAsync(TestContext.Current.CancellationToken); + [Fact] + public async Task EventsThatPileUpWhileTheSinkIsBusy_ArriveAsOneBatch() + { + GatedBatchAuditSink inner = new(); + await using QueuedAuditSink sink = new(inner); - // One reader drains the channel, so the chain of D23 reaches the store in the order the conversation - // produced it. That ordering is now a property of this class and not of each adapter. - Assert.Equal(ids, inner.Events.Select(item => item.EventId).ToArray()); - } + await sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); - [Fact] - public async Task EventsThatPileUpWhileTheSinkIsBusy_ArriveAsOneBatch() - { - GatedBatchAuditSink inner = new(); - await using QueuedAuditSink sink = new(inner); + // The writer is now inside the inner sink and reads nothing more, so what follows queues. + await inner.Entered; - await sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); + for (long sequence = 2; sequence <= 21; sequence++) + { + await sink.AppendAsync(Event(sequence), TestContext.Current.CancellationToken); + } - // The writer is now inside the inner sink and reads nothing more, so what follows queues. - await inner.Entered; + inner.Release(); + await sink.FlushAsync(TestContext.Current.CancellationToken); - for (long sequence = 2; sequence <= 21; sequence++) - { - await sink.AppendAsync(Event(sequence), TestContext.Current.CancellationToken); + // PostgreSQL wants rows in batches, and one round trip for twenty rows is the reason this + // queue exists at all. The first batch is the one event that was there when the writer woke. + Assert.Equal([1, 20], inner.BatchSizes); } - inner.Release(); - await sink.FlushAsync(TestContext.Current.CancellationToken); + [Fact] + public async Task AFullQueue_DropsAndReports_AndTheCallerNeverWaits() + { + RecordingLogger logger = new(); + GatedBatchAuditSink inner = new(); + await using QueuedAuditSink sink = new(inner, logger, capacity: 4); - // PostgreSQL wants rows in batches, and one round trip for twenty rows is the reason this - // queue exists at all. The first batch is the one event that was there when the writer woke. - Assert.Equal([1, 20], inner.BatchSizes); - } + await sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); - [Fact] - public async Task AFullQueue_DropsAndReports_AndTheCallerNeverWaits() - { - RecordingLogger logger = new(); - GatedBatchAuditSink inner = new(); - await using QueuedAuditSink sink = new(inner, logger, capacity: 4); + // The writer holds the first batch open, so nothing is read while the next seven arrive: four + // fit the queue and three have nowhere to go. + await inner.Entered; - await sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); + for (long sequence = 2; sequence <= 8; sequence++) + { + ValueTask append = sink.AppendAsync(Event(sequence), TestContext.Current.CancellationToken); - // The writer holds the first batch open, so nothing is read while the next seven arrive: four - // fit the queue and three have nowhere to go. - await inner.Entered; + // A sink that cannot keep up drops and reports rather than slowing the caller down, so + // even the appends that are refused cost the turn nothing and throw nothing. + Assert.True(append.IsCompleted); + await append; + } - for (long sequence = 2; sequence <= 8; sequence++) - { - ValueTask append = sink.AppendAsync(Event(sequence), TestContext.Current.CancellationToken); + Assert.Equal(3, logger.Of(AuditQueueFullEventId).Count); - // A sink that cannot keep up drops and reports rather than slowing the caller down, so - // even the appends that are refused cost the turn nothing and throw nothing. - Assert.True(append.IsCompleted); - await append; + inner.Release(); } - Assert.Equal(3, logger.Of(AuditQueueFullEventId).Count); + [Fact] + public async Task AnInnerSinkThatRefuses_IsReportedAndTheQueueKeepsRunning() + { + RecordingLogger logger = new(); + ThrowingAuditSink inner = new(); + QueuedAuditSink sink = new(inner, logger); - inner.Release(); - } + await sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); + await sink.DisposeAsync(); - [Fact] - public async Task AnInnerSinkThatRefuses_IsReportedAndTheQueueKeepsRunning() - { - RecordingLogger logger = new(); - ThrowingAuditSink inner = new(); - QueuedAuditSink sink = new(inner, logger); + // Audit is a record of the conversation and never a part of it. The store refused, the line says so, + // and nothing was thrown at anyone. + LogLine line = Assert.Single(logger.Of(AuditAppendFailedEventId)); + Assert.Equal(ThrowingAuditSink.Message, line.Exception?.Message); + } - await sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); - await sink.DisposeAsync(); + [Fact] + public async Task Disposal_WritesWhatIsStillQueued() + { + InMemoryAuditSink inner = new(); + QueuedAuditSink sink = new(inner); - // Audit is a record of the conversation and never a part of it. The store refused, the line says so, - // and nothing was thrown at anyone. - LogLine line = Assert.Single(logger.Of(AuditAppendFailedEventId)); - Assert.Equal(ThrowingAuditSink.Message, line.Exception?.Message); - } + Guid id = Guid.CreateVersion7(); + await sink.AppendAsync(Event(1, id), TestContext.Current.CancellationToken); + await sink.DisposeAsync(); - [Fact] - public async Task Disposal_WritesWhatIsStillQueued() - { - InMemoryAuditSink inner = new(); - QueuedAuditSink sink = new(inner); + // A host that stops does not lose the rows it already accepted, which is what makes a queue + // in front of the chain safe to put there. + Assert.Equal(id, Assert.Single(inner.Events).EventId); + } - var id = Guid.CreateVersion7(); - await sink.AppendAsync(Event(1, id), TestContext.Current.CancellationToken); - await sink.DisposeAsync(); + [Fact] + public async Task AnAppendAfterDisposal_IsDroppedAndNeverThrows() + { + RecordingLogger logger = new(); + InMemoryAuditSink inner = new(); + QueuedAuditSink sink = new(inner, logger); - // A host that stops does not lose the rows it already accepted, which is what makes a queue - // in front of the chain safe to put there. - Assert.Equal(id, Assert.Single(inner.Events).EventId); - } + await sink.DisposeAsync(); + ValueTask append = sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); - [Fact] - public async Task AnAppendAfterDisposal_IsDroppedAndNeverThrows() - { - RecordingLogger logger = new(); - InMemoryAuditSink inner = new(); - QueuedAuditSink sink = new(inner, logger); - - await sink.DisposeAsync(); - ValueTask append = sink.AppendAsync(Event(1), TestContext.Current.CancellationToken); - - // Shutdown order is the host's, not this library's, so a late event is reported and dropped - // rather than thrown back into whatever is still finishing. - Assert.True(append.IsCompleted); - await append; - Assert.Single(logger.Of(AuditQueueFullEventId)); - Assert.Empty(inner.Events); - } + // Shutdown order is the host's, not this library's, so a late event is reported and dropped + // rather than thrown back into whatever is still finishing. + Assert.True(append.IsCompleted); + await append; + _ = Assert.Single(logger.Of(AuditQueueFullEventId)); + Assert.Empty(inner.Events); + } - private static AuditEvent Event(long sequence, Guid? eventId = null) => new() - { - ConversationId = ConversationId, - EventId = eventId ?? Guid.CreateVersion7(), - Kind = AuditEventKind.TurnCompleted, - OccurredAt = DateTimeOffset.UnixEpoch.AddSeconds(sequence), - }; + private static AuditEvent Event(long sequence, Guid? eventId = null) + { + return new() + { + ConversationId = ConversationId, + EventId = eventId ?? Guid.CreateVersion7(), + Kind = AuditEventKind.TurnCompleted, + OccurredAt = DateTimeOffset.UnixEpoch.AddSeconds(sequence), + }; + } - /// - /// A batch-taking sink that holds its first batch open until a test releases it. - /// - /// - /// It records the size of each batch, which is the only way to tell a queue that batches from one - /// that hands the store a row at a time. - /// - private sealed class GatedBatchAuditSink : IAuditSinkPort - { - private readonly TaskCompletionSource _entered = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly Lock _gate = new(); - private readonly List _batches = []; + /// + /// A batch-taking sink that holds its first batch open until a test releases it. + /// + /// + /// It records the size of each batch, which is the only way to tell a queue that batches from one + /// that hands the store a row at a time. + /// + private sealed class GatedBatchAuditSink : IAuditSinkPort + { + private readonly TaskCompletionSource _entered = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly Lock _gate = new(); + private readonly List _batches = []; - /// Completes once the sink is inside its first batch. - public Task Entered => _entered.Task; + /// Completes once the sink is inside its first batch. + public Task Entered => _entered.Task; - /// Gets the size of each batch this sink took, oldest first. - public IReadOnlyList BatchSizes - { - get + /// Gets the size of each batch this sink took, oldest first. + public IReadOnlyList BatchSizes { - lock (_gate) + get { - return [.. _batches]; + lock (_gate) + { + return [.. _batches]; + } } } - } - - /// Lets the held batch complete, and every batch after it. - public void Release() => _release.TrySetResult(); - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - => AppendManyAsync([auditEvent], cancellationToken); - - public async ValueTask AppendManyAsync( - IReadOnlyList auditEvents, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(auditEvents); + /// Lets the held batch complete, and every batch after it. + public void Release() + { + _ = _release.TrySetResult(); + } - lock (_gate) + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { - _batches.Add(auditEvents.Count); + return AppendManyAsync([auditEvent], cancellationToken); } - _entered.TrySetResult(); - await _release.Task.ConfigureAwait(false); + public async ValueTask AppendManyAsync( + IReadOnlyList auditEvents, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(auditEvents); + + lock (_gate) + { + _batches.Add(auditEvents.Count); + } + + _ = _entered.TrySetResult(); + await _release.Task.ConfigureAwait(false); + } } } } diff --git a/tests/AgentCore.Application.Tests/Blobs/BlobLinkTests.cs b/tests/AgentCore.Application.Tests/Blobs/BlobLinkTests.cs index d1740c04..80904407 100644 --- a/tests/AgentCore.Application.Tests/Blobs/BlobLinkTests.cs +++ b/tests/AgentCore.Application.Tests/Blobs/BlobLinkTests.cs @@ -1,41 +1,42 @@ using AgentCore.Application.Blobs; using Xunit; -namespace AgentCore.Application.Tests.Blobs; - -/// The disposition a link serves a blob with. RFC 6266 spells the header; the spec picks inline vs attachment. -public sealed class BlobLinkTests +namespace AgentCore.Application.Tests.Blobs { - [Theory] - [InlineData("image/png", "chart.png", "inline; filename*=UTF-8''chart.png")] - [InlineData("application/pdf", "report.pdf", "inline; filename*=UTF-8''report.pdf")] - [InlineData("text/csv", "rows.csv", "attachment; filename*=UTF-8''rows.csv")] - [InlineData("image/svg+xml", "logo.svg", "attachment; filename*=UTF-8''logo.svg")] - [InlineData("text/html", "page.html", "attachment; filename*=UTF-8''page.html")] - [InlineData("application/octet-stream", "blob.bin", "attachment; filename*=UTF-8''blob.bin")] - public void DispositionOf_KnownMediaTypes_MatchesTheSpec(string mediaType, string name, string expected) + /// The disposition a link serves a blob with. RFC 6266 spells the header; the spec picks inline vs attachment. + public sealed class BlobLinkTests { - // Act - var header = BlobLink.DispositionOf(mediaType, name); + [Theory] + [InlineData("image/png", "chart.png", "inline; filename*=UTF-8''chart.png")] + [InlineData("application/pdf", "report.pdf", "inline; filename*=UTF-8''report.pdf")] + [InlineData("text/csv", "rows.csv", "attachment; filename*=UTF-8''rows.csv")] + [InlineData("image/svg+xml", "logo.svg", "attachment; filename*=UTF-8''logo.svg")] + [InlineData("text/html", "page.html", "attachment; filename*=UTF-8''page.html")] + [InlineData("application/octet-stream", "blob.bin", "attachment; filename*=UTF-8''blob.bin")] + public void DispositionOf_KnownMediaTypes_MatchesTheSpec(string mediaType, string name, string expected) + { + // Act + string header = BlobLink.DispositionOf(mediaType, name); - // Assert - Assert.Equal(expected, header); - } + // Assert + Assert.Equal(expected, header); + } - [Fact] - public void DispositionOf_NameWithSpaceAndUnicode_PercentEncodesPerRfc5987() - { - // Act - var header = BlobLink.DispositionOf("image/png", "my chart é.png"); + [Fact] + public void DispositionOf_NameWithSpaceAndUnicode_PercentEncodesPerRfc5987() + { + // Act + string header = BlobLink.DispositionOf("image/png", "my chart é.png"); - // Assert - Assert.Equal("inline; filename*=UTF-8''my%20chart%20%C3%A9.png", header); - } + // Assert + Assert.Equal("inline; filename*=UTF-8''my%20chart%20%C3%A9.png", header); + } - [Fact] - public void Lifetime_IsFifteenMinutes() - { - // Assert: decision 10 of the sandbox file capture spec. - Assert.Equal(TimeSpan.FromMinutes(15), BlobLink.Lifetime); + [Fact] + public void Lifetime_IsFifteenMinutes() + { + // Assert: decision 10 of the sandbox file capture spec. + Assert.Equal(TimeSpan.FromMinutes(15), BlobLink.Lifetime); + } } } diff --git a/tests/AgentCore.Application.Tests/Blobs/BlobNameTests.cs b/tests/AgentCore.Application.Tests/Blobs/BlobNameTests.cs index 850940cd..a449f33b 100644 --- a/tests/AgentCore.Application.Tests/Blobs/BlobNameTests.cs +++ b/tests/AgentCore.Application.Tests/Blobs/BlobNameTests.cs @@ -1,64 +1,65 @@ using AgentCore.Application.Blobs; using Xunit; -namespace AgentCore.Application.Tests.Blobs; - -/// The name a blob is keyed by. A key, never a path. -public sealed class BlobNameTests +namespace AgentCore.Application.Tests.Blobs { - [Theory] - [InlineData("chart.png")] - [InlineData("sales report.pdf")] - [InlineData("q3-données.csv")] - public void IsSafe_PlainName_Accepts(string name) + /// The name a blob is keyed by. A key, never a path. + public sealed class BlobNameTests { - Assert.True(BlobName.IsSafe(name)); - } + [Theory] + [InlineData("chart.png")] + [InlineData("sales report.pdf")] + [InlineData("q3-données.csv")] + public void IsSafe_PlainName_Accepts(string name) + { + Assert.True(BlobName.IsSafe(name)); + } - [Theory] - [InlineData(null)] - [InlineData("")] - [InlineData(" ")] - [InlineData("../etc/passwd")] - [InlineData("..")] - [InlineData("a/b.png")] - [InlineData("a\\b.png")] - [InlineData("/chart.png")] - [InlineData("chart\0.png")] - [InlineData("chart\n.png")] - [InlineData("chart..png")] - public void IsSafe_PathOrControlChars_Refuses(string? name) - { - Assert.False(BlobName.IsSafe(name)); - } + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + [InlineData("../etc/passwd")] + [InlineData("..")] + [InlineData("a/b.png")] + [InlineData("a\\b.png")] + [InlineData("/chart.png")] + [InlineData("chart\0.png")] + [InlineData("chart\n.png")] + [InlineData("chart..png")] + public void IsSafe_PathOrControlChars_Refuses(string? name) + { + Assert.False(BlobName.IsSafe(name)); + } - [Fact] - public void IsSafe_Over255Utf8Bytes_Refuses() - { - // Arrange: 252 ASCII bytes + ".png" = 256 bytes. - var name = new string('a', 252) + ".png"; + [Fact] + public void IsSafe_Over255Utf8Bytes_Refuses() + { + // Arrange: 252 ASCII bytes + ".png" = 256 bytes. + string name = new string('a', 252) + ".png"; - // Act & Assert - Assert.False(BlobName.IsSafe(name)); - } + // Act & Assert + Assert.False(BlobName.IsSafe(name)); + } - [Fact] - public void IsSafe_Exactly255Utf8Bytes_Accepts() - { - // Arrange - var name = new string('a', 251) + ".png"; + [Fact] + public void IsSafe_Exactly255Utf8Bytes_Accepts() + { + // Arrange + string name = new string('a', 251) + ".png"; - // Act & Assert - Assert.True(BlobName.IsSafe(name)); - } + // Act & Assert + Assert.True(BlobName.IsSafe(name)); + } - [Fact] - public void IsSafe_MultiByteCharsCountAsBytesNotChars() - { - // Arrange: "é" is 2 UTF-8 bytes, so 126 of them + ".png" = 256 bytes in 130 chars. - var name = new string('é', 126) + ".png"; + [Fact] + public void IsSafe_MultiByteCharsCountAsBytesNotChars() + { + // Arrange: "é" is 2 UTF-8 bytes, so 126 of them + ".png" = 256 bytes in 130 chars. + string name = new string('é', 126) + ".png"; - // Act & Assert - Assert.False(BlobName.IsSafe(name)); + // Act & Assert + Assert.False(BlobName.IsSafe(name)); + } } } diff --git a/tests/AgentCore.Application.Tests/Blobs/BlobPolicyTests.cs b/tests/AgentCore.Application.Tests/Blobs/BlobPolicyTests.cs index f77528b5..e4f86df9 100644 --- a/tests/AgentCore.Application.Tests/Blobs/BlobPolicyTests.cs +++ b/tests/AgentCore.Application.Tests/Blobs/BlobPolicyTests.cs @@ -1,109 +1,108 @@ using AgentCore.Application.Blobs; using Xunit; -namespace AgentCore.Application.Tests.Blobs; - -/// The cap and the allowlist a captured file must pass. -public sealed class BlobPolicyTests +namespace AgentCore.Application.Tests.Blobs { - [Theory] - [InlineData("chart.png", 15_769)] - [InlineData("report.PDF", 1)] - [InlineData("rows.csv", 0)] - [InlineData("rows.tsv", 0)] - [InlineData("big.png", 10L * 1024 * 1024)] - [InlineData("report.md", 518)] - [InlineData("units.xlsx", 4_096)] - [InlineData("bundle.zip", 4_096)] - public void WhyRefused_AllowedExtensionUnderCap_ReturnsNull(string name, long length) - { - // Act - var reason = BlobPolicy.Default.WhyRefused(name, length); - - // Assert - Assert.Null(reason); - } - - [Fact] - public void WhyRefused_OneByteOverCap_NamesTheSize() - { - // Act - var reason = BlobPolicy.Default.WhyRefused("chart.png", 10L * 1024 * 1024 + 1); - - // Assert - Assert.NotNull(reason); - Assert.Contains("10485760", reason, StringComparison.Ordinal); - } - - [Theory] - [InlineData("page.html")] - [InlineData("logo.svg")] - [InlineData("feed.xml")] - [InlineData("run.exe")] - [InlineData("chart.png.js")] - public void WhyRefused_ExtensionOffTheList_NamesTheExtension(string name) - { - // Act - var reason = BlobPolicy.Default.WhyRefused(name, 10); - - // Assert - Assert.NotNull(reason); - Assert.Contains("not allowed", reason, StringComparison.Ordinal); - } - - [Theory] - [InlineData("README")] - [InlineData("chart.")] - public void WhyRefused_NoExtension_Refuses(string name) - { - // Act - var reason = BlobPolicy.Default.WhyRefused(name, 10); - - // Assert - Assert.Equal("no extension", reason); - } - - [Fact] - public void WhyRefused_NegativeLength_Refuses() - { - // Act - var reason = BlobPolicy.Default.WhyRefused("chart.png", -1); - - // Assert - Assert.NotNull(reason); - } - - [Fact] - public void Constructor_CustomList_MatchesWithoutRegardToCase() + /// The cap and the allowlist a captured file must pass. + public sealed class BlobPolicyTests { - // Arrange - var policy = new BlobPolicy(100, ["JPG"]); - - // Act - var accepted = policy.WhyRefused("photo.jpg", 50); - var refused = policy.WhyRefused("chart.png", 50); - - // Assert - Assert.Null(accepted); - Assert.NotNull(refused); - } - - [Fact] - public void Constructor_ZeroCap_Throws() - { - // Act & Assert - Assert.Throws(() => new BlobPolicy(0, ["png"])); - } - - [Fact] - public void DefaultExtensions_EachHasAMediaType() - { - // Act - var untyped = BlobPolicy.DefaultExtensions - .Where(extension => BlobMediaTypes.Of("file." + extension) == BlobMediaTypes.Fallback) - .ToList(); - - // Assert - Assert.Empty(untyped); + [Theory] + [InlineData("chart.png", 15_769)] + [InlineData("report.PDF", 1)] + [InlineData("rows.csv", 0)] + [InlineData("rows.tsv", 0)] + [InlineData("big.png", 10L * 1024 * 1024)] + [InlineData("report.md", 518)] + [InlineData("units.xlsx", 4_096)] + [InlineData("bundle.zip", 4_096)] + public void WhyRefused_AllowedExtensionUnderCap_ReturnsNull(string name, long length) + { + // Act + string? reason = BlobPolicy.Default.WhyRefused(name, length); + + // Assert + Assert.Null(reason); + } + + [Fact] + public void WhyRefused_OneByteOverCap_NamesTheSize() + { + // Act + string? reason = BlobPolicy.Default.WhyRefused("chart.png", (10L * 1024 * 1024) + 1); + + // Assert + Assert.NotNull(reason); + Assert.Contains("10485760", reason, StringComparison.Ordinal); + } + + [Theory] + [InlineData("page.html")] + [InlineData("logo.svg")] + [InlineData("feed.xml")] + [InlineData("run.exe")] + [InlineData("chart.png.js")] + public void WhyRefused_ExtensionOffTheList_NamesTheExtension(string name) + { + // Act + string? reason = BlobPolicy.Default.WhyRefused(name, 10); + + // Assert + Assert.NotNull(reason); + Assert.Contains("not allowed", reason, StringComparison.Ordinal); + } + + [Theory] + [InlineData("README")] + [InlineData("chart.")] + public void WhyRefused_NoExtension_Refuses(string name) + { + // Act + string? reason = BlobPolicy.Default.WhyRefused(name, 10); + + // Assert + Assert.Equal("no extension", reason); + } + + [Fact] + public void WhyRefused_NegativeLength_Refuses() + { + // Act + string? reason = BlobPolicy.Default.WhyRefused("chart.png", -1); + + // Assert + Assert.NotNull(reason); + } + + [Fact] + public void Constructor_CustomList_MatchesWithoutRegardToCase() + { + // Arrange + BlobPolicy policy = new(100, ["JPG"]); + + // Act + string? accepted = policy.WhyRefused("photo.jpg", 50); + string? refused = policy.WhyRefused("chart.png", 50); + + // Assert + Assert.Null(accepted); + Assert.NotNull(refused); + } + + [Fact] + public void Constructor_ZeroCap_Throws() + { + // Act & Assert + _ = Assert.Throws(() => new BlobPolicy(0, ["png"])); + } + + [Fact] + public void DefaultExtensions_EachHasAMediaType() + { + // Act + List untyped = [.. BlobPolicy.DefaultExtensions.Where(extension => BlobMediaTypes.Of("file." + extension) == BlobMediaTypes.Fallback)]; + + // Assert + Assert.Empty(untyped); + } } } diff --git a/tests/AgentCore.Application.Tests/Blobs/BlobStoreFactoryTests.cs b/tests/AgentCore.Application.Tests/Blobs/BlobStoreFactoryTests.cs index 48d95719..7570efea 100644 --- a/tests/AgentCore.Application.Tests/Blobs/BlobStoreFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Blobs/BlobStoreFactoryTests.cs @@ -4,126 +4,139 @@ using AgentCore.Application.Ports; using Xunit; -namespace AgentCore.Application.Tests.Blobs; - -/// -/// The blob vendor seam: providers.blobs, and what a document that names none gets. -/// -/// -/// Unlike the conversation store, there is no built-in kind. A document that names none gets -/// , and that null is what switches the capture provider off. -/// -public sealed class BlobStoreFactoryTests +namespace AgentCore.Application.Tests.Blobs { - [Fact] - public async Task OpenAsync_NoBlobsBlock_GetsNullAndAsksNoAdapter() + /// + /// The blob vendor seam: providers.blobs, and what a document that names none gets. + /// + /// + /// Unlike the conversation store, there is no built-in kind. A document that names none gets + /// , and that null is what switches the capture provider off. + /// + public sealed class BlobStoreFactoryTests { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document()); - FakeBlobStoreAdapter adapter = new("s3"); - - // Act - var store = await BlobStoreFactory.OpenAsync( - configuration, secrets: null, [adapter], TestContext.Current.CancellationToken); - - // Assert - Assert.Null(store); - Assert.Equal(0, adapter.Opens); - } - - [Fact] - public async Task OpenAsync_TheKind_PicksOneAdapterAndHandsItTheWholeBlock() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml( - Document("kind: fake", "endpoint: https://s3.us-east-005.backblazeb2.com", "bucket: spirit", "region: us-east-005")); - FakeBlobStoreAdapter fake = new("fake"); - FakeBlobStoreAdapter other = new("s3"); - - // Act - var store = await BlobStoreFactory.OpenAsync( - configuration, secrets: null, [other, fake], TestContext.Current.CancellationToken); - - // Assert - Assert.Same(fake.Store, store); - Assert.Equal(0, other.Opens); - Assert.NotNull(fake.Entry); - Assert.Equal("https://s3.us-east-005.backblazeb2.com", fake.Entry.Endpoint); - Assert.Equal("spirit", fake.Entry.Bucket); - Assert.Equal("us-east-005", fake.Entry.Region); - } - - [Fact] - public async Task OpenAsync_AKindNoAdapterServes_FailsTheStartAndPointsAtTheKind() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document("kind: s3")); - FakeBlobStoreAdapter adapter = new("fake"); - - // Act - var failure = await Assert.ThrowsAsync( - async () => await BlobStoreFactory.OpenAsync( - configuration, secrets: null, [adapter], TestContext.Current.CancellationToken)); - - // Assert - Assert.Contains("s3", failure.Message, StringComparison.Ordinal); - Assert.Equal("/providers/blobs/kind", failure.Errors[0].Pointer); - } + [Fact] + public async Task OpenAsync_NoBlobsBlock_GetsNullAndAsksNoAdapter() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document()); + FakeBlobStoreAdapter adapter = new("s3"); - [Fact] - public void LoadYaml_AnUnknownKeyUnderBlobs_IsRejectedBySchema() - { - // Act & Assert - Assert.Throws( - () => ConfigurationLoader.LoadYaml(Document("kind: s3", "path: /tmp"))); - } + // Act + IBlobStore? store = await BlobStoreFactory.OpenAsync( + configuration, secrets: null, [adapter], TestContext.Current.CancellationToken); - /// Builds the section 8.1 document with its blobs block replaced by these entries, or taken out. - private static string Document(params string[] entries) - => Configuration.ExampleDocument.Yaml.Replace( - Configuration.ExampleDocument.BlobsLine, - entries.Length == 0 - ? string.Empty - : " blobs:\n" + string.Join("\n", entries.Select(entry => " " + entry)), - StringComparison.Ordinal); - - /// An adapter that opens nothing and records what it was handed. - private sealed class FakeBlobStoreAdapter(string kind) : IBlobStoreAdapter - { - public string Kind => kind; + // Assert + Assert.Null(store); + Assert.Equal(0, adapter.Opens); + } - public int Opens { get; private set; } + [Fact] + public async Task OpenAsync_TheKind_PicksOneAdapterAndHandsItTheWholeBlock() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml( + Document("kind: fake", "endpoint: https://s3.us-east-005.backblazeb2.com", "bucket: spirit", "region: us-east-005")); + FakeBlobStoreAdapter fake = new("fake"); + FakeBlobStoreAdapter other = new("s3"); + + // Act + IBlobStore? store = await BlobStoreFactory.OpenAsync( + configuration, secrets: null, [other, fake], TestContext.Current.CancellationToken); + + // Assert + Assert.Same(fake.Store, store); + Assert.Equal(0, other.Opens); + Assert.NotNull(fake.Entry); + Assert.Equal("https://s3.us-east-005.backblazeb2.com", fake.Entry.Endpoint); + Assert.Equal("spirit", fake.Entry.Bucket); + Assert.Equal("us-east-005", fake.Entry.Region); + } - public BlobProviderConfiguration? Entry { get; private set; } + [Fact] + public async Task OpenAsync_AKindNoAdapterServes_FailsTheStartAndPointsAtTheKind() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: s3")); + FakeBlobStoreAdapter adapter = new("fake"); + + // Act + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await BlobStoreFactory.OpenAsync( + configuration, secrets: null, [adapter], TestContext.Current.CancellationToken)); + + // Assert + Assert.Contains("s3", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/blobs/kind", failure.Errors[0].Pointer); + } - public IBlobStore Store { get; } = new FakeBlobStore(); + [Fact] + public void LoadYaml_AnUnknownKeyUnderBlobs_IsRejectedBySchema() + { + // Act & Assert + _ = Assert.Throws( + () => ConfigurationLoader.LoadYaml(Document("kind: s3", "path: /tmp"))); + } - public ValueTask OpenAsync( - BlobProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) + /// Builds the section 8.1 document with its blobs block replaced by these entries, or taken out. + private static string Document(params string[] entries) { - Opens++; - Entry = entry; - return ValueTask.FromResult(Store); + return Configuration.ExampleDocument.Yaml.Replace( + Configuration.ExampleDocument.BlobsLine, + entries.Length == 0 + ? string.Empty + : " blobs:\n" + string.Join("\n", entries.Select(entry => " " + entry)), + StringComparison.Ordinal); } - } - private sealed class FakeBlobStore : IBlobStore - { - public ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + /// An adapter that opens nothing and records what it was handed. + private sealed class FakeBlobStoreAdapter(string kind) : IBlobStoreAdapter + { + public string Kind => kind; + + public int Opens { get; private set; } - public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public BlobProviderConfiguration? Entry { get; private set; } - public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public IBlobStore Store { get; } = new FakeBlobStore(); - public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public ValueTask OpenAsync( + BlobProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + Opens++; + Entry = entry; + return ValueTask.FromResult(Store); + } + } - public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + private sealed class FakeBlobStore : IBlobStore + { + public ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/AgentHarnessTests.cs b/tests/AgentCore.Application.Tests/Configuration/AgentHarnessTests.cs index adb118a8..80385eb3 100644 --- a/tests/AgentCore.Application.Tests/Configuration/AgentHarnessTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/AgentHarnessTests.cs @@ -2,85 +2,88 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// : the key-by-key merge of one agent's todos: / mode: / -/// clock: / baseInstructions: switches against agents.defaults. -/// -public sealed class AgentHarnessTests +namespace AgentCore.Application.Tests.Configuration { - [Fact] - public void Compose_NoKeyAnywhere_BothFalse() - { - var resolved = AgentHarness.Compose(defaults: null, Agent(todos: null, mode: null)); - - Assert.False(resolved.Todos); - Assert.False(resolved.Mode); - } - - [Fact] - public void Compose_NoKeyAnywhere_ClockAndBaseAreOn() - { - var resolved = AgentHarness.Compose(defaults: null, Agent(todos: null, mode: null)); - - Assert.True(resolved.Clock); - Assert.True(resolved.BaseInstructions); - } - - [Fact] - public void Compose_DefaultsFalse_TurnsClockAndBaseOff() + /// + /// : the key-by-key merge of one agent's todos: / mode: / + /// clock: / baseInstructions: switches against agents.defaults. + /// + public sealed class AgentHarnessTests { - var resolved = AgentHarness.Compose( - new AgentDefaults { Clock = false, BaseInstructions = false }, - Agent(todos: null, mode: null)); - - Assert.False(resolved.Clock); - Assert.False(resolved.BaseInstructions); - } - - [Fact] - public void Compose_AgentTrueOverDefaultsFalse_TakesTheAgent() - { - var resolved = AgentHarness.Compose( - new AgentDefaults { Clock = false, BaseInstructions = false }, - Agent(todos: null, mode: null) with { Clock = true, BaseInstructions = true }); - - Assert.True(resolved.Clock); - Assert.True(resolved.BaseInstructions); + [Fact] + public void Compose_NoKeyAnywhere_BothFalse() + { + ResolvedHarness resolved = AgentHarness.Compose(defaults: null, Agent(todos: null, mode: null)); + + Assert.False(resolved.Todos); + Assert.False(resolved.Mode); + } + + [Fact] + public void Compose_NoKeyAnywhere_ClockAndBaseAreOn() + { + ResolvedHarness resolved = AgentHarness.Compose(defaults: null, Agent(todos: null, mode: null)); + + Assert.True(resolved.Clock); + Assert.True(resolved.BaseInstructions); + } + + [Fact] + public void Compose_DefaultsFalse_TurnsClockAndBaseOff() + { + ResolvedHarness resolved = AgentHarness.Compose( + new AgentDefaults { Clock = false, BaseInstructions = false }, + Agent(todos: null, mode: null)); + + Assert.False(resolved.Clock); + Assert.False(resolved.BaseInstructions); + } + + [Fact] + public void Compose_AgentTrueOverDefaultsFalse_TakesTheAgent() + { + ResolvedHarness resolved = AgentHarness.Compose( + new AgentDefaults { Clock = false, BaseInstructions = false }, + Agent(todos: null, mode: null) with { Clock = true, BaseInstructions = true }); + + Assert.True(resolved.Clock); + Assert.True(resolved.BaseInstructions); + } + + [Fact] + public void Compose_DefaultsOnly_IsInherited() + { + ResolvedHarness resolved = AgentHarness.Compose( + new AgentDefaults { Todos = true, Mode = true }, + Agent(todos: null, mode: null)); + + Assert.True(resolved.Todos); + Assert.True(resolved.Mode); + } + + [Fact] + public void Compose_AgentFalseOverridesDefaultsTrue_TakesTheAgent() + { + ResolvedHarness resolved = AgentHarness.Compose( + new AgentDefaults { Todos = true, Mode = true }, + Agent(todos: false, mode: false)); + + Assert.False(resolved.Todos); + Assert.False(resolved.Mode); + } + + [Fact] + public void Compose_AgentTrueOverNullDefaults_IsTrue() + { + ResolvedHarness resolved = AgentHarness.Compose(defaults: null, Agent(todos: true, mode: true)); + + Assert.True(resolved.Todos); + Assert.True(resolved.Mode); + } + + private static AgentConfiguration Agent(bool? todos, bool? mode) + { + return new() { Id = "reply", Todos = todos, Mode = mode }; + } } - - [Fact] - public void Compose_DefaultsOnly_IsInherited() - { - var resolved = AgentHarness.Compose( - new AgentDefaults { Todos = true, Mode = true }, - Agent(todos: null, mode: null)); - - Assert.True(resolved.Todos); - Assert.True(resolved.Mode); - } - - [Fact] - public void Compose_AgentFalseOverridesDefaultsTrue_TakesTheAgent() - { - var resolved = AgentHarness.Compose( - new AgentDefaults { Todos = true, Mode = true }, - Agent(todos: false, mode: false)); - - Assert.False(resolved.Todos); - Assert.False(resolved.Mode); - } - - [Fact] - public void Compose_AgentTrueOverNullDefaults_IsTrue() - { - var resolved = AgentHarness.Compose(defaults: null, Agent(todos: true, mode: true)); - - Assert.True(resolved.Todos); - Assert.True(resolved.Mode); - } - - private static AgentConfiguration Agent(bool? todos, bool? mode) => - new() { Id = "reply", Todos = todos, Mode = mode }; } diff --git a/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs b/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs index f9ff3c3e..37662137 100644 --- a/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs @@ -3,209 +3,218 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// : the key-by-key merge of one agent's knowledge: block against -/// agents.defaults.knowledge, and the two boolean questions it answers over a whole document. -/// -public sealed class AgentKnowledgeTests +namespace AgentCore.Application.Tests.Configuration { - [Fact] - public void Compose_NoBlockAnywhere_IsNull() - { - // An agent with nothing to do with the knowledge base gets no provider at all, - // and therefore pays nothing. - Assert.Null(AgentKnowledge.Compose(defaults: null, Agent(knowledge: null))); - } - - [Fact] - public void Compose_DefaultsOnly_UsesTheDefaults() - { - var resolved = AgentKnowledge.Compose( - Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Limit = 5 }), - Agent(knowledge: null)); - - Assert.Equal(KnowledgeMode.Prefetch, resolved!.Mode); - Assert.Equal(5, resolved.Limit); - Assert.False(resolved.Citations); - Assert.True(resolved.Scoped); - } - - [Fact] - public void Compose_AgentSetsTwoKeys_InheritsTheRestKeyByKey() - { - // This is the new merge semantics. `Model` replaces wholesale and `Instructions` - // concatenates; neither is this. - var resolved = AgentKnowledge.Compose( - Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Limit = 5, Citations = false }), - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Citations = false })); - - Assert.Equal(KnowledgeMode.Tool, resolved!.Mode); - Assert.Equal(5, resolved.Limit); // inherited - Assert.False(resolved.Citations); - } - - [Fact] - public void Compose_AgentOverridesOnlyMode_LimitStillCameFromDefaultsNotTheBuiltInDefault() - { - // Defaults' Limit (7) differs from the built-in default (5), so this only passes if the - // merge actually reads agents.defaults.knowledge.limit, and not a wholesale-replace that - // falls back straight from the agent's block to the built-in constant. - var resolved = AgentKnowledge.Compose( - Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Limit = 7 }), - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool })); - - Assert.Equal(7, resolved!.Limit); - } - - [Fact] - public void Compose_CitationsUnset_DefaultsToFalse() + /// + /// : the key-by-key merge of one agent's knowledge: block against + /// agents.defaults.knowledge, and the two boolean questions it answers over a whole document. + /// + public sealed class AgentKnowledgeTests { - // A forgotten flag must fail loudly, not leak silently: manifest titles carry - // internal labels and ticket titles can carry a customer name. - var resolved = AgentKnowledge.Compose(null, Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool })); - - Assert.False(resolved!.Citations); - } + [Fact] + public void Compose_NoBlockAnywhere_IsNull() + { + // An agent with nothing to do with the knowledge base gets no provider at all, + // and therefore pays nothing. + Assert.Null(AgentKnowledge.Compose(defaults: null, Agent(knowledge: null))); + } - [Fact] - public void Compose_ScopedUnset_DefaultsToTrue() - { - var resolved = AgentKnowledge.Compose(null, Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool })); + [Fact] + public void Compose_DefaultsOnly_UsesTheDefaults() + { + ResolvedKnowledge? resolved = AgentKnowledge.Compose( + Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Limit = 5 }), + Agent(knowledge: null)); + + Assert.Equal(KnowledgeMode.Prefetch, resolved!.Mode); + Assert.Equal(5, resolved.Limit); + Assert.False(resolved.Citations); + Assert.True(resolved.Scoped); + } - Assert.True(resolved!.Scoped); - } + [Fact] + public void Compose_AgentSetsTwoKeys_InheritsTheRestKeyByKey() + { + // This is the new merge semantics. `Model` replaces wholesale and `Instructions` + // concatenates; neither is this. + ResolvedKnowledge? resolved = AgentKnowledge.Compose( + Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Limit = 5, Citations = false }), + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Citations = false })); + + Assert.Equal(KnowledgeMode.Tool, resolved!.Mode); + Assert.Equal(5, resolved.Limit); // inherited + Assert.False(resolved.Citations); + } - [Fact] - public void AnyScoped_OneScopedAgentAmongUnscopedOnes_IsTrue() - { - var section = new AgentsConfiguration + [Fact] + public void Compose_AgentOverridesOnlyMode_LimitStillCameFromDefaultsNotTheBuiltInDefault() { - Items = - [ - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Scoped = false }, id: "analyst"), - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch }, id: "resolver"), - ], - }; + // Defaults' Limit (7) differs from the built-in default (5), so this only passes if the + // merge actually reads agents.defaults.knowledge.limit, and not a wholesale-replace that + // falls back straight from the agent's block to the built-in constant. + ResolvedKnowledge? resolved = AgentKnowledge.Compose( + Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Limit = 7 }), + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool })); + + Assert.Equal(7, resolved!.Limit); + } - Assert.True(AgentKnowledge.AnyScoped(section)); - } + [Fact] + public void Compose_CitationsUnset_DefaultsToFalse() + { + // A forgotten flag must fail loudly, not leak silently: manifest titles carry + // internal labels and ticket titles can carry a customer name. + ResolvedKnowledge? resolved = AgentKnowledge.Compose(null, Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool })); - [Fact] - public void AnyScoped_NoAgentDeclaresKnowledge_IsFalse() - => Assert.False(AgentKnowledge.AnyScoped(new AgentsConfiguration { Items = [Agent(knowledge: null)] })); + Assert.False(resolved!.Citations); + } - [Fact] - public void AnyScoped_AgentInheritsScopedFromDefaultsWithNoOwnBlock_IsTrue() - { - // The composed value, not the raw one: this agent declares no knowledge: block of its own, - // and is still scoped because it inherits scoped: true from agents.defaults.knowledge. - var section = new AgentsConfiguration + [Fact] + public void Compose_ScopedUnset_DefaultsToTrue() { - Defaults = Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Scoped = true }), - Items = [Agent(knowledge: null)], - }; + ResolvedKnowledge? resolved = AgentKnowledge.Compose(null, Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool })); - Assert.True(AgentKnowledge.AnyScoped(section)); - } + Assert.True(resolved!.Scoped); + } - [Fact] - public void AllScoped_EveryAgentThatDeclaresKnowledgeIsScoped_IsTrue() - { - var section = new AgentsConfiguration + [Fact] + public void AnyScoped_OneScopedAgentAmongUnscopedOnes_IsTrue() { - Items = - [ - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool }, id: "a"), - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, id: "b"), - ], - }; - - Assert.True(AgentKnowledge.AllScoped(section)); - } + AgentsConfiguration section = new() + { + Items = + [ + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Scoped = false }, id: "analyst"), + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch }, id: "resolver"), + ], + }; + + Assert.True(AgentKnowledge.AnyScoped(section)); + } - [Fact] - public void AllScoped_OneUnscopedAgentAmongScopedOnes_IsFalse() - { - var section = new AgentsConfiguration + [Fact] + public void AnyScoped_NoAgentDeclaresKnowledge_IsFalse() { - Items = - [ - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool }, id: "a"), - Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = false }, id: "b"), - ], - }; + Assert.False(AgentKnowledge.AnyScoped(new AgentsConfiguration { Items = [Agent(knowledge: null)] })); + } - Assert.False(AgentKnowledge.AllScoped(section)); - } + [Fact] + public void AnyScoped_AgentInheritsScopedFromDefaultsWithNoOwnBlock_IsTrue() + { + // The composed value, not the raw one: this agent declares no knowledge: block of its own, + // and is still scoped because it inherits scoped: true from agents.defaults.knowledge. + AgentsConfiguration section = new() + { + Defaults = Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Scoped = true }), + Items = [Agent(knowledge: null)], + }; + + Assert.True(AgentKnowledge.AnyScoped(section)); + } - [Fact] - public void AllScoped_NoAgentDeclaresKnowledge_IsTrueVacuously() - // Mirrors Enumerable.All's own empty-sequence convention. A store no agent ever reads is - // never asked to enforce anything, so defaulting the empty case to the fail-closed direction - // costs nothing. - => Assert.True(AgentKnowledge.AllScoped(new AgentsConfiguration { Items = [Agent(knowledge: null)] })); + [Fact] + public void AllScoped_EveryAgentThatDeclaresKnowledgeIsScoped_IsTrue() + { + AgentsConfiguration section = new() + { + Items = + [ + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool }, id: "a"), + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, id: "b"), + ], + }; + + Assert.True(AgentKnowledge.AllScoped(section)); + } - [Fact] - public void AllScoped_AgentInheritsUnscopedFromDefaultsWithNoOwnBlock_IsFalse() - { - // Composed, not raw, cuts both ways: an agent with no knowledge: block of its own still - // counts against AllScoped when the defaults it inherits from set scoped: false. - var section = new AgentsConfiguration + [Fact] + public void AllScoped_OneUnscopedAgentAmongScopedOnes_IsFalse() { - Defaults = Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Scoped = false }), - Items = [Agent(knowledge: null)], - }; + AgentsConfiguration section = new() + { + Items = + [ + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool }, id: "a"), + Agent(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = false }, id: "b"), + ], + }; + + Assert.False(AgentKnowledge.AllScoped(section)); + } - Assert.False(AgentKnowledge.AllScoped(section)); - } + [Fact] + public void AllScoped_NoAgentDeclaresKnowledge_IsTrueVacuously() + { + // Mirrors Enumerable.All's own empty-sequence convention. A store no agent ever reads is + // never asked to enforce anything, so defaulting the empty case to the fail-closed direction + // costs nothing. + Assert.True(AgentKnowledge.AllScoped(new AgentsConfiguration { Items = [Agent(knowledge: null)] })); + } - [Fact] - public void TwoDefaultValuedInstances_AreEqualAndShareAHashCode() - { - // ResolvedKnowledge is a public record; its generated Equals and GetHashCode walk every - // member, including Clarification. A default value that allocates a fresh instance per - // ResolvedKnowledge would compare unequal to another default-valued one by reference, - // silently breaking the value semantics a record promises. - var a = new ResolvedKnowledge(KnowledgeMode.Prefetch, 5, Citations: false, Scoped: true); - var b = new ResolvedKnowledge(KnowledgeMode.Prefetch, 5, Citations: false, Scoped: true); - - Assert.Equal(a, b); - Assert.Equal(a.GetHashCode(), b.GetHashCode()); - } + [Fact] + public void AllScoped_AgentInheritsUnscopedFromDefaultsWithNoOwnBlock_IsFalse() + { + // Composed, not raw, cuts both ways: an agent with no knowledge: block of its own still + // counts against AllScoped when the defaults it inherits from set scoped: false. + AgentsConfiguration section = new() + { + Defaults = Defaults(new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Tool, Scoped = false }), + Items = [Agent(knowledge: null)], + }; + + Assert.False(AgentKnowledge.AllScoped(section)); + } - [Fact] - public void TheShippedSchema_CapsLimitAtTheSameValueAsTheConstant() - { - // JSON Schema cannot reference a C# constant, so agentcore-v1.schema.json hardcodes - // AgentKnowledgeConfiguration.MaximumLimit's value under $defs.agentKnowledge.properties.limit. - // Nothing ties the two together at compile time, so this is what catches the day someone - // changes one and forgets the other. - var path = Path.Combine(RepositoryRoot(), "src", "AgentCore.Application", "Configuration", "Schema", "agentcore-v1.schema.json"); - Assert.True(File.Exists(path), $"The shipped schema is missing at '{path}'."); + [Fact] + public void TwoDefaultValuedInstances_AreEqualAndShareAHashCode() + { + // ResolvedKnowledge is a public record; its generated Equals and GetHashCode walk every + // member, including Clarification. A default value that allocates a fresh instance per + // ResolvedKnowledge would compare unequal to another default-valued one by reference, + // silently breaking the value semantics a record promises. + ResolvedKnowledge a = new(KnowledgeMode.Prefetch, 5, Citations: false, Scoped: true); + ResolvedKnowledge b = new(KnowledgeMode.Prefetch, 5, Citations: false, Scoped: true); + + Assert.Equal(a, b); + Assert.Equal(a.GetHashCode(), b.GetHashCode()); + } - var schema = JsonNode.Parse(File.ReadAllText(path))!; - var maximum = schema["$defs"]!["agentKnowledge"]!["properties"]!["limit"]!["maximum"]!.GetValue(); + [Fact] + public void TheShippedSchema_CapsLimitAtTheSameValueAsTheConstant() + { + // JSON Schema cannot reference a C# constant, so agentcore-v1.schema.json hardcodes + // AgentKnowledgeConfiguration.MaximumLimit's value under $defs.agentKnowledge.properties.limit. + // Nothing ties the two together at compile time, so this is what catches the day someone + // changes one and forgets the other. + string path = Path.Combine(RepositoryRoot(), "src", "AgentCore.Application", "Configuration", "Schema", "agentcore-v1.schema.json"); + Assert.True(File.Exists(path), $"The shipped schema is missing at '{path}'."); - Assert.Equal(AgentKnowledgeConfiguration.MaximumLimit, maximum); - } + JsonNode schema = JsonNode.Parse(File.ReadAllText(path))!; + int maximum = schema["$defs"]!["agentKnowledge"]!["properties"]!["limit"]!["maximum"]!.GetValue(); - private static AgentConfiguration Agent(AgentKnowledgeConfiguration? knowledge, string id = "agent") - => new() { Id = id, Knowledge = knowledge }; + Assert.Equal(AgentKnowledgeConfiguration.MaximumLimit, maximum); + } - private static AgentDefaults Defaults(AgentKnowledgeConfiguration knowledge) - => new() { Knowledge = knowledge }; + private static AgentConfiguration Agent(AgentKnowledgeConfiguration? knowledge, string id = "agent") + { + return new() { Id = id, Knowledge = knowledge }; + } - private static string RepositoryRoot() - { - var directory = new DirectoryInfo(AppContext.BaseDirectory); - while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + private static AgentDefaults Defaults(AgentKnowledgeConfiguration knowledge) { - directory = directory.Parent; + return new() { Knowledge = knowledge }; } - Assert.NotNull(directory); - return directory!.FullName; + private static string RepositoryRoot() + { + DirectoryInfo? directory = new(AppContext.BaseDirectory); + while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + { + directory = directory.Parent; + } + + Assert.NotNull(directory); + return directory!.FullName; + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/AgenticKeySchemaTests.cs b/tests/AgentCore.Application.Tests/Configuration/AgenticKeySchemaTests.cs index b15f8990..c3e62de2 100644 --- a/tests/AgentCore.Application.Tests/Configuration/AgenticKeySchemaTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/AgenticKeySchemaTests.cs @@ -1,83 +1,88 @@ using System.Text.Json.Nodes; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The agentic keys and the values agentcore-v1.schema.json allows for them. The schema hardcodes -/// every spelling, so this is what catches the day someone changes a record and forgets the -/// document it describes. -/// -public sealed class AgenticKeySchemaTests +namespace AgentCore.Application.Tests.Configuration { - [Fact] - public void TheSchema_DeclaresEveryAgenticKeyTheRecordCarries() + /// + /// The agentic keys and the values agentcore-v1.schema.json allows for them. The schema hardcodes + /// every spelling, so this is what catches the day someone changes a record and forgets the + /// document it describes. + /// + public sealed class AgenticKeySchemaTests { - var agent = Schema()["$defs"]!["agent"]!["properties"]!; - - List keys = ["todos", "mode", "memory", "files", "shell", "approval", "background", "loop"]; - foreach (string key in keys) + [Fact] + public void TheSchema_DeclaresEveryAgenticKeyTheRecordCarries() { - Assert.True(agent[key] is not null, $"agentcore-v1.schema.json does not declare 'agent.{key}'."); - } - } + JsonNode agent = Schema()["$defs"]!["agent"]!["properties"]!; - [Fact] - public void TheDefaults_DeclareTheInheritableKeysTheRecordCarries() - { - var defaults = Schema()["$defs"]!["agents"]!["properties"]!["defaults"]!["properties"]!; + List keys = ["todos", "mode", "memory", "files", "shell", "approval", "background", "loop"]; + foreach (string key in keys) + { + Assert.True(agent[key] is not null, $"agentcore-v1.schema.json does not declare 'agent.{key}'."); + } + } - List keys = ["todos", "mode", "approval"]; - foreach (string key in keys) + [Fact] + public void TheDefaults_DeclareTheInheritableKeysTheRecordCarries() { - Assert.True(defaults[key] is not null, $"agentcore-v1.schema.json does not declare 'defaults.{key}'."); + JsonNode defaults = Schema()["$defs"]!["agents"]!["properties"]!["defaults"]!["properties"]!; + + List keys = ["todos", "mode", "approval"]; + foreach (string key in keys) + { + Assert.True(defaults[key] is not null, $"agentcore-v1.schema.json does not declare 'defaults.{key}'."); + } } - } - [Fact] - public void TheStoresTheSchemaAllows_AreWorkspace() - { - Assert.True(JsonNode.DeepEquals(Enum("agentStore"), Parse("[\"workspace\"]"))); - } + [Fact] + public void TheStoresTheSchemaAllows_AreWorkspace() + { + Assert.True(JsonNode.DeepEquals(Enum("agentStore"), Parse("[\"workspace\"]"))); + } - [Fact] - public void TheShellKindsTheSchemaAllows_AreDockerAndLocal() - { - Assert.True(JsonNode.DeepEquals(Enum("shellKind"), Parse("[\"docker\", \"local\"]"))); - } + [Fact] + public void TheShellKindsTheSchemaAllows_AreDockerAndLocal() + { + Assert.True(JsonNode.DeepEquals(Enum("shellKind"), Parse("[\"docker\", \"local\"]"))); + } - [Fact] - public void TheLoopConditionsTheSchemaAllows_AreTodosAndBackground() - { - var until = Schema()["$defs"]!["loopUntil"]!["properties"]!; + [Fact] + public void TheLoopConditionsTheSchemaAllows_AreTodosAndBackground() + { + JsonNode until = Schema()["$defs"]!["loopUntil"]!["properties"]!; - Assert.True(until["todos"] is not null); - Assert.True(until["background"] is not null); - } + Assert.True(until["todos"] is not null); + Assert.True(until["background"] is not null); + } - private static JsonNode Enum(string name) - => Schema()["$defs"]![name]!["enum"]!; + private static JsonNode Enum(string name) + { + return Schema()["$defs"]![name]!["enum"]!; + } - private static JsonNode Parse(string json) - => JsonNode.Parse(json)!; + private static JsonNode Parse(string json) + { + return JsonNode.Parse(json)!; + } - private static JsonNode Schema() - { - var path = Path.Combine(RepositoryRoot(), "src", "AgentCore.Application", "Configuration", "Schema", "agentcore-v1.schema.json"); - Assert.True(File.Exists(path), $"The shipped schema is missing at '{path}'."); + private static JsonNode Schema() + { + string path = Path.Combine(RepositoryRoot(), "src", "AgentCore.Application", "Configuration", "Schema", "agentcore-v1.schema.json"); + Assert.True(File.Exists(path), $"The shipped schema is missing at '{path}'."); - return JsonNode.Parse(File.ReadAllText(path))!; - } + return JsonNode.Parse(File.ReadAllText(path))!; + } - private static string RepositoryRoot() - { - var directory = new DirectoryInfo(AppContext.BaseDirectory); - while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + private static string RepositoryRoot() { - directory = directory.Parent; - } + DirectoryInfo? directory = new(AppContext.BaseDirectory); + while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + { + directory = directory.Parent; + } - Assert.NotNull(directory); - return directory!.FullName; + Assert.NotNull(directory); + return directory!.FullName; + } } -} \ No newline at end of file +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs index 43976a58..8a56421b 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/AgentToolTests.cs @@ -1,3 +1,4 @@ +using System.Text.Json; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -6,20 +7,20 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The fourth tool kind of section 8.1: kind: agent, which is agent-as-tool. -/// -/// -/// MAF separates handoff from agent-as-tool. graph: with pattern: handoff already -/// carries handoff, so this kind carries the other half: the outer agent calls the inner agent, -/// reads the reply, and keeps control. -/// -public sealed class AgentToolTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string DelegatingYaml = - """ + /// + /// The fourth tool kind of section 8.1: kind: agent, which is agent-as-tool. + /// + /// + /// MAF separates handoff from agent-as-tool. graph: with pattern: handoff already + /// carries handoff, so this kind carries the other half: the outer agent calls the inner agent, + /// reads the reply, and keeps control. + /// + public sealed class AgentToolTests + { + private const string DelegatingYaml = + """ apiVersion: agentcore/v1 tools: - id: ask_specialist @@ -42,8 +43,8 @@ public sealed class AgentToolTests - { id: talk, agent: front, terminal: true } """; - private const string TwoCallersYaml = - """ + private const string TwoCallersYaml = + """ apiVersion: agentcore/v1 tools: - { id: ask_specialist, kind: agent, agent: specialist, description: Ask the specialist. } @@ -61,8 +62,8 @@ public sealed class AgentToolTests - { id: fallback, agent: backup, terminal: true } """; - private const string MissingAgentYaml = - """ + private const string MissingAgentYaml = + """ apiVersion: agentcore/v1 tools: - { id: ask_nobody, kind: agent, agent: nobody, description: Ask an agent nobody declared. } @@ -74,8 +75,8 @@ public sealed class AgentToolTests agent: front """; - private const string CycleYaml = - """ + private const string CycleYaml = + """ apiVersion: agentcore/v1 tools: - { id: ask_second, kind: agent, agent: second, description: Ask the second agent. } @@ -92,28 +93,28 @@ public sealed class AgentToolTests - { id: talk, agent: first, terminal: true } """; - private static readonly string[] Tags = ["belt", "motor"]; - - // --------------------------------------------------------------------------------------------- - // Binding. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AKindAgentTool_BindsItsAgentField() - { - var document = ConfigurationLoader.LoadYaml(DelegatingYaml); - - var tool = Assert.Single(document.Tools); - Assert.Equal("ask_specialist", tool.Id); - Assert.Equal(ToolKind.Agent, tool.Kind); - Assert.Equal("specialist", tool.Agent); - Assert.Equal("Ask the specialist one product question.", tool.Description); - Assert.NotNull(tool.Parameters); - } - - [Fact] - public void AKindAgentTool_WithNoAgentField_FailsCheckOne() - { - const string document = """ + private static readonly string[] Tags = ["belt", "motor"]; + + // --------------------------------------------------------------------------------------------- + // Binding. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AKindAgentTool_BindsItsAgentField() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(DelegatingYaml); + + ToolConfiguration tool = Assert.Single(document.Tools); + Assert.Equal("ask_specialist", tool.Id); + Assert.Equal(ToolKind.Agent, tool.Kind); + Assert.Equal("specialist", tool.Agent); + Assert.Equal("Ask the specialist one product question.", tool.Description); + Assert.NotNull(tool.Parameters); + } + + [Fact] + public void AKindAgentTool_WithNoAgentField_FailsCheckOne() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: ask_specialist, kind: agent, description: Ask the specialist. } @@ -125,242 +126,243 @@ public void AKindAgentTool_WithNoAgentField_FailsCheckOne() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/tools/0", StringComparison.Ordinal)); - } - - // --------------------------------------------------------------------------------------------- - // Compiling. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindAgentTool_ReachesTheModelWithTheDeclaredShape() - { - using ToolCallingChatClient client = new("the specialist answer"); - var compiled = Compile(DelegatingYaml, client); - - await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); - - var function = client.Offered[0]; - - // The calling model reads the name, the description, and the parameters, and all three come - // from the document rather than from the framework default. - Assert.Equal("ask_specialist", function.Name); - Assert.Equal("Ask the specialist one product question.", function.Description); - Assert.Contains("question", function.JsonSchema.ToString(), StringComparison.Ordinal); - - // Three requests: the outer agent calls the tool, the inner agent answers, and the outer - // agent replies. Only the two outer requests carry a tool, because the document gives the - // inner agent none. The inner tool-calling loop is the inner agent's own. - Assert.Equal(3, client.Calls); - Assert.Equal(2, client.Offered.Count); - Assert.All(client.Offered, offered => Assert.Equal("ask_specialist", offered.Name)); - } - - [Fact] - public async Task TheDeclaredParameters_ReplaceTheGeneratedSingleStringSchema() - { - using ToolCallingChatClient client = new("the specialist answer"); - var compiled = Compile(DelegatingYaml, client); - - await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); - - var schema = client.Offered[0].JsonSchema; - - // The whole point of the wrapper: what the model sees is the document's parameters block and - // nothing else. AsAIFunction() generates one string argument named query, so a schema that - // still carries query is a schema the substitution failed to replace. - var properties = schema.GetProperty("properties"); - Assert.Equal("question", Assert.Single(properties.EnumerateObject()).Name); - Assert.False(properties.TryGetProperty("query", out _)); - Assert.Equal("object", schema.GetProperty("type").GetString()); - Assert.Equal( - ["question"], - schema.GetProperty("required").EnumerateArray().Select(entry => entry.GetString())); - } - - [Fact] - public async Task D8_TheDelegatingFunction_NeverHandsBackTheInnerAgent() - { - using ToolCallingChatClient client = new("the specialist answer"); - var compiled = Compile(DelegatingYaml, client); - - await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); - - var function = client.Offered[0]; - - // The wrapper forwards GetService to the function AsAIFunction() built. That function closes - // over the inner AIAgent but never publishes it, and D8 depends on it staying that way: no - // probe may pull an agent out of a tool the outer agent advertises. - Assert.Null(function.GetService()); - Assert.Null(function.GetService()); - - // The probe the framework does make answers the same before and after the forward. - Assert.Null(function.GetService()); - - // Asking for what this object is still returns this object, keyed lookups still find nothing. - Assert.Same(function, function.GetService()); - Assert.Null(function.GetService("keyed")); - } - - [Fact] - public void AKindAgentTool_NeedsNoToolFactory() - { - using ToolCallingChatClient client = new("the specialist answer"); - - // Every other kind needs AgentCompilationContext.Tools. This one does not, because the inner - // agent is already in the document. Section 7: section 8 adds no port. - var compiled = Compile(DelegatingYaml, client); - - Assert.Equal(2, compiled.Agents.Count); - } - - [Fact] - public async Task TheOuterAgent_CallsTheInnerAgentAndKeepsControl() - { - using ToolCallingChatClient client = new( - "the specialist answer", - new Dictionary(StringComparer.Ordinal) { ["question"] = "where is my order" }); - - var compiled = Compile(DelegatingYaml, client); - - var reply = await compiled.Agent.RunAsync( - "help me", - cancellationToken: TestContext.Current.CancellationToken); - - // The outer agent asked for the tool the document declares. - Assert.Equal(["ask_specialist"], client.Called); - - // The inner agent read the arguments the model filled, as one JSON object. - Assert.Contains(client.Prompts, prompt => prompt.Contains("where is my order", StringComparison.Ordinal)); - - // The inner reply came back as a tool result, and the outer agent produced the final text. - Assert.Contains("the specialist answer", client.ToolResults); - Assert.Equal("the specialist answer", reply.Text); - } - - // --------------------------------------------------------------------------------------------- - // The fallback arm of the argument switch. A type it does not name is carried as the text of - // ToString(), and not serialized. Any replacement for the switch has to keep answering this way. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AnArgumentTypeTheSwitchDoesNotName_ReachesTheInnerAgentAsItsToStringText() - { - using ToolCallingChatClient client = new( - "the specialist answer", - new Dictionary(StringComparer.Ordinal) { ["question"] = Tags }); - - var compiled = Compile(DelegatingYaml, client); - - await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); - - Assert.Contains( - client.Prompts, - prompt => prompt.Contains("""{"question":"System.String[]"}""", StringComparison.Ordinal)); - } - - // --------------------------------------------------------------------------------------------- - // T44 and rule 16: the compiled agent is a process singleton, and delegation does not break it. - // --------------------------------------------------------------------------------------------- - [Fact] - public void Rule16_ADelegatingDocument_BuildsTheInnerAgentOnce() - { - using ToolCallingChatClient client = new("the specialist answer"); - FakeChatClientFactory factory = new(client); - var document = ConfigurationLoader.LoadYaml(TwoCallersYaml); - - var compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(factory))["main"]; - - // Three declared agents, so three model resolutions, each asking the factory twice: once - // for the compaction pipeline's summariser, once for its own ChatClientAgent. Two callers - // share the one specialist, and neither of them compiled a second copy of it. - Assert.Equal(3, compiled.Agents.Count); - Assert.Equal(6, factory.Requested.Count); - } - - [Fact] - public void Rule16_ADelegatingDocument_CompilesOnceThroughTheRegistry() - { - using ToolCallingChatClient client = new("the specialist answer"); - FakeChatClientFactory factory = new(client); - var document = ConfigurationLoader.LoadYaml(TwoCallersYaml); - AgentCompilationContext context = new(factory); - CompiledAgentRegistry registry = new(); - - var first = registry.GetOrCompile(document, "main", context); - var second = registry.GetOrCompile(document, "main", context); - - Assert.Same(first, second); - Assert.Equal(1, registry.CompileCount); - Assert.Equal(6, factory.Requested.Count); - } - - [Fact] - public async Task Rule16_TwentySixSimultaneousConversations_ShareOneDelegatingAgent() - { - const int fanOut = 26; - - using ToolCallingChatClient client = new("the specialist answer"); - var document = ConfigurationLoader.LoadYaml(DelegatingYaml); - AgentCompilationContext context = new(new FakeChatClientFactory(client)); - CompiledAgentRegistry registry = new(); - - var token = TestContext.Current.CancellationToken; - using Barrier gate = new(fanOut); - - var runs = Enumerable.Range(0, fanOut).Select(index => Task.Run( - async () => - { - var compiled = registry.GetOrCompile(document, "main", context); - gate.SignalAndWait(token); - - var reply = await compiled.Agent.RunAsync($"conversation {index}", cancellationToken: token) - .ConfigureAwait(false); - return (compiled, reply.Text); - }, - token)); - - var results = await Task.WhenAll(runs); - - Assert.Equal(1, registry.CompileCount); - Assert.All(results, result => Assert.Same(results[0].compiled, result.compiled)); - Assert.All(results, result => Assert.Equal("the specialist answer", result.Text)); - } - - // --------------------------------------------------------------------------------------------- - // Failing at load. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AKindAgentTool_NamingAnAgentThatDoesNotExist_FailsAtLoad() - { - // Check 1 passes: the shape is right, and JSON Schema cannot cross-reference. - var document = ConfigurationLoader.LoadYaml(MissingAgentYaml); - - using ToolCallingChatClient client = new("never reached"); - var failure = Assert.Throws( - () => ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]); - - Assert.Equal("/agents/items/0/tools/0", failure.Pointer); - Assert.Contains("nobody", failure.Message, StringComparison.Ordinal); - Assert.Contains("agents.items does not declare", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void ADelegationCycle_FailsAtLoadAndNeverRecursesForever() - { - var document = ConfigurationLoader.LoadYaml(CycleYaml); - - using ToolCallingChatClient client = new("never reached"); - var failure = Assert.Throws( - () => ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]); - - Assert.Contains("first -> second -> first", failure.Message, StringComparison.Ordinal); - } - - private static CompiledAgent Compile(string yaml, IChatClient client) - { - var document = ConfigurationLoader.LoadYaml(yaml); - return ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; - } - } + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/tools/0", StringComparison.Ordinal)); + } + + // --------------------------------------------------------------------------------------------- + // Compiling. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindAgentTool_ReachesTheModelWithTheDeclaredShape() + { + using ToolCallingChatClient client = new("the specialist answer"); + CompiledAgent compiled = Compile(DelegatingYaml, client); + + _ = await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); + + AIFunction function = client.Offered[0]; + + // The calling model reads the name, the description, and the parameters, and all three come + // from the document rather than from the framework default. + Assert.Equal("ask_specialist", function.Name); + Assert.Equal("Ask the specialist one product question.", function.Description); + Assert.Contains("question", function.JsonSchema.ToString(), StringComparison.Ordinal); + + // Three requests: the outer agent calls the tool, the inner agent answers, and the outer + // agent replies. Only the two outer requests carry a tool, because the document gives the + // inner agent none. The inner tool-calling loop is the inner agent's own. + Assert.Equal(3, client.Calls); + Assert.Equal(2, client.Offered.Count); + Assert.All(client.Offered, offered => Assert.Equal("ask_specialist", offered.Name)); + } + + [Fact] + public async Task TheDeclaredParameters_ReplaceTheGeneratedSingleStringSchema() + { + using ToolCallingChatClient client = new("the specialist answer"); + CompiledAgent compiled = Compile(DelegatingYaml, client); + + _ = await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); + + JsonElement schema = client.Offered[0].JsonSchema; + + // The whole point of the wrapper: what the model sees is the document's parameters block and + // nothing else. AsAIFunction() generates one string argument named query, so a schema that + // still carries query is a schema the substitution failed to replace. + JsonElement properties = schema.GetProperty("properties"); + Assert.Equal("question", Assert.Single(properties.EnumerateObject()).Name); + Assert.False(properties.TryGetProperty("query", out _)); + Assert.Equal("object", schema.GetProperty("type").GetString()); + Assert.Equal( + ["question"], + schema.GetProperty("required").EnumerateArray().Select(entry => entry.GetString())); + } + + [Fact] + public async Task D8_TheDelegatingFunction_NeverHandsBackTheInnerAgent() + { + using ToolCallingChatClient client = new("the specialist answer"); + CompiledAgent compiled = Compile(DelegatingYaml, client); + + _ = await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); + + AIFunction function = client.Offered[0]; + + // The wrapper forwards GetService to the function AsAIFunction() built. That function closes + // over the inner AIAgent but never publishes it, and D8 depends on it staying that way: no + // probe may pull an agent out of a tool the outer agent advertises. + Assert.Null(function.GetService()); + Assert.Null(function.GetService()); + + // The probe the framework does make answers the same before and after the forward. + Assert.Null(function.GetService()); + + // Asking for what this object is still returns this object, keyed lookups still find nothing. + Assert.Same(function, function.GetService()); + Assert.Null(function.GetService("keyed")); + } + + [Fact] + public void AKindAgentTool_NeedsNoToolFactory() + { + using ToolCallingChatClient client = new("the specialist answer"); + + // Every other kind needs AgentCompilationContext.Tools. This one does not, because the inner + // agent is already in the document. Section 7: section 8 adds no port. + CompiledAgent compiled = Compile(DelegatingYaml, client); + + Assert.Equal(2, compiled.Agents.Count); + } + + [Fact] + public async Task TheOuterAgent_CallsTheInnerAgentAndKeepsControl() + { + using ToolCallingChatClient client = new( + "the specialist answer", + new Dictionary(StringComparer.Ordinal) { ["question"] = "where is my order" }); + + CompiledAgent compiled = Compile(DelegatingYaml, client); + + AgentResponse reply = await compiled.Agent.RunAsync( + "help me", + cancellationToken: TestContext.Current.CancellationToken); + + // The outer agent asked for the tool the document declares. + Assert.Equal(["ask_specialist"], client.Called); + + // The inner agent read the arguments the model filled, as one JSON object. + Assert.Contains(client.Prompts, prompt => prompt.Contains("where is my order", StringComparison.Ordinal)); + + // The inner reply came back as a tool result, and the outer agent produced the final text. + Assert.Contains("the specialist answer", client.ToolResults); + Assert.Equal("the specialist answer", reply.Text); + } + + // --------------------------------------------------------------------------------------------- + // The fallback arm of the argument switch. A type it does not name is carried as the text of + // ToString(), and not serialized. Any replacement for the switch has to keep answering this way. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AnArgumentTypeTheSwitchDoesNotName_ReachesTheInnerAgentAsItsToStringText() + { + using ToolCallingChatClient client = new( + "the specialist answer", + new Dictionary(StringComparer.Ordinal) { ["question"] = Tags }); + + CompiledAgent compiled = Compile(DelegatingYaml, client); + + _ = await compiled.Agent.RunAsync("help me", cancellationToken: TestContext.Current.CancellationToken); + + Assert.Contains( + client.Prompts, + prompt => prompt.Contains(/*lang=json,strict*/ """{"question":"System.String[]"}""", StringComparison.Ordinal)); + } + + // --------------------------------------------------------------------------------------------- + // T44 and rule 16: the compiled agent is a process singleton, and delegation does not break it. + // --------------------------------------------------------------------------------------------- + [Fact] + public void Rule16_ADelegatingDocument_BuildsTheInnerAgentOnce() + { + using ToolCallingChatClient client = new("the specialist answer"); + FakeChatClientFactory factory = new(client); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(TwoCallersYaml); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(factory))["main"]; + + // Three declared agents, so three model resolutions, each asking the factory twice: once + // for the compaction pipeline's summariser, once for its own ChatClientAgent. Two callers + // share the one specialist, and neither of them compiled a second copy of it. + Assert.Equal(3, compiled.Agents.Count); + Assert.Equal(6, factory.Requested.Count); + } + + [Fact] + public void Rule16_ADelegatingDocument_CompilesOnceThroughTheRegistry() + { + using ToolCallingChatClient client = new("the specialist answer"); + FakeChatClientFactory factory = new(client); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(TwoCallersYaml); + AgentCompilationContext context = new(factory); + CompiledAgentRegistry registry = new(); + + CompiledAgent first = registry.GetOrCompile(document, "main", context); + CompiledAgent second = registry.GetOrCompile(document, "main", context); + + Assert.Same(first, second); + Assert.Equal(1, registry.CompileCount); + Assert.Equal(6, factory.Requested.Count); + } + + [Fact] + public async Task Rule16_TwentySixSimultaneousConversations_ShareOneDelegatingAgent() + { + const int fanOut = 26; + + using ToolCallingChatClient client = new("the specialist answer"); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(DelegatingYaml); + AgentCompilationContext context = new(new FakeChatClientFactory(client)); + CompiledAgentRegistry registry = new(); + + CancellationToken token = TestContext.Current.CancellationToken; + using Barrier gate = new(fanOut); + + IEnumerable> runs = Enumerable.Range(0, fanOut).Select(index => Task.Run( + async () => + { + CompiledAgent compiled = registry.GetOrCompile(document, "main", context); + gate.SignalAndWait(token); + + AgentResponse reply = await compiled.Agent.RunAsync($"conversation {index}", cancellationToken: token) + .ConfigureAwait(false); + return (compiled, reply.Text); + }, + token)); + + (CompiledAgent compiled, string Text)[] results = await Task.WhenAll(runs); + + Assert.Equal(1, registry.CompileCount); + Assert.All(results, result => Assert.Same(results[0].compiled, result.compiled)); + Assert.All(results, result => Assert.Equal("the specialist answer", result.Text)); + } + + // --------------------------------------------------------------------------------------------- + // Failing at load. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AKindAgentTool_NamingAnAgentThatDoesNotExist_FailsAtLoad() + { + // Check 1 passes: the shape is right, and JSON Schema cannot cross-reference. + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(MissingAgentYaml); + + using ToolCallingChatClient client = new("never reached"); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]); + + Assert.Equal("/agents/items/0/tools/0", failure.Pointer); + Assert.Contains("nobody", failure.Message, StringComparison.Ordinal); + Assert.Contains("agents.items does not declare", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void ADelegationCycle_FailsAtLoadAndNeverRecursesForever() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(CycleYaml); + + using ToolCallingChatClient client = new("never reached"); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]); + + Assert.Contains("first -> second -> first", failure.Message, StringComparison.Ordinal); + } + + private static CompiledAgent Compile(string yaml, IChatClient client) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + return ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; + } + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ApprovalCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ApprovalCompilationTests.cs index 210eeb7a..593d986f 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/ApprovalCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ApprovalCompilationTests.cs @@ -3,21 +3,22 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Tests.Fakes; using AgentCore.TestSupport; +using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The approval: block reaching a compiled agent as UseToolApproval rules: an -/// auto: entry lets its tool run with no request surfacing, anything else still asks, and -/// the layer adds no state keys — toolApprovalState persistence rides with the Phase 2 -/// round trip, when standing rules can exist. -/// -public sealed class ApprovalCompilationTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string GatedToolYaml = - """ + /// + /// The approval: block reaching a compiled agent as UseToolApproval rules: an + /// auto: entry lets its tool run with no request surfacing, anything else still asks, and + /// the layer adds no state keys — toolApprovalState persistence rides with the Phase 2 + /// round trip, when standing rules can exist. + /// + public sealed class ApprovalCompilationTests + { + private const string GatedToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: send_email, kind: builtin, uses: test.send, description: "Send an email." } @@ -32,8 +33,8 @@ public sealed class ApprovalCompilationTests agent: only """; - private const string UngatedToolYaml = - """ + private const string UngatedToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: send_email, kind: builtin, uses: test.send, description: "Send an email." } @@ -48,122 +49,122 @@ public sealed class ApprovalCompilationTests agent: only """; - [Fact] - public void Compose_AgentAuto_ReturnsItsOwn() - { - var agent = new AgentConfiguration + [Fact] + public void Compose_AgentAuto_ReturnsItsOwn() { - Id = "coder", - Approval = new ApprovalConfiguration { Auto = ["send_email"] }, - }; + AgentConfiguration agent = new() + { + Id = "coder", + Approval = new ApprovalConfiguration { Auto = ["send_email"] }, + }; - Assert.Equal(["send_email"], AgentApproval.Compose(null, agent)); - } + Assert.Equal(["send_email"], AgentApproval.Compose(null, agent)); + } - [Fact] - public void Compose_NoAgentAuto_ReturnsTheDefaults() - { - var defaults = new AgentDefaults { Approval = new ApprovalConfiguration { Auto = ["get_time"] } }; - var agent = new AgentConfiguration { Id = "coder" }; + [Fact] + public void Compose_NoAgentAuto_ReturnsTheDefaults() + { + AgentDefaults defaults = new() { Approval = new ApprovalConfiguration { Auto = ["get_time"] } }; + AgentConfiguration agent = new() { Id = "coder" }; - Assert.Equal(["get_time"], AgentApproval.Compose(defaults, agent)); - } + Assert.Equal(["get_time"], AgentApproval.Compose(defaults, agent)); + } - [Fact] - public void Compose_BothAuto_AgentWins() - { - var defaults = new AgentDefaults { Approval = new ApprovalConfiguration { Auto = ["get_time"] } }; - var agent = new AgentConfiguration + [Fact] + public void Compose_BothAuto_AgentWins() { - Id = "coder", - Approval = new ApprovalConfiguration { Auto = ["send_email"] }, - }; + AgentDefaults defaults = new() { Approval = new ApprovalConfiguration { Auto = ["get_time"] } }; + AgentConfiguration agent = new() + { + Id = "coder", + Approval = new ApprovalConfiguration { Auto = ["send_email"] }, + }; - Assert.Equal(["send_email"], AgentApproval.Compose(defaults, agent)); - } + Assert.Equal(["send_email"], AgentApproval.Compose(defaults, agent)); + } - [Fact] - public void Compose_NoApprovalAnywhere_ReturnsEmpty() - { - var agent = new AgentConfiguration { Id = "coder" }; + [Fact] + public void Compose_NoApprovalAnywhere_ReturnsEmpty() + { + AgentConfiguration agent = new() { Id = "coder" }; - Assert.Empty(AgentApproval.Compose(null, agent)); - } + Assert.Empty(AgentApproval.Compose(null, agent)); + } - [Fact] - public void Matches_ExactName_MatchesOnlyItself() - { - Assert.True(AgentApproval.Matches("send_email", "send_email")); - Assert.False(AgentApproval.Matches("send_email", "send_sms")); - Assert.False(AgentApproval.Matches("send_email", "Send_Email")); - } - - [Fact] - public void Matches_TrailingStar_MatchesByPrefix() - { - Assert.True(AgentApproval.Matches("file_access_read*", "file_access_read_lines")); - Assert.False(AgentApproval.Matches("file_access_read*", "file_access_write")); - } + [Fact] + public void Matches_ExactName_MatchesOnlyItself() + { + Assert.True(AgentApproval.Matches("send_email", "send_email")); + Assert.False(AgentApproval.Matches("send_email", "send_sms")); + Assert.False(AgentApproval.Matches("send_email", "Send_Email")); + } - [Fact] - public void Matches_StarAlone_MatchesEverythingButMidStarIsLiteral() - { - Assert.True(AgentApproval.Matches("*", "send_email")); - Assert.False(AgentApproval.Matches("send*email", "send_email")); - } + [Fact] + public void Matches_TrailingStar_MatchesByPrefix() + { + Assert.True(AgentApproval.Matches("file_access_read*", "file_access_read_lines")); + Assert.False(AgentApproval.Matches("file_access_read*", "file_access_write")); + } - [Fact] - public async Task Compile_ApprovalAutoMatchingTool_RunsWithoutSurfacingRequest() - { - var token = TestContext.Current.CancellationToken; - int sent = 0; - using ToolCallingChatClient client = new( - "done.", - new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" }); - var compiled = Compile(GatedToolYaml, client, () => sent++, token); - - var response = await compiled.Agents["only"].RunAsync("send it", cancellationToken: token); - - Assert.Equal(1, sent); - Assert.DoesNotContain( - response.Messages.SelectMany(message => message.Contents), - content => content is ToolApprovalRequestContent); - Assert.Equal("done.", response.Text); - } + [Fact] + public void Matches_StarAlone_MatchesEverythingButMidStarIsLiteral() + { + Assert.True(AgentApproval.Matches("*", "send_email")); + Assert.False(AgentApproval.Matches("send*email", "send_email")); + } - [Fact] - public async Task Compile_ApprovalAutoNamingAnotherTool_RequestStillSurfaces() - { - var token = TestContext.Current.CancellationToken; - int sent = 0; - using ToolCallingChatClient client = new( - "done.", - new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" }); - var compiled = Compile(UngatedToolYaml, client, () => sent++, token); + [Fact] + public async Task Compile_ApprovalAutoMatchingTool_RunsWithoutSurfacingRequest() + { + CancellationToken token = TestContext.Current.CancellationToken; + int sent = 0; + using ToolCallingChatClient client = new( + "done.", + new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" }); + CompiledAgent compiled = Compile(GatedToolYaml, client, () => sent++, token); + + AgentResponse response = await compiled.Agents["only"].RunAsync("send it", cancellationToken: token); + + Assert.Equal(1, sent); + Assert.DoesNotContain( + response.Messages.SelectMany(message => message.Contents), + content => content is ToolApprovalRequestContent); + Assert.Equal("done.", response.Text); + } + + [Fact] + public async Task Compile_ApprovalAutoNamingAnotherTool_RequestStillSurfaces() + { + CancellationToken token = TestContext.Current.CancellationToken; + int sent = 0; + using ToolCallingChatClient client = new( + "done.", + new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" }); + CompiledAgent compiled = Compile(UngatedToolYaml, client, () => sent++, token); - var response = await compiled.Agents["only"].RunAsync("send it", cancellationToken: token); + AgentResponse response = await compiled.Agents["only"].RunAsync("send it", cancellationToken: token); - Assert.Equal(0, sent); - Assert.Single(response.Messages.SelectMany(message => message.Contents).OfType()); - } + Assert.Equal(0, sent); + _ = Assert.Single(response.Messages.SelectMany(message => message.Contents).OfType()); + } - [Fact] - public void Compile_ApprovalSurface_KeepsTheQueueAndStandingKeys() - { - var token = TestContext.Current.CancellationToken; - using ToolCallingChatClient client = new("unused"); - var compiled = Compile(GatedToolYaml, client, () => { }, token); + [Fact] + public void Compile_ApprovalSurface_KeepsTheQueueAndStandingKeys() + { + CancellationToken token = TestContext.Current.CancellationToken; + using ToolCallingChatClient client = new("unused"); + CompiledAgent compiled = Compile(GatedToolYaml, client, () => { }, token); - Assert.Equal( - ["_pendingApprovalRequests", "toolApprovalState"], - compiled.HarnessStateKeys.OrderBy(key => key)); - } + Assert.Equal( + ["_pendingApprovalRequests", "toolApprovalState"], + compiled.HarnessStateKeys.OrderBy(key => key)); + } - [Fact] - public void Compile_PlainAgent_KeepsNoApprovalKeys() - { - const string plainYaml = - """ + [Fact] + public void Compile_PlainAgent_KeepsNoApprovalKeys() + { + const string plainYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -172,35 +173,39 @@ public void Compile_PlainAgent_KeepsNoApprovalKeys() main: agent: only """; - var token = TestContext.Current.CancellationToken; - using ToolCallingChatClient client = new("unused"); - var document = ConfigurationLoader.LoadYaml(plainYaml); - var compiled = ConfigurationCompiler.CompileAll( - document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; + _ = TestContext.Current.CancellationToken; + using ToolCallingChatClient client = new("unused"); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(plainYaml); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; - Assert.Empty(compiled.HarnessStateKeys); - } + Assert.Empty(compiled.HarnessStateKeys); + } - private static CompiledAgent Compile(string yaml, IChatClient client, Action onSend, CancellationToken token) - { - var document = ConfigurationLoader.LoadYaml(yaml); - return ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(client)) + private static CompiledAgent Compile(string yaml, IChatClient client, Action onSend, CancellationToken token) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + return ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(client)) + { + Tools = TestToolRegistry.From( + document, + declared => declared.Uses == "test.send" ? GatedSendEmail(onSend) : null, + token), + })["main"]; + } + + private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) + { + return new ApprovalRequiredAIFunction(AIFunctionFactory.Create( + (string to) => { - Tools = TestToolRegistry.From( - document, - declared => declared.Uses == "test.send" ? GatedSendEmail(onSend) : null, - token), - })["main"]; + onSend(); + return "sent"; + }, + "send_email", + "Send an email.")); + } } - - private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) => new ApprovalRequiredAIFunction(AIFunctionFactory.Create( - (string to) => - { - onSend(); - return "sent"; - }, - "send_email", - "Send an email.")); } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/BackgroundCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/BackgroundCompilationTests.cs index be5b47b2..4d6b848f 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/BackgroundCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/BackgroundCompilationTests.cs @@ -4,31 +4,30 @@ using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Runtime; using Microsoft.Agents.AI; -using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The background: list reaching a compiled agent as a , -/// the background_agents_* tools it puts in front of the model, and the state key it -/// contributes to resume. -/// -#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class BackgroundCompilationTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private static readonly string[] ExpectedBackgroundTools = - [ - "background_agents_start_task", - "background_agents_wait_for_first_completion", - "background_agents_get_task_results", - "background_agents_get_all_tasks", - "background_agents_continue_task", - "background_agents_clear_completed_task", - ]; - - private const string ParentWithChildYaml = - """ + /// + /// The background: list reaching a compiled agent as a , + /// the background_agents_* tools it puts in front of the model, and the state key it + /// contributes to resume. + /// +#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class BackgroundCompilationTests + { + private static readonly string[] ExpectedBackgroundTools = + [ + "background_agents_start_task", + "background_agents_wait_for_first_completion", + "background_agents_get_task_results", + "background_agents_get_all_tasks", + "background_agents_continue_task", + "background_agents_clear_completed_task", + ]; + + private const string ParentWithChildYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -45,8 +44,8 @@ public sealed class BackgroundCompilationTests - { id: done, agent: coder, terminal: true } """; - private const string ParentWithTodosAndChildYaml = - """ + private const string ParentWithTodosAndChildYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -63,61 +62,61 @@ public sealed class BackgroundCompilationTests - { id: done, agent: coder, terminal: true } """; - [Fact] - public void Compile_BackgroundWithAChild_GetsABackgroundAgentsProvider() - { - var compiled = Compile(ParentWithChildYaml); - - var parent = compiled.Agents["parent"].GetService(); - Assert.NotNull(parent); - Assert.Contains(parent.AIContextProviders ?? [], provider => provider is BackgroundAgentsProvider); - } - - [Fact] - public void Compile_NoBackground_GetsNoBackgroundAgentsProvider() - { - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = [new AgentConfiguration { Id = "only" }], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration { Agent = "only" }, - }, - }, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - - var agent = Assert.Single(compiled.Agents.Values).GetService(); - Assert.NotNull(agent); - Assert.DoesNotContain(agent.AIContextProviders ?? [], provider => provider is BackgroundAgentsProvider); - } - - [Fact] - public async Task Compile_BackgroundWithAChild_ModelSeesTheSixBackgroundTools() - { - using SequencedChatClient reply = new("hello there."); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ParentWithChildYaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - var agent = compiled.Agents["parent"]; - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); - - await agent.RunAsync("hi", session, cancellationToken: token); - - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - - Assert.Equal(ExpectedBackgroundTools, toolNames, StringComparer.Ordinal); - } - - private const string ParentWithDescribedChildYaml = - """ + [Fact] + public void Compile_BackgroundWithAChild_GetsABackgroundAgentsProvider() + { + CompiledAgent compiled = Compile(ParentWithChildYaml); + + ChatClientAgent? parent = compiled.Agents["parent"].GetService(); + Assert.NotNull(parent); + Assert.Contains(parent.AIContextProviders ?? [], provider => provider is BackgroundAgentsProvider); + } + + [Fact] + public void Compile_NoBackground_GetsNoBackgroundAgentsProvider() + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only" }], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "only" }, + }, + }, + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + + ChatClientAgent? agent = Assert.Single(compiled.Agents.Values).GetService(); + Assert.NotNull(agent); + Assert.DoesNotContain(agent.AIContextProviders ?? [], provider => provider is BackgroundAgentsProvider); + } + + [Fact] + public async Task Compile_BackgroundWithAChild_ModelSeesTheSixBackgroundTools() + { + using SequencedChatClient reply = new("hello there."); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ParentWithChildYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + + AIAgent agent = compiled.Agents["parent"]; + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); + + _ = await agent.RunAsync("hi", session, cancellationToken: token); + + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + + Assert.Equal(ExpectedBackgroundTools, toolNames, StringComparer.Ordinal); + } + + private const string ParentWithDescribedChildYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -134,55 +133,55 @@ public async Task Compile_BackgroundWithAChild_ModelSeesTheSixBackgroundTools() - { id: done, agent: coder, terminal: true } """; - [Fact] - public async Task Compile_BackgroundChildWithDescription_ModelSeesTheDescriptionBesideTheId() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public async Task Compile_BackgroundChildWithDescription_ModelSeesTheDescriptionBesideTheId() + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ParentWithDescribedChildYaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ParentWithDescribedChildYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - var agent = compiled.Agents["parent"]; - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); + AIAgent agent = compiled.Agents["parent"]; + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); - await agent.RunAsync("hi", session, cancellationToken: token); + _ = await agent.RunAsync("hi", session, cancellationToken: token); - var seen = string.Join( - '\n', - reply.Requests[^1].Select(message => message.Text).Prepend(reply.Options[^1]?.Instructions ?? string.Empty)); + string seen = string.Join( + '\n', + reply.Requests[^1].Select(message => message.Text).Prepend(reply.Options[^1]?.Instructions ?? string.Empty)); - Assert.Contains("- coder: write code fast", seen, StringComparison.Ordinal); - } + Assert.Contains("- coder: write code fast", seen, StringComparison.Ordinal); + } - [Fact] - public void Compile_BackgroundWithTodos_HarnessStateKeysIncludeTheBackgroundKey() - { - using SequencedChatClient childReply = new("hi"); - var backgroundKeys = new BackgroundAgentsProvider( - [new ChatClientAgent(childReply, new ChatClientAgentOptions { Name = "coder" })]).StateKeys; + [Fact] + public void Compile_BackgroundWithTodos_HarnessStateKeysIncludeTheBackgroundKey() + { + using SequencedChatClient childReply = new("hi"); + IReadOnlyList backgroundKeys = new BackgroundAgentsProvider( + [new ChatClientAgent(childReply, new ChatClientAgentOptions { Name = "coder" })]).StateKeys; - var compiled = Compile(ParentWithTodosAndChildYaml); - HashSet expected = [new TodoProvider().StateKeys[0]]; - expected.UnionWith(backgroundKeys); + CompiledAgent compiled = Compile(ParentWithTodosAndChildYaml); + HashSet expected = [new TodoProvider().StateKeys[0]]; + expected.UnionWith(backgroundKeys); - Assert.Equal(expected, compiled.HarnessStateKeys); - } + Assert.Equal(expected, compiled.HarnessStateKeys); + } - [Fact] - public void Compile_BackgroundChildDeclaredLater_ResolvesForward() - { - var compiled = Compile(ParentWithChildYaml); + [Fact] + public void Compile_BackgroundChildDeclaredLater_ResolvesForward() + { + CompiledAgent compiled = Compile(ParentWithChildYaml); - Assert.True(compiled.Agents.ContainsKey("coder")); - var parent = compiled.Agents["parent"].GetService(); - Assert.NotNull(parent); - Assert.Contains(parent.AIContextProviders ?? [], provider => provider is BackgroundAgentsProvider); - } + Assert.True(compiled.Agents.ContainsKey("coder")); + ChatClientAgent? parent = compiled.Agents["parent"].GetService(); + Assert.NotNull(parent); + Assert.Contains(parent.AIContextProviders ?? [], provider => provider is BackgroundAgentsProvider); + } - private const string UnknownChildYaml = - """ + private const string UnknownChildYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -192,28 +191,17 @@ public void Compile_BackgroundChildDeclaredLater_ResolvesForward() agent: parent """; - [Fact] - public void Compile_BackgroundUnknownChild_FailsNamingTheBackgroundPointer() - { - var failure = Assert.Throws(() => Compile(UnknownChildYaml)); + [Fact] + public void Compile_BackgroundUnknownChild_FailsNamingTheBackgroundPointer() + { + ConfigurationLoadException failure = Assert.Throws(() => Compile(UnknownChildYaml)); - Assert.Equal("/agents/items/0/background/0", failure.Pointer); - Assert.Contains("not declared in agents.items", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/0/background/0", failure.Pointer); + Assert.Contains("not declared in agents.items", failure.Message, StringComparison.Ordinal); + } - private const string SelfChildYaml = - """ - apiVersion: agentcore/v1 - agents: - items: - - { id: parent, instructions: "delegate work", background: [parent] } - entries: - main: - agent: parent - """; - - private const string CollidingChildYaml = - """ + private const string CollidingChildYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -231,16 +219,20 @@ public void Compile_BackgroundUnknownChild_FailsNamingTheBackgroundPointer() - { id: done, agent: coder, terminal: true } """; - [Fact] - public void Compile_BackgroundChildrenWithCollidingNames_FailsNamingTheBackgroundPointer() - { - var failure = Assert.Throws(() => Compile(CollidingChildYaml)); + [Fact] + public void Compile_BackgroundChildrenWithCollidingNames_FailsNamingTheBackgroundPointer() + { + ConfigurationLoadException failure = Assert.Throws(() => Compile(CollidingChildYaml)); - Assert.Equal("/agents/items/0/background", failure.Pointer); - } + Assert.Equal("/agents/items/0/background", failure.Pointer); + } - private static CompiledAgent Compile(string yaml) => ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - } - #pragma warning restore MAAI001 + private static CompiledAgent Compile(string yaml) + { + return ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + } + } +#pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ClarificationWiringBindingTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ClarificationWiringBindingTests.cs index bce285de..0da4b5ad 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/ClarificationWiringBindingTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ClarificationWiringBindingTests.cs @@ -11,19 +11,19 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Where the document's providers.knowledge ambiguity wiring becomes part of the agent's own -/// bound search. The wiring is document-level and the knowledge: block is per agent, so the -/// compiler is the only place the two meet. -/// -public sealed class ClarificationWiringBindingTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string ModelDescription = "The model, as printed on the machine."; + /// + /// Where the document's providers.knowledge ambiguity wiring becomes part of the agent's own + /// bound search. The wiring is document-level and the knowledge: block is per agent, so the + /// compiler is the only place the two meet. + /// + public sealed class ClarificationWiringBindingTests + { + private const string ModelDescription = "The model, as printed on the machine."; - private const string WiredYaml = - """ + private const string WiredYaml = + """ apiVersion: agentcore/v1 state: model: @@ -59,176 +59,186 @@ public sealed class ClarificationWiringBindingTests agent: only """; - [Fact] - public async Task TheDocumentsAmbiguityWiring_ReachesTheAgentsOwnBoundSearch() - { - // Every gate in the probe's own preamble reads one member of the wiring the compiler - // carries across: drop any of ambiguity, wildcard.value, wildcard.facets, scope.template or - // fromState on the way, and this note collapses into the bare "holds nothing" notice. - var port = new ScopedFakePort(); - var turn = new TurnInvocation + [Fact] + public async Task TheDocumentsAmbiguityWiring_ReachesTheAgentsOwnBoundSearch() { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Knowledge = Scope(model: "*", audience: "everyone"), - Clarifications = new Clarifications(), - }; + // Every gate in the probe's own preamble reads one member of the wiring the compiler + // carries across: drop any of ambiguity, wildcard.value, wildcard.facets, scope.template or + // fromState on the way, and this note collapses into the bare "holds nothing" notice. + ScopedFakePort port = new(); + TurnInvocation turn = new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Knowledge = Scope(model: "*", audience: "everyone"), + Clarifications = new Clarifications(), + }; - var note = await SearchAsync(CompileTheSearchProvider(port), "belt slipping", turn); + string note = await SearchAsync(CompileTheSearchProvider(port), "belt slipping", turn); - Assert.Contains("It could be: e33, f63", note, StringComparison.Ordinal); - Assert.Equal(2, port.Calls); - } + Assert.Contains("It could be: e33, f63", note, StringComparison.Ordinal); + Assert.Equal(2, port.Calls); + } - [Fact] - public async Task TheSlotsOwnDescription_ReachesTheNoteTheProbeWrites() - { - // The description lives under state:, not under providers.knowledge, so it reaches the probe - // only because the compiler joined the two. Losing it degrades the ask to the bare slot name. - var port = new ScopedFakePort(); - var turn = new TurnInvocation + [Fact] + public async Task TheSlotsOwnDescription_ReachesTheNoteTheProbeWrites() { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Knowledge = Scope(model: "*", audience: "everyone"), - Clarifications = new Clarifications(), - }; + // The description lives under state:, not under providers.knowledge, so it reaches the probe + // only because the compiler joined the two. Losing it degrades the ask to the bare slot name. + ScopedFakePort port = new(); + TurnInvocation turn = new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Knowledge = Scope(model: "*", audience: "everyone"), + Clarifications = new Clarifications(), + }; - var note = await SearchAsync(CompileTheSearchProvider(port), "belt slipping", turn); + string note = await SearchAsync(CompileTheSearchProvider(port), "belt slipping", turn); - Assert.Contains(ModelDescription, note, StringComparison.Ordinal); - Assert.DoesNotContain("known: model ", note, StringComparison.Ordinal); - } + Assert.Contains(ModelDescription, note, StringComparison.Ordinal); + Assert.DoesNotContain("known: model ", note, StringComparison.Ordinal); + } - private static FacetFilterProvider CompileTheSearchProvider(IKnowledgeRetrievalPort port) - { - using SequencedChatClient reply = new("hello there."); + private static FacetFilterProvider CompileTheSearchProvider(IKnowledgeRetrievalPort port) + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(WiredYaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port })["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(WiredYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port })["main"]; - return Assert.Single(Providers(compiled.Agents["only"]).OfType()); - } + return Assert.Single(Providers(compiled.Agents["only"]).OfType()); + } - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); - return inner.AIContextProviders ?? []; - } + return inner.AIContextProviders ?? []; + } - private static KnowledgeScope Scope(string model, string audience) - => new() + private static KnowledgeScope Scope(string model, string audience) { - Facets = new Dictionary(StringComparer.Ordinal) + return new() { - ["model"] = model, - ["audience"] = audience, - }, - }; + Facets = new Dictionary(StringComparer.Ordinal) + { + ["model"] = model, + ["audience"] = audience, + }, + }; + } - /// The one notice the bound search returned, as text. - private static async Task SearchAsync(AIContextProvider provider, string query, TurnInvocation turn) - { - StubSession session = new(); - var context = await provider.InvokingAsync( - Invoking("hello", session), TestContext.Current.CancellationToken).ConfigureAwait(false); - var search = Assert.Single(context.Tools!, tool => tool.Name == "Search"); - var results = await ((AIFunction)search).InvokeAsync( - turn.FileIn(new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) - { - ["userQuestion"] = query, - })), - TestContext.Current.CancellationToken).ConfigureAwait(false) - as IReadOnlyList; - return Assert.Single(results!).Text; - } + /// The one notice the bound search returned, as text. + private static async Task SearchAsync(AIContextProvider provider, string query, TurnInvocation turn) + { + StubSession session = new(); + AIContext context = await provider.InvokingAsync( + Invoking("hello", session), TestContext.Current.CancellationToken).ConfigureAwait(false); + AITool search = Assert.Single(context.Tools!, tool => tool.Name == "Search"); + IReadOnlyList? results = await ((AIFunction)search).InvokeAsync( + turn.FileIn(new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) + { + ["userQuestion"] = query, + })), + TestContext.Current.CancellationToken).ConfigureAwait(false) + as IReadOnlyList; + return Assert.Single(results!).Text; + } - /// Runs the provider the way the framework runs it, over one caller message. - private static AIContextProvider.InvokingContext Invoking(string text, AgentSession session) - { + /// Runs the provider the way the framework runs it, over one caller message. + private static AIContextProvider.InvokingContext Invoking(string text, AgentSession session) + { #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - return new( - StubAgent.Instance, - session, - new AIContext { Messages = [new ChatMessage(ChatRole.User, text)] }); + return new( + StubAgent.Instance, + session, + new AIContext { Messages = [new ChatMessage(ChatRole.User, text)] }); #pragma warning restore MAAI001 - } + } - private sealed class StubSession : AgentSession; + private sealed class StubSession : AgentSession; - /// Stands in for the agent the framework names on a context. Nothing here runs it. - private sealed class StubAgent : AIAgent - { - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - } + /// Stands in for the agent the framework names on a context. Nothing here runs it. + private sealed class StubAgent : AIAgent + { + public static StubAgent Instance { get; } = new(); - /// - /// A store that answers nothing while model is still in the scope, and names two models - /// once the probe has dropped it — the shape §8 exists to resolve. - /// - private sealed class ScopedFakePort : IKnowledgeRetrievalPort - { - internal int Calls { get; private set; } + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) + { + return new(new StubSession()); + } - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - { - Calls++; + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - var facets = scope?.Facets; - if (facets is null || facets.ContainsKey("model")) + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) { - return new([]); + throw new NotSupportedException(); } - return new([Card("a", "e33"), Card("b", "f63")]); + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } } - private static KnowledgeCard Card(string id, string model) - => new() + /// + /// A store that answers nothing while model is still in the scope, and names two models + /// once the probe has dropped it — the shape §8 exists to resolve. + /// + private sealed class ScopedFakePort : IKnowledgeRetrievalPort + { + internal int Calls { get; private set; } + + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) { - CardId = id, - Text = "card " + id, - ViaLink = false, - Extras = new Dictionary(StringComparer.Ordinal) + Calls++; + + IReadOnlyDictionary? facets = scope?.Facets; + return facets is null || facets.ContainsKey("model") ? new([]) : new([Card("a", "e33"), Card("b", "f63")]); + } + + private static KnowledgeCard Card(string id, string model) + { + return new() { - ["facets"] = new Dictionary(StringComparer.Ordinal) { ["model"] = model }, - }, - }; + CardId = id, + Text = "card " + id, + ViaLink = false, + Extras = new Dictionary(StringComparer.Ordinal) + { + ["facets"] = new Dictionary(StringComparer.Ordinal) { ["model"] = model }, + }, + }; + } + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs index be773889..af24ae94 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs @@ -6,23 +6,24 @@ using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; using AgentCore.Domain.Sources; +using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Compaction reaching a compiled agent's context providers, and the trimming reaching the model. -/// The block itself is D15's ledger: in -/// Runtime covers the stages and the unknown-model compile failure. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class CompactionCompilationTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - [Fact] - public void Compile_ADocumentThatStillWritesCompaction_FailsSchemaValidationLikeAnyUnknownKey() + /// + /// Compaction reaching a compiled agent's context providers, and the trimming reaching the model. + /// The block itself is D15's ledger: in + /// Runtime covers the stages and the unknown-model compile failure. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class CompactionCompilationTests { - const string document = """ + [Fact] + public void Compile_ADocumentThatStillWritesCompaction_FailsSchemaValidationLikeAnyUnknownKey() + { + const string document = """ apiVersion: agentcore/v1 agents: defaults: @@ -34,61 +35,65 @@ public void Compile_ADocumentThatStillWritesCompaction_FailsSchemaValidationLike agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains("compaction", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("compaction", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task Compile_AnAgent_KeepsReaderContentOutOfTheModelRequest() - { - using SequencedChatClient reply = new("noted."); - var compiled = CompileOneAgent(reply); - var agent = Assert.Single(compiled.Agents.Values); - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); - - ChatMessage published = new(ChatRole.Tool, [new FunctionResultContent("call-1", "published")]); - published.Contents.Add(new FileContent { Name = "report.md", FileId = "out/report.md", Kept = true }); - published.Contents.Add(new RenderContent + [Fact] + public async Task Compile_AnAgent_KeepsReaderContentOutOfTheModelRequest() { - Name = "card", - RenderId = "card-1", - Data = JsonSerializer.SerializeToElement(new { title = "Report" }), - }); - published.Contents.Add(new SourceContent - { - Source = new SourceReference { SourceId = "doc-1", Kind = SourceKind.Document, Title = "Doc", Origin = "knowledge" }, - CallId = "call-1", - }); - List conversation = - [ - new ChatMessage(ChatRole.User, "make me a report"), - new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call-1", "file.publish")]), - published, - new ChatMessage(ChatRole.User, "thanks"), - ]; + using SequencedChatClient reply = new("noted."); + CompiledAgent compiled = CompileOneAgent(reply); + AIAgent agent = Assert.Single(compiled.Agents.Values); + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); - await agent.RunAsync(conversation, session, cancellationToken: token); + ChatMessage published = new(ChatRole.Tool, [new FunctionResultContent("call-1", "published")]); + published.Contents.Add(new FileContent { Name = "report.md", FileId = "out/report.md", Kept = true }); + published.Contents.Add(new RenderContent + { + Name = "card", + RenderId = "card-1", + Data = JsonSerializer.SerializeToElement(new { title = "Report" }), + }); + published.Contents.Add(new SourceContent + { + Source = new SourceReference { SourceId = "doc-1", Kind = SourceKind.Document, Title = "Doc", Origin = "knowledge" }, + CallId = "call-1", + }); + List conversation = + [ + new ChatMessage(ChatRole.User, "make me a report"), + new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call-1", "file.publish")]), + published, + new ChatMessage(ChatRole.User, "thanks"), + ]; - Assert.DoesNotContain( - reply.Requests[^1].SelectMany(message => message.Contents), - content => content is FileContent or RenderContent or SourceContent); - } + _ = await agent.RunAsync(conversation, session, cancellationToken: token); - private static CompiledAgent CompileOneAgent(SequencedChatClient reply) => ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration + Assert.DoesNotContain( + reply.Requests[^1].SelectMany(message => message.Contents), + content => content is FileContent or RenderContent or SourceContent); + } + + private static CompiledAgent CompileOneAgent(SequencedChatClient reply) { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = [new AgentConfiguration { Id = "only" }], - }, - Entries = new Dictionary + return ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - ["main"] = new EntryConfiguration { Agent = "only" }, + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only" }], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "only" }, + }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; -} + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + } + } #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs index 875bf17e..c745cab0 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompileTableTests.cs @@ -6,15 +6,15 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The five rows of the section 8.2 compile table. The compiler is a table, not a heuristic. -/// -public sealed class CompileTableTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - internal const string OneAgentYaml = - """ + /// + /// The five rows of the section 8.2 compile table. The compiler is a table, not a heuristic. + /// + public sealed class CompileTableTests + { + internal const string OneAgentYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -28,8 +28,8 @@ the stable cached prefix agent: only """; - private const string PolicyAndGraphYaml = - """ + private const string PolicyAndGraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -47,12 +47,12 @@ the stable cached prefix agents: [ first, second ] """; - /// The agents.defaults.instructions of . - private const string SharedPrefix = "the stable cached prefix"; + /// The agents.defaults.instructions of . + private const string SharedPrefix = "the stable cached prefix"; - /// Two agents, one shared prefix, and a delta on each of them. - private const string SharedPrefixYaml = - """ + /// Two agents, one shared prefix, and a delta on each of them. + private const string SharedPrefixYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -69,8 +69,8 @@ the stable cached prefix agents: [ greeter, closer ] """; - private const string PatternYaml = - """ + private const string PatternYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -83,8 +83,8 @@ the stable cached prefix agents: [ first, second ] """; - internal const string ExplicitGraphYaml = - """ + internal const string ExplicitGraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -99,154 +99,154 @@ the stable cached prefix edges: - { from: start, to: finish } """; - [Fact] - public void Row1_OneAgentAndNoRuntime_IsTheSingleAgentShape() - { - var document = ConfigurationLoader.LoadYaml(OneAgentYaml); - Assert.Equal(CompiledAgentShape.SingleAgent, ConfigurationCompiler.SelectEntryRow(document.Entries["main"], "/entries/main").Shape); - } - - [Fact] - public void Row1_CompilesToAChatClientAgentInstrumentedForOpenTelemetry() - { - var compiled = Compile(OneAgentYaml); - - // Task 6a wraps every compiled agent for OpenTelemetry exactly once (ConfigurationCompiler's - // Resolve, the single place agents are built and cached). compiled.Agent is therefore the - // OpenTelemetryAgent, not the ChatClientAgent underneath it — GetService is how a caller, - // and this test, reaches through a DelegatingAIAgent to what it wraps. - Assert.IsType(compiled.Agent); - Assert.IsType(compiled.Agent.GetService()); - Assert.Equal("only", compiled.Agent.Name); - } - - [Fact] - public void Row2_AgentsPlusPolicy_IsThePolicyShape() - { - var document = ConfigurationLoader.LoadYaml(Tests.Configuration.ExampleDocument.Yaml); - Assert.Equal(CompiledAgentShape.Policy, ConfigurationCompiler.SelectEntryRow(document.Entries["phone"], "/entries/phone").Shape); - } + [Fact] + public void Row1_OneAgentAndNoRuntime_IsTheSingleAgentShape() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(OneAgentYaml); + Assert.Equal(CompiledAgentShape.SingleAgent, ConfigurationCompiler.SelectEntryRow(document.Entries["main"], "/entries/main").Shape); + } - [Fact] - public void Row2_TheSection81Example_Compiles() - { - var compiled = Compile(Tests.Configuration.ExampleDocument.Yaml, "phone"); + [Fact] + public void Row1_CompilesToAChatClientAgentInstrumentedForOpenTelemetry() + { + CompiledAgent compiled = Compile(OneAgentYaml); + + // Task 6a wraps every compiled agent for OpenTelemetry exactly once (ConfigurationCompiler's + // Resolve, the single place agents are built and cached). compiled.Agent is therefore the + // OpenTelemetryAgent, not the ChatClientAgent underneath it — GetService is how a caller, + // and this test, reaches through a DelegatingAIAgent to what it wraps. + _ = Assert.IsType(compiled.Agent); + _ = Assert.IsType(compiled.Agent.GetService()); + Assert.Equal("only", compiled.Agent.Name); + } + + [Fact] + public void Row2_AgentsPlusPolicy_IsThePolicyShape() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + Assert.Equal(CompiledAgentShape.Policy, ConfigurationCompiler.SelectEntryRow(document.Entries["phone"], "/entries/phone").Shape); + } - Assert.Equal(CompiledAgentShape.Policy, compiled.Shape); - // 5 agents on the stage machine, plus analyst and webchat, which policy: never reaches. - Assert.Equal(7, compiled.Agents.Count); + [Fact] + public void Row2_TheSection81Example_Compiles() + { + CompiledAgent compiled = Compile(ExampleDocument.Yaml, "phone"); - // The initial stage is greeting, and greeting names greeter. - Assert.Equal("greeter", compiled.Agent.Name); - Assert.Equal("resolver", compiled.ForStage("resolve")!.Name); - Assert.Equal("closer", compiled.ForStage("close")!.Name); - } + Assert.Equal(CompiledAgentShape.Policy, compiled.Shape); + // 5 agents on the stage machine, plus analyst and webchat, which policy: never reaches. + Assert.Equal(7, compiled.Agents.Count); - [Fact] - public void Row2_KnowsEveryStageOfTheExample() - { - var compiled = Compile(Tests.Configuration.ExampleDocument.Yaml, "phone"); + // The initial stage is greeting, and greeting names greeter. + Assert.Equal("greeter", compiled.Agent.Name); + Assert.Equal("resolver", compiled.ForStage("resolve")!.Name); + Assert.Equal("closer", compiled.ForStage("close")!.Name); + } - Assert.Throws(() => compiled.ForStage("nowhere")); - } + [Fact] + public void Row2_KnowsEveryStageOfTheExample() + { + CompiledAgent compiled = Compile(ExampleDocument.Yaml, "phone"); - [Fact] - public void Row3_GraphWithAPattern_IsThePatternGraphShape() - { - var document = ConfigurationLoader.LoadYaml(PatternYaml); - Assert.Equal(CompiledAgentShape.PatternGraph, ConfigurationCompiler.SelectEntryRow(document.Entries["main"], "/entries/main").Shape); - } + _ = Assert.Throws(() => compiled.ForStage("nowhere")); + } - [Theory] - [InlineData("sequential")] - [InlineData("concurrent")] - [InlineData("handoff")] - [InlineData("group_chat")] - public void Row3_EveryPattern_CompilesThroughAgentWorkflowBuilder(string pattern) - { - var yaml = PatternYaml.Replace("pattern: sequential", "pattern: " + pattern, StringComparison.Ordinal); + [Fact] + public void Row3_GraphWithAPattern_IsThePatternGraphShape() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(PatternYaml); + Assert.Equal(CompiledAgentShape.PatternGraph, ConfigurationCompiler.SelectEntryRow(document.Entries["main"], "/entries/main").Shape); + } + + [Theory] + [InlineData("sequential")] + [InlineData("concurrent")] + [InlineData("handoff")] + [InlineData("group_chat")] + public void Row3_EveryPattern_CompilesThroughAgentWorkflowBuilder(string pattern) + { + string yaml = PatternYaml.Replace("pattern: sequential", "pattern: " + pattern, StringComparison.Ordinal); - var compiled = Compile(yaml); + CompiledAgent compiled = Compile(yaml); - Assert.Equal(CompiledAgentShape.PatternGraph, compiled.Shape); - Assert.Equal("main", compiled.Agent.Name); - } + Assert.Equal(CompiledAgentShape.PatternGraph, compiled.Shape); + Assert.Equal("main", compiled.Agent.Name); + } - [Fact] - public void Row4_GraphWithNodesAndEdges_IsTheExplicitGraphShape() - { - var document = ConfigurationLoader.LoadYaml(ExplicitGraphYaml); - Assert.Equal(CompiledAgentShape.ExplicitGraph, ConfigurationCompiler.SelectEntryRow(document.Entries["main"], "/entries/main").Shape); - } + [Fact] + public void Row4_GraphWithNodesAndEdges_IsTheExplicitGraphShape() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExplicitGraphYaml); + Assert.Equal(CompiledAgentShape.ExplicitGraph, ConfigurationCompiler.SelectEntryRow(document.Entries["main"], "/entries/main").Shape); + } - [Fact] - public void Row4_CompilesThroughWorkflowBuilderAndAsAIAgent() - { - var compiled = Compile(ExplicitGraphYaml); + [Fact] + public void Row4_CompilesThroughWorkflowBuilderAndAsAIAgent() + { + CompiledAgent compiled = Compile(ExplicitGraphYaml); - Assert.Equal(CompiledAgentShape.ExplicitGraph, compiled.Shape); - Assert.Equal("main", compiled.Agent.Name); - Assert.IsNotType(compiled.Agent); - } + Assert.Equal(CompiledAgentShape.ExplicitGraph, compiled.Shape); + Assert.Equal("main", compiled.Agent.Name); + Assert.IsNotType(compiled.Agent); + } - [Fact] - public void Row4_AGraphWithoutOneStartNode_IsALoadTimeError() - { - var yaml = ExplicitGraphYaml.Replace("{ id: start, agent: first, start: true }", "{ id: start, agent: first }", StringComparison.Ordinal); + [Fact] + public void Row4_AGraphWithoutOneStartNode_IsALoadTimeError() + { + string yaml = ExplicitGraphYaml.Replace("{ id: start, agent: first, start: true }", "{ id: start, agent: first }", StringComparison.Ordinal); - var failure = Assert.Throws(() => Compile(yaml)); + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); - Assert.Equal("/entries/main/graph/nodes", failure.Pointer); - Assert.Contains("start nodes", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/entries/main/graph/nodes", failure.Pointer); + Assert.Contains("start nodes", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Row4_AGuardedEdgeWithNoEvaluator_IsALoadTimeError() - { - var yaml = ExplicitGraphYaml.Replace( - "- { from: start, to: finish }", - "- { from: start, to: finish, when: always }", - StringComparison.Ordinal) - + "\nguards:\n always: { \"===\": [ 1, 1 ] }\n"; + [Fact] + public void Row4_AGuardedEdgeWithNoEvaluator_IsALoadTimeError() + { + string yaml = ExplicitGraphYaml.Replace( + "- { from: start, to: finish }", + "- { from: start, to: finish, when: always }", + StringComparison.Ordinal) + + "\nguards:\n always: { \"===\": [ 1, 1 ] }\n"; - var failure = Assert.Throws(() => Compile(yaml)); + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); - Assert.Equal("/entries/main/graph/edges/0/when", failure.Pointer); - } + Assert.Equal("/entries/main/graph/edges/0/when", failure.Pointer); + } - [Fact] - public void Row5_BothPolicyAndGraph_IsRejectedWhenTheDocumentLoads() - { - // Check 1 of section 8.5 already refuses the shape, so the document never reaches the table. - Assert.Throws(() => ConfigurationLoader.LoadYaml(PolicyAndGraphYaml)); - } + [Fact] + public void Row5_BothPolicyAndGraph_IsRejectedWhenTheDocumentLoads() + { + // Check 1 of section 8.5 already refuses the shape, so the document never reaches the table. + _ = Assert.Throws(() => ConfigurationLoader.LoadYaml(PolicyAndGraphYaml)); + } - [Fact] - public void Row5_BothPolicyAndGraph_IsALoadTimeErrorInTheTableToo() - { - // The same rule again, against a record built in code. Row 5 is a rule of the table, and not - // only a rule of the JSON Schema. - var document = ConfigurationLoader.LoadYaml(Tests.Configuration.ExampleDocument.Yaml); - var both = document.Entries["phone"] with + [Fact] + public void Row5_BothPolicyAndGraph_IsALoadTimeErrorInTheTableToo() { - Graph = new GraphConfiguration + // The same rule again, against a record built in code. Row 5 is a rule of the table, and not + // only a rule of the JSON Schema. + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + EntryConfiguration both = document.Entries["phone"] with { - Pattern = GraphPattern.Sequential, - Agents = ["greeter", "closer"], - }, - }; + Graph = new GraphConfiguration + { + Pattern = GraphPattern.Sequential, + Agents = ["greeter", "closer"], + }, + }; - var failure = Assert.Throws(() => ConfigurationCompiler.SelectEntryRow(both, "/entries/phone")); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.SelectEntryRow(both, "/entries/phone")); - Assert.Equal("/entries/phone", failure.Pointer); - Assert.Contains("two of agent:, policy:, and graph:", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/entries/phone", failure.Pointer); + Assert.Contains("two of agent:, policy:, and graph:", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void TwoAgentsAndNoRuntime_IsALoadTimeError() - { - var yaml = - """ + [Fact] + public void TwoAgentsAndNoRuntime_IsALoadTimeError() + { + string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -256,17 +256,17 @@ public void TwoAgentsAndNoRuntime_IsALoadTimeError() main: {} """; - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml(yaml)); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml(yaml)); - Assert.Equal("/entries/main", failure.Pointer); - } + Assert.Equal("/entries/main", failure.Pointer); + } - [Fact] - public void ADocumentWithNothingToCompile_IsALoadTimeError() - { - var yaml = - """ + [Fact] + public void ADocumentWithNothingToCompile_IsALoadTimeError() + { + string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -275,16 +275,16 @@ public void ADocumentWithNothingToCompile_IsALoadTimeError() main: {} """; - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml(yaml)); - Assert.Equal("/entries/main", failure.Pointer); - } + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml(yaml)); + Assert.Equal("/entries/main", failure.Pointer); + } - [Fact] - public void AStageThatNamesAnUndeclaredAgent_IsALoadTimeError() - { - var yaml = - """ + [Fact] + public void AStageThatNamesAnUndeclaredAgent_IsALoadTimeError() + { + string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -298,16 +298,16 @@ public void AStageThatNamesAnUndeclaredAgent_IsALoadTimeError() - { id: two, agent: nobody, terminal: true } """; - var failure = Assert.Throws(() => Compile(yaml)); + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); - Assert.Equal("/entries/main/policy/stages/1/agent", failure.Pointer); - } + Assert.Equal("/entries/main/policy/stages/1/agent", failure.Pointer); + } - [Fact] - public void AnInitialStageThatNamesNoAgent_IsALoadTimeError() - { - var yaml = - """ + [Fact] + public void AnInitialStageThatNamesNoAgent_IsALoadTimeError() + { + string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -320,98 +320,99 @@ public void AnInitialStageThatNamesNoAgent_IsALoadTimeError() - { id: one, terminal: true } """; - var failure = Assert.Throws(() => Compile(yaml)); + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); - Assert.Equal("/entries/main/policy/initial", failure.Pointer); - } + Assert.Equal("/entries/main/policy/initial", failure.Pointer); + } - [Fact] - public void TheCachedPrefix_SitsAboveTheStageDelta() - { - var document = ConfigurationLoader.LoadYaml(OneAgentYaml); - - var composed = AgentInstructions.Compose(document.Agents!.Defaults, document.Agents.Items[0]); - - Assert.Equal( - AgentInstructions.Base + AgentInstructions.Separator - + "the stable cached prefix" + AgentInstructions.Separator + "the stage delta", - composed); - Assert.StartsWith(AgentInstructions.Base, composed, StringComparison.Ordinal); - } - - [Fact] - public void TheBase_SitsAboveThePrefix_AndBaseInstructionsFalseDropsIt() - { - AgentDefaults defaults = new() { Instructions = "prefix" }; - AgentConfiguration agent = new() { Id = "solo", Instructions = "delta" }; - - Assert.Equal( - AgentInstructions.Base + AgentInstructions.Separator + "prefix" + AgentInstructions.Separator + "delta", - AgentInstructions.Compose(defaults, agent)); - Assert.Equal( - "prefix" + AgentInstructions.Separator + "delta", - AgentInstructions.Compose(defaults with { BaseInstructions = false }, agent)); - Assert.Equal( - "prefix" + AgentInstructions.Separator + "delta", - AgentInstructions.Compose(defaults, agent with { BaseInstructions = false })); - Assert.Equal(AgentInstructions.Base, AgentInstructions.Compose(null, new AgentConfiguration { Id = "bare" })); - } + [Fact] + public void TheCachedPrefix_SitsAboveTheStageDelta() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(OneAgentYaml); - [Fact] - public void AnAgentWithNoDelta_KeepsThePrefixAlone() - { - AgentDefaults defaults = new() { Instructions = "prefix", BaseInstructions = false }; - AgentConfiguration agent = new() { Id = "solo" }; + string? composed = AgentInstructions.Compose(document.Agents!.Defaults, document.Agents.Items[0]); - Assert.Equal("prefix", AgentInstructions.Compose(defaults, agent)); - Assert.Equal("delta", AgentInstructions.Compose(null, agent with { Instructions = "delta", BaseInstructions = false })); - Assert.Null(AgentInstructions.Compose(null, agent with { BaseInstructions = false })); - } + Assert.Equal( + AgentInstructions.Base + AgentInstructions.Separator + + "the stable cached prefix" + AgentInstructions.Separator + "the stage delta", + composed); + Assert.StartsWith(AgentInstructions.Base, composed, StringComparison.Ordinal); + } - [Fact] - public void EveryCompiledAgent_CarriesTheCachedPrefixAboveItsOwnDelta() - { - var compiled = Compile(SharedPrefixYaml); - - var greeter = compiled.Agents["greeter"].GetService(); - var closer = compiled.Agents["closer"].GetService(); - Assert.NotNull(greeter); - Assert.NotNull(closer); - - // Section 8.1 makes agents.defaults.instructions a cached prefix, and the compiler has one - // build path for every agent. This asserts that path and not AgentInstructions.Compose: an - // agent the compiler built without the prefix would defeat the cache for every later turn. - var above = AgentInstructions.Base + AgentInstructions.Separator + SharedPrefix + AgentInstructions.Separator; - Assert.Equal(above + "the greeter delta", greeter.Instructions); - Assert.Equal(above + "the closer delta", closer.Instructions); - Assert.StartsWith(AgentInstructions.Base, greeter.Instructions, StringComparison.Ordinal); - Assert.StartsWith(AgentInstructions.Base, closer.Instructions, StringComparison.Ordinal); - } + [Fact] + public void TheBase_SitsAboveThePrefix_AndBaseInstructionsFalseDropsIt() + { + AgentDefaults defaults = new() { Instructions = "prefix" }; + AgentConfiguration agent = new() { Id = "solo", Instructions = "delta" }; + + Assert.Equal( + AgentInstructions.Base + AgentInstructions.Separator + "prefix" + AgentInstructions.Separator + "delta", + AgentInstructions.Compose(defaults, agent)); + Assert.Equal( + "prefix" + AgentInstructions.Separator + "delta", + AgentInstructions.Compose(defaults with { BaseInstructions = false }, agent)); + Assert.Equal( + "prefix" + AgentInstructions.Separator + "delta", + AgentInstructions.Compose(defaults, agent with { BaseInstructions = false })); + Assert.Equal(AgentInstructions.Base, AgentInstructions.Compose(null, new AgentConfiguration { Id = "bare" })); + } + + [Fact] + public void AnAgentWithNoDelta_KeepsThePrefixAlone() + { + AgentDefaults defaults = new() { Instructions = "prefix", BaseInstructions = false }; + AgentConfiguration agent = new() { Id = "solo" }; - [Fact] - public void EveryAgent_TakesTheModelTheDocumentNames() - { - var document = ConfigurationLoader.LoadYaml(Tests.Configuration.ExampleDocument.Yaml); - using ScriptedChatClient client = new("ok"); - FakeChatClientFactory factory = new(client); - - _ = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(factory) { Knowledge = new StubKnowledgePort([]) })["phone"]; - - // 5 agents on the stage machine, plus analyst and webchat, which policy: never reaches. Each - // asks the factory twice: once for the compaction pipeline's summariser, once for its own - // ChatClientAgent. - Assert.Equal(14, factory.Requested.Count); - Assert.All(factory.Requested, model => Assert.Equal("reply", model!.Ref)); - } + Assert.Equal("prefix", AgentInstructions.Compose(defaults, agent)); + Assert.Equal("delta", AgentInstructions.Compose(null, agent with { Instructions = "delta", BaseInstructions = false })); + Assert.Null(AgentInstructions.Compose(null, agent with { BaseInstructions = false })); + } - internal static CompiledAgent Compile(string yaml, string entryName = "main") - { - var document = ConfigurationLoader.LoadYaml(yaml); - var client = new ScriptedChatClient("ok"); - return ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(client)) { Knowledge = new StubKnowledgePort([]) })[entryName]; + [Fact] + public void EveryCompiledAgent_CarriesTheCachedPrefixAboveItsOwnDelta() + { + CompiledAgent compiled = Compile(SharedPrefixYaml); + + ChatClientAgent? greeter = compiled.Agents["greeter"].GetService(); + ChatClientAgent? closer = compiled.Agents["closer"].GetService(); + Assert.NotNull(greeter); + Assert.NotNull(closer); + + // Section 8.1 makes agents.defaults.instructions a cached prefix, and the compiler has one + // build path for every agent. This asserts that path and not AgentInstructions.Compose: an + // agent the compiler built without the prefix would defeat the cache for every later turn. + string above = AgentInstructions.Base + AgentInstructions.Separator + SharedPrefix + AgentInstructions.Separator; + Assert.Equal(above + "the greeter delta", greeter.Instructions); + Assert.Equal(above + "the closer delta", closer.Instructions); + Assert.StartsWith(AgentInstructions.Base, greeter.Instructions, StringComparison.Ordinal); + Assert.StartsWith(AgentInstructions.Base, closer.Instructions, StringComparison.Ordinal); + } + + [Fact] + public void EveryAgent_TakesTheModelTheDocumentNames() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + using ScriptedChatClient client = new("ok"); + FakeChatClientFactory factory = new(client); + + _ = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(factory) { Knowledge = new StubKnowledgePort([]) })["phone"]; + + // 5 agents on the stage machine, plus analyst and webchat, which policy: never reaches. Each + // asks the factory twice: once for the compaction pipeline's summariser, once for its own + // ChatClientAgent. + Assert.Equal(14, factory.Requested.Count); + Assert.All(factory.Requested, model => Assert.Equal("reply", model!.Ref)); + } + + internal static CompiledAgent Compile(string yaml, string entryName = "main") + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + ScriptedChatClient client = new("ok"); + return ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(client)) { Knowledge = new StubKnowledgePort([]) })[entryName]; + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentConcurrencyTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentConcurrencyTests.cs index 0b5efd2c..70fb3d76 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentConcurrencyTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentConcurrencyTests.cs @@ -1,94 +1,96 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Tests.Fakes; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Rule 16 of section 11, and T44. A fan-out of 26 simultaneous conversations against one compiled agent is -/// clean, and no code path compiles an agent for each conversation. -/// -public sealed class CompiledAgentConcurrencyTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const int FanOut = 26; - - [Fact] - public async Task Rule16_TwentySixSimultaneousConversations_ShareOneCompiledAgent() - { - using ScriptedChatClient client = new("Hello", " from", " one", " agent."); - var document = ConfigurationLoader.LoadYaml(CompileTableTests.OneAgentYaml); - AgentCompilationContext context = new(new FakeChatClientFactory(client)); - CompiledAgentRegistry registry = new(); - - var token = TestContext.Current.CancellationToken; - using Barrier gate = new(FanOut); - - var runs = Enumerable.Range(0, FanOut).Select(index => Task.Run( - async () => - { - // Every conversation asks the registry for the agent, exactly as the turn loop does. - var compiled = registry.GetOrCompile(document, "main", context); - - // Nothing starts until all 26 are ready, so the fan-out is really simultaneous. - gate.SignalAndWait(token); - - var reply = await compiled.Agent.RunAsync($"conversation {index}", cancellationToken: token) - .ConfigureAwait(false); - return (compiled, reply.Text); - }, - token)); - - var results = await Task.WhenAll(runs); - - // No code path compiles an agent for each conversation. The compiled agent is a process singleton. - Assert.Equal(1, registry.CompileCount); - Assert.All(results, result => Assert.Same(results[0].compiled, result.compiled)); - Assert.All(results, result => Assert.Equal(client.FullText, result.Text)); - Assert.Equal(FanOut, client.Calls); - } - - [Fact] - public async Task Rule16_TwentySixSimultaneousConversations_AreCleanAgainstOneGraphWrapper() + /// + /// Rule 16 of section 11, and T44. A fan-out of 26 simultaneous conversations against one compiled agent is + /// clean, and no code path compiles an agent for each conversation. + /// + public sealed class CompiledAgentConcurrencyTests { - using ScriptedChatClient client = new("Hello", " from", " the", " graph."); - var document = ConfigurationLoader.LoadYaml(CompileTableTests.ExplicitGraphYaml); - AgentCompilationContext context = new(new FakeChatClientFactory(client)); - CompiledAgentRegistry registry = new(); - - var token = TestContext.Current.CancellationToken; - var compiled = registry.GetOrCompile(document, "main", context); - using Barrier gate = new(FanOut); - - var runs = Enumerable.Range(0, FanOut).Select(index => Task.Run( - async () => - { - gate.SignalAndWait(token); - var reply = await compiled.Agent.RunAsync($"conversation {index}", cancellationToken: token) - .ConfigureAwait(false); - return reply.Text; - }, - token)); - - var texts = await Task.WhenAll(runs); - - // T44: nothing serializes inside the AsAIAgent() wrapper, so one wrapper serves every conversation. - Assert.Equal(1, registry.CompileCount); - Assert.All(texts, text => Assert.Contains("graph.", text, StringComparison.Ordinal)); - } - - [Fact] - public void Rule16_TheRegistryCompilesOncePerDocument() - { - using ScriptedChatClient client = new("ok"); - var document = ConfigurationLoader.LoadYaml(CompileTableTests.OneAgentYaml); - AgentCompilationContext context = new(new FakeChatClientFactory(client)); - CompiledAgentRegistry registry = new(); - - var first = registry.GetOrCompile(document, "main", context); - var second = registry.GetOrCompile(document, "main", context); - - Assert.Same(first, second); - Assert.Equal(1, registry.CompileCount); + private const int FanOut = 26; + + [Fact] + public async Task Rule16_TwentySixSimultaneousConversations_ShareOneCompiledAgent() + { + using ScriptedChatClient client = new("Hello", " from", " one", " agent."); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(CompileTableTests.OneAgentYaml); + AgentCompilationContext context = new(new FakeChatClientFactory(client)); + CompiledAgentRegistry registry = new(); + + CancellationToken token = TestContext.Current.CancellationToken; + using Barrier gate = new(FanOut); + + IEnumerable> runs = Enumerable.Range(0, FanOut).Select(index => Task.Run( + async () => + { + // Every conversation asks the registry for the agent, exactly as the turn loop does. + CompiledAgent compiled = registry.GetOrCompile(document, "main", context); + + // Nothing starts until all 26 are ready, so the fan-out is really simultaneous. + gate.SignalAndWait(token); + + Microsoft.Agents.AI.AgentResponse reply = await compiled.Agent.RunAsync($"conversation {index}", cancellationToken: token) + .ConfigureAwait(false); + return (compiled, reply.Text); + }, + token)); + + (CompiledAgent compiled, string Text)[] results = await Task.WhenAll(runs); + + // No code path compiles an agent for each conversation. The compiled agent is a process singleton. + Assert.Equal(1, registry.CompileCount); + Assert.All(results, result => Assert.Same(results[0].compiled, result.compiled)); + Assert.All(results, result => Assert.Equal(client.FullText, result.Text)); + Assert.Equal(FanOut, client.Calls); + } + + [Fact] + public async Task Rule16_TwentySixSimultaneousConversations_AreCleanAgainstOneGraphWrapper() + { + using ScriptedChatClient client = new("Hello", " from", " the", " graph."); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(CompileTableTests.ExplicitGraphYaml); + AgentCompilationContext context = new(new FakeChatClientFactory(client)); + CompiledAgentRegistry registry = new(); + + CancellationToken token = TestContext.Current.CancellationToken; + CompiledAgent compiled = registry.GetOrCompile(document, "main", context); + using Barrier gate = new(FanOut); + + IEnumerable> runs = Enumerable.Range(0, FanOut).Select(index => Task.Run( + async () => + { + gate.SignalAndWait(token); + Microsoft.Agents.AI.AgentResponse reply = await compiled.Agent.RunAsync($"conversation {index}", cancellationToken: token) + .ConfigureAwait(false); + return reply.Text; + }, + token)); + + string[] texts = await Task.WhenAll(runs); + + // T44: nothing serializes inside the AsAIAgent() wrapper, so one wrapper serves every conversation. + Assert.Equal(1, registry.CompileCount); + Assert.All(texts, text => Assert.Contains("graph.", text, StringComparison.Ordinal)); + } + + [Fact] + public void Rule16_TheRegistryCompilesOncePerDocument() + { + using ScriptedChatClient client = new("ok"); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(CompileTableTests.OneAgentYaml); + AgentCompilationContext context = new(new FakeChatClientFactory(client)); + CompiledAgentRegistry registry = new(); + + CompiledAgent first = registry.GetOrCompile(document, "main", context); + CompiledAgent second = registry.GetOrCompile(document, "main", context); + + Assert.Same(first, second); + Assert.Equal(1, registry.CompileCount); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentRunTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentRunTests.cs index 8836a01f..3558c739 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentRunTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompiledAgentRunTests.cs @@ -4,94 +4,94 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Rule 13 of section 11. A one-agent configuration compiles to a ChatClientAgent and answers -/// a turn, and a graph: configuration compiles through WorkflowBuilder and -/// AsAIAgent() and yields its first non-empty delta before the model finishes. -/// -/// -/// Every test here uses an offline . There is no network conversation and no -/// API key anywhere in this file. -/// -public sealed class CompiledAgentRunTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private static readonly string[] Fragments = - ["Hello", " there.", " I", " am", " the", " compiled", " agent.", " Done."]; - - [Fact] - public async Task Rule13_AOneAgentConfiguration_AnswersATurn() + /// + /// Rule 13 of section 11. A one-agent configuration compiles to a ChatClientAgent and answers + /// a turn, and a graph: configuration compiles through WorkflowBuilder and + /// AsAIAgent() and yields its first non-empty delta before the model finishes. + /// + /// + /// Every test here uses an offline . There is no network conversation and no + /// API key anywhere in this file. + /// + public sealed class CompiledAgentRunTests { - using ScriptedChatClient client = new(Fragments); - var compiled = Compile(CompileTableTests.OneAgentYaml, client); + private static readonly string[] Fragments = + ["Hello", " there.", " I", " am", " the", " compiled", " agent.", " Done."]; - // Task 6a wraps every compiled agent for OpenTelemetry, so compiled.Agent is now the - // OpenTelemetryAgent and the ChatClientAgent it built sits underneath it. - Assert.IsType(compiled.Agent); - Assert.IsType(compiled.Agent.GetService()); + [Fact] + public async Task Rule13_AOneAgentConfiguration_AnswersATurn() + { + using ScriptedChatClient client = new(Fragments); + CompiledAgent compiled = Compile(CompileTableTests.OneAgentYaml, client); - var reply = await compiled.Agent.RunAsync("hello", cancellationToken: TestContext.Current.CancellationToken); + // Task 6a wraps every compiled agent for OpenTelemetry, so compiled.Agent is now the + // OpenTelemetryAgent and the ChatClientAgent it built sits underneath it. + _ = Assert.IsType(compiled.Agent); + _ = Assert.IsType(compiled.Agent.GetService()); - Assert.Equal(client.FullText, reply.Text); - Assert.Equal(1, client.Calls); - } + AgentResponse reply = await compiled.Agent.RunAsync("hello", cancellationToken: TestContext.Current.CancellationToken); - [Fact] - public async Task Rule13_AOneAgentConfiguration_StreamsEachDeltaThrough() - { - using ScriptedChatClient client = new(Fragments) { GateAfterFirstFragment = true }; - var compiled = Compile(CompileTableTests.OneAgentYaml, client); + Assert.Equal(client.FullText, reply.Text); + Assert.Equal(1, client.Calls); + } - var first = await FirstNonEmptyDeltaAsync(compiled.Agent, client); + [Fact] + public async Task Rule13_AOneAgentConfiguration_StreamsEachDeltaThrough() + { + using ScriptedChatClient client = new(Fragments) { GateAfterFirstFragment = true }; + CompiledAgent compiled = Compile(CompileTableTests.OneAgentYaml, client); - Assert.Equal("Hello", first); - } + string? first = await FirstNonEmptyDeltaAsync(compiled.Agent, client); - [Fact] - public async Task Rule13_AGraphConfiguration_YieldsItsFirstDeltaBeforeTheModelFinishes() - { - using ScriptedChatClient client = new(Fragments) { GateAfterFirstFragment = true }; - var compiled = Compile(CompileTableTests.ExplicitGraphYaml, client); + Assert.Equal("Hello", first); + } - Assert.Equal(CompiledAgentShape.ExplicitGraph, compiled.Shape); + [Fact] + public async Task Rule13_AGraphConfiguration_YieldsItsFirstDeltaBeforeTheModelFinishes() + { + using ScriptedChatClient client = new(Fragments) { GateAfterFirstFragment = true }; + CompiledAgent compiled = Compile(CompileTableTests.ExplicitGraphYaml, client); - // The model holds every fragment after the first, so a seam that aggregated would never - // reach this line. The gate opens only after the first delta arrives. - var first = await FirstNonEmptyDeltaAsync(compiled.Agent, client); + Assert.Equal(CompiledAgentShape.ExplicitGraph, compiled.Shape); - Assert.Equal("Hello", first); - } + // The model holds every fragment after the first, so a seam that aggregated would never + // reach this line. The gate opens only after the first delta arrives. + string? first = await FirstNonEmptyDeltaAsync(compiled.Agent, client); - [Fact] - public async Task Rule13_AGraphConfiguration_CarriesTheWholeReplyAfterFilteringOnNonEmptyText() - { - using ScriptedChatClient client = new(Fragments); - var compiled = Compile(CompileTableTests.ExplicitGraphYaml, client); + Assert.Equal("Hello", first); + } - List updates = []; - await foreach (var update in compiled.Agent.RunStreamingAsync( - "hello", cancellationToken: TestContext.Current.CancellationToken)) + [Fact] + public async Task Rule13_AGraphConfiguration_CarriesTheWholeReplyAfterFilteringOnNonEmptyText() { - updates.Add(update); - } + using ScriptedChatClient client = new(Fragments); + CompiledAgent compiled = Compile(CompileTableTests.ExplicitGraphYaml, client); - var text = string.Concat(updates.Where(update => !string.IsNullOrEmpty(update.Text)).Select(update => update.Text)); + List updates = []; + await foreach (AgentResponseUpdate update in compiled.Agent.RunStreamingAsync( + "hello", cancellationToken: TestContext.Current.CancellationToken)) + { + updates.Add(update); + } - // Section 8.6: AsAIAgent() yields more updates than text fragments, and the ones that carry - // no content match the lifecycle events. The synthesis adapter must filter on non-empty Text. - Assert.True(updates.Count > Fragments.Length, $"the wrapper yielded {updates.Count} updates for {Fragments.Length} fragments"); - Assert.Contains(updates, update => string.IsNullOrEmpty(update.Text)); + string text = string.Concat(updates.Where(update => !string.IsNullOrEmpty(update.Text)).Select(update => update.Text)); - // The graph runs both nodes, so the text is the model reply twice over. Nothing is lost. - Assert.Equal(client.FullText + client.FullText, text); - } + // Section 8.6: AsAIAgent() yields more updates than text fragments, and the ones that carry + // no content match the lifecycle events. The synthesis adapter must filter on non-empty Text. + Assert.True(updates.Count > Fragments.Length, $"the wrapper yielded {updates.Count} updates for {Fragments.Length} fragments"); + Assert.Contains(updates, update => string.IsNullOrEmpty(update.Text)); - [Fact] - public async Task Rule13_APatternGraph_AnswersATurn() - { - var yaml = - """ + // The graph runs both nodes, so the text is the model reply twice over. Nothing is lost. + Assert.Equal(client.FullText + client.FullText, text); + } + + [Fact] + public async Task Rule13_APatternGraph_AnswersATurn() + { + string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -104,41 +104,44 @@ public async Task Rule13_APatternGraph_AnswersATurn() agents: [ first, second ] """; - using ScriptedChatClient client = new("done"); - var compiled = Compile(yaml, client); - - var reply = await compiled.Agent.RunAsync("hello", cancellationToken: TestContext.Current.CancellationToken); - - Assert.Contains("done", reply.Text, StringComparison.Ordinal); - } - - private static async Task FirstNonEmptyDeltaAsync(AIAgent agent, ScriptedChatClient client) - { - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); + using ScriptedChatClient client = new("done"); + CompiledAgent compiled = Compile(yaml, client); - string? first = null; - await foreach (var update in agent.RunStreamingAsync("hello", cancellationToken: linked.Token)) - { - if (string.IsNullOrEmpty(update.Text)) - { - continue; - } + AgentResponse reply = await compiled.Agent.RunAsync("hello", cancellationToken: TestContext.Current.CancellationToken); - first = update.Text; - - // The reply reached us, so let the model finish. The order proves the seam streams. - client.OpenGate(); - break; - } + Assert.Contains("done", reply.Text, StringComparison.Ordinal); + } - client.OpenGate(); - return first; - } + private static async Task FirstNonEmptyDeltaAsync(AIAgent agent, ScriptedChatClient client) + { + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); + + string? first = null; + await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("hello", cancellationToken: linked.Token)) + { + if (string.IsNullOrEmpty(update.Text)) + { + continue; + } + + first = update.Text; + + // The reply reached us, so let the model finish. The order proves the seam streams. + client.OpenGate(); + break; + } + + client.OpenGate(); + return first; + } - private static CompiledAgent Compile(string yaml, ScriptedChatClient client) - => ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; - } + private static CompiledAgent Compile(string yaml, ScriptedChatClient client) + { + return ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; + } + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs index 2b3b6c68..bea14b4f 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerConversationStampTests.cs @@ -1,22 +1,24 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Llm; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; +using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// A compiled agent stamps the running turn's conversation id on every request the vendor sees, -/// under . This proves the COMPILED chain, not -/// the stamp on its own. -/// -public sealed class ConfigurationCompilerConversationStampTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string Yaml = - """ + /// + /// A compiled agent stamps the running turn's conversation id on every request the vendor sees, + /// under . This proves the COMPILED chain, not + /// the stamp on its own. + /// + public sealed class ConfigurationCompilerConversationStampTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -26,62 +28,67 @@ public sealed class ConfigurationCompilerConversationStampTests agent: only """; - [Fact] - public async Task ARunInsideATurn_CarriesTheConversationIdToTheVendor() - { - var turn = new TurnInvocation { ConversationId = "conversation-7", TurnIndex = 0, Stage = "" }; - OptionsCapturingChatClient model = new(); - var compiled = Compile(model); - - var session = await compiled.CreateSessionAsync(TestContext.Current.CancellationToken); - await compiled.RunAsync( - [new ChatMessage(ChatRole.User, "hi")], - session, - turn.RunOptions(), - TestContext.Current.CancellationToken); - - Assert.True(model.Seen!.AdditionalProperties!.TryGetValue(ChatRequestProperties.ConversationId, out string? stamped)); - Assert.Equal("conversation-7", stamped); - } + [Fact] + public async Task ARunInsideATurn_CarriesTheConversationIdToTheVendor() + { + TurnInvocation turn = new() { ConversationId = "conversation-7", TurnIndex = 0, Stage = "" }; + OptionsCapturingChatClient model = new(); + AIAgent compiled = Compile(model); - [Fact] - public async Task ARunOutsideATurn_StampsNothing() - { - OptionsCapturingChatClient model = new(); - var compiled = Compile(model); + AgentSession session = await compiled.CreateSessionAsync(TestContext.Current.CancellationToken); + _ = await compiled.RunAsync( + [new ChatMessage(ChatRole.User, "hi")], + session, + turn.RunOptions(), + TestContext.Current.CancellationToken); - var session = await compiled.CreateSessionAsync(TestContext.Current.CancellationToken); - await compiled.RunAsync([new ChatMessage(ChatRole.User, "hi")], session, cancellationToken: TestContext.Current.CancellationToken); + Assert.True(model.Seen!.AdditionalProperties!.TryGetValue(ChatRequestProperties.ConversationId, out string? stamped)); + Assert.Equal("conversation-7", stamped); + } - Assert.False(model.Seen!.AdditionalProperties?.ContainsKey(ChatRequestProperties.ConversationId) ?? false); - } + [Fact] + public async Task ARunOutsideATurn_StampsNothing() + { + OptionsCapturingChatClient model = new(); + AIAgent compiled = Compile(model); - private static Microsoft.Agents.AI.AIAgent Compile(IChatClient model) - { - var document = ConfigurationLoader.LoadYaml(Yaml); - return ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(model)))["main"].Agent; - } + AgentSession session = await compiled.CreateSessionAsync(TestContext.Current.CancellationToken); + _ = await compiled.RunAsync([new ChatMessage(ChatRole.User, "hi")], session, cancellationToken: TestContext.Current.CancellationToken); - private sealed class OptionsCapturingChatClient : IChatClient - { - public ChatOptions? Seen { get; private set; } + Assert.False(model.Seen!.AdditionalProperties?.ContainsKey(ChatRequestProperties.ConversationId) ?? false); + } - public Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + private static AIAgent Compile(IChatClient model) { - Seen = options; - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); + return ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(new FakeChatClientFactory(model)))["main"].Agent; } - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + private sealed class OptionsCapturingChatClient : IChatClient + { + public ChatOptions? Seen { get; private set; } - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + Seen = options; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); + } - public void Dispose() - { + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs index 2e2b7ef9..eb289f8c 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs @@ -1,26 +1,28 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Turn; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tools.Binding; using AgentCore.Application.Transcript; using AgentCore.TestSupport; +using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// ConfigurationCompiler.WithToolFailureAuditing puts -/// into a real pipeline rather than a hand-built one. Deleting its .Use(...) line changes no test in -/// ModelFacingChatClientTests at all, because none of them compile a document. This proves the -/// COMPILED agent, not the client on its own. -/// -public sealed class ConfigurationCompilerModelFacingTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string Yaml = - """ + /// + /// ConfigurationCompiler.WithToolFailureAuditing puts + /// into a real pipeline rather than a hand-built one. Deleting its .Use(...) line changes no test in + /// ModelFacingChatClientTests at all, because none of them compile a document. This proves the + /// COMPILED agent, not the client on its own. + /// + public sealed class ConfigurationCompilerModelFacingTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 tools: - { id: draw_card, kind: builtin, uses: test.draw, description: "Draw a card for the caller." } @@ -32,48 +34,51 @@ public sealed class ConfigurationCompilerModelFacingTests agent: only """; - [Fact] - public async Task TheSecondRoundOfACompiledAgent_NeverForwardsARenderContentTheFirstRoundsToolAttached() - { - TurnRenders renders = new(); - var turn = new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Renders = renders }; + [Fact] + public async Task TheSecondRoundOfACompiledAgent_NeverForwardsARenderContentTheFirstRoundsToolAttached() + { + TurnRenders renders = new(); + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", Renders = renders }; - RequestCapturingChatClient recorder = new(new ToolCallingChatClient("done.")); - var document = ConfigurationLoader.LoadYaml(Yaml); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(recorder)) - { - Tools = TestToolRegistry.From( - document, - static declared => declared.Uses == "test.draw" ? DrawCard() : null, - TestContext.Current.CancellationToken), - })["main"]; + RequestCapturingChatClient recorder = new(new ToolCallingChatClient("done.")); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(recorder)) + { + Tools = TestToolRegistry.From( + document, + static declared => declared.Uses == "test.draw" ? DrawCard() : null, + TestContext.Current.CancellationToken), + })["main"]; - var session = await compiled.Agent.CreateSessionAsync(TestContext.Current.CancellationToken); - await compiled.Agent.RunAsync( - [new ChatMessage(ChatRole.User, "draw me a card")], - session, - turn.RunOptions(), - TestContext.Current.CancellationToken); + AgentSession session = await compiled.Agent.CreateSessionAsync(TestContext.Current.CancellationToken); + _ = await compiled.Agent.RunAsync( + [new ChatMessage(ChatRole.User, "draw me a card")], + session, + turn.RunOptions(), + TestContext.Current.CancellationToken); - Assert.Equal(2, recorder.Requests.Count); - Assert.DoesNotContain( - recorder.Requests[1], - message => message.Contents.Any(content => content is RenderContent)); - } + Assert.Equal(2, recorder.Requests.Count); + Assert.DoesNotContain( + recorder.Requests[1], + message => message.Contents.Any(content => content is RenderContent)); + } - private static AIFunction DrawCard() - => AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - turn!.Renders!.Publish("card", "card-1", new { text = "hi" }); - return "drawn."; - }, - new AIFunctionFactoryOptions - { - Name = "draw_card", - Description = "Draw a card for the caller.", - ConfigureParameterBinding = ToolParameterBindings.For, - }); + private static AIFunction DrawCard() + { + return AIFunctionFactory.Create( + (TurnInvocation? turn) => + { + turn!.Renders!.Publish("card", "card-1", new { text = "hi" }); + return "drawn."; + }, + new AIFunctionFactoryOptions + { + Name = "draw_card", + Description = "Draw a card for the caller.", + ConfigureParameterBinding = ToolParameterBindings.For, + }); + } + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/DiscoveredToolReferenceTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/DiscoveredToolReferenceTests.cs index e587cf78..6ff98919 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/DiscoveredToolReferenceTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/DiscoveredToolReferenceTests.cs @@ -3,28 +3,27 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tools; using AgentCore.Application.Tools.Registry; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Decision 15 at the compile layer: an agent's tools: entry may name an id the registry -/// serves even when no tools: entry ever declares it — the shape an mcp: server's -/// discovery always takes. -/// -/// -/// only ever serves a declared id, so every -/// other compiler test in this project builds a registry that way and never exercises this path. The -/// two tests here build the registry directly through instead, so a -/// served id can be absent from tools: entirely. -/// -public sealed class DiscoveredToolReferenceTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string DiscoveredOnlyYaml = - """ + /// + /// Decision 15 at the compile layer: an agent's tools: entry may name an id the registry + /// serves even when no tools: entry ever declares it — the shape an mcp: server's + /// discovery always takes. + /// + /// + /// only ever serves a declared id, so every + /// other compiler test in this project builds a registry that way and never exercises this path. The + /// two tests here build the registry directly through instead, so a + /// served id can be absent from tools: entirely. + /// + public sealed class DiscoveredToolReferenceTests + { + private const string DiscoveredOnlyYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -34,55 +33,58 @@ public sealed class DiscoveredToolReferenceTests agent: only """; - [Fact] - public async Task AnIdNoToolsEntryDeclares_StillReachesTheModelWhenTheRegistryServesIt() - { - var document = ConfigurationLoader.LoadYaml(DiscoveredOnlyYaml); - var registry = await BuildRegistryAsync(document, "discovered_only", TestContext.Current.CancellationToken); + [Fact] + public async Task AnIdNoToolsEntryDeclares_StillReachesTheModelWhenTheRegistryServesIt() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(DiscoveredOnlyYaml); + ToolRegistry registry = await BuildRegistryAsync(document, "discovered_only", TestContext.Current.CancellationToken); - using ToolCallingChatClient client = new("answered"); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(client)) { Tools = registry })["main"]; + using ToolCallingChatClient client = new("answered"); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(client)) { Tools = registry })["main"]; - await compiled.Agent.RunAsync("hello", cancellationToken: TestContext.Current.CancellationToken); + _ = await compiled.Agent.RunAsync("hello", cancellationToken: TestContext.Current.CancellationToken); - Assert.NotEmpty(client.Offered); - Assert.All(client.Offered, offered => Assert.Equal("discovered_only", offered.Name)); - } + Assert.NotEmpty(client.Offered); + Assert.All(client.Offered, offered => Assert.Equal("discovered_only", offered.Name)); + } - [Fact] - public async Task AnIdInNeitherToolsNorTheRegistry_FailsNamingTheAskingAgent() - { - var document = ConfigurationLoader.LoadYaml(DiscoveredOnlyYaml); - var emptyRegistry = await BuildRegistryAsync(document, null, TestContext.Current.CancellationToken); + [Fact] + public async Task AnIdInNeitherToolsNorTheRegistry_FailsNamingTheAskingAgent() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(DiscoveredOnlyYaml); + ToolRegistry emptyRegistry = await BuildRegistryAsync(document, null, TestContext.Current.CancellationToken); - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(new ToolCallingChatClient("unused"))) - { - Tools = emptyRegistry, - })["main"]); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(new ToolCallingChatClient("unused"))) + { + Tools = emptyRegistry, + })["main"]); - var error = Assert.Single(failure.Errors); - Assert.Equal("/agents/items/0/tools/0", error.Pointer); - Assert.Contains("discovered_only", error.Message, StringComparison.Ordinal); - Assert.Contains("is not declared in tools:, and no tool source serves it", error.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/agents/items/0/tools/0", error.Pointer); + Assert.Contains("discovered_only", error.Message, StringComparison.Ordinal); + Assert.Contains("is not declared in tools:, and no tool source serves it", error.Message, StringComparison.Ordinal); + } - /// Builds a registry serving one id, or nothing at all when is . - private static async Task BuildRegistryAsync( - AgentCoreConfiguration document, string? id, CancellationToken cancellationToken) - { - IToolSource[] sources = id is null ? [] : [new OneToolSource(id)]; - return await ToolRegistryBuilder.BuildAsync(sources, new ToolSourceContext(document), cancellationToken); - } + /// Builds a registry serving one id, or nothing at all when is . + private static async Task BuildRegistryAsync( + AgentCoreConfiguration document, string? id, CancellationToken cancellationToken) + { + IToolSource[] sources = id is null ? [] : [new OneToolSource(id)]; + return await ToolRegistryBuilder.BuildAsync(sources, new ToolSourceContext(document), cancellationToken); + } - private sealed class OneToolSource(string id) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - [new ToolRegistration(id, "A tool discovered but never declared.", () => AIFunctionFactory.Create(() => "ok", id))]); + private sealed class OneToolSource(string id) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>( + [new ToolRegistration(id, "A tool discovered but never declared.", () => AIFunctionFactory.Create(() => "ok", id))]); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/FilesCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/FilesCompilationTests.cs index f29c4b56..61fc7d03 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/FilesCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/FilesCompilationTests.cs @@ -1,6 +1,7 @@ using System.Runtime.CompilerServices; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Harness; @@ -12,37 +13,37 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The files: block reaching a compiled agent as a , the -/// file_access_* tools it puts in front of the model, and the conversation folder it scopes to. -/// -#pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class FilesCompilationTests : IDisposable +namespace AgentCore.Application.Tests.Configuration.Compilation { - private static readonly string[] ExpectedFilesTools = - [ - "file_access_read", - "file_access_read_lines", - "file_access_ls", - "file_access_grep", - "file_access_write", - "file_access_delete", - "file_access_replace", - "file_access_replace_lines", - ]; - - private static readonly string[] ExpectedReadOnlyFilesTools = - [ - "file_access_read", - "file_access_read_lines", - "file_access_ls", - "file_access_grep", - ]; - - private const string FilesYaml = - """ + /// + /// The files: block reaching a compiled agent as a , the + /// file_access_* tools it puts in front of the model, and the conversation folder it scopes to. + /// +#pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class FilesCompilationTests : IDisposable + { + private static readonly string[] ExpectedFilesTools = + [ + "file_access_read", + "file_access_read_lines", + "file_access_ls", + "file_access_grep", + "file_access_write", + "file_access_delete", + "file_access_replace", + "file_access_replace_lines", + ]; + + private static readonly string[] ExpectedReadOnlyFilesTools = + [ + "file_access_read", + "file_access_read_lines", + "file_access_ls", + "file_access_grep", + ]; + + private const string FilesYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -52,8 +53,8 @@ public sealed class FilesCompilationTests : IDisposable agent: only """; - private const string ReadOnlyFilesYaml = - """ + private const string ReadOnlyFilesYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -63,8 +64,8 @@ public sealed class FilesCompilationTests : IDisposable agent: only """; - private const string NoFilesYaml = - """ + private const string NoFilesYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -74,302 +75,300 @@ public sealed class FilesCompilationTests : IDisposable agent: only """; - private readonly string _root = - Path.Combine(Path.GetTempPath(), "agentcore-files-" + Guid.NewGuid().ToString("N")); + private readonly string _root = + Path.Combine(Path.GetTempPath(), "agentcore-files-" + Guid.NewGuid().ToString("N")); - public void Dispose() - { - if (Directory.Exists(_root)) + public void Dispose() { - Directory.Delete(_root, recursive: true); + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } } - } - [Fact] - public async Task Compile_FilesWorkspaceWithARoot_GetsAFileAccessProviderAndTheEightTools() - { - using SequencedChatClient reply = new("hello there."); - var agent = CompileOne(FilesYaml, reply, _root); - Assert.Contains(Providers(agent), provider => provider is ConversationFilesProvider); - - var factory = BuildFactory(FilesYaml, _root, reply); - var session = factory.Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var tools = reply.Options[^1]?.Tools?.OfType().ToArray() ?? []; - AssertSameNames(ExpectedFilesTools, tools.Select(tool => tool.Name).ToArray()); - Assert.True( - tools.All(tool => tool is not ApprovalRequiredAIFunction), - "expected no file_access_* tool to require approval"); - } + [Fact] + public async Task Compile_FilesWorkspaceWithARoot_GetsAFileAccessProviderAndTheEightTools() + { + using SequencedChatClient reply = new("hello there."); + AIAgent agent = CompileOne(FilesYaml, reply, _root); + Assert.Contains(Providers(agent), provider => provider is ConversationFilesProvider); + + ConversationSessionFactory factory = BuildFactory(FilesYaml, _root, reply); + ConversationSession session = factory.Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + AITool[] tools = reply.Options[^1]?.Tools?.OfType().ToArray() ?? []; + AssertSameNames(ExpectedFilesTools, [.. tools.Select(tool => tool.Name)]); + Assert.True( + tools.All(tool => tool is not ApprovalRequiredAIFunction), + "expected no file_access_* tool to require approval"); + } - [Fact] - public async Task Compile_FilesWorkspaceWithARoot_TheModelsInstructionsAreTruthfulAboutDeletion() - { - using SequencedChatClient reply = new("hello there."); - var factory = BuildFactory(FilesYaml, _root, reply); - var session = factory.Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var instructions = reply.Options[^1]?.Instructions ?? string.Empty; - Assert.Contains("deleted when the conversation ends", instructions, StringComparison.Ordinal); - Assert.DoesNotContain("persist beyond", instructions, StringComparison.Ordinal); - } + [Fact] + public async Task Compile_FilesWorkspaceWithARoot_TheModelsInstructionsAreTruthfulAboutDeletion() + { + using SequencedChatClient reply = new("hello there."); + ConversationSessionFactory factory = BuildFactory(FilesYaml, _root, reply); + ConversationSession session = factory.Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + string instructions = reply.Options[^1]?.Instructions ?? string.Empty; + Assert.Contains("deleted when the conversation ends", instructions, StringComparison.Ordinal); + Assert.DoesNotContain("persist beyond", instructions, StringComparison.Ordinal); + } - [Fact] - public async Task Compile_FilesWorkspaceWriteFalse_GetsOnlyTheFourReadOnlyTools() - { - using SequencedChatClient reply = new("hello there."); - var factory = BuildFactory(ReadOnlyFilesYaml, _root, reply); - var session = factory.Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + [Fact] + public async Task Compile_FilesWorkspaceWriteFalse_GetsOnlyTheFourReadOnlyTools() + { + using SequencedChatClient reply = new("hello there."); + ConversationSessionFactory factory = BuildFactory(ReadOnlyFilesYaml, _root, reply); + ConversationSession session = factory.Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - AssertSameNames(ExpectedReadOnlyFilesTools, toolNames); - } + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + AssertSameNames(ExpectedReadOnlyFilesTools, toolNames); + } - [Fact] - public async Task Compile_NoFilesBlock_GetsNoFileAccessProviderAndNoTool() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public async Task Compile_NoFilesBlock_GetsNoFileAccessProviderAndNoTool() + { + using SequencedChatClient reply = new("hello there."); - var agent = CompileOne(NoFilesYaml, reply, _root); - Assert.DoesNotContain(Providers(agent), provider => provider is FileAccessProvider); + AIAgent agent = CompileOne(NoFilesYaml, reply, _root); + Assert.DoesNotContain(Providers(agent), provider => provider is FileAccessProvider); - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); - await agent.RunAsync("hi", session, cancellationToken: token); + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); + _ = await agent.RunAsync("hi", session, cancellationToken: token); - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - Assert.DoesNotContain(toolNames, name => name.StartsWith("file_access_", StringComparison.Ordinal)); - } + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + Assert.DoesNotContain(toolNames, name => name.StartsWith("file_access_", StringComparison.Ordinal)); + } - [Fact] - public void Compile_FilesWorkspaceWithNoRoot_FailsNamingTheFilesPointer() - { - var document = ConfigurationLoader.LoadYaml(FilesYaml); + [Fact] + public void Compile_FilesWorkspaceWithNoRoot_FailsNamingTheFilesPointer() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(FilesYaml); - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))))["main"]); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))))["main"]); - Assert.Equal("/agents/items/0/files", failure.Pointer); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/0/files", failure.Pointer); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task EndToEnd_WriteReadLsGrep_ThenEndConversationDeletesTheFolder() - { - var client = new SequencedToolCallClient( - (FileAccessProvider.WriteToolName, Args(("fileName", "out.txt"), ("content", "hello"))), - (FileAccessProvider.ReadFileToolName, Args(("fileName", "out.txt"))), - (FileAccessProvider.LsToolName, Args()), - (FileAccessProvider.GrepToolName, Args(("regexPattern", "hell")))); + [Fact] + public async Task EndToEnd_WriteReadLsGrep_ThenEndConversationDeletesTheFolder() + { + SequencedToolCallClient client = new( + (FileAccessProvider.WriteToolName, Args(("fileName", "out.txt"), ("content", "hello"))), + (FileAccessProvider.ReadFileToolName, Args(("fileName", "out.txt"))), + (FileAccessProvider.LsToolName, Args()), + (FileAccessProvider.GrepToolName, Args(("regexPattern", "hell")))); - var factory = BuildFactory(FilesYaml, _root, client); - var session = factory.Create("conversation-1"); - var conversationFolder = session.Workspace!; + ConversationSessionFactory factory = BuildFactory(FilesYaml, _root, client); + ConversationSession session = factory.Create("conversation-1"); + string conversationFolder = session.Workspace!; - await session.RunTurnAsync("write hello to out.txt", TestContext.Current.CancellationToken); - Assert.Equal("hello", await File.ReadAllTextAsync( - Path.Combine(conversationFolder, "out.txt"), TestContext.Current.CancellationToken)); + _ = await session.RunTurnAsync("write hello to out.txt", TestContext.Current.CancellationToken); + Assert.Equal("hello", await File.ReadAllTextAsync( + Path.Combine(conversationFolder, "out.txt"), TestContext.Current.CancellationToken)); - await session.RunTurnAsync("read out.txt", TestContext.Current.CancellationToken); - Assert.Contains("hello", client.ToolResults[1]); + _ = await session.RunTurnAsync("read out.txt", TestContext.Current.CancellationToken); + Assert.Contains("hello", client.ToolResults[1]); - await session.RunTurnAsync("list the folder", TestContext.Current.CancellationToken); - Assert.Contains("out.txt", client.ToolResults[2]); - Assert.DoesNotContain("conversation-1", client.ToolResults[2], StringComparison.Ordinal); + _ = await session.RunTurnAsync("list the folder", TestContext.Current.CancellationToken); + Assert.Contains("out.txt", client.ToolResults[2]); + Assert.DoesNotContain("conversation-1", client.ToolResults[2], StringComparison.Ordinal); - await session.RunTurnAsync("grep for hell", TestContext.Current.CancellationToken); - Assert.Contains("out.txt", client.ToolResults[3]); + _ = await session.RunTurnAsync("grep for hell", TestContext.Current.CancellationToken); + Assert.Contains("out.txt", client.ToolResults[3]); - session.EndConversation(ConversationEndReason.CallerHungUp); - Assert.False(Directory.Exists(conversationFolder)); - } + _ = session.EndConversation(ConversationEndReason.CallerHungUp); + Assert.False(Directory.Exists(conversationFolder)); + } - [Fact] - public async Task Escape_WriteOutsideTheConversationFolder_CreatesNothingOutsideItAndDoesNotThrow() - { - var client = new SequencedToolCallClient( - (FileAccessProvider.WriteToolName, Args(("fileName", "../escape.txt"), ("content", "leaked")))); - - var factory = BuildFactory(FilesYaml, _root, client); - var session = factory.Create("conversation-1"); - - // The point of the assertion is that this completes at all: an escape attempt must not - // throw out of RunTurnAsync. - await session.RunTurnAsync("escape", TestContext.Current.CancellationToken); - - // The real string, not the probe's "Error: Function failed." (that string is what a store - // exception looks like when it escapes uncaught, e.g. the missing-ambient case; a rejected - // path is instead refused before it throws, as a JSON error object naming the tool.) - Assert.Contains("\"error\": true", client.ToolResults[0], StringComparison.Ordinal); - Assert.Contains("file_access_write", client.ToolResults[0], StringComparison.Ordinal); - - var escaped = Directory.Exists(_root) - ? Directory.EnumerateFiles(_root, "escape.txt", SearchOption.AllDirectories).ToList() - : []; - Assert.Empty(escaped); - } + [Fact] + public async Task Escape_WriteOutsideTheConversationFolder_CreatesNothingOutsideItAndDoesNotThrow() + { + SequencedToolCallClient client = new( + (FileAccessProvider.WriteToolName, Args(("fileName", "../escape.txt"), ("content", "leaked")))); - [Fact] - public async Task TwoSessions_DifferentConversationIds_SeeOnlyTheirOwnFile() - { - var clientA = new SequencedToolCallClient( - (FileAccessProvider.WriteToolName, Args(("fileName", "out.txt"), ("content", "A")))); - var clientB = new SequencedToolCallClient( - (FileAccessProvider.WriteToolName, Args(("fileName", "out.txt"), ("content", "B")))); + ConversationSessionFactory factory = BuildFactory(FilesYaml, _root, client); + ConversationSession session = factory.Create("conversation-1"); - var factoryA = BuildFactory(FilesYaml, _root, clientA); - var sessionA = factoryA.Create("conversation-a"); - await sessionA.RunTurnAsync("write A", TestContext.Current.CancellationToken); + // The point of the assertion is that this completes at all: an escape attempt must not + // throw out of RunTurnAsync. + _ = await session.RunTurnAsync("escape", TestContext.Current.CancellationToken); - var factoryB = BuildFactory(FilesYaml, _root, clientB); - var sessionB = factoryB.Create("conversation-b"); - await sessionB.RunTurnAsync("write B", TestContext.Current.CancellationToken); + // The real string, not the probe's "Error: Function failed." (that string is what a store + // exception looks like when it escapes uncaught, e.g. the missing-ambient case; a rejected + // path is instead refused before it throws, as a JSON error object naming the tool.) + Assert.Contains("\"error\": true", client.ToolResults[0], StringComparison.Ordinal); + Assert.Contains("file_access_write", client.ToolResults[0], StringComparison.Ordinal); - var pathA = Path.Combine(sessionA.Workspace!, "out.txt"); - var pathB = Path.Combine(sessionB.Workspace!, "out.txt"); + List escaped = Directory.Exists(_root) + ? [.. Directory.EnumerateFiles(_root, "escape.txt", SearchOption.AllDirectories)] + : []; + Assert.Empty(escaped); + } - Assert.Equal("A", await File.ReadAllTextAsync(pathA, TestContext.Current.CancellationToken)); - Assert.Equal("B", await File.ReadAllTextAsync(pathB, TestContext.Current.CancellationToken)); - } + [Fact] + public async Task TwoSessions_DifferentConversationIds_SeeOnlyTheirOwnFile() + { + SequencedToolCallClient clientA = new( + (FileAccessProvider.WriteToolName, Args(("fileName", "out.txt"), ("content", "A")))); + SequencedToolCallClient clientB = new( + (FileAccessProvider.WriteToolName, Args(("fileName", "out.txt"), ("content", "B")))); - private static void AssertSameNames(string[] expected, string[] actual) - { - var expectedSorted = expected.OrderBy(n => n, StringComparer.Ordinal).ToArray(); - var actualSorted = actual.OrderBy(n => n, StringComparer.Ordinal).ToArray(); - Assert.Equal(expectedSorted, actualSorted, StringComparer.Ordinal); - } + ConversationSessionFactory factoryA = BuildFactory(FilesYaml, _root, clientA); + ConversationSession sessionA = factoryA.Create("conversation-a"); + _ = await sessionA.RunTurnAsync("write A", TestContext.Current.CancellationToken); - private static Dictionary Args(params (string Key, object? Value)[] pairs) - { - var args = new Dictionary(StringComparer.Ordinal); - foreach (var (key, value) in pairs) - { - args[key] = value; - } + ConversationSessionFactory factoryB = BuildFactory(FilesYaml, _root, clientB); + ConversationSession sessionB = factoryB.Create("conversation-b"); + _ = await sessionB.RunTurnAsync("write B", TestContext.Current.CancellationToken); - return args; - } + string pathA = Path.Combine(sessionA.Workspace!, "out.txt"); + string pathB = Path.Combine(sessionB.Workspace!, "out.txt"); - private static ConversationSessionFactory BuildFactory(string yaml, string root, IChatClient? client = null) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new RoutingChatClientFactory(client ?? new SequencedChatClient("done")); + Assert.Equal("A", await File.ReadAllTextAsync(pathA, TestContext.Current.CancellationToken)); + Assert.Equal("B", await File.ReadAllTextAsync(pathB, TestContext.Current.CancellationToken)); + } - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { WorkspaceRoot = root })["main"]; + private static void AssertSameNames(string[] expected, string[] actual) + { + string[] expectedSorted = [.. expected.OrderBy(n => n, StringComparer.Ordinal)]; + string[] actualSorted = [.. actual.OrderBy(n => n, StringComparer.Ordinal)]; + Assert.Equal(expectedSorted, actualSorted, StringComparer.Ordinal); + } - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - workspaceRoot: root); - } + private static Dictionary Args(params (string Key, object? Value)[] pairs) + { + Dictionary args = new(StringComparer.Ordinal); + foreach ((string? key, object? value) in pairs) + { + args[key] = value; + } - private static AIAgent CompileOne(string yaml, SequencedChatClient reply, string root) - { - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) { WorkspaceRoot = root })["main"]; + return args; + } - return Assert.Single(compiled.Agents.Values); - } + private static ConversationSessionFactory BuildFactory(string yaml, string root, IChatClient? client = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(client ?? new SequencedChatClient("done")); - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; - } + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { WorkspaceRoot = root })["main"]; - /// - /// A deterministic offline model that plays a queue of specific named tool calls, one per turn: - /// it calls the next queued tool when the last message is a fresh user turn, and replies with - /// text once the framework has fed the tool's result back mid-turn. - /// - private sealed class SequencedToolCallClient : IChatClient - { - private readonly Queue<(string Name, Dictionary Args)> _steps; + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + workspaceRoot: root); + } - public SequencedToolCallClient(params (string Name, Dictionary Args)[] steps) - => _steps = new(steps); + private static AIAgent CompileOne(string yaml, SequencedChatClient reply, string root) + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { WorkspaceRoot = root })["main"]; - /// Gets the text of each tool result this client was fed back, in call order. - public List ToolResults { get; } = []; + return Assert.Single(compiled.Agents.Values); + } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + private static IEnumerable Providers(AIAgent agent) { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } - var transcript = messages.ToList(); - var responseId = Guid.NewGuid().ToString("N"); + /// + /// A deterministic offline model that plays a queue of specific named tool calls, one per turn: + /// it calls the next queued tool when the last message is a fresh user turn, and replies with + /// text once the framework has fed the tool's result back mid-turn. + /// + private sealed class SequencedToolCallClient(params (string Name, Dictionary Args)[] steps) : IChatClient + { + private readonly Queue<(string Name, Dictionary Args)> _steps = new(steps); - var lastResults = transcript.Count > 0 - ? transcript[^1].Contents.OfType().ToList() - : []; + /// Gets the text of each tool result this client was fed back, in call order. + public List ToolResults { get; } = []; - foreach (var result in lastResults) + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - lock (ToolResults) + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); + + List transcript = [.. messages]; + string responseId = Guid.NewGuid().ToString("N"); + + List lastResults = transcript.Count > 0 + ? [.. transcript[^1].Contents.OfType()] + : []; + + foreach (FunctionResultContent? result in lastResults) { - ToolResults.Add(result.Result?.ToString() ?? string.Empty); + lock (ToolResults) + { + ToolResults.Add(result.Result?.ToString() ?? string.Empty); + } } - } - if (lastResults.Count == 0 && _steps.Count > 0) - { - var (name, args) = _steps.Dequeue(); + if (lastResults.Count == 0 && _steps.Count > 0) + { + (string? name, Dictionary? args) = _steps.Dequeue(); + + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent("conversation_" + Guid.NewGuid().ToString("N"), name, args)]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent("conversation_" + Guid.NewGuid().ToString("N"), name, args)]) + yield return new ChatResponseUpdate(ChatRole.Assistant, "done") { ResponseId = responseId, MessageId = responseId, }; - - yield break; } - yield return new ChatResponseUpdate(ChatRole.Assistant, "done") + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs index e90d268c..27cd96e3 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/GraphNoMatchTests.cs @@ -3,42 +3,42 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.State; using AgentCore.Application.Tests.Fakes; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Row 4 of the section 8.2 compile table, where no edge guard is true. -/// -/// -/// -/// A stage says onNoMatch: error, and a graph node has no such key. Measured on -/// Microsoft.Agents.AI.Workflows 1.17.0: a run whose outgoing guards are all false ends at -/// idle, InProcessRunner raises no exception, and the AsAIAgent() wrapper emits no -/// update. The caller therefore reads an empty run and no error, which is the silent graph failure -/// section 8.2 refuses to ship. -/// -/// -/// Every test here runs offline. There is no network conversation and no API key in this file. -/// -/// -public sealed class GraphNoMatchTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - /// The text the one output node produces when the run reaches it. - private const string EscalatedReply = "ESCALATED"; - /// - /// One start node and one guarded exit. The guard is false whenever escalate is false, so - /// the run stops at the start node and nothing reaches the output node. + /// Row 4 of the section 8.2 compile table, where no edge guard is true. /// - private const string NoMatchGraphYaml = - """ + /// + /// + /// A stage says onNoMatch: error, and a graph node has no such key. Measured on + /// Microsoft.Agents.AI.Workflows 1.17.0: a run whose outgoing guards are all false ends at + /// idle, InProcessRunner raises no exception, and the AsAIAgent() wrapper emits no + /// update. The caller therefore reads an empty run and no error, which is the silent graph failure + /// section 8.2 refuses to ship. + /// + /// + /// Every test here runs offline. There is no network conversation and no API key in this file. + /// + /// + public sealed class GraphNoMatchTests + { + /// The text the one output node produces when the run reaches it. + private const string EscalatedReply = "ESCALATED"; + + /// + /// One start node and one guarded exit. The guard is false whenever escalate is false, so + /// the run stops at the start node and nothing reaches the output node. + /// + private const string NoMatchGraphYaml = + """ apiVersion: agentcore/v1 state: escalate: { type: boolean, writer: extractor, default: false } @@ -66,183 +66,187 @@ public sealed class GraphNoMatchTests - { kind: openai, model: gpt-4.1-mini, as: human } """; - [Fact] - public async Task Row4_AGraphWhereNoEdgeGuardIsTrue_ThrowsInsteadOfAnsweringNothing() - { - using Harness harness = new(); - - var failure = await Record.ExceptionAsync(() => harness.Compiled.Agent.RunAsync( - "hello", null, harness.StateOptions(escalate: false), - cancellationToken: TestContext.Current.CancellationToken)); - - Assert.IsType(failure); - Assert.Contains("main", failure.Message, StringComparison.Ordinal); - Assert.Contains(RequireOutputAgent.NoOutputMessage, failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task Row4_AGraphWhereNoEdgeGuardIsTrue_ThrowsWhileStreamingToo() - { - using Harness harness = new(); - - // The streaming path hands the updates over one at a time, so the check reads them as they - // pass and throws after the last one. A caller that enumerates to the end sees the fault. - var failure = await Record.ExceptionAsync(async () => - { - await foreach (var update in harness.Compiled.Agent.RunStreamingAsync( - "hello", null, harness.StateOptions(escalate: false), - cancellationToken: TestContext.Current.CancellationToken)) - { - _ = update; - } - }); - - Assert.IsType(failure); - Assert.Contains("main", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task Row4_AGraphWhereAnEdgeGuardIsTrue_StillAnswers() - { - using Harness harness = new(); - - var reply = await harness.Compiled.Agent.RunAsync( - "hello", null, harness.StateOptions(escalate: true), - cancellationToken: TestContext.Current.CancellationToken); - - // The check sits in front of nothing. A run that produced text is the run it always was. - Assert.Contains(EscalatedReply, reply.Text, StringComparison.Ordinal); - } - - [Fact] - public async Task Row4_AGraphWhereAnEdgeGuardIsTrue_StillStreams() - { - using Harness harness = new(); - - List text = []; - await foreach (var update in harness.Compiled.Agent.RunStreamingAsync( - "hello", null, harness.StateOptions(escalate: true), - cancellationToken: TestContext.Current.CancellationToken)) - { - text.Add(update.Text); - } - - Assert.Contains(EscalatedReply, string.Concat(text), StringComparison.Ordinal); - } - - [Fact] - public async Task Row4_ANoMatchInsideAConversation_SpeaksTheFallbackAndTheConversationLives() - { - using Harness harness = new(); - var session = harness.NewSession(); - session.State.TryWrite("escalate", false); - - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Section 8.7, sixth row. The run throws, the turn speaks the fallback, and the conversation lives. - // A live conversation therefore does not change: only a host that runs the compiled agent itself - // reads the exception. - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.NotNull(turn.Failure); - Assert.False(session.IsComplete); - } - - [Fact] - public async Task Row4_ANoMatchInsideAStreamingConversation_SpeaksTheFallbackAndTheConversationLives() - { - using Harness harness = new(); - var session = harness.NewSession(); - session.State.TryWrite("escalate", false); - - await foreach (var update in session.RunTurnStreamingAsync( - "hello", TestContext.Current.CancellationToken)) - { - _ = update; - } - - Assert.NotNull(session.LastTurn); - Assert.Equal(ConversationSession.FallbackReply, session.LastTurn!.ReplyText); - Assert.NotNull(session.LastTurn.Failure); - Assert.False(session.IsComplete); - } - - /// - /// One compiled graph, wired the way the composition root wires it. - /// - private sealed class Harness : IDisposable - { - // The start node classifies and speaks nothing, which is the shape that goes silent. Every - // node binding emits agent update events, so a start node that did speak would carry its own - // text out of the run and the caller would read that instead of an empty run. - private readonly ScriptedChatClient _router = new(string.Empty); - private readonly ScriptedChatClient _human = new(EscalatedReply); - private readonly AgentCoreConfiguration _document; - private readonly ConversationSessionFactory _sessions; - - /// Compiles the no-match graph once, over two offline models. - public Harness() - { - _document = ConfigurationLoader.LoadYaml(NoMatchGraphYaml); - GuardEvaluator guards = new(_document.Guards); - - RoutingChatClientFactory models = new(); - models.Route("router", _router); - models.Route("human", _human); - - Compiled = ConfigurationCompiler.CompileAll( - _document, - new AgentCompilationContext(models) - { - Guards = guards, - })["main"]; - - _sessions = new ConversationSessionFactory(Compiled, guards); - } - - /// Gets the one compiled agent every conversation shares. - public CompiledAgent Compiled { get; } - - /// Builds the state of one conversation, with the slot the guard reads set. - /// What the guard wants_human reads. - /// The state document. - public StateDocument NewState(bool escalate) - { - StateDocument state = new(_document); - state.TryWrite("escalate", escalate); - return state; - } - - /// Files one conversation's state on a bare run's options, the way the turn loop files it. - /// What the guard wants_human reads. - /// Run options carrying the turn the graph-state wrapper reads. - public ChatClientAgentRunOptions StateOptions(bool escalate) - { - TurnInvocation invocation = new() - { - ConversationId = "test-conversation", - TurnIndex = 0, - Stage = string.Empty, - State = NewState(escalate), - }; - - return new ChatClientAgentRunOptions(new ChatOptions - { - AdditionalProperties = new AdditionalPropertiesDictionary - { - [TurnInvocation.ArgumentsKey] = invocation, - }, - }); - } - - /// Builds the session of one more conversation. - /// The session. - public ConversationSession NewSession() => _sessions.Create(); - - public void Dispose() - { - _router.Dispose(); - _human.Dispose(); - } - } - - } + [Fact] + public async Task Row4_AGraphWhereNoEdgeGuardIsTrue_ThrowsInsteadOfAnsweringNothing() + { + using Harness harness = new(); + + Exception? failure = await Record.ExceptionAsync(() => harness.Compiled.Agent.RunAsync( + "hello", null, harness.StateOptions(escalate: false), + cancellationToken: TestContext.Current.CancellationToken)); + + _ = Assert.IsType(failure); + Assert.Contains("main", failure.Message, StringComparison.Ordinal); + Assert.Contains(RequireOutputAgent.NoOutputMessage, failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task Row4_AGraphWhereNoEdgeGuardIsTrue_ThrowsWhileStreamingToo() + { + using Harness harness = new(); + + // The streaming path hands the updates over one at a time, so the check reads them as they + // pass and throws after the last one. A caller that enumerates to the end sees the fault. + Exception? failure = await Record.ExceptionAsync(async () => + { + await foreach (AgentResponseUpdate update in harness.Compiled.Agent.RunStreamingAsync( + "hello", null, harness.StateOptions(escalate: false), + cancellationToken: TestContext.Current.CancellationToken)) + { + _ = update; + } + }); + + _ = Assert.IsType(failure); + Assert.Contains("main", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task Row4_AGraphWhereAnEdgeGuardIsTrue_StillAnswers() + { + using Harness harness = new(); + + AgentResponse reply = await harness.Compiled.Agent.RunAsync( + "hello", null, harness.StateOptions(escalate: true), + cancellationToken: TestContext.Current.CancellationToken); + + // The check sits in front of nothing. A run that produced text is the run it always was. + Assert.Contains(EscalatedReply, reply.Text, StringComparison.Ordinal); + } + + [Fact] + public async Task Row4_AGraphWhereAnEdgeGuardIsTrue_StillStreams() + { + using Harness harness = new(); + + List text = []; + await foreach (AgentResponseUpdate update in harness.Compiled.Agent.RunStreamingAsync( + "hello", null, harness.StateOptions(escalate: true), + cancellationToken: TestContext.Current.CancellationToken)) + { + text.Add(update.Text); + } + + Assert.Contains(EscalatedReply, string.Concat(text), StringComparison.Ordinal); + } + + [Fact] + public async Task Row4_ANoMatchInsideAConversation_SpeaksTheFallbackAndTheConversationLives() + { + using Harness harness = new(); + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", false); + + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Section 8.7, sixth row. The run throws, the turn speaks the fallback, and the conversation lives. + // A live conversation therefore does not change: only a host that runs the compiled agent itself + // reads the exception. + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.NotNull(turn.Failure); + Assert.False(session.IsComplete); + } + + [Fact] + public async Task Row4_ANoMatchInsideAStreamingConversation_SpeaksTheFallbackAndTheConversationLives() + { + using Harness harness = new(); + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", false); + + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync( + "hello", TestContext.Current.CancellationToken)) + { + _ = update; + } + + Assert.NotNull(session.LastTurn); + Assert.Equal(ConversationSession.FallbackReply, session.LastTurn!.ReplyText); + Assert.NotNull(session.LastTurn.Failure); + Assert.False(session.IsComplete); + } + + /// + /// One compiled graph, wired the way the composition root wires it. + /// + private sealed class Harness : IDisposable + { + // The start node classifies and speaks nothing, which is the shape that goes silent. Every + // node binding emits agent update events, so a start node that did speak would carry its own + // text out of the run and the caller would read that instead of an empty run. + private readonly ScriptedChatClient _router = new(string.Empty); + private readonly ScriptedChatClient _human = new(EscalatedReply); + private readonly AgentCoreConfiguration _document; + private readonly ConversationSessionFactory _sessions; + + /// Compiles the no-match graph once, over two offline models. + public Harness() + { + _document = ConfigurationLoader.LoadYaml(NoMatchGraphYaml); + GuardEvaluator guards = new(_document.Guards); + + RoutingChatClientFactory models = new(); + _ = models.Route("router", _router); + _ = models.Route("human", _human); + + Compiled = ConfigurationCompiler.CompileAll( + _document, + new AgentCompilationContext(models) + { + Guards = guards, + })["main"]; + + _sessions = new ConversationSessionFactory(Compiled, guards); + } + + /// Gets the one compiled agent every conversation shares. + public CompiledAgent Compiled { get; } + + /// Builds the state of one conversation, with the slot the guard reads set. + /// What the guard wants_human reads. + /// The state document. + public StateDocument NewState(bool escalate) + { + StateDocument state = new(_document); + _ = state.TryWrite("escalate", escalate); + return state; + } + + /// Files one conversation's state on a bare run's options, the way the turn loop files it. + /// What the guard wants_human reads. + /// Run options carrying the turn the graph-state wrapper reads. + public ChatClientAgentRunOptions StateOptions(bool escalate) + { + TurnInvocation invocation = new() + { + ConversationId = "test-conversation", + TurnIndex = 0, + Stage = string.Empty, + State = NewState(escalate), + }; + + return new ChatClientAgentRunOptions(new ChatOptions + { + AdditionalProperties = new AdditionalPropertiesDictionary + { + [TurnInvocation.ArgumentsKey] = invocation, + }, + }); + } + + /// Builds the session of one more conversation. + /// The session. + public ConversationSession NewSession() + { + return _sessions.Create(); + } + + public void Dispose() + { + _router.Dispose(); + _human.Dispose(); + } + } + + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs index eb4fbe4a..033b53c3 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/GuardedGraphEdgeTests.cs @@ -3,45 +3,45 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Row 4 of the section 8.2 compile table, with a guarded edge. -/// -/// -/// -/// Two rules pull apart here. T44 makes the compiled agent a process singleton, so one graph serves -/// every conversation and no code path compiles one for each conversation. A guarded edge reads the state of one -/// conversation, and each conversation owns its own state document. The graph-state wrapper files the turn's -/// snapshot on the run and a gate executor reads it back, so the compiled graph captures nothing -/// per conversation and concurrent conversations never share it. -/// -/// -/// Every test here runs offline. There is no network conversation and no API key in this file. -/// -/// -public sealed class GuardedGraphEdgeTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const int FanOut = 26; - - /// The text of the node a conversation reaches when the guard wants_human holds. - private const string EscalatedReply = "ESCALATED"; - - /// The text of the node a conversation reaches when the guard stays_with_bot holds. - private const string HandledReply = "HANDLED"; - /// - /// One start node and two guarded exits. Check 5 of section 8.5 proves the two guards exclusive - /// over the state domain, so exactly one edge fires for each conversation. + /// Row 4 of the section 8.2 compile table, with a guarded edge. /// - internal const string GuardedGraphYaml = - """ + /// + /// + /// Two rules pull apart here. T44 makes the compiled agent a process singleton, so one graph serves + /// every conversation and no code path compiles one for each conversation. A guarded edge reads the state of one + /// conversation, and each conversation owns its own state document. The graph-state wrapper files the turn's + /// snapshot on the run and a gate executor reads it back, so the compiled graph captures nothing + /// per conversation and concurrent conversations never share it. + /// + /// + /// Every test here runs offline. There is no network conversation and no API key in this file. + /// + /// + public sealed class GuardedGraphEdgeTests + { + private const int FanOut = 26; + + /// The text of the node a conversation reaches when the guard wants_human holds. + private const string EscalatedReply = "ESCALATED"; + + /// The text of the node a conversation reaches when the guard stays_with_bot holds. + private const string HandledReply = "HANDLED"; + + /// + /// One start node and two guarded exits. Check 5 of section 8.5 proves the two guards exclusive + /// over the state domain, so exactly one edge fires for each conversation. + /// + internal const string GuardedGraphYaml = + """ apiVersion: agentcore/v1 state: escalate: { type: boolean, writer: extractor, default: false } @@ -74,254 +74,261 @@ public sealed class GuardedGraphEdgeTests - { kind: openai, model: gpt-4.1-mini, as: bot } """; - [Fact] - public void AGuardedEdge_PassesEveryOneOfTheEightChecks() - { - var document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); - - // The defect this file closes: the document was valid and then failed to compile. Check 5 - // even proves the two guards exclusive, so the load has nothing left to object to. - var result = ConfigurationValidator.Evaluate(document); - - Assert.Empty(result.Errors); - } - - [Fact] - public async Task AGuardedEdge_CompilesAndTakesTheEdgeTheStateNames() - { - using Harness harness = new(); - var session = harness.NewSession(); - session.State.TryWrite("escalate", true); - - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Contains(EscalatedReply, turn.ReplyText, StringComparison.Ordinal); - Assert.DoesNotContain(HandledReply, turn.ReplyText, StringComparison.Ordinal); - } - - [Fact] - public async Task AGuardedEdge_TakesTheOtherEdgeWhenTheStateSaysSo() - { - using Harness harness = new(); - var session = harness.NewSession(); - session.State.TryWrite("escalate", false); - - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Contains(HandledReply, turn.ReplyText, StringComparison.Ordinal); - Assert.DoesNotContain(EscalatedReply, turn.ReplyText, StringComparison.Ordinal); - } - - [Fact] - public async Task AGuardedEdge_TakesTheEdgeTheStateNamesWhileStreaming() - { - using Harness harness = new(); - var session = harness.NewSession(); - session.State.TryWrite("escalate", true); - - List text = []; - await foreach (var update in session.RunTurnStreamingAsync( - "hello", TestContext.Current.CancellationToken)) - { - text.Add(update.Text); - } - - // The turn's snapshot rides the run's own messages, so the streaming path needs no - // per-step scope to route: the gate reads what the entry filed before the first model call. - Assert.Contains(EscalatedReply, string.Concat(text), StringComparison.Ordinal); - Assert.DoesNotContain(HandledReply, string.Concat(text), StringComparison.Ordinal); - } - - [Fact] - public async Task Rule16_TwentySixSimultaneousConversations_EachTakeTheirOwnEdgeThroughOneCompiledGraph() - { - using Harness harness = new(); - var token = TestContext.Current.CancellationToken; - using Barrier gate = new(FanOut); - - var conversations = Enumerable.Range(0, FanOut).Select(index => Task.Run( - async () => - { - var escalate = index % 2 == 0; - var session = harness.NewSession(); - session.State.TryWrite("escalate", escalate); - - // Nothing starts until all 26 are ready, so the fan-out is really simultaneous. - gate.SignalAndWait(token); - - var turn = await session.RunTurnAsync($"conversation {index}", token).ConfigureAwait(false); - return (Escalate: escalate, turn.ReplyText); - }, - token)); - - var results = await Task.WhenAll(conversations); - - // Rule 16: one compiled agent, and no code path compiles one for each conversation. - Assert.Equal(1, harness.CompileCount); - - // No conversation read the state of another one. Thirteen went each way, and none went both. - Assert.All(results, result => Assert.Contains( - result.Escalate ? EscalatedReply : HandledReply, result.ReplyText, StringComparison.Ordinal)); - Assert.All(results, result => Assert.DoesNotContain( - result.Escalate ? HandledReply : EscalatedReply, result.ReplyText, StringComparison.Ordinal)); - Assert.Equal(FanOut / 2, results.Count(result => result.Escalate)); - } - - [Fact] - public async Task AGuardedEdgeWithNoFiledState_FailsLoudlyAndNeverAnswersFalse() - { - using Harness harness = new(); - - // The run goes straight at the shared graph, with no turn filed on it anywhere. A guarded - // edge that quietly became unconditional is the silent graph failure section 8.2 refuses - // to ship, so the wrapper throws instead. - var failure = await Record.ExceptionAsync(() => harness.Compiled.Agent.RunAsync( - "hello", cancellationToken: TestContext.Current.CancellationToken)); - - Assert.NotNull(failure); - Assert.Contains(GraphGuardGate.NoStateMessage, Flatten(failure), StringComparison.Ordinal); - } - - [Fact] - public void AGuardedGraph_KeepsTheNameOfTheDocument() - { - using Harness harness = new(); - - // The check that makes a missing state source loud sits in front of the graph, and it must - // not change what the graph is. The entry key names the compiled agent. - Assert.Equal("main", harness.Compiled.Agent.Name); - Assert.Equal(CompiledAgentShape.ExplicitGraph, harness.Compiled.Shape); - } - - [Fact] - public async Task Rule13_AGuardedGraph_YieldsItsFirstDeltaBeforeTheModelFinishes() - { - using Harness harness = new(holdEscalatedReply: true); - var session = harness.NewSession(); - session.State.TryWrite("escalate", true); - - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); - - string? first = null; - await foreach (var update in session.RunTurnStreamingAsync("hello", linked.Token)) - { - if (update.Text is not { Length: > 0 } text) - { - continue; - } - - first = text; - - // The reply reached us, so let the model finish. The order proves the seam still streams - // with the guard check in front of it. - harness.ReleaseEscalatedReply(); - break; - } - - harness.ReleaseEscalatedReply(); - - // The delta arrives before the run finishes, which is what rule 13 asks. It is the OUTPUT - // node's word and not the start node's: the caller hears the answer, never the graph - // deliberating its way to one, on the streaming path exactly as on the buffered one. - Assert.Equal("ESCALATED", first); - } - - [Fact] - public void AGuardedEdgeWithNoEvaluator_IsALoadTimeErrorThatNamesTheMissingSeam() - { - var document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); - using ScriptedChatClient client = new("ok"); - AgentCompilationContext context = new(new FakeChatClientFactory(client)); - - var failure = Assert.Throws( - () => ConfigurationCompiler.CompileAll(document, context)["main"]); - - Assert.Equal("/entries/main/graph/edges/0/when", failure.Pointer); - Assert.Contains("binds no guard evaluator", failure.Message, StringComparison.Ordinal); - } - - /// Reads one fault and every fault it wraps, as one string. - /// The fault the run reported. - /// Every message in the chain, joined. - private static string Flatten(Exception exception) - { - List messages = []; - for (Exception? current = exception; current is not null; current = current.InnerException) - { - messages.Add(current.Message); - if (current is AggregateException aggregate) - { - messages.AddRange(aggregate.InnerExceptions.Select(Flatten)); - } - } - - return string.Join(" | ", messages); - } - - /// - /// One compiled graph, wired the way the composition root wires it. - /// - /// - /// The seam is the one AddAgentCore bind: the shared guard evaluator. Nothing per conversation - /// is captured: the turn's snapshot rides each run. - /// - private sealed class Harness : IDisposable - { - private readonly ScriptedChatClient _router = new("ROUTED"); - private readonly ScriptedChatClient _human; - private readonly ScriptedChatClient _bot = new(HandledReply); - private readonly CompiledAgentRegistry _registry = new(); - private readonly ConversationSessionFactory _sessions; - - /// Compiles the guarded graph once, over three offline models. - /// - /// Whether the escalated node holds every fragment after the first. A test that asks for this - /// proves the reply reaches the caller before the model finishes. - /// - public Harness(bool holdEscalatedReply = false) - { - _human = new ScriptedChatClient(EscalatedReply, " and", " more.") - { - GateAfterFirstFragment = holdEscalatedReply, - }; - - var document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); - GuardEvaluator guards = new(document.Guards); - - RoutingChatClientFactory models = new(); - models.Route("router", _router); - models.Route("human", _human); - models.Route("bot", _bot); - - Compiled = _registry.GetOrCompile(document, "main", new AgentCompilationContext(models) + [Fact] + public void AGuardedEdge_PassesEveryOneOfTheEightChecks() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); + + // The defect this file closes: the document was valid and then failed to compile. Check 5 + // even proves the two guards exclusive, so the load has nothing left to object to. + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(document); + + Assert.Empty(result.Errors); + } + + [Fact] + public async Task AGuardedEdge_CompilesAndTakesTheEdgeTheStateNames() + { + using Harness harness = new(); + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", true); + + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + Assert.Contains(EscalatedReply, turn.ReplyText, StringComparison.Ordinal); + Assert.DoesNotContain(HandledReply, turn.ReplyText, StringComparison.Ordinal); + } + + [Fact] + public async Task AGuardedEdge_TakesTheOtherEdgeWhenTheStateSaysSo() + { + using Harness harness = new(); + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", false); + + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + Assert.Contains(HandledReply, turn.ReplyText, StringComparison.Ordinal); + Assert.DoesNotContain(EscalatedReply, turn.ReplyText, StringComparison.Ordinal); + } + + [Fact] + public async Task AGuardedEdge_TakesTheEdgeTheStateNamesWhileStreaming() + { + using Harness harness = new(); + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", true); + + List text = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync( + "hello", TestContext.Current.CancellationToken)) + { + text.Add(update.Text); + } + + // The turn's snapshot rides the run's own messages, so the streaming path needs no + // per-step scope to route: the gate reads what the entry filed before the first model call. + Assert.Contains(EscalatedReply, string.Concat(text), StringComparison.Ordinal); + Assert.DoesNotContain(HandledReply, string.Concat(text), StringComparison.Ordinal); + } + + [Fact] + public async Task Rule16_TwentySixSimultaneousConversations_EachTakeTheirOwnEdgeThroughOneCompiledGraph() + { + using Harness harness = new(); + CancellationToken token = TestContext.Current.CancellationToken; + using Barrier gate = new(FanOut); + + IEnumerable> conversations = Enumerable.Range(0, FanOut).Select(index => Task.Run( + async () => + { + bool escalate = index % 2 == 0; + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", escalate); + + // Nothing starts until all 26 are ready, so the fan-out is really simultaneous. + gate.SignalAndWait(token); + + TurnResult turn = await session.RunTurnAsync($"conversation {index}", token).ConfigureAwait(false); + return (Escalate: escalate, turn.ReplyText); + }, + token)); + + (bool Escalate, string ReplyText)[] results = await Task.WhenAll(conversations); + + // Rule 16: one compiled agent, and no code path compiles one for each conversation. + Assert.Equal(1, harness.CompileCount); + + // No conversation read the state of another one. Thirteen went each way, and none went both. + Assert.All(results, result => Assert.Contains( + result.Escalate ? EscalatedReply : HandledReply, result.ReplyText, StringComparison.Ordinal)); + Assert.All(results, result => Assert.DoesNotContain( + result.Escalate ? HandledReply : EscalatedReply, result.ReplyText, StringComparison.Ordinal)); + Assert.Equal(FanOut / 2, results.Count(result => result.Escalate)); + } + + [Fact] + public async Task AGuardedEdgeWithNoFiledState_FailsLoudlyAndNeverAnswersFalse() + { + using Harness harness = new(); + + // The run goes straight at the shared graph, with no turn filed on it anywhere. A guarded + // edge that quietly became unconditional is the silent graph failure section 8.2 refuses + // to ship, so the wrapper throws instead. + Exception? failure = await Record.ExceptionAsync(() => harness.Compiled.Agent.RunAsync( + "hello", cancellationToken: TestContext.Current.CancellationToken)); + + Assert.NotNull(failure); + Assert.Contains(GraphGuardGate.NoStateMessage, Flatten(failure), StringComparison.Ordinal); + } + + [Fact] + public void AGuardedGraph_KeepsTheNameOfTheDocument() + { + using Harness harness = new(); + + // The check that makes a missing state source loud sits in front of the graph, and it must + // not change what the graph is. The entry key names the compiled agent. + Assert.Equal("main", harness.Compiled.Agent.Name); + Assert.Equal(CompiledAgentShape.ExplicitGraph, harness.Compiled.Shape); + } + + [Fact] + public async Task Rule13_AGuardedGraph_YieldsItsFirstDeltaBeforeTheModelFinishes() + { + using Harness harness = new(holdEscalatedReply: true); + ConversationSession session = harness.NewSession(); + _ = session.State.TryWrite("escalate", true); + + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); + + string? first = null; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("hello", linked.Token)) + { + if (update.Text is not { Length: > 0 } text) + { + continue; + } + + first = text; + + // The reply reached us, so let the model finish. The order proves the seam still streams + // with the guard check in front of it. + harness.ReleaseEscalatedReply(); + break; + } + + harness.ReleaseEscalatedReply(); + + // The delta arrives before the run finishes, which is what rule 13 asks. It is the OUTPUT + // node's word and not the start node's: the caller hears the answer, never the graph + // deliberating its way to one, on the streaming path exactly as on the buffered one. + Assert.Equal("ESCALATED", first); + } + + [Fact] + public void AGuardedEdgeWithNoEvaluator_IsALoadTimeErrorThatNamesTheMissingSeam() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); + using ScriptedChatClient client = new("ok"); + AgentCompilationContext context = new(new FakeChatClientFactory(client)); + + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationCompiler.CompileAll(document, context)["main"]); + + Assert.Equal("/entries/main/graph/edges/0/when", failure.Pointer); + Assert.Contains("binds no guard evaluator", failure.Message, StringComparison.Ordinal); + } + + /// Reads one fault and every fault it wraps, as one string. + /// The fault the run reported. + /// Every message in the chain, joined. + private static string Flatten(Exception exception) + { + List messages = []; + for (Exception? current = exception; current is not null; current = current.InnerException) + { + messages.Add(current.Message); + if (current is AggregateException aggregate) + { + messages.AddRange(aggregate.InnerExceptions.Select(Flatten)); + } + } + + return string.Join(" | ", messages); + } + + /// + /// One compiled graph, wired the way the composition root wires it. + /// + /// + /// The seam is the one AddAgentCore bind: the shared guard evaluator. Nothing per conversation + /// is captured: the turn's snapshot rides each run. + /// + private sealed class Harness : IDisposable + { + private readonly ScriptedChatClient _router = new("ROUTED"); + private readonly ScriptedChatClient _human; + private readonly ScriptedChatClient _bot = new(HandledReply); + private readonly CompiledAgentRegistry _registry = new(); + private readonly ConversationSessionFactory _sessions; + + /// Compiles the guarded graph once, over three offline models. + /// + /// Whether the escalated node holds every fragment after the first. A test that asks for this + /// proves the reply reaches the caller before the model finishes. + /// + public Harness(bool holdEscalatedReply = false) { - Guards = guards, - }); + _human = new ScriptedChatClient(EscalatedReply, " and", " more.") + { + GateAfterFirstFragment = holdEscalatedReply, + }; - _sessions = new ConversationSessionFactory(Compiled, guards); - } + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(GuardedGraphYaml); + GuardEvaluator guards = new(document.Guards); - /// Gets the one compiled agent every conversation shares. - public CompiledAgent Compiled { get; } + RoutingChatClientFactory models = new(); + _ = models.Route("router", _router); + _ = models.Route("human", _human); + _ = models.Route("bot", _bot); - /// Gets how many times the registry ran the compile table. - public int CompileCount => _registry.CompileCount; + Compiled = _registry.GetOrCompile(document, "main", new AgentCompilationContext(models) + { + Guards = guards, + }); - /// Builds the session of one more conversation. - /// The session. - public ConversationSession NewSession() => _sessions.Create(); + _sessions = new ConversationSessionFactory(Compiled, guards); + } - /// Lets the rest of the escalated reply flow. - public void ReleaseEscalatedReply() => _human.OpenGate(); + /// Gets the one compiled agent every conversation shares. + public CompiledAgent Compiled { get; } - public void Dispose() - { - _router.Dispose(); - _human.Dispose(); - _bot.Dispose(); - } - } + /// Gets how many times the registry ran the compile table. + public int CompileCount => _registry.CompileCount; - } + /// Builds the session of one more conversation. + /// The session. + public ConversationSession NewSession() + { + return _sessions.Create(); + } + + /// Lets the rest of the escalated reply flow. + public void ReleaseEscalatedReply() + { + _human.OpenGate(); + } + + public void Dispose() + { + _router.Dispose(); + _human.Dispose(); + _bot.Dispose(); + } + } + + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/HarnessCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/HarnessCompilationTests.cs index dfc5b2f1..3c8cdcb3 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/HarnessCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/HarnessCompilationTests.cs @@ -7,145 +7,145 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The todos: / mode: switches reaching a compiled agent's context providers, and the -/// tools they add reaching the model. -/// -public sealed class HarnessCompilationTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private static readonly string[] ExpectedTodoTools = - ["todos_add", "todos_complete", "todos_remove", "todos_get_remaining", "todos_get_all"]; + /// + /// The todos: / mode: switches reaching a compiled agent's context providers, and the + /// tools they add reaching the model. + /// + public sealed class HarnessCompilationTests + { + private static readonly string[] ExpectedTodoTools = + ["todos_add", "todos_complete", "todos_remove", "todos_get_remaining", "todos_get_all"]; - private static readonly string[] ExpectedModeTools = ["mode_set", "mode_get"]; + private static readonly string[] ExpectedModeTools = ["mode_set", "mode_get"]; - [Fact] - public void Compile_TodosTrue_GetsATodoProvider() - { - var providers = Providers(CompileOne(withTodos: true, withMode: false)); + [Fact] + public void Compile_TodosTrue_GetsATodoProvider() + { + IEnumerable providers = Providers(CompileOne(withTodos: true, withMode: false)); - Assert.Contains(providers, provider => provider is TodoProvider); - } + Assert.Contains(providers, provider => provider is TodoProvider); + } - [Fact] - public void Compile_ModeTrue_GetsAnAgentModeProvider() - { - var providers = Providers(CompileOne(withTodos: false, withMode: true)); + [Fact] + public void Compile_ModeTrue_GetsAnAgentModeProvider() + { + IEnumerable providers = Providers(CompileOne(withTodos: false, withMode: true)); - Assert.Contains(providers, provider => provider is AgentModeProvider); - } + Assert.Contains(providers, provider => provider is AgentModeProvider); + } - [Fact] - public void Compile_NeitherKey_GetsNeitherProvider() - { - var providers = Providers(CompileOne(withTodos: false, withMode: false)); + [Fact] + public void Compile_NeitherKey_GetsNeitherProvider() + { + IEnumerable providers = Providers(CompileOne(withTodos: false, withMode: false)); - Assert.DoesNotContain(providers, provider => provider is TodoProvider); - Assert.DoesNotContain(providers, provider => provider is AgentModeProvider); - } + Assert.DoesNotContain(providers, provider => provider is TodoProvider); + Assert.DoesNotContain(providers, provider => provider is AgentModeProvider); + } - [Fact] - public async Task Compile_TodosTrue_ModelSeesTheFiveTodoTools() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public async Task Compile_TodosTrue_ModelSeesTheFiveTodoTools() + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - Items = [new AgentConfiguration { Id = "only", Todos = true }], + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only", Todos = true }], + }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - var agent = Assert.Single(compiled.Agents.Values); - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); + AIAgent agent = Assert.Single(compiled.Agents.Values); + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); - await agent.RunAsync("hi", session, cancellationToken: token); + _ = await agent.RunAsync("hi", session, cancellationToken: token); - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - Assert.Equal(ExpectedTodoTools, toolNames, StringComparer.Ordinal); - } + Assert.Equal(ExpectedTodoTools, toolNames, StringComparer.Ordinal); + } - [Fact] - public async Task Compile_ModeTrue_ModelSeesTheTwoModeTools() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public async Task Compile_ModeTrue_ModelSeesTheTwoModeTools() + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - Items = [new AgentConfiguration { Id = "only", Mode = true }], + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only", Mode = true }], + }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - var agent = Assert.Single(compiled.Agents.Values); - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); + AIAgent agent = Assert.Single(compiled.Agents.Values); + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); - await agent.RunAsync("hi", session, cancellationToken: token); + _ = await agent.RunAsync("hi", session, cancellationToken: token); - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - Assert.Equal(ExpectedModeTools, toolNames, StringComparer.Ordinal); - } + Assert.Equal(ExpectedModeTools, toolNames, StringComparer.Ordinal); + } - [Fact] - public void Compile_TodosAndModeTrue_HarnessStateKeysIsTheUnionOfBoth() - { - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration + [Fact] + public void Compile_TodosAndModeTrue_HarnessStateKeysIsTheUnionOfBoth() + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - Items = [new AgentConfiguration { Id = "only", Todos = true, Mode = true }], + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only", Todos = true, Mode = true }], + }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - Assert.Equal( - new HashSet(StringComparer.Ordinal) - { - new TodoProvider().StateKeys[0], - new AgentModeProvider().StateKeys[0], - }, - compiled.HarnessStateKeys); - } + Assert.Equal( + new HashSet(StringComparer.Ordinal) + { + new TodoProvider().StateKeys[0], + new AgentModeProvider().StateKeys[0], + }, + compiled.HarnessStateKeys); + } - [Fact] - public void Compile_NeitherTodosNorMode_HarnessStateKeysIsEmpty() - { - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration + [Fact] + public void Compile_NeitherTodosNorMode_HarnessStateKeysIsEmpty() + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - Items = [new AgentConfiguration { Id = "only" }], + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only" }], + }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - Assert.Empty(compiled.HarnessStateKeys); - } + Assert.Empty(compiled.HarnessStateKeys); + } - private const string TwoAgentsOnlyOneWithTodosYaml = - """ + private const string TwoAgentsOnlyOneWithTodosYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -162,20 +162,20 @@ public void Compile_NeitherTodosNorMode_HarnessStateKeysIsEmpty() - { id: done, agent: plain, terminal: true } """; - [Fact] - public void Compile_TwoAgentsOnlyOneWithTodos_HarnessStateKeysHasTheTodoKey() - { - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(TwoAgentsOnlyOneWithTodosYaml), - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + [Fact] + public void Compile_TwoAgentsOnlyOneWithTodos_HarnessStateKeysHasTheTodoKey() + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(TwoAgentsOnlyOneWithTodosYaml), + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - Assert.Equal( - new HashSet(StringComparer.Ordinal) { new TodoProvider().StateKeys[0] }, - compiled.HarnessStateKeys); - } + Assert.Equal( + new HashSet(StringComparer.Ordinal) { new TodoProvider().StateKeys[0] }, + compiled.HarnessStateKeys); + } - private const string ShellYaml = - """ + private const string ShellYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -185,8 +185,8 @@ public void Compile_TwoAgentsOnlyOneWithTodos_HarnessStateKeysHasTheTodoKey() agent: only """; - private const string ShellBadPolicyYaml = - """ + private const string ShellBadPolicyYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -196,110 +196,111 @@ public void Compile_TwoAgentsOnlyOneWithTodos_HarnessStateKeysHasTheTodoKey() agent: only """; - [Fact] - public void Compile_ShellWithNoWorkspaceRoot_FailsNamingTheShellPointer() - { - var document = ConfigurationLoader.LoadYaml(ShellYaml); - - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))))["main"]); - - Assert.Equal("/agents/items/0/shell", failure.Pointer); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void Compile_ShellWithABadPolicyRegex_FailsNamingTheShellPolicyPointerAndThePattern() - { - var document = ConfigurationLoader.LoadYaml(ShellBadPolicyYaml); + [Fact] + public void Compile_ShellWithNoWorkspaceRoot_FailsNamingTheShellPointer() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ShellYaml); - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) - { - WorkspaceRoot = Path.Combine(Path.GetTempPath(), "agentcore-shell-" + Guid.NewGuid().ToString("N")), - })["main"]); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))))["main"]); - Assert.Equal("/agents/items/0/shell/policy", failure.Pointer); - Assert.Contains("'('", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/0/shell", failure.Pointer); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Compile_ShellWithAValidBlockAndARoot_Compiles() - { - var root = Path.Combine(Path.GetTempPath(), "agentcore-shell-" + Guid.NewGuid().ToString("N")); - try + [Fact] + public void Compile_ShellWithABadPolicyRegex_FailsNamingTheShellPolicyPointerAndThePattern() { - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ShellYaml), + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ShellBadPolicyYaml); + + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + document, new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) { - WorkspaceRoot = root, - })["main"]; + WorkspaceRoot = Path.Combine(Path.GetTempPath(), "agentcore-shell-" + Guid.NewGuid().ToString("N")), + })["main"]); - Assert.Single(compiled.Agents.Values); - Assert.Empty(compiled.HarnessStateKeys); + Assert.Equal("/agents/items/0/shell/policy", failure.Pointer); + Assert.Contains("'('", failure.Message, StringComparison.Ordinal); } - finally + + [Fact] + public void Compile_ShellWithAValidBlockAndARoot_Compiles() { - if (Directory.Exists(root)) + string root = Path.Combine(Path.GetTempPath(), "agentcore-shell-" + Guid.NewGuid().ToString("N")); + try + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ShellYaml), + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) + { + WorkspaceRoot = root, + })["main"]; + + _ = Assert.Single(compiled.Agents.Values); + Assert.Empty(compiled.HarnessStateKeys); + } + finally { - Directory.Delete(root, recursive: true); + if (Directory.Exists(root)) + { + Directory.Delete(root, recursive: true); + } } } - } - [Fact] - public void Compile_ShellBlock_GetsAToolProviderAndAnEnvironmentProvider() - { - var root = Path.Combine(Path.GetTempPath(), "agentcore-shell-env-" + Guid.NewGuid().ToString("N")); - try + [Fact] + public void Compile_ShellBlock_GetsAToolProviderAndAnEnvironmentProvider() { - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ShellYaml), - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) - { - WorkspaceRoot = root, - })["main"]; + string root = Path.Combine(Path.GetTempPath(), "agentcore-shell-env-" + Guid.NewGuid().ToString("N")); + try + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ShellYaml), + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) + { + WorkspaceRoot = root, + })["main"]; - var providers = Providers(Assert.Single(compiled.Agents.Values)); + IEnumerable providers = Providers(Assert.Single(compiled.Agents.Values)); - Assert.Contains(providers, provider => provider is ConversationShellProvider); - Assert.Contains(providers, provider => provider is ConversationShellEnvironmentProvider); - } - finally - { - if (Directory.Exists(root)) + Assert.Contains(providers, provider => provider is ConversationShellProvider); + Assert.Contains(providers, provider => provider is ConversationShellEnvironmentProvider); + } + finally { - Directory.Delete(root, recursive: true); + if (Directory.Exists(root)) + { + Directory.Delete(root, recursive: true); + } } } - } - private static AIAgent CompileOne(bool withTodos, bool withMode) - { - using SequencedChatClient reply = new("hello there."); + private static AIAgent CompileOne(bool withTodos, bool withMode) + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, - Agents = new AgentsConfiguration + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - Items = [new AgentConfiguration { Id = "only", Todos = withTodos, Mode = withMode }], + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "only" } }, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only", Todos = withTodos, Mode = withMode }], + }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - return Assert.Single(compiled.Agents.Values); - } + return Assert.Single(compiled.Agents.Values); + } - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs index 3f8e2329..6f58e3ed 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/HostedWebSearchDropTests.cs @@ -5,224 +5,242 @@ using AgentCore.Application.Tools.Builtin; using AgentCore.Application.Tools.Registry; using AgentCore.TestSupport; -using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The hosted markers reaching, or not reaching, one compiled agent. -/// -public sealed class HostedWebSearchDropTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string SearchToolId = BuiltinToolNames.WebSearch; - - [Fact] - public void Compile_CapableModel_KeepsTheTool() + /// + /// The hosted markers reaching, or not reaching, one compiled agent. + /// + public sealed class HostedWebSearchDropTests { - var tools = Tools(agent: "reply", capable: true); + private const string SearchToolId = BuiltinToolNames.WebSearch; - Assert.Single(tools.OfType()); - } + [Fact] + public void Compile_CapableModel_KeepsTheTool() + { + List tools = Tools(agent: "reply", capable: true); - [Fact] - public void Compile_TunedMarker_ReachesTheModel() - { - HostedWebSearchTool tuned = new(new Dictionary { ["memory_limit"] = "4g" }); - var tools = BuildAgentTools("reply", model: null, ScreeningChatClientFactory(tuned)); + _ = Assert.Single(tools.OfType()); + } - Assert.Same(tuned, Assert.Single(tools.OfType())); - } + [Fact] + public void Compile_TunedMarker_ReachesTheModel() + { + HostedWebSearchTool tuned = new(new Dictionary { ["memory_limit"] = "4g" }); + List tools = BuildAgentTools("reply", model: null, ScreeningChatClientFactory(tuned)); - [Fact] - public void Compile_IncapableModel_DropsTheTool() - { - var tools = Tools(agent: "reply", capable: false); + Assert.Same(tuned, Assert.Single(tools.OfType())); + } - Assert.Empty(tools.OfType()); - } + [Fact] + public void Compile_IncapableModel_DropsTheTool() + { + List tools = Tools(agent: "reply", capable: false); - [Fact] - public void Compile_IncapableModel_LogsOneWarning() - { - var (tools, logs) = ToolsAndLogs(agent: "reply", capable: false); + Assert.Empty(tools.OfType()); + } - Assert.Empty(tools.OfType()); - var warning = Assert.Single(logs); - Assert.Contains("reply", warning, StringComparison.Ordinal); - Assert.Contains("web.search", warning, StringComparison.Ordinal); - } + [Fact] + public void Compile_IncapableModel_LogsOneWarning() + { + (List? tools, List? logs) = ToolsAndLogs(agent: "reply", capable: false); - [Fact] - public void Compile_IncapableModel_DoesNotThrow() - { - // An agent with no web search still answers. This never stops a host. - Assert.Null(Record.Exception(() => Tools(agent: "reply", capable: false))); - } + Assert.Empty(tools.OfType()); + string warning = Assert.Single(logs); + Assert.Contains("reply", warning, StringComparison.Ordinal); + Assert.Contains("web.search", warning, StringComparison.Ordinal); + } - [Fact] - public void Compile_TwoAgentsOnDifferentModels_OnlyTheCapableOneKeepsIt() - { - var (capable, incapable) = TwoAgents(); + [Fact] + public void Compile_IncapableModel_DoesNotThrow() + { + // An agent with no web search still answers. This never stops a host. + Assert.Null(Record.Exception(() => Tools(agent: "reply", capable: false))); + } - Assert.Single(capable.OfType()); - Assert.Empty(incapable.OfType()); - } + [Fact] + public void Compile_TwoAgentsOnDifferentModels_OnlyTheCapableOneKeepsIt() + { + (List? capable, List? incapable) = TwoAgents(); - [Fact] - public void Compile_HostSuppliedHostedTool_IsDroppedByTheSameRule() - { - // The check tests the tool type, not the builtin name, so a hosted search tool arriving - // from a host's own IToolSource is covered with no second place to forget. - var tools = ToolsFromHostSource(capable: false); + _ = Assert.Single(capable.OfType()); + Assert.Empty(incapable.OfType()); + } - Assert.Empty(tools.OfType()); - } + [Fact] + public void Compile_HostSuppliedHostedTool_IsDroppedByTheSameRule() + { + // The check tests the tool type, not the builtin name, so a hosted search tool arriving + // from a host's own IToolSource is covered with no second place to forget. + List tools = ToolsFromHostSource(capable: false); - [Fact] - public async Task Compile_TwoAgentsOnDifferentModels_ThroughTheRealCompiler_OnlyTheCapableOneKeepsIt() - { - // AgentToolCompiler.Build takes the model as a parameter, and the six tests above call it - // directly. None of them exercises the expression that picks that parameter per agent - // (ConfigurationCompiler's item.Model ?? section.Defaults?.Model), so this one goes through - // ConfigurationCompiler.Compile on a document with two agents pinned to two different models, - // and reads back what each agent actually sent its chat client. - const string capableRef = "vendor-a"; - const string incapableRef = "vendor-b"; - - using SequencedChatClient reply = new("hello there."); - var registry = BuildRegistry([new BuiltinToolSource(new BuiltinToolPorts(null))], [SearchTool()]); - - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Tools = [SearchTool()], - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration { Id = "capable", Model = new ModelReference { Ref = capableRef }, Tools = [SearchToolId] }, - new AgentConfiguration { Id = "incapable", Model = new ModelReference { Ref = incapableRef }, Tools = [SearchToolId] }, - ], - }, - Entries = new Dictionary + Assert.Empty(tools.OfType()); + } + + [Fact] + public async Task Compile_TwoAgentsOnDifferentModels_ThroughTheRealCompiler_OnlyTheCapableOneKeepsIt() + { + // AgentToolCompiler.Build takes the model as a parameter, and the six tests above call it + // directly. None of them exercises the expression that picks that parameter per agent + // (ConfigurationCompiler's item.Model ?? section.Defaults?.Model), so this one goes through + // ConfigurationCompiler.Compile on a document with two agents pinned to two different models, + // and reads back what each agent actually sent its chat client. + const string capableRef = "vendor-a"; + const string incapableRef = "vendor-b"; + + using SequencedChatClient reply = new("hello there."); + ToolRegistry registry = BuildRegistry([new BuiltinToolSource(new BuiltinToolPorts(null))], [SearchTool()]); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - ["main"] = new EntryConfiguration + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Tools = [SearchTool()], + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration { Id = "capable", Model = new ModelReference { Ref = capableRef }, Tools = [SearchToolId] }, + new AgentConfiguration { Id = "incapable", Model = new ModelReference { Ref = incapableRef }, Tools = [SearchToolId] }, + ], + }, + Entries = new Dictionary { - Policy = new PolicyConfiguration + ["main"] = new EntryConfiguration { - Initial = "opening", - Stages = - [ - new StageConfiguration { Id = "opening", Agent = "capable" }, - new StageConfiguration { Id = "closing", Agent = "incapable" }, - ], + Policy = new PolicyConfiguration + { + Initial = "opening", + Stages = + [ + new StageConfiguration { Id = "opening", Agent = "capable" }, + new StageConfiguration { Id = "closing", Agent = "incapable" }, + ], + }, }, }, }, - }, - new AgentCompilationContext(RoutingCapabilityChatClientFactory(capableRef, reply)) { Tools = registry })["main"]; - - var token = TestContext.Current.CancellationToken; - await compiled.Agents["capable"].RunAsync("hi", cancellationToken: token); - await compiled.Agents["incapable"].RunAsync("hi", cancellationToken: token); + new AgentCompilationContext(RoutingCapabilityChatClientFactory(capableRef, reply)) { Tools = registry })["main"]; - Assert.Single((reply.Options[0]?.Tools ?? []).OfType()); - Assert.Empty((reply.Options[1]?.Tools ?? []).OfType()); - } + CancellationToken token = TestContext.Current.CancellationToken; + _ = await compiled.Agents["capable"].RunAsync("hi", cancellationToken: token); + _ = await compiled.Agents["incapable"].RunAsync("hi", cancellationToken: token); - private static ToolConfiguration SearchTool() - => new() { Id = SearchToolId, Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }; + _ = Assert.Single((reply.Options[0]?.Tools ?? []).OfType()); + Assert.Empty((reply.Options[1]?.Tools ?? []).OfType()); + } - private static List Tools(string agent, bool capable) - => BuildAgentTools(agent, model: null, SearchTool(), ScreeningChatClientFactory(Marker(capable))); + private static ToolConfiguration SearchTool() + { + return new() { Id = SearchToolId, Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }; + } - private static HostedWebSearchTool? Marker(bool capable) => capable ? new HostedWebSearchTool() : null; + private static List Tools(string agent, bool capable) + { + return BuildAgentTools(agent, model: null, SearchTool(), ScreeningChatClientFactory(Marker(capable))); + } - private static (List Tools, List Logs) ToolsAndLogs(string agent, bool capable) - { - RecordingLoggerFactory loggers = new(); - var tools = BuildAgentTools(agent, model: null, SearchTool(), ScreeningChatClientFactory(Marker(capable)), loggers); - return (tools, [.. loggers.Of(18).Select(line => line.Message)]); - } + private static HostedWebSearchTool? Marker(bool capable) + { + return capable ? new HostedWebSearchTool() : null; + } - private static (List Capable, List Incapable) TwoAgents() - { - const string capableRef = "vendor-a"; - const string incapableRef = "vendor-b"; + private static (List Tools, List Logs) ToolsAndLogs(string agent, bool capable) + { + RecordingLoggerFactory loggers = new(); + List tools = BuildAgentTools(agent, model: null, SearchTool(), ScreeningChatClientFactory(Marker(capable)), loggers); + return (tools, [.. loggers.Of(18).Select(line => line.Message)]); + } - var factory = RoutingCapabilityChatClientFactory(capableRef); + private static (List Capable, List Incapable) TwoAgents() + { + const string capableRef = "vendor-a"; + const string incapableRef = "vendor-b"; - var capable = BuildAgentTools("capable", new ModelReference { Ref = capableRef }, factory); - var incapable = BuildAgentTools("incapable", new ModelReference { Ref = incapableRef }, factory); - return (capable, incapable); - } + LambdaChatClientFactory factory = RoutingCapabilityChatClientFactory(capableRef); - private static List ToolsFromHostSource(bool capable) - { - const string hostToolId = "vendor_search"; + List capable = BuildAgentTools("capable", new ModelReference { Ref = capableRef }, factory); + List incapable = BuildAgentTools("incapable", new ModelReference { Ref = incapableRef }, factory); + return (capable, incapable); + } - AgentConfiguration item = new() { Id = "reply", Tools = [hostToolId] }; - Dictionary declared = new(StringComparer.Ordinal); - var registry = BuildRegistry([new HostSearchToolSource(hostToolId)], []); + private static List ToolsFromHostSource(bool capable) + { + const string hostToolId = "vendor_search"; - AgentCompilationContext context = new(ScreeningChatClientFactory(Marker(capable))) { Tools = registry }; + AgentConfiguration item = new() { Id = "reply", Tools = [hostToolId] }; + Dictionary declared = new(StringComparer.Ordinal); + ToolRegistry registry = BuildRegistry([new HostSearchToolSource(hostToolId)], []); - return AgentToolCompiler.Build(item, model: null, declared, context, "/agents/items/0", static _ => null) ?? []; - } + AgentCompilationContext context = new(ScreeningChatClientFactory(Marker(capable))) { Tools = registry }; + return AgentToolCompiler.Build(item, model: null, declared, context, "/agents/items/0", static _ => null) ?? []; + } - private static List BuildAgentTools( - string agentId, - ModelReference? model, - IChatClientFactory chatClients, - RecordingLoggerFactory? loggers = null) - => BuildAgentTools(agentId, model, SearchTool(), chatClients, loggers); - private static List BuildAgentTools( - string agentId, - ModelReference? model, - ToolConfiguration declared, - IChatClientFactory chatClients, - RecordingLoggerFactory? loggers = null) - { - AgentConfiguration item = new() { Id = agentId, Tools = [declared.Id] }; - Dictionary declaredById = new(StringComparer.Ordinal) { [declared.Id] = declared }; - var registry = BuildRegistry([new BuiltinToolSource(new BuiltinToolPorts(null))], [declared]); + private static List BuildAgentTools( + string agentId, + ModelReference? model, + IChatClientFactory chatClients, + RecordingLoggerFactory? loggers = null) + { + return BuildAgentTools(agentId, model, SearchTool(), chatClients, loggers); + } + + private static List BuildAgentTools( + string agentId, + ModelReference? model, + ToolConfiguration declared, + IChatClientFactory chatClients, + RecordingLoggerFactory? loggers = null) + { + AgentConfiguration item = new() { Id = agentId, Tools = [declared.Id] }; + Dictionary declaredById = new(StringComparer.Ordinal) { [declared.Id] = declared }; + ToolRegistry registry = BuildRegistry([new BuiltinToolSource(new BuiltinToolPorts(null))], [declared]); - AgentCompilationContext context = new(chatClients) { Tools = registry, Loggers = loggers }; + AgentCompilationContext context = new(chatClients) { Tools = registry, Loggers = loggers }; - return AgentToolCompiler.Build(item, model, declaredById, context, "/agents/items/0", static _ => null) ?? []; - } + return AgentToolCompiler.Build(item, model, declaredById, context, "/agents/items/0", static _ => null) ?? []; + } - private static ToolRegistry BuildRegistry(IEnumerable sources, IReadOnlyList declared) - { - AgentCoreConfiguration document = new() + private static ToolRegistry BuildRegistry(IEnumerable sources, IReadOnlyList declared) { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Tools = declared, - }; + AgentCoreConfiguration document = new() + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = declared, + }; - return ToolRegistryBuilder.BuildAsync(sources, new ToolSourceContext(document)).AsTask().GetAwaiter().GetResult(); - } + return ToolRegistryBuilder.BuildAsync(sources, new ToolSourceContext(document)).AsTask().GetAwaiter().GetResult(); + } - private sealed class HostSearchToolSource(string id) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - [new ToolRegistration(id, "A vendor's own hosted search.", () => new HostedWebSearchTool())]); - } + private sealed class HostSearchToolSource(string id) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>( + [new ToolRegistration(id, "A vendor's own hosted search.", () => new HostedWebSearchTool())]); + } + } - /// Admits any hosted tool for only. - private static LambdaChatClientFactory RoutingCapabilityChatClientFactory(string capableRef, IChatClient? client = null) => new( - client is null ? null : _ => client, - (marker, model) => string.Equals(model?.Ref, capableRef, StringComparison.Ordinal) ? marker : null); + /// Admits any hosted tool for only. + private static LambdaChatClientFactory RoutingCapabilityChatClientFactory(string capableRef, IChatClient? client = null) + { + return new( + client is null ? null : _ => client, + (marker, model) => string.Equals(model?.Ref, capableRef, StringComparison.Ordinal) ? marker : null); + } - /// Admits a hosted tool of 's type, answering with . - private static LambdaChatClientFactory ScreeningChatClientFactory(AITool? marker) => new( - hostedTool: (asked, _) => marker is not null && asked.GetType() == marker.GetType() ? marker : null); + /// Admits a hosted tool of 's type, answering with . + private static LambdaChatClientFactory ScreeningChatClientFactory(AITool? marker) + { + return new( + hostedTool: (asked, _) => marker is not null && asked.GetType() == marker.GetType() ? marker : null); + } + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderBindingTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderBindingTests.cs index b0b5567e..8604c860 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderBindingTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderBindingTests.cs @@ -10,16 +10,16 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// Where the knowledge: block becomes a bound provider. The block is per agent, so the -/// binding is too: one agent in a document can retrieve and its neighbour can pay nothing for it. -/// -public sealed class KnowledgeProviderBindingTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string KnowledgeYaml = - """ + /// + /// Where the knowledge: block becomes a bound provider. The block is per agent, so the + /// binding is too: one agent in a document can retrieve and its neighbour can pay nothing for it. + /// + public sealed class KnowledgeProviderBindingTests + { + private const string KnowledgeYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -29,8 +29,8 @@ public sealed class KnowledgeProviderBindingTests agent: only """; - private const string MixedYaml = - """ + private const string MixedYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -45,8 +45,8 @@ public sealed class KnowledgeProviderBindingTests - { id: closing, agent: quiet } """; - private const string FilterableYaml = - """ + private const string FilterableYaml = + """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -70,8 +70,8 @@ public sealed class KnowledgeProviderBindingTests agent: only """; - private const string NoKnowledgeYaml = - """ + private const string NoKnowledgeYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -81,125 +81,126 @@ public sealed class KnowledgeProviderBindingTests agent: only """; - [Fact] - public void AnAgentWithAKnowledgeBlock_CarriesBothProviders() - { - var agent = CompileOne(KnowledgeYaml, new StubKnowledgePort([])); + [Fact] + public void AnAgentWithAKnowledgeBlock_CarriesBothProviders() + { + AIAgent agent = CompileOne(KnowledgeYaml, new StubKnowledgePort([])); - Assert.Contains(Providers(agent), provider => provider is TurnContextProvider); - Assert.Contains(Providers(agent), provider => provider is KnowledgePrefetchProvider); - } + Assert.Contains(Providers(agent), provider => provider is TurnContextProvider); + Assert.Contains(Providers(agent), provider => provider is KnowledgePrefetchProvider); + } - [Fact] - public void AnAgentWithNoKnowledgeBlock_CarriesOnlyTheTurnProvider() - { - var agent = CompileOne(NoKnowledgeYaml, new StubKnowledgePort([])); + [Fact] + public void AnAgentWithNoKnowledgeBlock_CarriesOnlyTheTurnProvider() + { + AIAgent agent = CompileOne(NoKnowledgeYaml, new StubKnowledgePort([])); - Assert.DoesNotContain(Providers(agent), provider => provider is FacetFilterProvider or KnowledgePrefetchProvider); - } + Assert.DoesNotContain(Providers(agent), provider => provider is FacetFilterProvider or KnowledgePrefetchProvider); + } - [Fact] - public void OnlyTheAgentThatDeclaredTheBlock_Retrieves() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public void OnlyTheAgentThatDeclaredTheBlock_Retrieves() + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(MixedYaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) - { - Knowledge = new StubKnowledgePort([]), - })["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(MixedYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) + { + Knowledge = new StubKnowledgePort([]), + })["main"]; - Assert.Contains(Providers(compiled.Agents["reader"]), provider => provider is FacetFilterProvider); - Assert.DoesNotContain(Providers(compiled.Agents["quiet"]), provider => provider is FacetFilterProvider or KnowledgePrefetchProvider); - } + Assert.Contains(Providers(compiled.Agents["reader"]), provider => provider is FacetFilterProvider); + Assert.DoesNotContain(Providers(compiled.Agents["quiet"]), provider => provider is FacetFilterProvider or KnowledgePrefetchProvider); + } - [Fact] - public async Task TheAgentsOwnSettings_ReachTheProviderThatWasBound() - { - // A compiler that composed the block and then bound something else would attach a provider - // that works and silently ignores every key the document set. - using SequencedChatClient reply = new("hello there."); + [Fact] + public async Task TheAgentsOwnSettings_ReachTheProviderThatWasBound() + { + // A compiler that composed the block and then bound something else would attach a provider + // that works and silently ignores every key the document set. + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(MixedYaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) - { - Knowledge = new StubKnowledgePort([]), - })["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(MixedYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) + { + Knowledge = new StubKnowledgePort([]), + })["main"]; - var reader = compiled.Agents["reader"]; - var provider = Assert.Single(Providers(reader).OfType()); + AIAgent reader = compiled.Agents["reader"]; + FacetFilterProvider provider = Assert.Single(Providers(reader).OfType()); #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(reader, null, new AIContext()); + AIContextProvider.InvokingContext context = new(reader, null, new AIContext()); #pragma warning restore MAAI001 - var result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + AIContext result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - // mode: tool, from the document. Anything else would have prefetched instead. - Assert.NotNull(result.Tools); - Assert.Single(result.Tools); - } + // mode: tool, from the document. Anything else would have prefetched instead. + Assert.NotNull(result.Tools); + _ = Assert.Single(result.Tools); + } - [Fact] - public void AKnowledgeBlockOverAHostThatBoundNoPort_FailsTheStart() - { - // Ruling 17a. Compiling this to an agent with no provider is the silent fail-open the A16 - // notice exists to eliminate: it answers from its own weights and says so to nobody. The - // failure names the agent and the missing seam, so the deployer knows which half to fix. - var failure = Assert.Throws( - () => CompileOne(KnowledgeYaml, port: null)); - - Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); - Assert.Contains("no knowledge vendor", failure.Message, StringComparison.Ordinal); - Assert.Equal("/agents/items/0/knowledge", Assert.Single(failure.Errors).Pointer); - } + [Fact] + public void AKnowledgeBlockOverAHostThatBoundNoPort_FailsTheStart() + { + // Ruling 17a. Compiling this to an agent with no provider is the silent fail-open the A16 + // notice exists to eliminate: it answers from its own weights and says so to nobody. The + // failure names the agent and the missing seam, so the deployer knows which half to fix. + ConfigurationLoadException failure = Assert.Throws( + () => CompileOne(KnowledgeYaml, port: null)); + + Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); + Assert.Contains("no knowledge vendor", failure.Message, StringComparison.Ordinal); + Assert.Equal("/agents/items/0/knowledge", Assert.Single(failure.Errors).Pointer); + } - [Fact] - public async Task AFilterableFacet_ReachesTheSearchToolTheAgentIsGiven() - { - // The declaration crosses four layers before the model sees it: the document schema has to - // allow the block, the record has to bind it, the compiler has to carry it to the factory, - // and the factory has to wrap the function. Every one of those is silent when it drops it, - // and the agent then searches the whole corpus and nobody is told. - var agent = CompileOne(FilterableYaml, new StubKnowledgePort([])); - - List offered = []; - foreach (var provider in Providers(agent)) + [Fact] + public async Task AFilterableFacet_ReachesTheSearchToolTheAgentIsGiven() { + // The declaration crosses four layers before the model sees it: the document schema has to + // allow the block, the record has to bind it, the compiler has to carry it to the factory, + // and the factory has to wrap the function. Every one of those is silent when it drops it, + // and the agent then searches the whole corpus and nobody is told. + AIAgent agent = CompileOne(FilterableYaml, new StubKnowledgePort([])); + + List offered = []; + foreach (AIContextProvider provider in Providers(agent)) + { #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(agent, null, new AIContext()); + AIContextProvider.InvokingContext context = new(agent, null, new AIContext()); #pragma warning restore MAAI001 - var result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - offered.AddRange((result.Tools ?? []).OfType()); + AIContext result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + offered.AddRange((result.Tools ?? []).OfType()); + } + + AIFunction tool = Assert.Single(offered); + IEnumerable keys = tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("items").GetProperty("properties").GetProperty("key") + .GetProperty("enum") + .EnumerateArray() + .Select(value => value.GetString()); + + Assert.Equal(["model"], keys); } - var tool = Assert.Single(offered); - var keys = tool.JsonSchema - .GetProperty("properties").GetProperty("filters") - .GetProperty("items").GetProperty("properties").GetProperty("key") - .GetProperty("enum") - .EnumerateArray() - .Select(value => value.GetString()); - - Assert.Equal(["model"], keys); - } - - private static AIAgent CompileOne(string yaml, IKnowledgeRetrievalPort? port) - { - using SequencedChatClient reply = new("hello there."); + private static AIAgent CompileOne(string yaml, IKnowledgeRetrievalPort? port) + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port })["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port })["main"]; - return Assert.Single(compiled.Agents.Values); - } + return Assert.Single(compiled.Agents.Values); + } - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderSchemaTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderSchemaTests.cs index 17cbdf66..4191c69e 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderSchemaTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/KnowledgeProviderSchemaTests.cs @@ -2,21 +2,21 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The providers.knowledge block. It ships no payload field names at all, so the block a deployment -/// writes is the only description of its collection that exists. -/// -/// -/// This file used to assert the opposite: that every unwritten field took the name one particular -/// ingester happened to use. That made one corpus's naming the framework's, and made a mismapped -/// role silent instead of loud. The assertions below are the inversion of that. -/// -public sealed class KnowledgeProviderSchemaTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string MinimalYaml = - """ + /// + /// The providers.knowledge block. It ships no payload field names at all, so the block a deployment + /// writes is the only description of its collection that exists. + /// + /// + /// This file used to assert the opposite: that every unwritten field took the name one particular + /// ingester happened to use. That made one corpus's naming the framework's, and made a mismapped + /// role silent instead of loud. The assertions below are the inversion of that. + /// + public sealed class KnowledgeProviderSchemaTests + { + private const string MinimalYaml = + """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -32,8 +32,8 @@ public sealed class KnowledgeProviderSchemaTests agent: only """; - private const string FullYaml = - """ + private const string FullYaml = + """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -70,8 +70,8 @@ public sealed class KnowledgeProviderSchemaTests agent: only """; - private const string UnknownKeyYaml = - """ + private const string UnknownKeyYaml = + """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -87,69 +87,69 @@ public sealed class KnowledgeProviderSchemaTests agent: only """; - [Fact] - public void ABlockThatNamesNoFields_MapsNothing() - { - var knowledge = Load(MinimalYaml).Providers!.Knowledge!; - - Assert.Null(knowledge.Vector); - - // Not an empty fields block with six null roles: no block at all. The document said nothing - // about this collection's payload, and nothing is what AgentCore knows about it. - Assert.Null(knowledge.Fields); - Assert.Null(knowledge.Scope.Template); - Assert.Null(knowledge.Links); - - // 'none' requires no term, so ranking is vector similarity alone. The old default named one - // corpus's error-code shape and applied it to every consumer's queries. - Assert.Equal("none", knowledge.Analyzer); - - // A wording IS shipped, unlike a field name: a citation has to read something, and the two - // roles it reads are the two the document already named. The wording is replaceable, and - // that is a different thing from being absent. - Assert.Equal("source-locator", knowledge.Citation); - // Cosine similarity on the dense prefetch. Measured 2026-09-02 on text-embedding-3-small: - // 0.25 let twelve of twenty cards through for a question the corpus did not answer; 0.35 let - // none through and kept every card of every answered question. - Assert.Equal(0.35, knowledge.ScoreFloor); - } - - [Fact] - public void EveryFieldBinds() - { - var knowledge = Load(FullYaml).Providers!.Knowledge!; - - Assert.Equal("embedding", knowledge.Vector); - Assert.Equal("doc_id", knowledge.Fields!.Id); - Assert.Equal("content", knowledge.Fields.Body); - Assert.Equal("content", knowledge.Fields.Lexical); - Assert.Equal("origin", knowledge.Fields.Source); - Assert.Equal("page", knowledge.Fields.Locator); - Assert.Equal("trust", knowledge.Fields.Authority); - Assert.Equal("{key}", knowledge.Scope.Template); - Assert.NotNull(knowledge.Links); - Assert.Equal("related", knowledge.Links!.Field); - Assert.Equal(KnowledgeLinkLookup.Filter, knowledge.Links.Lookup); - Assert.Equal("dns", knowledge.Links.Namespace); - Assert.Equal("doc:", knowledge.Links.Prefix); - Assert.Equal("none", knowledge.Analyzer); - Assert.Equal("acme-handbook", knowledge.Citation); - Assert.Equal(0.5, knowledge.ScoreFloor); - } - - [Fact] - public void UnknownKey_IsRejectedBySchemaValidation() - { - var failure = Assert.Throws(() => Load(UnknownKeyYaml)); - - Assert.Contains("vectorName", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void ScopeTemplate_WithoutKeyPlaceholder_IsRejectedBySchemaValidation() - { - const string yaml = - """ + [Fact] + public void ABlockThatNamesNoFields_MapsNothing() + { + KnowledgeProviderConfiguration knowledge = Load(MinimalYaml).Providers!.Knowledge!; + + Assert.Null(knowledge.Vector); + + // Not an empty fields block with six null roles: no block at all. The document said nothing + // about this collection's payload, and nothing is what AgentCore knows about it. + Assert.Null(knowledge.Fields); + Assert.Null(knowledge.Scope.Template); + Assert.Null(knowledge.Links); + + // 'none' requires no term, so ranking is vector similarity alone. The old default named one + // corpus's error-code shape and applied it to every consumer's queries. + Assert.Equal("none", knowledge.Analyzer); + + // A wording IS shipped, unlike a field name: a citation has to read something, and the two + // roles it reads are the two the document already named. The wording is replaceable, and + // that is a different thing from being absent. + Assert.Equal("source-locator", knowledge.Citation); + // Cosine similarity on the dense prefetch. Measured 2026-09-02 on text-embedding-3-small: + // 0.25 let twelve of twenty cards through for a question the corpus did not answer; 0.35 let + // none through and kept every card of every answered question. + Assert.Equal(0.35, knowledge.ScoreFloor); + } + + [Fact] + public void EveryFieldBinds() + { + KnowledgeProviderConfiguration knowledge = Load(FullYaml).Providers!.Knowledge!; + + Assert.Equal("embedding", knowledge.Vector); + Assert.Equal("doc_id", knowledge.Fields!.Id); + Assert.Equal("content", knowledge.Fields.Body); + Assert.Equal("content", knowledge.Fields.Lexical); + Assert.Equal("origin", knowledge.Fields.Source); + Assert.Equal("page", knowledge.Fields.Locator); + Assert.Equal("trust", knowledge.Fields.Authority); + Assert.Equal("{key}", knowledge.Scope.Template); + Assert.NotNull(knowledge.Links); + Assert.Equal("related", knowledge.Links!.Field); + Assert.Equal(KnowledgeLinkLookup.Filter, knowledge.Links.Lookup); + Assert.Equal("dns", knowledge.Links.Namespace); + Assert.Equal("doc:", knowledge.Links.Prefix); + Assert.Equal("none", knowledge.Analyzer); + Assert.Equal("acme-handbook", knowledge.Citation); + Assert.Equal(0.5, knowledge.ScoreFloor); + } + + [Fact] + public void UnknownKey_IsRejectedBySchemaValidation() + { + ConfigurationLoadException failure = Assert.Throws(() => Load(UnknownKeyYaml)); + + Assert.Contains("vectorName", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void ScopeTemplate_WithoutKeyPlaceholder_IsRejectedBySchemaValidation() + { + const string yaml = + """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -170,8 +170,12 @@ public void ScopeTemplate_WithoutKeyPlaceholder_IsRejectedBySchemaValidation() agent: only """; - Assert.Throws(() => Load(yaml)); - } + _ = Assert.Throws(() => Load(yaml)); + } - private static AgentCoreConfiguration Load(string yaml) => ConfigurationLoader.LoadYaml(yaml); + private static AgentCoreConfiguration Load(string yaml) + { + return ConfigurationLoader.LoadYaml(yaml); + } + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/LoopCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/LoopCompilationTests.cs index 30e04917..5ff305ee 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/LoopCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/LoopCompilationTests.cs @@ -6,17 +6,17 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The loop: block reaching a compiled agent as a , the evaluator -/// each until: entry selects, and the failures a block names that its agent cannot honor. -/// -#pragma warning disable MAAI001 // The loop family is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class LoopCompilationTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string TodosLoopYaml = - """ + /// + /// The loop: block reaching a compiled agent as a , the evaluator + /// each until: entry selects, and the failures a block names that its agent cannot honor. + /// +#pragma warning disable MAAI001 // The loop family is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class LoopCompilationTests + { + private const string TodosLoopYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -26,8 +26,8 @@ public sealed class LoopCompilationTests agent: coder """; - private const string BackgroundLoopYaml = - """ + private const string BackgroundLoopYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -44,73 +44,73 @@ public sealed class LoopCompilationTests - { id: done, agent: coder, terminal: true } """; - [Fact] - public void Compile_LoopWithUntilTodosAndTodos_GetsALoopAgent() - { - var compiled = Compile(TodosLoopYaml); - - Assert.NotNull(compiled.Agents["coder"].GetService()); - } - - [Fact] - public void Compile_NoLoop_GetsNoLoopAgent() - { - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = [new AgentConfiguration { Id = "only", Todos = true }], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration { Agent = "only" }, - }, - }, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - - Assert.Null(Assert.Single(compiled.Agents.Values).GetService()); - } - - [Fact] - public async Task Compile_LoopWithMaxRoundsThreeAndOpenTodos_RunsThreeIterationsThenStops() - { - var client = new ToolCallingChatClient( - "added", - new Dictionary(StringComparer.Ordinal) - { - ["todos"] = new object[] - { - new Dictionary(StringComparer.Ordinal) { ["title"] = "T" }, - }, - }); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(TodosLoopYaml), - new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; - - var agent = compiled.Agents["coder"]; - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); - - var response = await agent.RunAsync("fix it", session, cancellationToken: token); - - // Each iteration replays the tool call and the text: iterations rerun from the initial - // messages plus the evaluator's feedback while only the provider session state carries - // over, so the open todo list keeps every iteration going. Three iterations at the - // maxRounds: 3 cap, then the loop stops rather than running on. Without the wrap the - // single run would spend two model calls and conversation todos_add once. - Assert.Equal(3, client.Called.Count(name => name == "todos_add")); - Assert.Equal(6, client.Calls); - Assert.Contains("added", response.Text, StringComparison.Ordinal); - } - - [Fact] - public void Compile_LoopUntilTodosWithoutTodos_FailsNamingTheUntilPointer() - { - const string yaml = - """ + [Fact] + public void Compile_LoopWithUntilTodosAndTodos_GetsALoopAgent() + { + CompiledAgent compiled = Compile(TodosLoopYaml); + + Assert.NotNull(compiled.Agents["coder"].GetService()); + } + + [Fact] + public void Compile_NoLoop_GetsNoLoopAgent() + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only", Todos = true }], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "only" }, + }, + }, + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + + Assert.Null(Assert.Single(compiled.Agents.Values).GetService()); + } + + [Fact] + public async Task Compile_LoopWithMaxRoundsThreeAndOpenTodos_RunsThreeIterationsThenStops() + { + ToolCallingChatClient client = new( + "added", + new Dictionary(StringComparer.Ordinal) + { + ["todos"] = new object[] + { + new Dictionary(StringComparer.Ordinal) { ["title"] = "T" }, + }, + }); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(TodosLoopYaml), + new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; + + AIAgent agent = compiled.Agents["coder"]; + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); + + AgentResponse response = await agent.RunAsync("fix it", session, cancellationToken: token); + + // Each iteration replays the tool call and the text: iterations rerun from the initial + // messages plus the evaluator's feedback while only the provider session state carries + // over, so the open todo list keeps every iteration going. Three iterations at the + // maxRounds: 3 cap, then the loop stops rather than running on. Without the wrap the + // single run would spend two model calls and conversation todos_add once. + Assert.Equal(3, client.Called.Count(name => name == "todos_add")); + Assert.Equal(6, client.Calls); + Assert.Contains("added", response.Text, StringComparison.Ordinal); + } + + [Fact] + public void Compile_LoopUntilTodosWithoutTodos_FailsNamingTheUntilPointer() + { + const string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -120,17 +120,17 @@ public void Compile_LoopUntilTodosWithoutTodos_FailsNamingTheUntilPointer() agent: coder """; - var failure = Assert.Throws(() => Compile(yaml)); + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); - Assert.Equal("/agents/items/0/loop/until/0", failure.Pointer); - Assert.Contains("todos:", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/0/loop/until/0", failure.Pointer); + Assert.Contains("todos:", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Compile_LoopUntilBackgroundWithoutBackground_FailsNamingTheUntilPointer() - { - const string yaml = - """ + [Fact] + public void Compile_LoopUntilBackgroundWithoutBackground_FailsNamingTheUntilPointer() + { + const string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -140,17 +140,17 @@ public void Compile_LoopUntilBackgroundWithoutBackground_FailsNamingTheUntilPoin agent: coder """; - var failure = Assert.Throws(() => Compile(yaml)); + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); - Assert.Equal("/agents/items/0/loop/until/0", failure.Pointer); - Assert.Contains("background:", failure.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/0/loop/until/0", failure.Pointer); + Assert.Contains("background:", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Compile_LoopWithNoUntil_FailsNamingTheLoopPointer() - { - const string yaml = - """ + [Fact] + public void Compile_LoopWithNoUntil_FailsNamingTheLoopPointer() + { + const string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -160,27 +160,31 @@ public void Compile_LoopWithNoUntil_FailsNamingTheLoopPointer() agent: coder """; - var failure = Assert.Throws(() => Compile(yaml)); - - Assert.Equal("/agents/items/0/loop", failure.Pointer); - Assert.Contains("until:", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void Compile_LoopWithBackgroundUntilAndChildren_CompilesAndAddsNoStateKeys() - { - using SequencedChatClient childReply = new("hi"); - var backgroundKeys = new BackgroundAgentsProvider( - [new ChatClientAgent(childReply, new ChatClientAgentOptions { Name = "coder" })]).StateKeys; - - var compiled = Compile(BackgroundLoopYaml); - - Assert.NotNull(compiled.Agents["parent"].GetService()); - Assert.Equal(backgroundKeys.ToHashSet(StringComparer.Ordinal), compiled.HarnessStateKeys); - } - - private static CompiledAgent Compile(string yaml) => ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; - } - #pragma warning restore MAAI001 + ConfigurationLoadException failure = Assert.Throws(() => Compile(yaml)); + + Assert.Equal("/agents/items/0/loop", failure.Pointer); + Assert.Contains("until:", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void Compile_LoopWithBackgroundUntilAndChildren_CompilesAndAddsNoStateKeys() + { + using SequencedChatClient childReply = new("hi"); + IReadOnlyList backgroundKeys = new BackgroundAgentsProvider( + [new ChatClientAgent(childReply, new ChatClientAgentOptions { Name = "coder" })]).StateKeys; + + CompiledAgent compiled = Compile(BackgroundLoopYaml); + + Assert.NotNull(compiled.Agents["parent"].GetService()); + Assert.Equal(backgroundKeys.ToHashSet(StringComparer.Ordinal), compiled.HarnessStateKeys); + } + + private static CompiledAgent Compile(string yaml) + { + return ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hello there."))))["main"]; + } + } +#pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/MemoryCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/MemoryCompilationTests.cs index 386f72c1..3085f370 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/MemoryCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/MemoryCompilationTests.cs @@ -1,38 +1,40 @@ using System.Runtime.CompilerServices; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Runtime; +using AgentCore.Domain; using AgentCore.Domain.Audit; using AgentCore.TestSupport; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The memory: block reaching a compiled agent as a , the -/// seven file_memory_* tools it puts in front of the model, and the working folder it binds -/// to the running conversation. -/// -public sealed class MemoryCompilationTests : IDisposable +namespace AgentCore.Application.Tests.Configuration.Compilation { - private static readonly string[] ExpectedMemoryTools = - [ - "file_memory_write", - "file_memory_read", - "file_memory_delete", - "file_memory_ls", - "file_memory_grep", - "file_memory_replace", - "file_memory_replace_lines", - ]; - - private const string MemoryYaml = - """ + /// + /// The memory: block reaching a compiled agent as a , the + /// seven file_memory_* tools it puts in front of the model, and the working folder it binds + /// to the running conversation. + /// + public sealed class MemoryCompilationTests : IDisposable + { + private static readonly string[] ExpectedMemoryTools = + [ + "file_memory_write", + "file_memory_read", + "file_memory_delete", + "file_memory_ls", + "file_memory_grep", + "file_memory_replace", + "file_memory_replace_lines", + ]; + + private const string MemoryYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -42,8 +44,8 @@ public sealed class MemoryCompilationTests : IDisposable agent: only """; - private const string NoMemoryYaml = - """ + private const string NoMemoryYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -53,8 +55,8 @@ public sealed class MemoryCompilationTests : IDisposable agent: only """; - private const string MemoryPolicyYaml = - """ + private const string MemoryPolicyYaml = + """ apiVersion: agentcore/v1 state: done: @@ -80,284 +82,281 @@ public sealed class MemoryCompilationTests : IDisposable terminal: true """; - private readonly string _root = - Path.Combine(Path.GetTempPath(), "agentcore-memory-" + Guid.NewGuid().ToString("N")); - - public void Dispose() - { - if (Directory.Exists(_root)) - { - Directory.Delete(_root, recursive: true); - } - } - - [Fact] - public async Task Compile_MemoryWorkspaceWithARoot_GetsAFileMemoryProviderAndTheSevenTools() - { - using SequencedChatClient reply = new("hello there."); - var document = ConfigurationLoader.LoadYaml(MemoryYaml); - var chatClients = new RoutingChatClientFactory(reply); - - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; - var agent = Assert.Single(compiled.Agents.Values); - Assert.Contains(Providers(agent), provider => provider is FileMemoryProvider); - - var factory = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); - var session = factory.Create("conversation-1"); - - // A turn must be open for the FileMemoryProvider's state initializer to read the conversation id off - // the session, so the tool list is read through a real conversation rather than agent.RunAsync - // directly, unlike the todos/mode providers in HarnessCompilationTests. - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - Assert.Equal(ExpectedMemoryTools, toolNames, StringComparer.Ordinal); - } - - [Fact] - public async Task Compile_MemoryWorkspaceWithARoot_TheModelsInstructionsAreTruthfulAboutDeletion() - { - using SequencedChatClient reply = new("hello there."); - var document = ConfigurationLoader.LoadYaml(MemoryYaml); - var chatClients = new RoutingChatClientFactory(reply); - - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; - var factory = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); - var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var instructions = reply.Options[^1]?.Instructions ?? string.Empty; - Assert.Contains("deleted when the conversation ends", instructions, StringComparison.Ordinal); - Assert.DoesNotContain("persist beyond", instructions, StringComparison.Ordinal); - } - - [Fact] - public async Task Compile_NoMemoryBlock_GetsNoFileMemoryProviderAndNoTool() - { - using SequencedChatClient reply = new("hello there."); - - var agent = CompileOne(NoMemoryYaml, reply, _root); - Assert.DoesNotContain(Providers(agent), provider => provider is FileMemoryProvider); - - var token = TestContext.Current.CancellationToken; - var session = await agent.CreateSessionAsync(token); - await agent.RunAsync("hi", session, cancellationToken: token); - - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - Assert.DoesNotContain(toolNames, name => name.StartsWith("file_memory_", StringComparison.Ordinal)); - } - - [Fact] - public void Compile_MemoryWorkspaceWithNoRoot_FailsNamingTheMemoryPointer() - { - using SequencedChatClient reply = new("hello there."); - var document = ConfigurationLoader.LoadYaml(MemoryYaml); - - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]); - - Assert.Equal("/agents/items/0/memory", failure.Pointer); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task EndToEnd_TheModelWritesAFile_ItLandsUnderTheConversationsFolder_AndIsGoneWhenTheConversationEnds() - { - var factory = BuildFactory(MemoryYaml, _root); - var session = factory.Create("conversation-1"); - var conversationFolder = session.Workspace!; - - await session.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); - - var notes = FindRecursive(conversationFolder, "notes.md"); - Assert.NotEmpty(notes); - Assert.Contains("hello", await File.ReadAllTextAsync(notes[0], TestContext.Current.CancellationToken)); - - session.EndConversation(ConversationEndReason.CallerHungUp); - - Assert.False(Directory.Exists(conversationFolder)); - } - - [Fact] - public async Task TwoSessions_DifferentConversationIds_WriteToDifferentFolders() - { - var factory = BuildFactory(MemoryYaml, _root); - - var first = factory.Create("conversation-a"); - await first.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); - - var second = factory.Create("conversation-b"); - await second.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); - - var firstNotes = FindRecursive(first.Workspace!, "notes.md"); - var secondNotes = FindRecursive(second.Workspace!, "notes.md"); - - Assert.NotEmpty(firstNotes); - Assert.NotEmpty(secondNotes); - Assert.DoesNotContain(firstNotes[0], secondNotes); - } - - [Fact] - public async Task MidTurnEndConversation_DuringAFileMemoryWrite_StillDeletesTheFolder_EvenWhenThePolicyIsNotTerminal() - { - var document = ConfigurationLoader.LoadYaml(MemoryPolicyYaml); - EndConversationDuringToolChatClient chatClient = new( - "hello there.", - new Dictionary(StringComparer.Ordinal) - { - ["fileName"] = "notes.md", - ["content"] = "hello", - }); - var chatClients = new RoutingChatClientFactory(chatClient); - - var compiled = ConfigurationCompiler.CompileAll( - document, new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; - var factory = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); - var session = factory.Create("conversation-1"); - var conversationFolder = session.Workspace!; - - // The callback fires from inside the model's response, before the framework runs the tool - // it just asked for — mid-turn, exactly where a mid-turn EndConversation would land in production. - chatClient.BeforeToolCall = () => session.EndConversation(ConversationEndReason.CallerHungUp); - - var turn = await session.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); - - Assert.False(turn.IsTerminal); - Assert.False(Directory.Exists(conversationFolder)); - } - - private static ConversationSessionFactory BuildFactory(string yaml, string root) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new RoutingChatClientFactory(new ToolCallingChatClient( - "hello there.", - new Dictionary(StringComparer.Ordinal) - { - ["fileName"] = "notes.md", - ["content"] = "hello", - })); - - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { WorkspaceRoot = root })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - workspaceRoot: root); - } - - private static string[] FindRecursive(string root, string fileName) - => Directory.Exists(root) - ? Directory.GetFiles(root, fileName, SearchOption.AllDirectories) - : []; - - private static AIAgent CompileOne(string yaml, SequencedChatClient reply, string root) - { - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) { WorkspaceRoot = root })["main"]; - - return Assert.Single(compiled.Agents.Values); - } - - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; - } - - /// - /// Like , but runs immediately - /// before it emits the one tool call it makes — the model-side moment a mid-turn - /// EndConversation lands at, before the framework has actually run the tool. - /// - private sealed class EndConversationDuringToolChatClient : IChatClient - { - private const string ConversationId = "conversation_1"; - - private readonly string _reply; - private readonly Dictionary _arguments; - private bool _answered; - - public EndConversationDuringToolChatClient(string reply, Dictionary arguments) - { - _reply = reply; - _arguments = arguments; - } - - public Action? BeforeToolCall { get; set; } - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); - - var answeredAlready = messages.Any( - message => message.Contents.Any(content => content is FunctionResultContent)); - var tool = options?.Tools?.OfType().FirstOrDefault(); - var responseId = Guid.NewGuid().ToString("N"); - - if (tool is not null && !answeredAlready && !_answered) - { - _answered = true; - BeforeToolCall?.Invoke(); - - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent(ConversationId, tool.Name, _arguments)]) - { - ResponseId = responseId, - MessageId = responseId, - }; - - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - }; - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } - - public void Dispose() - { - // Nothing to release. - } - } - } + private readonly string _root = + Path.Combine(Path.GetTempPath(), "agentcore-memory-" + Guid.NewGuid().ToString("N")); + + public void Dispose() + { + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } + } + + [Fact] + public async Task Compile_MemoryWorkspaceWithARoot_GetsAFileMemoryProviderAndTheSevenTools() + { + using SequencedChatClient reply = new("hello there."); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(MemoryYaml); + RoutingChatClientFactory chatClients = new(reply); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; + AIAgent agent = Assert.Single(compiled.Agents.Values); + Assert.Contains(Providers(agent), provider => provider is FileMemoryProvider); + + ConversationSessionFactory factory = new( + compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); + ConversationSession session = factory.Create("conversation-1"); + + // A turn must be open for the FileMemoryProvider's state initializer to read the conversation id off + // the session, so the tool list is read through a real conversation rather than agent.RunAsync + // directly, unlike the todos/mode providers in HarnessCompilationTests. + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + Assert.Equal(ExpectedMemoryTools, toolNames, StringComparer.Ordinal); + } + + [Fact] + public async Task Compile_MemoryWorkspaceWithARoot_TheModelsInstructionsAreTruthfulAboutDeletion() + { + using SequencedChatClient reply = new("hello there."); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(MemoryYaml); + RoutingChatClientFactory chatClients = new(reply); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; + ConversationSessionFactory factory = new( + compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); + ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + string instructions = reply.Options[^1]?.Instructions ?? string.Empty; + Assert.Contains("deleted when the conversation ends", instructions, StringComparison.Ordinal); + Assert.DoesNotContain("persist beyond", instructions, StringComparison.Ordinal); + } + + [Fact] + public async Task Compile_NoMemoryBlock_GetsNoFileMemoryProviderAndNoTool() + { + using SequencedChatClient reply = new("hello there."); + + AIAgent agent = CompileOne(NoMemoryYaml, reply, _root); + Assert.DoesNotContain(Providers(agent), provider => provider is FileMemoryProvider); + + CancellationToken token = TestContext.Current.CancellationToken; + AgentSession session = await agent.CreateSessionAsync(token); + _ = await agent.RunAsync("hi", session, cancellationToken: token); + + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + Assert.DoesNotContain(toolNames, name => name.StartsWith("file_memory_", StringComparison.Ordinal)); + } + + [Fact] + public void Compile_MemoryWorkspaceWithNoRoot_FailsNamingTheMemoryPointer() + { + using SequencedChatClient reply = new("hello there."); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(MemoryYaml); + + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]); + + Assert.Equal("/agents/items/0/memory", failure.Pointer); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task EndToEnd_TheModelWritesAFile_ItLandsUnderTheConversationsFolder_AndIsGoneWhenTheConversationEnds() + { + ConversationSessionFactory factory = BuildFactory(MemoryYaml, _root); + ConversationSession session = factory.Create("conversation-1"); + string conversationFolder = session.Workspace!; + + _ = await session.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); + + string[] notes = FindRecursive(conversationFolder, "notes.md"); + Assert.NotEmpty(notes); + Assert.Contains("hello", await File.ReadAllTextAsync(notes[0], TestContext.Current.CancellationToken)); + + _ = session.EndConversation(ConversationEndReason.CallerHungUp); + + Assert.False(Directory.Exists(conversationFolder)); + } + + [Fact] + public async Task TwoSessions_DifferentConversationIds_WriteToDifferentFolders() + { + ConversationSessionFactory factory = BuildFactory(MemoryYaml, _root); + + ConversationSession first = factory.Create("conversation-a"); + _ = await first.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); + + ConversationSession second = factory.Create("conversation-b"); + _ = await second.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); + + string[] firstNotes = FindRecursive(first.Workspace!, "notes.md"); + string[] secondNotes = FindRecursive(second.Workspace!, "notes.md"); + + Assert.NotEmpty(firstNotes); + Assert.NotEmpty(secondNotes); + Assert.DoesNotContain(firstNotes[0], secondNotes); + } + + [Fact] + public async Task MidTurnEndConversation_DuringAFileMemoryWrite_StillDeletesTheFolder_EvenWhenThePolicyIsNotTerminal() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(MemoryPolicyYaml); + EndConversationDuringToolChatClient chatClient = new( + "hello there.", + new Dictionary(StringComparer.Ordinal) + { + ["fileName"] = "notes.md", + ["content"] = "hello", + }); + RoutingChatClientFactory chatClients = new(chatClient); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; + ConversationSessionFactory factory = new( + compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); + ConversationSession session = factory.Create("conversation-1"); + string conversationFolder = session.Workspace!; + + // The callback fires from inside the model's response, before the framework runs the tool + // it just asked for — mid-turn, exactly where a mid-turn EndConversation would land in production. + chatClient.BeforeToolCall = () => session.EndConversation(ConversationEndReason.CallerHungUp); + + TurnResult turn = await session.RunTurnAsync("please remember this", TestContext.Current.CancellationToken); + + Assert.False(turn.IsTerminal); + Assert.False(Directory.Exists(conversationFolder)); + } + + private static ConversationSessionFactory BuildFactory(string yaml, string root) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(new ToolCallingChatClient( + "hello there.", + new Dictionary(StringComparer.Ordinal) + { + ["fileName"] = "notes.md", + ["content"] = "hello", + })); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { WorkspaceRoot = root })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + workspaceRoot: root); + } + + private static string[] FindRecursive(string root, string fileName) + { + return Directory.Exists(root) + ? Directory.GetFiles(root, fileName, SearchOption.AllDirectories) + : []; + } + + private static AIAgent CompileOne(string yaml, SequencedChatClient reply, string root) + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { WorkspaceRoot = root })["main"]; + + return Assert.Single(compiled.Agents.Values); + } + + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } + + /// + /// Like , but runs immediately + /// before it emits the one tool call it makes — the model-side moment a mid-turn + /// EndConversation lands at, before the framework has actually run the tool. + /// + private sealed class EndConversationDuringToolChatClient(string reply, Dictionary arguments) : IChatClient + { + private const string ConversationId = "conversation_1"; + + private readonly string _reply = reply; + private readonly Dictionary _arguments = arguments; + private bool _answered; + + public Action? BeforeToolCall { get; set; } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); + + bool answeredAlready = messages.Any( + message => message.Contents.Any(content => content is FunctionResultContent)); + AIFunction? tool = options?.Tools?.OfType().FirstOrDefault(); + string responseId = Guid.NewGuid().ToString("N"); + + if (tool is not null && !answeredAlready && !_answered) + { + _answered = true; + BeforeToolCall?.Invoke(); + + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent(ConversationId, tool.Name, _arguments)]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + // Nothing to release. + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ShellOptionsCompilerTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ShellOptionsCompilerTests.cs index 38937c05..9683c71a 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/ShellOptionsCompilerTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ShellOptionsCompilerTests.cs @@ -1,23 +1,24 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Runtime.Harness; using AgentCore.Application.Secrets; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Runtime; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// The new shell: keys: env: (with ${secret:name}), maxOutputKb:, and the -/// Docker-only keys refused under kind: local. -/// -public sealed class ShellOptionsCompilerTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - [Fact] - public void Load_ShellEnvWithASecretReference_BindsTheReferenceAndLeavesAPlainValueAlone() + /// + /// The new shell: keys: env: (with ${secret:name}), maxOutputKb:, and the + /// Docker-only keys refused under kind: local. + /// + public sealed class ShellOptionsCompilerTests { - var configuration = ConfigurationLoader.LoadYaml(""" + [Fact] + public void Load_ShellEnvWithASecretReference_BindsTheReferenceAndLeavesAPlainValueAlone() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -29,46 +30,46 @@ public void Load_ShellEnvWithASecretReference_BindsTheReferenceAndLeavesAPlainVa agent: only """); - var shell = Assert.Single(configuration.Agents!.Items).Shell; - Assert.NotNull(shell); - Assert.True(shell!.Env["CUSTSERVICE_DSN"].HasSecretReferences); - Assert.Equal("custservice-dsn", Assert.Single(shell.Env["CUSTSERVICE_DSN"].References).Name); - Assert.False(shell.Env["PYTHONUNBUFFERED"].HasSecretReferences); - } + ShellConfiguration? shell = Assert.Single(configuration.Agents!.Items).Shell; + Assert.NotNull(shell); + Assert.True(shell!.Env["CUSTSERVICE_DSN"].HasSecretReferences); + Assert.Equal("custservice-dsn", Assert.Single(shell.Env["CUSTSERVICE_DSN"].References).Name); + Assert.False(shell.Env["PYTHONUNBUFFERED"].HasSecretReferences); + } - [Fact] - public void Build_ShellEnvAndMaxOutputKb_ResolveIntoTheConversationShellOptions() - { - var root = Path.Combine(Path.GetTempPath(), "agentcore-shell-env-secret-" + Guid.NewGuid().ToString("N")); - var item = new AgentConfiguration { Id = "only" }; - var shell = new ShellConfiguration + [Fact] + public void Build_ShellEnvAndMaxOutputKb_ResolveIntoTheConversationShellOptions() { - Kind = ShellKind.Local, - MaxOutputKb = 64, - Env = new Dictionary(StringComparer.Ordinal) + string root = Path.Combine(Path.GetTempPath(), "agentcore-shell-env-secret-" + Guid.NewGuid().ToString("N")); + AgentConfiguration item = new() { Id = "only" }; + ShellConfiguration shell = new() { - ["CUSTSERVICE_DSN"] = SecretTemplate.Parse("${secret:custservice-dsn}"), - ["PYTHONUNBUFFERED"] = SecretTemplate.Parse("1"), - }, - }; + Kind = ShellKind.Local, + MaxOutputKb = 64, + Env = new Dictionary(StringComparer.Ordinal) + { + ["CUSTSERVICE_DSN"] = SecretTemplate.Parse("${secret:custservice-dsn}"), + ["PYTHONUNBUFFERED"] = SecretTemplate.Parse("1"), + }, + }; - var context = new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) - { - WorkspaceRoot = root, - Secrets = ResolvedSecrets.Create([new KeyValuePair("custservice-dsn", "postgres://x")]), - }; + AgentCompilationContext context = new(new FakeChatClientFactory(new SequencedChatClient("hi"))) + { + WorkspaceRoot = root, + Secrets = ResolvedSecrets.Create([new KeyValuePair("custservice-dsn", "postgres://x")]), + }; - var options = AgentShellOptionsCompiler.Build(item, shell, context, "/agents/items/0"); + ConversationShellOptions options = AgentShellOptionsCompiler.Build(item, shell, context, "/agents/items/0"); - Assert.Equal("postgres://x", options.Env!["CUSTSERVICE_DSN"]); - Assert.Equal("1", options.Env!["PYTHONUNBUFFERED"]); - Assert.Equal(64 * 1024, options.MaxOutputBytes); - } + Assert.Equal("postgres://x", options.Env!["CUSTSERVICE_DSN"]); + Assert.Equal("1", options.Env!["PYTHONUNBUFFERED"]); + Assert.Equal(64 * 1024, options.MaxOutputBytes); + } - [Fact] - public void Compile_ShellWithADockerOnlyKeyUnderKindLocal_FailsNamingTheAgentAndTheKey() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public void Compile_ShellWithADockerOnlyKeyUnderKindLocal_FailsNamingTheAgentAndTheKey() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -80,17 +81,18 @@ public void Compile_ShellWithADockerOnlyKeyUnderKindLocal_FailsNamingTheAgentAnd agent: only """); - var root = Path.Combine(Path.GetTempPath(), "agentcore-shell-docker-only-" + Guid.NewGuid().ToString("N")); + string root = Path.Combine(Path.GetTempPath(), "agentcore-shell-docker-only-" + Guid.NewGuid().ToString("N")); - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) - { - WorkspaceRoot = root, - })["main"]); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(new SequencedChatClient("hi"))) + { + WorkspaceRoot = root, + })["main"]); - Assert.Equal("/agents/items/0/shell", failure.Pointer); - Assert.Contains("'only'", failure.Message, StringComparison.Ordinal); - Assert.Contains("image:", failure.Message, StringComparison.Ordinal); + Assert.Equal("/agents/items/0/shell", failure.Pointer); + Assert.Contains("'only'", failure.Message, StringComparison.Ordinal); + Assert.Contains("image:", failure.Message, StringComparison.Ordinal); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/SkillsProviderBindingTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/SkillsProviderBindingTests.cs index 1f036704..283a5143 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/SkillsProviderBindingTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/SkillsProviderBindingTests.cs @@ -7,16 +7,16 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Compilation; - -/// -/// An agent that declares skills: must carry the provider even when it declares no knowledge: -/// block — the knowledge branch returns early, so a skills branch placed below it would compile -/// to nothing at all. -/// -public sealed class SkillsProviderBindingTests +namespace AgentCore.Application.Tests.Configuration.Compilation { - private const string SkillsYaml = """ + /// + /// An agent that declares skills: must carry the provider even when it declares no knowledge: + /// block — the knowledge branch returns early, so a skills branch placed below it would compile + /// to nothing at all. + /// + public sealed class SkillsProviderBindingTests + { + private const string SkillsYaml = """ apiVersion: agentcore/v1 agents: items: @@ -26,7 +26,7 @@ public sealed class SkillsProviderBindingTests agent: support """; - private const string NoSkillsYaml = """ + private const string NoSkillsYaml = """ apiVersion: agentcore/v1 agents: items: @@ -36,56 +36,57 @@ public sealed class SkillsProviderBindingTests agent: greeter """; - [Fact] - public void AnAgentWithSkillsAndNoKnowledge_CarriesTheSkillsProvider() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - using AgentFileSkillsSource source = new(folder.Root); - SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); + [Fact] + public void AnAgentWithSkillsAndNoKnowledge_CarriesTheSkillsProvider() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + using AgentFileSkillsSource source = new(folder.Root); + SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); - var providers = Providers(CompileOne(SkillsYaml, catalog)); + IEnumerable providers = Providers(CompileOne(SkillsYaml, catalog)); - Assert.Contains(providers, provider => provider is ReadOnlySkillsProvider); - } + Assert.Contains(providers, provider => provider is ReadOnlySkillsProvider); + } - [Fact] - public void AnAgentWithNoSkillsList_CarriesNoSkillsProvider() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - using AgentFileSkillsSource source = new(folder.Root); - SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); + [Fact] + public void AnAgentWithNoSkillsList_CarriesNoSkillsProvider() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + using AgentFileSkillsSource source = new(folder.Root); + SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); - var providers = Providers(CompileOne(NoSkillsYaml, catalog)); + IEnumerable providers = Providers(CompileOne(NoSkillsYaml, catalog)); - Assert.DoesNotContain(providers, provider => provider is ReadOnlySkillsProvider); - } + Assert.DoesNotContain(providers, provider => provider is ReadOnlySkillsProvider); + } - [Fact] - public void AnAgentWithSkillsAndNoBoundFolder_FailsNamingTheAgentAndTheSeam() - { - var failure = Assert.Throws(() => CompileOne(SkillsYaml, catalog: null)); + [Fact] + public void AnAgentWithSkillsAndNoBoundFolder_FailsNamingTheAgentAndTheSeam() + { + ConfigurationLoadException failure = Assert.Throws(() => CompileOne(SkillsYaml, catalog: null)); - Assert.Contains("agent 'support'", failure.Message, StringComparison.Ordinal); - Assert.Contains("options.UseSkills(...)", failure.Message, StringComparison.Ordinal); - Assert.Equal("/agents/items/0/skills", Assert.Single(failure.Errors).Pointer); - Assert.Equal(ConfigurationCheck.DocumentSchema, Assert.Single(failure.Errors).Check); - } + Assert.Contains("agent 'support'", failure.Message, StringComparison.Ordinal); + Assert.Contains("options.UseSkills(...)", failure.Message, StringComparison.Ordinal); + Assert.Equal("/agents/items/0/skills", Assert.Single(failure.Errors).Pointer); + Assert.Equal(ConfigurationCheck.DocumentSchema, Assert.Single(failure.Errors).Check); + } - private static AIAgent CompileOne(string yaml, SkillCatalog? catalog) - { - using SequencedChatClient reply = new("hello there."); + private static AIAgent CompileOne(string yaml, SkillCatalog? catalog) + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) { Skills = catalog })["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { Skills = catalog })["main"]; - return Assert.Single(compiled.Agents.Values); - } + return Assert.Single(compiled.Agents.Values); + } - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs index 84dd30eb..fb88eb00 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs @@ -2,22 +2,22 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The guarantees the hand-written binder made, kept after the reader took its place. -/// -/// -/// The binder now calls JsonSerializer, so every shape rule it used to enforce itself has to -/// be enforced somewhere else: in the document schema of check 1, or in one of the three converters. -/// Each test here pins one of those, so a schema edit that drops a rule fails rather than quietly -/// widening what a document may say. -/// -public sealed class ConfigurationBinderTests +namespace AgentCore.Application.Tests.Configuration { - private const string Header = "apiVersion: agentcore/v1\n" + "agents:\n items: [{ id: only }]\nentries:\n main:\n agent: only\n"; + /// + /// The guarantees the hand-written binder made, kept after the reader took its place. + /// + /// + /// The binder now calls JsonSerializer, so every shape rule it used to enforce itself has to + /// be enforced somewhere else: in the document schema of check 1, or in one of the three converters. + /// Each test here pins one of those, so a schema edit that drops a rule fails rather than quietly + /// widening what a document may say. + /// + public sealed class ConfigurationBinderTests + { + private const string Header = "apiVersion: agentcore/v1\n" + "agents:\n items: [{ id: only }]\nentries:\n main:\n agent: only\n"; - private const string Providers = """ + private const string Providers = """ providers: conversation: { kind: telnyx-relay } speech: @@ -25,116 +25,116 @@ public sealed class ConfigurationBinderTests tts: { kind: telnyx-relay } """; - /// Check 5 walks the members of an enumeration, and a member with no value is not a point. - [Fact] - public void AnEnumMemberWithNoValue_FailsWithThePointerOfThatMember() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml( - Header + "state:\n colour: { type: string, writer: const, value: red, enum: [red, null] }\n")); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/state/colour/enum/1"); - } - - /// The frame size becomes a buffer length, so a number no buffer can hold is a document defect. - [Fact] - public void AMaxFrameSizeLargerThanABufferLength_FailsWithThePointerOfTheField() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml( - Header + "providers:\n conversation: { kind: telnyx-relay, maxFrameBytes: 4294967296 }\n" - + " speech:\n stt: { kind: telnyx-relay }\n tts: { kind: telnyx-relay }\n")); - - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/conversation/maxFrameBytes"); - } - - /// The export interval becomes a period in milliseconds, and the same bound applies. - [Fact] - public void AnExportIntervalLargerThanAPeriod_FailsWithThePointerOfTheField() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml( - Header + Providers + "\n telemetry: { kind: grafana, exportIntervalMs: 4294967296 }\n")); - - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/telemetry/exportIntervalMs"); - } - - /// A source name of nothing but spaces listens to nothing, so it is a document defect. - [Theory] - [InlineData("sources")] - [InlineData("meters")] - public void ATelemetryNameOfSpaces_FailsWithThePointerOfThatName(string key) - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml( - Header + Providers + $"\n telemetry: {{ kind: grafana, {key}: [\" \"] }}\n")); - - Assert.Contains(failure.Errors, error => error.Pointer == $"/providers/telemetry/{key}/0"); - } - - /// An empty list is not an absent one: it listens to AgentCore alone. - [Fact] - public void AnEmptyTelemetryNameList_StaysEmptyRatherThanTakingTheDefaults() - { - var configuration = ConfigurationLoader.LoadYaml( - Header + Providers + "\n telemetry: { kind: grafana, sources: [], meters: [] }\n"); - - Assert.Empty(configuration.Providers!.Telemetry!.Sources); - Assert.Empty(configuration.Providers.Telemetry.Meters); - } - - /// An absent list takes the defaults, which is not the same as an empty one. - [Fact] - public void AnAbsentTelemetryNameList_TakesTheDefaults() - { - var configuration = ConfigurationLoader.LoadYaml( - Header + Providers + "\n telemetry: { kind: grafana }\n"); - - var telemetry = configuration.Providers!.Telemetry!; - Assert.Equal(AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.DefaultSources, telemetry.Sources); - Assert.Equal(AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.DefaultMeters, telemetry.Meters); - } - - /// T61's floor is a correction and not a refusal, and the reader still runs the setter that applies it. - [Fact] - public void AnExportIntervalBelowTheFloor_IsRaisedToIt() - { - var configuration = ConfigurationLoader.LoadYaml( - Header + Providers + "\n telemetry: { kind: grafana, exportIntervalMs: 1000 }\n"); - - Assert.Equal( - AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.MinimumExportIntervalMilliseconds, - configuration.Providers!.Telemetry!.ExportIntervalMilliseconds); - } - - /// A when: of empty text names no guard, and check 2 could only report a guard called nothing. - [Fact] - public void AGuardReferenceWithNoText_FailsWithThePointerOfTheField() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml( - "apiVersion: agentcore/v1\nagents:\n items: [{ id: only }]\nentries:\n main:\n policy:\n initial: start\n stages:\n - { id: start, agent: only, to: [{ stage: start, when: \"\" }] }\n")); - - var error = Assert.Single(failure.Errors); - Assert.Contains("guard name", error.Message, StringComparison.Ordinal); - } - - /// A whole number key does not take a number written with a fractional part. - /// - /// The two writings fail in two different places. JSON Schema calls 30.5 a number and not - /// an integer, so check 1 rejects it. It calls 30.0 an integer, because the fraction is - /// zero — so that one reaches the reader, which will not put it in an int. Both end as one - /// load error carrying the pointer of the field, which is what the hand-written binder did. - /// - [Theory] - [InlineData("30.5")] - [InlineData("30.0")] - public void AWholeNumberKeyWrittenWithAFraction_FailsWithThePointerOfTheField(string written) - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadJson( - $$""" + /// Check 5 walks the members of an enumeration, and a member with no value is not a point. + [Fact] + public void AnEnumMemberWithNoValue_FailsWithThePointerOfThatMember() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml( + Header + "state:\n colour: { type: string, writer: const, value: red, enum: [red, null] }\n")); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/state/colour/enum/1"); + } + + /// The frame size becomes a buffer length, so a number no buffer can hold is a document defect. + [Fact] + public void AMaxFrameSizeLargerThanABufferLength_FailsWithThePointerOfTheField() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml( + Header + "providers:\n conversation: { kind: telnyx-relay, maxFrameBytes: 4294967296 }\n" + + " speech:\n stt: { kind: telnyx-relay }\n tts: { kind: telnyx-relay }\n")); + + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/conversation/maxFrameBytes"); + } + + /// The export interval becomes a period in milliseconds, and the same bound applies. + [Fact] + public void AnExportIntervalLargerThanAPeriod_FailsWithThePointerOfTheField() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml( + Header + Providers + "\n telemetry: { kind: grafana, exportIntervalMs: 4294967296 }\n")); + + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/telemetry/exportIntervalMs"); + } + + /// A source name of nothing but spaces listens to nothing, so it is a document defect. + [Theory] + [InlineData("sources")] + [InlineData("meters")] + public void ATelemetryNameOfSpaces_FailsWithThePointerOfThatName(string key) + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml( + Header + Providers + $"\n telemetry: {{ kind: grafana, {key}: [\" \"] }}\n")); + + Assert.Contains(failure.Errors, error => error.Pointer == $"/providers/telemetry/{key}/0"); + } + + /// An empty list is not an absent one: it listens to AgentCore alone. + [Fact] + public void AnEmptyTelemetryNameList_StaysEmptyRatherThanTakingTheDefaults() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml( + Header + Providers + "\n telemetry: { kind: grafana, sources: [], meters: [] }\n"); + + Assert.Empty(configuration.Providers!.Telemetry!.Sources); + Assert.Empty(configuration.Providers.Telemetry.Meters); + } + + /// An absent list takes the defaults, which is not the same as an empty one. + [Fact] + public void AnAbsentTelemetryNameList_TakesTheDefaults() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml( + Header + Providers + "\n telemetry: { kind: grafana }\n"); + + TelemetryProviderConfiguration telemetry = configuration.Providers!.Telemetry!; + Assert.Equal(TelemetryProviderConfiguration.DefaultSources, telemetry.Sources); + Assert.Equal(TelemetryProviderConfiguration.DefaultMeters, telemetry.Meters); + } + + /// T61's floor is a correction and not a refusal, and the reader still runs the setter that applies it. + [Fact] + public void AnExportIntervalBelowTheFloor_IsRaisedToIt() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml( + Header + Providers + "\n telemetry: { kind: grafana, exportIntervalMs: 1000 }\n"); + + Assert.Equal( + TelemetryProviderConfiguration.MinimumExportIntervalMilliseconds, + configuration.Providers!.Telemetry!.ExportIntervalMilliseconds); + } + + /// A when: of empty text names no guard, and check 2 could only report a guard called nothing. + [Fact] + public void AGuardReferenceWithNoText_FailsWithThePointerOfTheField() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml( + "apiVersion: agentcore/v1\nagents:\n items: [{ id: only }]\nentries:\n main:\n policy:\n initial: start\n stages:\n - { id: start, agent: only, to: [{ stage: start, when: \"\" }] }\n")); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Contains("guard name", error.Message, StringComparison.Ordinal); + } + + /// A whole number key does not take a number written with a fractional part. + /// + /// The two writings fail in two different places. JSON Schema calls 30.5 a number and not + /// an integer, so check 1 rejects it. It calls 30.0 an integer, because the fraction is + /// zero — so that one reaches the reader, which will not put it in an int. Both end as one + /// load error carrying the pointer of the field, which is what the hand-written binder did. + /// + [Theory] + [InlineData("30.5")] + [InlineData("30.0")] + public void AWholeNumberKeyWrittenWithAFraction_FailsWithThePointerOfTheField(string written) + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadJson( + $$""" { "apiVersion": "agentcore/v1", "agents": { "items": [{ "id": "only" }] }, @@ -146,37 +146,41 @@ public void AWholeNumberKeyWrittenWithAFraction_FailsWithThePointerOfTheField(st } """)); - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/conversation/idleTimeoutSeconds"); - Assert.DoesNotContain("System.", failure.Message, StringComparison.Ordinal); - } - - /// The reader reports a path, and section 8.7 asks for a JSON Pointer. - [Theory] - [InlineData(null, "")] - [InlineData("$", "")] - [InlineData("$.name", "/name")] - [InlineData("$.tools[0].request.url", "/tools/0/request/url")] - [InlineData("$['a/b'].c", "/a~1b/c")] - [InlineData("$['a~b']", "/a~0b")] - public void ThePathTheReaderReports_BecomesAJsonPointer(string? path, string expected) - => Assert.Equal(expected, ConfigurationBinder.Pointer(path)); - - /// The reader names CLR types, and whoever wrote the document has never heard of them. - [Theory] - [InlineData("The JSON value could not be converted to System.String. Path: $.name | LineNumber: 0 | BytePositionInLine: 9.", "a string is expected")] - [InlineData("The JSON value could not be converted to System.Int32.", "a whole number is expected")] - [InlineData("The JSON value could not be converted to System.Nullable`1[System.Int32].", "a whole number is expected")] - [InlineData("The JSON value could not be converted to System.Double.", "a number is expected")] - [InlineData("The JSON value could not be converted to System.Boolean.", "a boolean is expected")] - [InlineData("JSON deserialization for type 'X' was missing required properties, including: 'name'.", "the required property 'name' is missing")] - [InlineData("something new the reader learned to say", "something new the reader learned to say")] - public void TheMessageTheReaderWrites_IsRewrittenForTheAuthor(string written, string expected) - => Assert.Equal(expected, ConfigurationBinder.Explain(written)); - - [Fact] - public void Bind_AnAgentWithASkillsList_CarriesTheNamesInOrder() - { - const string document = """ + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/conversation/idleTimeoutSeconds"); + Assert.DoesNotContain("System.", failure.Message, StringComparison.Ordinal); + } + + /// The reader reports a path, and section 8.7 asks for a JSON Pointer. + [Theory] + [InlineData(null, "")] + [InlineData("$", "")] + [InlineData("$.name", "/name")] + [InlineData("$.tools[0].request.url", "/tools/0/request/url")] + [InlineData("$['a/b'].c", "/a~1b/c")] + [InlineData("$['a~b']", "/a~0b")] + public void ThePathTheReaderReports_BecomesAJsonPointer(string? path, string expected) + { + Assert.Equal(expected, ConfigurationBinder.Pointer(path)); + } + + /// The reader names CLR types, and whoever wrote the document has never heard of them. + [Theory] + [InlineData("The JSON value could not be converted to System.String. Path: $.name | LineNumber: 0 | BytePositionInLine: 9.", "a string is expected")] + [InlineData("The JSON value could not be converted to System.Int32.", "a whole number is expected")] + [InlineData("The JSON value could not be converted to System.Nullable`1[System.Int32].", "a whole number is expected")] + [InlineData("The JSON value could not be converted to System.Double.", "a number is expected")] + [InlineData("The JSON value could not be converted to System.Boolean.", "a boolean is expected")] + [InlineData("JSON deserialization for type 'X' was missing required properties, including: 'name'.", "the required property 'name' is missing")] + [InlineData("something new the reader learned to say", "something new the reader learned to say")] + public void TheMessageTheReaderWrites_IsRewrittenForTheAuthor(string written, string expected) + { + Assert.Equal(expected, ConfigurationBinder.Explain(written)); + } + + [Fact] + public void Bind_AnAgentWithASkillsList_CarriesTheNamesInOrder() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -186,16 +190,16 @@ public void Bind_AnAgentWithASkillsList_CarriesTheNamesInOrder() agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - var agent = Assert.Single(configuration.Agents!.Items); - Assert.Equal(["warranty-returns", "shipping-claims"], agent.Skills); - } + AgentConfiguration agent = Assert.Single(configuration.Agents!.Items); + Assert.Equal(["warranty-returns", "shipping-claims"], agent.Skills); + } - [Fact] - public void Bind_AnAgentWithNoSkillsKey_CarriesAnEmptyList() - { - const string document = """ + [Fact] + public void Bind_AnAgentWithNoSkillsKey_CarriesAnEmptyList() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -205,35 +209,35 @@ public void Bind_AnAgentWithNoSkillsKey_CarriesAnEmptyList() agent: greeter """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Empty(Assert.Single(configuration.Agents!.Items).Skills); - } + Assert.Empty(Assert.Single(configuration.Agents!.Items).Skills); + } - [Theory] - [InlineData("Warranty_Returns")] - [InlineData("Warranty-Returns")] - [InlineData("-leading-hyphen")] - [InlineData("trailing-hyphen-")] - [InlineData("double--hyphen")] - public void Bind_ASkillNameOutsideMafsCharset_FailsCheckOne(string name) - { - var document = $$""" + [Theory] + [InlineData("Warranty_Returns")] + [InlineData("Warranty-Returns")] + [InlineData("-leading-hyphen")] + [InlineData("trailing-hyphen-")] + [InlineData("double--hyphen")] + public void Bind_ASkillNameOutsideMafsCharset_FailsCheckOne(string name) + { + string document = $$""" apiVersion: agentcore/v1 agents: items: - { id: support, skills: [{{name}}] } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } - [Fact] - public void Bind_KnowledgeScopeWildcardAndFromState_ReadsBoth() - { - const string Document = """ + [Fact] + public void Bind_KnowledgeScopeWildcardAndFromState_ReadsBoth() + { + const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -258,18 +262,18 @@ public void Bind_KnowledgeScopeWildcardAndFromState_ReadsBoth() fromState: [brand, applies_to] """; - var configuration = ConfigurationLoader.LoadYaml(Document); - var scope = configuration.Providers!.Knowledge!.Scope; + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document); + KnowledgeScopeConfiguration scope = configuration.Providers!.Knowledge!.Scope; - Assert.Equal("*", scope.Wildcard!.Value); - Assert.Equal(["brand", "applies_to"], scope.Wildcard.Facets); - Assert.Equal(["brand", "applies_to"], scope.FromState); - } + Assert.Equal("*", scope.Wildcard!.Value); + Assert.Equal(["brand", "applies_to"], scope.Wildcard.Facets); + Assert.Equal(["brand", "applies_to"], scope.FromState); + } - [Fact] - public void Bind_AmbiguityBlock_ReadsDefaults() - { - const string Document = """ + [Fact] + public void Bind_AmbiguityBlock_ReadsDefaults() + { + const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -289,20 +293,20 @@ public void Bind_AmbiguityBlock_ReadsDefaults() ambiguity: {} """; - var configuration = ConfigurationLoader.LoadYaml(Document); - var ambiguity = configuration.Providers!.Knowledge!.Ambiguity; + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document); + KnowledgeAmbiguityConfiguration? ambiguity = configuration.Providers!.Knowledge!.Ambiguity; - Assert.NotNull(ambiguity); - Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultMaxCandidates, ambiguity!.MaxCandidates); - Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultMaxAsks, ambiguity.MaxAsks); - Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultProbeDeadlineSeconds, ambiguity.ProbeDeadlineSeconds); - Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultProbeWaitMarginSeconds, ambiguity.ProbeWaitMarginSeconds); - } + Assert.NotNull(ambiguity); + Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultMaxCandidates, ambiguity!.MaxCandidates); + Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultMaxAsks, ambiguity.MaxAsks); + Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultProbeDeadlineSeconds, ambiguity.ProbeDeadlineSeconds); + Assert.Equal(KnowledgeAmbiguityConfiguration.DefaultProbeWaitMarginSeconds, ambiguity.ProbeWaitMarginSeconds); + } - [Fact] - public void Bind_AmbiguityBlock_ReadsEveryField() - { - const string Document = """ + [Fact] + public void Bind_AmbiguityBlock_ReadsEveryField() + { + const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -322,19 +326,19 @@ public void Bind_AmbiguityBlock_ReadsEveryField() ambiguity: { maxCandidates: 4, maxAsks: 1, probeDeadlineSeconds: 3, probeWaitMarginSeconds: 2 } """; - var configuration = ConfigurationLoader.LoadYaml(Document); - var ambiguity = configuration.Providers!.Knowledge!.Ambiguity!; + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document); + KnowledgeAmbiguityConfiguration ambiguity = configuration.Providers!.Knowledge!.Ambiguity!; - Assert.Equal(4, ambiguity.MaxCandidates); - Assert.Equal(1, ambiguity.MaxAsks); - Assert.Equal(3, ambiguity.ProbeDeadlineSeconds); - Assert.Equal(2, ambiguity.ProbeWaitMarginSeconds); - } + Assert.Equal(4, ambiguity.MaxCandidates); + Assert.Equal(1, ambiguity.MaxAsks); + Assert.Equal(3, ambiguity.ProbeDeadlineSeconds); + Assert.Equal(2, ambiguity.ProbeWaitMarginSeconds); + } - [Fact] - public void Bind_AnUnknownAmbiguityKey_FailsCheckOne() - { - const string Document = """ + [Fact] + public void Bind_AnUnknownAmbiguityKey_FailsCheckOne() + { + const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -354,8 +358,9 @@ public void Bind_AnUnknownAmbiguityKey_FailsCheckOne() ambiguity: { bogus: 1 } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(Document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(Document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs index 59a76ca8..9beda7c8 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs @@ -3,170 +3,172 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The section 8.1 document parses, and every section binds. -/// -public sealed class ConfigurationLoaderTests +namespace AgentCore.Application.Tests.Configuration { - private static readonly AgentCoreConfiguration Example = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - - [Fact] - public void Example_CarriesTheDocumentHeader() + /// + /// The section 8.1 document parses, and every section binds. + /// + public sealed class ConfigurationLoaderTests { - Assert.Equal(AgentCoreConfiguration.SupportedApiVersion, Example.ApiVersion); - Assert.Equal(["phone", "chat"], [.. Example.Entries.Keys]); - } + private static readonly AgentCoreConfiguration Example = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - [Fact] - public void Example_BindsEveryStateSlot() - { - Assert.Equal(8, Example.State.Count); - - var goodbye = Example.State["callerSaidGoodbye"]; - Assert.Equal(StateSlotType.Boolean, goodbye.Type); - Assert.Equal(StateWriter.Extractor, goodbye.Writer); - Assert.False(goodbye.Default!.GetValue()); - - var counter = Example.State["failedResolveTurns"]; - Assert.Equal(StateSlotType.Integer, counter.Type); - Assert.Equal(StateWriter.Counter, counter.Writer); - Assert.Equal(0, counter.Default!.GetValue()); - Assert.NotNull(counter.Increment); - Assert.Contains("\"===\"", counter.Increment!.ToJsonString(), StringComparison.Ordinal); - } + [Fact] + public void Example_CarriesTheDocumentHeader() + { + Assert.Equal(AgentCoreConfiguration.SupportedApiVersion, Example.ApiVersion); + Assert.Equal(["phone", "chat"], [.. Example.Entries.Keys]); + } - [Fact] - public void Example_BindsTheToolWriterPath() - { - var slot = Example.State["orderStatus"]; + [Fact] + public void Example_BindsEveryStateSlot() + { + Assert.Equal(8, Example.State.Count); + + StateSlotConfiguration goodbye = Example.State["callerSaidGoodbye"]; + Assert.Equal(StateSlotType.Boolean, goodbye.Type); + Assert.Equal(StateWriter.Extractor, goodbye.Writer); + Assert.False(goodbye.Default!.GetValue()); + + StateSlotConfiguration counter = Example.State["failedResolveTurns"]; + Assert.Equal(StateSlotType.Integer, counter.Type); + Assert.Equal(StateWriter.Counter, counter.Writer); + Assert.Equal(0, counter.Default!.GetValue()); + Assert.NotNull(counter.Increment); + Assert.Contains("\"===\"", counter.Increment!.ToJsonString(), StringComparison.Ordinal); + } - Assert.Equal(StateWriter.Tool, slot.Writer); - Assert.Equal(new ToolResultReference("lookup_order", "status"), slot.From); - Assert.Null(slot.Default); - } + [Fact] + public void Example_BindsTheToolWriterPath() + { + StateSlotConfiguration slot = Example.State["orderStatus"]; - [Fact] - public void Example_BindsTheExtractor() - { - Assert.NotNull(Example.Extractor); - Assert.Equal("fill", Example.Extractor!.Model.Ref); - Assert.Equal(ExtractorTrigger.AfterReply, Example.Extractor.When); - Assert.Null(Example.Extractor.Model.Temperature); - } + Assert.Equal(StateWriter.Tool, slot.Writer); + Assert.Equal(new ToolResultReference("lookup_order", "status"), slot.From); + Assert.Null(slot.Default); + } - [Fact] - public void Example_KeepsEveryGuardAsRawJsonLogic() - { - Assert.Equal(5, Example.Guards.Count); - Assert.Equal( - ["saidGoodbye", "wantsHuman", "identified", "goodbyeOrFixed", "humanOrExhausted"], - Example.Guards.Keys); + [Fact] + public void Example_BindsTheExtractor() + { + Assert.NotNull(Example.Extractor); + Assert.Equal("fill", Example.Extractor!.Model.Ref); + Assert.Equal(ExtractorTrigger.AfterReply, Example.Extractor.When); + Assert.Null(Example.Extractor.Model.Temperature); + } - Assert.Equal("""{"var":"callerSaidGoodbye"}""", Example.Guards["saidGoodbye"].ToJsonString()); - } + [Fact] + public void Example_KeepsEveryGuardAsRawJsonLogic() + { + Assert.Equal(5, Example.Guards.Count); + Assert.Equal( + ["saidGoodbye", "wantsHuman", "identified", "goodbyeOrFixed", "humanOrExhausted"], + Example.Guards.Keys); - [Fact] - public void Example_BindsEveryToolKind() - { - Assert.Equal(4, Example.Tools.Count); + Assert.Equal(/*lang=json,strict*/ """{"var":"callerSaidGoodbye"}""", Example.Guards["saidGoodbye"].ToJsonString()); + } - var binding = Example.Tools[1]; - Assert.Equal(ToolKind.Binding, binding.Kind); - Assert.Equal("CreateCase", binding.Binds); - Assert.NotNull(binding.Parameters); - Assert.Equal("object", binding.Parameters!["type"]!.GetValue()); + [Fact] + public void Example_BindsEveryToolKind() + { + Assert.Equal(4, Example.Tools.Count); - Assert.Equal(ToolKind.Builtin, Example.Tools[2].Kind); - Assert.Equal("web.search", Example.Tools[2].Uses); + ToolConfiguration binding = Example.Tools[1]; + Assert.Equal(ToolKind.Binding, binding.Kind); + Assert.Equal("CreateCase", binding.Binds); + Assert.NotNull(binding.Parameters); + Assert.Equal("object", binding.Parameters!["type"]!.GetValue()); - Assert.Equal(ToolKind.Builtin, Example.Tools[3].Kind); - Assert.Equal("file.publish", Example.Tools[3].Uses); - } + Assert.Equal(ToolKind.Builtin, Example.Tools[2].Kind); + Assert.Equal("web.search", Example.Tools[2].Uses); - [Fact] - public void Example_ReadsTheSecretReferenceAndResolvesNothing() - { - var http = Example.Tools[0]; - - Assert.Equal(ToolKind.Http, http.Kind); - Assert.NotNull(http.Request); - Assert.Equal("GET", http.Request!.Method); - Assert.Equal("https://api.example.com/orders/{orderId}", http.Request.Url); - - var header = http.Request.Headers["Authorization"]; - Assert.True(header.HasSecretReferences); - Assert.Equal("Bearer ${secret:orders-api-key}", header.Raw); - Assert.Equal("orders-api-key", Assert.Single(header.References).Name); - Assert.Equal("Bearer opened", header.Format(_ => "opened")); - } + Assert.Equal(ToolKind.Builtin, Example.Tools[3].Kind); + Assert.Equal("file.publish", Example.Tools[3].Uses); + } - [Fact] - public void Example_BindsAgents() - { - Assert.NotNull(Example.Agents); - Assert.Equal("reply", Example.Agents!.Defaults!.Model!.Ref); - Assert.Equal(0.3, Example.Agents.Defaults.Model.Temperature); - Assert.StartsWith(" "opened")); + } - [Fact] - public void Example_BindsThePolicy() - { - var policy = Example.Entries["phone"].Policy; - Assert.NotNull(policy); - Assert.Equal("greeting", policy!.Initial); - Assert.Equal(5, policy.Stages.Count); - - var identify = policy.Stages[1]; - Assert.Equal("identifier", identify.Agent); - Assert.Equal(StageNoMatch.Stay, identify.OnNoMatch); - Assert.Equal(3, identify.To.Count); - Assert.Equal("close", identify.To[0].Stage); - Assert.Equal("saidGoodbye", identify.To[0].When!.Name); - Assert.True(identify.To[0].When!.IsNamed); - - var close = policy.Stages[4]; - Assert.True(close.Terminal); - Assert.Empty(close.To); - - Assert.Null(policy.Stages[0].To[0].When); - } + [Fact] + public void Example_BindsAgents() + { + Assert.NotNull(Example.Agents); + Assert.Equal("reply", Example.Agents!.Defaults!.Model!.Ref); + Assert.Equal(0.3, Example.Agents.Defaults.Model.Temperature); + Assert.StartsWith(" Assert.Equal("webchat", Example.Entries["chat"].Agent); + [Fact] + public void Example_BindsThePolicy() + { + PolicyConfiguration? policy = Example.Entries["phone"].Policy; + Assert.NotNull(policy); + Assert.Equal("greeting", policy!.Initial); + Assert.Equal(5, policy.Stages.Count); + + StageConfiguration identify = policy.Stages[1]; + Assert.Equal("identifier", identify.Agent); + Assert.Equal(StageNoMatch.Stay, identify.OnNoMatch); + Assert.Equal(3, identify.To.Count); + Assert.Equal("close", identify.To[0].Stage); + Assert.Equal("saidGoodbye", identify.To[0].When!.Name); + Assert.True(identify.To[0].When!.IsNamed); + + StageConfiguration close = policy.Stages[4]; + Assert.True(close.Terminal); + Assert.Empty(close.To); + + Assert.Null(policy.Stages[0].To[0].When); + } - [Fact] - public void Example_BindsProviders() - { - Assert.NotNull(Example.Providers); - Assert.Equal(4, Example.Providers!.Llm.Count); - Assert.Equal("gpt-4.1-mini", Example.Providers.Llm[0].Model); - Assert.Equal("reply", Example.Providers.Llm[0].As); - Assert.Equal("fill", Example.Providers.Llm[1].As); - Assert.Equal("judge", Example.Providers.Llm[2].As); - Assert.Equal("cheap", Example.Providers.Llm[3].As); - Assert.Equal(false, Example.Providers.Llm[3].WebSearch); - Assert.Equal("telnyx-relay", Example.Providers.Speech!.Stt.Kind); - Assert.Equal("telnyx", Example.Providers.Telephony!.Kind); - Assert.Equal("qdrant", Example.Providers.Knowledge!.Kind); - Assert.Equal("https://qdrant.example.com:6334", Example.Providers.Knowledge.Endpoint); - Assert.Equal("kb", Example.Providers.Knowledge.Collection); - } + [Fact] + public void Example_BindsTheChatEntry() + { + Assert.Equal("webchat", Example.Entries["chat"].Agent); + } - [Fact] - public void AnEmptyKnowledgeBlock_FailsTheLoadForKindAndCollection() - { - // There is nothing to default them to. AgentCore knows no vendor and no collection name, so - // an empty block names no store at all rather than naming a conventional one. - const string document = """ + [Fact] + public void Example_BindsProviders() + { + Assert.NotNull(Example.Providers); + Assert.Equal(4, Example.Providers!.Llm.Count); + Assert.Equal("gpt-4.1-mini", Example.Providers.Llm[0].Model); + Assert.Equal("reply", Example.Providers.Llm[0].As); + Assert.Equal("fill", Example.Providers.Llm[1].As); + Assert.Equal("judge", Example.Providers.Llm[2].As); + Assert.Equal("cheap", Example.Providers.Llm[3].As); + Assert.Equal(false, Example.Providers.Llm[3].WebSearch); + Assert.Equal("telnyx-relay", Example.Providers.Speech!.Stt.Kind); + Assert.Equal("telnyx", Example.Providers.Telephony!.Kind); + Assert.Equal("qdrant", Example.Providers.Knowledge!.Kind); + Assert.Equal("https://qdrant.example.com:6334", Example.Providers.Knowledge.Endpoint); + Assert.Equal("kb", Example.Providers.Knowledge.Collection); + } + + [Fact] + public void AnEmptyKnowledgeBlock_FailsTheLoadForKindAndCollection() + { + // There is nothing to default them to. AgentCore knows no vendor and no collection name, so + // an empty block names no store at all rather than naming a conventional one. + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -176,18 +178,18 @@ public void AnEmptyKnowledgeBlock_FailsTheLoadForKindAndCollection() knowledge: {} """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains("kind", failure.Message, StringComparison.Ordinal); - Assert.Contains("collection", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("kind", failure.Message, StringComparison.Ordinal); + Assert.Contains("collection", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AFieldsBlockNamingOneRole_LeavesEveryOtherRoleUnmapped() - { - // The whole point of the block: a role this document does not name is absent from the card. - // It is never filled in from a name AgentCore chose, because AgentCore chooses none. - const string document = """ + [Fact] + public void AFieldsBlockNamingOneRole_LeavesEveryOtherRoleUnmapped() + { + // The whole point of the block: a role this document does not name is absent from the card. + // It is never filled in from a name AgentCore chose, because AgentCore chooses none. + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -206,21 +208,21 @@ public void AFieldsBlockNamingOneRole_LeavesEveryOtherRoleUnmapped() agent: only """; - var knowledge = ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!; + KnowledgeProviderConfiguration knowledge = ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!; - Assert.Equal("page_content", knowledge.Fields!.Body); - Assert.Null(knowledge.Fields.Id); - Assert.Null(knowledge.Fields.Lexical); - Assert.Null(knowledge.Fields.Source); - Assert.Null(knowledge.Fields.Locator); - Assert.Null(knowledge.Fields.Authority); - Assert.Null(knowledge.Scope.Template); - } + Assert.Equal("page_content", knowledge.Fields!.Body); + Assert.Null(knowledge.Fields.Id); + Assert.Null(knowledge.Fields.Lexical); + Assert.Null(knowledge.Fields.Source); + Assert.Null(knowledge.Fields.Locator); + Assert.Null(knowledge.Fields.Authority); + Assert.Null(knowledge.Scope.Template); + } - [Fact] - public void ABodyFieldSetToNull_FailsTheLoad() - { - const string document = """ + [Fact] + public void ABodyFieldSetToNull_FailsTheLoad() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -233,17 +235,17 @@ public void ABodyFieldSetToNull_FailsTheLoad() fields: { body: null } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains( - failure.Errors, - error => error.Pointer!.StartsWith("/providers/knowledge/fields", StringComparison.Ordinal)); - } + Assert.Contains( + failure.Errors, + error => error.Pointer!.StartsWith("/providers/knowledge/fields", StringComparison.Ordinal)); + } - [Fact] - public void AKnowledgeProviderThatWritesEveryField_BindsThem() - { - const string document = """ + [Fact] + public void AKnowledgeProviderThatWritesEveryField_BindsThem() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -262,18 +264,18 @@ public void AKnowledgeProviderThatWritesEveryField_BindsThem() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - var knowledge = configuration.Providers!.Knowledge!; - Assert.Equal("qdrant", knowledge.Kind); - Assert.Equal("https://cluster.example.com:6334", knowledge.Endpoint); - Assert.Equal("manuals", knowledge.Collection); - } + KnowledgeProviderConfiguration knowledge = configuration.Providers!.Knowledge!; + Assert.Equal("qdrant", knowledge.Kind); + Assert.Equal("https://cluster.example.com:6334", knowledge.Endpoint); + Assert.Equal("manuals", knowledge.Collection); + } - [Fact] - public void AKnowledgeProviderWithNoVector_BindsNullMeaningTheAnonymousVector() - { - const string document = """ + [Fact] + public void AKnowledgeProviderWithNoVector_BindsNullMeaningTheAnonymousVector() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -289,15 +291,15 @@ public void AKnowledgeProviderWithNoVector_BindsNullMeaningTheAnonymousVector() agent: only """; - var knowledge = ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!; + KnowledgeProviderConfiguration knowledge = ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!; - Assert.Null(knowledge.Vector); - } + Assert.Null(knowledge.Vector); + } - [Fact] - public void AKnowledgeProviderNamingAMapper_BindsIt() - { - const string document = """ + [Fact] + public void AKnowledgeProviderNamingAMapper_BindsIt() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -316,30 +318,30 @@ public void AKnowledgeProviderNamingAMapper_BindsIt() agent: only """; - Assert.Equal("acme-catalog", ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!.Mapper); - } + Assert.Equal("acme-catalog", ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!.Mapper); + } - [Fact] - public void Example_BindsTheSpokenFallbackAndTheSampleRate() - { - // Both keys are optional, and the worked example writes both at their default. - Assert.Equal(AgentCoreConfiguration.DefaultFallbackReply, Example.FallbackReply); - Assert.NotNull(Example.Evaluation); - Assert.Equal(EvaluationConfiguration.DefaultSampleRate, Example.Evaluation!.SampleRate); - } + [Fact] + public void Example_BindsTheSpokenFallbackAndTheSampleRate() + { + // Both keys are optional, and the worked example writes both at their default. + Assert.Equal(AgentCoreConfiguration.DefaultFallbackReply, Example.FallbackReply); + Assert.NotNull(Example.Evaluation); + Assert.Equal(EvaluationConfiguration.DefaultSampleRate, Example.Evaluation!.SampleRate); + } - [Fact] - public void Example_BindsTheJudgeModelReference() - { - Assert.NotNull(Example.Evaluation!.Judge); - Assert.Equal("judge", Example.Evaluation.Judge!.Ref); - Assert.Equal(0, Example.Evaluation.Judge.Temperature); - } + [Fact] + public void Example_BindsTheJudgeModelReference() + { + Assert.NotNull(Example.Evaluation!.Judge); + Assert.Equal("judge", Example.Evaluation.Judge!.Ref); + Assert.Equal(0, Example.Evaluation.Judge.Temperature); + } - [Fact] - public void AnEvaluationSectionWithNoJudge_LeavesTheReferenceNull() - { - const string document = """ + [Fact] + public void AnEvaluationSectionWithNoJudge_LeavesTheReferenceNull() + { + const string document = """ apiVersion: agentcore/v1 evaluation: sampleRate: 0.25 @@ -351,15 +353,15 @@ public void AnEvaluationSectionWithNoJudge_LeavesTheReferenceNull() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Null(configuration.Evaluation!.Judge); - } + Assert.Null(configuration.Evaluation!.Judge); + } - [Fact] - public void AJudgeWithNoRef_FailsTheLoad() - { - const string document = """ + [Fact] + public void AJudgeWithNoRef_FailsTheLoad() + { + const string document = """ apiVersion: agentcore/v1 evaluation: judge: { temperature: 0 } @@ -371,15 +373,15 @@ public void AJudgeWithNoRef_FailsTheLoad() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/evaluation/judge"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/evaluation/judge"); + } - [Fact] - public void ADocumentThatSetsBothTunableKeys_BindsThem() - { - const string document = """ + [Fact] + public void ADocumentThatSetsBothTunableKeys_BindsThem() + { + const string document = """ apiVersion: agentcore/v1 fallbackReply: "One moment please. I will try that again." evaluation: @@ -392,16 +394,16 @@ public void ADocumentThatSetsBothTunableKeys_BindsThem() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal("One moment please. I will try that again.", configuration.FallbackReply); - Assert.Equal(0.25, configuration.Evaluation!.SampleRate); - } + Assert.Equal("One moment please. I will try that again.", configuration.FallbackReply); + Assert.Equal(0.25, configuration.Evaluation!.SampleRate); + } - [Fact] - public void ADocumentThatOmitsBothTunableKeys_TakesTheDefaults() - { - const string document = """ + [Fact] + public void ADocumentThatOmitsBothTunableKeys_TakesTheDefaults() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -411,24 +413,24 @@ public void ADocumentThatOmitsBothTunableKeys_TakesTheDefaults() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - // Section 8.7 still speaks a fallback, and T18 still evaluates no turn. - Assert.Equal(AgentCoreConfiguration.DefaultFallbackReply, configuration.FallbackReply); - Assert.Null(configuration.Evaluation); - } + // Section 8.7 still speaks a fallback, and T18 still evaluates no turn. + Assert.Equal(AgentCoreConfiguration.DefaultFallbackReply, configuration.FallbackReply); + Assert.Null(configuration.Evaluation); + } - [Fact] - public void Example_BindsTheSpokenRefusal() - { - // The key is optional, and the worked example writes it at its default. - Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, Example.RefusalReply); - } + [Fact] + public void Example_BindsTheSpokenRefusal() + { + // The key is optional, and the worked example writes it at its default. + Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, Example.RefusalReply); + } - [Fact] - public void ADocumentThatSetsTheRefusalReply_BindsIt() - { - const string document = """ + [Fact] + public void ADocumentThatSetsTheRefusalReply_BindsIt() + { + const string document = """ apiVersion: agentcore/v1 refusalReply: "I am not able to answer that." agents: @@ -439,15 +441,15 @@ public void ADocumentThatSetsTheRefusalReply_BindsIt() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal("I am not able to answer that.", configuration.RefusalReply); - } + Assert.Equal("I am not able to answer that.", configuration.RefusalReply); + } - [Fact] - public void ADocumentThatOmitsTheRefusalReply_TakesTheDefault() - { - const string document = """ + [Fact] + public void ADocumentThatOmitsTheRefusalReply_TakesTheDefault() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -457,16 +459,16 @@ public void ADocumentThatOmitsTheRefusalReply_TakesTheDefault() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - // A document written before the key existed behaves the same way. - Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, configuration.RefusalReply); - } + // A document written before the key existed behaves the same way. + Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, configuration.RefusalReply); + } - [Fact] - public void ADocumentThatSetsOnlyOneSpokenLine_LeavesTheOtherAtItsDefault() - { - var withFallback = ConfigurationLoader.LoadYaml(""" + [Fact] + public void ADocumentThatSetsOnlyOneSpokenLine_LeavesTheOtherAtItsDefault() + { + AgentCoreConfiguration withFallback = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 fallbackReply: "One moment please. I will try that again." agents: @@ -476,7 +478,7 @@ public void ADocumentThatSetsOnlyOneSpokenLine_LeavesTheOtherAtItsDefault() main: agent: only """); - var withRefusal = ConfigurationLoader.LoadYaml(""" + AgentCoreConfiguration withRefusal = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 refusalReply: "I am not able to answer that." agents: @@ -487,16 +489,16 @@ public void ADocumentThatSetsOnlyOneSpokenLine_LeavesTheOtherAtItsDefault() agent: only """); - Assert.Equal("One moment please. I will try that again.", withFallback.FallbackReply); - Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, withFallback.RefusalReply); - Assert.Equal(AgentCoreConfiguration.DefaultFallbackReply, withRefusal.FallbackReply); - Assert.Equal("I am not able to answer that.", withRefusal.RefusalReply); - } + Assert.Equal("One moment please. I will try that again.", withFallback.FallbackReply); + Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, withFallback.RefusalReply); + Assert.Equal(AgentCoreConfiguration.DefaultFallbackReply, withRefusal.FallbackReply); + Assert.Equal("I am not able to answer that.", withRefusal.RefusalReply); + } - [Fact] - public void ADocumentThatSetsBothSpokenLines_BindsThemIndependently() - { - const string document = """ + [Fact] + public void ADocumentThatSetsBothSpokenLines_BindsThemIndependently() + { + const string document = """ apiVersion: agentcore/v1 fallbackReply: "One moment please. I will try that again." refusalReply: "I am not able to answer that." @@ -508,16 +510,16 @@ public void ADocumentThatSetsBothSpokenLines_BindsThemIndependently() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal("One moment please. I will try that again.", configuration.FallbackReply); - Assert.Equal("I am not able to answer that.", configuration.RefusalReply); - } + Assert.Equal("One moment please. I will try that again.", configuration.FallbackReply); + Assert.Equal("I am not able to answer that.", configuration.RefusalReply); + } - [Fact] - public void AnEvaluationSectionWithNoRate_TakesTheDefaultRate() - { - const string document = """ + [Fact] + public void AnEvaluationSectionWithNoRate_TakesTheDefaultRate() + { + const string document = """ apiVersion: agentcore/v1 evaluation: {} agents: @@ -528,31 +530,31 @@ public void AnEvaluationSectionWithNoRate_TakesTheDefaultRate() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal(EvaluationConfiguration.DefaultSampleRate, configuration.Evaluation!.SampleRate); - } + Assert.Equal(EvaluationConfiguration.DefaultSampleRate, configuration.Evaluation!.SampleRate); + } - [Theory] - [InlineData("0", 0.0)] - [InlineData("1", 1.0)] - [InlineData("0.05", 0.05)] - public void ASampleRateInsideTheRange_Binds(string written, double expected) - { - var configuration = ConfigurationLoader.LoadYaml( - $"apiVersion: agentcore/v1\nevaluation:\n sampleRate: {written}\nagents:\n items:\n - {{ id: only, instructions: \"ok\" }}\nentries:\n main:\n agent: only\n"); + [Theory] + [InlineData("0", 0.0)] + [InlineData("1", 1.0)] + [InlineData("0.05", 0.05)] + public void ASampleRateInsideTheRange_Binds(string written, double expected) + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml( + $"apiVersion: agentcore/v1\nevaluation:\n sampleRate: {written}\nagents:\n items:\n - {{ id: only, instructions: \"ok\" }}\nentries:\n main:\n agent: only\n"); - Assert.Equal(expected, configuration.Evaluation!.SampleRate); - } + Assert.Equal(expected, configuration.Evaluation!.SampleRate); + } - /// - /// A repeated key is a mistake in both formats. On the YAML path YamlDotNet's own loader rejects - /// two keys that are the same YAML node, before walks the mapping. - /// - [Fact] - public void ADuplicateKeyInYaml_FailsTheLoad() - { - const string document = """ + /// + /// A repeated key is a mistake in both formats. On the YAML path YamlDotNet's own loader rejects + /// two keys that are the same YAML node, before walks the mapping. + /// + [Fact] + public void ADuplicateKeyInYaml_FailsTheLoad() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -565,24 +567,24 @@ public void ADuplicateKeyInYaml_FailsTheLoad() - { id: only, instructions: "ok" } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Message.Contains("Duplicate key", StringComparison.Ordinal)); - } + Assert.Contains(failure.Errors, error => error.Message.Contains("Duplicate key", StringComparison.Ordinal)); + } - /// - /// Two keys that differ as YAML and agree as JSON are still one key in the document tree. - /// - /// - /// A tag makes two scalars different YAML nodes, so YamlDotNet keeps both — and both name the - /// property "1" once the mapping becomes a JsonObject. The check in - /// YamlToJson.ConvertMapping is what catches this, and it is the only thing that does: - /// without it the second value silently replaces the first. - /// - [Fact] - public void TwoKeysThatDifferOnlyByTag_FailTheLoad() - { - const string document = """ + /// + /// Two keys that differ as YAML and agree as JSON are still one key in the document tree. + /// + /// + /// A tag makes two scalars different YAML nodes, so YamlDotNet keeps both — and both name the + /// property "1" once the mapping becomes a JsonObject. The check in + /// YamlToJson.ConvertMapping is what catches this, and it is the only thing that does: + /// without it the second value silently replaces the first. + /// + [Fact] + public void TwoKeysThatDifferOnlyByTag_FailTheLoad() + { + const string document = """ apiVersion: agentcore/v1 !!str 1: first 1: second @@ -594,51 +596,51 @@ public void TwoKeysThatDifferOnlyByTag_FailTheLoad() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.Syntax, failure.Check); - Assert.Contains(failure.Errors, error => error.Message.Contains("appears twice", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.Syntax, failure.Check); + Assert.Contains(failure.Errors, error => error.Message.Contains("appears twice", StringComparison.Ordinal)); + } - /// - /// A number no can hold is a defect in the document, not a crash. - /// - /// - /// It parses to an infinity, which JSON cannot write. The loader used to let the - /// ArgumentException that came of it straight out, past the - /// section 8.7 tells every caller to catch. - /// - [Theory] - [InlineData("1e400")] - [InlineData("-1e400")] - public void ANumberTooLargeToHold_FailsTheLoad(string written) - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml($"apiVersion: agentcore/v1\nevaluation:\n sampleRate: {written}\n")); + /// + /// A number no can hold is a defect in the document, not a crash. + /// + /// + /// It parses to an infinity, which JSON cannot write. The loader used to let the + /// ArgumentException that came of it straight out, past the + /// section 8.7 tells every caller to catch. + /// + [Theory] + [InlineData("1e400")] + [InlineData("-1e400")] + public void ANumberTooLargeToHold_FailsTheLoad(string written) + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml($"apiVersion: agentcore/v1\nevaluation:\n sampleRate: {written}\n")); - Assert.Equal(ConfigurationCheck.Syntax, failure.Check); - Assert.Contains(failure.Errors, error => error.Message.Contains("larger than a number can hold", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.Syntax, failure.Check); + Assert.Contains(failure.Errors, error => error.Message.Contains("larger than a number can hold", StringComparison.Ordinal)); + } - /// A number that underflows is zero, which JSON can write, so it loads. - [Fact] - public void ANumberTooSmallToHold_ReadsAsZero() - { - var configuration = ConfigurationLoader.LoadYaml( - "apiVersion: agentcore/v1\nevaluation:\n sampleRate: 1e-400\nagents:\n items:\n - { id: only, instructions: \"ok\" }\nentries:\n main:\n agent: only\n"); + /// A number that underflows is zero, which JSON can write, so it loads. + [Fact] + public void ANumberTooSmallToHold_ReadsAsZero() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml( + "apiVersion: agentcore/v1\nevaluation:\n sampleRate: 1e-400\nagents:\n items:\n - { id: only, instructions: \"ok\" }\nentries:\n main:\n agent: only\n"); - Assert.Equal(0, configuration.Evaluation!.SampleRate); - } + Assert.Equal(0, configuration.Evaluation!.SampleRate); + } - /// - /// A repeated key on the JSON path is rejected by ReadJson's own - /// setting before the - /// document ever reaches the shared reparse. This pins that behaviour too. - /// - [Fact] - public void ADuplicateKeyInJson_FailsTheLoad() - { - const string document = """ + /// + /// A repeated key on the JSON path is rejected by ReadJson's own + /// setting before the + /// document ever reaches the shared reparse. This pins that behaviour too. + /// + [Fact] + public void ADuplicateKeyInJson_FailsTheLoad() + { + const string document = /*lang=json,strict*/ """ { "apiVersion": "agentcore/v1", "agents": { "items": [{ "id": "only" }] }, @@ -646,15 +648,15 @@ public void ADuplicateKeyInJson_FailsTheLoad() } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadJson(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadJson(document)); - Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.Syntax); - } + Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.Syntax); + } - [Fact] - public void Load_AToolWithAModelRef_ReadsIt() - { - const string document = """ + [Fact] + public void Load_AToolWithAModelRef_ReadsIt() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: search, kind: builtin, uses: web.search, description: d, model: { ref: cheap } } @@ -666,15 +668,15 @@ public void Load_AToolWithAModelRef_ReadsIt() agent: search """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal("cheap", configuration.Tools[0].Model!.Ref); - } + Assert.Equal("cheap", configuration.Tools[0].Model!.Ref); + } - [Fact] - public void Load_AToolWithMaxRounds_ReadsIt() - { - const string document = """ + [Fact] + public void Load_AToolWithMaxRounds_ReadsIt() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: dummy, kind: builtin, uses: web.search, description: d, maxRounds: 4 } @@ -686,15 +688,15 @@ public void Load_AToolWithMaxRounds_ReadsIt() agent: only """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal(4, configuration.Tools[0].MaxRounds); - } + Assert.Equal(4, configuration.Tools[0].MaxRounds); + } - [Fact] - public void NoLinksBlock_LeavesLinksNullAndTheFeatureOff() - { - const string document = """ + [Fact] + public void NoLinksBlock_LeavesLinksNullAndTheFeatureOff() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -710,14 +712,14 @@ public void NoLinksBlock_LeavesLinksNullAndTheFeatureOff() agent: only """; - Assert.Null(ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!.Links); - } + Assert.Null(ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!.Links); + } - [Fact] - public void ALinksBlockWithoutLookup_DefaultsToFilter() - { - // filter is the only mode that works on any collection. uuid5 and direct derive the key. - const string document = """ + [Fact] + public void ALinksBlockWithoutLookup_DefaultsToFilter() + { + // filter is the only mode that works on any collection. uuid5 and direct derive the key. + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -736,33 +738,34 @@ public void ALinksBlockWithoutLookup_DefaultsToFilter() agent: only """; - var links = ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!.Links; + KnowledgeLinksConfiguration? links = ConfigurationLoader.LoadYaml(document).Providers!.Knowledge!.Links; - Assert.NotNull(links); - Assert.Equal(KnowledgeLinkLookup.Filter, links!.Lookup); - Assert.Equal("related", links.Field); - } + Assert.NotNull(links); + Assert.Equal(KnowledgeLinkLookup.Filter, links!.Lookup); + Assert.Equal("related", links.Field); + } - [Fact] - public void ShippedExampleFile_Loads() - { - var path = Path.Combine(RepositoryRoot(), "config", "example.yaml"); - Assert.True(File.Exists(path), $"The shipped example is missing at '{path}'."); + [Fact] + public void ShippedExampleFile_Loads() + { + string path = Path.Combine(RepositoryRoot(), "config", "example.yaml"); + Assert.True(File.Exists(path), $"The shipped example is missing at '{path}'."); - var shipped = ConfigurationLoader.LoadFile(path); + AgentCoreConfiguration shipped = ConfigurationLoader.LoadFile(path); - Assert.Equal(JsonSerializer.Serialize(Example), JsonSerializer.Serialize(shipped)); - } + Assert.Equal(JsonSerializer.Serialize(Example), JsonSerializer.Serialize(shipped)); + } - private static string RepositoryRoot() - { - var directory = new DirectoryInfo(AppContext.BaseDirectory); - while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + private static string RepositoryRoot() { - directory = directory.Parent; - } + DirectoryInfo? directory = new(AppContext.BaseDirectory); + while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + { + directory = directory.Parent; + } - Assert.NotNull(directory); - return directory!.FullName; + Assert.NotNull(directory); + return directory!.FullName; + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationRoundTripTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationRoundTripTests.cs index 7f0feccc..37abfcf1 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationRoundTripTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationRoundTripTests.cs @@ -4,69 +4,71 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// Rule 17 of section 11: the same document loads identically as YAML and as JSON. -/// -public sealed class ConfigurationRoundTripTests +namespace AgentCore.Application.Tests.Configuration { /// - /// Writes one bound document out as JSON, so two loads compare by content. + /// Rule 17 of section 11: the same document loads identically as YAML and as JSON. /// - /// - /// The bound records hold BCL collections, which a record compares by reference, so - /// Assert.Equal on two values would only ever say - /// "different object". Serialising walks every bound field instead — including the raw - /// rules, which a reference comparison would also have missed. - /// - /// The bound document. - /// The content of every bound field, as one JSON string. - private static string Content(AgentCoreConfiguration configuration) - => JsonSerializer.Serialize(configuration); - - [Fact] - public void SameDocument_BindsToTheSameContent() - { - var fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var fromJson = ConfigurationLoader.LoadJson(ExampleDocument.Json); - - Assert.Equal(Content(fromYaml), Content(fromJson)); - } - - [Fact] - public void SameDocument_ReadsToTheSameNodeTree() - { - var fromYaml = ConfigurationLoader.ReadDocument(ExampleDocument.Yaml, ConfigurationFormat.Yaml); - var fromJson = ConfigurationLoader.ReadDocument(ExampleDocument.Json, ConfigurationFormat.Json); - - Assert.True(JsonNode.DeepEquals(fromYaml, fromJson)); - } - - [Fact] - public void ADifferentDocument_DoesNotBindToTheSameContent() - { - var fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var changed = ConfigurationLoader.LoadJson( - ExampleDocument.Json.Replace("Please say it again.", "Please try once more.", StringComparison.Ordinal)); - - Assert.NotEqual(Content(fromYaml), Content(changed)); - } - - [Fact] - public void AChangedGuardThreshold_DoesNotBindToTheSameContent() - { - var fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var changed = ConfigurationLoader.LoadYaml( - ExampleDocument.Yaml.Replace("failedResolveTurns }, 3 ]", "failedResolveTurns }, 4 ]", StringComparison.Ordinal)); - - Assert.NotEqual(Content(fromYaml), Content(changed)); - } - - [Fact] - public void TheTwoTunableKeys_ReadTheSameFromYamlAndFromJson() + public sealed class ConfigurationRoundTripTests { - var fromYaml = ConfigurationLoader.LoadYaml(""" + /// + /// Writes one bound document out as JSON, so two loads compare by content. + /// + /// + /// The bound records hold BCL collections, which a record compares by reference, so + /// Assert.Equal on two values would only ever say + /// "different object". Serialising walks every bound field instead — including the raw + /// rules, which a reference comparison would also have missed. + /// + /// The bound document. + /// The content of every bound field, as one JSON string. + private static string Content(AgentCoreConfiguration configuration) + { + return JsonSerializer.Serialize(configuration); + } + + [Fact] + public void SameDocument_BindsToTheSameContent() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + AgentCoreConfiguration fromJson = ConfigurationLoader.LoadJson(ExampleDocument.Json); + + Assert.Equal(Content(fromYaml), Content(fromJson)); + } + + [Fact] + public void SameDocument_ReadsToTheSameNodeTree() + { + JsonNode fromYaml = ConfigurationLoader.ReadDocument(ExampleDocument.Yaml, ConfigurationFormat.Yaml); + JsonNode fromJson = ConfigurationLoader.ReadDocument(ExampleDocument.Json, ConfigurationFormat.Json); + + Assert.True(JsonNode.DeepEquals(fromYaml, fromJson)); + } + + [Fact] + public void ADifferentDocument_DoesNotBindToTheSameContent() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + AgentCoreConfiguration changed = ConfigurationLoader.LoadJson( + ExampleDocument.Json.Replace("Please say it again.", "Please try once more.", StringComparison.Ordinal)); + + Assert.NotEqual(Content(fromYaml), Content(changed)); + } + + [Fact] + public void AChangedGuardThreshold_DoesNotBindToTheSameContent() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + AgentCoreConfiguration changed = ConfigurationLoader.LoadYaml( + ExampleDocument.Yaml.Replace("failedResolveTurns }, 3 ]", "failedResolveTurns }, 4 ]", StringComparison.Ordinal)); + + Assert.NotEqual(Content(fromYaml), Content(changed)); + } + + [Fact] + public void TheTwoTunableKeys_ReadTheSameFromYamlAndFromJson() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 fallbackReply: "One moment please. I will try that again." evaluation: @@ -78,7 +80,7 @@ public void TheTwoTunableKeys_ReadTheSameFromYamlAndFromJson() main: agent: only """); - var fromJson = ConfigurationLoader.LoadJson(""" + AgentCoreConfiguration fromJson = ConfigurationLoader.LoadJson(/*lang=json,strict*/ """ { "apiVersion": "agentcore/v1", "fallbackReply": "One moment please. I will try that again.", @@ -88,33 +90,33 @@ public void TheTwoTunableKeys_ReadTheSameFromYamlAndFromJson() } """); - Assert.Equal(Content(fromYaml), Content(fromJson)); - } - - [Fact] - public void AChangedSampleRate_DoesNotBindToTheSameContent() - { - var fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var changed = ConfigurationLoader.LoadYaml( - ExampleDocument.Yaml.Replace("sampleRate: 0", "sampleRate: 0.5", StringComparison.Ordinal)); - - Assert.NotEqual(Content(fromYaml), Content(changed)); - } - - [Fact] - public void AChangedFallbackReply_DoesNotBindToTheSameContent() - { - var fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var changed = ConfigurationLoader.LoadYaml( - ExampleDocument.Yaml.Replace("Please say it again.", "Please try once more.", StringComparison.Ordinal)); - - Assert.NotEqual(Content(fromYaml), Content(changed)); - } - - [Fact] - public void TheTwoSpokenLines_ReadTheSameFromYamlAndFromJson() - { - var fromYaml = ConfigurationLoader.LoadYaml(""" + Assert.Equal(Content(fromYaml), Content(fromJson)); + } + + [Fact] + public void AChangedSampleRate_DoesNotBindToTheSameContent() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + AgentCoreConfiguration changed = ConfigurationLoader.LoadYaml( + ExampleDocument.Yaml.Replace("sampleRate: 0", "sampleRate: 0.5", StringComparison.Ordinal)); + + Assert.NotEqual(Content(fromYaml), Content(changed)); + } + + [Fact] + public void AChangedFallbackReply_DoesNotBindToTheSameContent() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + AgentCoreConfiguration changed = ConfigurationLoader.LoadYaml( + ExampleDocument.Yaml.Replace("Please say it again.", "Please try once more.", StringComparison.Ordinal)); + + Assert.NotEqual(Content(fromYaml), Content(changed)); + } + + [Fact] + public void TheTwoSpokenLines_ReadTheSameFromYamlAndFromJson() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 fallbackReply: "One moment please. I will try that again." refusalReply: "I am not able to answer that." @@ -125,7 +127,7 @@ public void TheTwoSpokenLines_ReadTheSameFromYamlAndFromJson() main: agent: only """); - var fromJson = ConfigurationLoader.LoadJson(""" + AgentCoreConfiguration fromJson = ConfigurationLoader.LoadJson(/*lang=json,strict*/ """ { "apiVersion": "agentcore/v1", "fallbackReply": "One moment please. I will try that again.", @@ -135,92 +137,92 @@ public void TheTwoSpokenLines_ReadTheSameFromYamlAndFromJson() } """); - Assert.Equal(Content(fromYaml), Content(fromJson)); - } - - [Fact] - public void AChangedRefusalReply_DoesNotBindToTheSameContent() - { - var fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var changed = ConfigurationLoader.LoadYaml( - ExampleDocument.Yaml.Replace( - "I cannot help with that request.", - "I am not able to answer that.", - StringComparison.Ordinal)); - - Assert.NotEqual(Content(fromYaml), Content(changed)); - } - - [Fact] - public void ADuplicateJsonKey_Fails() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadJson("""{"apiVersion":"agentcore/v1","name":"first","name":"second"}""")); - - Assert.Equal(ConfigurationCheck.Syntax, failure.Check); - } - - [Theory] - [InlineData("value: 3", 3L)] - [InlineData("value: -7", -7L)] - [InlineData("value: 0x10", 16L)] - public void APlainIntegerScalar_ReadsAsANumber(string yaml, long expected) - { - var document = ConfigurationLoader.ReadDocument(yaml, ConfigurationFormat.Yaml); - - Assert.Equal(expected, document["value"]!.GetValue()); - } - - [Theory] - [InlineData("value: true", true)] - [InlineData("value: FALSE", false)] - public void APlainBooleanScalar_ReadsAsABoolean(string yaml, bool expected) - { - var document = ConfigurationLoader.ReadDocument(yaml, ConfigurationFormat.Yaml); - - Assert.Equal(expected, document["value"]!.GetValue()); - } - - /// - /// The scalars that stay text. - /// - /// - /// The last four are the ones that separate the YAML 1.2 core schema from a looser reading. An - /// explicit !!str tag is the document's only way to force text onto something that would - /// otherwise be a number or a boolean, and a thousands separator or a pair of accounting - /// parentheses is a typo in a configuration document, not a number. Reading any of them as a - /// number would let a mistyped value pass check 1 with a value nobody wrote. - /// - [Theory] - [InlineData("value: \"3\"", "3")] - [InlineData("value: 'true'", "true")] - [InlineData("value: gpt-4.1-mini", "gpt-4.1-mini")] - [InlineData("value: agentcore/v1", "agentcore/v1")] - [InlineData("value: ./kb", "./kb")] - [InlineData("value: yes", "yes")] - [InlineData("value: !!str 1", "1")] - [InlineData("value: !!str true", "true")] - [InlineData("value: 1,000", "1,000")] - [InlineData("value: (5)", "(5)")] - public void AQuotedOrWordScalar_ReadsAsAString(string yaml, string expected) - { - var document = ConfigurationLoader.ReadDocument(yaml, ConfigurationFormat.Yaml); - - Assert.Equal(expected, document["value"]!.GetValue()); - } - - [Fact] - public void APlainFloatScalar_ReadsAsANumber() - { - var document = ConfigurationLoader.ReadDocument("value: 0.3", ConfigurationFormat.Yaml); - - Assert.Equal(0.3, document["value"]!.GetValue()); - } - - [Fact] - public void TheAgenticKeys_ReadTheSameFromYamlAndFromJson() - { - const string yaml = """ + Assert.Equal(Content(fromYaml), Content(fromJson)); + } + + [Fact] + public void AChangedRefusalReply_DoesNotBindToTheSameContent() + { + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + AgentCoreConfiguration changed = ConfigurationLoader.LoadYaml( + ExampleDocument.Yaml.Replace( + "I cannot help with that request.", + "I am not able to answer that.", + StringComparison.Ordinal)); + + Assert.NotEqual(Content(fromYaml), Content(changed)); + } + + [Fact] + public void ADuplicateJsonKey_Fails() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadJson(/*lang=json,strict*/ """{"apiVersion":"agentcore/v1","name":"first","name":"second"}""")); + + Assert.Equal(ConfigurationCheck.Syntax, failure.Check); + } + + [Theory] + [InlineData("value: 3", 3L)] + [InlineData("value: -7", -7L)] + [InlineData("value: 0x10", 16L)] + public void APlainIntegerScalar_ReadsAsANumber(string yaml, long expected) + { + JsonNode document = ConfigurationLoader.ReadDocument(yaml, ConfigurationFormat.Yaml); + + Assert.Equal(expected, document["value"]!.GetValue()); + } + + [Theory] + [InlineData("value: true", true)] + [InlineData("value: FALSE", false)] + public void APlainBooleanScalar_ReadsAsABoolean(string yaml, bool expected) + { + JsonNode document = ConfigurationLoader.ReadDocument(yaml, ConfigurationFormat.Yaml); + + Assert.Equal(expected, document["value"]!.GetValue()); + } + + /// + /// The scalars that stay text. + /// + /// + /// The last four are the ones that separate the YAML 1.2 core schema from a looser reading. An + /// explicit !!str tag is the document's only way to force text onto something that would + /// otherwise be a number or a boolean, and a thousands separator or a pair of accounting + /// parentheses is a typo in a configuration document, not a number. Reading any of them as a + /// number would let a mistyped value pass check 1 with a value nobody wrote. + /// + [Theory] + [InlineData("value: \"3\"", "3")] + [InlineData("value: 'true'", "true")] + [InlineData("value: gpt-4.1-mini", "gpt-4.1-mini")] + [InlineData("value: agentcore/v1", "agentcore/v1")] + [InlineData("value: ./kb", "./kb")] + [InlineData("value: yes", "yes")] + [InlineData("value: !!str 1", "1")] + [InlineData("value: !!str true", "true")] + [InlineData("value: 1,000", "1,000")] + [InlineData("value: (5)", "(5)")] + public void AQuotedOrWordScalar_ReadsAsAString(string yaml, string expected) + { + JsonNode document = ConfigurationLoader.ReadDocument(yaml, ConfigurationFormat.Yaml); + + Assert.Equal(expected, document["value"]!.GetValue()); + } + + [Fact] + public void APlainFloatScalar_ReadsAsANumber() + { + JsonNode document = ConfigurationLoader.ReadDocument("value: 0.3", ConfigurationFormat.Yaml); + + Assert.Equal(0.3, document["value"]!.GetValue()); + } + + [Fact] + public void TheAgenticKeys_ReadTheSameFromYamlAndFromJson() + { + const string yaml = """ apiVersion: agentcore/v1 agents: defaults: @@ -248,7 +250,7 @@ public void TheAgenticKeys_ReadTheSameFromYamlAndFromJson() main: agent: coder """; - const string json = $$""" + const string json = $$""" { "apiVersion": "agentcore/v1", "agents": { @@ -282,8 +284,9 @@ public void TheAgenticKeys_ReadTheSameFromYamlAndFromJson() } """; - var fromYaml = ConfigurationLoader.LoadYaml(yaml); + AgentCoreConfiguration fromYaml = ConfigurationLoader.LoadYaml(yaml); - Assert.Equal(Content(fromYaml), Content(ConfigurationLoader.LoadJson(json))); + Assert.Equal(Content(fromYaml), Content(ConfigurationLoader.LoadJson(json))); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs index 0fa6dd2e..83d94f69 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs @@ -1,25 +1,27 @@ +using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// Check 1 of section 8.5, and the JSON Pointer that section 8.7 requires of every load failure. -/// -public sealed class ConfigurationSchemaValidatorTests +namespace AgentCore.Application.Tests.Configuration { - [Fact] - public void TheExample_PassesCheckOne() + /// + /// Check 1 of section 8.5, and the JSON Pointer that section 8.7 requires of every load failure. + /// + public sealed class ConfigurationSchemaValidatorTests { - var document = ConfigurationLoader.ReadDocument(ExampleDocument.Yaml, ConfigurationFormat.Yaml); + [Fact] + public void TheExample_PassesCheckOne() + { + JsonNode document = ConfigurationLoader.ReadDocument(ExampleDocument.Yaml, ConfigurationFormat.Yaml); - Assert.Empty(ConfigurationSchemaValidator.Evaluate(document)); - } + Assert.Empty(ConfigurationSchemaValidator.Evaluate(document)); + } - [Fact] - public void AnUnknownToolKind_FailsWithThePointerOfThatTool() - { - const string document = """ + [Fact] + public void AnUnknownToolKind_FailsWithThePointerOfThatTool() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: search_chunks, kind: builtin, uses: knowledge.search } @@ -32,47 +34,47 @@ public void AnUnknownToolKind_FailsWithThePointerOfThatTool() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/tools/1/kind"); - Assert.Contains("/tools/1/kind", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/tools/1/kind"); + Assert.Contains("/tools/1/kind", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AMissingRequiredProperty_FailsWithThePointerOfItsParent() - { - const string document = """ + [Fact] + public void AMissingRequiredProperty_FailsWithThePointerOfItsParent() + { + const string document = """ apiVersion: agentcore/v1 entries: main: agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Equal(ConfigurationError.RootPointer, failure.Pointer); - Assert.Contains("agents", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Equal(ConfigurationError.RootPointer, failure.Pointer); + Assert.Contains("agents", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AWrongApiVersion_FailsWithThePointerOfTheField() - { - const string document = """ + [Fact] + public void AWrongApiVersion_FailsWithThePointerOfTheField() + { + const string document = """ apiVersion: agentcore/v2 """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/apiVersion"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/apiVersion"); + } - [Fact] - public void ASecondExtractorTrigger_Fails() - { - const string document = """ + [Fact] + public void ASecondExtractorTrigger_Fails() + { + const string document = """ apiVersion: agentcore/v1 extractor: model: { ref: fill } @@ -85,28 +87,28 @@ public void ASecondExtractorTrigger_Fails() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/extractor/when"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/extractor/when"); + } - [Fact] - public void ATitlerWithNoModel_Fails() - { - const string document = """ + [Fact] + public void ATitlerWithNoModel_Fails() + { + const string document = """ apiVersion: agentcore/v1 titler: {} """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/titler"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/titler"); + } - [Fact] - public void ASecondKeyInTheTitler_Fails() - { - const string document = """ + [Fact] + public void ASecondKeyInTheTitler_Fails() + { + const string document = """ apiVersion: agentcore/v1 titler: model: { ref: fill } @@ -119,15 +121,15 @@ public void ASecondKeyInTheTitler_Fails() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/titler"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/titler"); + } - [Fact] - public void AToolWriterWithNoPath_FailsWithThePointerOfTheSlot() - { - const string document = """ + [Fact] + public void AToolWriterWithNoPath_FailsWithThePointerOfTheSlot() + { + const string document = """ apiVersion: agentcore/v1 state: orderStatus: { type: string, writer: tool } @@ -139,41 +141,41 @@ public void AToolWriterWithNoPath_FailsWithThePointerOfTheSlot() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Contains(failure.Errors, error => error.Pointer == "/state/orderStatus"); - } - - [Theory] - [InlineData("\"\"")] - [InlineData("\" \"")] - public void AFallbackReplyWithNoWords_FailsWithThePointerOfTheField(string written) - { - // Section 8.7 asks for a spoken fallback, and a line with no words is silence on a conversation. - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml($"apiVersion: agentcore/v1\nfallbackReply: {written}\n")); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/fallbackReply"); - } - - [Theory] - [InlineData("\"\"")] - [InlineData("\" \"")] - public void ARefusalReplyWithNoWords_FailsWithThePointerOfTheField(string written) - { - // The refusal is spoken too, and a line with no words is silence on a conversation. - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml($"apiVersion: agentcore/v1\nrefusalReply: {written}\n")); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/refusalReply"); - } - - [Fact] - public void ARefusalReplyThatIsNotAString_FailsWithThePointerOfTheField() - { - const string document = """ + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Contains(failure.Errors, error => error.Pointer == "/state/orderStatus"); + } + + [Theory] + [InlineData("\"\"")] + [InlineData("\" \"")] + public void AFallbackReplyWithNoWords_FailsWithThePointerOfTheField(string written) + { + // Section 8.7 asks for a spoken fallback, and a line with no words is silence on a conversation. + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml($"apiVersion: agentcore/v1\nfallbackReply: {written}\n")); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/fallbackReply"); + } + + [Theory] + [InlineData("\"\"")] + [InlineData("\" \"")] + public void ARefusalReplyWithNoWords_FailsWithThePointerOfTheField(string written) + { + // The refusal is spoken too, and a line with no words is silence on a conversation. + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml($"apiVersion: agentcore/v1\nrefusalReply: {written}\n")); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/refusalReply"); + } + + [Fact] + public void ARefusalReplyThatIsNotAString_FailsWithThePointerOfTheField() + { + const string document = """ apiVersion: agentcore/v1 refusalReply: 7 agents: @@ -184,45 +186,45 @@ public void ARefusalReplyThatIsNotAString_FailsWithThePointerOfTheField() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/refusalReply"); - Assert.Contains("/refusalReply", failure.Message, StringComparison.Ordinal); - } - - [Theory] - [InlineData("-0.1")] - [InlineData("1.1")] - public void ASampleRateOutsideTheRange_FailsWithThePointerOfTheField(string written) - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml( - $"apiVersion: agentcore/v1\nevaluation:\n sampleRate: {written}\n")); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/evaluation/sampleRate"); - Assert.Contains("/evaluation/sampleRate", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void ASampleRateThatIsNotANumber_FailsWithThePointerOfTheField() - { - const string document = """ + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/refusalReply"); + Assert.Contains("/refusalReply", failure.Message, StringComparison.Ordinal); + } + + [Theory] + [InlineData("-0.1")] + [InlineData("1.1")] + public void ASampleRateOutsideTheRange_FailsWithThePointerOfTheField(string written) + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml( + $"apiVersion: agentcore/v1\nevaluation:\n sampleRate: {written}\n")); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/evaluation/sampleRate"); + Assert.Contains("/evaluation/sampleRate", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void ASampleRateThatIsNotANumber_FailsWithThePointerOfTheField() + { + const string document = """ apiVersion: agentcore/v1 evaluation: sampleRate: "half" """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/evaluation/sampleRate"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/evaluation/sampleRate"); + } - [Fact] - public void AnUnknownEvaluationKey_Fails() - { - const string document = """ + [Fact] + public void AnUnknownEvaluationKey_Fails() + { + const string document = """ apiVersion: agentcore/v1 evaluation: sampleRatio: 0.5 @@ -234,15 +236,15 @@ public void AnUnknownEvaluationKey_Fails() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains("sampleRatio", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("sampleRatio", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AnUnknownKnowledgeKey_Fails() - { - const string document = """ + [Fact] + public void AnUnknownKnowledgeKey_Fails() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -252,18 +254,18 @@ public void AnUnknownKnowledgeKey_Fails() knowledge: { vectors: zilliz } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/knowledge"); - Assert.Contains("vectors", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/knowledge"); + Assert.Contains("vectors", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void TheOldKnowledgeStoreKey_Fails() - { - // The store field went away. Each knowledge port now names its own adapter. - const string document = """ + [Fact] + public void TheOldKnowledgeStoreKey_Fails() + { + // The store field went away. Each knowledge port now names its own adapter. + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -279,16 +281,16 @@ public void TheOldKnowledgeStoreKey_Fails() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains("store", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains("store", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AKnowledgeProviderNamingOnlyKindAndCollection_PassesCheckOne() - { - const string document = """ + [Fact] + public void AKnowledgeProviderNamingOnlyKindAndCollection_PassesCheckOne() + { + const string document = """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -304,15 +306,15 @@ public void AKnowledgeProviderNamingOnlyKindAndCollection_PassesCheckOne() agent: only """; - var parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); + JsonNode parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); - Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); - } + Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); + } - [Fact] - public void AnUnknownProperty_Fails() - { - const string document = """ + [Fact] + public void AnUnknownProperty_Fails() + { + const string document = """ apiVersion: agentcore/v1 stage: greeting agents: @@ -323,15 +325,15 @@ public void AnUnknownProperty_Fails() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains("stage", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("stage", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void APolicyAndAGraphTogether_Fail() - { - const string document = """ + [Fact] + public void APolicyAndAGraphTogether_Fail() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -345,15 +347,15 @@ public void APolicyAndAGraphTogether_Fail() - { id: greeting, agent: only, terminal: true } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } - [Fact] - public void AGraphWithNodesAndEdges_Loads() - { - const string document = """ + [Fact] + public void AGraphWithNodesAndEdges_Loads() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -369,25 +371,25 @@ public void AGraphWithNodesAndEdges_Loads() - { from: draft, to: review, when: { var: resolved } } """; - var configuration = ConfigurationLoader.LoadYaml(document); - - var graph = configuration.Entries["main"].Graph; - Assert.NotNull(graph); - Assert.Null(graph!.Pattern); - Assert.Equal(2, graph.Nodes.Count); - Assert.True(graph.Nodes[0].Start); - Assert.True(graph.Nodes[1].Output); - - var edge = Assert.Single(graph.Edges); - Assert.Equal("draft", edge.From); - Assert.False(edge.When!.IsNamed); - Assert.Equal("""{"var":"resolved"}""", edge.When!.Rule!.ToJsonString()); - } - - [Fact] - public void AGraphWithAPattern_Loads() - { - const string document = """ + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + + GraphConfiguration? graph = configuration.Entries["main"].Graph; + Assert.NotNull(graph); + Assert.Null(graph!.Pattern); + Assert.Equal(2, graph.Nodes.Count); + Assert.True(graph.Nodes[0].Start); + Assert.True(graph.Nodes[1].Output); + + GraphEdgeConfiguration edge = Assert.Single(graph.Edges); + Assert.Equal("draft", edge.From); + Assert.False(edge.When!.IsNamed); + Assert.Equal(/*lang=json,strict*/ """{"var":"resolved"}""", edge.When!.Rule!.ToJsonString()); + } + + [Fact] + public void AGraphWithAPattern_Loads() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -400,26 +402,26 @@ public void AGraphWithAPattern_Loads() agents: [ writer, reviewer ] """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - Assert.Equal(AgentCore.Application.Configuration.Schema.GraphPattern.GroupChat, configuration.Entries["main"].Graph!.Pattern); - Assert.Equal(["writer", "reviewer"], configuration.Entries["main"].Graph!.Agents); - Assert.Empty(configuration.Entries["main"].Graph!.Nodes); - } + Assert.Equal(GraphPattern.GroupChat, configuration.Entries["main"].Graph!.Pattern); + Assert.Equal(["writer", "reviewer"], configuration.Entries["main"].Graph!.Agents); + Assert.Empty(configuration.Entries["main"].Graph!.Nodes); + } - [Fact] - public void MalformedYaml_FailsBeforeCheckOne() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml("apiVersion: [agentcore/v1")); + [Fact] + public void MalformedYaml_FailsBeforeCheckOne() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml("apiVersion: [agentcore/v1")); - Assert.Equal(ConfigurationCheck.Syntax, failure.Check); - } + Assert.Equal(ConfigurationCheck.Syntax, failure.Check); + } - [Fact] - public void ADuplicateKey_FailsBeforeCheckOne() - { - const string document = """ + [Fact] + public void ADuplicateKey_FailsBeforeCheckOne() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -432,37 +434,37 @@ public void ADuplicateKey_FailsBeforeCheckOne() - { id: only, instructions: "ok" } """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.Syntax, failure.Check); - } - - // --------------------------------------------------------------------------------------------- - // What the author of the document reads. - // - // The library writes for whoever wrote the schema. "All values fail against the false schema" is - // exact and says nothing to somebody looking at a YAML file, and the branch machinery of `if` and - // `oneOf` used to report its own misses as if they were the document's. These pin the sentences - // check 1 hands back instead. - // --------------------------------------------------------------------------------------------- - - [Fact] - public void AnUnknownKey_SaysTheSchemaDoesNotKnowIt() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml("apiVersion: agentcore/v1\nsampleRatio: 0.5\n")); - - Assert.DoesNotContain("false schema", failure.Message, StringComparison.OrdinalIgnoreCase); - Assert.Contains(failure.Errors, error => error.Message.Contains("sampleRatio", StringComparison.Ordinal)); - } - - [Fact] - public void AWriterWithNoPath_DoesNotAdviseAnotherWriter() - { - // The slot declares `writer: tool` and leaves out `from`. The schema reaches that by asking - // each `if` in turn, and the misses used to be reported: the author was told the writer - // should have been `counter`, and then `const`, which is the opposite of the fix. - const string document = """ + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.Syntax, failure.Check); + } + + // --------------------------------------------------------------------------------------------- + // What the author of the document reads. + // + // The library writes for whoever wrote the schema. "All values fail against the false schema" is + // exact and says nothing to somebody looking at a YAML file, and the branch machinery of `if` and + // `oneOf` used to report its own misses as if they were the document's. These pin the sentences + // check 1 hands back instead. + // --------------------------------------------------------------------------------------------- + + [Fact] + public void AnUnknownKey_SaysTheSchemaDoesNotKnowIt() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml("apiVersion: agentcore/v1\nsampleRatio: 0.5\n")); + + Assert.DoesNotContain("false schema", failure.Message, StringComparison.OrdinalIgnoreCase); + Assert.Contains(failure.Errors, error => error.Message.Contains("sampleRatio", StringComparison.Ordinal)); + } + + [Fact] + public void AWriterWithNoPath_DoesNotAdviseAnotherWriter() + { + // The slot declares `writer: tool` and leaves out `from`. The schema reaches that by asking + // each `if` in turn, and the misses used to be reported: the author was told the writer + // should have been `counter`, and then `const`, which is the opposite of the fix. + const string document = """ apiVersion: agentcore/v1 state: orderStatus: { type: string, writer: tool } @@ -474,19 +476,19 @@ public void AWriterWithNoPath_DoesNotAdviseAnotherWriter() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/state/orderStatus", error.Pointer); - Assert.Contains("from", error.Message, StringComparison.Ordinal); - Assert.DoesNotContain("counter", failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain("const", failure.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/state/orderStatus", error.Pointer); + Assert.Contains("from", error.Message, StringComparison.Ordinal); + Assert.DoesNotContain("counter", failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain("const", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AnUnknownEnumValue_ListsTheValuesTheKeyAccepts() - { - const string document = """ + [Fact] + public void AnUnknownEnumValue_ListsTheValuesTheKeyAccepts() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: lookup_order, kind: ftp } @@ -498,19 +500,19 @@ public void AnUnknownEnumValue_ListsTheValuesTheKeyAccepts() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/tools/0/kind", error.Pointer); - Assert.Contains("builtin, http, binding, agent", error.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/tools/0/kind", error.Pointer); + Assert.Contains("builtin, http, binding, agent", error.Message, StringComparison.Ordinal); + } - [Fact] - public void APolicyAndAGraphTogether_SayWhatTheDocumentDid() - { - // The rule has no keyword of its own — it is a `not` over a dependent schema — so the schema - // writes it out in prose and check 1 reads that back. - const string document = """ + [Fact] + public void APolicyAndAGraphTogether_SayWhatTheDocumentDid() + { + // The rule has no keyword of its own — it is a `not` over a dependent schema — so the schema + // writes it out in prose and check 1 reads that back. + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -523,16 +525,16 @@ public void APolicyAndAGraphTogether_SayWhatTheDocumentDid() agents: [ only ] """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - var error = Assert.Single(failure.Errors); - Assert.Contains("one of", error.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Contains("one of", error.Message, StringComparison.Ordinal); + } - [Fact] - public void AGraphThatIsBothShapes_NamesTheShapesItCouldHaveBeen() - { - const string document = """ + [Fact] + public void AGraphThatIsBothShapes_NamesTheShapesItCouldHaveBeen() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -546,19 +548,19 @@ public void AGraphThatIsBothShapes_NamesTheShapesItCouldHaveBeen() edges: [] """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains( - failure.Errors, - error => error.Pointer == "/entries/main/graph" - && error.Message.Contains("a pattern graph", StringComparison.Ordinal) - && error.Message.Contains("nodes and edges", StringComparison.Ordinal)); - } + Assert.Contains( + failure.Errors, + error => error.Pointer == "/entries/main/graph" + && error.Message.Contains("a pattern graph", StringComparison.Ordinal) + && error.Message.Contains("nodes and edges", StringComparison.Ordinal)); + } - [Fact] - public void AnIdentifierThatIsNotOne_ShowsTheFormTheKeyTakes() - { - const string document = """ + [Fact] + public void AnIdentifierThatIsNotOne_ShowsTheFormTheKeyTakes() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: "9lives", kind: builtin, uses: knowledge.search } @@ -570,23 +572,25 @@ public void AnIdentifierThatIsNotOne_ShowsTheFormTheKeyTakes() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - var error = Assert.Single(failure.Errors); - Assert.Equal("/tools/0/id", error.Pointer); - Assert.Contains("^[A-Za-z_][A-Za-z0-9_-]*$", error.Message, StringComparison.Ordinal); - } - - [Fact] - public void TheEmbeddedSchema_IsPresent() - => Assert.Contains("agentcore/v1", ConfigurationSchemaValidator.SchemaJson, StringComparison.Ordinal); - - [Fact] - public void ABuiltinToolWithParameters_FailsWithThePointerOfTheTool() - { - // The C# still reads fixed argument names for a builtin (BuiltinToolSource). A document - // that overrides the schema makes the model fill boxes the C# never reads. - const string document = """ + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/tools/0/id", error.Pointer); + Assert.Contains("^[A-Za-z_][A-Za-z0-9_-]*$", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void TheEmbeddedSchema_IsPresent() + { + Assert.Contains("agentcore/v1", ConfigurationSchemaValidator.SchemaJson, StringComparison.Ordinal); + } + + [Fact] + public void ABuiltinToolWithParameters_FailsWithThePointerOfTheTool() + { + // The C# still reads fixed argument names for a builtin (BuiltinToolSource). A document + // that overrides the schema makes the model fill boxes the C# never reads. + const string document = """ apiVersion: agentcore/v1 tools: - { id: search_chunks, kind: builtin, uses: knowledge.search, parameters: { type: object } } @@ -595,16 +599,16 @@ public void ABuiltinToolWithParameters_FailsWithThePointerOfTheTool() agent: search_chunks """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/tools/0/parameters"); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/tools/0/parameters"); + } - [Fact] - public void AToolWithMaxRoundsBelowOne_FailsWithThePointerOfTheTool() - { - const string document = """ + [Fact] + public void AToolWithMaxRoundsBelowOne_FailsWithThePointerOfTheTool() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: search, kind: builtin, uses: web.search, maxRounds: 0 } @@ -616,23 +620,23 @@ public void AToolWithMaxRoundsBelowOne_FailsWithThePointerOfTheTool() agent: only """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.Contains("maxRounds", StringComparison.Ordinal)); - } - - /// - /// Only the kind: builtin path reads model: and maxRounds:. On any other - /// kind they would be accepted and then never looked at, which is the silent failure decisions 4 - /// and 8 of the tool registry design reject. - /// - [Theory] - [InlineData("model: { ref: cheap }", "model")] - [InlineData("maxRounds: 4", "maxRounds")] - public void ABuiltinDialOnAKindThatNeverReadsIt_FailsWithThePointerOfTheKey(string key, string name) - { - var document = $$""" + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.Contains("maxRounds", StringComparison.Ordinal)); + } + + /// + /// Only the kind: builtin path reads model: and maxRounds:. On any other + /// kind they would be accepted and then never looked at, which is the silent failure decisions 4 + /// and 8 of the tool registry design reject. + /// + [Theory] + [InlineData("model: { ref: cheap }", "model")] + [InlineData("maxRounds: 4", "maxRounds")] + public void ABuiltinDialOnAKindThatNeverReadsIt_FailsWithThePointerOfTheKey(string key, string name) + { + string document = $$""" apiVersion: agentcore/v1 tools: - { id: lookup, kind: http, request: { method: GET, url: "https://example.test" }, {{key}} } @@ -641,68 +645,68 @@ public void ABuiltinDialOnAKindThatNeverReadsIt_FailsWithThePointerOfTheKey(stri agent: lookup """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.Contains(name, StringComparison.Ordinal)); - } - - /// - /// A cached call runs nothing. A built-in acts on the conversation and a kind: agent tool - /// runs a model, so neither may declare cacheSeconds:; a GET or a reading host delegate may. - /// - [Theory] - [InlineData("builtin", "uses: web.search")] - [InlineData("agent", "agent: reviewer")] - public void CacheSecondsOnAKindWhoseAnswerIsNotAFunctionOfItsArguments_FailsWithThePointerOfTheKey(string kind, string discriminatorField) - { - var document = "apiVersion: agentcore/v1\n" - + "agents:\n" - + " items:\n" - + " - { id: reviewer, instructions: \"ok\" }\n" - + "entries:\n" - + " main:\n" - + " agent: reviewer\n" - + "tools:\n" - + " - id: lookup\n" - + " kind: " + kind + "\n" - + " " + discriminatorField + "\n" - + " cacheSeconds: 60\n"; - - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.Contains("cacheSeconds", StringComparison.Ordinal)); - } - - [Theory] - [InlineData("http", "request: { method: GET, url: \"https://example.test\" }")] - [InlineData("binding", "binds: host.lookup")] - public void CacheSecondsOnAToolThatReads_PassesCheckOne(string kind, string discriminatorField) - { - var document = "apiVersion: agentcore/v1\n" - + "agents:\n" - + " items:\n" - + " - { id: reviewer, instructions: \"ok\" }\n" - + "entries:\n" - + " main:\n" - + " agent: reviewer\n" - + "tools:\n" - + " - id: lookup\n" - + " kind: " + kind + "\n" - + " " + discriminatorField + "\n" - + " cacheSeconds: 60\n"; - - var parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); - - Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); - Assert.Equal(60, ConfigurationLoader.LoadYaml(document).Tools[0].CacheSeconds); - } - - [Fact] - public void ABuiltinToolWithNoParameters_PassesCheckOne() - { - const string document = """ + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.Contains(name, StringComparison.Ordinal)); + } + + /// + /// A cached call runs nothing. A built-in acts on the conversation and a kind: agent tool + /// runs a model, so neither may declare cacheSeconds:; a GET or a reading host delegate may. + /// + [Theory] + [InlineData("builtin", "uses: web.search")] + [InlineData("agent", "agent: reviewer")] + public void CacheSecondsOnAKindWhoseAnswerIsNotAFunctionOfItsArguments_FailsWithThePointerOfTheKey(string kind, string discriminatorField) + { + string document = "apiVersion: agentcore/v1\n" + + "agents:\n" + + " items:\n" + + " - { id: reviewer, instructions: \"ok\" }\n" + + "entries:\n" + + " main:\n" + + " agent: reviewer\n" + + "tools:\n" + + " - id: lookup\n" + + " kind: " + kind + "\n" + + " " + discriminatorField + "\n" + + " cacheSeconds: 60\n"; + + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.Contains("cacheSeconds", StringComparison.Ordinal)); + } + + [Theory] + [InlineData("http", "request: { method: GET, url: \"https://example.test\" }")] + [InlineData("binding", "binds: host.lookup")] + public void CacheSecondsOnAToolThatReads_PassesCheckOne(string kind, string discriminatorField) + { + string document = "apiVersion: agentcore/v1\n" + + "agents:\n" + + " items:\n" + + " - { id: reviewer, instructions: \"ok\" }\n" + + "entries:\n" + + " main:\n" + + " agent: reviewer\n" + + "tools:\n" + + " - id: lookup\n" + + " kind: " + kind + "\n" + + " " + discriminatorField + "\n" + + " cacheSeconds: 60\n"; + + JsonNode parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); + + Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); + Assert.Equal(60, ConfigurationLoader.LoadYaml(document).Tools[0].CacheSeconds); + } + + [Fact] + public void ABuiltinToolWithNoParameters_PassesCheckOne() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: search_chunks, kind: builtin, uses: knowledge.search } @@ -714,39 +718,39 @@ public void ABuiltinToolWithNoParameters_PassesCheckOne() agent: only """; - var parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); - - Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); - } - - [Theory] - [InlineData("http", "request: { method: GET, url: \"https://example.test\" }")] - [InlineData("binding", "binds: host.lookup")] - [InlineData("agent", "agent: reviewer")] - public void ANonBuiltinToolWithParameters_PassesCheckOne(string kind, string discriminatorField) - { - var document = "apiVersion: agentcore/v1\n" - + "agents:\n" - + " items:\n" - + " - { id: reviewer, instructions: \"ok\" }\n" - + "entries:\n" - + " main:\n" - + " agent: reviewer\n" - + "tools:\n" - + " - id: delegated\n" - + " kind: " + kind + "\n" - + " " + discriminatorField + "\n" - + " parameters: { type: object }\n"; - - var parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); - - Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); - } - - [Fact] - public void AFullAgenticAgent_PassesCheckOne() - { - const string document = """ + JsonNode parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); + + Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); + } + + [Theory] + [InlineData("http", "request: { method: GET, url: \"https://example.test\" }")] + [InlineData("binding", "binds: host.lookup")] + [InlineData("agent", "agent: reviewer")] + public void ANonBuiltinToolWithParameters_PassesCheckOne(string kind, string discriminatorField) + { + string document = "apiVersion: agentcore/v1\n" + + "agents:\n" + + " items:\n" + + " - { id: reviewer, instructions: \"ok\" }\n" + + "entries:\n" + + " main:\n" + + " agent: reviewer\n" + + "tools:\n" + + " - id: delegated\n" + + " kind: " + kind + "\n" + + " " + discriminatorField + "\n" + + " parameters: { type: object }\n"; + + JsonNode parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); + + Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); + } + + [Fact] + public void AFullAgenticAgent_PassesCheckOne() + { + const string document = """ apiVersion: agentcore/v1 agents: defaults: @@ -777,16 +781,16 @@ public void AFullAgenticAgent_PassesCheckOne() agent: coder """; - var parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); + JsonNode parsed = ConfigurationLoader.ReadDocument(document, ConfigurationFormat.Yaml); - Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); - Assert.NotNull(ConfigurationLoader.LoadYaml(document).Agents!.Items[1].Shell); - } + Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); + Assert.NotNull(ConfigurationLoader.LoadYaml(document).Agents!.Items[1].Shell); + } - [Fact] - public void AnUnknownShellKind_FailsWithThePointerOfThatKind() - { - const string document = """ + [Fact] + public void AnUnknownShellKind_FailsWithThePointerOfThatKind() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -797,16 +801,16 @@ public void AnUnknownShellKind_FailsWithThePointerOfThatKind() agent: coder """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/shell/kind"); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/shell/kind"); + } - [Fact] - public void AMemoryBlockWithoutAStore_FailsWithThePointerOfTheBlock() - { - const string document = """ + [Fact] + public void AMemoryBlockWithoutAStore_FailsWithThePointerOfTheBlock() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -817,15 +821,15 @@ public void AMemoryBlockWithoutAStore_FailsWithThePointerOfTheBlock() agent: coder """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/memory"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/memory"); + } - [Fact] - public void ATwoConditionUntilEntry_FailsWithThePointerOfThatEntry() - { - const string document = """ + [Fact] + public void ATwoConditionUntilEntry_FailsWithThePointerOfThatEntry() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -839,15 +843,15 @@ public void ATwoConditionUntilEntry_FailsWithThePointerOfThatEntry() agent: coder """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/loop/until/0"); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/loop/until/0"); + } - [Fact] - public void ADuplicateBackgroundChild_FailsWithThePointerOfTheList() - { - const string document = """ + [Fact] + public void ADuplicateBackgroundChild_FailsWithThePointerOfTheList() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -858,8 +862,9 @@ public void ADuplicateBackgroundChild_FailsWithThePointerOfTheList() agent: coder """; - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); - Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/background"); + Assert.Contains(failure.Errors, error => error.Pointer == "/agents/items/0/background"); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConversationSchemaTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConversationSchemaTests.cs index 2deaa08b..a7fb3509 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConversationSchemaTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConversationSchemaTests.cs @@ -2,23 +2,23 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// providers.conversation names the vendor that carries the conversation, and the limits of its socket. -/// -/// -/// The media plane is not providers.speech, which names recognition and synthesis one role -/// at a time, and it is not providers.telephony, which is conversation control. Section 8.2 asks a -/// document that writes a providers: section to name both the pipe and the ears, so the two -/// blocks are required together — and the speech block requires both of its own roles in turn. -/// -public sealed class ConversationSchemaTests +namespace AgentCore.Application.Tests.Configuration { - [Fact] - public void TheConversationBlockBindsItsKindAndItsThreeKnobs() + /// + /// providers.conversation names the vendor that carries the conversation, and the limits of its socket. + /// + /// + /// The media plane is not providers.speech, which names recognition and synthesis one role + /// at a time, and it is not providers.telephony, which is conversation control. Section 8.2 asks a + /// document that writes a providers: section to name both the pipe and the ears, so the two + /// blocks are required together — and the speech block requires both of its own roles in turn. + /// + public sealed class ConversationSchemaTests { - var configuration = Load(""" + [Fact] + public void TheConversationBlockBindsItsKindAndItsThreeKnobs() + { + AgentCoreConfiguration configuration = Load(""" providers: conversation: kind: telnyx-relay @@ -30,17 +30,17 @@ public void TheConversationBlockBindsItsKindAndItsThreeKnobs() tts: { kind: telnyx-relay } """); - var conversation = configuration.Providers!.Conversation!; - Assert.Equal("telnyx-relay", conversation.Kind); - Assert.Equal(30, conversation.IdleTimeoutSeconds); - Assert.Equal(5, conversation.CloseTimeoutSeconds); - Assert.Equal(65536, conversation.MaxFrameBytes); - } - - [Fact] - public void TheThreeKnobsAreOptional() - { - var configuration = Load(""" + ConversationProviderConfiguration conversation = configuration.Providers!.Conversation!; + Assert.Equal("telnyx-relay", conversation.Kind); + Assert.Equal(30, conversation.IdleTimeoutSeconds); + Assert.Equal(5, conversation.CloseTimeoutSeconds); + Assert.Equal(65536, conversation.MaxFrameBytes); + } + + [Fact] + public void TheThreeKnobsAreOptional() + { + AgentCoreConfiguration configuration = Load(""" providers: conversation: { kind: telnyx-relay } speech: @@ -48,45 +48,45 @@ public void TheThreeKnobsAreOptional() tts: { kind: telnyx-relay } """); - var conversation = configuration.Providers!.Conversation!; - Assert.Null(conversation.IdleTimeoutSeconds); - Assert.Null(conversation.CloseTimeoutSeconds); - Assert.Null(conversation.MaxFrameBytes); - } - - [Fact] - public void AMissingConversationBlockFailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + ConversationProviderConfiguration conversation = configuration.Providers!.Conversation!; + Assert.Null(conversation.IdleTimeoutSeconds); + Assert.Null(conversation.CloseTimeoutSeconds); + Assert.Null(conversation.MaxFrameBytes); + } + + [Fact] + public void AMissingConversationBlockFailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" providers: speech: stt: { kind: telnyx-relay } tts: { kind: telnyx-relay } """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains("conversation", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains("conversation", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AMissingSpeechBlockFailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AMissingSpeechBlockFailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" providers: conversation: { kind: telnyx-relay } """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains("speech", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains("speech", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AnUnknownFieldUnderConversationFailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnUnknownFieldUnderConversationFailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" providers: conversation: { kind: telnyx-relay, idleTimeoutSecnods: 30 } speech: @@ -94,15 +94,15 @@ public void AnUnknownFieldUnderConversationFailsTheLoad() tts: { kind: telnyx-relay } """)); - // additionalProperties names the offending property in the pointer rather than the text, and - // ConfigurationLoadException.Message carries pointer and message together for every error. - Assert.Contains("idleTimeoutSecnods", failure.Message, StringComparison.Ordinal); - } + // additionalProperties names the offending property in the pointer rather than the text, and + // ConfigurationLoadException.Message carries pointer and message together for every error. + Assert.Contains("idleTimeoutSecnods", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void InfiniteIsSpelledMinusOne() - { - var configuration = Load(""" + [Fact] + public void InfiniteIsSpelledMinusOne() + { + AgentCoreConfiguration configuration = Load(""" providers: conversation: { kind: telnyx-relay, idleTimeoutSeconds: -1 } speech: @@ -110,13 +110,13 @@ public void InfiniteIsSpelledMinusOne() tts: { kind: telnyx-relay } """); - Assert.Equal(-1, configuration.Providers!.Conversation!.IdleTimeoutSeconds); - } + Assert.Equal(-1, configuration.Providers!.Conversation!.IdleTimeoutSeconds); + } - [Fact] - public void TheSpeechBlockBindsBothRoles() - { - var configuration = Load(""" + [Fact] + public void TheSpeechBlockBindsBothRoles() + { + AgentCoreConfiguration configuration = Load(""" providers: conversation: { kind: sip } speech: @@ -124,46 +124,46 @@ public void TheSpeechBlockBindsBothRoles() tts: { kind: elevenlabs } """); - var speech = configuration.Providers!.Speech!; - Assert.Equal("deepgram", speech.Stt.Kind); - Assert.Equal("elevenlabs", speech.Tts.Kind); - } + SpeechProviderConfiguration speech = configuration.Providers!.Speech!; + Assert.Equal("deepgram", speech.Stt.Kind); + Assert.Equal("elevenlabs", speech.Tts.Kind); + } - [Fact] - public void ASpeechBlockWithoutRecognitionFailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void ASpeechBlockWithoutRecognitionFailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" providers: conversation: { kind: telnyx-relay } speech: tts: { kind: telnyx-relay } """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains("stt", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains("stt", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void ASpeechBlockWithoutSynthesisFailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void ASpeechBlockWithoutSynthesisFailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" providers: conversation: { kind: telnyx-relay } speech: stt: { kind: telnyx-relay } """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains("tts", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains("tts", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AnUnknownFieldUnderSpeechFailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnUnknownFieldUnderSpeechFailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" providers: conversation: { kind: telnyx-relay } speech: @@ -172,22 +172,25 @@ public void AnUnknownFieldUnderSpeechFailsTheLoad() voice: alloy """)); - // additionalProperties names the offending property in the pointer rather than the text, and - // ConfigurationLoadException.Message carries pointer and message together for every error. - // The field is one no speech document writes, so the assertion cannot pass on another failure. - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains("voice", failure.Message, StringComparison.Ordinal); + // additionalProperties names the offending property in the pointer rather than the text, and + // ConfigurationLoadException.Message carries pointer and message together for every error. + // The field is one no speech document writes, so the assertion cannot pass on another failure. + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains("voice", failure.Message, StringComparison.Ordinal); + } + + /// Loads one providers: section under the smallest complete document header. + /// The providers: section, written at the document's own margin. + /// The loaded document. + /// + /// Check 1 of section 8.5 is the only check ConfigurationLoader.LoadYaml runs, and the + /// document root requires apiVersion, agents, and entries. Every other test + /// in this folder loads the same way. + /// + private static AgentCoreConfiguration Load(string providers) + { + return ConfigurationLoader.LoadYaml( + "apiVersion: agentcore/v1\nagents:\n items:\n - { id: only, instructions: \"ok\" }\nentries:\n main:\n agent: only\n" + providers); + } } - - /// Loads one providers: section under the smallest complete document header. - /// The providers: section, written at the document's own margin. - /// The loaded document. - /// - /// Check 1 of section 8.5 is the only check ConfigurationLoader.LoadYaml runs, and the - /// document root requires apiVersion, agents, and entries. Every other test - /// in this folder loads the same way. - /// - private static AgentCoreConfiguration Load(string providers) - => ConfigurationLoader.LoadYaml( - "apiVersion: agentcore/v1\nagents:\n items:\n - { id: only, instructions: \"ok\" }\nentries:\n main:\n agent: only\n" + providers); } diff --git a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs index b4ecb86c..6764d66c 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs @@ -1,45 +1,45 @@ -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The worked example of section 8.1, in both forms. -/// -/// -/// The YAML is the document as the design writes it, plus the three optional keys section 8.1 does -/// not print: fallbackReply, refusalReply, and evaluation. All three hold their -/// default, and the shipped -/// config/example.yaml holds the same document. The JSON is the same document again, and it -/// was produced by a different YAML reader so that rule 17 of section 11 tests something real. -/// -internal static class ExampleDocument +namespace AgentCore.Application.Tests.Configuration { /// - /// The last line of the providers: block, for a test that splices its own provider block - /// in after it. + /// The worked example of section 8.1, in both forms. /// /// - /// - /// Three test files used to keep a private copy of the one-line providers.knowledge entry and - /// anchor on that. When the block grew to ten lines, every copy stopped matching, Replace - /// silently did nothing, and eighteen tests failed on a provider that had never been written - /// into the document at all. One anchor, owned by the document, cannot drift out of step with it. - /// - /// - /// It must stay the LAST line of providers:. A splice after any earlier line lands inside the - /// block that follows, which is a different failure again -- valid YAML, wrong nesting, and a - /// provider silently belonging to the wrong parent. - /// + /// The YAML is the document as the design writes it, plus the three optional keys section 8.1 does + /// not print: fallbackReply, refusalReply, and evaluation. All three hold their + /// default, and the shipped + /// config/example.yaml holds the same document. The JSON is the same document again, and it + /// was produced by a different YAML reader so that rule 17 of section 11 tests something real. /// - public const string LastProviderLine = " citation: source-locator"; + internal static class ExampleDocument + { + /// + /// The last line of the providers: block, for a test that splices its own provider block + /// in after it. + /// + /// + /// + /// Three test files used to keep a private copy of the one-line providers.knowledge entry and + /// anchor on that. When the block grew to ten lines, every copy stopped matching, Replace + /// silently did nothing, and eighteen tests failed on a provider that had never been written + /// into the document at all. One anchor, owned by the document, cannot drift out of step with it. + /// + /// + /// It must stay the LAST line of providers:. A splice after any earlier line lands inside the + /// block that follows, which is a different failure again -- valid YAML, wrong nesting, and a + /// provider silently belonging to the wrong parent. + /// + /// + public const string LastProviderLine = " citation: source-locator"; - /// - /// The one-line providers.blobs entry, for a test that takes it out or swaps its own in. - /// - public const string BlobsLine = - " blobs: { kind: s3, endpoint: https://s3.us-east-005.backblazeb2.com, bucket: agentcore-files, region: us-east-005 }"; + /// + /// The one-line providers.blobs entry, for a test that takes it out or swaps its own in. + /// + public const string BlobsLine = + " blobs: { kind: s3, endpoint: https://s3.us-east-005.backblazeb2.com, bucket: agentcore-files, region: us-east-005 }"; - /// The section 8.1 document as YAML. - public const string Yaml = - """ + /// The section 8.1 document as YAML. + public const string Yaml = + """ apiVersion: agentcore/v1 fallbackReply: "I am sorry. I could not finish that. Please say it again." refusalReply: "I am sorry. I cannot help with that request." @@ -208,9 +208,10 @@ internal static class ExampleDocument judge: { ref: judge, temperature: 0 } """; - /// The same document as JSON. - public const string Json = - """ + /// The same document as JSON. + public const string Json = + /*lang=json,strict*/ + """ { "apiVersion": "agentcore/v1", "fallbackReply": "I am sorry. I could not finish that. Please say it again.", @@ -670,4 +671,5 @@ internal static class ExampleDocument } } """; + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ExampleDocumentTests.cs b/tests/AgentCore.Application.Tests/Configuration/ExampleDocumentTests.cs index dbd85754..f4b0ddb6 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ExampleDocumentTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ExampleDocumentTests.cs @@ -1,51 +1,52 @@ using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The worked example's own invariants, so a test file does not have to remember them. -/// -public sealed class ExampleDocumentTests +namespace AgentCore.Application.Tests.Configuration { - [Fact] - public void LastProviderLine_IsReallyTheLastLineOfProviders() + /// + /// The worked example's own invariants, so a test file does not have to remember them. + /// + public sealed class ExampleDocumentTests { - // Three seam tests splice their own provider block in after this anchor. If it stops being - // the last line, the splice lands INSIDE whatever block follows: still valid YAML, wrong - // nesting, and a provider quietly belonging to the wrong parent. That is harder to notice - // than the failure this anchor was introduced to fix, so it is checked rather than trusted. - var lines = ExampleDocument.Yaml.Split('\n').Select(line => line.TrimEnd('\r')).ToList(); - - var start = lines.FindIndex(line => line.StartsWith("providers:", StringComparison.Ordinal)); - Assert.True(start >= 0, "The example document has no providers: block."); - - var last = start; - for (var i = start + 1; i < lines.Count; i++) + [Fact] + public void LastProviderLine_IsReallyTheLastLineOfProviders() { - var line = lines[i]; - if (line.Length == 0 || line.TrimStart().StartsWith('#')) - { - continue; - } + // Three seam tests splice their own provider block in after this anchor. If it stops being + // the last line, the splice lands INSIDE whatever block follows: still valid YAML, wrong + // nesting, and a provider quietly belonging to the wrong parent. That is harder to notice + // than the failure this anchor was introduced to fix, so it is checked rather than trusted. + List lines = [.. ExampleDocument.Yaml.Split('\n').Select(line => line.TrimEnd('\r'))]; + + int start = lines.FindIndex(line => line.StartsWith("providers:", StringComparison.Ordinal)); + Assert.True(start >= 0, "The example document has no providers: block."); - if (!line.StartsWith(' ')) + int last = start; + for (int i = start + 1; i < lines.Count; i++) { - break; + string line = lines[i]; + if (line.Length == 0 || line.TrimStart().StartsWith('#')) + { + continue; + } + + if (!line.StartsWith(' ')) + { + break; + } + + last = i; } - last = i; + Assert.Equal(ExampleDocument.LastProviderLine, lines[last]); } - Assert.Equal(ExampleDocument.LastProviderLine, lines[last]); - } - - [Fact] - public void LastProviderLine_AppearsExactlyOnce() - { - // Replace() rewrites every occurrence, so a second copy of this line would splice the same - // provider block in twice and the document would fail to load on a duplicate key. - var occurrences = ExampleDocument.Yaml.Split(ExampleDocument.LastProviderLine).Length - 1; + [Fact] + public void LastProviderLine_AppearsExactlyOnce() + { + // Replace() rewrites every occurrence, so a second copy of this line would splice the same + // provider block in twice and the document would fail to load on a duplicate key. + int occurrences = ExampleDocument.Yaml.Split(ExampleDocument.LastProviderLine).Length - 1; - Assert.Equal(1, occurrences); + Assert.Equal(1, occurrences); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs b/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs index 01917b2e..c00b19e1 100644 --- a/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs @@ -1,15 +1,15 @@ +using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Validation; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The document schema knows the resolve block on a filterable facet. -/// -public sealed class FacetResolveSchemaTests +namespace AgentCore.Application.Tests.Configuration { - private const string Facets = """ + /// + /// The document schema knows the resolve block on a filterable facet. + /// + public sealed class FacetResolveSchemaTests + { + private const string Facets = """ apiVersion: agentcore/v1 agents: items: @@ -35,33 +35,34 @@ public sealed class FacetResolveSchemaTests resolve: """; - [Fact] - public void AFacetWithResolve_PassesTheSchema() - { - var document = ConfigurationLoader.ReadDocument( - Facets + """ + [Fact] + public void AFacetWithResolve_PassesTheSchema() + { + JsonNode document = ConfigurationLoader.ReadDocument( + Facets + """ via: { key: lookup, value: model-numbers } query: " model number" read: the Tag column of the row for the person's year """, - ConfigurationFormat.Yaml); + ConfigurationFormat.Yaml); - Assert.Empty(ConfigurationSchemaValidator.Evaluate(document)); - } + Assert.Empty(ConfigurationSchemaValidator.Evaluate(document)); + } - [Fact] - public void AResolveMissingItsRead_FailsTheSchema() - { - var document = ConfigurationLoader.ReadDocument( - Facets + """ + [Fact] + public void AResolveMissingItsRead_FailsTheSchema() + { + JsonNode document = ConfigurationLoader.ReadDocument( + Facets + """ via: { key: lookup, value: model-numbers } query: " model number" """, - ConfigurationFormat.Yaml); + ConfigurationFormat.Yaml); - var failure = Assert.Single(ConfigurationSchemaValidator.Evaluate(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + ConfigurationError failure = Assert.Single(ConfigurationSchemaValidator.Evaluate(document)); + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/McpConfigurationTests.cs b/tests/AgentCore.Application.Tests/Configuration/McpConfigurationTests.cs index ba065db9..e7cb173c 100644 --- a/tests/AgentCore.Application.Tests/Configuration/McpConfigurationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/McpConfigurationTests.cs @@ -3,25 +3,25 @@ using AgentCore.Application.Configuration.Schema; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// The mcp: block of decision 13: parse and shape only, no connection. -/// -/// -/// Each test pins one rule check 1 of section 8.5 enforces over an mcp: server: the -/// allow: entry shapes decision 6 permits, and the transport/command/url pairing a server's -/// connection depends on. Served ids depend on id and allow[].as (decision 10), not on -/// the transport. -/// -public sealed class McpConfigurationTests +namespace AgentCore.Application.Tests.Configuration { - private static readonly string[] JiraCommand = ["npx", "-y", "@atlassian/mcp"]; - - [Fact] - public void AStdioServerBindsItsCommandAndTwoAllowEntries() + /// + /// The mcp: block of decision 13: parse and shape only, no connection. + /// + /// + /// Each test pins one rule check 1 of section 8.5 enforces over an mcp: server: the + /// allow: entry shapes decision 6 permits, and the transport/command/url pairing a server's + /// connection depends on. Served ids depend on id and allow[].as (decision 10), not on + /// the transport. + /// + public sealed class McpConfigurationTests { - var configuration = Load(""" + private static readonly string[] JiraCommand = ["npx", "-y", "@atlassian/mcp"]; + + [Fact] + public void AStdioServerBindsItsCommandAndTwoAllowEntries() + { + AgentCoreConfiguration configuration = Load(""" mcp: - id: jira transport: stdio @@ -31,29 +31,29 @@ public void AStdioServerBindsItsCommandAndTwoAllowEntries() - search_issues: { as: find_ticket } """); - var server = Assert.Single(configuration.Mcp); - Assert.Equal("jira", server.Id); - Assert.Equal(McpTransport.Stdio, server.Transport); - Assert.Equal(JiraCommand, server.Command); - - Assert.Collection( - server.Allow, - entry => - { - Assert.Equal("create_issue", entry.Name); - Assert.Null(entry.As); - }, - entry => - { - Assert.Equal("search_issues", entry.Name); - Assert.Equal("find_ticket", entry.As); - }); - } - - [Fact] - public void AWildcardAllowBindsToOneUnaliasedEntry() - { - var configuration = Load(""" + McpServerConfiguration server = Assert.Single(configuration.Mcp); + Assert.Equal("jira", server.Id); + Assert.Equal(McpTransport.Stdio, server.Transport); + Assert.Equal(JiraCommand, server.Command); + + Assert.Collection( + server.Allow, + entry => + { + Assert.Equal("create_issue", entry.Name); + Assert.Null(entry.As); + }, + entry => + { + Assert.Equal("search_issues", entry.Name); + Assert.Equal("find_ticket", entry.As); + }); + } + + [Fact] + public void AWildcardAllowBindsToOneUnaliasedEntry() + { + AgentCoreConfiguration configuration = Load(""" mcp: - id: jira transport: stdio @@ -61,16 +61,16 @@ public void AWildcardAllowBindsToOneUnaliasedEntry() allow: ["*"] """); - var entry = Assert.Single(Assert.Single(configuration.Mcp).Allow); - Assert.Equal("*", entry.Name); - Assert.Null(entry.As); - } + McpAllowEntry entry = Assert.Single(Assert.Single(configuration.Mcp).Allow); + Assert.Equal("*", entry.Name); + Assert.Null(entry.As); + } - [Fact] - public void AnAllowEntryMapWithTwoKeys_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnAllowEntryMapWithTwoKeys_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: stdio @@ -79,15 +79,15 @@ public void AnAllowEntryMapWithTwoKeys_FailsTheLoad() - { a: { as: x }, b: { as: y } } """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - [Fact] - public void AnAllowEntryMapWithAKeyOtherThanAs_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnAllowEntryMapWithAKeyOtherThanAs_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: stdio @@ -96,43 +96,43 @@ public void AnAllowEntryMapWithAKeyOtherThanAs_FailsTheLoad() - search_issues: { rename: find_ticket } """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - [Fact] - public void AStdioServerWithNoCommand_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AStdioServerWithNoCommand_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: stdio """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - [Fact] - public void AnHttpServerWithNoUrl_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnHttpServerWithNoUrl_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: http """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - [Fact] - public void AnUnknownKeyOnAServer_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnUnknownKeyOnAServer_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: stdio @@ -140,15 +140,15 @@ public void AnUnknownKeyOnAServer_FailsTheLoad() nickname: jira-prod """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - [Fact] - public void AStdioServerWithAUrl_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AStdioServerWithAUrl_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: stdio @@ -156,15 +156,15 @@ public void AStdioServerWithAUrl_FailsTheLoad() url: https://example.test """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - [Fact] - public void AnHttpServerWithACommand_FailsTheLoad() - { - var failure = Assert.Throws( - () => Load(""" + [Fact] + public void AnHttpServerWithACommand_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => Load(""" mcp: - id: jira transport: http @@ -172,21 +172,21 @@ public void AnHttpServerWithACommand_FailsTheLoad() command: [npx] """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } - - /// - /// A null allow: entry is check 1's job, and check 1 already refuses it (see - /// and its neighbours). This test bypasses - /// check 1 and binds a hand-built tree directly, the route 's - /// own failure branches exist for: without HandleNull, JsonSerializer never conversations - /// Read for a null token and simply stores a null reference in the list. - /// - [Fact] - public void ANullAllowEntry_FailsThroughTheBinder() - { - var document = JsonNode.Parse(""" + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } + + /// + /// A null allow: entry is check 1's job, and check 1 already refuses it (see + /// and its neighbours). This test bypasses + /// check 1 and binds a hand-built tree directly, the route 's + /// own failure branches exist for: without HandleNull, JsonSerializer never conversations + /// Read for a null token and simply stores a null reference in the list. + /// + [Fact] + public void ANullAllowEntry_FailsThroughTheBinder() + { + JsonNode document = JsonNode.Parse(""" { "apiVersion": "agentcore/v1", "agents": { "items": [{ "id": "only" }] }, @@ -197,17 +197,17 @@ public void ANullAllowEntry_FailsThroughTheBinder() } """)!; - var failure = Assert.Throws(() => ConfigurationBinder.Bind(document)); + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationBinder.Bind(document)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); - Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); - } + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer.StartsWith("/mcp", StringComparison.Ordinal)); + } - /// Decision 10: a served MCP tool id carries the one dot that tools: otherwise forbids. - [Fact] - public void AnAgentReferencingADottedMcpToolId_PassesTheLoad() - { - var configuration = ConfigurationLoader.LoadYaml(""" + /// Decision 10: a served MCP tool id carries the one dot that tools: otherwise forbids. + [Fact] + public void AnAgentReferencingADottedMcpToolId_PassesTheLoad() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -218,16 +218,16 @@ public void AnAgentReferencingADottedMcpToolId_PassesTheLoad() agent: front """); - var agent = Assert.Single(configuration.Agents!.Items); - Assert.Equal("jira.create_issue", Assert.Single(agent.Tools)); - } + AgentConfiguration agent = Assert.Single(configuration.Agents!.Items); + Assert.Equal("jira.create_issue", Assert.Single(agent.Tools)); + } - /// A tool id carries at most one dot; a second dot is not a served MCP id and is refused. - [Fact] - public void AnAgentReferencingATwoDottedToolId_FailsTheLoad() - { - var failure = Assert.Throws( - () => ConfigurationLoader.LoadYaml(""" + /// A tool id carries at most one dot; a second dot is not a served MCP id and is refused. + [Fact] + public void AnAgentReferencingATwoDottedToolId_FailsTheLoad() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -238,13 +238,16 @@ public void AnAgentReferencingATwoDottedToolId_FailsTheLoad() agent: front """)); - Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } + + /// Loads a document section under the smallest complete document header. + /// The section, written at the document's own margin. + /// The loaded document. + private static AgentCoreConfiguration Load(string section) + { + return ConfigurationLoader.LoadYaml( + "apiVersion: agentcore/v1\nagents:\n items:\n - { id: only, instructions: \"ok\" }\nentries:\n main:\n agent: only\n" + section); + } } - - /// Loads a document section under the smallest complete document header. - /// The section, written at the document's own margin. - /// The loaded document. - private static AgentCoreConfiguration Load(string section) - => ConfigurationLoader.LoadYaml( - "apiVersion: agentcore/v1\nagents:\n items:\n - { id: only, instructions: \"ok\" }\nentries:\n main:\n agent: only\n" + section); } diff --git a/tests/AgentCore.Application.Tests/Configuration/McpServerConfigurationTests.cs b/tests/AgentCore.Application.Tests/Configuration/McpServerConfigurationTests.cs index 9978a36a..69204b81 100644 --- a/tests/AgentCore.Application.Tests/Configuration/McpServerConfigurationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/McpServerConfigurationTests.cs @@ -1,35 +1,34 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Ports; using AgentCore.Application.Secrets; using AgentCore.TestSupport; using Xunit; -namespace AgentCore.Application.Tests.Configuration; - -/// -/// What an mcp: entry may hold, and where a credential is allowed to go. -/// -/// -/// An HTTP server behind authentication is reached with headers:, and a stdio server's -/// credential belongs in env:. Neither may go in command:, where every user on the -/// machine can read it out of ps. -/// -public sealed class McpServerConfigurationTests +namespace AgentCore.Application.Tests.Configuration { - private const string TokenName = "gh-token"; - private const string TokenValue = "ghp_0123456789"; + /// + /// What an mcp: entry may hold, and where a credential is allowed to go. + /// + /// + /// An HTTP server behind authentication is reached with headers:, and a stdio server's + /// credential belongs in env:. Neither may go in command:, where every user on the + /// machine can read it out of ps. + /// + public sealed class McpServerConfigurationTests + { + private const string TokenName = "gh-token"; + private const string TokenValue = "ghp_0123456789"; - private static CancellationToken Token => TestContext.Current.CancellationToken; + private static CancellationToken Token => TestContext.Current.CancellationToken; - // --------------------------------------------------------------------------------------------- - // A credential has somewhere to go, on either transport. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AStdioServer_BindsItsEnvironment() - { - var document = ConfigurationLoader.LoadYaml(""" + // --------------------------------------------------------------------------------------------- + // A credential has somewhere to go, on either transport. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AStdioServer_BindsItsEnvironment() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -47,19 +46,19 @@ public void AStdioServer_BindsItsEnvironment() allow: ["*"] """); - var server = Assert.Single(document.Mcp); - Assert.Equal("${secret:gh-token}", server.Env["GITHUB_TOKEN"].Raw); - Assert.True(server.Env["GITHUB_TOKEN"].HasSecretReferences); + McpServerConfiguration server = Assert.Single(document.Mcp); + Assert.Equal("${secret:gh-token}", server.Env["GITHUB_TOKEN"].Raw); + Assert.True(server.Env["GITHUB_TOKEN"].HasSecretReferences); - // A plain value is config, not a credential, and is carried through untouched. - Assert.Equal("production", server.Env["NODE_ENV"].Raw); - Assert.False(server.Env["NODE_ENV"].HasSecretReferences); - } + // A plain value is config, not a credential, and is carried through untouched. + Assert.Equal("production", server.Env["NODE_ENV"].Raw); + Assert.False(server.Env["NODE_ENV"].HasSecretReferences); + } - [Fact] - public void AnHttpServer_BindsItsHeaders() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public void AnHttpServer_BindsItsHeaders() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -76,14 +75,14 @@ public void AnHttpServer_BindsItsHeaders() allow: ["*"] """); - var server = Assert.Single(document.Mcp); - Assert.Equal("Bearer ${secret:jira-token}", server.Headers["Authorization"].Raw); - } + McpServerConfiguration server = Assert.Single(document.Mcp); + Assert.Equal("Bearer ${secret:jira-token}", server.Headers["Authorization"].Raw); + } - [Fact] - public async Task AnMcpCredential_IsResolvedAtStartup_LikeAToolHeader() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public async Task AnMcpCredential_IsResolvedAtStartup_LikeAToolHeader() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -104,19 +103,19 @@ public async Task AnMcpCredential_IsResolvedAtStartup_LikeAToolHeader() allow: ["*"] """); - var secrets = await ResolvedSecrets.ResolveAsync( - document, - new MapSecretResolver().With(TokenName, TokenValue).With("jira-token", "jira-abc"), - Token); + ResolvedSecrets secrets = await ResolvedSecrets.ResolveAsync( + document, + new MapSecretResolver().With(TokenName, TokenValue).With("jira-token", "jira-abc"), + Token); - Assert.Equal(TokenValue, secrets.Format(document.Mcp[0].Env["GITHUB_TOKEN"])); - Assert.Equal("Bearer jira-abc", secrets.Format(document.Mcp[1].Headers["Authorization"])); - } + Assert.Equal(TokenValue, secrets.Format(document.Mcp[0].Env["GITHUB_TOKEN"])); + Assert.Equal("Bearer jira-abc", secrets.Format(document.Mcp[1].Headers["Authorization"])); + } - [Fact] - public async Task AnMcpCredentialThatResolvesToNothing_FailsTheBoot_NamingWhereItWasWritten() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public async Task AnMcpCredentialThatResolvesToNothing_FailsTheBoot_NamingWhereItWasWritten() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -132,20 +131,20 @@ public async Task AnMcpCredentialThatResolvesToNothing_FailsTheBoot_NamingWhereI allow: ["*"] """); - var failure = await Assert.ThrowsAsync( - async () => await ResolvedSecrets.ResolveAsync(document, new MapSecretResolver(), Token)); + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await ResolvedSecrets.ResolveAsync(document, new MapSecretResolver(), Token)); - Assert.Contains(TokenName, failure.Message, StringComparison.Ordinal); - Assert.Contains("/mcp/0/env/GITHUB_TOKEN", failure.Message, StringComparison.Ordinal); - } + Assert.Contains(TokenName, failure.Message, StringComparison.Ordinal); + Assert.Contains("/mcp/0/env/GITHUB_TOKEN", failure.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // A credential in command: or url: would leak while not even working, so the document is refused. - // --------------------------------------------------------------------------------------------- - [Fact] - public void ASecretWrittenIntoCommand_FailsTheDocument_AndPointsAtEnv() - { - var document = ConfigurationLoader.LoadYaml(""" + // --------------------------------------------------------------------------------------------- + // A credential in command: or url: would leak while not even working, so the document is refused. + // --------------------------------------------------------------------------------------------- + [Fact] + public void ASecretWrittenIntoCommand_FailsTheDocument_AndPointsAtEnv() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -160,17 +159,17 @@ public void ASecretWrittenIntoCommand_FailsTheDocument_AndPointsAtEnv() allow: ["*"] """); - var error = Assert.Single(ConfigurationValidator.EvaluateStructure(document).Errors); + ConfigurationError error = Assert.Single(ConfigurationValidator.EvaluateStructure(document).Errors); - Assert.Equal("/mcp/0/command/2", error.Pointer); - Assert.Contains("ps", error.Message, StringComparison.Ordinal); - Assert.Contains("env:", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/mcp/0/command/2", error.Pointer); + Assert.Contains("ps", error.Message, StringComparison.Ordinal); + Assert.Contains("env:", error.Message, StringComparison.Ordinal); + } - [Fact] - public void ASecretWrittenIntoUrl_FailsTheDocument_AndPointsAtHeaders() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public void ASecretWrittenIntoUrl_FailsTheDocument_AndPointsAtHeaders() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -185,16 +184,16 @@ public void ASecretWrittenIntoUrl_FailsTheDocument_AndPointsAtHeaders() allow: ["*"] """); - var error = Assert.Single(ConfigurationValidator.EvaluateStructure(document).Errors); + ConfigurationError error = Assert.Single(ConfigurationValidator.EvaluateStructure(document).Errors); - Assert.Equal("/mcp/0/url", error.Pointer); - Assert.Contains("headers:", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/mcp/0/url", error.Pointer); + Assert.Contains("headers:", error.Message, StringComparison.Ordinal); + } - [Fact] - public void AServerThatWritesNoSecretAnywhereOdd_Passes() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public void AServerThatWritesNoSecretAnywhereOdd_Passes() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -210,20 +209,20 @@ public void AServerThatWritesNoSecretAnywhereOdd_Passes() allow: ["*"] """); - Assert.Empty(ConfigurationValidator.EvaluateStructure(document).Errors); - } + Assert.Empty(ConfigurationValidator.EvaluateStructure(document).Errors); + } - // --------------------------------------------------------------------------------------------- - // The transport branches: a key that belongs to the other transport is refused by check 1, so a - // deployer never gets a header silently ignored on a child process. - // --------------------------------------------------------------------------------------------- - [Theory] - [InlineData("stdio", "command: [\"a\"]", "headers: { Authorization: x }")] - [InlineData("http", "url: https://x.example.com/", "env: { A: b }")] - [InlineData("http", "url: https://x.example.com/", "inheritEnv: true")] - public void AKeyOfTheOtherTransport_IsRefused(string transport, string address, string wrongKey) - { - var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml($""" + // --------------------------------------------------------------------------------------------- + // The transport branches: a key that belongs to the other transport is refused by check 1, so a + // deployer never gets a header silently ignored on a child process. + // --------------------------------------------------------------------------------------------- + [Theory] + [InlineData("stdio", "command: [\"a\"]", "headers: { Authorization: x }")] + [InlineData("http", "url: https://x.example.com/", "env: { A: b }")] + [InlineData("http", "url: https://x.example.com/", "inheritEnv: true")] + public void AKeyOfTheOtherTransport_IsRefused(string transport, string address, string wrongKey) + { + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationLoader.LoadYaml($""" apiVersion: agentcore/v1 agents: items: @@ -240,16 +239,16 @@ public void AKeyOfTheOtherTransport_IsRefused(string transport, string address, allow: ["*"] """)); - Assert.Contains("/mcp/0", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("/mcp/0", failure.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // The timing knobs bind. What they do to a connection is McpServerSessionTests. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TimeoutsAndRetry_Bind() - { - var document = ConfigurationLoader.LoadYaml(""" + // --------------------------------------------------------------------------------------------- + // The timing knobs bind. What they do to a connection is McpServerSessionTests. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TimeoutsAndRetry_Bind() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -268,17 +267,17 @@ public void TimeoutsAndRetry_Bind() allow: ["*"] """); - var server = Assert.Single(document.Mcp); - Assert.Equal(3, server.ConnectTimeoutSeconds); - Assert.Equal(12, server.CallTimeoutSeconds); - Assert.Equal(5, server.Retry!.Attempts); - Assert.Equal(250, server.Retry.BackoffMs); - } + McpServerConfiguration server = Assert.Single(document.Mcp); + Assert.Equal(3, server.ConnectTimeoutSeconds); + Assert.Equal(12, server.CallTimeoutSeconds); + Assert.Equal(5, server.Retry!.Attempts); + Assert.Equal(250, server.Retry.BackoffMs); + } - [Fact] - public void AServerThatNamesNoTimings_LeavesThemUnset_SoTheSessionDefaultsApply() - { - var document = ConfigurationLoader.LoadYaml(""" + [Fact] + public void AServerThatNamesNoTimings_LeavesThemUnset_SoTheSessionDefaultsApply() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -293,20 +292,20 @@ public void AServerThatNamesNoTimings_LeavesThemUnset_SoTheSessionDefaultsApply( allow: ["*"] """); - var server = Assert.Single(document.Mcp); - Assert.Null(server.ConnectTimeoutSeconds); - Assert.Null(server.CallTimeoutSeconds); - Assert.Null(server.Retry); - } + McpServerConfiguration server = Assert.Single(document.Mcp); + Assert.Null(server.ConnectTimeoutSeconds); + Assert.Null(server.CallTimeoutSeconds); + Assert.Null(server.Retry); + } - /// - /// The SDK's own default is to inherit, which would hand a third-party child process every other - /// credential this one holds. A document has to ask for that. - /// - [Fact] - public void InheritingTheHostEnvironment_IsOffUnlessTheDocumentAsks() - { - var document = ConfigurationLoader.LoadYaml(""" + /// + /// The SDK's own default is to inherit, which would hand a third-party child process every other + /// credential this one holds. A document has to ask for that. + /// + [Fact] + public void InheritingTheHostEnvironment_IsOffUnlessTheDocumentAsks() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(""" apiVersion: agentcore/v1 agents: items: @@ -326,7 +325,8 @@ public void InheritingTheHostEnvironment_IsOffUnlessTheDocumentAsks() allow: ["*"] """); - Assert.False(document.Mcp[0].InheritEnv); - Assert.True(document.Mcp[1].InheritEnv); + Assert.False(document.Mcp[0].InheritEnv); + Assert.True(document.Mcp[1].InheritEnv); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs index 3c7a6657..6ddc517f 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs @@ -5,21 +5,21 @@ using AgentCore.Application.Configuration.Validation; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Validation; - -/// -/// Checks 2 to 8 of section 8.5, and rule 14 of section 11. -/// -/// -/// Rule 14: each of the eight checks has a failing-configuration test that asserts the message and -/// the JSON Pointer, and check 5 prints the state that makes two guards overlap. Check 1 is tested -/// in , and the seven others are tested here. -/// -public sealed class ConfigurationValidatorTests +namespace AgentCore.Application.Tests.Configuration.Validation { - /// The smallest provider set that satisfies checks 1 and 2 on its own. - private const string MinimalProviders = - """ + /// + /// Checks 2 to 8 of section 8.5, and rule 14 of section 11. + /// + /// + /// Rule 14: each of the eight checks has a failing-configuration test that asserts the message and + /// the JSON Pointer, and check 5 prints the state that makes two guards overlap. Check 1 is tested + /// in , and the seven others are tested here. + /// + public sealed class ConfigurationValidatorTests + { + /// The smallest provider set that satisfies checks 1 and 2 on its own. + private const string MinimalProviders = + """ providers: conversation: { kind: telnyx-relay } speech: @@ -29,55 +29,45 @@ public sealed class ConfigurationValidatorTests - { kind: openai, model: gpt-4.1-mini, as: reply } """; - /// without llm:, for checks that never read a model. - private const string SpeechOnlyProviders = - """ - providers: - conversation: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - """; - - [Fact] - public void TheExample_PassesEveryCheck() - { - var configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + [Fact] + public void TheExample_PassesEveryCheck() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var result = ConfigurationValidator.Evaluate(configuration); + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(configuration); - Assert.Empty(result.Errors); - Assert.Empty(result.Warnings); - Assert.True(result.IsValid); - } + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + Assert.True(result.IsValid); + } - [Fact] - public void TheShippedExampleFile_PassesEveryCheck() - { - var path = Path.Combine(RepositoryRoot(), "config", "example.yaml"); - Assert.True(File.Exists(path), $"The shipped example is missing at '{path}'."); + [Fact] + public void TheShippedExampleFile_PassesEveryCheck() + { + string path = Path.Combine(RepositoryRoot(), "config", "example.yaml"); + Assert.True(File.Exists(path), $"The shipped example is missing at '{path}'."); - var result = ConfigurationValidator.Evaluate(ConfigurationLoader.LoadFile(path)); + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(ConfigurationLoader.LoadFile(path)); - Assert.Empty(result.Errors); - Assert.Empty(result.Warnings); - } + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + } - [Fact] - public void TheExampleAsJson_PassesEveryCheck() - { - var configuration = ConfigurationLoader.LoadJson(ExampleDocument.Json); + [Fact] + public void TheExampleAsJson_PassesEveryCheck() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadJson(ExampleDocument.Json); - Assert.Empty(ConfigurationValidator.Evaluate(configuration).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(configuration).Errors); + } - // --------------------------------------------------------------------------------------------- - // Check 2: reference resolution. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AnUnknownAgent_FailsCheckTwoWithThePointerOfTheStage() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 2: reference resolution. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AnUnknownAgent_FailsCheckTwoWithThePointerOfTheStage() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -90,16 +80,16 @@ public void AnUnknownAgent_FailsCheckTwoWithThePointerOfTheStage() - { id: greeting, agent: ghost, terminal: true } """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/entries/main/policy/stages/0/agent", error.Pointer); - Assert.Equal("the agent 'ghost' is not declared in agents.items", error.Message); - } + Assert.Equal("/entries/main/policy/stages/0/agent", error.Pointer); + Assert.Equal("the agent 'ghost' is not declared in agents.items", error.Message); + } - [Fact] - public void AnUnknownTool_FailsCheckTwoWithThePointerOfTheSlot() - { - const string document = """ + [Fact] + public void AnUnknownTool_FailsCheckTwoWithThePointerOfTheSlot() + { + const string document = """ apiVersion: agentcore/v1 state: orderStatus: { type: string, writer: tool, from: lookup_order.status } @@ -111,16 +101,16 @@ public void AnUnknownTool_FailsCheckTwoWithThePointerOfTheSlot() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/state/orderStatus/from", error.Pointer); - Assert.Equal("nothing serves the tool 'lookup_order'. Declare it in tools:, or check that an mcp: server offers it.", error.Message); - } + Assert.Equal("/state/orderStatus/from", error.Pointer); + Assert.Equal("nothing serves the tool 'lookup_order'. Declare it in tools:, or check that an mcp: server offers it.", error.Message); + } - [Fact] - public void ABackgroundChildThatIsNotAnAgent_FailsCheckTwoWithThePointerOfThatChild() - { - const string document = """ + [Fact] + public void ABackgroundChildThatIsNotAnAgent_FailsCheckTwoWithThePointerOfThatChild() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -131,16 +121,16 @@ public void ABackgroundChildThatIsNotAnAgent_FailsCheckTwoWithThePointerOfThatCh agent: coder """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/agents/items/0/background/0", error.Pointer); - Assert.Equal("the agent 'searcher' is not declared in agents.items", error.Message); - } + Assert.Equal("/agents/items/0/background/0", error.Pointer); + Assert.Equal("the agent 'searcher' is not declared in agents.items", error.Message); + } - [Fact] - public void AnUnknownGuard_FailsCheckTwoWithThePointerOfTheExit() - { - const string document = """ + [Fact] + public void AnUnknownGuard_FailsCheckTwoWithThePointerOfTheExit() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -156,16 +146,16 @@ public void AnUnknownGuard_FailsCheckTwoWithThePointerOfTheExit() - { id: close, agent: greeter, terminal: true } """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/entries/main/policy/stages/0/to/0/when", error.Pointer); - Assert.Equal("the guard 'ghostGuard' is not declared in guards:", error.Message); - } + Assert.Equal("/entries/main/policy/stages/0/to/0/when", error.Pointer); + Assert.Equal("the guard 'ghostGuard' is not declared in guards:", error.Message); + } - [Fact] - public void AnUnknownExtractorModel_FailsCheckTwoWithThePointerOfTheReference() - { - const string document = $$""" + [Fact] + public void AnUnknownExtractorModel_FailsCheckTwoWithThePointerOfTheReference() + { + const string document = $$""" apiVersion: agentcore/v1 extractor: model: { ref: ghost } @@ -178,16 +168,16 @@ public void AnUnknownExtractorModel_FailsCheckTwoWithThePointerOfTheReference() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/extractor/model/ref", error.Pointer); - Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); - } + Assert.Equal("/extractor/model/ref", error.Pointer); + Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); + } - [Fact] - public void AnUnknownJudgeModel_FailsCheckTwoWithThePointerOfTheReference() - { - const string document = $$""" + [Fact] + public void AnUnknownJudgeModel_FailsCheckTwoWithThePointerOfTheReference() + { + const string document = $$""" apiVersion: agentcore/v1 evaluation: judge: { ref: ghost } @@ -200,16 +190,16 @@ public void AnUnknownJudgeModel_FailsCheckTwoWithThePointerOfTheReference() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/evaluation/judge/ref", error.Pointer); - Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); - } + Assert.Equal("/evaluation/judge/ref", error.Pointer); + Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); + } - [Fact] - public void AnUnknownTitlerModel_FailsCheckTwoWithThePointerOfTheReference() - { - const string document = $$""" + [Fact] + public void AnUnknownTitlerModel_FailsCheckTwoWithThePointerOfTheReference() + { + const string document = $$""" apiVersion: agentcore/v1 titler: model: { ref: ghost } @@ -222,16 +212,16 @@ public void AnUnknownTitlerModel_FailsCheckTwoWithThePointerOfTheReference() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/titler/model/ref", error.Pointer); - Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); - } + Assert.Equal("/titler/model/ref", error.Pointer); + Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); + } - [Fact] - public void AnEvaluationSectionWithNoJudge_PassesCheckTwo() - { - const string document = $$""" + [Fact] + public void AnEvaluationSectionWithNoJudge_PassesCheckTwo() + { + const string document = $$""" apiVersion: agentcore/v1 evaluation: sampleRate: 0 @@ -244,13 +234,13 @@ public void AnEvaluationSectionWithNoJudge_PassesCheckTwo() agent: only """; - Assert.Empty(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - } + Assert.Empty(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + } - [Fact] - public void AnUnknownAgentModel_FailsCheckTwoWithThePointerOfThatAgent() - { - const string document = $$""" + [Fact] + public void AnUnknownAgentModel_FailsCheckTwoWithThePointerOfThatAgent() + { + const string document = $$""" apiVersion: agentcore/v1 {{MinimalProviders}} agents: @@ -261,16 +251,16 @@ public void AnUnknownAgentModel_FailsCheckTwoWithThePointerOfThatAgent() agent: greeter """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/agents/items/0/model/ref", error.Pointer); - Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); - } + Assert.Equal("/agents/items/0/model/ref", error.Pointer); + Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); + } - [Fact] - public void AnUnknownDefaultModel_FailsCheckTwoWithThePointerOfTheDefaults() - { - const string document = $$""" + [Fact] + public void AnUnknownDefaultModel_FailsCheckTwoWithThePointerOfTheDefaults() + { + const string document = $$""" apiVersion: agentcore/v1 agents: defaults: @@ -283,18 +273,18 @@ public void AnUnknownDefaultModel_FailsCheckTwoWithThePointerOfTheDefaults() agent: greeter """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/agents/defaults/model/ref", error.Pointer); - Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); - } + Assert.Equal("/agents/defaults/model/ref", error.Pointer); + Assert.Equal("the model 'ghost' is not declared in providers.llm", error.Message); + } - [Fact] - public void AModelReferenceWithNoProvidersSection_FailsCheckTwo() - { - // An absent providers: declares no model name, so the reference is unknown. Check 2 reads an - // absent tools: and an absent agents: the same way. - const string document = """ + [Fact] + public void AModelReferenceWithNoProvidersSection_FailsCheckTwo() + { + // An absent providers: declares no model name, so the reference is unknown. Check 2 reads an + // absent tools: and an absent agents: the same way. + const string document = """ apiVersion: agentcore/v1 extractor: model: { ref: fill } @@ -306,16 +296,16 @@ public void AModelReferenceWithNoProvidersSection_FailsCheckTwo() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/extractor/model/ref", error.Pointer); - Assert.Equal("the model 'fill' is not declared in providers.llm", error.Message); - } + Assert.Equal("/extractor/model/ref", error.Pointer); + Assert.Equal("the model 'fill' is not declared in providers.llm", error.Message); + } - [Fact] - public void ADocumentThatNamesNoModel_PassesCheckTwoWithNoProvidersSection() - { - const string document = """ + [Fact] + public void ADocumentThatNamesNoModel_PassesCheckTwoWithNoProvidersSection() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -325,14 +315,14 @@ public void ADocumentThatNamesNoModel_PassesCheckTwoWithNoProvidersSection() agent: greeter """; - Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); + } - [Fact] - public void AnUnusedAgentToolNamingAnUndeclaredAgent_FailsCheckTwo() - { - // No agent lists this tool, so only the compiler used to catch it, and only later. - const string document = """ + [Fact] + public void AnUnusedAgentToolNamingAnUndeclaredAgent_FailsCheckTwo() + { + // No agent lists this tool, so only the compiler used to catch it, and only later. + const string document = """ apiVersion: agentcore/v1 tools: - { id: conversation_ghost, kind: agent, agent: ghost } @@ -344,25 +334,25 @@ public void AnUnusedAgentToolNamingAnUndeclaredAgent_FailsCheckTwo() agent: planner """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/tools/0/agent", error.Pointer); - Assert.Equal("the agent 'ghost' is not declared in agents.items", error.Message); - } + Assert.Equal("/tools/0/agent", error.Pointer); + Assert.Equal("the agent 'ghost' is not declared in agents.items", error.Message); + } - // --------------------------------------------------------------------------------------------- - // Check 2, mcp: ids: two servers must not share one id. - // --------------------------------------------------------------------------------------------- - /// - /// Two mcp: entries with disjoint allow: sets would otherwise boot silently — nothing - /// in the schema, this validator, or McpToolSource catches it until an overlapping pair - /// happens to collide on a served tool id, and even then the failure names the tool, never the - /// duplicated server id. This runs before any connection opens. - /// - [Fact] - public void TwoMcpEntriesSharingAnId_FailCheckTwoNamingTheId() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 2, mcp: ids: two servers must not share one id. + // --------------------------------------------------------------------------------------------- + /// + /// Two mcp: entries with disjoint allow: sets would otherwise boot silently — nothing + /// in the schema, this validator, or McpToolSource catches it until an overlapping pair + /// happens to collide on a served tool id, and even then the failure names the tool, never the + /// duplicated server id. This runs before any connection opens. + /// + [Fact] + public void TwoMcpEntriesSharingAnId_FailCheckTwoNamingTheId() + { + const string document = """ apiVersion: agentcore/v1 mcp: - id: jira @@ -381,431 +371,446 @@ public void TwoMcpEntriesSharingAnId_FailCheckTwoNamingTheId() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); - Assert.Equal("/mcp/1/id", error.Pointer); - Assert.Contains("jira", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/mcp/1/id", error.Pointer); + Assert.Contains("jira", error.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // Check 2, knowledge scope: a state-built scope must not produce a filter nobody meant. - // --------------------------------------------------------------------------------------------- - // KnowledgeStartup skips the store factory for a host-supplied port, and returns null when - // KnowledgeStores is unset, but ConversationSession composes the scope regardless — so these are document - // checks, not store checks. - private static AgentCoreConfiguration Scoped( - IReadOnlyList fromState, - KnowledgeWildcardConfiguration? wildcard, - IDictionary state, - ExtractorConfiguration? extractor = null, - KnowledgeAmbiguityConfiguration? ambiguity = null, - string? mapper = null) => new() - { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [new AgentConfiguration { Id = "planner" }] }, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "planner" } }, - State = new Dictionary(state, StringComparer.Ordinal), - Extractor = extractor, - Providers = new() - { - // AnExtractor() references the model 'small'. Declaring it here means a caller that - // passes an extractor never also, silently, trips check 2's reference-resolution row — - // which every predicate-filtered assertion in this file would otherwise hide. - Llm = [new() { Kind = "openai", Model = "gpt", As = "small" }], - Knowledge = new() + // --------------------------------------------------------------------------------------------- + // Check 2, knowledge scope: a state-built scope must not produce a filter nobody meant. + // --------------------------------------------------------------------------------------------- + // KnowledgeStartup skips the store factory for a host-supplied port, and returns null when + // KnowledgeStores is unset, but ConversationSession composes the scope regardless — so these are document + // checks, not store checks. + private static AgentCoreConfiguration Scoped( + IReadOnlyList fromState, + KnowledgeWildcardConfiguration? wildcard, + IDictionary state, + ExtractorConfiguration? extractor = null, + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) + { + return new() { - Kind = "qdrant", - Collection = "kb", - Fields = new() { Body = "text" }, - Mapper = mapper, - Scope = new() + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [new AgentConfiguration { Id = "planner" }] }, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "planner" } }, + State = new Dictionary(state, StringComparer.Ordinal), + Extractor = extractor, + Providers = new() { - Template = "facets.{key}", - Wildcard = wildcard, - FromState = fromState, + // AnExtractor() references the model 'small'. Declaring it here means a caller that + // passes an extractor never also, silently, trips check 2's reference-resolution row — + // which every predicate-filtered assertion in this file would otherwise hide. + Llm = [new() { Kind = "openai", Model = "gpt", As = "small" }], + Knowledge = new() + { + Kind = "qdrant", + Collection = "kb", + Fields = new() { Body = "text" }, + Mapper = mapper, + Scope = new() + { + Template = "facets.{key}", + Wildcard = wildcard, + FromState = fromState, + }, + Ambiguity = ambiguity, + }, }, - Ambiguity = ambiguity, - }, - }, - }; - - private static StateSlotConfiguration FacetSlot() => new() - { - Type = StateSlotType.String, - Writer = StateWriter.Extractor, - EnumValues = [JsonValue.Create("f63")!], - }; - - private static KnowledgeAmbiguityConfiguration AnAmbiguity() => new(); - - private static readonly KnowledgeWildcardConfiguration Star = - new() { Value = "*", Facets = ["applies_to"] }; - - private static ExtractorConfiguration AnExtractor() => - new() { Model = new ModelReference { Ref = "small" } }; - - /// One facet slot, named by and by fromState. - private static AgentCoreConfiguration OneFacetScope( - KnowledgeAmbiguityConfiguration? ambiguity = null, - string? mapper = null) => - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity, - mapper); + }; + } - /// - /// Two facet slots. This is the smallest scope that keeps the single-facet ambiguity warning - /// (K33) silent, so it is the base for every test that asserts no warning. - /// - private static AgentCoreConfiguration TwoFacetScope( - KnowledgeAmbiguityConfiguration? ambiguity = null, - string? mapper = null) => - Scoped( - ["applies_to", "brand"], - new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }, - new Dictionary + private static StateSlotConfiguration FacetSlot() + { + return new() { - ["applies_to"] = FacetSlot(), - ["brand"] = FacetSlot(), - }, - AnExtractor(), - ambiguity, - mapper); - - [Fact] - public void Evaluate_FromStateNamesAnUndeclaredSlot_Fails() - { - var result = ConfigurationValidator.EvaluateStructure( - Scoped(["applies_to"], Star, new Dictionary(), AnExtractor())); + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [JsonValue.Create("f63")!], + }; + } - var error = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/fromState"); - Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); - } + private static KnowledgeAmbiguityConfiguration AnAmbiguity() + { + return new(); + } - [Fact] - public void Evaluate_FacetSlotDeclaresADefault_Fails() - { - var slot = FacetSlot() with { Default = JsonValue.Create("f63") }; + private static readonly KnowledgeWildcardConfiguration Star = + new() { Value = "*", Facets = ["applies_to"] }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( + private static ExtractorConfiguration AnExtractor() + { + return new() { Model = new ModelReference { Ref = "small" } }; + } + + /// One facet slot, named by and by fromState. + private static AgentCoreConfiguration OneFacetScope( + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) + { + return Scoped( ["applies_to"], Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor())); + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity, + mapper); + } - Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/default"); - } + /// + /// Two facet slots. This is the smallest scope that keeps the single-facet ambiguity warning + /// (K33) silent, so it is the base for every test that asserts no warning. + /// + private static AgentCoreConfiguration TwoFacetScope( + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) + { + return Scoped( + ["applies_to", "brand"], + new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity, + mapper); + } - [Fact] - public void Evaluate_FromStateWithoutAWildcard_Fails() - { - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - wildcard: null, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor())); + [Fact] + public void Evaluate_FromStateNamesAnUndeclaredSlot_Fails() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped(["applies_to"], Star, new Dictionary(), AnExtractor())); - Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard"); - } + ConfigurationError error = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/fromState"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } - [Fact] - public void Evaluate_FacetSlotIsNotTypeString_Fails() - { - var slot = FacetSlot() with { Type = StateSlotType.Boolean }; + [Fact] + public void Evaluate_FacetSlotDeclaresADefault_Fails() + { + StateSlotConfiguration slot = FacetSlot() with { Default = JsonValue.Create("f63") }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor())); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor())); - var error = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/type"); - Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); - } + _ = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/default"); + } - [Fact] - public void Evaluate_FacetSlotIsNotWrittenByExtractor_Fails() - { - var slot = FacetSlot() with { Writer = StateWriter.Const, Value = JsonValue.Create("f63") }; + [Fact] + public void Evaluate_FromStateWithoutAWildcard_Fails() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + wildcard: null, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor())); + + _ = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard"); + } - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor())); + [Fact] + public void Evaluate_FacetSlotIsNotTypeString_Fails() + { + StateSlotConfiguration slot = FacetSlot() with { Type = StateSlotType.Boolean }; - var error = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/writer"); - Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); - } + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor())); - [Fact] - public void Evaluate_FacetSlotDeclaresNoEnum_Fails() - { - var slot = FacetSlot() with { EnumValues = null }; + ConfigurationError error = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/type"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor())); + [Fact] + public void Evaluate_FacetSlotIsNotWrittenByExtractor_Fails() + { + StateSlotConfiguration slot = FacetSlot() with { Writer = StateWriter.Const, Value = JsonValue.Create("f63") }; - var error = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/enum"); - Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); - } + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor())); - [Fact] - public void Evaluate_FromStateWithNoExtractor_Fails() - { - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() })); + ConfigurationError error = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/writer"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } - Assert.Single(result.Errors, e => e.Pointer == "/extractor"); - } + [Fact] + public void Evaluate_FacetSlotDeclaresNoEnum_Fails() + { + StateSlotConfiguration slot = FacetSlot() with { EnumValues = null }; - [Fact] - public void Evaluate_FromStateNameNotInWildcardFacets_Fails() - { - // wildcard.facets omits 'applies_to' but every member it does name ('brand') is still in - // fromState, so only the fromState -> facets direction trips here; the reverse (facets -> - // fromState) has its own test below. - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }; + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor())); - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to", "brand"], - wildcard, - new Dictionary - { - ["applies_to"] = FacetSlot(), - ["brand"] = FacetSlot(), - }, - AnExtractor())); + ConfigurationError error = Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/enum"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } - var error = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/facets"); - Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); - } + [Fact] + public void Evaluate_FromStateWithNoExtractor_Fails() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() })); - [Fact] - public void Evaluate_WildcardFacetNotInFromState_Fails() - { - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "other_facet"] }; + _ = Assert.Single(result.Errors, e => e.Pointer == "/extractor"); + } - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - wildcard, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor())); + [Fact] + public void Evaluate_FromStateNameNotInWildcardFacets_Fails() + { + // wildcard.facets omits 'applies_to' but every member it does name ('brand') is still in + // fromState, so only the fromState -> facets direction trips here; the reverse (facets -> + // fromState) has its own test below. + KnowledgeWildcardConfiguration wildcard = new() { Value = "*", Facets = ["brand"] }; + + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to", "brand"], + wildcard, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor())); + + ConfigurationError error = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/facets"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/scope/wildcard/facets", error.Pointer); - Assert.Contains("other_facet", error.Message, StringComparison.Ordinal); - } + [Fact] + public void Evaluate_WildcardFacetNotInFromState_Fails() + { + KnowledgeWildcardConfiguration wildcard = new() { Value = "*", Facets = ["applies_to", "other_facet"] }; + + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + wildcard, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor())); + + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/scope/wildcard/facets", error.Pointer); + Assert.Contains("other_facet", error.Message, StringComparison.Ordinal); + } - [Fact] - public void Evaluate_FacetWildcardValueIsWhitespace_Fails() - { - var wildcard = new KnowledgeWildcardConfiguration { Value = " ", Facets = ["applies_to"] }; + [Fact] + public void Evaluate_FacetWildcardValueIsWhitespace_Fails() + { + KnowledgeWildcardConfiguration wildcard = new() { Value = " ", Facets = ["applies_to"] }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped([], wildcard, new Dictionary())); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped([], wildcard, new Dictionary())); - Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/value"); - } + _ = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/value"); + } - [Fact] - public void Evaluate_WildcardWithoutFromState_Passes() - { - // A deployment may resolve its own facets and open them as the host ambient, wanting only the - // wildcard's widening. StateKnowledgeScope.Compose refuses the reverse, never this. - var result = ConfigurationValidator.EvaluateStructure( - Scoped([], Star, new Dictionary())); + [Fact] + public void Evaluate_WildcardWithoutFromState_Passes() + { + // A deployment may resolve its own facets and open them as the host ambient, wanting only the + // wildcard's widening. StateKnowledgeScope.Compose refuses the reverse, never this. + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped([], Star, new Dictionary())); - Assert.Empty(result.Errors); - } + Assert.Empty(result.Errors); + } - [Fact] - public void Evaluate_FacetWildcardDeclaresNoFacets_Fails() - { - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = [] }; + [Fact] + public void Evaluate_FacetWildcardDeclaresNoFacets_Fails() + { + KnowledgeWildcardConfiguration wildcard = new() { Value = "*", Facets = [] }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped([], wildcard, new Dictionary())); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped([], wildcard, new Dictionary())); - Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/facets"); - } + _ = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/facets"); + } - // --------------------------------------------------------------------------------------------- - // Check 2, ambiguity: section 10 of the ambiguity design. - // - // Every fixture below keeps fromState and wildcard.facets in lockstep (both naming exactly the - // facets the test declares slots for) so the row-8 and enum checks stay silent, and sets - // ambiguity: and wildcard: wherever their absence would otherwise trip rows 5 or 6. - // Each refusal test asserts the *total* error count, not just a filtered pointer match, so a - // fixture that quietly grows a second error cannot hide behind the assertion. - // --------------------------------------------------------------------------------------------- - [Fact] - public void Evaluate_AmbiguityWithNoWildcard_Fails() - { - var result = ConfigurationValidator.EvaluateStructure( - Scoped([], wildcard: null, new Dictionary(), ambiguity: AnAmbiguity())); + // --------------------------------------------------------------------------------------------- + // Check 2, ambiguity: section 10 of the ambiguity design. + // + // Every fixture below keeps fromState and wildcard.facets in lockstep (both naming exactly the + // facets the test declares slots for) so the row-8 and enum checks stay silent, and sets + // ambiguity: and wildcard: wherever their absence would otherwise trip rows 5 or 6. + // Each refusal test asserts the *total* error count, not just a filtered pointer match, so a + // fixture that quietly grows a second error cannot hide behind the assertion. + // --------------------------------------------------------------------------------------------- + [Fact] + public void Evaluate_AmbiguityWithNoWildcard_Fails() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped([], wildcard: null, new Dictionary(), ambiguity: AnAmbiguity())); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityMaxCandidatesBelowTwo_Fails() - { - var ambiguity = new KnowledgeAmbiguityConfiguration { MaxCandidates = 1 }; + [Fact] + public void Evaluate_AmbiguityMaxCandidatesBelowTwo_Fails() + { + KnowledgeAmbiguityConfiguration ambiguity = new() { MaxCandidates = 1 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity/maxCandidates", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/maxCandidates", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityMaxAsksBelowZero_Fails() - { - var ambiguity = new KnowledgeAmbiguityConfiguration { MaxAsks = -1 }; + [Fact] + public void Evaluate_AmbiguityMaxAsksBelowZero_Fails() + { + KnowledgeAmbiguityConfiguration ambiguity = new() { MaxAsks = -1 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity/maxAsks", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/maxAsks", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityMaxAsksOfZero_IsLegal() - { - // K38: 0 means gate only. It must never trip the same floor that refuses a negative count. - var ambiguity = new KnowledgeAmbiguityConfiguration { MaxAsks = 0 }; + [Fact] + public void Evaluate_AmbiguityMaxAsksOfZero_IsLegal() + { + // K38: 0 means gate only. It must never trip the same floor that refuses a negative count. + KnowledgeAmbiguityConfiguration ambiguity = new() { MaxAsks = 0 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - Assert.Empty(result.Errors); - } + Assert.Empty(result.Errors); + } - [Fact] - public void Evaluate_AmbiguityProbeDeadlineSecondsBelowOne_Fails() - { - var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 0 }; + [Fact] + public void Evaluate_AmbiguityProbeDeadlineSecondsBelowOne_Fails() + { + KnowledgeAmbiguityConfiguration ambiguity = new() { ProbeDeadlineSeconds = 0 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity/probeDeadlineSeconds", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/probeDeadlineSeconds", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityProbeWaitMarginSecondsBelowOne_Fails() - { - var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeWaitMarginSeconds = 0 }; + [Fact] + public void Evaluate_AmbiguityProbeWaitMarginSecondsBelowOne_Fails() + { + KnowledgeAmbiguityConfiguration ambiguity = new() { ProbeWaitMarginSeconds = 0 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityWithCustomMapper_Fails() - { - // The probe reads Extras, which only the built-in field mapper fills. - var result = ConfigurationValidator.EvaluateStructure( - TwoFacetScope(AnAmbiguity(), mapper: "custom-mapper")); + [Fact] + public void Evaluate_AmbiguityWithCustomMapper_Fails() + { + // The probe reads Extras, which only the built-in field mapper fills. + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + TwoFacetScope(AnAmbiguity(), mapper: "custom-mapper")); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/mapper", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/mapper", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityProbeDeadlineSecondsAboveTheTimerCeiling_Fails() - { - // CancelAfter throws above int.MaxValue milliseconds, from a conversation site with no pointer. - var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 3_000_000 }; + [Fact] + public void Evaluate_AmbiguityProbeDeadlineSecondsAboveTheTimerCeiling_Fails() + { + // CancelAfter throws above int.MaxValue milliseconds, from a conversation site with no pointer. + KnowledgeAmbiguityConfiguration ambiguity = new() { ProbeDeadlineSeconds = 3_000_000 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity/probeDeadlineSeconds", error.Pointer); - Assert.Equal(ConfigurationCheck.ValueRange, error.Check); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/probeDeadlineSeconds", error.Pointer); + Assert.Equal(ConfigurationCheck.ValueRange, error.Check); + } - [Fact] - public void Evaluate_AmbiguityProbeWaitMarginSecondsAboveTheTimerCeiling_Fails() - { - var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeWaitMarginSeconds = 3_000_000 }; + [Fact] + public void Evaluate_AmbiguityProbeWaitMarginSecondsAboveTheTimerCeiling_Fails() + { + KnowledgeAmbiguityConfiguration ambiguity = new() { ProbeWaitMarginSeconds = 3_000_000 }; - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); - var error = Assert.Single(result.Errors); - Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); + } - [Fact] - public void Evaluate_AmbiguityWithEmptyFromState_Warns() - { - // No facet to drop is as unreachable as one, and the wildcard-only shape now loads. - var result = ConfigurationValidator.EvaluateStructure( - Scoped([], Star, new Dictionary(), ambiguity: AnAmbiguity())); + [Fact] + public void Evaluate_AmbiguityWithEmptyFromState_Warns() + { + // No facet to drop is as unreachable as one, and the wildcard-only shape now loads. + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure( + Scoped([], Star, new Dictionary(), ambiguity: AnAmbiguity())); - Assert.Empty(result.Errors); - var warning = Assert.Single(result.Warnings); - Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); - } + Assert.Empty(result.Errors); + ConfigurationError warning = Assert.Single(result.Warnings); + Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); + } - [Fact] - public void Evaluate_AmbiguityWithSingleFacetFromState_Warns() - { - var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(AnAmbiguity())); + [Fact] + public void Evaluate_AmbiguityWithSingleFacetFromState_Warns() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(OneFacetScope(AnAmbiguity())); - Assert.Empty(result.Errors); - var warning = Assert.Single(result.Warnings); - Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); - } + Assert.Empty(result.Errors); + ConfigurationError warning = Assert.Single(result.Warnings); + Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); + } - [Fact] - public void Evaluate_AmbiguityWithTwoFacetsFromState_DoesNotWarn() - { - var result = ConfigurationValidator.EvaluateStructure(TwoFacetScope(AnAmbiguity())); + [Fact] + public void Evaluate_AmbiguityWithTwoFacetsFromState_DoesNotWarn() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(TwoFacetScope(AnAmbiguity())); - Assert.Empty(result.Errors); - Assert.Empty(result.Warnings); - } + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + } - [Fact] - public void Evaluate_NoAmbiguity_BindsNullAndAddsNothing() - { - var configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + [Fact] + public void Evaluate_NoAmbiguity_BindsNullAndAddsNothing() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - Assert.Null(configuration.Providers?.Knowledge?.Ambiguity); + Assert.Null(configuration.Providers?.Knowledge?.Ambiguity); - var result = ConfigurationValidator.Evaluate(configuration); + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(configuration); - Assert.Empty(result.Errors); - Assert.Empty(result.Warnings); - } + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + } - // --------------------------------------------------------------------------------------------- - // Check 3: one writer for each slot. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AReservedSlotDeclaredInState_FailsCheckThreeWithThePointerOfTheSlot() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 3: one writer for each slot. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AReservedSlotDeclaredInState_FailsCheckThreeWithThePointerOfTheSlot() + { + const string document = """ apiVersion: agentcore/v1 state: stage: { type: string, writer: extractor } @@ -817,18 +822,18 @@ public void AReservedSlotDeclaredInState_FailsCheckThreeWithThePointerOfTheSlot( agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.SlotWriters)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.SlotWriters)); - Assert.Equal("/state/stage", error.Pointer); - Assert.Equal( - "the slot has two writers: 'stage' is a reserved read-only slot that is always present, and state: declares it again", - error.Message); - } + Assert.Equal("/state/stage", error.Pointer); + Assert.Equal( + "the slot has two writers: 'stage' is a reserved read-only slot that is always present, and state: declares it again", + error.Message); + } - [Fact] - public void ASlotWithASecondWriterField_FailsCheckThreeWithThePointerOfThatField() - { - const string document = """ + [Fact] + public void ASlotWithASecondWriterField_FailsCheckThreeWithThePointerOfThatField() + { + const string document = """ apiVersion: agentcore/v1 state: failedResolveTurns: @@ -844,19 +849,19 @@ public void ASlotWithASecondWriterField_FailsCheckThreeWithThePointerOfThatField agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.SlotWriters)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.SlotWriters)); - Assert.Equal("/state/failedResolveTurns/value", error.Pointer); - Assert.Equal("the slot has two writers: writer: counter owns it, and 'value:' names a second", error.Message); - } + Assert.Equal("/state/failedResolveTurns/value", error.Pointer); + Assert.Equal("the slot has two writers: writer: counter owns it, and 'value:' names a second", error.Message); + } - // --------------------------------------------------------------------------------------------- - // Check 4: guard operators and variables. - // --------------------------------------------------------------------------------------------- - [Fact] - public void LooseEquality_FailsCheckFourAndTheMessageNamesTheReplacement() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 4: guard operators and variables. + // --------------------------------------------------------------------------------------------- + [Fact] + public void LooseEquality_FailsCheckFourAndTheMessageNamesTheReplacement() + { + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -870,28 +875,28 @@ public void LooseEquality_FailsCheckFourAndTheMessageNamesTheReplacement() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); - Assert.Equal("/guards/fixedNow", error.Pointer); - Assert.Equal("the operator '==' is rejected because it is loose equality. Use '===' instead.", error.Message); - } + Assert.Equal("/guards/fixedNow", error.Pointer); + Assert.Equal("the operator '==' is rejected because it is loose equality. Use '===' instead.", error.Message); + } - [Theory] - [InlineData("==")] - [InlineData("!=")] - [InlineData("log")] - [InlineData("map")] - [InlineData("filter")] - [InlineData("reduce")] - [InlineData("all")] - [InlineData("some")] - [InlineData("none")] - [InlineData("merge")] - [InlineData("cat")] - [InlineData("substr")] - public void EveryRejectedOperator_FailsCheckFour(string rejected) - { - var document = $$""" + [Theory] + [InlineData("==")] + [InlineData("!=")] + [InlineData("log")] + [InlineData("map")] + [InlineData("filter")] + [InlineData("reduce")] + [InlineData("all")] + [InlineData("some")] + [InlineData("none")] + [InlineData("merge")] + [InlineData("cat")] + [InlineData("substr")] + public void EveryRejectedOperator_FailsCheckFour(string rejected) + { + string document = $$""" apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -905,16 +910,16 @@ public void EveryRejectedOperator_FailsCheckFour(string rejected) agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); - Assert.Equal("/guards/bad", error.Pointer); - Assert.Equal(GuardOperators.DescribeRejection(rejected), error.Message); - } + Assert.Equal("/guards/bad", error.Pointer); + Assert.Equal(GuardOperators.DescribeRejection(rejected), error.Message); + } - [Fact] - public void AVarNamingAnUndeclaredSlot_FailsCheckFour() - { - const string document = """ + [Fact] + public void AVarNamingAnUndeclaredSlot_FailsCheckFour() + { + const string document = """ apiVersion: agentcore/v1 guards: ghost: { var: neverDeclared } @@ -926,16 +931,16 @@ public void AVarNamingAnUndeclaredSlot_FailsCheckFour() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); - Assert.Equal("/guards/ghost", error.Pointer); - Assert.Equal("the rule reads the slot 'neverDeclared', and state: does not declare it", error.Message); - } + Assert.Equal("/guards/ghost", error.Pointer); + Assert.Equal("the rule reads the slot 'neverDeclared', and state: does not declare it", error.Message); + } - [Fact] - public void ANumericComparisonAgainstABooleanSlot_FailsCheckFour() - { - const string document = """ + [Fact] + public void ANumericComparisonAgainstABooleanSlot_FailsCheckFour() + { + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -949,18 +954,18 @@ public void ANumericComparisonAgainstABooleanSlot_FailsCheckFour() agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); - Assert.Equal("/guards/tooMany", error.Pointer); - Assert.Equal( - "the operator '>=' compares the slot 'resolved', and that slot is a boolean rather than a number", - error.Message); - } + Assert.Equal("/guards/tooMany", error.Pointer); + Assert.Equal( + "the operator '>=' compares the slot 'resolved', and that slot is a boolean rather than a number", + error.Message); + } - [Fact] - public void TheUnarySugarFormOfDoubleNegation_FailsCheckFourAndTheMessageNamesTheArrayForm() - { - const string document = """ + [Fact] + public void TheUnarySugarFormOfDoubleNegation_FailsCheckFourAndTheMessageNamesTheArrayForm() + { + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -974,17 +979,17 @@ public void TheUnarySugarFormOfDoubleNegation_FailsCheckFourAndTheMessageNamesTh agent: only """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardOperators)); - Assert.Equal("/guards/isResolved", error.Pointer); - Assert.Equal(GuardOperators.DoubleNegationSugarRejection, error.Message); - Assert.Contains("""{"!!": [ x ]}""", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/guards/isResolved", error.Pointer); + Assert.Equal(GuardOperators.DoubleNegationSugarRejection, error.Message); + Assert.Contains("""{"!!": [ x ]}""", error.Message, StringComparison.Ordinal); + } - [Fact] - public void TheArrayFormOfDoubleNegation_PassesCheckFour() - { - const string document = """ + [Fact] + public void TheArrayFormOfDoubleNegation_PassesCheckFour() + { + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -998,14 +1003,14 @@ public void TheArrayFormOfDoubleNegation_PassesCheckFour() agent: only """; - Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); + } - [Fact] - public void TheUnarySugarFormOfSingleNegation_PassesCheckFour() - { - // JsonLogic reads the sugar for '!' and not for '!!', so only '!!' is rejected. - const string document = """ + [Fact] + public void TheUnarySugarFormOfSingleNegation_PassesCheckFour() + { + // JsonLogic reads the sugar for '!' and not for '!!', so only '!!' is rejected. + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -1019,13 +1024,13 @@ public void TheUnarySugarFormOfSingleNegation_PassesCheckFour() agent: only """; - Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); + } - [Fact] - public void AReservedSlotReadInARule_PassesCheckFour() - { - const string document = """ + [Fact] + public void AReservedSlotReadInARule_PassesCheckFour() + { + const string document = """ apiVersion: agentcore/v1 guards: inResolve: { "===": [ { var: stage }, "resolve" ] } @@ -1039,16 +1044,16 @@ public void AReservedSlotReadInARule_PassesCheckFour() agent: only """; - Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); + } - // --------------------------------------------------------------------------------------------- - // Check 5: exclusivity and coverage by evaluation. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TwoSiblingGuardsTrueAtOnce_FailCheckFiveAndTheMessagePrintsTheState() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 5: exclusivity and coverage by evaluation. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TwoSiblingGuardsTrueAtOnce_FailCheckFiveAndTheMessagePrintsTheState() + { + const string document = """ apiVersion: agentcore/v1 state: callerAskedForHuman: { type: boolean, default: false, writer: extractor } @@ -1074,19 +1079,19 @@ public void TwoSiblingGuardsTrueAtOnce_FailCheckFiveAndTheMessagePrintsTheState( """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); - Assert.Equal("/entries/main/policy/stages/0/to/1/when", error.Pointer); - Assert.Equal( - "the guard 'saidGoodbye' and the guard 'wantsHuman' are both true at the same time. " - + """The state that triggers it is {"callerSaidGoodbye":true,"callerAskedForHuman":true}.""", - error.Message); - } + Assert.Equal("/entries/main/policy/stages/0/to/1/when", error.Pointer); + Assert.Equal( + "the guard 'saidGoodbye' and the guard 'wantsHuman' are both true at the same time. " + + """The state that triggers it is {"callerSaidGoodbye":true,"callerAskedForHuman":true}.""", + error.Message); + } - [Fact] - public void AnUnconditionalExitBesideAGuardedOne_FailsCheckFive() - { - const string document = """ + [Fact] + public void AnUnconditionalExitBesideAGuardedOne_FailsCheckFive() + { + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -1109,17 +1114,17 @@ public void AnUnconditionalExitBesideAGuardedOne_FailsCheckFive() - { id: escalate, agent: greeter, terminal: true } """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); - Assert.Equal("/entries/main/policy/stages/0/to/1", error.Pointer); - Assert.Contains("the unconditional exit to 'escalate'", error.Message, StringComparison.Ordinal); - Assert.Contains("""{"resolved":true}""", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/entries/main/policy/stages/0/to/1", error.Pointer); + Assert.Contains("the unconditional exit to 'escalate'", error.Message, StringComparison.Ordinal); + Assert.Contains(/*lang=json,strict*/ """{"resolved":true}""", error.Message, StringComparison.Ordinal); + } - [Fact] - public void TwoGraphEdgesTrueAtOnce_FailCheckFiveOnTheEdge() - { - const string document = """ + [Fact] + public void TwoGraphEdgesTrueAtOnce_FailCheckFiveOnTheEdge() + { + const string document = """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -1144,19 +1149,19 @@ public void TwoGraphEdgesTrueAtOnce_FailCheckFiveOnTheEdge() """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); - Assert.Equal("/entries/main/graph/edges/1/when", error.Pointer); - Assert.Contains("the guard 'fixedNow' and the guard 'handedOff'", error.Message, StringComparison.Ordinal); - Assert.Contains("""{"resolved":true,"escalated":false}""", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/entries/main/graph/edges/1/when", error.Pointer); + Assert.Contains("the guard 'fixedNow' and the guard 'handedOff'", error.Message, StringComparison.Ordinal); + Assert.Contains(/*lang=json,strict*/ """{"resolved":true,"escalated":false}""", error.Message, StringComparison.Ordinal); + } - [Fact] - public void ANumberSlot_IsBucketedAroundEveryThresholdTheSiblingsMention() - { - // failedResolveTurns >= 3 and failedResolveTurns < 3 never overlap, so the buckets must not - // invent a false positive. failedResolveTurns >= 3 and failedResolveTurns > 1 do overlap at 4. - const string document = """ + [Fact] + public void ANumberSlot_IsBucketedAroundEveryThresholdTheSiblingsMention() + { + // failedResolveTurns >= 3 and failedResolveTurns < 3 never overlap, so the buckets must not + // invent a false positive. failedResolveTurns >= 3 and failedResolveTurns > 1 do overlap at 4. + const string document = """ apiVersion: agentcore/v1 state: failedResolveTurns: { type: integer, default: 0, writer: counter, increment: { var: turnIndex } } @@ -1180,35 +1185,35 @@ public void ANumberSlot_IsBucketedAroundEveryThresholdTheSiblingsMention() - { id: escalate, agent: greeter, terminal: true } """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); - - Assert.Equal("/entries/main/policy/stages/0/to/1/when", error.Pointer); - Assert.Contains("""{"failedResolveTurns":3}""", error.Message, StringComparison.Ordinal); - } - - [Fact] - public void AStateDomainAboveTheCeiling_WarnsThatCoverageIsPartial() - { - var configuration = ConfigurationLoader.LoadYaml(WideDocument(17)); - - var result = ConfigurationValidator.Evaluate(configuration); - - Assert.Empty(result.Errors); - var warning = Assert.Single(result.Warnings); - Assert.Equal(ConfigurationCheck.GuardExclusivity, warning.Check); - Assert.Equal("/entries/main/policy/stages/0/to", warning.Pointer); - Assert.Equal( - "the state domain of the stage 'resolve' passes 65536 points, so check 5 sampled 65536 points at random and its coverage is partial", - warning.Message); - } - - // --------------------------------------------------------------------------------------------- - // Check 6: reachability. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AnUnreachableStage_FailsCheckSixWithThePointerOfThatStage() - { - const string document = """ + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GuardExclusivity)); + + Assert.Equal("/entries/main/policy/stages/0/to/1/when", error.Pointer); + Assert.Contains(/*lang=json,strict*/ """{"failedResolveTurns":3}""", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void AStateDomainAboveTheCeiling_WarnsThatCoverageIsPartial() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(WideDocument(17)); + + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(configuration); + + Assert.Empty(result.Errors); + ConfigurationError warning = Assert.Single(result.Warnings); + Assert.Equal(ConfigurationCheck.GuardExclusivity, warning.Check); + Assert.Equal("/entries/main/policy/stages/0/to", warning.Pointer); + Assert.Equal( + "the state domain of the stage 'resolve' passes 65536 points, so check 5 sampled 65536 points at random and its coverage is partial", + warning.Message); + } + + // --------------------------------------------------------------------------------------------- + // Check 6: reachability. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AnUnreachableStage_FailsCheckSixWithThePointerOfThatStage() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1222,16 +1227,16 @@ public void AnUnreachableStage_FailsCheckSixWithThePointerOfThatStage() - { id: island, agent: greeter, terminal: true } """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.Reachability)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.Reachability)); - Assert.Equal("/entries/main/policy/stages/1", error.Pointer); - Assert.Equal("the stage 'island' is unreachable from the initial stage 'greeting' in entry 'main'", error.Message); - } + Assert.Equal("/entries/main/policy/stages/1", error.Pointer); + Assert.Equal("the stage 'island' is unreachable from the initial stage 'greeting' in entry 'main'", error.Message); + } - [Fact] - public void ANonTerminalStageWithNoExit_FailsCheckSix() - { - const string document = """ + [Fact] + public void ANonTerminalStageWithNoExit_FailsCheckSix() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1244,19 +1249,19 @@ public void ANonTerminalStageWithNoExit_FailsCheckSix() - { id: greeting, agent: greeter } """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.Reachability)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.Reachability)); - Assert.Equal("/entries/main/policy/stages/0", error.Pointer); - Assert.Equal("the stage 'greeting' is not terminal and has no exit", error.Message); - } + Assert.Equal("/entries/main/policy/stages/0", error.Pointer); + Assert.Equal("the stage 'greeting' is not terminal and has no exit", error.Message); + } - // --------------------------------------------------------------------------------------------- - // Check 7: graph well-formedness. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AGraphWithNoStartNode_FailsCheckSeven() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 7: graph well-formedness. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AGraphWithNoStartNode_FailsCheckSeven() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1273,16 +1278,16 @@ public void AGraphWithNoStartNode_FailsCheckSeven() """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GraphWellFormedness)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GraphWellFormedness)); - Assert.Equal("/entries/main/graph/nodes", error.Pointer); - Assert.Equal("the graph in entry 'main' declares 0 start nodes, and check 7 needs exactly one", error.Message); - } + Assert.Equal("/entries/main/graph/nodes", error.Pointer); + Assert.Equal("the graph in entry 'main' declares 0 start nodes, and check 7 needs exactly one", error.Message); + } - [Fact] - public void AnOrphanNode_FailsCheckSevenWithThePointerOfThatNode() - { - const string document = """ + [Fact] + public void AnOrphanNode_FailsCheckSevenWithThePointerOfThatNode() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1300,17 +1305,17 @@ public void AnOrphanNode_FailsCheckSevenWithThePointerOfThatNode() """; - // An orphan is also unreachable, so check 6 speaks too. This test reads check 7 alone. - var error = SingleFor(document, ConfigurationCheck.GraphWellFormedness); + // An orphan is also unreachable, so check 6 speaks too. This test reads check 7 alone. + ConfigurationError error = SingleFor(document, ConfigurationCheck.GraphWellFormedness); - Assert.Equal("/entries/main/graph/nodes/2", error.Pointer); - Assert.Equal("the node 'island' is an orphan: no edge reaches it and no edge leaves it", error.Message); - } + Assert.Equal("/entries/main/graph/nodes/2", error.Pointer); + Assert.Equal("the node 'island' is an orphan: no edge reaches it and no edge leaves it", error.Message); + } - [Fact] - public void APathThatReachesNoOutput_FailsCheckSeven() - { - const string document = """ + [Fact] + public void APathThatReachesNoOutput_FailsCheckSeven() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1329,16 +1334,16 @@ public void APathThatReachesNoOutput_FailsCheckSeven() """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.GraphWellFormedness)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.GraphWellFormedness)); - Assert.Equal("/entries/main/graph/nodes/2", error.Pointer); - Assert.Equal("no path from the node 'sink' reaches an output node", error.Message); - } + Assert.Equal("/entries/main/graph/nodes/2", error.Pointer); + Assert.Equal("no path from the node 'sink' reaches an output node", error.Message); + } - [Fact] - public void AnUnreachableNode_FailsCheckSix() - { - const string document = """ + [Fact] + public void AnUnreachableNode_FailsCheckSix() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1357,19 +1362,19 @@ public void AnUnreachableNode_FailsCheckSix() """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.Reachability)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.Reachability)); - Assert.Equal("/entries/main/graph/nodes/2", error.Pointer); - Assert.Equal("the node 'island' is unreachable from the start node 'first' in entry 'main'", error.Message); - } + Assert.Equal("/entries/main/graph/nodes/2", error.Pointer); + Assert.Equal("the node 'island' is unreachable from the start node 'first' in entry 'main'", error.Message); + } - // --------------------------------------------------------------------------------------------- - // Check 8: delegation cycles. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AnAgentAsToolLoop_FailsCheckEightWithThePointerOfTheToolThatClosesIt() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // Check 8: delegation cycles. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AnAgentAsToolLoop_FailsCheckEightWithThePointerOfTheToolThatClosesIt() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: call_writer, kind: agent, agent: writer } @@ -1383,19 +1388,19 @@ public void AnAgentAsToolLoop_FailsCheckEightWithThePointerOfTheToolThatClosesIt agent: planner """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.DelegationCycles)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.DelegationCycles)); - Assert.Equal("/agents/items/1/tools/0", error.Pointer); - Assert.Equal( - "this tool runs the agent 'planner', and that closes the delegation cycle " - + "planner -> writer -> planner. The conversation would never return.", - error.Message); - } + Assert.Equal("/agents/items/1/tools/0", error.Pointer); + Assert.Equal( + "this tool runs the agent 'planner', and that closes the delegation cycle " + + "planner -> writer -> planner. The conversation would never return.", + error.Message); + } - [Fact] - public void AnAgentThatCallsItself_FailsCheckEight() - { - const string document = """ + [Fact] + public void AnAgentThatCallsItself_FailsCheckEight() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: call_self, kind: agent, agent: planner } @@ -1407,16 +1412,16 @@ public void AnAgentThatCallsItself_FailsCheckEight() agent: planner """; - var error = Assert.Single(Evaluate(document, ConfigurationCheck.DelegationCycles)); + ConfigurationError error = Assert.Single(Evaluate(document, ConfigurationCheck.DelegationCycles)); - Assert.Equal("/agents/items/0/tools/0", error.Pointer); - Assert.Contains("planner -> planner", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/0/tools/0", error.Pointer); + Assert.Contains("planner -> planner", error.Message, StringComparison.Ordinal); + } - [Fact] - public void ATwoAgentDelegationChainWithNoLoop_PassesCheckEight() - { - const string document = """ + [Fact] + public void ATwoAgentDelegationChainWithNoLoop_PassesCheckEight() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: call_writer, kind: agent, agent: writer } @@ -1431,16 +1436,16 @@ public void ATwoAgentDelegationChainWithNoLoop_PassesCheckEight() agent: planner """; - Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); + } - [Fact] - public void AToolWhoseUsesValueMatchesAnAgentId_IsNotADelegationEdge() - { - // 'uses:' names a built-in and never an agent, so the match is a coincidence. The old check 8 - // read this pair as a cycle. The tool id matches an agent id here as well, and that is a - // coincidence too. - const string document = """ + [Fact] + public void AToolWhoseUsesValueMatchesAnAgentId_IsNotADelegationEdge() + { + // 'uses:' names a built-in and never an agent, so the match is a coincidence. The old check 8 + // read this pair as a cycle. The tool id matches an agent id here as well, and that is a + // coincidence too. + const string document = """ apiVersion: agentcore/v1 tools: - { id: writer, kind: builtin, uses: planner } @@ -1454,16 +1459,16 @@ public void AToolWhoseUsesValueMatchesAnAgentId_IsNotADelegationEdge() agent: writer """; - Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); - } + Assert.Empty(ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(document)).Errors); + } - // --------------------------------------------------------------------------------------------- - // The entry point. - // --------------------------------------------------------------------------------------------- - [Fact] - public void Validate_ThrowsOneExceptionThatCarriesEveryError() - { - const string document = """ + // --------------------------------------------------------------------------------------------- + // The entry point. + // --------------------------------------------------------------------------------------------- + [Fact] + public void Validate_ThrowsOneExceptionThatCarriesEveryError() + { + const string document = """ apiVersion: agentcore/v1 state: stage: { type: string, writer: extractor } @@ -1481,38 +1486,38 @@ public void Validate_ThrowsOneExceptionThatCarriesEveryError() """; - var configuration = ConfigurationLoader.LoadYaml(document); - - var failure = Assert.Throws(() => ConfigurationValidator.Validate(configuration)); - - Assert.Equal(3, failure.Errors.Count); - Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.ReferenceResolution); - Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.SlotWriters); - Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.GuardOperators); - } - - [Fact] - public void Validate_ReturnsTheWarningsWhenNothingFails() - { - var configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - - var result = ConfigurationValidator.Validate(configuration); - - Assert.True(result.IsValid); - } - - // --------------------------------------------------------------------------------------------- - // Decision 15: structural, then tool references. - // --------------------------------------------------------------------------------------------- - /// - /// Decision 15's whole point: a YAML typo must not cost a round trip to every MCP server. The - /// structural pass therefore has to find a defect that has nothing to do with tool ids, on a - /// document whose tool references cannot possibly resolve yet. - /// - [Fact] - public void EvaluateStructure_ADefectThatIsNotAToolReference_IsFoundWithNoServedIds() - { - const string document = """ + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationValidator.Validate(configuration)); + + Assert.Equal(3, failure.Errors.Count); + Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.ReferenceResolution); + Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.SlotWriters); + Assert.Contains(failure.Errors, error => error.Check == ConfigurationCheck.GuardOperators); + } + + [Fact] + public void Validate_ReturnsTheWarningsWhenNothingFails() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + + ConfigurationValidationResult result = ConfigurationValidator.Validate(configuration); + + Assert.True(result.IsValid); + } + + // --------------------------------------------------------------------------------------------- + // Decision 15: structural, then tool references. + // --------------------------------------------------------------------------------------------- + /// + /// Decision 15's whole point: a YAML typo must not cost a round trip to every MCP server. The + /// structural pass therefore has to find a defect that has nothing to do with tool ids, on a + /// document whose tool references cannot possibly resolve yet. + /// + [Fact] + public void EvaluateStructure_ADefectThatIsNotAToolReference_IsFoundWithNoServedIds() + { + const string document = """ apiVersion: agentcore/v1 guards: ghost: { var: neverDeclared } @@ -1524,21 +1529,21 @@ public void EvaluateStructure_ADefectThatIsNotAToolReference_IsFoundWithNoServed agent: planner """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - var result = ConfigurationValidator.EvaluateStructure(configuration); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(configuration); - var error = Assert.Single(result.Errors); - Assert.Equal(ConfigurationCheck.GuardOperators, error.Check); - Assert.Equal("/guards/ghost", error.Pointer); - Assert.Equal("the rule reads the slot 'neverDeclared', and state: does not declare it", error.Message); - Assert.DoesNotContain(result.Errors, e => e.Message.Contains("jira.create_issue", StringComparison.Ordinal)); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal(ConfigurationCheck.GuardOperators, error.Check); + Assert.Equal("/guards/ghost", error.Pointer); + Assert.Equal("the rule reads the slot 'neverDeclared', and state: does not declare it", error.Message); + Assert.DoesNotContain(result.Errors, e => e.Message.Contains("jira.create_issue", StringComparison.Ordinal)); + } - [Fact] - public void ValidateToolReferences_AnIdNothingServes_FailsNamingTheIdAndThePointer() - { - const string document = """ + [Fact] + public void ValidateToolReferences_AnIdNothingServes_FailsNamingTheIdAndThePointer() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1548,23 +1553,23 @@ public void ValidateToolReferences_AnIdNothingServes_FailsNamingTheIdAndThePoint agent: planner """; - var configuration = ConfigurationLoader.LoadYaml(document); - var servedToolIds = new HashSet(StringComparer.Ordinal); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + HashSet servedToolIds = new(StringComparer.Ordinal); - var failure = Assert.Throws( - () => ConfigurationValidator.ValidateToolReferences(configuration, servedToolIds)); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationValidator.ValidateToolReferences(configuration, servedToolIds)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/agents/items/0/tools/0", error.Pointer); - Assert.Equal( - "nothing serves the tool 'jira.create_issue'. Declare it in tools:, or check that an mcp: server offers it.", - error.Message); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/agents/items/0/tools/0", error.Pointer); + Assert.Equal( + "nothing serves the tool 'jira.create_issue'. Declare it in tools:, or check that an mcp: server offers it.", + error.Message); + } - [Fact] - public void ValidateToolReferences_AnIdOnlyDiscoveryServes_Passes() - { - const string document = """ + [Fact] + public void ValidateToolReferences_AnIdOnlyDiscoveryServes_Passes() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1574,18 +1579,18 @@ public void ValidateToolReferences_AnIdOnlyDiscoveryServes_Passes() agent: planner """; - var configuration = ConfigurationLoader.LoadYaml(document); - var servedToolIds = new HashSet(StringComparer.Ordinal) { "jira.create_issue" }; + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + HashSet servedToolIds = new(StringComparer.Ordinal) { "jira.create_issue" }; - var exception = Record.Exception(() => ConfigurationValidator.ValidateToolReferences(configuration, servedToolIds)); + Exception? exception = Record.Exception(() => ConfigurationValidator.ValidateToolReferences(configuration, servedToolIds)); - Assert.Null(exception); - } + Assert.Null(exception); + } - [Fact] - public void ValidateSkillReferences_ANameTheFolderDoesNotServe_FailsNamingItAndWhatIsServed() - { - const string document = """ + [Fact] + public void ValidateSkillReferences_ANameTheFolderDoesNotServe_FailsNamingItAndWhatIsServed() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1595,24 +1600,24 @@ public void ValidateSkillReferences_ANameTheFolderDoesNotServe_FailsNamingItAndW agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); - var served = new HashSet(["shipping-claims", "warranty-returns"], StringComparer.Ordinal); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + HashSet served = new(["shipping-claims", "warranty-returns"], StringComparer.Ordinal); - var failure = Assert.Throws( - () => ConfigurationValidator.ValidateSkillReferences(configuration, served)); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationValidator.ValidateSkillReferences(configuration, served)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/agents/items/0/skills/0", error.Pointer); - Assert.Equal( - "the skill 'warranty-return' is not in the bound skills folder. The folder serves: shipping-claims, warranty-returns.", - error.Message); - Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/agents/items/0/skills/0", error.Pointer); + Assert.Equal( + "the skill 'warranty-return' is not in the bound skills folder. The folder serves: shipping-claims, warranty-returns.", + error.Message); + Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); + } - [Fact] - public void ValidateSkillReferences_EveryNameServed_DoesNotThrow() - { - const string document = """ + [Fact] + public void ValidateSkillReferences_EveryNameServed_DoesNotThrow() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1622,18 +1627,18 @@ public void ValidateSkillReferences_EveryNameServed_DoesNotThrow() agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); - var served = new HashSet(["warranty-returns"], StringComparer.Ordinal); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + HashSet served = new(["warranty-returns"], StringComparer.Ordinal); - var exception = Record.Exception(() => ConfigurationValidator.ValidateSkillReferences(configuration, served)); + Exception? exception = Record.Exception(() => ConfigurationValidator.ValidateSkillReferences(configuration, served)); - Assert.Null(exception); - } + Assert.Null(exception); + } - [Fact] - public void ValidateSkillReferences_APinnedNameTheFolderDoesNotServe_FailsAtThePinnedSlot() - { - const string document = """ + [Fact] + public void ValidateSkillReferences_APinnedNameTheFolderDoesNotServe_FailsAtThePinnedSlot() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1643,23 +1648,23 @@ public void ValidateSkillReferences_APinnedNameTheFolderDoesNotServe_FailsAtTheP agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); - var served = new HashSet(["warranty-returns"], StringComparer.Ordinal); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + HashSet served = new(["warranty-returns"], StringComparer.Ordinal); - var failure = Assert.Throws( - () => ConfigurationValidator.ValidateSkillReferences(configuration, served)); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationValidator.ValidateSkillReferences(configuration, served)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/agents/items/0/pinned/0", error.Pointer); - Assert.Equal( - "the skill 'openui' is not in the bound skills folder. The folder serves: warranty-returns.", - error.Message); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/agents/items/0/pinned/0", error.Pointer); + Assert.Equal( + "the skill 'openui' is not in the bound skills folder. The folder serves: warranty-returns.", + error.Message); + } - [Fact] - public void ValidateSkillReferences_ASkillBothPinnedAndLoadable_Fails() - { - const string document = """ + [Fact] + public void ValidateSkillReferences_ASkillBothPinnedAndLoadable_Fails() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -1669,26 +1674,26 @@ public void ValidateSkillReferences_ASkillBothPinnedAndLoadable_Fails() agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); - var served = new HashSet(["openui"], StringComparer.Ordinal); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); + HashSet served = new(["openui"], StringComparer.Ordinal); - var failure = Assert.Throws( - () => ConfigurationValidator.ValidateSkillReferences(configuration, served)); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationValidator.ValidateSkillReferences(configuration, served)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/agents/items/0/pinned/0", error.Pointer); - Assert.Equal( - "the skill 'openui' is both pinned and in the skills: list. A pinned skill is already in the prompt, so drop it from skills:.", - error.Message); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/agents/items/0/pinned/0", error.Pointer); + Assert.Equal( + "the skill 'openui' is both pinned and in the skills: list. A pinned skill is already in the prompt, so drop it from skills:.", + error.Message); + } - [Theory] - [InlineData("load_skill")] - [InlineData("read_skill_resource")] - [InlineData("run_skill_script")] - public void ValidateSkillToolNames_AToolIdTheSkillsProviderOwns_FailsNamingIt(string reserved) - { - var document = $$""" + [Theory] + [InlineData("load_skill")] + [InlineData("read_skill_resource")] + [InlineData("run_skill_script")] + public void ValidateSkillToolNames_AToolIdTheSkillsProviderOwns_FailsNamingIt(string reserved) + { + string document = $$""" apiVersion: agentcore/v1 tools: - { id: {{reserved}}, kind: http, request: { method: GET, url: "https://example.test" } } @@ -1700,19 +1705,19 @@ public void ValidateSkillToolNames_AToolIdTheSkillsProviderOwns_FailsNamingIt(st agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - var failure = Assert.Throws( - () => ConfigurationValidator.ValidateSkillToolNames(configuration)); + ConfigurationLoadException failure = Assert.Throws( + () => ConfigurationValidator.ValidateSkillToolNames(configuration)); - var error = Assert.Single(failure.Errors); - Assert.Contains($"the tool id '{reserved}' is reserved", error.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Contains($"the tool id '{reserved}' is reserved", error.Message, StringComparison.Ordinal); + } - [Fact] - public void ValidateSkillToolNames_NoAgentDeclaresSkills_AllowsTheName() - { - const string document = """ + [Fact] + public void ValidateSkillToolNames_NoAgentDeclaresSkills_AllowsTheName() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: load_skill, kind: http, request: { method: GET, url: "https://example.test" } } @@ -1724,81 +1729,82 @@ public void ValidateSkillToolNames_NoAgentDeclaresSkills_AllowsTheName() agent: support """; - var configuration = ConfigurationLoader.LoadYaml(document); + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(document); - var exception = Record.Exception(() => ConfigurationValidator.ValidateSkillToolNames(configuration)); + Exception? exception = Record.Exception(() => ConfigurationValidator.ValidateSkillToolNames(configuration)); - Assert.Null(exception); - } + Assert.Null(exception); + } - /// Walks up from the test binaries to the directory that holds the solution file. - /// The repository root. - private static string RepositoryRoot() - { - var directory = new DirectoryInfo(AppContext.BaseDirectory); - while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + /// Walks up from the test binaries to the directory that holds the solution file. + /// The repository root. + private static string RepositoryRoot() { - directory = directory.Parent; + DirectoryInfo? directory = new(AppContext.BaseDirectory); + while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "AgentCore.sln"))) + { + directory = directory.Parent; + } + + Assert.NotNull(directory); + return directory!.FullName; } - Assert.NotNull(directory); - return directory!.FullName; - } + private static ConfigurationError SingleFor(string yaml, ConfigurationCheck check) + { + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(yaml)); - private static ConfigurationError SingleFor(string yaml, ConfigurationCheck check) - { - var result = ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(yaml)); + return Assert.Single(result.Errors, error => error.Check == check); + } - return Assert.Single(result.Errors, error => error.Check == check); - } + private static IReadOnlyList Evaluate(string yaml, ConfigurationCheck check) + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(yaml); + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(configuration); - private static IReadOnlyList Evaluate(string yaml, ConfigurationCheck check) - { - var configuration = ConfigurationLoader.LoadYaml(yaml); - var result = ConfigurationValidator.Evaluate(configuration); + // Every error the document holds must belong to the check under test. + Assert.All(result.Errors, error => Assert.Equal(check, error.Check)); + return result.Errors; + } - // Every error the document holds must belong to the check under test. - Assert.All(result.Errors, error => Assert.Equal(check, error.Check)); - return result.Errors; - } + /// Writes a document whose sibling guards name enough boolean slots to pass the ceiling. + /// How many boolean slots to declare. 17 slots give 131,072 points. + /// The YAML text. + private static string WideDocument(int slots) + { + StringBuilder text = new(); + _ = text.AppendLine("apiVersion: agentcore/v1"); + _ = text.AppendLine("state:"); + for (int index = 0; index < slots; index++) + { + _ = text.AppendLine(System.Globalization.CultureInfo.InvariantCulture, $" s{index}: {{ type: boolean, default: false, writer: extractor }}"); + } - /// Writes a document whose sibling guards name enough boolean slots to pass the ceiling. - /// How many boolean slots to declare. 17 slots give 131,072 points. - /// The YAML text. - private static string WideDocument(int slots) - { - var text = new StringBuilder(); - text.AppendLine("apiVersion: agentcore/v1"); - text.AppendLine("state:"); - for (var index = 0; index < slots; index++) - { - text.AppendLine(System.Globalization.CultureInfo.InvariantCulture, $" s{index}: {{ type: boolean, default: false, writer: extractor }}"); - } - - text.AppendLine("guards:"); - text.AppendLine(" first: { var: s0 }"); - text.Append(" second: { and: [ { \"!\": { var: s0 } }"); - for (var index = 1; index < slots; index++) - { - text.Append(System.Globalization.CultureInfo.InvariantCulture, $", {{ var: s{index} }}"); - } - - text.AppendLine(" ] }"); - text.AppendLine("agents:"); - text.AppendLine(" items:"); - text.AppendLine(" - { id: greeter }"); - text.AppendLine("entries:"); - text.AppendLine(" main:"); - text.AppendLine(" policy:"); - text.AppendLine(" initial: resolve"); - text.AppendLine(" stages:"); - text.AppendLine(" - id: resolve"); - text.AppendLine(" agent: greeter"); - text.AppendLine(" to:"); - text.AppendLine(" - { stage: close, when: first }"); - text.AppendLine(" - { stage: escalate, when: second }"); - text.AppendLine(" - { id: close, agent: greeter, terminal: true }"); - text.AppendLine(" - { id: escalate, agent: greeter, terminal: true }"); - return text.ToString(); + _ = text.AppendLine("guards:"); + _ = text.AppendLine(" first: { var: s0 }"); + _ = text.Append(" second: { and: [ { \"!\": { var: s0 } }"); + for (int index = 1; index < slots; index++) + { + _ = text.Append(System.Globalization.CultureInfo.InvariantCulture, $", {{ var: s{index} }}"); + } + + _ = text.AppendLine(" ] }"); + _ = text.AppendLine("agents:"); + _ = text.AppendLine(" items:"); + _ = text.AppendLine(" - { id: greeter }"); + _ = text.AppendLine("entries:"); + _ = text.AppendLine(" main:"); + _ = text.AppendLine(" policy:"); + _ = text.AppendLine(" initial: resolve"); + _ = text.AppendLine(" stages:"); + _ = text.AppendLine(" - id: resolve"); + _ = text.AppendLine(" agent: greeter"); + _ = text.AppendLine(" to:"); + _ = text.AppendLine(" - { stage: close, when: first }"); + _ = text.AppendLine(" - { stage: escalate, when: second }"); + _ = text.AppendLine(" - { id: close, agent: greeter, terminal: true }"); + _ = text.AppendLine(" - { id: escalate, agent: greeter, terminal: true }"); + return text.ToString(); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/GuardEvaluatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/GuardEvaluatorTests.cs index 37f72985..07dee209 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/GuardEvaluatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/GuardEvaluatorTests.cs @@ -4,299 +4,300 @@ using AgentCore.Application.Configuration.Validation; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Validation; - -/// -/// The guard evaluator of section 8.4, and the run-time failure row of section 8.7. -/// -public sealed class GuardEvaluatorTests +namespace AgentCore.Application.Tests.Configuration.Validation { - private static readonly string[] OrderingOperators = [">", ">=", "<", "<="]; - - private static readonly string[] NonOrderingOperators = ["===", "!==", "in", "var", "+"]; - - private static readonly Dictionary State = new(StringComparer.Ordinal) - { - ["yes"] = JsonValue.Create(true), - ["no"] = JsonValue.Create(false), - ["turns"] = JsonValue.Create(3), - ["one"] = JsonValue.Create(1), - ["nine"] = JsonValue.Create(9), - ["status"] = JsonValue.Create("shipped"), - ["text"] = JsonValue.Create("abc"), - }; - - [Theory] - [InlineData("""{ "var": "yes" }""", true)] - [InlineData("""{ "var": "no" }""", false)] - [InlineData("""{ "missing": [ "yes" ] }""", false)] - [InlineData("""{ "missing": [ "ghost" ] }""", true)] - [InlineData("""{ "if": [ { "var": "yes" }, true, false ] }""", true)] - [InlineData("""{ "===": [ { "var": "turns" }, 3 ] }""", true)] - [InlineData("""{ "===": [ { "var": "status" }, "shipped" ] }""", true)] - [InlineData("""{ "!==": [ { "var": "turns" }, 4 ] }""", true)] - [InlineData("""{ ">": [ { "var": "turns" }, 2 ] }""", true)] - [InlineData("""{ ">=": [ { "var": "turns" }, 3 ] }""", true)] - [InlineData("""{ "<": [ { "var": "turns" }, 4 ] }""", true)] - [InlineData("""{ "<=": [ { "var": "turns" }, 3 ] }""", true)] - [InlineData("""{ "!": { "var": "no" } }""", true)] - [InlineData("""{ "!!": [ { "var": "yes" } ] }""", true)] - [InlineData("""{ "and": [ { "var": "yes" }, { "!": { "var": "no" } } ] }""", true)] - [InlineData("""{ "or": [ { "var": "no" }, { "var": "yes" } ] }""", true)] - [InlineData("""{ "in": [ { "var": "status" }, [ "shipped", "held" ] ] }""", true)] - [InlineData("""{ "in": [ { "var": "status" }, [ "held" ] ] }""", false)] - [InlineData("""{ ">": [ { "+": [ { "var": "turns" }, 1 ] }, 3 ] }""", true)] - [InlineData("""{ "===": [ { "-": [ { "var": "turns" }, 1 ] }, 2 ] }""", true)] - [InlineData("""{ "===": [ { "*": [ { "var": "turns" }, 2 ] }, 6 ] }""", true)] - [InlineData("""{ "===": [ { "/": [ { "var": "turns" }, 3 ] }, 1 ] }""", true)] - [InlineData("""{ "===": [ { "min": [ 3, 9 ] }, 3 ] }""", true)] - [InlineData("""{ ">": [ { "max": [ 3, 9 ] }, 5 ] }""", true)] - public void EveryAllowedOperator_Evaluates(string rule, bool expected) - { - var evaluator = new GuardEvaluator(new Dictionary(StringComparer.Ordinal)); - - Assert.Equal(expected, evaluator.Evaluate(JsonNode.Parse(rule)!, State)); - } - /// - /// The same twenty operators, each reading at least one slot through var. + /// The guard evaluator of section 8.4, and the run-time failure row of section 8.7. /// - /// - /// A guard reads state, so a literal-only proof proves nothing about the engine a guard meets. - /// The newer JsonLogic.Apply(JsonNode, JsonNode) engine of package version 6.1.0 returns - /// for min and for max as soon as one operand is a - /// var read, so the two rows that name them fail on it and hold on the Rule model. - /// - /// The rule text. - /// What the rule answers against . - [Theory] - [InlineData("""{ "var": "turns" }""", true)] - [InlineData("""{ "missing": [ "turns" ] }""", false)] - [InlineData("""{ "if": [ { "var": "yes" }, { "var": "turns" }, 0 ] }""", true)] - [InlineData("""{ "===": [ { "var": "turns" }, { "var": "turns" } ] }""", true)] - [InlineData("""{ "!==": [ { "var": "turns" }, { "var": "one" } ] }""", true)] - [InlineData("""{ ">": [ { "var": "turns" }, { "var": "one" } ] }""", true)] - [InlineData("""{ ">=": [ { "var": "turns" }, { "var": "turns" } ] }""", true)] - [InlineData("""{ "<": [ { "var": "turns" }, { "var": "nine" } ] }""", true)] - [InlineData("""{ "<=": [ { "var": "turns" }, { "var": "turns" } ] }""", true)] - [InlineData("""{ "!": [ { "var": "no" } ] }""", true)] - [InlineData("""{ "!!": [ { "var": "turns" } ] }""", true)] - [InlineData("""{ "and": [ { "var": "yes" }, { "var": "turns" } ] }""", true)] - [InlineData("""{ "or": [ { "var": "no" }, { "var": "turns" } ] }""", true)] - [InlineData("""{ "in": [ { "var": "status" }, [ "shipped", "held" ] ] }""", true)] - [InlineData("""{ "===": [ { "+": [ { "var": "turns" }, { "var": "one" } ] }, 4 ] }""", true)] - [InlineData("""{ "===": [ { "-": [ { "var": "turns" }, { "var": "one" } ] }, 2 ] }""", true)] - [InlineData("""{ "===": [ { "*": [ { "var": "turns" }, { "var": "nine" } ] }, 27 ] }""", true)] - [InlineData("""{ "===": [ { "/": [ { "var": "nine" }, { "var": "turns" } ] }, 3 ] }""", true)] - [InlineData("""{ "===": [ { "min": [ { "var": "turns" }, { "var": "nine" } ] }, 3 ] }""", true)] - [InlineData("""{ "===": [ { "max": [ { "var": "turns" }, { "var": "nine" } ] }, 9 ] }""", true)] - public void EveryAllowedOperator_EvaluatesWithAVarOperand(string rule, bool expected) + public sealed class GuardEvaluatorTests { - var evaluator = new GuardEvaluator(new Dictionary(StringComparer.Ordinal)); + private static readonly string[] OrderingOperators = [">", ">=", "<", "<="]; - Assert.Equal(expected, evaluator.Evaluate(JsonNode.Parse(rule)!, State)); - } - - [Fact] - public void MinAndMax_ReadASlotRatherThanAnswerNull() - { - // This is the whole point of the engine switch. On the newer engine both rules answer null, - // so both comparisons are false and a guard built on either operator is false at every state. - var evaluator = new GuardEvaluator(new Dictionary(StringComparer.Ordinal)); - - Assert.True(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "min": [ { "var": "turns" }, 9 ] }, 3 ] }""")!, State)); - Assert.True(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "max": [ { "var": "turns" }, 9 ] }, 9 ] }""")!, State)); + private static readonly string[] NonOrderingOperators = ["===", "!==", "in", "var", "+"]; - // The pair proves the rules are not vacuously false, and that they read the slot. - Assert.False(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "min": [ { "var": "turns" }, 9 ] }, 9 ] }""")!, State)); - Assert.False(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "max": [ { "var": "turns" }, 9 ] }, 3 ] }""")!, State)); - } - - [Fact] - public void AGuardThatIsBuiltOnMin_DecidesAStageExit() - { - var guards = new Dictionary(StringComparer.Ordinal) + private static readonly Dictionary State = new(StringComparer.Ordinal) { - ["capped"] = JsonNode.Parse("""{ ">=": [ { "min": [ { "var": "turns" }, 5 ] }, 3 ] }""")!, + ["yes"] = JsonValue.Create(true), + ["no"] = JsonValue.Create(false), + ["turns"] = JsonValue.Create(3), + ["one"] = JsonValue.Create(1), + ["nine"] = JsonValue.Create(9), + ["status"] = JsonValue.Create("shipped"), + ["text"] = JsonValue.Create("abc"), }; - var evaluator = new GuardEvaluator(guards); - - Assert.True(evaluator.Evaluate(GuardReference.FromName("capped"), State)); - } - - [Fact] - public void TheAllowListHoldsExactlyTheTwentyOperatorsOfSectionEightFour() - { - Assert.Equal( - [ - "var", "missing", "if", "===", "!==", ">", ">=", "<", "<=", "!", "!!", - "and", "or", "in", "+", "-", "*", "/", "min", "max", - ], - GuardOperators.Allowed); - - Assert.Equal( - ["==", "!=", "log", "map", "filter", "reduce", "all", "some", "none", "merge", "cat", "substr"], - GuardOperators.Rejected); - - Assert.All(GuardOperators.Rejected, name => Assert.False(GuardOperators.IsAllowed(name))); - Assert.All(GuardOperators.Allowed, name => Assert.False(GuardOperators.IsNamedRejected(name))); - } - - // --------------------------------------------------------------------------------------------- - // An operator name is matched exactly. A table that folded case would let 'VAR' through check 4 - // and then fail at run time, where JsonLogic knows no such operator. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TheOperatorTables_MatchAnOperatorNameCaseSensitively() - { - Assert.True(GuardOperators.IsAllowed("var")); - Assert.False(GuardOperators.IsAllowed("VAR")); - Assert.False(GuardOperators.IsAllowed("Missing")); - - Assert.True(GuardOperators.IsNamedRejected("log")); - Assert.False(GuardOperators.IsNamedRejected("LOG")); - Assert.False(GuardOperators.IsNamedRejected("Filter")); - } - [Fact] - public void TheNumericComparisons_AreTheFourOrderingOperators() - { - Assert.All(OrderingOperators, name => Assert.True(GuardOperators.IsNumericComparison(name))); - Assert.All(NonOrderingOperators, name => Assert.False(GuardOperators.IsNumericComparison(name))); - } + [Theory] + [InlineData(/*lang=json,strict*/ """{ "var": "yes" }""", true)] + [InlineData(/*lang=json,strict*/ """{ "var": "no" }""", false)] + [InlineData(/*lang=json,strict*/ """{ "missing": [ "yes" ] }""", false)] + [InlineData(/*lang=json,strict*/ """{ "missing": [ "ghost" ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "if": [ { "var": "yes" }, true, false ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "var": "turns" }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "var": "status" }, "shipped" ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "!==": [ { "var": "turns" }, 4 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ ">": [ { "var": "turns" }, 2 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ ">=": [ { "var": "turns" }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "<": [ { "var": "turns" }, 4 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "<=": [ { "var": "turns" }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "!": { "var": "no" } }""", true)] + [InlineData(/*lang=json,strict*/ """{ "!!": [ { "var": "yes" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "and": [ { "var": "yes" }, { "!": { "var": "no" } } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "or": [ { "var": "no" }, { "var": "yes" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "in": [ { "var": "status" }, [ "shipped", "held" ] ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "in": [ { "var": "status" }, [ "held" ] ] }""", false)] + [InlineData(/*lang=json,strict*/ """{ ">": [ { "+": [ { "var": "turns" }, 1 ] }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "-": [ { "var": "turns" }, 1 ] }, 2 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "*": [ { "var": "turns" }, 2 ] }, 6 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "/": [ { "var": "turns" }, 3 ] }, 1 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "min": [ 3, 9 ] }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ ">": [ { "max": [ 3, 9 ] }, 5 ] }""", true)] + public void EveryAllowedOperator_Evaluates(string rule, bool expected) + { + GuardEvaluator evaluator = new(new Dictionary(StringComparer.Ordinal)); + + Assert.Equal(expected, evaluator.Evaluate(JsonNode.Parse(rule)!, State)); + } + + /// + /// The same twenty operators, each reading at least one slot through var. + /// + /// + /// A guard reads state, so a literal-only proof proves nothing about the engine a guard meets. + /// The newer JsonLogic.Apply(JsonNode, JsonNode) engine of package version 6.1.0 returns + /// for min and for max as soon as one operand is a + /// var read, so the two rows that name them fail on it and hold on the Rule model. + /// + /// The rule text. + /// What the rule answers against . + [Theory] + [InlineData(/*lang=json,strict*/ """{ "var": "turns" }""", true)] + [InlineData(/*lang=json,strict*/ """{ "missing": [ "turns" ] }""", false)] + [InlineData(/*lang=json,strict*/ """{ "if": [ { "var": "yes" }, { "var": "turns" }, 0 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "var": "turns" }, { "var": "turns" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "!==": [ { "var": "turns" }, { "var": "one" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ ">": [ { "var": "turns" }, { "var": "one" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ ">=": [ { "var": "turns" }, { "var": "turns" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "<": [ { "var": "turns" }, { "var": "nine" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "<=": [ { "var": "turns" }, { "var": "turns" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "!": [ { "var": "no" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "!!": [ { "var": "turns" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "and": [ { "var": "yes" }, { "var": "turns" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "or": [ { "var": "no" }, { "var": "turns" } ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "in": [ { "var": "status" }, [ "shipped", "held" ] ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "+": [ { "var": "turns" }, { "var": "one" } ] }, 4 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "-": [ { "var": "turns" }, { "var": "one" } ] }, 2 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "*": [ { "var": "turns" }, { "var": "nine" } ] }, 27 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "/": [ { "var": "nine" }, { "var": "turns" } ] }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "min": [ { "var": "turns" }, { "var": "nine" } ] }, 3 ] }""", true)] + [InlineData(/*lang=json,strict*/ """{ "===": [ { "max": [ { "var": "turns" }, { "var": "nine" } ] }, 9 ] }""", true)] + public void EveryAllowedOperator_EvaluatesWithAVarOperand(string rule, bool expected) + { + GuardEvaluator evaluator = new(new Dictionary(StringComparer.Ordinal)); - [Fact] - public void TheLooseEqualityRejection_NamesTheReplacement() - { - Assert.Equal("===", GuardOperators.ReplacementFor("==")); - Assert.Equal("!==", GuardOperators.ReplacementFor("!=")); - Assert.Null(GuardOperators.ReplacementFor("map")); - Assert.Contains("'==='", GuardOperators.DescribeRejection("=="), StringComparison.Ordinal); - } + Assert.Equal(expected, evaluator.Evaluate(JsonNode.Parse(rule)!, State)); + } - [Fact] - public void ANamedGuard_ResolvesThroughTheTableTheConstructorTakes() - { - var guards = new Dictionary(StringComparer.Ordinal) + [Fact] + public void MinAndMax_ReadASlotRatherThanAnswerNull() { - ["saidGoodbye"] = JsonNode.Parse("""{ "var": "yes" }""")!, - }; - var evaluator = new GuardEvaluator(guards); + // This is the whole point of the engine switch. On the newer engine both rules answer null, + // so both comparisons are false and a guard built on either operator is false at every state. + GuardEvaluator evaluator = new(new Dictionary(StringComparer.Ordinal)); - Assert.True(evaluator.Evaluate(GuardReference.FromName("saidGoodbye"), State)); - Assert.True(evaluator.TryGetGuard("saidGoodbye", out _)); - } - - [Fact] - public void AGuardNameTheTableDoesNotHold_IsFalse() - { - var evaluator = new GuardEvaluator(new Dictionary(StringComparer.Ordinal)); + Assert.True(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "min": [ { "var": "turns" }, 9 ] }, 3 ] }""")!, State)); + Assert.True(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "max": [ { "var": "turns" }, 9 ] }, 9 ] }""")!, State)); - Assert.False(evaluator.Evaluate(GuardReference.FromName("ghost"), State)); - Assert.False(evaluator.TryGetGuard("ghost", out _)); - } + // The pair proves the rules are not vacuously false, and that they read the slot. + Assert.False(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "min": [ { "var": "turns" }, 9 ] }, 9 ] }""")!, State)); + Assert.False(evaluator.Evaluate(JsonNode.Parse("""{ "===": [ { "max": [ { "var": "turns" }, 9 ] }, 3 ] }""")!, State)); + } - [Fact] - public void AnUnconditionalExit_ResolvesToARuleThatIsAlwaysTrue() - { - var evaluator = new GuardEvaluator(new Dictionary(StringComparer.Ordinal)); + [Fact] + public void AGuardThatIsBuiltOnMin_DecidesAStageExit() + { + Dictionary guards = new(StringComparer.Ordinal) + { + ["capped"] = JsonNode.Parse("""{ ">=": [ { "min": [ { "var": "turns" }, 5 ] }, 3 ] }""")!, + }; + GuardEvaluator evaluator = new(guards); - var rule = evaluator.Resolve(null); + Assert.True(evaluator.Evaluate(GuardReference.FromName("capped"), State)); + } - Assert.NotNull(rule); - Assert.True(evaluator.Evaluate(rule, State)); - } + [Fact] + public void TheAllowListHoldsExactlyTheTwentyOperatorsOfSectionEightFour() + { + Assert.Equal( + [ + "var", "missing", "if", "===", "!==", ">", ">=", "<", "<=", "!", "!!", + "and", "or", "in", "+", "-", "*", "/", "min", "max", + ], + GuardOperators.Allowed); + + Assert.Equal( + ["==", "!=", "log", "map", "filter", "reduce", "all", "some", "none", "merge", "cat", "substr"], + GuardOperators.Rejected); + + Assert.All(GuardOperators.Rejected, name => Assert.False(GuardOperators.IsAllowed(name))); + Assert.All(GuardOperators.Allowed, name => Assert.False(GuardOperators.IsNamedRejected(name))); + } + + // --------------------------------------------------------------------------------------------- + // An operator name is matched exactly. A table that folded case would let 'VAR' through check 4 + // and then fail at run time, where JsonLogic knows no such operator. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TheOperatorTables_MatchAnOperatorNameCaseSensitively() + { + Assert.True(GuardOperators.IsAllowed("var")); + Assert.False(GuardOperators.IsAllowed("VAR")); + Assert.False(GuardOperators.IsAllowed("Missing")); - [Fact] - public void AGuardThatThrowsAtRunTime_IsFalseAndIsReportedOnce() - { - var failures = new List(); - var evaluator = new GuardEvaluator( - new Dictionary(StringComparer.Ordinal), - (description, _) => failures.Add(description)); - - // 'and' is on the allow-list, so check 4 passes the rule. Its argument is not an array, and - // JsonLogic throws while it reads it. Section 8.7 conversations that possible and not a defect. - var rule = JsonNode.Parse("""{ "and": 5 }""")!; - - Assert.False(evaluator.Evaluate(rule, State)); - Assert.False(evaluator.Evaluate(rule, State)); - Assert.Single(failures); - } + Assert.True(GuardOperators.IsNamedRejected("log")); + Assert.False(GuardOperators.IsNamedRejected("LOG")); + Assert.False(GuardOperators.IsNamedRejected("Filter")); + } - [Fact] - public void AGuardThatWillNotParse_NamesTheGuardAndNeverThrowsOutOfTheConstructor() - { - var failures = new List(); - var guards = new Dictionary(StringComparer.Ordinal) + [Fact] + public void TheNumericComparisons_AreTheFourOrderingOperators() { - ["good"] = JsonNode.Parse("""{ "var": "yes" }""")!, + Assert.All(OrderingOperators, name => Assert.True(GuardOperators.IsNumericComparison(name))); + Assert.All(NonOrderingOperators, name => Assert.False(GuardOperators.IsNumericComparison(name))); + } - // 'and' is on the allow-list and its argument is not an array, so the rule does not - // deserialize. The rule now parses while the constructor runs, and section 8.7 keeps the - // process alive: the failure names the guard, reports once, and the guard is false. - ["bad"] = JsonNode.Parse("""{ "and": 5 }""")!, - }; - - var evaluator = new GuardEvaluator(guards, (description, _) => failures.Add(description)); + [Fact] + public void TheLooseEqualityRejection_NamesTheReplacement() + { + Assert.Equal("===", GuardOperators.ReplacementFor("==")); + Assert.Equal("!==", GuardOperators.ReplacementFor("!=")); + Assert.Null(GuardOperators.ReplacementFor("map")); + Assert.Contains("'==='", GuardOperators.DescribeRejection("=="), StringComparison.Ordinal); + } + + [Fact] + public void ANamedGuard_ResolvesThroughTheTableTheConstructorTakes() + { + Dictionary guards = new(StringComparer.Ordinal) + { + ["saidGoodbye"] = JsonNode.Parse("""{ "var": "yes" }""")!, + }; + GuardEvaluator evaluator = new(guards); + + Assert.True(evaluator.Evaluate(GuardReference.FromName("saidGoodbye"), State)); + Assert.True(evaluator.TryGetGuard("saidGoodbye", out _)); + } + + [Fact] + public void AGuardNameTheTableDoesNotHold_IsFalse() + { + GuardEvaluator evaluator = new(new Dictionary(StringComparer.Ordinal)); - Assert.Equal(["bad"], failures); - Assert.False(evaluator.Evaluate(GuardReference.FromName("bad"), State)); - Assert.False(evaluator.Evaluate(GuardReference.FromName("bad"), State)); - Assert.Single(failures); - Assert.True(evaluator.Evaluate(GuardReference.FromName("good"), State)); - } + Assert.False(evaluator.Evaluate(GuardReference.FromName("ghost"), State)); + Assert.False(evaluator.TryGetGuard("ghost", out _)); + } - [Fact] - public void AGuardThatWillNotParse_DoesNotThrowWhenNoHandlerIsGiven() - { - var guards = new Dictionary(StringComparer.Ordinal) + [Fact] + public void AnUnconditionalExit_ResolvesToARuleThatIsAlwaysTrue() { - ["bad"] = JsonNode.Parse("""{ "and": 5 }""")!, - }; + GuardEvaluator evaluator = new(new Dictionary(StringComparer.Ordinal)); - var evaluator = new GuardEvaluator(guards); + JsonNode? rule = evaluator.Resolve(null); - Assert.False(evaluator.Evaluate(GuardReference.FromName("bad"), State)); - } + Assert.NotNull(rule); + Assert.True(evaluator.Evaluate(rule, State)); + } - [Fact] - public void AnInlineRule_EvaluatesWithoutTheTable() - { - var evaluator = new GuardEvaluator(new Dictionary(StringComparer.Ordinal)); - var guard = GuardReference.FromRule(JsonNode.Parse("""{ "!": { "var": "no" } }""")!); + [Fact] + public void AGuardThatThrowsAtRunTime_IsFalseAndIsReportedOnce() + { + List failures = []; + GuardEvaluator evaluator = new( + new Dictionary(StringComparer.Ordinal), + (description, _) => failures.Add(description)); + + // 'and' is on the allow-list, so check 4 passes the rule. Its argument is not an array, and + // JsonLogic throws while it reads it. Section 8.7 conversations that possible and not a defect. + JsonNode rule = JsonNode.Parse("""{ "and": 5 }""")!; + + Assert.False(evaluator.Evaluate(rule, State)); + Assert.False(evaluator.Evaluate(rule, State)); + _ = Assert.Single(failures); + } + + [Fact] + public void AGuardThatWillNotParse_NamesTheGuardAndNeverThrowsOutOfTheConstructor() + { + List failures = []; + Dictionary guards = new(StringComparer.Ordinal) + { + ["good"] = JsonNode.Parse("""{ "var": "yes" }""")!, + + // 'and' is on the allow-list and its argument is not an array, so the rule does not + // deserialize. The rule now parses while the constructor runs, and section 8.7 keeps the + // process alive: the failure names the guard, reports once, and the guard is false. + ["bad"] = JsonNode.Parse("""{ "and": 5 }""")!, + }; + + GuardEvaluator evaluator = new(guards, (description, _) => failures.Add(description)); + + Assert.Equal(["bad"], failures); + Assert.False(evaluator.Evaluate(GuardReference.FromName("bad"), State)); + Assert.False(evaluator.Evaluate(GuardReference.FromName("bad"), State)); + _ = Assert.Single(failures); + Assert.True(evaluator.Evaluate(GuardReference.FromName("good"), State)); + } + + [Fact] + public void AGuardThatWillNotParse_DoesNotThrowWhenNoHandlerIsGiven() + { + Dictionary guards = new(StringComparer.Ordinal) + { + ["bad"] = JsonNode.Parse("""{ "and": 5 }""")!, + }; - Assert.True(evaluator.Evaluate(guard, State)); - } + GuardEvaluator evaluator = new(guards); - [Fact] - public void TheExampleGuards_EvaluateAgainstTheDeclaredState() - { - var configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var evaluator = new GuardEvaluator(configuration.Guards); + Assert.False(evaluator.Evaluate(GuardReference.FromName("bad"), State)); + } - var state = new Dictionary(StringComparer.Ordinal) + [Fact] + public void AnInlineRule_EvaluatesWithoutTheTable() { - ["callerAskedForHuman"] = JsonValue.Create(false), - ["callerSaidGoodbye"] = JsonValue.Create(false), - ["machineIdentified"] = JsonValue.Create(true), - ["resolved"] = JsonValue.Create(false), - ["failedResolveTurns"] = JsonValue.Create(0), - [ReservedStateSlots.Stage] = JsonValue.Create("identify"), - }; + GuardEvaluator evaluator = new(new Dictionary(StringComparer.Ordinal)); + GuardReference guard = GuardReference.FromRule(JsonNode.Parse("""{ "!": { "var": "no" } }""")!); - Assert.True(evaluator.Evaluate(GuardReference.FromName("identified"), state)); - Assert.False(evaluator.Evaluate(GuardReference.FromName("saidGoodbye"), state)); - Assert.False(evaluator.Evaluate(GuardReference.FromName("wantsHuman"), state)); - Assert.False(evaluator.Evaluate(GuardReference.FromName("humanOrExhausted"), state)); - } + Assert.True(evaluator.Evaluate(guard, State)); + } - [Fact] - public void BuildData_ClonesEveryValueSoNoNodeKeepsASecondParent() - { - var data = GuardEvaluator.BuildData(State); + [Fact] + public void TheExampleGuards_EvaluateAgainstTheDeclaredState() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + GuardEvaluator evaluator = new(configuration.Guards); + + Dictionary state = new(StringComparer.Ordinal) + { + ["callerAskedForHuman"] = JsonValue.Create(false), + ["callerSaidGoodbye"] = JsonValue.Create(false), + ["machineIdentified"] = JsonValue.Create(true), + ["resolved"] = JsonValue.Create(false), + ["failedResolveTurns"] = JsonValue.Create(0), + [ReservedStateSlots.Stage] = JsonValue.Create("identify"), + }; + + Assert.True(evaluator.Evaluate(GuardReference.FromName("identified"), state)); + Assert.False(evaluator.Evaluate(GuardReference.FromName("saidGoodbye"), state)); + Assert.False(evaluator.Evaluate(GuardReference.FromName("wantsHuman"), state)); + Assert.False(evaluator.Evaluate(GuardReference.FromName("humanOrExhausted"), state)); + } + + [Fact] + public void BuildData_ClonesEveryValueSoNoNodeKeepsASecondParent() + { + JsonObject data = GuardEvaluator.BuildData(State); - Assert.NotSame(State["yes"], data["yes"]); - Assert.True(JsonNode.DeepEquals(State["yes"], data["yes"])); + Assert.NotSame(State["yes"], data["yes"]); + Assert.True(JsonNode.DeepEquals(State["yes"], data["yes"])); + } } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs index 9cef85d2..d4fc5a5e 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs @@ -1,108 +1,120 @@ +using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Validation; - -/// -/// The resolve block a filterable facet may carry: it names the lookup the model runs to find -/// an exact value, so every part of it must point at something real. -/// -public sealed class KnowledgeFilterValidatorTests +namespace AgentCore.Application.Tests.Configuration.Validation { - private const string Pointer = "/providers/knowledge/scope/filterable/1/resolve"; - - [Fact] - public void Resolve_ViaAnotherFilterableFacet_Passes() + /// + /// The resolve block a filterable facet may carry: it names the lookup the model runs to find + /// an exact value, so every part of it must point at something real. + /// + public sealed class KnowledgeFilterValidatorTests { - var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("lookup")))); - - Assert.Empty(result.Errors); - } + private const string Pointer = "/providers/knowledge/scope/filterable/1/resolve"; - [Fact] - public void Resolve_ViaAKeyNobodyDeclared_Fails() - { - var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("family")))); + [Fact] + public void Resolve_ViaAnotherFilterableFacet_Passes() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("lookup")))); - var error = Assert.Single(result.Errors); - Assert.Equal(Pointer + "/via/key", error.Pointer); - Assert.Contains("family", error.Message, StringComparison.Ordinal); - } + Assert.Empty(result.Errors); + } - [Fact] - public void Resolve_ViaItself_Fails() - { - var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("model")))); + [Fact] + public void Resolve_ViaAKeyNobodyDeclared_Fails() + { + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("family")))); - var error = Assert.Single(result.Errors); - Assert.Equal(Pointer + "/via/key", error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal(Pointer + "/via/key", error.Pointer); + Assert.Contains("family", error.Message, StringComparison.Ordinal); + } - [Fact] - public void Resolve_ViaAFacetThatResolvesToo_Fails() - { - var lookup = Lookup() with + [Fact] + public void Resolve_ViaItself_Fails() { - Resolve = new() - { - Via = new() { Key = "model", Value = "x" }, - Query = "q", - Read = "r", - }, - }; - - var result = ConfigurationValidator.EvaluateStructure(Filterable(lookup, Model(Via("lookup")))); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("model")))); - Assert.Contains(result.Errors, e => e.Pointer == Pointer + "/via/key"); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal(Pointer + "/via/key", error.Pointer); + } - [Theory] - [InlineData("value", "/via/value")] - [InlineData("query", "/query")] - [InlineData("read", "/read")] - public void Resolve_ABlankPart_Fails(string blank, string suffix) - { - var resolve = Via("lookup") with + [Fact] + public void Resolve_ViaAFacetThatResolvesToo_Fails() + { + KnowledgeFilterableFacetConfiguration lookup = Lookup() with + { + Resolve = new() + { + Via = new() { Key = "model", Value = "x" }, + Query = "q", + Read = "r", + }, + }; + + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(Filterable(lookup, Model(Via("lookup")))); + + Assert.Contains(result.Errors, e => e.Pointer == Pointer + "/via/key"); + } + + [Theory] + [InlineData("value", "/via/value")] + [InlineData("query", "/query")] + [InlineData("read", "/read")] + public void Resolve_ABlankPart_Fails(string blank, string suffix) { - Via = new() { Key = "lookup", Value = blank == "value" ? " " : "model-numbers" }, - Query = blank == "query" ? " " : " model number", - Read = blank == "read" ? " " : "the Tag column", - }; + KnowledgeFacetResolveConfiguration resolve = Via("lookup") with + { + Via = new() { Key = "lookup", Value = blank == "value" ? " " : "model-numbers" }, + Query = blank == "query" ? " " : " model number", + Read = blank == "read" ? " " : "the Tag column", + }; - var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(resolve))); + ConfigurationValidationResult result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(resolve))); - var error = Assert.Single(result.Errors); - Assert.Equal(Pointer + suffix, error.Pointer); - } + ConfigurationError error = Assert.Single(result.Errors); + Assert.Equal(Pointer + suffix, error.Pointer); + } - private static KnowledgeFacetResolveConfiguration Via(string key) => new() - { - Via = new() { Key = key, Value = "model-numbers" }, - Query = " model number", - Read = "the Tag column of the row for the person's year", - }; + private static KnowledgeFacetResolveConfiguration Via(string key) + { + return new() + { + Via = new() { Key = key, Value = "model-numbers" }, + Query = " model number", + Read = "the Tag column of the row for the person's year", + }; + } - private static KnowledgeFilterableFacetConfiguration Lookup() => - new() { Key = "lookup", Description = "The only value is model-numbers." }; + private static KnowledgeFilterableFacetConfiguration Lookup() + { + return new() { Key = "lookup", Description = "The only value is model-numbers." }; + } - private static KnowledgeFilterableFacetConfiguration Model(KnowledgeFacetResolveConfiguration resolve) => - new() { Key = "model", Description = "One machine and its year, as one tag.", Resolve = resolve }; + private static KnowledgeFilterableFacetConfiguration Model(KnowledgeFacetResolveConfiguration resolve) + { + return new() { Key = "model", Description = "One machine and its year, as one tag.", Resolve = resolve }; + } - private static AgentCoreConfiguration Filterable(params KnowledgeFilterableFacetConfiguration[] facets) => new() - { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [new AgentConfiguration { Id = "planner" }] }, - Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "planner" } }, - Providers = new() + private static AgentCoreConfiguration Filterable(params KnowledgeFilterableFacetConfiguration[] facets) { - Knowledge = new() + return new() { - Kind = "qdrant", - Collection = "kb", - Fields = new() { Body = "text" }, - Scope = new() { Template = "facets.{key}", Filterable = facets }, - }, - }, - }; + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [new AgentConfiguration { Id = "planner" }] }, + Entries = new Dictionary { ["main"] = new EntryConfiguration { Agent = "planner" } }, + Providers = new() + { + Knowledge = new() + { + Kind = "qdrant", + Collection = "kb", + Fields = new() { Body = "text" }, + Scope = new() { Template = "facets.{key}", Filterable = facets }, + }, + }, + }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs index ef85943e..787f7fcd 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs @@ -2,57 +2,67 @@ using AgentCore.Application.Configuration.Validation; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Validation; - -/// -/// Check 9 over reasoningEffort and temperature. -/// -/// -/// The vendor answers 400 to the pair, and its message names only temperature. These tests -/// pin the load-time error instead, because it names both keys and points at the one the author -/// has to change. -/// -public sealed class ReasoningTemperatureCheckTests +namespace AgentCore.Application.Tests.Configuration.Validation { - [Fact] - public void AReasoningEntryWithATemperature_FailsAndNamesBothKeys() + /// + /// Check 9 over reasoningEffort and temperature. + /// + /// + /// The vendor answers 400 to the pair, and its message names only temperature. These tests + /// pin the load-time error instead, because it names both keys and points at the one the author + /// has to change. + /// + public sealed class ReasoningTemperatureCheckTests { - var error = Assert.Single(Evaluate(Document("low", "temperature: 0.2"))); + [Fact] + public void AReasoningEntryWithATemperature_FailsAndNamesBothKeys() + { + ConfigurationError error = Assert.Single(Evaluate(Document("low", "temperature: 0.2"))); - Assert.Equal("/agents/items/1/model/temperature", error.Pointer); - Assert.Contains("temperature 0.2", error.Message, StringComparison.Ordinal); - Assert.Contains("reasoningEffort 'low'", error.Message, StringComparison.Ordinal); - Assert.Contains("'reply'", error.Message, StringComparison.Ordinal); - } + Assert.Equal("/agents/items/1/model/temperature", error.Pointer); + Assert.Contains("temperature 0.2", error.Message, StringComparison.Ordinal); + Assert.Contains("reasoningEffort 'low'", error.Message, StringComparison.Ordinal); + Assert.Contains("'reply'", error.Message, StringComparison.Ordinal); + } - [Theory] - [InlineData("minimal")] - [InlineData("low")] - [InlineData("medium")] - [InlineData("high")] - public void EveryEffortAboveNone_RefusesATemperatureOtherThanOne(string effort) - => Assert.Single(Evaluate(Document(effort, "temperature: 0.0"))); + [Theory] + [InlineData("minimal")] + [InlineData("low")] + [InlineData("medium")] + [InlineData("high")] + public void EveryEffortAboveNone_RefusesATemperatureOtherThanOne(string effort) + { + _ = Assert.Single(Evaluate(Document(effort, "temperature: 0.0"))); + } - [Fact] - public void TheOneTemperatureAReasoningEntryAccepts_Passes() - => Assert.Empty(Evaluate(Document("high", "temperature: 1.0"))); + [Fact] + public void TheOneTemperatureAReasoningEntryAccepts_Passes() + { + Assert.Empty(Evaluate(Document("high", "temperature: 1.0"))); + } - [Fact] - public void AReasoningEntryWithNoTemperatureAtAll_Passes() - => Assert.Empty(Evaluate(Document("high", null))); + [Fact] + public void AReasoningEntryWithNoTemperatureAtAll_Passes() + { + Assert.Empty(Evaluate(Document("high", null))); + } - [Fact] - public void AnEntryThatDoesNotReason_LeavesTemperatureFree() - => Assert.Empty(Evaluate(Document("none", "temperature: 0.2"))); + [Fact] + public void AnEntryThatDoesNotReason_LeavesTemperatureFree() + { + Assert.Empty(Evaluate(Document("none", "temperature: 0.2"))); + } - [Fact] - public void AnEntryThatNamesNoEffortAtAll_LeavesTemperatureFree() - => Assert.Empty(Evaluate(Document(null, "temperature: 0.2"))); + [Fact] + public void AnEntryThatNamesNoEffortAtAll_LeavesTemperatureFree() + { + Assert.Empty(Evaluate(Document(null, "temperature: 0.2"))); + } - [Fact] - public void TheEffortOfAnotherEntry_DoesNotReachThisReference() - { - const string document = """ + [Fact] + public void TheEffortOfAnotherEntry_DoesNotReachThisReference() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -70,13 +80,13 @@ public void TheEffortOfAnotherEntry_DoesNotReachThisReference() - { kind: openai, model: gpt-4.1-mini, as: fill } """; - Assert.Empty(Evaluate(document)); - } + Assert.Empty(Evaluate(document)); + } - [Fact] - public void ATitlerAndAToolAndTheAgentDefaults_AreCheckedToo() - { - const string document = """ + [Fact] + public void ATitlerAndAToolAndTheAgentDefaults_AreCheckedToo() + { + const string document = """ apiVersion: agentcore/v1 tools: - { id: search, kind: builtin, uses: web.search, model: { ref: reply, temperature: 0.2 } } @@ -99,28 +109,29 @@ public void ATitlerAndAToolAndTheAgentDefaults_AreCheckedToo() agent: greeter """; - Assert.Equal( - ["/agents/defaults/model/temperature", "/titler/model/temperature", "/tools/0/model/temperature"], - Evaluate(document).Select(static error => error.Pointer).Order(StringComparer.Ordinal).ToArray()); - } + Assert.Equal( + ["/agents/defaults/model/temperature", "/titler/model/temperature", "/tools/0/model/temperature"], + [.. Evaluate(document).Select(static error => error.Pointer).Order(StringComparer.Ordinal)]); + } - /// Runs the whole validator and keeps the errors of check 9 only. - /// The document. - /// The errors this check raised. - private static IReadOnlyList Evaluate(string yaml) - { - var result = ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(yaml)); + /// Runs the whole validator and keeps the errors of check 9 only. + /// The document. + /// The errors this check raised. + private static IReadOnlyList Evaluate(string yaml) + { + ConfigurationValidationResult result = ConfigurationValidator.Evaluate(ConfigurationLoader.LoadYaml(yaml)); - Assert.All(result.Errors, error => Assert.Equal(ConfigurationCheck.ValueRange, error.Check)); - return result.Errors; - } + Assert.All(result.Errors, error => Assert.Equal(ConfigurationCheck.ValueRange, error.Check)); + return result.Errors; + } - /// Writes one agent that points at one provider entry. - /// The entry's reasoningEffort, or to omit it. - /// The reference's temperature: line, or to omit it. - /// The YAML text. - private static string Document(string? effort, string? temperature) - => $$""" + /// Writes one agent that points at one provider entry. + /// The entry's reasoningEffort, or to omit it. + /// The reference's temperature: line, or to omit it. + /// The YAML text. + private static string Document(string? effort, string? temperature) + { + return $$""" apiVersion: agentcore/v1 agents: items: @@ -143,4 +154,6 @@ private static string Document(string? effort, string? temperature) as: reply {{(effort is null ? "" : $"reasoningEffort: {effort}")}} """; + } + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs index fc939d58..8863f86d 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs @@ -3,43 +3,45 @@ using AgentCore.Application.Configuration.Validation; using Xunit; -namespace AgentCore.Application.Tests.Configuration.Validation; - -/// -/// The state-domain enumeration of check 5, section 8.5. -/// -public sealed class StateDomainTests +namespace AgentCore.Application.Tests.Configuration.Validation { - [Fact] - public void Points_EnumSlotWithNoDefault_IncludesTheUnfilledPoint() + /// + /// The state-domain enumeration of check 5, section 8.5. + /// + public sealed class StateDomainTests { - AgentCoreConfiguration configuration = new() + [Fact] + public void Points_EnumSlotWithNoDefault_IncludesTheUnfilledPoint() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - State = new Dictionary(StringComparer.Ordinal) + AgentCoreConfiguration configuration = new() { - ["applies_to"] = new() + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + State = new Dictionary(StringComparer.Ordinal) { - Type = StateSlotType.String, - Writer = StateWriter.Extractor, - EnumValues = [JsonValue.Create("f63")!, JsonValue.Create("f65")!], + ["applies_to"] = new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [JsonValue.Create("f63")!, JsonValue.Create("f65")!], + }, }, - }, - }; + }; - var points = Points(configuration, "applies_to"); + IReadOnlyList points = Points(configuration, "applies_to"); - Assert.Contains(points, point => point is null); - Assert.Equal(3, points.Count); - } + Assert.Contains(points, point => point is null); + Assert.Equal(3, points.Count); + } - private static IReadOnlyList Points(AgentCoreConfiguration configuration, string slotName) - { - var facts = new GuardRuleFacts(); - facts.Collect(new JsonObject { ["var"] = slotName }); + private static IReadOnlyList Points(AgentCoreConfiguration configuration, string slotName) + { + GuardRuleFacts facts = new(); + facts.Collect(new JsonObject { ["var"] = slotName }); - var domains = StateDomain.Build(facts, configuration.State, new Dictionary(StringComparer.Ordinal)); - return domains.Single(domain => domain.Name == slotName).Points; + List domains = StateDomain.Build(facts, configuration.State, new Dictionary(StringComparer.Ordinal)); + return domains.Single(domain => domain.Name == slotName).Points; + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs b/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs index b0012c2a..0fd89809 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ChatConversationTitlerTests.cs @@ -5,252 +5,261 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// Making a conversation's title from its words. -public sealed class ChatConversationTitlerTests +namespace AgentCore.Application.Tests.Conversation { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task GenerateAsync_AConversationWithWords_StreamsThePiecesAndStoresTheWhole() + /// Making a conversation's title from its words. + public sealed class ChatConversationTitlerTests { - // Arrange - var (titler, conversations) = await BuildAsync("A squeaky ", "belt"); + private static CancellationToken Token => TestContext.Current.CancellationToken; - // Act - var pieces = await CollectAsync(titler.GenerateAsync("c1", Token)); + [Fact] + public async Task GenerateAsync_AConversationWithWords_StreamsThePiecesAndStoresTheWhole() + { + // Arrange + (ChatConversationTitler? titler, InMemoryConversationStore? conversations) = await BuildAsync("A squeaky ", "belt"); - // Assert - Assert.Equal(["A squeaky ", "belt"], pieces); - Assert.Equal("A squeaky belt", (await conversations.GetAsync("c1", Token))!.Title); - } + // Act + List pieces = await CollectAsync(titler.GenerateAsync("c1", Token)); - [Fact] - public async Task GenerateAsync_AConversationWithNoWords_YieldsNothingAndLeavesTheTitleAlone() - { - // Arrange - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - await conversations.RenameAsync("c1", "kept", Token); - ChatConversationTitler titler = new(conversations, new StubChatClient("ignored")); - - // Act - var pieces = await CollectAsync(titler.GenerateAsync("c1", Token)); - - // Assert - Assert.Empty(pieces); - Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); - } - - [Fact] - public async Task GenerateAsync_StoppedPartWay_LeavesTheTitleAlone() - { - // Arrange - var (titler, conversations) = await BuildAsync("A squeaky ", "belt"); - await conversations.RenameAsync("c1", "kept", Token); + // Assert + Assert.Equal(["A squeaky ", "belt"], pieces); + Assert.Equal("A squeaky belt", (await conversations.GetAsync("c1", Token))!.Title); + } - // Act - await foreach (var _ in titler.GenerateAsync("c1", Token)) + [Fact] + public async Task GenerateAsync_AConversationWithNoWords_YieldsNothingAndLeavesTheTitleAlone() { - break; + // Arrange + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + await conversations.RenameAsync("c1", "kept", Token); + ChatConversationTitler titler = new(conversations, new StubChatClient("ignored")); + + // Act + List pieces = await CollectAsync(titler.GenerateAsync("c1", Token)); + + // Assert + Assert.Empty(pieces); + Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); } - // Assert - Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); - } - - [Fact] - public async Task GenerateAsync_OneTurnWritingManyMessages_SendsOnlyTheNewestSix() - { - // Arrange: the store reads whole turns, so one wide turn hands back more than six rows. - // The cut is by message, not by turn. - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - await conversations.AppendAsync( - "c1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "early"), "m0"), - .. Enumerable.Range(1, 7).Select(n => new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, $"m{n}"), $"m{n}")), - ], - cancellationToken: Token); - StubChatClient client = new("title"); - ChatConversationTitler titler = new(conversations, client); - - // Act - await CollectAsync(titler.GenerateAsync("c1", Token)); - - // Assert - var transcript = Assert.Single(client.Seen, message => message.Role == ChatRole.User).Text; - Assert.Equal("user: m2\nuser: m3\nuser: m4\nuser: m5\nuser: m6\nuser: m7\n", transcript.ReplaceLineEndings("\n")); - } + [Fact] + public async Task GenerateAsync_StoppedPartWay_LeavesTheTitleAlone() + { + // Arrange + (ChatConversationTitler? titler, InMemoryConversationStore? conversations) = await BuildAsync("A squeaky ", "belt"); + await conversations.RenameAsync("c1", "kept", Token); - [Fact] - public async Task GenerateFromAsync_MessagesFromTheCaller_StreamsThePiecesAndStoresTheWhole() - { - // Arrange - // The conversation holds no messages at all, so a title here can only have come from the caller's. - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - ChatConversationTitler titler = new(conversations, new StubChatClient("A squeaky ", "belt")); - - // Act - var pieces = await CollectAsync(titler.GenerateFromAsync("c1", Said("my belt squeaks"), Token)); - - // Assert - Assert.Equal(["A squeaky ", "belt"], pieces); - Assert.Equal("A squeaky belt", (await conversations.GetAsync("c1", Token))!.Title); - } + // Act + await foreach (string _ in titler.GenerateAsync("c1", Token)) + { + break; + } - [Fact] - public async Task GenerateFromAsync_NoMessagesFromTheCaller_YieldsNothingAndLeavesTheTitleAlone() - { - // Arrange - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - await conversations.RenameAsync("c1", "kept", Token); - ChatConversationTitler titler = new(conversations, new StubChatClient("ignored")); - - // Act - var pieces = await CollectAsync(titler.GenerateFromAsync("c1", [], Token)); - - // Assert - Assert.Empty(pieces); - Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); - } + // Assert + Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); + } - [Fact] - public async Task GenerateFromAsync_StoppedPartWay_LeavesTheTitleAlone() - { - // Arrange - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - await conversations.RenameAsync("c1", "kept", Token); - ChatConversationTitler titler = new(conversations, new StubChatClient("A squeaky ", "belt")); - - // Act - await foreach (var _ in titler.GenerateFromAsync("c1", Said("my belt squeaks"), Token)) + [Fact] + public async Task GenerateAsync_OneTurnWritingManyMessages_SendsOnlyTheNewestSix() { - break; + // Arrange: the store reads whole turns, so one wide turn hands back more than six rows. + // The cut is by message, not by turn. + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + _ = await conversations.AppendAsync( + "c1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "early"), "m0"), + .. Enumerable.Range(1, 7).Select(n => new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, $"m{n}"), $"m{n}")), + ], + cancellationToken: Token); + StubChatClient client = new("title"); + ChatConversationTitler titler = new(conversations, client); + + // Act + _ = await CollectAsync(titler.GenerateAsync("c1", Token)); + + // Assert + string transcript = Assert.Single(client.Seen, message => message.Role == ChatRole.User).Text; + Assert.Equal("user: m2\nuser: m3\nuser: m4\nuser: m5\nuser: m6\nuser: m7\n", transcript.ReplaceLineEndings("\n")); } - // Assert - Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); - } - - [Fact] - public async Task GenerateFromAsync_AnUnknownConversation_YieldsNothingAndNeverAsksTheModel() - { - // Arrange - InMemoryConversationStore conversations = new(); - StubChatClient client = new("A squeaky belt"); - ChatConversationTitler titler = new(conversations, client); + [Fact] + public async Task GenerateFromAsync_MessagesFromTheCaller_StreamsThePiecesAndStoresTheWhole() + { + // Arrange + // The conversation holds no messages at all, so a title here can only have come from the caller's. + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + ChatConversationTitler titler = new(conversations, new StubChatClient("A squeaky ", "belt")); + + // Act + List pieces = await CollectAsync(titler.GenerateFromAsync("c1", Said("my belt squeaks"), Token)); + + // Assert + Assert.Equal(["A squeaky ", "belt"], pieces); + Assert.Equal("A squeaky belt", (await conversations.GetAsync("c1", Token))!.Title); + } - // Act - var pieces = await CollectAsync(titler.GenerateFromAsync("missing", Said("my belt squeaks"), Token)); + [Fact] + public async Task GenerateFromAsync_NoMessagesFromTheCaller_YieldsNothingAndLeavesTheTitleAlone() + { + // Arrange + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + await conversations.RenameAsync("c1", "kept", Token); + ChatConversationTitler titler = new(conversations, new StubChatClient("ignored")); + + // Act + List pieces = await CollectAsync(titler.GenerateFromAsync("c1", [], Token)); + + // Assert + Assert.Empty(pieces); + Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); + } - // Assert - Assert.Empty(pieces); - Assert.Empty(client.Seen); - } + [Fact] + public async Task GenerateFromAsync_StoppedPartWay_LeavesTheTitleAlone() + { + // Arrange + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + await conversations.RenameAsync("c1", "kept", Token); + ChatConversationTitler titler = new(conversations, new StubChatClient("A squeaky ", "belt")); + + // Act + await foreach (string _ in titler.GenerateFromAsync("c1", Said("my belt squeaks"), Token)) + { + break; + } - [Fact] - public async Task GenerateFromAsync_MoreMessagesThanTheCap_SendsOnlyTheFirstSix() - { - // Arrange - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - StubChatClient client = new("A squeaky belt"); - ChatConversationTitler titler = new(conversations, client); - List many = [.. Enumerable.Range(0, 9).Select(n => new ChatMessage(ChatRole.User, $"m{n}"))]; - - // Act - await CollectAsync(titler.GenerateFromAsync("c1", many, Token)); - - // Assert - // The instruction is the system message; the caller's words are folded into the one user message. - var transcript = Assert.Single(client.Seen, message => message.Role == ChatRole.User).Text; - Assert.Equal("user: m0\nuser: m1\nuser: m2\nuser: m3\nuser: m4\nuser: m5\n", transcript.ReplaceLineEndings("\n")); - } + // Assert + Assert.Equal("kept", (await conversations.GetAsync("c1", Token))!.Title); + } - [Fact] - public async Task GenerateFromAsync_Always_SendsTheInstructionAsTheSystemMessageAndTheWordsAsTheUser() - { - // Arrange - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - StubChatClient client = new("A squeaky belt"); - ChatConversationTitler titler = new(conversations, client); - - // Act - await CollectAsync(titler.GenerateFromAsync("c1", Said("my belt squeaks"), Token)); - - // Assert - Assert.Collection( - client.Seen, - message => Assert.Equal(ChatRole.System, message.Role), - message => - { - Assert.Equal(ChatRole.User, message.Role); - Assert.Equal("user: my belt squeaks", message.Text.Trim()); - }); - } + [Fact] + public async Task GenerateFromAsync_AnUnknownConversation_YieldsNothingAndNeverAsksTheModel() + { + // Arrange + InMemoryConversationStore conversations = new(); + StubChatClient client = new("A squeaky belt"); + ChatConversationTitler titler = new(conversations, client); - private static List Said(string words) => [new ChatMessage(ChatRole.User, words)]; + // Act + List pieces = await CollectAsync(titler.GenerateFromAsync("missing", Said("my belt squeaks"), Token)); - private static async Task> CollectAsync(IAsyncEnumerable stream) - { - List pieces = []; + // Assert + Assert.Empty(pieces); + Assert.Empty(client.Seen); + } - await foreach (var piece in stream) + [Fact] + public async Task GenerateFromAsync_MoreMessagesThanTheCap_SendsOnlyTheFirstSix() { - pieces.Add(piece); + // Arrange + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + StubChatClient client = new("A squeaky belt"); + ChatConversationTitler titler = new(conversations, client); + List many = [.. Enumerable.Range(0, 9).Select(n => new ChatMessage(ChatRole.User, $"m{n}"))]; + + // Act + _ = await CollectAsync(titler.GenerateFromAsync("c1", many, Token)); + + // Assert + // The instruction is the system message; the caller's words are folded into the one user message. + string transcript = Assert.Single(client.Seen, message => message.Role == ChatRole.User).Text; + Assert.Equal("user: m0\nuser: m1\nuser: m2\nuser: m3\nuser: m4\nuser: m5\n", transcript.ReplaceLineEndings("\n")); } - return pieces; - } + [Fact] + public async Task GenerateFromAsync_Always_SendsTheInstructionAsTheSystemMessageAndTheWordsAsTheUser() + { + // Arrange + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + StubChatClient client = new("A squeaky belt"); + ChatConversationTitler titler = new(conversations, client); + + // Act + _ = await CollectAsync(titler.GenerateFromAsync("c1", Said("my belt squeaks"), Token)); + + // Assert + Assert.Collection( + client.Seen, + message => Assert.Equal(ChatRole.System, message.Role), + message => + { + Assert.Equal(ChatRole.User, message.Role); + Assert.Equal("user: my belt squeaks", message.Text.Trim()); + }); + } - private static async Task<(ChatConversationTitler Titler, InMemoryConversationStore Conversations)> BuildAsync(params string[] pieces) - { - InMemoryConversationStore conversations = new(); - await conversations.CreateAsync("c1", Token); - await conversations.AppendAsync( - "c1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "my belt squeaks"), "m0")], - cancellationToken: Token); - - return (new ChatConversationTitler(conversations, new StubChatClient(pieces)), conversations); - } + private static List Said(string words) + { + return [new ChatMessage(ChatRole.User, words)]; + } - private sealed class StubChatClient(params string[] pieces) : IChatClient - { - public List Seen { get; } = []; - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) => - throw new NotSupportedException("The titler streams."); - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + private static async Task> CollectAsync(IAsyncEnumerable stream) { - Seen.AddRange(messages); + List pieces = []; - foreach (var piece in pieces) + await foreach (string piece in stream) { - cancellationToken.ThrowIfCancellationRequested(); - yield return new ChatResponseUpdate(ChatRole.Assistant, piece); - await Task.Yield(); + pieces.Add(piece); } + + return pieces; } - public object? GetService(Type serviceType, object? serviceKey = null) => null; + private static async Task<(ChatConversationTitler Titler, InMemoryConversationStore Conversations)> BuildAsync(params string[] pieces) + { + InMemoryConversationStore conversations = new(); + _ = await conversations.CreateAsync("c1", Token); + _ = await conversations.AppendAsync( + "c1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "my belt squeaks"), "m0")], + cancellationToken: Token); + + return (new ChatConversationTitler(conversations, new StubChatClient(pieces)), conversations); + } - public void Dispose() + private sealed class StubChatClient(params string[] pieces) : IChatClient { + public List Seen { get; } = []; + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException("The titler streams."); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + Seen.AddRange(messages); + + foreach (string piece in pieces) + { + cancellationToken.ThrowIfCancellationRequested(); + yield return new ChatResponseUpdate(ChatRole.Assistant, piece); + await Task.Yield(); + } + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationChannelTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationChannelTests.cs index 3ba30994..1a3dd4e4 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationChannelTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationChannelTests.cs @@ -2,70 +2,79 @@ using AgentCore.Application.Conversation; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// -/// The channel pair, including the case where one object fills both slots. -/// -public sealed class ConversationChannelTests +namespace AgentCore.Application.Tests.Conversation { - [Fact] - public async Task OneObjectInBothSlots_IsDisposedExactlyOnce() + /// + /// The channel pair, including the case where one object fills both slots. + /// + public sealed class ConversationChannelTests { - var both = new CountingChannel(); - var channel = new ConversationChannel(both, both); - - await channel.DisposeAsync(); - - Assert.Equal(1, both.Disposals); - } - - [Fact] - public async Task TwoDistinctObjects_AreEachDisposedOnce() - { - var input = new CountingChannel(); - var output = new CountingChannel(); - var channel = new ConversationChannel(input, output); - - await channel.DisposeAsync(); - - Assert.Equal(1, input.Disposals); - Assert.Equal(1, output.Disposals); - } + [Fact] + public async Task OneObjectInBothSlots_IsDisposedExactlyOnce() + { + CountingChannel both = new(); + ConversationChannel channel = new(both, both); - [Fact] - public async Task DisposingTwice_DisposesTheInnerPortsOnlyOnce() - { - var both = new CountingChannel(); - var channel = new ConversationChannel(both, both); + await channel.DisposeAsync(); - await channel.DisposeAsync(); - await channel.DisposeAsync(); + Assert.Equal(1, both.Disposals); + } - Assert.Equal(1, both.Disposals); - } + [Fact] + public async Task TwoDistinctObjects_AreEachDisposedOnce() + { + CountingChannel input = new(); + CountingChannel output = new(); + ConversationChannel channel = new(input, output); - /// A port that fills either slot, or both, and counts its own disposals. - private sealed class CountingChannel : IConversationInputPort, IConversationOutputPort - { - public int Disposals { get; private set; } + await channel.DisposeAsync(); - public IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + Assert.Equal(1, input.Disposals); + Assert.Equal(1, output.Disposals); + } - public ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + [Fact] + public async Task DisposingTwice_DisposesTheInnerPortsOnlyOnce() + { + CountingChannel both = new(); + ConversationChannel channel = new(both, both); - public ValueTask CompleteAsync(CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + await channel.DisposeAsync(); + await channel.DisposeAsync(); - public ValueTask StopAsync(CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + Assert.Equal(1, both.Disposals); + } - public ValueTask DisposeAsync() + /// A port that fills either slot, or both, and counts its own disposals. + private sealed class CountingChannel : IConversationInputPort, IConversationOutputPort { - Disposals++; - return ValueTask.CompletedTask; + public int Disposals { get; private set; } + + public IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask CompleteAsync(CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask StopAsync(CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask DisposeAsync() + { + Disposals++; + return ValueTask.CompletedTask; + } } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationCursorTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationCursorTests.cs index f44913c7..4b256dd6 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationCursorTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationCursorTests.cs @@ -1,52 +1,53 @@ using AgentCore.Application.Conversation; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// The opaque cursor a listing hands back and takes again. -public sealed class ConversationCursorTests +namespace AgentCore.Application.Tests.Conversation { - [Fact] - public void Encode_ThenDecode_ReturnsBothValues() - { - // Arrange - DateTimeOffset sortAt = new(2026, 8, 30, 12, 34, 56, 789, TimeSpan.Zero); - - // Act - var cursor = ConversationCursor.Encode(sortAt, "conversation-1"); - var decoded = ConversationCursor.TryDecode(cursor, out var readAt, out var readId); - - // Assert - Assert.True(decoded); - Assert.Equal(sortAt, readAt); - Assert.Equal("conversation-1", readId); - } - - [Fact] - public void Encode_AConversationIdHoldingTheSeparator_RoundTripsWhole() + /// The opaque cursor a listing hands back and takes again. + public sealed class ConversationCursorTests { - // Arrange - const string ConversationId = "conversation|with|pipes"; - - // Act - var cursor = ConversationCursor.Encode(DateTimeOffset.UnixEpoch, ConversationId); - ConversationCursor.TryDecode(cursor, out _, out var readId); - - // Assert - Assert.Equal(ConversationId, readId); - } - - [Theory] - [InlineData(null)] - [InlineData("")] - [InlineData("not-base64!")] - [InlineData("bm90LWEtY3Vyc29y")] - public void TryDecode_SomethingThatIsNotACursor_IsFalseAndNotAThrow(string? cursor) - { - // Act - var decoded = ConversationCursor.TryDecode(cursor, out _, out _); - - // Assert - Assert.False(decoded); + [Fact] + public void Encode_ThenDecode_ReturnsBothValues() + { + // Arrange + DateTimeOffset sortAt = new(2026, 8, 30, 12, 34, 56, 789, TimeSpan.Zero); + + // Act + string cursor = ConversationCursor.Encode(sortAt, "conversation-1"); + bool decoded = ConversationCursor.TryDecode(cursor, out DateTimeOffset readAt, out string? readId); + + // Assert + Assert.True(decoded); + Assert.Equal(sortAt, readAt); + Assert.Equal("conversation-1", readId); + } + + [Fact] + public void Encode_AConversationIdHoldingTheSeparator_RoundTripsWhole() + { + // Arrange + const string ConversationId = "conversation|with|pipes"; + + // Act + string cursor = ConversationCursor.Encode(DateTimeOffset.UnixEpoch, ConversationId); + _ = ConversationCursor.TryDecode(cursor, out _, out string? readId); + + // Assert + Assert.Equal(ConversationId, readId); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData("not-base64!")] + [InlineData("bm90LWEtY3Vyc29y")] + public void TryDecode_SomethingThatIsNotACursor_IsFalseAndNotAThrow(string? cursor) + { + // Act + bool decoded = ConversationCursor.TryDecode(cursor, out _, out _); + + // Assert + Assert.False(decoded); + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationSessionStateTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationSessionStateTests.cs index a64529c4..0b4b6f39 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationSessionStateTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationSessionStateTests.cs @@ -1,92 +1,96 @@ -using System.Linq; using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Conversation; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -public sealed class ConversationSessionStateTests +namespace AgentCore.Application.Tests.Conversation { - [Fact] - public void ItRoundTripsThroughJson() + public sealed class ConversationSessionStateTests { - ConversationSessionState state = new() + [Fact] + public void ItRoundTripsThroughJson() { - Stage = "collecting", - IsComplete = false, - Slots = new Dictionary(StringComparer.Ordinal) + ConversationSessionState state = new() { - ["model"] = JsonValue.Create("F63"), - ["serial"] = null, - ["visits"] = JsonValue.Create(2), - ["address"] = new JsonObject + Stage = "collecting", + IsComplete = false, + Slots = new Dictionary(StringComparer.Ordinal) { - ["street"] = "1 Main St", - ["zip"] = JsonValue.Create(94107), + ["model"] = JsonValue.Create("F63"), + ["serial"] = null, + ["visits"] = JsonValue.Create(2), + ["address"] = new JsonObject + { + ["street"] = "1 Main St", + ["zip"] = JsonValue.Create(94107), + }, + ["tags"] = new JsonArray(JsonValue.Create("urgent"), JsonValue.Create("repeat")), }, - ["tags"] = new JsonArray(JsonValue.Create("urgent"), JsonValue.Create("repeat")), - }, - }; + }; - var json = JsonSerializer.Serialize(state, ConversationStateJson.Options); - var read = JsonSerializer.Deserialize(json, ConversationStateJson.Options); + string json = JsonSerializer.Serialize(state, ConversationStateJson.Options); + ConversationSessionState? read = JsonSerializer.Deserialize(json, ConversationStateJson.Options); - Assert.NotNull(read); - Assert.Equal(ConversationSessionState.CurrentVersion, read.Version); - Assert.Equal("collecting", read.Stage); - Assert.False(read.IsComplete); - Assert.Equal("F63", read.Slots["model"]!.GetValue()); - Assert.Null(read.Slots["serial"]); - Assert.Equal(2, read.Slots["visits"]!.GetValue()); - Assert.Equal("1 Main St", read.Slots["address"]!["street"]!.GetValue()); - Assert.Equal(94107, read.Slots["address"]!["zip"]!.GetValue()); - Assert.Equal( - ["urgent", "repeat"], - read.Slots["tags"]!.AsArray().Select(node => node!.GetValue())); - } + Assert.NotNull(read); + Assert.Equal(ConversationSessionState.CurrentVersion, read.Version); + Assert.Equal("collecting", read.Stage); + Assert.False(read.IsComplete); + Assert.Equal("F63", read.Slots["model"]!.GetValue()); + Assert.Null(read.Slots["serial"]); + Assert.Equal(2, read.Slots["visits"]!.GetValue()); + Assert.Equal("1 Main St", read.Slots["address"]!["street"]!.GetValue()); + Assert.Equal(94107, read.Slots["address"]!["zip"]!.GetValue()); + Assert.Equal( + ["urgent", "repeat"], + read.Slots["tags"]!.AsArray().Select(node => node!.GetValue())); + } - [Fact] - public void ANewStateCarriesTheCurrentVersion() - => Assert.Equal(ConversationSessionState.CurrentVersion, new ConversationSessionState().Version); + [Fact] + public void ANewStateCarriesTheCurrentVersion() + { + Assert.Equal(ConversationSessionState.CurrentVersion, new ConversationSessionState().Version); + } - [Fact] - public void ItRoundTripsProvidersThroughJson() - { - ConversationSessionState state = new() + [Fact] + public void ItRoundTripsProvidersThroughJson() { - Providers = new Dictionary(StringComparer.Ordinal) + ConversationSessionState state = new() { - ["TodoProvider"] = JsonDocument.Parse( - """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}""").RootElement, - ["AgentModeProvider"] = JsonDocument.Parse("""{"currentMode":"plan"}""").RootElement, - }, - }; + Providers = new Dictionary(StringComparer.Ordinal) + { + ["TodoProvider"] = JsonDocument.Parse( + """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}""").RootElement, + ["AgentModeProvider"] = JsonDocument.Parse("""{"currentMode":"plan"}""").RootElement, + }, + }; - var json = JsonSerializer.Serialize(state, ConversationStateJson.Options); - var read = JsonSerializer.Deserialize(json, ConversationStateJson.Options); + string json = JsonSerializer.Serialize(state, ConversationStateJson.Options); + ConversationSessionState? read = JsonSerializer.Deserialize(json, ConversationStateJson.Options); - Assert.NotNull(read); - Assert.Equal(2, read.Providers.Count); - Assert.Equal( - state.Providers["TodoProvider"].GetRawText(), - read.Providers["TodoProvider"].GetRawText()); - Assert.Equal( - state.Providers["AgentModeProvider"].GetRawText(), - read.Providers["AgentModeProvider"].GetRawText()); - } + Assert.NotNull(read); + Assert.Equal(2, read.Providers.Count); + Assert.Equal( + state.Providers["TodoProvider"].GetRawText(), + read.Providers["TodoProvider"].GetRawText()); + Assert.Equal( + state.Providers["AgentModeProvider"].GetRawText(), + read.Providers["AgentModeProvider"].GetRawText()); + } - [Fact] - public void ABlobWithNoProvidersMember_DeserializesWithEmptyProviders() - { - var read = JsonSerializer.Deserialize( - """{"version":1,"nextTurnIndex":0,"stage":"","isComplete":false}""", ConversationStateJson.Options); + [Fact] + public void ABlobWithNoProvidersMember_DeserializesWithEmptyProviders() + { + ConversationSessionState? read = JsonSerializer.Deserialize( + """{"version":1,"nextTurnIndex":0,"stage":"","isComplete":false}""", ConversationStateJson.Options); - Assert.NotNull(read); - Assert.Empty(read.Providers); - } + Assert.NotNull(read); + Assert.Empty(read.Providers); + } - [Fact] - public void ANewState_HasEmptyProviders() - => Assert.Empty(new ConversationSessionState().Providers); + [Fact] + public void ANewState_HasEmptyProviders() + { + Assert.Empty(new ConversationSessionState().Providers); + } + } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationSpeechPairingTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationSpeechPairingTests.cs index 94051466..24dad2a2 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationSpeechPairingTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationSpeechPairingTests.cs @@ -4,113 +4,120 @@ using AgentCore.Application.Ports; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -public sealed class ConversationSpeechPairingTests +namespace AgentCore.Application.Tests.Conversation { - private sealed class FakeConversationAdapter(string kind, bool carriesText) : IConversationAdapter - { - public string Kind { get; } = kind; - - public bool CarriesText { get; } = carriesText; - } - - private static ConversationProviderConfiguration Conversation(string kind) => new() { Kind = kind }; - - private static SpeechProviderConfiguration Speech(string stt, string tts) => new() - { - Stt = new VendorProviderConfiguration { Kind = stt }, - Tts = new VendorProviderConfiguration { Kind = tts }, - }; - - [Fact] - public void ATextCarryingTransportBesideItsOwnSpeechKindPasses() + public sealed class ConversationSpeechPairingTests { - ConversationSpeechPairing.Validate( - Conversation("telnyx-relay"), - Speech("telnyx-relay", "telnyx-relay"), - new FakeConversationAdapter("telnyx-relay", carriesText: true)); - } - - [Fact] - public void TheKindsMatchWithoutRegardToCase() - { - ConversationSpeechPairing.Validate( - Conversation("telnyx-relay"), - Speech("TELNYX-RELAY", "Telnyx-Relay"), - new FakeConversationAdapter("telnyx-relay", carriesText: true)); - } - - [Fact] - public void ATextCarryingTransportBesideAnotherRecognitionKindFailsTheStart() - { - var failure = Assert.Throws( - () => ConversationSpeechPairing.Validate( + private sealed class FakeConversationAdapter(string kind, bool carriesText) : IConversationAdapter + { + public string Kind { get; } = kind; + + public bool CarriesText { get; } = carriesText; + } + + private static ConversationProviderConfiguration Conversation(string kind) + { + return new() { Kind = kind }; + } + + private static SpeechProviderConfiguration Speech(string stt, string tts) + { + return new() + { + Stt = new VendorProviderConfiguration { Kind = stt }, + Tts = new VendorProviderConfiguration { Kind = tts }, + }; + } + + [Fact] + public void ATextCarryingTransportBesideItsOwnSpeechKindPasses() + { + ConversationSpeechPairing.Validate( Conversation("telnyx-relay"), - Speech("deepgram", "telnyx-relay"), - new FakeConversationAdapter("telnyx-relay", carriesText: true))); - - Assert.Single(failure.Errors); - Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); - Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Errors[0].Check); - Assert.Contains("telnyx-relay", failure.Message, StringComparison.Ordinal); - Assert.Contains("deepgram", failure.Message, StringComparison.Ordinal); - Assert.Contains("providers.speech.stt", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void ATextCarryingTransportBesideAnotherSynthesisKindFailsTheStart() - { - var failure = Assert.Throws( - () => ConversationSpeechPairing.Validate( - Conversation("telnyx-relay"), - Speech("telnyx-relay", "elevenlabs"), - new FakeConversationAdapter("telnyx-relay", carriesText: true))); - - Assert.Single(failure.Errors); - Assert.Equal("/providers/speech/tts/kind", failure.Errors[0].Pointer); - Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Errors[0].Check); - Assert.Contains("telnyx-relay", failure.Message, StringComparison.Ordinal); - Assert.Contains("elevenlabs", failure.Message, StringComparison.Ordinal); - Assert.Contains("providers.speech.tts", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void BothRolesMismatchedReportTwoErrors() - { - var failure = Assert.Throws( - () => ConversationSpeechPairing.Validate( + Speech("telnyx-relay", "telnyx-relay"), + new FakeConversationAdapter("telnyx-relay", carriesText: true)); + } + + [Fact] + public void TheKindsMatchWithoutRegardToCase() + { + ConversationSpeechPairing.Validate( Conversation("telnyx-relay"), + Speech("TELNYX-RELAY", "Telnyx-Relay"), + new FakeConversationAdapter("telnyx-relay", carriesText: true)); + } + + [Fact] + public void ATextCarryingTransportBesideAnotherRecognitionKindFailsTheStart() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConversationSpeechPairing.Validate( + Conversation("telnyx-relay"), + Speech("deepgram", "telnyx-relay"), + new FakeConversationAdapter("telnyx-relay", carriesText: true))); + + _ = Assert.Single(failure.Errors); + Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); + Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Errors[0].Check); + Assert.Contains("telnyx-relay", failure.Message, StringComparison.Ordinal); + Assert.Contains("deepgram", failure.Message, StringComparison.Ordinal); + Assert.Contains("providers.speech.stt", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void ATextCarryingTransportBesideAnotherSynthesisKindFailsTheStart() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConversationSpeechPairing.Validate( + Conversation("telnyx-relay"), + Speech("telnyx-relay", "elevenlabs"), + new FakeConversationAdapter("telnyx-relay", carriesText: true))); + + _ = Assert.Single(failure.Errors); + Assert.Equal("/providers/speech/tts/kind", failure.Errors[0].Pointer); + Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Errors[0].Check); + Assert.Contains("telnyx-relay", failure.Message, StringComparison.Ordinal); + Assert.Contains("elevenlabs", failure.Message, StringComparison.Ordinal); + Assert.Contains("providers.speech.tts", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void BothRolesMismatchedReportTwoErrors() + { + ConfigurationLoadException failure = Assert.Throws( + () => ConversationSpeechPairing.Validate( + Conversation("telnyx-relay"), + Speech("deepgram", "elevenlabs"), + new FakeConversationAdapter("telnyx-relay", carriesText: true))); + + Assert.Equal(2, failure.Errors.Count); + Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); + Assert.Equal("/providers/speech/tts/kind", failure.Errors[1].Pointer); + } + + [Fact] + public void AnAudioCarryingTransportBesideTwoOtherSpeechKindsPasses() + { + // This is the split shape: a SIP leg carries audio, one vendor turns it into text, and + // another turns text back into what the caller hears. + ConversationSpeechPairing.Validate( + Conversation("sip"), Speech("deepgram", "elevenlabs"), - new FakeConversationAdapter("telnyx-relay", carriesText: true))); - - Assert.Equal(2, failure.Errors.Count); - Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); - Assert.Equal("/providers/speech/tts/kind", failure.Errors[1].Pointer); - } - - [Fact] - public void AnAudioCarryingTransportBesideTwoOtherSpeechKindsPasses() - { - // This is the split shape: a SIP leg carries audio, one vendor turns it into text, and - // another turns text back into what the caller hears. - ConversationSpeechPairing.Validate( - Conversation("sip"), - Speech("deepgram", "elevenlabs"), - new FakeConversationAdapter("sip", carriesText: false)); - } - - [Fact] - public void NullArgumentsAreRefused() - { - var adapter = new FakeConversationAdapter("telnyx-relay", carriesText: true); - var speech = Speech("telnyx-relay", "telnyx-relay"); - - Assert.Throws( - () => ConversationSpeechPairing.Validate(null!, speech, adapter)); - Assert.Throws( - () => ConversationSpeechPairing.Validate(Conversation("telnyx-relay"), null!, adapter)); - Assert.Throws( - () => ConversationSpeechPairing.Validate(Conversation("telnyx-relay"), speech, null!)); + new FakeConversationAdapter("sip", carriesText: false)); + } + + [Fact] + public void NullArgumentsAreRefused() + { + FakeConversationAdapter adapter = new("telnyx-relay", carriesText: true); + SpeechProviderConfiguration speech = Speech("telnyx-relay", "telnyx-relay"); + + _ = Assert.Throws( + () => ConversationSpeechPairing.Validate(null!, speech, adapter)); + _ = Assert.Throws( + () => ConversationSpeechPairing.Validate(Conversation("telnyx-relay"), null!, adapter)); + _ = Assert.Throws( + () => ConversationSpeechPairing.Validate(Conversation("telnyx-relay"), speech, null!)); + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationStoreFactoryTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationStoreFactoryTests.cs index a49dd546..e1f8e4a6 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationStoreFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationStoreFactoryTests.cs @@ -6,153 +6,156 @@ using AgentCore.TestSupport; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// -/// The store vendor seam: providers.conversations, and what a document that names none gets. -/// -/// -/// The answer is never : a conversation's row and its words must have somewhere to go -/// whether or not a document chose where. These tests pin the parts that are this project's and not a vendor's -- -/// that there is always a store, that memory is this library's own name, and that every other -/// kind goes through the shared selector. -/// -public sealed class ConversationStoreFactoryTests +namespace AgentCore.Application.Tests.Conversation { - [Fact] - public async Task OpenAsync_NoConversationsBlock_GetsTheInProcessStoreAndAsksNoAdapter() + /// + /// The store vendor seam: providers.conversations, and what a document that names none gets. + /// + /// + /// The answer is never : a conversation's row and its words must have somewhere to go + /// whether or not a document chose where. These tests pin the parts that are this project's and not a vendor's -- + /// that there is always a store, that memory is this library's own name, and that every other + /// kind goes through the shared selector. + /// + public sealed class ConversationStoreFactoryTests { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document()); - FakeConversationStoreAdapter adapter = new("postgres"); - - // Act - var store = await ConversationStoreFactory.OpenAsync( - configuration, secrets: null, [adapter], TestContext.Current.CancellationToken); + [Fact] + public async Task OpenAsync_NoConversationsBlock_GetsTheInProcessStoreAndAsksNoAdapter() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document()); + FakeConversationStoreAdapter adapter = new("postgres"); - // Assert - Assert.IsType(store); - Assert.Equal(0, adapter.Opens); - } + // Act + IConversationStore store = await ConversationStoreFactory.OpenAsync( + configuration, secrets: null, [adapter], TestContext.Current.CancellationToken); - [Fact] - public async Task OpenAsync_TheMemoryKind_GetsTheInProcessStoreWithNoAdapterRegistered() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); + // Assert + _ = Assert.IsType(store); + Assert.Equal(0, adapter.Opens); + } - // Act - var store = await ConversationStoreFactory.OpenAsync( - configuration, secrets: null, [], TestContext.Current.CancellationToken); + [Fact] + public async Task OpenAsync_TheMemoryKind_GetsTheInProcessStoreWithNoAdapterRegistered() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); - // Assert - Assert.IsType(store); - } + // Act + IConversationStore store = await ConversationStoreFactory.OpenAsync( + configuration, secrets: null, [], TestContext.Current.CancellationToken); - [Fact] - public async Task OpenAsync_AnAdapterClaimingTheMemoryKind_DoesNotTakeOverTheBuiltIn() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); - FakeConversationStoreAdapter impostor = new("memory"); + // Assert + _ = Assert.IsType(store); + } - // Act - var store = await ConversationStoreFactory.OpenAsync( - configuration, secrets: null, [impostor], TestContext.Current.CancellationToken); + [Fact] + public async Task OpenAsync_AnAdapterClaimingTheMemoryKind_DoesNotTakeOverTheBuiltIn() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: memory")); + FakeConversationStoreAdapter impostor = new("memory"); - // Assert - Assert.IsType(store); - Assert.Equal(0, impostor.Opens); - } + // Act + IConversationStore store = await ConversationStoreFactory.OpenAsync( + configuration, secrets: null, [impostor], TestContext.Current.CancellationToken); - [Fact] - public async Task OpenAsync_TheKind_PicksOneAdapterAndLeavesTheOthersAlone() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document("kind: fake")); - FakeConversationStoreAdapter fake = new("fake"); - FakeConversationStoreAdapter other = new("postgres"); - - // Act - var store = await ConversationStoreFactory.OpenAsync( - configuration, secrets: null, [other, fake], TestContext.Current.CancellationToken); - - // Assert - Assert.Same(fake.Store, store); - Assert.Equal(0, other.Opens); - } + // Assert + _ = Assert.IsType(store); + Assert.Equal(0, impostor.Opens); + } - [Fact] - public async Task OpenAsync_AKindNoAdapterServes_FailsTheStartAndNamesWhatIsRegistered() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); - FakeConversationStoreAdapter adapter = new("fake"); - - // Act - var failure = await Assert.ThrowsAsync( - async () => await ConversationStoreFactory.OpenAsync( - configuration, secrets: null, [adapter], TestContext.Current.CancellationToken)); - - // Assert - Assert.Contains("postgres", failure.Message, StringComparison.Ordinal); - Assert.Equal("/providers/conversations/kind", failure.Errors[0].Pointer); - } + [Fact] + public async Task OpenAsync_TheKind_PicksOneAdapterAndLeavesTheOthersAlone() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: fake")); + FakeConversationStoreAdapter fake = new("fake"); + FakeConversationStoreAdapter other = new("postgres"); + + // Act + IConversationStore store = await ConversationStoreFactory.OpenAsync( + configuration, secrets: null, [other, fake], TestContext.Current.CancellationToken); + + // Assert + Assert.Same(fake.Store, store); + Assert.Equal(0, other.Opens); + } - [Fact] - public async Task OpenAsync_TwoAdaptersOnOneKind_FailTheStart() - { - // Arrange - var configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); - FakeConversationStoreAdapter[] both = - [new FakeConversationStoreAdapter("postgres"), new FakeConversationStoreAdapter("postgres")]; - - // Act - var failure = await Assert.ThrowsAsync( - async () => await ConversationStoreFactory.OpenAsync( - configuration, secrets: null, both, TestContext.Current.CancellationToken)); - - // Assert - Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); - Assert.Contains("stores", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task OpenAsync_AKindNoAdapterServes_FailsTheStartAndNamesWhatIsRegistered() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); + FakeConversationStoreAdapter adapter = new("fake"); + + // Act + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await ConversationStoreFactory.OpenAsync( + configuration, secrets: null, [adapter], TestContext.Current.CancellationToken)); + + // Assert + Assert.Contains("postgres", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/conversations/kind", failure.Errors[0].Pointer); + } - /// The providers.knowledge line the conversations block is written after. - private const string KnowledgeLine = Configuration.ExampleDocument.LastProviderLine; - - /// Builds the section 8.1 document with one conversations block written into it. - /// - /// The keys under providers.conversations, one for each line and without indentation. No entry - /// at all leaves the block out, which is the case that must still produce a store. - /// - private static string Document(params string[] entries) - => entries.Length == 0 - ? Configuration.ExampleDocument.Yaml - : Configuration.ExampleDocument.Yaml.Replace( - KnowledgeLine, - KnowledgeLine + "\n conversations:\n" + string.Join("\n", entries.Select(entry => " " + entry)), - StringComparison.Ordinal); - - /// An adapter that opens nothing and records that it was asked. - private sealed class FakeConversationStoreAdapter(string kind) : IConversationStoreAdapter - { - public string Kind => kind; + [Fact] + public async Task OpenAsync_TwoAdaptersOnOneKind_FailTheStart() + { + // Arrange + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: postgres")); + FakeConversationStoreAdapter[] both = + [new FakeConversationStoreAdapter("postgres"), new FakeConversationStoreAdapter("postgres")]; + + // Act + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await ConversationStoreFactory.OpenAsync( + configuration, secrets: null, both, TestContext.Current.CancellationToken)); + + // Assert + Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + Assert.Contains("stores", failure.Message, StringComparison.Ordinal); + } - public int Opens { get; private set; } + /// The providers.knowledge line the conversations block is written after. + private const string KnowledgeLine = Configuration.ExampleDocument.LastProviderLine; - /// The store this adapter hands over. It is a different type from the built-in one. - public IConversationStore Store { get; } = new FakeConversationStore(); + /// Builds the section 8.1 document with one conversations block written into it. + /// + /// The keys under providers.conversations, one for each line and without indentation. No entry + /// at all leaves the block out, which is the case that must still produce a store. + /// + private static string Document(params string[] entries) + { + return entries.Length == 0 + ? Configuration.ExampleDocument.Yaml + : Configuration.ExampleDocument.Yaml.Replace( + KnowledgeLine, + KnowledgeLine + "\n conversations:\n" + string.Join("\n", entries.Select(entry => " " + entry)), + StringComparison.Ordinal); + } - public ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) + /// An adapter that opens nothing and records that it was asked. + private sealed class FakeConversationStoreAdapter(string kind) : IConversationStoreAdapter { - Opens++; - return ValueTask.FromResult(Store); + public string Kind => kind; + + public int Opens { get; private set; } + + /// The store this adapter hands over. It is a different type from the built-in one. + public IConversationStore Store { get; } = new FakeConversationStore(); + + public ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + Opens++; + return ValueTask.FromResult(Store); + } } - } - /// A store that is a different type from the built-in one, and does nothing else. - private sealed class FakeConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()); + /// A store that is a different type from the built-in one, and does nothing else. + private sealed class FakeConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()); + } } diff --git a/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs b/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs index 6ae4436c..dc725be2 100644 --- a/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/ConversationsTests.cs @@ -7,236 +7,253 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// The one door to a stored conversation: its row, its words, and its files go together. -public sealed class ConversationsTests +namespace AgentCore.Application.Tests.Conversation { - /// A reply whose files the capture kept, 3 bytes each. - private static ChatMessage ReplyWith(params (string Name, string MediaType)[] kept) - => new(ChatRole.Assistant, [new TextContent("see"), .. kept.Select(file => Kept(file.Name, file.MediaType))]); + /// The one door to a stored conversation: its row, its words, and its files go together. + public sealed class ConversationsTests + { + /// A reply whose files the capture kept, 3 bytes each. + private static ChatMessage ReplyWith(params (string Name, string MediaType)[] kept) + { + return new(ChatRole.Assistant, [new TextContent("see"), .. kept.Select(file => Kept(file.Name, file.MediaType))]); + } - private static FileContent Kept(string name, string mediaType, long length = 3) - => new() { Name = name, FileId = "cfile_" + name, MediaType = mediaType, Length = length, Kept = true }; + private static FileContent Kept(string name, string mediaType, long length = 3) + { + return new() { Name = name, FileId = "cfile_" + name, MediaType = mediaType, Length = length, Kept = true }; + } - private static FileContent Refused(string name) - => new() { Name = name, FileId = "cfile_" + name }; + private static FileContent Refused(string name) + { + return new() { Name = name, FileId = "cfile_" + name }; + } - private static async Task KeepAsync(RecordingBlobStore blobs, string conversationId, string name, string mediaType) - => await blobs.PutAsync(new BlobWrite(conversationId, name, mediaType, new MemoryStream([1, 2, 3]), 3), TestContext.Current.CancellationToken); + private static async Task KeepAsync(RecordingBlobStore blobs, string conversationId, string name, string mediaType) + { + return await blobs.PutAsync(new BlobWrite(conversationId, name, mediaType, new MemoryStream([1, 2, 3]), 3), TestContext.Current.CancellationToken); + } - [Fact] - public async Task DeleteAsync_DeletesTheFilesAndTheRow() - { - // Arrange - InMemoryConversationStore store = new(); - RecordingBlobStore blobs = new(); - Conversations conversations = new(store, blobs); - var token = TestContext.Current.CancellationToken; - await conversations.CreateAsync("conversation-1", token); - await KeepAsync(blobs, "conversation-1", "chart.png", "image/png"); - await KeepAsync(blobs, "conversation-2", "keep.png", "image/png"); - - // Act - await conversations.DeleteAsync("conversation-1", token); - - // Assert - Assert.Null(await store.GetAsync("conversation-1", token)); - Assert.Equal([("conversation-2", "keep.png")], blobs.Blobs.Keys); - } + [Fact] + public async Task DeleteAsync_DeletesTheFilesAndTheRow() + { + // Arrange + InMemoryConversationStore store = new(); + RecordingBlobStore blobs = new(); + Conversations conversations = new(store, blobs); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await conversations.CreateAsync("conversation-1", token); + _ = await KeepAsync(blobs, "conversation-1", "chart.png", "image/png"); + _ = await KeepAsync(blobs, "conversation-2", "keep.png", "image/png"); + + // Act + await conversations.DeleteAsync("conversation-1", token); + + // Assert + Assert.Null(await store.GetAsync("conversation-1", token)); + Assert.Equal([("conversation-2", "keep.png")], blobs.Blobs.Keys); + } - [Fact] - public async Task DeleteAsync_NoBlobStore_DeletesTheRowAlone() - { - // Arrange - InMemoryConversationStore store = new(); - Conversations conversations = new(store, blobs: null); - var token = TestContext.Current.CancellationToken; - await conversations.CreateAsync("conversation-1", token); + [Fact] + public async Task DeleteAsync_NoBlobStore_DeletesTheRowAlone() + { + // Arrange + InMemoryConversationStore store = new(); + Conversations conversations = new(store, blobs: null); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await conversations.CreateAsync("conversation-1", token); - // Act - await conversations.DeleteAsync("conversation-1", token); + // Act + await conversations.DeleteAsync("conversation-1", token); - // Assert - Assert.Null(await store.GetAsync("conversation-1", token)); - } + // Assert + Assert.Null(await store.GetAsync("conversation-1", token)); + } - [Fact] - public async Task LoadWindowAsync_ReturnsTheRowTheWordsAndOneLinkPerKeptFile() - { - // Arrange - CountingBlobStore blobs = new(); - Conversations conversations = new(new InMemoryConversationStore(), blobs); - var token = TestContext.Current.CancellationToken; - await conversations.CreateAsync("conversation-1", token); - await conversations.AppendMessageAsync("conversation-1", new ChatMessage(ChatRole.User, "chart it"), token); - await conversations.AppendMessageAsync("conversation-1", ReplyWith(("chart.png", "image/png")), token); - - // Act - var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 10), token); - - // Assert - Assert.NotNull(stored); - Assert.Equal("conversation-1", stored.Conversation.ConversationId); - Assert.Equal(["chart it", "see"], stored.Messages.Select(message => message.Content.Text)); - var link = Assert.Single(stored.Files); - Assert.Equal(new BlobRef("conversation-1", "chart.png", "image/png", 3), link.Blob); - Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", link.Url?.ToString()); - } + [Fact] + public async Task LoadWindowAsync_ReturnsTheRowTheWordsAndOneLinkPerKeptFile() + { + // Arrange + CountingBlobStore blobs = new(); + Conversations conversations = new(new InMemoryConversationStore(), blobs); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await conversations.CreateAsync("conversation-1", token); + _ = await conversations.AppendMessageAsync("conversation-1", new ChatMessage(ChatRole.User, "chart it"), token); + _ = await conversations.AppendMessageAsync("conversation-1", ReplyWith(("chart.png", "image/png")), token); + + // Act + StoredConversation? stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 10), token); + + // Assert + Assert.NotNull(stored); + Assert.Equal("conversation-1", stored.Conversation.ConversationId); + Assert.Equal(["chart it", "see"], stored.Messages.Select(message => message.Content.Text)); + FileLink link = Assert.Single(stored.Files); + Assert.Equal(new BlobRef("conversation-1", "chart.png", "image/png", 3), link.Blob); + Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", link.Url?.ToString()); + } - [Fact] - public async Task LoadWindowAsync_AFullWindow_NamesTheTurnToReadBeforeNext_AndLinksThatWindowsFilesAlone() - { - // Arrange: turn 0 kept a file, turn 1 kept another. The window holds turn 1 only. - CountingBlobStore blobs = new(); - Conversations conversations = new(new InMemoryConversationStore(), blobs); - var token = TestContext.Current.CancellationToken; - await conversations.CreateAsync("conversation-1", token); - await conversations.AppendAsync( - "conversation-1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "chart it"), "m0"), - new ConversationMessageDraft(0, ReplyWith(("chart.png", "image/png")), "m1"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "rows too"), "m2"), - new ConversationMessageDraft(1, ReplyWith(("rows.csv", "text/csv")), "m3"), - ], - cancellationToken: token); - - // Act - var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 1), token); - - // Assert - Assert.NotNull(stored); - Assert.Equal(["m2", "m3"], stored.Messages.Select(message => message.MessageId)); - Assert.Equal(1, stored.OlderBefore); - Assert.Equal("rows.csv", Assert.Single(stored.Files).Blob.Name); - } + [Fact] + public async Task LoadWindowAsync_AFullWindow_NamesTheTurnToReadBeforeNext_AndLinksThatWindowsFilesAlone() + { + // Arrange: turn 0 kept a file, turn 1 kept another. The window holds turn 1 only. + CountingBlobStore blobs = new(); + Conversations conversations = new(new InMemoryConversationStore(), blobs); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await conversations.CreateAsync("conversation-1", token); + _ = await conversations.AppendAsync( + "conversation-1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "chart it"), "m0"), + new ConversationMessageDraft(0, ReplyWith(("chart.png", "image/png")), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "rows too"), "m2"), + new ConversationMessageDraft(1, ReplyWith(("rows.csv", "text/csv")), "m3"), + ], + cancellationToken: token); + + // Act + StoredConversation? stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 1), token); + + // Assert + Assert.NotNull(stored); + Assert.Equal(["m2", "m3"], stored.Messages.Select(message => message.MessageId)); + Assert.Equal(1, stored.OlderBefore); + Assert.Equal("rows.csv", Assert.Single(stored.Files).Blob.Name); + } - [Fact] - public async Task LoadWindowAsync_AShortWindow_ReachedTheStart_AndNamesNoTurn() - { - // Arrange - Conversations conversations = new(new InMemoryConversationStore(), blobs: null); - var token = TestContext.Current.CancellationToken; - await conversations.CreateAsync("conversation-1", token); - await conversations.AppendMessageAsync("conversation-1", new ChatMessage(ChatRole.User, "hello"), token); - - // Act - var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 5), token); - - // Assert - Assert.NotNull(stored); - Assert.Single(stored.Messages); - Assert.Null(stored.OlderBefore); - } + [Fact] + public async Task LoadWindowAsync_AShortWindow_ReachedTheStart_AndNamesNoTurn() + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), blobs: null); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await conversations.CreateAsync("conversation-1", token); + _ = await conversations.AppendMessageAsync("conversation-1", new ChatMessage(ChatRole.User, "hello"), token); + + // Act + StoredConversation? stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 5), token); + + // Assert + Assert.NotNull(stored); + _ = Assert.Single(stored.Messages); + Assert.Null(stored.OlderBefore); + } - [Fact] - public async Task LoadWindowAsync_AConversationThatWasNeverMade_IsNull() - { - // Arrange - Conversations conversations = new(new InMemoryConversationStore(), blobs: null); + [Fact] + public async Task LoadWindowAsync_AConversationThatWasNeverMade_IsNull() + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), blobs: null); - // Act - var stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 5), TestContext.Current.CancellationToken); + // Act + StoredConversation? stored = await conversations.LoadWindowAsync("conversation-1", new TranscriptWindow(null, 5), TestContext.Current.CancellationToken); - // Assert - Assert.Null(stored); - } + // Assert + Assert.Null(stored); + } - [Fact] - public async Task LinkFilesAsync_LinksFromTheContent_EachOnce_InFirstSeenOrder_WithoutAskingTheStore() - { - // Arrange: the store is empty on purpose. The content is the index. - CountingBlobStore blobs = new(); - Conversations conversations = new(new InMemoryConversationStore(), blobs); - - // Act - var links = await conversations.LinkFilesAsync( - "conversation-1", - [ - new ChatMessage(ChatRole.Assistant, [Kept("chart.png", "image/png"), Refused("lost.pdf")]), - ReplyWith(("rows.csv", "text/csv"), ("chart.png", "image/png")), - ], - TestContext.Current.CancellationToken); - - // Assert - Assert.Collection( - links, - link => - { - Assert.Equal(new BlobRef("conversation-1", "chart.png", "image/png", 3), link.Blob); - Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", link.Url?.ToString()); - }, - link => Assert.Equal("rows.csv", link.Blob.Name)); - Assert.Equal(0, blobs.Stats); - } + [Fact] + public async Task LinkFilesAsync_LinksFromTheContent_EachOnce_InFirstSeenOrder_WithoutAskingTheStore() + { + // Arrange: the store is empty on purpose. The content is the index. + CountingBlobStore blobs = new(); + Conversations conversations = new(new InMemoryConversationStore(), blobs); + + // Act + IReadOnlyList links = await conversations.LinkFilesAsync( + "conversation-1", + [ + new ChatMessage(ChatRole.Assistant, [Kept("chart.png", "image/png"), Refused("lost.pdf")]), + ReplyWith(("rows.csv", "text/csv"), ("chart.png", "image/png")), + ], + TestContext.Current.CancellationToken); + + // Assert + Assert.Collection( + links, + link => + { + Assert.Equal(new BlobRef("conversation-1", "chart.png", "image/png", 3), link.Blob); + Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", link.Url?.ToString()); + }, + link => Assert.Equal("rows.csv", link.Blob.Name)); + Assert.Equal(0, blobs.Stats); + } - [Fact] - public async Task LinkFilesAsync_NoBlobStore_LinksNothing() - { - // Arrange - Conversations conversations = new(new InMemoryConversationStore(), blobs: null); + [Fact] + public async Task LinkFilesAsync_NoBlobStore_LinksNothing() + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), blobs: null); - // Act - var links = await conversations.LinkFilesAsync("conversation-1", [ReplyWith(("chart.png", "image/png"))], TestContext.Current.CancellationToken); + // Act + IReadOnlyList links = await conversations.LinkFilesAsync("conversation-1", [ReplyWith(("chart.png", "image/png"))], TestContext.Current.CancellationToken); - // Assert - Assert.Empty(links); - } + // Assert + Assert.Empty(links); + } - [Fact] - public async Task LinkFilesAsync_SameNameKeptTwice_TheLaterFactsWinInTheFirstPlace() - { - // Arrange: the model redrew chart.png after rows.csv; the store replaced the first. - Conversations conversations = new(new InMemoryConversationStore(), new RecordingBlobStore()); - ChatMessage reply = new(ChatRole.Assistant, [Kept("chart.png", "image/png", 10), Kept("rows.csv", "text/csv", 5), Kept("chart.png", "image/png", 20)]); + [Fact] + public async Task LinkFilesAsync_SameNameKeptTwice_TheLaterFactsWinInTheFirstPlace() + { + // Arrange: the model redrew chart.png after rows.csv; the store replaced the first. + Conversations conversations = new(new InMemoryConversationStore(), new RecordingBlobStore()); + ChatMessage reply = new(ChatRole.Assistant, [Kept("chart.png", "image/png", 10), Kept("rows.csv", "text/csv", 5), Kept("chart.png", "image/png", 20)]); - // Act - var links = await conversations.LinkFilesAsync("conversation-1", [reply], TestContext.Current.CancellationToken); + // Act + IReadOnlyList links = await conversations.LinkFilesAsync("conversation-1", [reply], TestContext.Current.CancellationToken); - // Assert - Assert.Equal( - [new BlobRef("conversation-1", "chart.png", "image/png", 20), new BlobRef("conversation-1", "rows.csv", "text/csv", 5)], - links.Select(link => link.Blob)); - } + // Assert + Assert.Equal( + [new BlobRef("conversation-1", "chart.png", "image/png", 20), new BlobRef("conversation-1", "rows.csv", "text/csv", 5)], + links.Select(link => link.Blob)); + } - [Theory] - [InlineData("../etc/passwd")] - [InlineData("a/b.png")] - [InlineData("")] - public async Task LinkFilesAsync_UnsafeName_IsNotLinked(string name) - { - // Arrange - Conversations conversations = new(new InMemoryConversationStore(), new RecordingBlobStore()); + [Theory] + [InlineData("../etc/passwd")] + [InlineData("a/b.png")] + [InlineData("")] + public async Task LinkFilesAsync_UnsafeName_IsNotLinked(string name) + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), new RecordingBlobStore()); - // Act - var links = await conversations.LinkFilesAsync("conversation-1", [new ChatMessage(ChatRole.Assistant, [Kept(name, "image/png")])], TestContext.Current.CancellationToken); + // Act + IReadOnlyList links = await conversations.LinkFilesAsync("conversation-1", [new ChatMessage(ChatRole.Assistant, [Kept(name, "image/png")])], TestContext.Current.CancellationToken); - // Assert - Assert.Empty(links); - } + // Assert + Assert.Empty(links); + } - /// Links like the recording store, and counts how often anyone asks it whether a blob exists. - private sealed class CountingBlobStore : IBlobStore - { - public int Stats { get; private set; } + /// Links like the recording store, and counts how often anyone asks it whether a blob exists. + private sealed class CountingBlobStore : IBlobStore + { + public int Stats { get; private set; } - public ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) - { - Stats++; - return ValueTask.FromResult(null); - } + public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + Stats++; + return ValueTask.FromResult(null); + } - public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) - => ValueTask.FromResult(new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}")); + public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}")); + } - public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs b/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs index e03b01c4..aba009fd 100644 --- a/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/DelegatingConversationStoreTests.cs @@ -6,55 +6,56 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// The forwarding base every store fake is built on. -public sealed class DelegatingConversationStoreTests +namespace AgentCore.Application.Tests.Conversation { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - private sealed class CountingAppends(IConversationStore inner) : DelegatingConversationStore(inner) + /// The forwarding base every store fake is built on. + public sealed class DelegatingConversationStoreTests { - public int Appends { get; private set; } + private static CancellationToken Token => TestContext.Current.CancellationToken; - public override ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) + private sealed class CountingAppends(IConversationStore inner) : DelegatingConversationStore(inner) { - Appends++; - return base.AppendAsync(conversationId, messages, state, cancellationToken); + public int Appends { get; private set; } + + public override ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + Appends++; + return base.AppendAsync(conversationId, messages, state, cancellationToken); + } } - } - [Fact] - public async Task AnOverride_CountsItsOwnCalls_AndStillReachesTheInnerStore() - { - // Arrange - CountingAppends store = new(new InMemoryConversationStore()); - await store.CreateAsync("c1", Token); + [Fact] + public async Task AnOverride_CountsItsOwnCalls_AndStillReachesTheInnerStore() + { + // Arrange + CountingAppends store = new(new InMemoryConversationStore()); + _ = await store.CreateAsync("c1", Token); - // Act - await store.AppendAsync( - "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hi"), "m0")], cancellationToken: Token); + // Act + _ = await store.AppendAsync( + "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hi"), "m0")], cancellationToken: Token); - // Assert - Assert.Equal(1, store.Appends); - Assert.Single(await store.ReadAllAsync("c1", Token)); - } + // Assert + Assert.Equal(1, store.Appends); + _ = Assert.Single(await store.ReadAllAsync("c1", Token)); + } - [Fact] - public async Task AMethodNotOverridden_ReachesTheInnerStoreUnchanged() - { - // Arrange - CountingAppends store = new(new InMemoryConversationStore()); + [Fact] + public async Task AMethodNotOverridden_ReachesTheInnerStoreUnchanged() + { + // Arrange + CountingAppends store = new(new InMemoryConversationStore()); - // Act - var conversation = await store.CreateAsync("c1", Token); + // Act + ConversationRecord conversation = await store.CreateAsync("c1", Token); - // Assert - Assert.Equal("c1", conversation.ConversationId); - Assert.Equal(0, store.Appends); + // Assert + Assert.Equal("c1", conversation.ConversationId); + Assert.Equal(0, store.Appends); + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs index c2d44f85..5174e61c 100644 --- a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreSummaryRowTests.cs @@ -2,36 +2,51 @@ using AgentCore.TestSupport; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// The summary row facts of , against the in-memory store. -public sealed class InMemoryConversationStoreSummaryRowTests +namespace AgentCore.Application.Tests.Conversation { - [Fact] - public Task ReadForSession_HandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers() - => ConversationStoreSummaryRowFacts.SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(new InMemoryConversationStore(), TestContext.Current.CancellationToken); - - [Fact] - public Task ReadForSession_WithNoSummary_HandsBackEveryRow() - => ConversationStoreSummaryRowFacts.SessionReadWithNoSummaryHandsBackEveryRow(new InMemoryConversationStore(), TestContext.Current.CancellationToken); - - [Fact] - public Task ConsumerReads_LeaveEverySummaryOut() - => ConversationStoreSummaryRowFacts.ConsumerReadsLeaveEverySummaryOut(new InMemoryConversationStore(), TestContext.Current.CancellationToken); - - [Fact] - public Task Truncate_UnderWhatTheSummaryCovers_TakesTheSummary() - => ConversationStoreSummaryRowFacts.TruncateUnderWhatTheSummaryCoversTakesTheSummary(new InMemoryConversationStore(), TestContext.Current.CancellationToken); - - [Fact] - public Task Truncate_AboveWhatTheSummaryCovers_KeepsTheSummaryWhateverItsOrdinal() - => ConversationStoreSummaryRowFacts.TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(new InMemoryConversationStore(), TestContext.Current.CancellationToken); - - [Fact] - public Task Truncate_AboveTheSummary_LeavesEverythingUnderItAlone() - => ConversationStoreSummaryRowFacts.TruncateAboveTheSummaryLeavesEverythingUnderItAlone(new InMemoryConversationStore(), TestContext.Current.CancellationToken); - - [Fact] - public Task OrdinalOf_FindsASpokenRow_AndNotASummary() - => ConversationStoreSummaryRowFacts.OrdinalOfFindsASpokenRowAndNotASummary(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + /// The summary row facts of , against the in-memory store. + public sealed class InMemoryConversationStoreSummaryRowTests + { + [Fact] + public Task ReadForSession_HandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers() + { + return ConversationStoreSummaryRowFacts.SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + + [Fact] + public Task ReadForSession_WithNoSummary_HandsBackEveryRow() + { + return ConversationStoreSummaryRowFacts.SessionReadWithNoSummaryHandsBackEveryRow(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + + [Fact] + public Task ConsumerReads_LeaveEverySummaryOut() + { + return ConversationStoreSummaryRowFacts.ConsumerReadsLeaveEverySummaryOut(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + + [Fact] + public Task Truncate_UnderWhatTheSummaryCovers_TakesTheSummary() + { + return ConversationStoreSummaryRowFacts.TruncateUnderWhatTheSummaryCoversTakesTheSummary(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + + [Fact] + public Task Truncate_AboveWhatTheSummaryCovers_KeepsTheSummaryWhateverItsOrdinal() + { + return ConversationStoreSummaryRowFacts.TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + + [Fact] + public Task Truncate_AboveTheSummary_LeavesEverythingUnderItAlone() + { + return ConversationStoreSummaryRowFacts.TruncateAboveTheSummaryLeavesEverythingUnderItAlone(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + + [Fact] + public Task OrdinalOf_FindsASpokenRow_AndNotASummary() + { + return ConversationStoreSummaryRowFacts.OrdinalOfFindsASpokenRowAndNotASummary(new InMemoryConversationStore(), TestContext.Current.CancellationToken); + } + } } diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTests.cs index 7a9e0dee..37d0f01b 100644 --- a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTests.cs @@ -4,284 +4,288 @@ using AgentCore.Application.Tests.Runtime; using Microsoft.Extensions.AI; using Xunit; +using System.Text.Json; -namespace AgentCore.Application.Tests.Conversation; - -/// Store 0, kept in this process. -public sealed class InMemoryConversationStoreTests +namespace AgentCore.Application.Tests.Conversation { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task CreateAsync_TheSameIdTwice_IsOneConversation() + /// Store 0, kept in this process. + public sealed class InMemoryConversationStoreTests { - // Arrange - InMemoryConversationStore store = new(); + private static CancellationToken Token => TestContext.Current.CancellationToken; - // Act - var first = await store.CreateAsync("c1", Token); - var second = await store.CreateAsync("c1", Token); + [Fact] + public async Task CreateAsync_TheSameIdTwice_IsOneConversation() + { + // Arrange + InMemoryConversationStore store = new(); - // Assert - Assert.Equal(first.ConversationId, second.ConversationId); - Assert.Equal(first.CreatedAt, second.CreatedAt); - } + // Act + ConversationRecord first = await store.CreateAsync("c1", Token); + ConversationRecord second = await store.CreateAsync("c1", Token); - [Fact] - public async Task GetAsync_AConversationThatWasNeverMade_IsNull() - { - // Arrange - InMemoryConversationStore store = new(); + // Assert + Assert.Equal(first.ConversationId, second.ConversationId); + Assert.Equal(first.CreatedAt, second.CreatedAt); + } - // Act - var found = await store.GetAsync("missing", Token); + [Fact] + public async Task GetAsync_AConversationThatWasNeverMade_IsNull() + { + // Arrange + InMemoryConversationStore store = new(); - // Assert - Assert.Null(found); - } + // Act + ConversationRecord? found = await store.GetAsync("missing", Token); - [Fact] - public async Task RenameAsync_AConversation_ChangesOnlyItsTitle() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); + // Assert + Assert.Null(found); + } - // Act - await store.RenameAsync("c1", "A squeaky belt", Token); + [Fact] + public async Task RenameAsync_AConversation_ChangesOnlyItsTitle() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); - // Assert - var found = await store.GetAsync("c1", Token); - Assert.Equal("A squeaky belt", found!.Title); - Assert.Equal(ConversationStatus.Regular, found.Status); - } + // Act + await store.RenameAsync("c1", "A squeaky belt", Token); - [Fact] - public async Task ListAsync_APrincipalWithNoConversations_IsEmptyAndHasNoCursor() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); + // Assert + ConversationRecord? found = await store.GetAsync("c1", Token); + Assert.Equal("A squeaky belt", found!.Title); + Assert.Equal(ConversationStatus.Regular, found.Status); + } - // Act - var page = await store.ListAsync("nobody", after: null, limit: 10, cancellationToken: Token); + [Fact] + public async Task ListAsync_APrincipalWithNoConversations_IsEmptyAndHasNoCursor() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); - // Assert - Assert.Empty(page.Conversations); - Assert.Null(page.NextCursor); - } + // Act + ConversationPage page = await store.ListAsync("nobody", after: null, limit: 10, cancellationToken: Token); - [Fact] - public async Task ListAsync_AnotherPrincipalsConversation_IsNotReturned() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("mine", Token); - await store.CreateAsync("theirs", Token); - await store.AttachPrincipalAsync("mine", "person-a", "caller", Token); - await store.AttachPrincipalAsync("theirs", "person-b", "caller", Token); - - // Act - var page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - - // Assert - Assert.Equal(["mine"], page.Conversations.Select(conversation => conversation.ConversationId)); - } + // Assert + Assert.Empty(page.Conversations); + Assert.Null(page.NextCursor); + } - [Fact] - public async Task ListAsync_TwoKeysOnOneConversation_FindsItByEither() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Act - var byTenant = await store.ListAsync("tenant-a", after: null, limit: 10, cancellationToken: Token); - var byPerson = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - - // Assert - Assert.Single(byTenant.Conversations); - Assert.Single(byPerson.Conversations); - } + [Fact] + public async Task ListAsync_AnotherPrincipalsConversation_IsNotReturned() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("mine", Token); + _ = await store.CreateAsync("theirs", Token); + await store.AttachPrincipalAsync("mine", "person-a", "caller", Token); + await store.AttachPrincipalAsync("theirs", "person-b", "caller", Token); + + // Act + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + + // Assert + Assert.Equal(["mine"], page.Conversations.Select(conversation => conversation.ConversationId)); + } - [Fact] - public async Task AttachPrincipalAsync_TheSamePairTwice_IsOneAttachment() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); + [Fact] + public async Task ListAsync_TwoKeysOnOneConversation_FindsItByEither() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Act + ConversationPage byTenant = await store.ListAsync("tenant-a", after: null, limit: 10, cancellationToken: Token); + ConversationPage byPerson = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + + // Assert + _ = Assert.Single(byTenant.Conversations); + _ = Assert.Single(byPerson.Conversations); + } - // Act - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + [Fact] + public async Task AttachPrincipalAsync_TheSamePairTwice_IsOneAttachment() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); - // Assert - var page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - Assert.Single(page.Conversations); - } + // Act + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - [Fact] - public async Task DetachPrincipalAsync_TheOnlyKey_LeavesTheConversationUnlisted() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + // Assert + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + _ = Assert.Single(page.Conversations); + } - // Act - await store.DetachPrincipalAsync("c1", "person-a", Token); + [Fact] + public async Task DetachPrincipalAsync_TheOnlyKey_LeavesTheConversationUnlisted() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - // Assert - Assert.Empty((await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token)).Conversations); - Assert.NotNull(await store.GetAsync("c1", Token)); - } + // Act + await store.DetachPrincipalAsync("c1", "person-a", Token); - [Fact] - public async Task ListAsync_ArchivedConversations_AreOutOfARegularListing() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - await store.SetStatusAsync("c1", ConversationStatus.Archived, Token); - - // Act - var regular = await store.ListAsync("person-a", after: null, limit: 10, ConversationStatus.Regular, Token); - var everything = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - - // Assert - Assert.Empty(regular.Conversations); - Assert.Single(everything.Conversations); - } + // Assert + Assert.Empty((await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token)).Conversations); + Assert.NotNull(await store.GetAsync("c1", Token)); + } - [Fact] - public async Task ListAsync_MoreConversationsThanTheLimit_PagesWithNoGapAndNoRepeat() - { - // Arrange - InMemoryConversationStore store = new(); - for (var i = 0; i < 5; i++) + [Fact] + public async Task ListAsync_ArchivedConversations_AreOutOfARegularListing() { - await store.CreateAsync($"c{i}", Token); - await store.AttachPrincipalAsync($"c{i}", "person-a", "caller", Token); + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + await store.SetStatusAsync("c1", ConversationStatus.Archived, Token); + + // Act + ConversationPage regular = await store.ListAsync("person-a", after: null, limit: 10, ConversationStatus.Regular, Token); + ConversationPage everything = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + + // Assert + Assert.Empty(regular.Conversations); + _ = Assert.Single(everything.Conversations); } - // Act - List seen = []; - string? cursor = null; - do + [Fact] + public async Task ListAsync_MoreConversationsThanTheLimit_PagesWithNoGapAndNoRepeat() { - var page = await store.ListAsync("person-a", cursor, limit: 2, cancellationToken: Token); - seen.AddRange(page.Conversations.Select(conversation => conversation.ConversationId)); - cursor = page.NextCursor; + // Arrange + InMemoryConversationStore store = new(); + for (int i = 0; i < 5; i++) + { + _ = await store.CreateAsync($"c{i}", Token); + await store.AttachPrincipalAsync($"c{i}", "person-a", "caller", Token); + } + + // Act + List seen = []; + string? cursor = null; + do + { + ConversationPage page = await store.ListAsync("person-a", cursor, limit: 2, cancellationToken: Token); + seen.AddRange(page.Conversations.Select(conversation => conversation.ConversationId)); + cursor = page.NextCursor; + } + while (cursor is not null); + + // Assert + Assert.Equal(5, seen.Count); + Assert.Equal(5, seen.Distinct().Count()); } - while (cursor is not null); - // Assert - Assert.Equal(5, seen.Count); - Assert.Equal(5, seen.Distinct().Count()); - } + [Fact] + public async Task SetExternalIdAsync_AConsumersOwnId_IsReadBack() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); - [Fact] - public async Task SetExternalIdAsync_AConsumersOwnId_IsReadBack() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); + // Act + await store.SetExternalIdAsync("c1", "crm-77", Token); - // Act - await store.SetExternalIdAsync("c1", "crm-77", Token); + // Assert + Assert.Equal("crm-77", (await store.GetAsync("c1", Token))!.ExternalId); + } - // Assert - Assert.Equal("crm-77", (await store.GetAsync("c1", Token))!.ExternalId); - } + [Fact] + public async Task SetExternalIdAsync_Null_ClearsTheId() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + await store.SetExternalIdAsync("c1", "crm-77", Token); - [Fact] - public async Task SetExternalIdAsync_Null_ClearsTheId() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.SetExternalIdAsync("c1", "crm-77", Token); + // Act + await store.SetExternalIdAsync("c1", null, Token); - // Act - await store.SetExternalIdAsync("c1", null, Token); + // Assert + Assert.Null((await store.GetAsync("c1", Token))!.ExternalId); + } - // Assert - Assert.Null((await store.GetAsync("c1", Token))!.ExternalId); - } + [Fact] + public async Task DeleteAsync_AConversation_TakesItsAttachmentsWithIt() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - [Fact] - public async Task DeleteAsync_AConversation_TakesItsAttachmentsWithIt() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + // Act + await store.DeleteAsync("c1", Token); - // Act - await store.DeleteAsync("c1", Token); + // Assert + Assert.Null(await store.GetAsync("c1", Token)); + Assert.Empty((await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token)).Conversations); + } - // Assert - Assert.Null(await store.GetAsync("c1", Token)); - Assert.Empty((await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token)).Conversations); - } + [Fact] + public async Task DeleteAsync_AConversation_TakesItsResumeStateWithIt() + { + // Arrange — the state lives beside the row rather than on it, so it has to be forgotten by + // hand. In PostgreSQL it is a column of the conversation row and DELETE FROM conversation takes it, and the + // two backings answering differently is the defect this pins. + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync("c1", [Word()], new ConversationSessionState { Stage = "collecting" }, Token); + + // Act + await store.DeleteAsync("c1", Token); + + // Assert — a conversation made again under the same id is a NEW conversation, not the dead one resurrected + // with its stage and the caller data the extractor left in its slots. + Assert.Null((await store.CreateAsync("c1", Token)).State); + } - [Fact] - public async Task DeleteAsync_AConversation_TakesItsResumeStateWithIt() - { - // Arrange — the state lives beside the row rather than on it, so it has to be forgotten by - // hand. In PostgreSQL it is a column of the conversation row and DELETE FROM conversation takes it, and the - // two backings answering differently is the defect this pins. - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AppendAsync("c1", [Word()], new ConversationSessionState { Stage = "collecting" }, Token); - - // Act - await store.DeleteAsync("c1", Token); - - // Assert — a conversation made again under the same id is a NEW conversation, not the dead one resurrected - // with its stage and the caller data the extractor left in its slots. - Assert.Null((await store.CreateAsync("c1", Token)).State); - } + [Fact] + public async Task DeleteAsync_AConversation_TakesItsSameIdContinuationWithIt() + { + // Arrange — one id plays three roles now: the conversation, the conversation, and the continuation + // key. Deleting the conversation must forget the key or the next thread turn resumes the dead conversation. + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + using JsonDocument document = JsonDocument.Parse("""{ "conversationId": "c1" }"""); + await store.SaveContinuationAsync("c1", document.RootElement, Token); + + // Act + await store.DeleteAsync("c1", Token); + + // Assert + Assert.Null(await store.GetContinuationAsync("c1", Token)); + } - [Fact] - public async Task DeleteAsync_AConversation_TakesItsSameIdContinuationWithIt() - { - // Arrange — one id plays three roles now: the conversation, the conversation, and the continuation - // key. Deleting the conversation must forget the key or the next thread turn resumes the dead conversation. - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - using var document = System.Text.Json.JsonDocument.Parse("""{ "conversationId": "c1" }"""); - await store.SaveContinuationAsync("c1", document.RootElement, Token); - - // Act - await store.DeleteAsync("c1", Token); - - // Assert - Assert.Null(await store.GetContinuationAsync("c1", Token)); - } + [Fact] + public async Task SweepAsync_AConversationPastRetention_TakesItsResumeStateWithIt() + { + // Arrange — retention is the promise that a conversation stops existing, and slots hold what the + // extractor took from the caller, so state left behind is data kept past the promise. + TestTimeProvider clock = new(); + InMemoryConversationStore store = new(clock); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync("c1", [Word()], new ConversationSessionState { Stage = "collecting" }, Token); + + // Act + clock.Advance(TimeSpan.FromDays(2)); + int swept = await store.SweepAsync(TimeSpan.FromDays(1), cancellationToken: Token); + + // Assert + Assert.Equal(1, swept); + Assert.Null((await store.CreateAsync("c1", Token)).State); + } - [Fact] - public async Task SweepAsync_AConversationPastRetention_TakesItsResumeStateWithIt() - { - // Arrange — retention is the promise that a conversation stops existing, and slots hold what the - // extractor took from the caller, so state left behind is data kept past the promise. - TestTimeProvider clock = new(); - InMemoryConversationStore store = new(clock); - await store.CreateAsync("c1", Token); - await store.AppendAsync("c1", [Word()], new ConversationSessionState { Stage = "collecting" }, Token); - - // Act - clock.Advance(TimeSpan.FromDays(2)); - var swept = await store.SweepAsync(TimeSpan.FromDays(1), cancellationToken: Token); - - // Assert - Assert.Equal(1, swept); - Assert.Null((await store.CreateAsync("c1", Token)).State); + private static ConversationMessageDraft Word() + { + return new(0, new ChatMessage(ChatRole.User, "hello"), "m0"); + } } - - private static ConversationMessageDraft Word() - => new(0, new ChatMessage(ChatRole.User, "hello"), "m0"); } diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs index cd0c3a46..1e0224f3 100644 --- a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreTranscriptTests.cs @@ -1,111 +1,113 @@ +using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Transcript; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// The words half of store 0, now that one store holds both halves. -public sealed class InMemoryConversationStoreTranscriptTests +namespace AgentCore.Application.Tests.Conversation { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task RewriteAsync_AnExistingMessage_ReplacesItsContent() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AppendAsync( - "c1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "long reply"), "m0")], - cancellationToken: Token); - - // Act - await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.Assistant, "cut"), Token); - - // Assert - var rows = await store.ReadAllAsync("c1", Token); - Assert.Equal("cut", Assert.Single(rows).Content.Text); - } - - [Fact] - public async Task EraseAsync_AConversationWithWords_RemovesThemAndReportsTheCount() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.CreateAsync("c2", Token); - await store.AppendAsync( - "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "a"), "m0")], cancellationToken: Token); - await store.AppendAsync( - "c2", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "b"), "m0")], cancellationToken: Token); - - // Act - var erased = await store.EraseAsync("c1", Token); - - // Assert - Assert.Equal(1, erased); - Assert.Empty(await store.ReadAllAsync("c1", Token)); - Assert.Single(await store.ReadAllAsync("c2", Token)); - } - - [Fact] - public async Task GetAsync_AfterAppend_ReportsWhenTheConversationWasLastSpokenOn() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - - // Act - await store.AppendAsync( - "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], cancellationToken: Token); - - // Assert - var conversation = await store.GetAsync("c1", Token); - Assert.NotNull(conversation); - Assert.NotNull(conversation.LastMessageAt); - } - - [Fact] - public async Task EraseAsync_AConversation_TakesEveryRowAndReportsHowMany() - { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "one"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "two"), "m1"), - ], - cancellationToken: Token); - - // Act - var erased = await store.EraseAsync("c1", Token); - - // Assert - Assert.Equal(2, erased); - Assert.Empty(await store.ReadAllAsync("c1", Token)); - } - - [Fact] - public async Task EraseAsync_AConversation_LeavesEveryOtherConversationAlone() + /// The words half of store 0, now that one store holds both halves. + public sealed class InMemoryConversationStoreTranscriptTests { - // Arrange - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.CreateAsync("c2", Token); - await store.AppendAsync( - "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "mine"), "m0")], cancellationToken: Token); - await store.AppendAsync( - "c2", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "theirs"), "m0")], cancellationToken: Token); - - // Act - await store.EraseAsync("c1", Token); - - // Assert - Assert.Single(await store.ReadAllAsync("c2", Token)); + private static CancellationToken Token => TestContext.Current.CancellationToken; + + [Fact] + public async Task RewriteAsync_AnExistingMessage_ReplacesItsContent() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync( + "c1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "long reply"), "m0")], + cancellationToken: Token); + + // Act + await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.Assistant, "cut"), Token); + + // Assert + IReadOnlyList rows = await store.ReadAllAsync("c1", Token); + Assert.Equal("cut", Assert.Single(rows).Content.Text); + } + + [Fact] + public async Task EraseAsync_AConversationWithWords_RemovesThemAndReportsTheCount() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + _ = await store.CreateAsync("c2", Token); + _ = await store.AppendAsync( + "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "a"), "m0")], cancellationToken: Token); + _ = await store.AppendAsync( + "c2", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "b"), "m0")], cancellationToken: Token); + + // Act + int erased = await store.EraseAsync("c1", Token); + + // Assert + Assert.Equal(1, erased); + Assert.Empty(await store.ReadAllAsync("c1", Token)); + _ = Assert.Single(await store.ReadAllAsync("c2", Token)); + } + + [Fact] + public async Task GetAsync_AfterAppend_ReportsWhenTheConversationWasLastSpokenOn() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + + // Act + _ = await store.AppendAsync( + "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], cancellationToken: Token); + + // Assert + ConversationRecord? conversation = await store.GetAsync("c1", Token); + Assert.NotNull(conversation); + _ = Assert.NotNull(conversation.LastMessageAt); + } + + [Fact] + public async Task EraseAsync_AConversation_TakesEveryRowAndReportsHowMany() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "one"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "two"), "m1"), + ], + cancellationToken: Token); + + // Act + int erased = await store.EraseAsync("c1", Token); + + // Assert + Assert.Equal(2, erased); + Assert.Empty(await store.ReadAllAsync("c1", Token)); + } + + [Fact] + public async Task EraseAsync_AConversation_LeavesEveryOtherConversationAlone() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + _ = await store.CreateAsync("c2", Token); + _ = await store.AppendAsync( + "c1", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "mine"), "m0")], cancellationToken: Token); + _ = await store.AppendAsync( + "c2", [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "theirs"), "m0")], cancellationToken: Token); + + // Act + _ = await store.EraseAsync("c1", Token); + + // Assert + _ = Assert.Single(await store.ReadAllAsync("c2", Token)); + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs index 6d64d624..103595aa 100644 --- a/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/InMemoryConversationStoreWindowTests.cs @@ -3,72 +3,73 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Conversation; - -/// Reading store 1 a window of turns at a time, newest turns first, every turn whole. -public sealed class InMemoryConversationStoreWindowTests +namespace AgentCore.Application.Tests.Conversation { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - /// Four turns. Turn 2 answers through a tool, so it holds four rows rather than two. - private static async Task FourTurnsAsync() + /// Reading store 1 a window of turns at a time, newest turns first, every turn whole. + public sealed class InMemoryConversationStoreWindowTests { - InMemoryConversationStore store = new(); - await store.CreateAsync("c1", Token); - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q0"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a0"), "m1"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q1"), "m2"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a1"), "m3"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2"), "m4"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call", "lookup")]), "m5"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call", "found")]), "m6"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, "a2"), "m7"), - new ConversationMessageDraft(3, new ChatMessage(ChatRole.User, "q3"), "m8"), - new ConversationMessageDraft(3, new ChatMessage(ChatRole.Assistant, "a3"), "m9"), - ], cancellationToken: Token); - return store; - } + private static CancellationToken Token => TestContext.Current.CancellationToken; - [Fact] - public async Task ReadWindowAsync_NoStart_ReadsTheNewestTurnsWholeOldestRowFirst() - { - var store = await FourTurnsAsync(); + /// Four turns. Turn 2 answers through a tool, so it holds four rows rather than two. + private static async Task FourTurnsAsync() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q0"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a0"), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q1"), "m2"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a1"), "m3"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2"), "m4"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call", "lookup")]), "m5"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call", "found")]), "m6"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, "a2"), "m7"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.User, "q3"), "m8"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.Assistant, "a3"), "m9"), + ], cancellationToken: Token); + return store; + } - var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(null, 2), Token); + [Fact] + public async Task ReadWindowAsync_NoStart_ReadsTheNewestTurnsWholeOldestRowFirst() + { + InMemoryConversationStore store = await FourTurnsAsync(); - Assert.Equal(["m4", "m5", "m6", "m7", "m8", "m9"], rows.Select(row => row.MessageId)); - } + IReadOnlyList rows = await store.ReadWindowAsync("c1", new TranscriptWindow(null, 2), Token); - [Fact] - public async Task ReadWindowAsync_BeforeATurn_ReadsTheTurnsJustBelowIt() - { - var store = await FourTurnsAsync(); + Assert.Equal(["m4", "m5", "m6", "m7", "m8", "m9"], rows.Select(row => row.MessageId)); + } - var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(2, 2), Token); + [Fact] + public async Task ReadWindowAsync_BeforeATurn_ReadsTheTurnsJustBelowIt() + { + InMemoryConversationStore store = await FourTurnsAsync(); - Assert.Equal(["m0", "m1", "m2", "m3"], rows.Select(row => row.MessageId)); - } + IReadOnlyList rows = await store.ReadWindowAsync("c1", new TranscriptWindow(2, 2), Token); - [Fact] - public async Task ReadWindowAsync_PastTheStart_ReadsWhatIsLeft() - { - var store = await FourTurnsAsync(); + Assert.Equal(["m0", "m1", "m2", "m3"], rows.Select(row => row.MessageId)); + } - var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(1, 5), Token); + [Fact] + public async Task ReadWindowAsync_PastTheStart_ReadsWhatIsLeft() + { + InMemoryConversationStore store = await FourTurnsAsync(); - Assert.Equal(["m0", "m1"], rows.Select(row => row.MessageId)); - } + IReadOnlyList rows = await store.ReadWindowAsync("c1", new TranscriptWindow(1, 5), Token); - [Fact] - public async Task ReadWindowAsync_BeforeTheFirstTurn_ReadsNothing() - { - var store = await FourTurnsAsync(); + Assert.Equal(["m0", "m1"], rows.Select(row => row.MessageId)); + } + + [Fact] + public async Task ReadWindowAsync_BeforeTheFirstTurn_ReadsNothing() + { + InMemoryConversationStore store = await FourTurnsAsync(); - var rows = await store.ReadWindowAsync("c1", new TranscriptWindow(0, 5), Token); + IReadOnlyList rows = await store.ReadWindowAsync("c1", new TranscriptWindow(0, 5), Token); - Assert.Empty(rows); + Assert.Empty(rows); + } } } diff --git a/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs b/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs index d89b532d..8319e25b 100644 --- a/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs +++ b/tests/AgentCore.Application.Tests/Conversation/Memory/InMemoryConversationStoreAppendTests.cs @@ -7,180 +7,181 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Conversation.Memory; - -/// -/// The store numbers every row from the conversation's own counter, in memory: the seam that lets a host -/// append to a conversation from outside any turn, whether or not a session for the conversation is live. -/// -#pragma warning disable CA1859 // store is typed as IConversationStore throughout: AppendAsync(conversationId, message, ct) - // is a default interface method, and only resolves through the interface type. -public sealed partial class InMemoryConversationStoreAppendTests +namespace AgentCore.Application.Tests.Conversation.Memory { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task AppendAsync_OneMessage_OnAFreshConversation_IsOrdinalZeroAndTurnZero() + /// + /// The store numbers every row from the conversation's own counter, in memory: the seam that lets a host + /// append to a conversation from outside any turn, whether or not a session for the conversation is live. + /// +#pragma warning disable CA1859 // store is typed as IConversationStore throughout: AppendAsync(conversationId, message, ct) + // is a default interface method, and only resolves through the interface type. + public sealed partial class InMemoryConversationStoreAppendTests { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - - // Act - var row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "hello"), Token); + private static CancellationToken Token => TestContext.Current.CancellationToken; - // Assert - Assert.Equal(0, row.Ordinal); - Assert.Equal(0, row.TurnIndex); - Assert.Matches(HexId(), row.MessageId); - } - - [Fact] - public async Task AppendAsync_OneMessage_WithItsOwnId_KeepsIt() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - ChatMessage message = new(ChatRole.User, "hello") { MessageId = "caller-named" }; + [Fact] + public async Task AppendAsync_OneMessage_OnAFreshConversation_IsOrdinalZeroAndTurnZero() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); - // Act - var row = await store.AppendMessageAsync("c1", message, Token); + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "hello"), Token); - // Assert - Assert.Equal("caller-named", row.MessageId); - } + // Assert + Assert.Equal(0, row.Ordinal); + Assert.Equal(0, row.TurnIndex); + Assert.Matches(HexId(), row.MessageId); + } - [Fact] - public async Task AppendAsync_TwoOutsideAppends_AreNumberedZeroThenOne() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - - // Act - var first = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); - var second = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); - - // Assert - Assert.Equal(0, first.Ordinal); - Assert.Equal(1, second.Ordinal); - var conversation = await store.GetAsync("c1", Token); - Assert.Equal(2, conversation?.NextOrdinal); - } - - [Fact] - public async Task AppendAsync_ABatchWithAnExplicitTurnIndex_NumbersThreeConsecutiveRowsInDraftOrder() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); - - ConversationMessageDraft[] drafts = - [ - new(4, new ChatMessage(ChatRole.User, "a"), "m-a"), - new(4, new ChatMessage(ChatRole.Assistant, "b"), "m-b"), - new(4, new ChatMessage(ChatRole.User, "c"), "m-c"), - ]; - - // Act - var rows = await store.AppendAsync("c1", drafts, cancellationToken: Token); - - // Assert - Assert.Equal([1, 2, 3], rows.Select(row => row.Ordinal)); - Assert.All(rows, row => Assert.Equal(4, row.TurnIndex)); - Assert.Equal(["m-a", "m-b", "m-c"], rows.Select(row => row.MessageId)); - } + [Fact] + public async Task AppendAsync_OneMessage_WithItsOwnId_KeepsIt() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + ChatMessage message = new(ChatRole.User, "hello") { MessageId = "caller-named" }; - [Fact] - public async Task AppendAsync_OutsideAppend_AfterABatchThatWroteState_IsStampedWithTheStoredNextTurnIndex() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - await store.AppendAsync( - "c1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { NextTurnIndex = 7 }, - Token); - - // Act - var row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); - - // Assert - Assert.Equal(7, row.TurnIndex); - } + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", message, Token); - [Fact] - public async Task AppendAsync_AConversationThatDoesNotExist_ThrowsNamingIt() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); + // Assert + Assert.Equal("caller-named", row.MessageId); + } - // Act - var failure = await Record.ExceptionAsync( - () => store.AppendMessageAsync("missing", new ChatMessage(ChatRole.User, "hello"), Token).AsTask()); - - // Assert - var invalid = Assert.IsType(failure); - Assert.Contains("missing", invalid.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AppendAsync_TwoOutsideAppends_AreNumberedZeroThenOne() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + + // Act + ConversationMessage first = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); + ConversationMessage second = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); + + // Assert + Assert.Equal(0, first.Ordinal); + Assert.Equal(1, second.Ordinal); + ConversationRecord? conversation = await store.GetAsync("c1", Token); + Assert.Equal(2, conversation?.NextOrdinal); + } + + [Fact] + public async Task AppendAsync_ABatchWithAnExplicitTurnIndex_NumbersThreeConsecutiveRowsInDraftOrder() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); + + ConversationMessageDraft[] drafts = + [ + new(4, new ChatMessage(ChatRole.User, "a"), "m-a"), + new(4, new ChatMessage(ChatRole.Assistant, "b"), "m-b"), + new(4, new ChatMessage(ChatRole.User, "c"), "m-c"), + ]; + + // Act + IReadOnlyList rows = await store.AppendAsync("c1", drafts, cancellationToken: Token); + + // Assert + Assert.Equal([1, 2, 3], rows.Select(row => row.Ordinal)); + Assert.All(rows, row => Assert.Equal(4, row.TurnIndex)); + Assert.Equal(["m-a", "m-b", "m-c"], rows.Select(row => row.MessageId)); + } + + [Fact] + public async Task AppendAsync_OutsideAppend_AfterABatchThatWroteState_IsStampedWithTheStoredNextTurnIndex() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync( + "c1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { NextTurnIndex = 7 }, + Token); + + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); + + // Assert + Assert.Equal(7, row.TurnIndex); + } + + [Fact] + public async Task AppendAsync_AConversationThatDoesNotExist_ThrowsNamingIt() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); - [Fact] - public async Task RewriteAsync_OneRow_ChangesOnlyThatRowsContent() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "first") { MessageId = "m0" }, Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "second") { MessageId = "m1" }, Token); - - // Act - await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.User, "corrected"), Token); - - // Assert - var rows = await store.ReadAllAsync("c1", Token); - Assert.Equal(["corrected", "second"], rows.Select(row => row.Content.Text)); - } + // Act + Exception? failure = await Record.ExceptionAsync( + () => store.AppendMessageAsync("missing", new ChatMessage(ChatRole.User, "hello"), Token).AsTask()); - [Fact] - public async Task AppendAsync_AfterATruncate_NeverReusesTheOrdinalsItTook() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "zero"), Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); - await store.TruncateAsync("c1", 1, Token); - - // Act - var row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "three"), Token); - - // Assert - Assert.Equal(3, row.Ordinal); - } + // Assert + InvalidOperationException invalid = Assert.IsType(failure); + Assert.Contains("missing", invalid.Message, StringComparison.Ordinal); + } - [Fact] - public async Task AppendAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() - { - // Arrange - IConversationStore store = new InMemoryConversationStore(); - await store.CreateAsync("c1", Token); - ChatMessage message = new(ChatRole.User, "hello") + [Fact] + public async Task RewriteAsync_OneRow_ChangesOnlyThatRowsContent() { - AdditionalProperties = new() { ["speaker"] = "human" }, - }; - - // Act - await store.AppendMessageAsync("c1", message, Token); - - // Assert - var rows = await store.ReadAllAsync("c1", Token); - Assert.Equal("human", Assert.Single(rows).Content.AdditionalProperties?["speaker"]?.ToString()); + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "first") { MessageId = "m0" }, Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "second") { MessageId = "m1" }, Token); + + // Act + await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.User, "corrected"), Token); + + // Assert + IReadOnlyList rows = await store.ReadAllAsync("c1", Token); + Assert.Equal(["corrected", "second"], rows.Select(row => row.Content.Text)); + } + + [Fact] + public async Task AppendAsync_AfterATruncate_NeverReusesTheOrdinalsItTook() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "zero"), Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); + _ = await store.TruncateAsync("c1", 1, Token); + + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "three"), Token); + + // Assert + Assert.Equal(3, row.Ordinal); + } + + [Fact] + public async Task AppendAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() + { + // Arrange + IConversationStore store = new InMemoryConversationStore(); + _ = await store.CreateAsync("c1", Token); + ChatMessage message = new(ChatRole.User, "hello") + { + AdditionalProperties = new() { ["speaker"] = "human" }, + }; + + // Act + _ = await store.AppendMessageAsync("c1", message, Token); + + // Assert + IReadOnlyList rows = await store.ReadAllAsync("c1", Token); + Assert.Equal("human", Assert.Single(rows).Content.AdditionalProperties?["speaker"]?.ToString()); + } + + [GeneratedRegex("^[0-9a-f]{32}$")] + private static partial Regex HexId(); } - - [GeneratedRegex("^[0-9a-f]{32}$")] - private static partial Regex HexId(); -} #pragma warning restore CA1859 +} diff --git a/tests/AgentCore.Application.Tests/Diagnostics/DiagnosticsFakes.cs b/tests/AgentCore.Application.Tests/Diagnostics/DiagnosticsFakes.cs index 726b261c..1aefdc95 100644 --- a/tests/AgentCore.Application.Tests/Diagnostics/DiagnosticsFakes.cs +++ b/tests/AgentCore.Application.Tests/Diagnostics/DiagnosticsFakes.cs @@ -2,115 +2,130 @@ using AgentCore.Domain.Audit; using Microsoft.Extensions.Logging; -namespace AgentCore.Application.Tests.Diagnostics; - -/// -/// One line the library wrote. -/// -/// How serious the line is. -/// The id the source-generated method carries. -/// The formatted text. -/// The cause, when the line carried one. -internal sealed record LogLine(LogLevel Level, int EventId, string Message, Exception? Exception); - -/// -/// A logger a test reads back. It keeps every line, in the order the library wrote them. -/// -internal sealed class RecordingLogger : ILogger +namespace AgentCore.Application.Tests.Diagnostics { - private readonly Lock _gate = new(); - private readonly List _lines = []; - - /// Gets the lines the library wrote, oldest first. - public IReadOnlyList Lines + /// + /// One line the library wrote. + /// + /// How serious the line is. + /// The id the source-generated method carries. + /// The formatted text. + /// The cause, when the line carried one. + internal sealed record LogLine(LogLevel Level, int EventId, string Message, Exception? Exception); + + /// + /// A logger a test reads back. It keeps every line, in the order the library wrote them. + /// + internal sealed class RecordingLogger : ILogger { - get + private readonly Lock _gate = new(); + private readonly List _lines = []; + + /// Gets the lines the library wrote, oldest first. + public IReadOnlyList Lines { - lock (_gate) + get { - return [.. _lines]; + lock (_gate) + { + return [.. _lines]; + } } } - } - /// Reads back the lines of one event id. - /// The id the source-generated method carries. - /// Those lines, oldest first. - public IReadOnlyList Of(int eventId) => [.. Lines.Where(line => line.EventId == eventId)]; + /// Reads back the lines of one event id. + /// The id the source-generated method carries. + /// Those lines, oldest first. + public IReadOnlyList Of(int eventId) + { + return [.. Lines.Where(line => line.EventId == eventId)]; + } + + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } - public IDisposable? BeginScope(TState state) - where TState : notnull => null; + public bool IsEnabled(LogLevel logLevel) + { + return true; + } - public bool IsEnabled(LogLevel logLevel) => true; + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + ArgumentNullException.ThrowIfNull(formatter); + + lock (_gate) + { + _lines.Add(new LogLine(logLevel, eventId.Id, formatter(state, exception), exception)); + } + } + } - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + /// + /// A sink that holds every append open until a test releases it. + /// + /// + /// Section 7 measures a durable insert at 13 ms p50 and 32 ms p99, against 91 nanoseconds to + /// enqueue, so the turn must never wait for the row. This sink turns that into a question a test + /// answers without a stopwatch: the turn finishes while every append is still open. + /// + internal sealed class BlockingAuditSink : IAuditSinkPort { - ArgumentNullException.ThrowIfNull(formatter); + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly Lock _lock = new(); + private readonly List _events = []; - lock (_gate) + /// Gets the events this sink took, in the order they arrived. + public IReadOnlyList Events { - _lines.Add(new LogLine(logLevel, eventId.Id, formatter(state, exception), exception)); + get + { + lock (_lock) + { + return [.. _events]; + } + } } - } -} -/// -/// A sink that holds every append open until a test releases it. -/// -/// -/// Section 7 measures a durable insert at 13 ms p50 and 32 ms p99, against 91 nanoseconds to -/// enqueue, so the turn must never wait for the row. This sink turns that into a question a test -/// answers without a stopwatch: the turn finishes while every append is still open. -/// -internal sealed class BlockingAuditSink : IAuditSinkPort -{ - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly Lock _lock = new(); - private readonly List _events = []; + /// Lets every open append complete. + public void Release() + { + _ = _gate.TrySetResult(); + } - /// Gets the events this sink took, in the order they arrived. - public IReadOnlyList Events - { - get + public async ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { lock (_lock) { - return [.. _events]; + _events.Add(auditEvent); } + + await _gate.Task.ConfigureAwait(false); } } - /// Lets every open append complete. - public void Release() => _gate.TrySetResult(); - - public async ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) + /// + /// A sink that refuses every event. + /// + /// + /// Audit is a record of the conversation and never a part of it, so a sink that fails must be reported and + /// the turn must go on. + /// + internal sealed class ThrowingAuditSink : IAuditSinkPort { - lock (_lock) + /// The message every refusal carries. + public const string Message = "the audit store is unreachable."; + + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { - _events.Add(auditEvent); + throw new InvalidOperationException(Message); } - - await _gate.Task.ConfigureAwait(false); } } - -/// -/// A sink that refuses every event. -/// -/// -/// Audit is a record of the conversation and never a part of it, so a sink that fails must be reported and -/// the turn must go on. -/// -internal sealed class ThrowingAuditSink : IAuditSinkPort -{ - /// The message every refusal carries. - public const string Message = "the audit store is unreachable."; - - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - => throw new InvalidOperationException(Message); -} diff --git a/tests/AgentCore.Application.Tests/Diagnostics/LibraryOpenTelemetryTests.cs b/tests/AgentCore.Application.Tests/Diagnostics/LibraryOpenTelemetryTests.cs index 50719b6b..d9e61d89 100644 --- a/tests/AgentCore.Application.Tests/Diagnostics/LibraryOpenTelemetryTests.cs +++ b/tests/AgentCore.Application.Tests/Diagnostics/LibraryOpenTelemetryTests.cs @@ -13,47 +13,47 @@ using System.Diagnostics; using Xunit; -namespace AgentCore.Application.Tests.Diagnostics; - -/// -/// Task 6a: Microsoft.Extensions.AI's and Microsoft.Agents.AI's own GenAI instrumentation, switched on -/// for the first time. AgentCoreTelemetry.cs asserted both libraries "already emit" their spans -/// and metrics; before this task nothing ever called UseOpenTelemetry, so nothing did. -/// -/// -/// -/// Every test here proves something an or a direct -/// GetService probe observed, not merely that the wiring compiles. -/// 's WithToolFailureAuditing and Resolve remarks -/// explain WHERE the instrumentation sits and WHY; this file is the proof those remarks describe what -/// the compiled pipeline actually does. -/// -/// -/// Every agent id and conversation id here is unique per test run (a fresh ), because an -/// subscribes to the whole process and another test class may run -/// beside this one on the same two library sources. -/// -/// -public sealed class LibraryOpenTelemetryTests +namespace AgentCore.Application.Tests.Diagnostics { - /// The default source name OpenTelemetryChatClient (Microsoft.Extensions.AI 10.8.3) - /// resolves to when a caller names none. Read out of the restored assembly; see - /// ConfigurationCompiler.WithToolFailureAuditing. - private const string ChatSourceName = "Experimental.Microsoft.Extensions.AI"; - - /// The default source name OpenTelemetryAgent (Microsoft.Agents.AI 1.17.0) resolves - /// to when a caller names none. Read out of the restored assembly; see - /// ConfigurationCompiler.BuildAgents. - private const string AgentSourceName = "Experimental.Microsoft.Agents.AI"; - - // ------------------------------------------------------------------------------------------- - // The ordering fix: execute_tool nests under invoke_agent, not beside it. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AToolCallingTurn_NestsExecuteToolUnderInvokeAgentAndNotBesideIt() + /// + /// Task 6a: Microsoft.Extensions.AI's and Microsoft.Agents.AI's own GenAI instrumentation, switched on + /// for the first time. AgentCoreTelemetry.cs asserted both libraries "already emit" their spans + /// and metrics; before this task nothing ever called UseOpenTelemetry, so nothing did. + /// + /// + /// + /// Every test here proves something an or a direct + /// GetService probe observed, not merely that the wiring compiles. + /// 's WithToolFailureAuditing and Resolve remarks + /// explain WHERE the instrumentation sits and WHY; this file is the proof those remarks describe what + /// the compiled pipeline actually does. + /// + /// + /// Every agent id and conversation id here is unique per test run (a fresh ), because an + /// subscribes to the whole process and another test class may run + /// beside this one on the same two library sources. + /// + /// + public sealed class LibraryOpenTelemetryTests { - var agentId = "agent-" + Guid.NewGuid().ToString("N"); - var yaml = $$""" + /// The default source name OpenTelemetryChatClient (Microsoft.Extensions.AI 10.8.3) + /// resolves to when a caller names none. Read out of the restored assembly; see + /// ConfigurationCompiler.WithToolFailureAuditing. + private const string ChatSourceName = "Experimental.Microsoft.Extensions.AI"; + + /// The default source name OpenTelemetryAgent (Microsoft.Agents.AI 1.17.0) resolves + /// to when a caller names none. Read out of the restored assembly; see + /// ConfigurationCompiler.BuildAgents. + private const string AgentSourceName = "Experimental.Microsoft.Agents.AI"; + + // ------------------------------------------------------------------------------------------- + // The ordering fix: execute_tool nests under invoke_agent, not beside it. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AToolCallingTurn_NestsExecuteToolUnderInvokeAgentAndNotBesideIt() + { + string agentId = "agent-" + Guid.NewGuid().ToString("N"); + string yaml = $$""" apiVersion: agentcore/v1 tools: - { id: lookup_order, kind: builtin, uses: orders.read, description: "Look up an order by its id." } @@ -65,60 +65,60 @@ public async Task AToolCallingTurn_NestsExecuteToolUnderInvokeAgentAndNotBesideI agent: {{agentId}} """; - List spans = []; - using var listener = ListenToLibrarySources(spans); - - using ToolCallingChatClient client = new("the order shipped."); - StubToolBuilder tools = new("""{ "status": "shipped" }"""); - - var session = Build(yaml, client, tools.Create).Create(); - - await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - var mine = Snapshot(spans); - - // OpenTelemetryAgent.RunCoreAsync relabels the span its own OpenTelemetryChatClient opens, so - // the operation this test looks for lives on DisplayName ("invoke_agent {name}({id})"), not on - // Activity.OperationName (which stays "chat" — verified by decompiling - // Microsoft.Extensions.AI.OpenTelemetryChatClient.GetResponseAsync). - var invokeAgent = Assert.Single( - mine, span => span.DisplayName.StartsWith("invoke_agent " + agentId, StringComparison.Ordinal)); - - // The listener subscribes to the whole process, and xUnit runs other test classes beside this - // one that also compile agents on these same two default source names. Everything from here - // down is scoped to children of THIS run's own invoke_agent (a per-test unique W3C span id), - // so a concurrent test's spans on the same sources cannot leak into these counts. - var underInvokeAgent = mine.Where(span => string.Equals(span.ParentId, invokeAgent.Id, StringComparison.Ordinal)).ToList(); - - // FunctionInvocationProcessor names its own span "execute_tool {toolName}" directly through - // ActivitySource.StartActivity, so OperationName is reliable here. - var executeTool = Assert.Single( - underInvokeAgent, span => span.OperationName.StartsWith("execute_tool", StringComparison.Ordinal)); - - // The actual proof the ordering fix worked: execute_tool's parent IS invoke_agent, by object - // identity and by W3C parent id — not a sibling of it, and not nested inside the whole - // tool-calling loop as one "chat" span the way the broken ordering produced. See the "Chat - // telemetry is wired here" remark on WithToolFailureAuditing for why the fix makes this true: - // the per-round chat span (source "Experimental.Microsoft.Extensions.AI") closes before the - // tool runs, so Activity.Current has reverted to invoke_agent by the time execute_tool opens. - Assert.Same(invokeAgent, executeTool.Parent); - - // And the per-round chat spans exist too (one for the round that decided to call the tool, one - // for the round that answered after the tool result), as siblings of execute_tool under the - // same parent — not merged into the tool loop, and not swallowing it. - var chatRounds = underInvokeAgent.Where(IsChatRoundSpan).ToList(); - Assert.Equal(2, chatRounds.Count); - } - - // ------------------------------------------------------------------------------------------- - // Exactly once: every compiled agent is wrapped for OpenTelemetry, and none is wrapped twice. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task EveryCompiledAgent_IsInstrumentedExactlyOnce() - { - var frontId = "front-" + Guid.NewGuid().ToString("N"); - var specialistId = "specialist-" + Guid.NewGuid().ToString("N"); - var yaml = $$""" + List spans = []; + using ActivityListener listener = ListenToLibrarySources(spans); + + using ToolCallingChatClient client = new("the order shipped."); + StubToolBuilder tools = new(/*lang=json,strict*/ """{ "status": "shipped" }"""); + + ConversationSession session = Build(yaml, client, tools.Create).Create(); + + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + List mine = Snapshot(spans); + + // OpenTelemetryAgent.RunCoreAsync relabels the span its own OpenTelemetryChatClient opens, so + // the operation this test looks for lives on DisplayName ("invoke_agent {name}({id})"), not on + // Activity.OperationName (which stays "chat" — verified by decompiling + // Microsoft.Extensions.AI.OpenTelemetryChatClient.GetResponseAsync). + Activity invokeAgent = Assert.Single( + mine, span => span.DisplayName.StartsWith("invoke_agent " + agentId, StringComparison.Ordinal)); + + // The listener subscribes to the whole process, and xUnit runs other test classes beside this + // one that also compile agents on these same two default source names. Everything from here + // down is scoped to children of THIS run's own invoke_agent (a per-test unique W3C span id), + // so a concurrent test's spans on the same sources cannot leak into these counts. + List underInvokeAgent = [.. mine.Where(span => string.Equals(span.ParentId, invokeAgent.Id, StringComparison.Ordinal))]; + + // FunctionInvocationProcessor names its own span "execute_tool {toolName}" directly through + // ActivitySource.StartActivity, so OperationName is reliable here. + Activity executeTool = Assert.Single( + underInvokeAgent, span => span.OperationName.StartsWith("execute_tool", StringComparison.Ordinal)); + + // The actual proof the ordering fix worked: execute_tool's parent IS invoke_agent, by object + // identity and by W3C parent id — not a sibling of it, and not nested inside the whole + // tool-calling loop as one "chat" span the way the broken ordering produced. See the "Chat + // telemetry is wired here" remark on WithToolFailureAuditing for why the fix makes this true: + // the per-round chat span (source "Experimental.Microsoft.Extensions.AI") closes before the + // tool runs, so Activity.Current has reverted to invoke_agent by the time execute_tool opens. + Assert.Same(invokeAgent, executeTool.Parent); + + // And the per-round chat spans exist too (one for the round that decided to call the tool, one + // for the round that answered after the tool result), as siblings of execute_tool under the + // same parent — not merged into the tool loop, and not swallowing it. + List chatRounds = [.. underInvokeAgent.Where(IsChatRoundSpan)]; + Assert.Equal(2, chatRounds.Count); + } + + // ------------------------------------------------------------------------------------------- + // Exactly once: every compiled agent is wrapped for OpenTelemetry, and none is wrapped twice. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task EveryCompiledAgent_IsInstrumentedExactlyOnce() + { + string frontId = "front-" + Guid.NewGuid().ToString("N"); + string specialistId = "specialist-" + Guid.NewGuid().ToString("N"); + string yaml = $$""" apiVersion: agentcore/v1 tools: - { id: ask_specialist, kind: agent, agent: {{specialistId}}, description: Ask the specialist. } @@ -134,56 +134,56 @@ public async Task EveryCompiledAgent_IsInstrumentedExactlyOnce() - { id: talk, agent: {{frontId}}, terminal: true } """; - var document = ConfigurationLoader.LoadYaml(yaml); - - // Reachable structurally, with no turn run at all: ConfigurationCompiler.Resolve wraps the - // agent it just built, once, immediately before it caches it in the dictionary every later - // lookup (row 2's stage lookup, and the delegation tool's ResolveInner) reads back out of. A - // second wrap would require Resolve to reach the "var built = new ChatClientAgent(...)" branch - // twice for one id, and the early "agents.TryGetValue" return above it is what this test would - // catch failing to hold. - using ToolCallingChatClient buildOnlyClient = new("unused"); - var compiledOnly = ConfigurationCompiler.CompileAll( - document, new AgentCompilationContext(new FakeChatClientFactory(buildOnlyClient)))["main"]; - - Assert.IsType(compiledOnly.Agents[frontId]); - Assert.IsType(compiledOnly.Agents[frontId].GetService()); - Assert.IsType(compiledOnly.Agents[specialistId]); - Assert.IsType(compiledOnly.Agents[specialistId].GetService()); - - // The behavioural half of the same proof: running a turn that calls through the delegation - // path produces exactly one invoke_agent span for each agent. Two OpenTelemetryAgent layers - // around the same ChatClientAgent would double whichever agent got wrapped twice; a missing - // wrap would mean zero. - List spans = []; - using var listener = ListenToLibrarySources(spans); - - // AsAIFunction() generates one required string argument named "query" (no parameters: is - // declared on ask_specialist), so the model call must fill it or the delegation throws - // ArgumentException before ever reaching the specialist agent. - using ToolCallingChatClient client = new( - "the specialist answer", new Dictionary(StringComparer.Ordinal) { ["query"] = "help me" }); - var session = Build(yaml, client, tools: null).Create(); - - await session.RunTurnAsync("help me", TestContext.Current.CancellationToken); - - var mine = Snapshot(spans); - - Assert.Single(mine, span => span.DisplayName.StartsWith("invoke_agent " + frontId, StringComparison.Ordinal)); - Assert.Single( - mine, span => span.DisplayName.StartsWith("invoke_agent " + specialistId, StringComparison.Ordinal)); - } - - // ------------------------------------------------------------------------------------------- - // The absolute constraint: EnableSensitiveData stays false on both the agent-level and the - // chat-level instrumentation, regardless of what OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - // says in the environment this test happens to run in. - // ------------------------------------------------------------------------------------------- - [Fact] - public void EveryCompiledAgent_KeepsSensitiveDataCaptureOffOnBothLayers() - { - var agentId = "agent-" + Guid.NewGuid().ToString("N"); - var yaml = $$""" + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + + // Reachable structurally, with no turn run at all: ConfigurationCompiler.Resolve wraps the + // agent it just built, once, immediately before it caches it in the dictionary every later + // lookup (row 2's stage lookup, and the delegation tool's ResolveInner) reads back out of. A + // second wrap would require Resolve to reach the "var built = new ChatClientAgent(...)" branch + // twice for one id, and the early "agents.TryGetValue" return above it is what this test would + // catch failing to hold. + using ToolCallingChatClient buildOnlyClient = new("unused"); + CompiledAgent compiledOnly = ConfigurationCompiler.CompileAll( + document, new AgentCompilationContext(new FakeChatClientFactory(buildOnlyClient)))["main"]; + + _ = Assert.IsType(compiledOnly.Agents[frontId]); + _ = Assert.IsType(compiledOnly.Agents[frontId].GetService()); + _ = Assert.IsType(compiledOnly.Agents[specialistId]); + _ = Assert.IsType(compiledOnly.Agents[specialistId].GetService()); + + // The behavioural half of the same proof: running a turn that calls through the delegation + // path produces exactly one invoke_agent span for each agent. Two OpenTelemetryAgent layers + // around the same ChatClientAgent would double whichever agent got wrapped twice; a missing + // wrap would mean zero. + List spans = []; + using ActivityListener listener = ListenToLibrarySources(spans); + + // AsAIFunction() generates one required string argument named "query" (no parameters: is + // declared on ask_specialist), so the model call must fill it or the delegation throws + // ArgumentException before ever reaching the specialist agent. + using ToolCallingChatClient client = new( + "the specialist answer", new Dictionary(StringComparer.Ordinal) { ["query"] = "help me" }); + ConversationSession session = Build(yaml, client, tools: null).Create(); + + _ = await session.RunTurnAsync("help me", TestContext.Current.CancellationToken); + + List mine = Snapshot(spans); + + _ = Assert.Single(mine, span => span.DisplayName.StartsWith("invoke_agent " + frontId, StringComparison.Ordinal)); + _ = Assert.Single( + mine, span => span.DisplayName.StartsWith("invoke_agent " + specialistId, StringComparison.Ordinal)); + } + + // ------------------------------------------------------------------------------------------- + // The absolute constraint: EnableSensitiveData stays false on both the agent-level and the + // chat-level instrumentation, regardless of what OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT + // says in the environment this test happens to run in. + // ------------------------------------------------------------------------------------------- + [Fact] + public void EveryCompiledAgent_KeepsSensitiveDataCaptureOffOnBothLayers() + { + string agentId = "agent-" + Guid.NewGuid().ToString("N"); + string yaml = $$""" apiVersion: agentcore/v1 agents: items: @@ -193,49 +193,49 @@ public void EveryCompiledAgent_KeepsSensitiveDataCaptureOffOnBothLayers() agent: {{agentId}} """; - using ToolCallingChatClient client = new("hello"); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; - - var otelAgent = Assert.IsType(compiled.Agent); - - // OpenTelemetryAgent.EnableSensitiveData otherwise defaults to - // TelemetryHelpers.EnableSensitiveDataDefault, which reads - // OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT from the environment. This repo carries - // live customer phone conversations, so ConfigurationCompiler forces it false explicitly rather than - // trusting that variable to stay unset. - Assert.False(otelAgent.EnableSensitiveData); - - // The chat-level layer WithToolFailureAuditing wires in below AuditingFunctionInvokingChatClient - // is a second, independent OpenTelemetryChatClient instance with its own EnableSensitiveData, - // and it is forced off the same way, at the same conversation site. - var chatClient = compiled.Agent.GetService(); - Assert.NotNull(chatClient); - Assert.False(chatClient.EnableSensitiveData); - } - - // ------------------------------------------------------------------------------------------- - // gen_ai.conversation.id: the parent span carries it, and the library children do not. - // ------------------------------------------------------------------------------------------- - - /// - /// The conversation id reaches a trace once, from AgentCoreTelemetry.StartTurn. - /// - /// - /// Naming the conversation on ChatOptions.ConversationId would put the attribute on the library's - /// children as well, and it is the one thing that must not be done to get it. To - /// ChatClientAgent a conversation id means the SERVICE keeps the history, so it answers by - /// ignoring the agent's own ChatHistoryProvider for the whole run — store 1, silently - /// gone. Keeping it then costs a per-run override of the provider and - /// ThrowOnChatHistoryProviderConflict = false on every compiled agent. The attribute is - /// not worth a disabled safety check: a reader that wants the conversation id of a child span walks up - /// the trace to agentcore.turn. - /// - [Fact] - public async Task ASingleAgentTurn_CarriesTheConversationIdOnTheTurnSpanAndOnNeitherLibrarySpan() - { - var agentId = "agent-" + Guid.NewGuid().ToString("N"); - var yaml = $$""" + using ToolCallingChatClient client = new("hello"); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; + + OpenTelemetryAgent otelAgent = Assert.IsType(compiled.Agent); + + // OpenTelemetryAgent.EnableSensitiveData otherwise defaults to + // TelemetryHelpers.EnableSensitiveDataDefault, which reads + // OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT from the environment. This repo carries + // live customer phone conversations, so ConfigurationCompiler forces it false explicitly rather than + // trusting that variable to stay unset. + Assert.False(otelAgent.EnableSensitiveData); + + // The chat-level layer WithToolFailureAuditing wires in below AuditingFunctionInvokingChatClient + // is a second, independent OpenTelemetryChatClient instance with its own EnableSensitiveData, + // and it is forced off the same way, at the same conversation site. + OpenTelemetryChatClient? chatClient = compiled.Agent.GetService(); + Assert.NotNull(chatClient); + Assert.False(chatClient.EnableSensitiveData); + } + + // ------------------------------------------------------------------------------------------- + // gen_ai.conversation.id: the parent span carries it, and the library children do not. + // ------------------------------------------------------------------------------------------- + + /// + /// The conversation id reaches a trace once, from AgentCoreTelemetry.StartTurn. + /// + /// + /// Naming the conversation on ChatOptions.ConversationId would put the attribute on the library's + /// children as well, and it is the one thing that must not be done to get it. To + /// ChatClientAgent a conversation id means the SERVICE keeps the history, so it answers by + /// ignoring the agent's own ChatHistoryProvider for the whole run — store 1, silently + /// gone. Keeping it then costs a per-run override of the provider and + /// ThrowOnChatHistoryProviderConflict = false on every compiled agent. The attribute is + /// not worth a disabled safety check: a reader that wants the conversation id of a child span walks up + /// the trace to agentcore.turn. + /// + [Fact] + public async Task ASingleAgentTurn_CarriesTheConversationIdOnTheTurnSpanAndOnNeitherLibrarySpan() + { + string agentId = "agent-" + Guid.NewGuid().ToString("N"); + string yaml = $$""" apiVersion: agentcore/v1 agents: items: @@ -245,57 +245,57 @@ public async Task ASingleAgentTurn_CarriesTheConversationIdOnTheTurnSpanAndOnNei agent: {{agentId}} """; - List spans = []; - using var libraries = ListenToLibrarySources(spans); - using var turns = ListenTo(spans, AgentCoreTelemetry.ActivitySourceName); - - using ToolCallingChatClient client = new("hello there."); - var conversationId = "conversation-" + Guid.NewGuid().ToString("N"); - var session = Build(yaml, client, tools: null).Create(conversationId); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var mine = Snapshot(spans); - - var invokeAgent = Assert.Single( - mine, span => span.DisplayName.StartsWith("invoke_agent " + agentId, StringComparison.Ordinal)); - - // Scoped to this run's own invoke_agent for the same reason as the nesting test above: other - // test classes compile agents on these same two sources concurrently. - var chat = Assert.Single( - mine, span => IsChatRoundSpan(span) && string.Equals(span.ParentId, invokeAgent.Id, StringComparison.Ordinal)); - - var turn = Assert.Single( - mine, - span => span.DisplayName == AgentCoreTelemetry.TurnActivityName - && string.Equals(span.Id, invokeAgent.ParentId, StringComparison.Ordinal)); - - Assert.Equal(conversationId, turn.GetTagItem("gen_ai.conversation.id")); - Assert.Null(invokeAgent.GetTagItem("gen_ai.conversation.id")); - Assert.Null(chat.GetTagItem("gen_ai.conversation.id")); - } - - // ------------------------------------------------------------------------------------------- - // The extractor is a model call too, and a model call the trace does not show is a model call - // nobody pays attention to until the bill arrives. - // ------------------------------------------------------------------------------------------- - - /// - /// One turn makes two model calls, and both of them emit a chat span. - /// - /// - /// ConversationSessionTests.ATurn_MakesTwoModelCalls_TheReplyAndTheExtractor proves the two conversations - /// happen. This proves both are instrumented. Until ConversationSessionFactory.CreateExtractor - /// wrapped the client it resolves, only the reply had a span: the extractor's duration, its token - /// usage, and its failures reached no exporter at all, so a two-turn conversation reported half the model - /// calls it made and roughly a third less spend than it cost. - /// - [Fact] - public async Task ATurnWithAnExtractor_EmitsAChatSpanForTheExtractorCallAndNotOnlyForTheReply() - { - var greeterId = "greeter-" + Guid.NewGuid().ToString("N"); - var closerId = "closer-" + Guid.NewGuid().ToString("N"); - var yaml = $$""" + List spans = []; + using ActivityListener libraries = ListenToLibrarySources(spans); + using ActivityListener turns = ListenTo(spans, AgentCoreTelemetry.ActivitySourceName); + + using ToolCallingChatClient client = new("hello there."); + string conversationId = "conversation-" + Guid.NewGuid().ToString("N"); + ConversationSession session = Build(yaml, client, tools: null).Create(conversationId); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + List mine = Snapshot(spans); + + Activity invokeAgent = Assert.Single( + mine, span => span.DisplayName.StartsWith("invoke_agent " + agentId, StringComparison.Ordinal)); + + // Scoped to this run's own invoke_agent for the same reason as the nesting test above: other + // test classes compile agents on these same two sources concurrently. + Activity chat = Assert.Single( + mine, span => IsChatRoundSpan(span) && string.Equals(span.ParentId, invokeAgent.Id, StringComparison.Ordinal)); + + Activity turn = Assert.Single( + mine, + span => span.DisplayName == AgentCoreTelemetry.TurnActivityName + && string.Equals(span.Id, invokeAgent.ParentId, StringComparison.Ordinal)); + + Assert.Equal(conversationId, turn.GetTagItem("gen_ai.conversation.id")); + Assert.Null(invokeAgent.GetTagItem("gen_ai.conversation.id")); + Assert.Null(chat.GetTagItem("gen_ai.conversation.id")); + } + + // ------------------------------------------------------------------------------------------- + // The extractor is a model call too, and a model call the trace does not show is a model call + // nobody pays attention to until the bill arrives. + // ------------------------------------------------------------------------------------------- + + /// + /// One turn makes two model calls, and both of them emit a chat span. + /// + /// + /// ConversationSessionTests.ATurn_MakesTwoModelCalls_TheReplyAndTheExtractor proves the two conversations + /// happen. This proves both are instrumented. Until ConversationSessionFactory.CreateExtractor + /// wrapped the client it resolves, only the reply had a span: the extractor's duration, its token + /// usage, and its failures reached no exporter at all, so a two-turn conversation reported half the model + /// calls it made and roughly a third less spend than it cost. + /// + [Fact] + public async Task ATurnWithAnExtractor_EmitsAChatSpanForTheExtractorCallAndNotOnlyForTheReply() + { + string greeterId = "greeter-" + Guid.NewGuid().ToString("N"); + string closerId = "closer-" + Guid.NewGuid().ToString("N"); + string yaml = $$""" apiVersion: agentcore/v1 state: callerSaidGoodbye: @@ -327,141 +327,146 @@ public async Task ATurnWithAnExtractor_EmitsAChatSpanForTheExtractorCallAndNotOn terminal: true """; - List spans = []; - using var libraries = ListenToLibrarySources(spans); - using var turns = ListenTo(spans, AgentCoreTelemetry.ActivitySourceName); - - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new("""{ "callerSaidGoodbye": null }"""); - - var conversationId = "conversation-" + Guid.NewGuid().ToString("N"); - var session = BuildWithExtractor(yaml, reply, fill).Create(conversationId); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // The premise: two clients, one call each. If this ever reads differently the span counts - // below mean nothing. - Assert.Equal(1, reply.Calls); - Assert.Equal(1, fill.Calls); - - var mine = Snapshot(spans); - - // Scoped by this run's own conversation id, because the listener subscribes to the whole process. - var turn = Assert.Single( - mine, - span => span.DisplayName == AgentCoreTelemetry.TurnActivityName - && string.Equals((string?)span.GetTagItem("gen_ai.conversation.id"), conversationId, StringComparison.Ordinal)); - - var invokeAgent = Assert.Single( - mine, - span => span.DisplayName.StartsWith("invoke_agent " + greeterId, StringComparison.Ordinal) - && string.Equals(span.ParentId, turn.Id, StringComparison.Ordinal)); - - // The reply's chat span sits under invoke_agent, where ConfigurationCompiler puts it. - Assert.Single( - mine, - span => IsChatRoundSpan(span) && string.Equals(span.ParentId, invokeAgent.Id, StringComparison.Ordinal)); - - // The extractor's chat span is the one this test exists for. It hangs directly off the turn - // span and not off invoke_agent, because ConversationSession runs the extractor after the agent's run - // has finished and its spans have closed, with Activity.Current back at agentcore.turn. - var extractorChat = Assert.Single( - mine, - span => IsChatRoundSpan(span) && string.Equals(span.ParentId, turn.Id, StringComparison.Ordinal)); - - // Instrumented the same way as every other model call in this library: the default source - // name, so a host already receiving agent chat spans receives this one with no second - // AddSource, and no message content on the span. - Assert.Equal(ChatSourceName, extractorChat.Source.Name); - Assert.Null(extractorChat.GetTagItem("gen_ai.input.messages")); - } - - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - /// - /// Whether one span is a per-round model call and not the relabeled invoke_agent span. - /// - /// - /// OpenTelemetryAgent opens its own invoke_agent span through an internal - /// OpenTelemetryChatClient instance, so that span's own Activity.OperationName is - /// also "chat" — only its DisplayName is rewritten. A filter on OperationName - /// alone therefore matches both the real per-round chat span this predicate looks for and the - /// invoke_agent span beside it; excluding the renamed DisplayName is what tells them apart. - /// - private static bool IsChatRoundSpan(Activity span) - => span.OperationName.StartsWith("chat", StringComparison.Ordinal) - && !span.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal); - - /// Subscribes to the two library sources this task turns on. - private static ActivityListener ListenToLibrarySources(List spans) - => ListenTo(spans, ChatSourceName, AgentSourceName); - - /// Subscribes to the named sources, collecting every span each one closes. - private static ActivityListener ListenTo(List spans, params string[] sources) - { - ActivityListener listener = new() - { - ShouldListenTo = source => Array.Exists(sources, name => string.Equals(source.Name, name, StringComparison.Ordinal)), - Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, - ActivityStopped = activity => - { - lock (spans) - { - spans.Add(activity); - } - }, - }; - - ActivitySource.AddActivityListener(listener); - return listener; - } - - /// Copies what the listener has collected so far. See the sibling helper in - /// TurnObservabilityTests for why a reader must not enumerate the live list. - private static List Snapshot(List spans) - { - lock (spans) - { - return [.. spans]; - } - } - - private static ConversationSessionFactory Build(string yaml, IChatClient client, Func? tools) - { - var document = ConfigurationLoader.LoadYaml(yaml); - FakeChatClientFactory factory = new(client); - - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(factory) - { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, factory), - timeProvider: null, - logger: null, - ConversationObservers.Standard(new InMemoryAuditSink(), logger: null)); - } - /// Builds a factory for a document that declares an extractor, scripting the two models - /// apart on the ref names the document uses. - private static ConversationSessionFactory BuildWithExtractor(string yaml, IChatClient reply, IChatClient fill) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var factory = new RoutingChatClientFactory(reply).Route("fill", fill); - - var compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(factory))["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, factory), - timeProvider: null, - logger: null, - ConversationObservers.Standard(new InMemoryAuditSink(), logger: null)); - } - } + List spans = []; + using ActivityListener libraries = ListenToLibrarySources(spans); + using ActivityListener turns = ListenTo(spans, AgentCoreTelemetry.ActivitySourceName); + + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(/*lang=json,strict*/ """{ "callerSaidGoodbye": null }"""); + + string conversationId = "conversation-" + Guid.NewGuid().ToString("N"); + ConversationSession session = BuildWithExtractor(yaml, reply, fill).Create(conversationId); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // The premise: two clients, one call each. If this ever reads differently the span counts + // below mean nothing. + Assert.Equal(1, reply.Calls); + Assert.Equal(1, fill.Calls); + + List mine = Snapshot(spans); + + // Scoped by this run's own conversation id, because the listener subscribes to the whole process. + Activity turn = Assert.Single( + mine, + span => span.DisplayName == AgentCoreTelemetry.TurnActivityName + && string.Equals((string?)span.GetTagItem("gen_ai.conversation.id"), conversationId, StringComparison.Ordinal)); + + Activity invokeAgent = Assert.Single( + mine, + span => span.DisplayName.StartsWith("invoke_agent " + greeterId, StringComparison.Ordinal) + && string.Equals(span.ParentId, turn.Id, StringComparison.Ordinal)); + + // The reply's chat span sits under invoke_agent, where ConfigurationCompiler puts it. + _ = Assert.Single( + mine, + span => IsChatRoundSpan(span) && string.Equals(span.ParentId, invokeAgent.Id, StringComparison.Ordinal)); + + // The extractor's chat span is the one this test exists for. It hangs directly off the turn + // span and not off invoke_agent, because ConversationSession runs the extractor after the agent's run + // has finished and its spans have closed, with Activity.Current back at agentcore.turn. + Activity extractorChat = Assert.Single( + mine, + span => IsChatRoundSpan(span) && string.Equals(span.ParentId, turn.Id, StringComparison.Ordinal)); + + // Instrumented the same way as every other model call in this library: the default source + // name, so a host already receiving agent chat spans receives this one with no second + // AddSource, and no message content on the span. + Assert.Equal(ChatSourceName, extractorChat.Source.Name); + Assert.Null(extractorChat.GetTagItem("gen_ai.input.messages")); + } + + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + /// + /// Whether one span is a per-round model call and not the relabeled invoke_agent span. + /// + /// + /// OpenTelemetryAgent opens its own invoke_agent span through an internal + /// OpenTelemetryChatClient instance, so that span's own Activity.OperationName is + /// also "chat" — only its DisplayName is rewritten. A filter on OperationName + /// alone therefore matches both the real per-round chat span this predicate looks for and the + /// invoke_agent span beside it; excluding the renamed DisplayName is what tells them apart. + /// + private static bool IsChatRoundSpan(Activity span) + { + return span.OperationName.StartsWith("chat", StringComparison.Ordinal) + && !span.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal); + } + + /// Subscribes to the two library sources this task turns on. + private static ActivityListener ListenToLibrarySources(List spans) + { + return ListenTo(spans, ChatSourceName, AgentSourceName); + } + + /// Subscribes to the named sources, collecting every span each one closes. + private static ActivityListener ListenTo(List spans, params string[] sources) + { + ActivityListener listener = new() + { + ShouldListenTo = source => Array.Exists(sources, name => string.Equals(source.Name, name, StringComparison.Ordinal)), + Sample = (ref _) => ActivitySamplingResult.AllData, + ActivityStopped = activity => + { + lock (spans) + { + spans.Add(activity); + } + }, + }; + + ActivitySource.AddActivityListener(listener); + return listener; + } + + /// Copies what the listener has collected so far. See the sibling helper in + /// TurnObservabilityTests for why a reader must not enumerate the live list. + private static List Snapshot(List spans) + { + lock (spans) + { + return [.. spans]; + } + } + + private static ConversationSessionFactory Build(string yaml, IChatClient client, Func? tools) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + FakeChatClientFactory factory = new(client); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(factory) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, factory), + timeProvider: null, + logger: null, + ConversationObservers.Standard(new InMemoryAuditSink(), logger: null)); + } + /// Builds a factory for a document that declares an extractor, scripting the two models + /// apart on the ref names the document uses. + private static ConversationSessionFactory BuildWithExtractor(string yaml, IChatClient reply, IChatClient fill) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory factory = new RoutingChatClientFactory(reply).Route("fill", fill); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(factory))["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, factory), + timeProvider: null, + logger: null, + ConversationObservers.Standard(new InMemoryAuditSink(), logger: null)); + } + } +} diff --git a/tests/AgentCore.Application.Tests/Diagnostics/LoggingConversationObserverTests.cs b/tests/AgentCore.Application.Tests/Diagnostics/LoggingConversationObserverTests.cs index 570cd54b..153a6ce2 100644 --- a/tests/AgentCore.Application.Tests/Diagnostics/LoggingConversationObserverTests.cs +++ b/tests/AgentCore.Application.Tests/Diagnostics/LoggingConversationObserverTests.cs @@ -4,214 +4,217 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.Application.Tests.Diagnostics; - -/// -/// The "log once" rows of section 8.7, written from a fact instead of from the turn loop. -/// -/// -/// Moving the conversation sites behind the hook must change neither the text an operator greps for nor how -/// often it appears, so these tests pin the event id, the level, and the fields of each of the six -/// lines. They also pin the six kinds that write nothing here: a normal conversation is recorded by the chain -/// of D23, and a log is not. -/// -public sealed class LoggingConversationObserverTests +namespace AgentCore.Application.Tests.Diagnostics { - private const string ConversationId = "conversation-1"; - - /// The ids the source-generated methods carry. They are unchanged by the hook. - private const int ExtractionFailedEventId = 1; - private const int ToolBudgetSpentEventId = 2; - private const int EmptyReplyEventId = 3; - private const int PromptRefusedEventId = 6; - private const int ModerationUnavailableEventId = 7; - private const int StateRestorePartialEventId = 13; - - /// The kinds this observer writes no line for. - public static TheoryData QuietKinds => - [ - ConversationEventKind.ConversationStarted, - ConversationEventKind.TurnCompleted, - ConversationEventKind.ReplyInterrupted, - ConversationEventKind.ConversationEnded, - - // Logged, but not here: the line is written where the write was refused, which is the only - // place the exception still exists. A line from this observer too would double it. - ConversationEventKind.TranscriptWriteFailed, - - // The quietest of them all: counted, and not logged anywhere. - ConversationEventKind.ModerationClean, - ]; - - [Fact] - public async Task ASpentToolBudget_IsAnErrorNamingTheTurnAndTheFault() + /// + /// The "log once" rows of section 8.7, written from a fact instead of from the turn loop. + /// + /// + /// Moving the conversation sites behind the hook must change neither the text an operator greps for nor how + /// often it appears, so these tests pin the event id, the level, and the fields of each of the six + /// lines. They also pin the six kinds that write nothing here: a normal conversation is recorded by the chain + /// of D23, and a log is not. + /// + public sealed class LoggingConversationObserverTests { - RecordingLogger logger = new(); - - await Observe( - logger, - Event(ConversationEventKind.ToolFailed, turnIndex: 2, AuditPayloadKeys.ToolError, "the CRM refused.")); - - var line = Assert.Single(logger.Of(ToolBudgetSpentEventId)); - Assert.Equal(LogLevel.Error, line.Level); - Assert.Equal( - "A tool of conversation conversation-1 failed four times in turn 2: the CRM refused. " - + "The turn spoke the fallback and the conversation continues.", - line.Message); - } - - [Fact] - public async Task AQuietRun_IsAWarningNamingTheTurn() - { - RecordingLogger logger = new(); - - await Observe(logger, Event(ConversationEventKind.EmptyReply, turnIndex: 3)); + private const string ConversationId = "conversation-1"; + + /// The ids the source-generated methods carry. They are unchanged by the hook. + private const int ExtractionFailedEventId = 1; + private const int ToolBudgetSpentEventId = 2; + private const int EmptyReplyEventId = 3; + private const int PromptRefusedEventId = 6; + private const int ModerationUnavailableEventId = 7; + private const int StateRestorePartialEventId = 13; + + /// The kinds this observer writes no line for. + public static TheoryData QuietKinds => + [ + ConversationEventKind.ConversationStarted, + ConversationEventKind.TurnCompleted, + ConversationEventKind.ReplyInterrupted, + ConversationEventKind.ConversationEnded, + + // Logged, but not here: the line is written where the write was refused, which is the only + // place the exception still exists. A line from this observer too would double it. + ConversationEventKind.TranscriptWriteFailed, + + // The quietest of them all: counted, and not logged anywhere. + ConversationEventKind.ModerationClean, + ]; + + [Fact] + public async Task ASpentToolBudget_IsAnErrorNamingTheTurnAndTheFault() + { + RecordingLogger logger = new(); + + await Observe( + logger, + Event(ConversationEventKind.ToolFailed, turnIndex: 2, AuditPayloadKeys.ToolError, "the CRM refused.")); + + LogLine line = Assert.Single(logger.Of(ToolBudgetSpentEventId)); + Assert.Equal(LogLevel.Error, line.Level); + Assert.Equal( + "A tool of conversation conversation-1 failed four times in turn 2: the CRM refused. " + + "The turn spoke the fallback and the conversation continues.", + line.Message); + } - var line = Assert.Single(logger.Of(EmptyReplyEventId)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Equal( - "Turn 3 of conversation conversation-1 returned an empty reply, so it spoke the fallback. " - + "The run reached 40 tool rounds, or the model answered nothing.", - line.Message); - } + [Fact] + public async Task AQuietRun_IsAWarningNamingTheTurn() + { + RecordingLogger logger = new(); - [Fact] - public async Task AnExtractorThatProducedNothing_IsAWarningAndNeverAnError() - { - RecordingLogger logger = new(); - - // Row two: the slots stay unchanged and the conversation continues. - await Observe( - logger, - Event(ConversationEventKind.ExtractionFailed, turnIndex: 0, ConversationEventPayloadKeys.Reason, "it timed out.")); - - var line = Assert.Single(logger.Of(ExtractionFailedEventId)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Equal( - "The extractor of conversation conversation-1 produced nothing for turn 0: it timed out. " - + "The slots stay unchanged and the conversation continues.", - line.Message); - } + await Observe(logger, Event(ConversationEventKind.EmptyReply, turnIndex: 3)); - [Fact] - public async Task ARefusedPrompt_ReportsTheCategoriesAndNeverTheWords() - { - RecordingLogger logger = new(); - - await Observe( - logger, - Event( - ConversationEventKind.PromptFlagged, - turnIndex: 1, - AuditPayloadKeys.ModerationCategories, - "harassment,violence")); - - var line = Assert.Single(logger.Of(PromptRefusedEventId)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Equal( - "Moderation flagged turn 1 of conversation conversation-1 for harassment,violence, " - + "so the agent refused it and spoke the refusal line.", - line.Message); - } + LogLine line = Assert.Single(logger.Of(EmptyReplyEventId)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Equal( + "Turn 3 of conversation conversation-1 returned an empty reply, so it spoke the fallback. " + + "The run reached 40 tool rounds, or the model answered nothing.", + line.Message); + } - [Fact] - public async Task AModerationEndpointThatDidNotAnswer_IsAWarningBecauseTheVendorIsNotThisLibrary() - { - RecordingLogger logger = new(); - - await Observe( - logger, - Event( - ConversationEventKind.ModerationUnavailable, - turnIndex: 4, - ConversationEventPayloadKeys.Reason, - "it did not answer within 500 ms.")); - - var line = Assert.Single(logger.Of(ModerationUnavailableEventId)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Equal( - "Moderation did not answer for turn 4 of conversation conversation-1 (it did not answer within 500 ms.). " - + "The turn ran unchecked, because moderation fails open.", - line.Message); - } + [Fact] + public async Task AnExtractorThatProducedNothing_IsAWarningAndNeverAnError() + { + RecordingLogger logger = new(); + + // Row two: the slots stay unchanged and the conversation continues. + await Observe( + logger, + Event(ConversationEventKind.ExtractionFailed, turnIndex: 0, ConversationEventPayloadKeys.Reason, "it timed out.")); + + LogLine line = Assert.Single(logger.Of(ExtractionFailedEventId)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Equal( + "The extractor of conversation conversation-1 produced nothing for turn 0: it timed out. " + + "The slots stay unchanged and the conversation continues.", + line.Message); + } - [Fact] - public async Task APartialStateRestore_IsAWarningNamingTheConversationAndWhatItLost() - { - RecordingLogger logger = new(); - - // No turn index: the conversation is still opening. It is documented as logged, and until this line - // existed it was not — a document change that cost every resumed conversation its stage produced no - // line and no metric, and six tests of the restore itself passed straight over the silence. - await Observe( - logger, - Event( - ConversationEventKind.StateRestorePartial, - turnIndex: null, - ConversationEventPayloadKeys.Reason, - "the document no longer declares the slot 'model'.")); - - var line = Assert.Single(logger.Of(StateRestorePartialEventId)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Equal( - "Conversation conversation-1 could not restore part of its stored state: the document no longer declares " - + "the slot 'model'. The conversation resumes without that part.", - line.Message); - } + [Fact] + public async Task ARefusedPrompt_ReportsTheCategoriesAndNeverTheWords() + { + RecordingLogger logger = new(); + + await Observe( + logger, + Event( + ConversationEventKind.PromptFlagged, + turnIndex: 1, + AuditPayloadKeys.ModerationCategories, + "harassment,violence")); + + LogLine line = Assert.Single(logger.Of(PromptRefusedEventId)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Equal( + "Moderation flagged turn 1 of conversation conversation-1 for harassment,violence, " + + "so the agent refused it and spoke the refusal line.", + line.Message); + } - [Theory] - [MemberData(nameof(QuietKinds))] - public async Task AKindTheChainRecords_WritesNoLine(ConversationEventKind kind) - { - RecordingLogger logger = new(); + [Fact] + public async Task AModerationEndpointThatDidNotAnswer_IsAWarningBecauseTheVendorIsNotThisLibrary() + { + RecordingLogger logger = new(); + + await Observe( + logger, + Event( + ConversationEventKind.ModerationUnavailable, + turnIndex: 4, + ConversationEventPayloadKeys.Reason, + "it did not answer within 500 ms.")); + + LogLine line = Assert.Single(logger.Of(ModerationUnavailableEventId)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Equal( + "Moderation did not answer for turn 4 of conversation conversation-1 (it did not answer within 500 ms.). " + + "The turn ran unchecked, because moderation fails open.", + line.Message); + } - await Observe(logger, Event(kind, turnIndex: 0)); + [Fact] + public async Task APartialStateRestore_IsAWarningNamingTheConversationAndWhatItLost() + { + RecordingLogger logger = new(); + + // No turn index: the conversation is still opening. It is documented as logged, and until this line + // existed it was not — a document change that cost every resumed conversation its stage produced no + // line and no metric, and six tests of the restore itself passed straight over the silence. + await Observe( + logger, + Event( + ConversationEventKind.StateRestorePartial, + turnIndex: null, + ConversationEventPayloadKeys.Reason, + "the document no longer declares the slot 'model'.")); + + LogLine line = Assert.Single(logger.Of(StateRestorePartialEventId)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Equal( + "Conversation conversation-1 could not restore part of its stored state: the document no longer declares " + + "the slot 'model'. The conversation resumes without that part.", + line.Message); + } - Assert.Empty(logger.Lines); - } + [Theory] + [MemberData(nameof(QuietKinds))] + public async Task AKindTheChainRecords_WritesNoLine(ConversationEventKind kind) + { + RecordingLogger logger = new(); - [Fact] - public async Task NoLogger_IsStillAnObserver() - { - // The library never throws for want of one. - var pending = new LoggingConversationObserver().OnConversationEventAsync( - Event(ConversationEventKind.EmptyReply, turnIndex: 0), - TestContext.Current.CancellationToken); + await Observe(logger, Event(kind, turnIndex: 0)); - await pending; - Assert.True(pending.IsCompletedSuccessfully); - } + Assert.Empty(logger.Lines); + } - [Fact] - public async Task NoEvent_IsRefused() - => await Assert.ThrowsAsync(async () => - await new LoggingConversationObserver() - .OnConversationEventAsync(null!, TestContext.Current.CancellationToken)); + [Fact] + public async Task NoLogger_IsStillAnObserver() + { + // The library never throws for want of one. + ValueTask pending = new LoggingConversationObserver().OnConversationEventAsync( + Event(ConversationEventKind.EmptyReply, turnIndex: 0), + TestContext.Current.CancellationToken); - private static async Task Observe(ILogger logger, ConversationEvent conversationEvent) - { - LoggingConversationObserver observer = new(logger); + await pending; + Assert.True(pending.IsCompletedSuccessfully); + } - // The observer never waits, so this always completes on this thread. It is awaited anyway, - // because the port says nothing about which of the two it does. - await observer.OnConversationEventAsync(conversationEvent, TestContext.Current.CancellationToken); - } + [Fact] + public async Task NoEvent_IsRefused() + { + _ = await Assert.ThrowsAsync(async () => + await new LoggingConversationObserver() + .OnConversationEventAsync(null!, TestContext.Current.CancellationToken)); + } - private static ConversationEvent Event(ConversationEventKind kind, int? turnIndex, string? key = null, string? detail = null) - { - Dictionary payload = new(StringComparer.Ordinal); - if (key is not null && detail is not null) + private static async Task Observe(ILogger logger, ConversationEvent conversationEvent) { - payload[key] = detail; + LoggingConversationObserver observer = new(logger); + + // The observer never waits, so this always completes on this thread. It is awaited anyway, + // because the port says nothing about which of the two it does. + await observer.OnConversationEventAsync(conversationEvent, TestContext.Current.CancellationToken); } - return new ConversationEvent + private static ConversationEvent Event(ConversationEventKind kind, int? turnIndex, string? key = null, string? detail = null) { - ConversationId = ConversationId, - Kind = kind, - OccurredAt = DateTimeOffset.UnixEpoch, - TurnIndex = turnIndex, - Payload = payload, - }; + Dictionary payload = new(StringComparer.Ordinal); + if (key is not null && detail is not null) + { + payload[key] = detail; + } + + return new ConversationEvent + { + ConversationId = ConversationId, + Kind = kind, + OccurredAt = DateTimeOffset.UnixEpoch, + TurnIndex = turnIndex, + Payload = payload, + }; + } } } diff --git a/tests/AgentCore.Application.Tests/Diagnostics/TelemetryConversationObserverTests.cs b/tests/AgentCore.Application.Tests/Diagnostics/TelemetryConversationObserverTests.cs index 0e93fff9..125dcc7f 100644 --- a/tests/AgentCore.Application.Tests/Diagnostics/TelemetryConversationObserverTests.cs +++ b/tests/AgentCore.Application.Tests/Diagnostics/TelemetryConversationObserverTests.cs @@ -3,147 +3,150 @@ using AgentCore.Application.Runtime; using Xunit; -namespace AgentCore.Application.Tests.Diagnostics; - -/// -/// The three counters of section 8.6, incremented from a fact instead of from the turn loop. -/// -/// -/// -/// Nothing about the numbers changed when the conversation sites moved behind the hook, so these tests pin the -/// instrument, the attribute key, and the value each kind writes. T61 is why the values are closed and -/// why no conversation id appears among them: a cumulative series lives forever once it is created, and the -/// Grafana Cloud free tier binds at 10,000. -/// -/// -/// The meter is a process-wide singleton, so another test running beside this one measures on the same -/// instruments. Every assertion here is therefore about what the observer DID write, and the negative -/// side — which kinds are counted as audit events at all — is pinned on the mapping itself, in -/// ConversationEventKindsTests, where nothing else can add to the reading. -/// -/// -public sealed class TelemetryConversationObserverTests +namespace AgentCore.Application.Tests.Diagnostics { - private const string FailureInstrument = "agentcore.turn.failures"; - private const string ModerationInstrument = "agentcore.moderation.verdicts"; - private const string AuditInstrument = "agentcore.audit.events"; - - private const string FailureKey = "agentcore.failure.kind"; - private const string ModerationKey = "agentcore.moderation.outcome"; - private const string AuditKey = "agentcore.audit.kind"; - - /// Each failure kind, beside the value section 8.7 gives its row. - public static TheoryData Failures => - new() - { - { ConversationEventKind.ToolFailed, "tool" }, - { ConversationEventKind.EmptyReply, "empty_reply" }, - { ConversationEventKind.ExtractionFailed, "extraction" }, - }; - - /// Each moderation verdict, beside the value an operator alerts on. - public static TheoryData Verdicts => - new() - { - { ConversationEventKind.PromptFlagged, "flagged" }, - { ConversationEventKind.ModerationClean, "clean" }, - { ConversationEventKind.ModerationUnavailable, "unavailable" }, - }; - - /// Each stored kind, beside the wire token the chain of D23 hashes. - public static TheoryData StoredKinds => - new() - { - { ConversationEventKind.ConversationStarted, "conversation.started" }, - { ConversationEventKind.PromptFlagged, "prompt.flagged" }, - { ConversationEventKind.ToolFailed, "tool.failed" }, - { ConversationEventKind.TurnCompleted, "turn.completed" }, - { ConversationEventKind.ReplyInterrupted, "reply.interrupted" }, - { ConversationEventKind.ConversationEnded, "conversation.ended" }, - }; - - [Theory] - [MemberData(nameof(Failures))] - public async Task AFailureRow_IsCountedUnderItsOwnKind(ConversationEventKind kind, string expected) + /// + /// The three counters of section 8.6, incremented from a fact instead of from the turn loop. + /// + /// + /// + /// Nothing about the numbers changed when the conversation sites moved behind the hook, so these tests pin the + /// instrument, the attribute key, and the value each kind writes. T61 is why the values are closed and + /// why no conversation id appears among them: a cumulative series lives forever once it is created, and the + /// Grafana Cloud free tier binds at 10,000. + /// + /// + /// The meter is a process-wide singleton, so another test running beside this one measures on the same + /// instruments. Every assertion here is therefore about what the observer DID write, and the negative + /// side — which kinds are counted as audit events at all — is pinned on the mapping itself, in + /// ConversationEventKindsTests, where nothing else can add to the reading. + /// + /// + public sealed class TelemetryConversationObserverTests { - var measured = await MeasureAsync(kind); + private const string FailureInstrument = "agentcore.turn.failures"; + private const string ModerationInstrument = "agentcore.moderation.verdicts"; + private const string AuditInstrument = "agentcore.audit.events"; - Assert.Contains(new Reading(FailureInstrument, FailureKey, expected), measured); - } + private const string FailureKey = "agentcore.failure.kind"; + private const string ModerationKey = "agentcore.moderation.outcome"; + private const string AuditKey = "agentcore.audit.kind"; - [Theory] - [MemberData(nameof(Verdicts))] - public async Task AModerationVerdict_IsCountedUnderItsOwnOutcome(ConversationEventKind kind, string expected) - { - var measured = await MeasureAsync(kind); + /// Each failure kind, beside the value section 8.7 gives its row. + public static TheoryData Failures => + new() + { + { ConversationEventKind.ToolFailed, "tool" }, + { ConversationEventKind.EmptyReply, "empty_reply" }, + { ConversationEventKind.ExtractionFailed, "extraction" }, + }; + + /// Each moderation verdict, beside the value an operator alerts on. + public static TheoryData Verdicts => + new() + { + { ConversationEventKind.PromptFlagged, "flagged" }, + { ConversationEventKind.ModerationClean, "clean" }, + { ConversationEventKind.ModerationUnavailable, "unavailable" }, + }; + + /// Each stored kind, beside the wire token the chain of D23 hashes. + public static TheoryData StoredKinds => + new() + { + { ConversationEventKind.ConversationStarted, "conversation.started" }, + { ConversationEventKind.PromptFlagged, "prompt.flagged" }, + { ConversationEventKind.ToolFailed, "tool.failed" }, + { ConversationEventKind.TurnCompleted, "turn.completed" }, + { ConversationEventKind.ReplyInterrupted, "reply.interrupted" }, + { ConversationEventKind.ConversationEnded, "conversation.ended" }, + }; + + [Theory] + [MemberData(nameof(Failures))] + public async Task AFailureRow_IsCountedUnderItsOwnKind(ConversationEventKind kind, string expected) + { + List measured = await MeasureAsync(kind); - Assert.Contains(new Reading(ModerationInstrument, ModerationKey, expected), measured); - } + Assert.Contains(new Reading(FailureInstrument, FailureKey, expected), measured); + } - [Theory] - [MemberData(nameof(StoredKinds))] - public async Task AStoredKind_IsCountedUnderTheTokenTheChainWrites(ConversationEventKind kind, string expected) - { - var measured = await MeasureAsync(kind); + [Theory] + [MemberData(nameof(Verdicts))] + public async Task AModerationVerdict_IsCountedUnderItsOwnOutcome(ConversationEventKind kind, string expected) + { + List measured = await MeasureAsync(kind); - Assert.Contains(new Reading(AuditInstrument, AuditKey, expected), measured); - } + Assert.Contains(new Reading(ModerationInstrument, ModerationKey, expected), measured); + } - [Fact] - public async Task NoEvent_IsRefused() - => await Assert.ThrowsAsync(async () => - await new TelemetryConversationObserver().OnConversationEventAsync(null!, TestContext.Current.CancellationToken)); + [Theory] + [MemberData(nameof(StoredKinds))] + public async Task AStoredKind_IsCountedUnderTheTokenTheChainWrites(ConversationEventKind kind, string expected) + { + List measured = await MeasureAsync(kind); - /// Hands one fact to the observer and reads back what the meter saw. - /// What happened. - /// Every attribute of every measurement, as instrument, key, and value. - private static async Task> MeasureAsync(ConversationEventKind kind) - { - List readings = []; - using MeterListener listener = new(); + Assert.Contains(new Reading(AuditInstrument, AuditKey, expected), measured); + } - listener.InstrumentPublished = (instrument, active) => + [Fact] + public async Task NoEvent_IsRefused() { - if (string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal)) - { - active.EnableMeasurementEvents(instrument); - } - }; + _ = await Assert.ThrowsAsync(async () => + await new TelemetryConversationObserver().OnConversationEventAsync(null!, TestContext.Current.CancellationToken)); + } - listener.SetMeasurementEventCallback((instrument, _, tags, _) => + /// Hands one fact to the observer and reads back what the meter saw. + /// What happened. + /// Every attribute of every measurement, as instrument, key, and value. + private static async Task> MeasureAsync(ConversationEventKind kind) { - var copy = tags.ToArray(); - lock (readings) - { - readings.AddRange(copy.Select(tag => - new Reading(instrument.Name, tag.Key, tag.Value?.ToString() ?? string.Empty))); - } - }); + List readings = []; + using MeterListener listener = new(); - listener.Start(); - - await new TelemetryConversationObserver().OnConversationEventAsync( - new ConversationEvent + listener.InstrumentPublished = (instrument, active) => { - ConversationId = "conversation-1", - Kind = kind, - OccurredAt = DateTimeOffset.UnixEpoch, - EventId = Guid.CreateVersion7(), - TurnIndex = 0, - }, - TestContext.Current.CancellationToken); + if (string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal)) + { + active.EnableMeasurementEvents(instrument); + } + }; - listener.Dispose(); + listener.SetMeasurementEventCallback((instrument, _, tags, _) => + { + KeyValuePair[] copy = tags.ToArray(); + lock (readings) + { + readings.AddRange(copy.Select(tag => + new Reading(instrument.Name, tag.Key, tag.Value?.ToString() ?? string.Empty))); + } + }); + + listener.Start(); + + await new TelemetryConversationObserver().OnConversationEventAsync( + new ConversationEvent + { + ConversationId = "conversation-1", + Kind = kind, + OccurredAt = DateTimeOffset.UnixEpoch, + EventId = Guid.CreateVersion7(), + TurnIndex = 0, + }, + TestContext.Current.CancellationToken); + + listener.Dispose(); - lock (readings) - { - return [.. readings]; + lock (readings) + { + return [.. readings]; + } } - } - /// One attribute of one measurement. - /// The instrument that took it. - /// The attribute key. - /// The attribute value. - private sealed record Reading(string Instrument, string Key, string Value); + /// One attribute of one measurement. + /// The instrument that took it. + /// The attribute key. + /// The attribute value. + private sealed record Reading(string Instrument, string Key, string Value); + } } diff --git a/tests/AgentCore.Application.Tests/Diagnostics/TelemetrySeamTests.cs b/tests/AgentCore.Application.Tests/Diagnostics/TelemetrySeamTests.cs index 7ae7ff68..7a978357 100644 --- a/tests/AgentCore.Application.Tests/Diagnostics/TelemetrySeamTests.cs +++ b/tests/AgentCore.Application.Tests/Diagnostics/TelemetrySeamTests.cs @@ -5,225 +5,231 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.Application.Tests.Diagnostics; - -/// -/// The fourth vendor seam: providers.telemetry, and what a document that names none gets. -/// -/// -/// -/// This seam differs from the other three in direction. Nothing in the library ever calls a -/// telemetry adapter, because the library writes to the ActivitySource and Meter that -/// owns and an exporter listens to those two names. The adapter -/// starts a listener and holds it, which is why is disposable and -/// why disposal is the flush. -/// -/// -/// These tests pin the parts that are this project's and not a vendor's: which adapter a -/// kind picks, that a document naming none starts nothing at all, and the T61 floor under the -/// export interval that costs money to lose. -/// -/// -public sealed class TelemetrySeamTests +namespace AgentCore.Application.Tests.Diagnostics { - // --------------------------------------------------------------------------------------------- - // A document that names nothing. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task NoTelemetryBlock_StartsNothingAndAsksNoAdapter() - { - var configuration = ConfigurationLoader.LoadYaml(Document()); - FakeTelemetryAdapter adapter = new("grafana"); - - var session = await TelemetrySessionFactory.StartAsync( - configuration, - secrets: null, - [adapter], - TestContext.Current.CancellationToken); - - // The deliberate default. Telemetry needs a vendor account, and a library that refused to - // start without one could not be used in a test. Registering a vendor costs nothing until a - // document names it, so the adapter is never asked and no credential is read. - Assert.Null(session); - Assert.Equal(0, adapter.Starts); - } - - // --------------------------------------------------------------------------------------------- - // The kind picks the adapter. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheKind_PicksOneAdapterAndLeavesTheOthersAlone() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana")); - FakeTelemetryAdapter grafana = new("grafana"); - FakeTelemetryAdapter other = new("honeycomb"); - - var session = await TelemetrySessionFactory.StartAsync( - configuration, - secrets: null, - [other, grafana], - TestContext.Current.CancellationToken); - - Assert.Same(grafana.Session, session); - Assert.Equal(1, grafana.Starts); - Assert.Equal(0, other.Starts); - } - - [Fact] - public async Task TheKind_MatchesWithoutRegardToCase() + /// + /// The fourth vendor seam: providers.telemetry, and what a document that names none gets. + /// + /// + /// + /// This seam differs from the other three in direction. Nothing in the library ever calls a + /// telemetry adapter, because the library writes to the ActivitySource and Meter that + /// owns and an exporter listens to those two names. The adapter + /// starts a listener and holds it, which is why is disposable and + /// why disposal is the flush. + /// + /// + /// These tests pin the parts that are this project's and not a vendor's: which adapter a + /// kind picks, that a document naming none starts nothing at all, and the T61 floor under the + /// export interval that costs money to lose. + /// + /// + public sealed class TelemetrySeamTests { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: Grafana")); - FakeTelemetryAdapter adapter = new("grafana"); + // --------------------------------------------------------------------------------------------- + // A document that names nothing. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task NoTelemetryBlock_StartsNothingAndAsksNoAdapter() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document()); + FakeTelemetryAdapter adapter = new("grafana"); - var session = await TelemetrySessionFactory.StartAsync( - configuration, - secrets: null, - [adapter], - TestContext.Current.CancellationToken); + ITelemetrySession? session = await TelemetrySessionFactory.StartAsync( + configuration, + secrets: null, + [adapter], + TestContext.Current.CancellationToken); - // A vendor name is written by a human, so a capital letter is not a different vendor. - Assert.NotNull(session); - } + // The deliberate default. Telemetry needs a vendor account, and a library that refused to + // start without one could not be used in a test. Registering a vendor costs nothing until a + // document names it, so the adapter is never asked and no credential is read. + Assert.Null(session); + Assert.Equal(0, adapter.Starts); + } - // --------------------------------------------------------------------------------------------- - // A kind nobody serves fails the start, and says what is registered. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindNoAdapterServes_FailsTheStartAndNamesWhatIsRegistered() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: honeycomb")); - FakeTelemetryAdapter adapter = new("grafana"); + // --------------------------------------------------------------------------------------------- + // The kind picks the adapter. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheKind_PicksOneAdapterAndLeavesTheOthersAlone() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana")); + FakeTelemetryAdapter grafana = new("grafana"); + FakeTelemetryAdapter other = new("honeycomb"); - var failure = await Assert.ThrowsAsync( - async () => await TelemetrySessionFactory.StartAsync( + ITelemetrySession? session = await TelemetrySessionFactory.StartAsync( configuration, secrets: null, - [adapter], - TestContext.Current.CancellationToken)); + [other, grafana], + TestContext.Current.CancellationToken); - // A document that asked for something this host cannot give. The message names the kinds the - // host does register, because the reader's next move is to pick one of them. - Assert.Contains("honeycomb", failure.Message, StringComparison.Ordinal); - Assert.Contains("'grafana'", failure.Message, StringComparison.Ordinal); - Assert.Equal("/providers/telemetry/kind", failure.Errors[0].Pointer); - } + Assert.Same(grafana.Session, session); + Assert.Equal(1, grafana.Starts); + Assert.Equal(0, other.Starts); + } - [Fact] - public async Task TwoAdaptersOnOneKind_FailTheStart() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana")); + [Fact] + public async Task TheKind_MatchesWithoutRegardToCase() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: Grafana")); + FakeTelemetryAdapter adapter = new("grafana"); - var failure = await Assert.ThrowsAsync( - async () => await TelemetrySessionFactory.StartAsync( + ITelemetrySession? session = await TelemetrySessionFactory.StartAsync( configuration, secrets: null, - [new FakeTelemetryAdapter("grafana"), new FakeTelemetryAdapter("grafana")], - TestContext.Current.CancellationToken)); + [adapter], + TestContext.Current.CancellationToken); - // One kind names one collector. Two adapters answering to it means the document silently - // picked whichever was registered first. - Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + // A vendor name is written by a human, so a capital letter is not a different vendor. + Assert.NotNull(session); + } - // And the noun is this seam's own. VendorSeam.Plural exists to keep four seams' wording - // through one shared selector, so telemetry's "collectors" is pinned here — without this, - // the argument could be dropped and nothing would fail. - Assert.Contains("collectors", failure.Message, StringComparison.Ordinal); - } + // --------------------------------------------------------------------------------------------- + // A kind nobody serves fails the start, and says what is registered. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindNoAdapterServes_FailsTheStartAndNamesWhatIsRegistered() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: honeycomb")); + FakeTelemetryAdapter adapter = new("grafana"); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await TelemetrySessionFactory.StartAsync( + configuration, + secrets: null, + [adapter], + TestContext.Current.CancellationToken)); + + // A document that asked for something this host cannot give. The message names the kinds the + // host does register, because the reader's next move is to pick one of them. + Assert.Contains("honeycomb", failure.Message, StringComparison.Ordinal); + Assert.Contains("'grafana'", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/telemetry/kind", failure.Errors[0].Pointer); + } - // --------------------------------------------------------------------------------------------- - // T61: the export interval has a floor, and a document cannot write its way under it. - // --------------------------------------------------------------------------------------------- - [Fact] - public void AnIntervalUnderTheFloor_IsRaisedToIt() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana", "exportIntervalMs: 1000")); - - // Grafana Cloud bills the greater of active series and data points a minute, so a one-second - // interval costs sixty times a one-minute interval for exactly the same series. This is the - // second half of T61, the half the library cannot enforce from AgentCoreTelemetry. - Assert.Equal( - TelemetryProviderConfiguration.MinimumExportIntervalMilliseconds, - configuration.Providers!.Telemetry!.ExportIntervalMilliseconds); - } + [Fact] + public async Task TwoAdaptersOnOneKind_FailTheStart() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana")); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await TelemetrySessionFactory.StartAsync( + configuration, + secrets: null, + [new FakeTelemetryAdapter("grafana"), new FakeTelemetryAdapter("grafana")], + TestContext.Current.CancellationToken)); + + // One kind names one collector. Two adapters answering to it means the document silently + // picked whichever was registered first. + Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + + // And the noun is this seam's own. VendorSeam.Plural exists to keep four seams' wording + // through one shared selector, so telemetry's "collectors" is pinned here — without this, + // the argument could be dropped and nothing would fail. + Assert.Contains("collectors", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AnIntervalAboveTheFloor_IsKept() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana", "exportIntervalMs: 300000")); + // --------------------------------------------------------------------------------------------- + // T61: the export interval has a floor, and a document cannot write its way under it. + // --------------------------------------------------------------------------------------------- + [Fact] + public void AnIntervalUnderTheFloor_IsRaisedToIt() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana", "exportIntervalMs: 1000")); + + // Grafana Cloud bills the greater of active series and data points a minute, so a one-second + // interval costs sixty times a one-minute interval for exactly the same series. This is the + // second half of T61, the half the library cannot enforce from AgentCoreTelemetry. + Assert.Equal( + TelemetryProviderConfiguration.MinimumExportIntervalMilliseconds, + configuration.Providers!.Telemetry!.ExportIntervalMilliseconds); + } - // A deployment may always send less often than the floor asks. Only under is corrected. - Assert.Equal(300_000, configuration.Providers!.Telemetry!.ExportIntervalMilliseconds); - } + [Fact] + public void AnIntervalAboveTheFloor_IsKept() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana", "exportIntervalMs: 300000")); - [Fact] - public void ADocumentThatListsNoSourcesOrMeters_GetsTheBuiltInNames() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana")); - var telemetry = configuration.Providers!.Telemetry!; + // A deployment may always send less often than the floor asks. Only under is corrected. + Assert.Equal(300_000, configuration.Providers!.Telemetry!.ExportIntervalMilliseconds); + } - Assert.Equal(TelemetryProviderConfiguration.DefaultSources, telemetry.Sources); - Assert.Equal(TelemetryProviderConfiguration.DefaultMeters, telemetry.Meters); - Assert.Equal(TelemetryProviderConfiguration.DefaultServiceName, telemetry.ServiceName); - } + [Fact] + public void ADocumentThatListsNoSourcesOrMeters_GetsTheBuiltInNames() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana")); + TelemetryProviderConfiguration telemetry = configuration.Providers!.Telemetry!; - [Fact] - public void AnEmptyListIsNotAnAbsentOne() - { - var configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana", "meters: []")); + Assert.Equal(TelemetryProviderConfiguration.DefaultSources, telemetry.Sources); + Assert.Equal(TelemetryProviderConfiguration.DefaultMeters, telemetry.Meters); + Assert.Equal(TelemetryProviderConfiguration.DefaultServiceName, telemetry.ServiceName); + } - // Absent means "use the defaults" and empty means "listen to AgentCore alone". That is how a - // deployment buys back the roughly 1,750 active series a normal replica spends against the - // 10,000 ceiling of item 12, so the two must not collapse into each other. - Assert.Empty(configuration.Providers!.Telemetry!.Meters); - Assert.Equal(TelemetryProviderConfiguration.DefaultSources, configuration.Providers.Telemetry.Sources); - } + [Fact] + public void AnEmptyListIsNotAnAbsentOne() + { + AgentCoreConfiguration configuration = ConfigurationLoader.LoadYaml(Document("kind: grafana", "meters: []")); - /// The providers.knowledge line the telemetry block is written after. - private const string KnowledgeLine = Configuration.ExampleDocument.LastProviderLine; + // Absent means "use the defaults" and empty means "listen to AgentCore alone". That is how a + // deployment buys back the roughly 1,750 active series a normal replica spends against the + // 10,000 ceiling of item 12, so the two must not collapse into each other. + Assert.Empty(configuration.Providers!.Telemetry!.Meters); + Assert.Equal(TelemetryProviderConfiguration.DefaultSources, configuration.Providers.Telemetry.Sources); + } - /// Builds the section 8.1 document with one telemetry block written into it. - /// - /// The keys under providers.telemetry, one for each line and without indentation. No entry - /// at all leaves the block out, which is the case that must start nothing. - /// - /// - /// The raw string in ExampleDocument strips its common indentation, so inside - /// providers: a key sits at two spaces and its own keys at four. Every line is written - /// here rather than by the caller, because YAML indentation written by hand at a conversation site is - /// how the first draft of these tests failed. - /// - private static string Document(params string[] entries) - => entries.Length == 0 - ? Configuration.ExampleDocument.Yaml - : Configuration.ExampleDocument.Yaml.Replace( - KnowledgeLine, - KnowledgeLine + "\n telemetry:\n" + string.Join("\n", entries.Select(entry => " " + entry)), - StringComparison.Ordinal); - - /// An adapter that starts nothing and records that it was asked. - private sealed class FakeTelemetryAdapter(string kind) : ITelemetryAdapter - { - public string Kind => kind; + /// The providers.knowledge line the telemetry block is written after. + private const string KnowledgeLine = Configuration.ExampleDocument.LastProviderLine; + + /// Builds the section 8.1 document with one telemetry block written into it. + /// + /// The keys under providers.telemetry, one for each line and without indentation. No entry + /// at all leaves the block out, which is the case that must start nothing. + /// + /// + /// The raw string in ExampleDocument strips its common indentation, so inside + /// providers: a key sits at two spaces and its own keys at four. Every line is written + /// here rather than by the caller, because YAML indentation written by hand at a conversation site is + /// how the first draft of these tests failed. + /// + private static string Document(params string[] entries) + { + return entries.Length == 0 + ? Configuration.ExampleDocument.Yaml + : Configuration.ExampleDocument.Yaml.Replace( + KnowledgeLine, + KnowledgeLine + "\n telemetry:\n" + string.Join("\n", entries.Select(entry => " " + entry)), + StringComparison.Ordinal); + } - public int Starts { get; private set; } + /// An adapter that starts nothing and records that it was asked. + private sealed class FakeTelemetryAdapter(string kind) : ITelemetryAdapter + { + public string Kind => kind; - public ITelemetrySession Session { get; } = new FakeSession(); + public int Starts { get; private set; } - public ValueTask StartAsync( - TelemetryProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - Starts++; - return ValueTask.FromResult(Session); + public ITelemetrySession Session { get; } = new FakeSession(); + + public ValueTask StartAsync( + TelemetryProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + Starts++; + return ValueTask.FromResult(Session); + } } - } - /// A session that exports nowhere and carries no log provider. - private sealed class FakeSession : ITelemetrySession - { - public ILoggerProvider? Logs => null; + /// A session that exports nowhere and carries no log provider. + private sealed class FakeSession : ITelemetrySession + { + public ILoggerProvider? Logs => null; - public ValueTask DisposeAsync() => ValueTask.CompletedTask; + public ValueTask DisposeAsync() + { + return ValueTask.CompletedTask; + } + } } } diff --git a/tests/AgentCore.Application.Tests/Diagnostics/TurnObservabilityTests.cs b/tests/AgentCore.Application.Tests/Diagnostics/TurnObservabilityTests.cs index 9580390d..2bb42318 100644 --- a/tests/AgentCore.Application.Tests/Diagnostics/TurnObservabilityTests.cs +++ b/tests/AgentCore.Application.Tests/Diagnostics/TurnObservabilityTests.cs @@ -1,6 +1,5 @@ using AgentCore.TestSupport; using AgentCore.Application.Audit.Memory; -using AgentCore.Application.Audit; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -14,31 +13,32 @@ using System.Diagnostics.Metrics; using System.Diagnostics; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Diagnostics; - -/// -/// What a turn reports: one span, three metrics, and the three "log once" rows of section 8.7. -/// -/// -/// Every test here runs offline. There is no collector, no exporter, and no network conversation. -/// -public sealed class TurnObservabilityTests +namespace AgentCore.Application.Tests.Diagnostics { - /// The only attribute keys any metric of this library may carry. See T61. - private static readonly string[] PermittedMetricKeys = - [ - "agentcore.turn.outcome", - "agentcore.failure.kind", - "agentcore.audit.kind", - - // Three values: clean, flagged, unavailable. Three series for each replica, against the - // 10,000 ceiling of item 12. No conversation id rides on it, so T61 holds. - "agentcore.moderation.outcome", - ]; - - private const string PolicyYaml = - """ + /// + /// What a turn reports: one span, three metrics, and the three "log once" rows of section 8.7. + /// + /// + /// Every test here runs offline. There is no collector, no exporter, and no network conversation. + /// + public sealed class TurnObservabilityTests + { + /// The only attribute keys any metric of this library may carry. See T61. + private static readonly string[] PermittedMetricKeys = + [ + "agentcore.turn.outcome", + "agentcore.failure.kind", + "agentcore.audit.kind", + + // Three values: clean, flagged, unavailable. Three series for each replica, against the + // 10,000 ceiling of item 12. No conversation id rides on it, so T61 holds. + "agentcore.moderation.outcome", + ]; + + private const string PolicyYaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: { type: boolean, default: false, writer: extractor } @@ -62,8 +62,8 @@ public sealed class TurnObservabilityTests - { id: close, agent: closer, terminal: true } """; - private const string ToolYaml = - """ + private const string ToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: lookup_order, kind: builtin, uses: orders.read, description: "Look up an order by its id." } @@ -77,227 +77,227 @@ public sealed class TurnObservabilityTests agent: only """; - private const string StayingNull = """{ "callerSaidGoodbye": null }"""; + private const string StayingNull = /*lang=json,strict*/ """{ "callerSaidGoodbye": null }"""; - // ------------------------------------------------------------------------------------------- - // T61: the metric attributes, and what may never appear on one. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task NoMetricAttribute_EverCarriesTheConversationId() - { - // A value nothing else in the process can produce, so a hit is this conversation and not another. - var conversationId = "conversation-" + Guid.NewGuid().ToString("N"); + // ------------------------------------------------------------------------------------------- + // T61: the metric attributes, and what may never appear on one. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task NoMetricAttribute_EverCarriesTheConversationId() + { + // A value nothing else in the process can produce, so a hit is this conversation and not another. + string conversationId = "conversation-" + Guid.NewGuid().ToString("N"); - var tags = await MeasureAsync(conversationId); + List> tags = await MeasureAsync(conversationId); - // The .NET default is cumulative temporality, so one conversation id on a metric attribute is one - // permanent series. A day of conversations would then be a day of permanent series, and the free - // tier binds at 10,000. See D26 and T61. - Assert.DoesNotContain(tags, tag => string.Equals(tag.Value as string, conversationId, StringComparison.Ordinal)); - } + // The .NET default is cumulative temporality, so one conversation id on a metric attribute is one + // permanent series. A day of conversations would then be a day of permanent series, and the free + // tier binds at 10,000. See D26 and T61. + Assert.DoesNotContain(tags, tag => string.Equals(tag.Value as string, conversationId, StringComparison.Ordinal)); + } - [Fact] - public async Task EveryMetricAttribute_ComesFromAClosedSet() - { - var tags = await MeasureAsync("conversation-" + Guid.NewGuid().ToString("N")); + [Fact] + public async Task EveryMetricAttribute_ComesFromAClosedSet() + { + List> tags = await MeasureAsync("conversation-" + Guid.NewGuid().ToString("N")); - // The listener really saw the instruments of this library. - Assert.NotEmpty(tags); + // The listener really saw the instruments of this library. + Assert.NotEmpty(tags); - // T61 again, and this is the half that catches the next attribute somebody adds. Every key - // below takes a handful of values the library writes itself. A key that is not on this list - // has not been costed, so the build refuses it. - Assert.All(tags, tag => Assert.Contains(tag.Key, PermittedMetricKeys, StringComparer.Ordinal)); - } + // T61 again, and this is the half that catches the next attribute somebody adds. Every key + // below takes a handful of values the library writes itself. A key that is not on this list + // has not been costed, so the build refuses it. + Assert.All(tags, tag => Assert.Contains(tag.Key, PermittedMetricKeys, StringComparer.Ordinal)); + } - [Fact] - public async Task ATurn_RecordsItsDurationOnceWithTheOutcome() - { - List> durations = []; - using MeterListener listener = new(); - listener.InstrumentPublished = (instrument, active) => + [Fact] + public async Task ATurn_RecordsItsDurationOnceWithTheOutcome() { - if (string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal) - && string.Equals(instrument.Name, "agentcore.turn.duration", StringComparison.Ordinal)) + List> durations = []; + using MeterListener listener = new(); + listener.InstrumentPublished = (instrument, active) => { - active.EnableMeasurementEvents(instrument); - } - }; - listener.SetMeasurementEventCallback((_, value, tags, _) => - { - lock (durations) + if (string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal) + && string.Equals(instrument.Name, "agentcore.turn.duration", StringComparison.Ordinal)) + { + active.EnableMeasurementEvents(instrument); + } + }; + listener.SetMeasurementEventCallback((_, value, tags, _) => { - durations.Add(new Measurement(value, tags)); - } - }); - listener.Start(); - - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - TestTimeProvider clock = new(); - var session = Build(PolicyYaml, reply, fill, timeProvider: clock).Create(); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - listener.Dispose(); - - // Other tests may run beside this one, so the assertion reads what this turn produced rather - // than the whole list. - Assert.Contains(durations, sample => sample.Tags.ToArray().Any(tag => - string.Equals(tag.Key, "agentcore.turn.outcome", StringComparison.Ordinal) - && string.Equals(tag.Value as string, "completed", StringComparison.Ordinal))); - } + lock (durations) + { + durations.Add(new Measurement(value, tags)); + } + }); + listener.Start(); + + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + TestTimeProvider clock = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, timeProvider: clock).Create(); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + listener.Dispose(); + + // Other tests may run beside this one, so the assertion reads what this turn produced rather + // than the whole list. + Assert.Contains(durations, sample => sample.Tags.ToArray().Any(tag => + string.Equals(tag.Key, "agentcore.turn.outcome", StringComparison.Ordinal) + && string.Equals(tag.Value as string, "completed", StringComparison.Ordinal))); + } - // ------------------------------------------------------------------------------------------- - // The span. A high-cardinality value belongs here and nowhere else. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ATurn_IsOneSpanThatCarriesTheConversationIdAsAGenAiAttribute() - { - var conversationId = "conversation-" + Guid.NewGuid().ToString("N"); - var spans = await RecordSpansAsync(conversationId); - - var span = Assert.Single(spans); - - Assert.Equal(AgentCoreTelemetry.TurnActivityName, span.OperationName); - - // Item 7 asks for gen_ai.* attributes on the trace, and gen_ai.conversation.id is the - // convention's own name for the conversation a request belongs to. A conversation is that - // conversation, and a span attribute costs no series. - Assert.Equal(conversationId, span.GetTagItem("gen_ai.conversation.id")); - Assert.Equal(0, span.GetTagItem("agentcore.turn.index")); - Assert.Equal("greeting", span.GetTagItem("agentcore.stage.before")); - Assert.Equal("greeting", span.GetTagItem("agentcore.stage.after")); - Assert.Equal("completed", span.GetTagItem("agentcore.turn.outcome")); - Assert.Equal(ActivityStatusCode.Unset, span.Status); - } + // ------------------------------------------------------------------------------------------- + // The span. A high-cardinality value belongs here and nowhere else. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task ATurn_IsOneSpanThatCarriesTheConversationIdAsAGenAiAttribute() + { + string conversationId = "conversation-" + Guid.NewGuid().ToString("N"); + List spans = await RecordSpansAsync(conversationId); + + Activity span = Assert.Single(spans); + + Assert.Equal(AgentCoreTelemetry.TurnActivityName, span.OperationName); + + // Item 7 asks for gen_ai.* attributes on the trace, and gen_ai.conversation.id is the + // convention's own name for the conversation a request belongs to. A conversation is that + // conversation, and a span attribute costs no series. + Assert.Equal(conversationId, span.GetTagItem("gen_ai.conversation.id")); + Assert.Equal(0, span.GetTagItem("agentcore.turn.index")); + Assert.Equal("greeting", span.GetTagItem("agentcore.stage.before")); + Assert.Equal("greeting", span.GetTagItem("agentcore.stage.after")); + Assert.Equal("completed", span.GetTagItem("agentcore.turn.outcome")); + Assert.Equal(ActivityStatusCode.Unset, span.Status); + } - [Fact] - public async Task AFailedTurn_MarksItsSpanWithTheReasonOfSectionEightSeven() - { - List spans = []; - using var listener = ListenTo(spans); + [Fact] + public async Task AFailedTurn_MarksItsSpanWithTheReasonOfSectionEightSeven() + { + List spans = []; + using ActivityListener listener = ListenTo(spans); - using SequencedChatClient reply = new(" "); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create("conversation-" + Guid.NewGuid().ToString("N")); + using SequencedChatClient reply = new(" "); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create("conversation-" + Guid.NewGuid().ToString("N")); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - var span = Assert.Single(Snapshot(spans), item => string.Equals( - item.GetTagItem("gen_ai.conversation.id") as string, session.ConversationId, StringComparison.Ordinal)); + Activity span = Assert.Single(Snapshot(spans), item => string.Equals( + item.GetTagItem("gen_ai.conversation.id") as string, session.ConversationId, StringComparison.Ordinal)); - Assert.Equal("failed", span.GetTagItem("agentcore.turn.outcome")); - Assert.Equal(ActivityStatusCode.Error, span.Status); - Assert.Equal(ConversationSession.EmptyReplyReason, span.StatusDescription); - } + Assert.Equal("failed", span.GetTagItem("agentcore.turn.outcome")); + Assert.Equal(ActivityStatusCode.Error, span.Status); + Assert.Equal(ConversationSession.EmptyReplyReason, span.StatusDescription); + } - [Fact] - public async Task AStreamedTurn_IsOneSpanToo() - { - List spans = []; - using var listener = ListenTo(spans); + [Fact] + public async Task AStreamedTurn_IsOneSpanToo() + { + List spans = []; + using ActivityListener listener = ListenTo(spans); - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create("conversation-" + Guid.NewGuid().ToString("N")); + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create("conversation-" + Guid.NewGuid().ToString("N")); - await foreach (var update in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) - { - Assert.NotNull(update); - } + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + Assert.NotNull(update); + } - // The span travels on the turn record and not on Activity.Current, because an async iterator - // restores the execution context of its caller at every yield. - var span = Assert.Single(Snapshot(spans), item => string.Equals( - item.GetTagItem("gen_ai.conversation.id") as string, session.ConversationId, StringComparison.Ordinal)); + // The span travels on the turn record and not on Activity.Current, because an async iterator + // restores the execution context of its caller at every yield. + Activity span = Assert.Single(Snapshot(spans), item => string.Equals( + item.GetTagItem("gen_ai.conversation.id") as string, session.ConversationId, StringComparison.Ordinal)); - Assert.Equal("completed", span.GetTagItem("agentcore.turn.outcome")); - } + Assert.Equal("completed", span.GetTagItem("agentcore.turn.outcome")); + } - // ------------------------------------------------------------------------------------------- - // Section 8.7: three rows say "log once". - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AFailedExtraction_IsLoggedOnceForTheTurnAndTheConversationContinues() - { - RecordingLogger logger = new(); - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new("I am sorry, I cannot do that."); - var session = Build(PolicyYaml, reply, fill, logger: logger).Create("conversation-x"); - - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // Row two of section 8.7: leave the slots unchanged, log once for the turn, and continue. - var line = Assert.Single(logger.Of(1)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Contains("conversation-x", line.Message, StringComparison.Ordinal); - Assert.NotNull(turn.ExtractionFailure); - Assert.Equal("hello there.", turn.ReplyText); - } + // ------------------------------------------------------------------------------------------- + // Section 8.7: three rows say "log once". + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AFailedExtraction_IsLoggedOnceForTheTurnAndTheConversationContinues() + { + RecordingLogger logger = new(); + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new("I am sorry, I cannot do that."); + ConversationSession session = Build(PolicyYaml, reply, fill, logger: logger).Create("conversation-x"); + + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // Row two of section 8.7: leave the slots unchanged, log once for the turn, and continue. + LogLine line = Assert.Single(logger.Of(1)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Contains("conversation-x", line.Message, StringComparison.Ordinal); + Assert.NotNull(turn.ExtractionFailure); + Assert.Equal("hello there.", turn.ReplyText); + } - [Fact] - public async Task AnEmptyReply_IsLoggedOnce() - { - RecordingLogger logger = new(); - using SequencedChatClient reply = new(" "); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill, logger: logger).Create("conversation-x"); + [Fact] + public async Task AnEmptyReply_IsLoggedOnce() + { + RecordingLogger logger = new(); + using SequencedChatClient reply = new(" "); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill, logger: logger).Create("conversation-x"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - var line = Assert.Single(logger.Of(3)); - Assert.Equal(LogLevel.Warning, line.Level); + LogLine line = Assert.Single(logger.Of(3)); + Assert.Equal(LogLevel.Warning, line.Level); - // The empty reply is not a tool fault, so the tool row stays silent. - Assert.Empty(logger.Of(2)); - } + // The empty reply is not a tool fault, so the tool row stays silent. + Assert.Empty(logger.Of(2)); + } - [Fact] - public async Task TheFourthConsecutiveToolFailure_IsLoggedOnce() - { - RecordingLogger logger = new(); - using LoopingToolCallingChatClient reply = new(); - var session = Build(ToolYaml, reply, null, new ThrowingToolBuilder().Create, logger: logger).Create("conversation-x"); - - await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Row six of section 8.7. The turn spoke the fallback, and the conversation is still alive. - // - // ONE line, and the turn spent four tool calls to get here. Each of those four is a row in - // the chain of D23, which is where a record of a conversation belongs; the log gets the turn-level - // fact alone, so the volume an operator pays Grafana Cloud for did not move. - var line = Assert.Single(logger.Of(2)); - Assert.Equal(LogLevel.Error, line.Level); - Assert.Contains(ThrowingToolBuilder.Message, line.Message, StringComparison.Ordinal); - Assert.False(session.IsComplete); - - // The tool row and the empty-reply row are different failures, and only one of them fired. - Assert.Empty(logger.Of(3)); - } + [Fact] + public async Task TheFourthConsecutiveToolFailure_IsLoggedOnce() + { + RecordingLogger logger = new(); + using LoopingToolCallingChatClient reply = new(); + ConversationSession session = Build(ToolYaml, reply, null, new ThrowingToolBuilder().Create, logger: logger).Create("conversation-x"); + + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Row six of section 8.7. The turn spoke the fallback, and the conversation is still alive. + // + // ONE line, and the turn spent four tool calls to get here. Each of those four is a row in + // the chain of D23, which is where a record of a conversation belongs; the log gets the turn-level + // fact alone, so the volume an operator pays Grafana Cloud for did not move. + LogLine line = Assert.Single(logger.Of(2)); + Assert.Equal(LogLevel.Error, line.Level); + Assert.Contains(ThrowingToolBuilder.Message, line.Message, StringComparison.Ordinal); + Assert.False(session.IsComplete); + + // The tool row and the empty-reply row are different failures, and only one of them fired. + Assert.Empty(logger.Of(3)); + } - [Fact] - public async Task ASessionWithNoLogger_RunsATurnAndThrowsNothing() - { - using SequencedChatClient reply = new(" "); - using SequencedChatClient fill = new("I am sorry, I cannot do that."); - var session = Build(PolicyYaml, reply, fill).Create(); + [Fact] + public async Task ASessionWithNoLogger_RunsATurnAndThrowsNothing() + { + using SequencedChatClient reply = new(" "); + using SequencedChatClient fill = new("I am sorry, I cannot do that."); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // Two of the three "log once" rows fire in this one turn, and neither has anywhere to write. - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + // Two of the three "log once" rows fire in this one turn, and neither has anywhere to write. + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.NotNull(turn.ExtractionFailure); - } + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.NotNull(turn.ExtractionFailure); + } - // ------------------------------------------------------------------------------------------- - // Section 8.7, row five: a guard that throws is logged once for each guard. - // ------------------------------------------------------------------------------------------- - [Fact] - public void AGuardThatDoesNotParse_IsLoggedOnceUnderItsName() - { - RecordingLogger logger = new(); - var document = ConfigurationLoader.LoadYaml( - """ + // ------------------------------------------------------------------------------------------- + // Section 8.7, row five: a guard that throws is logged once for each guard. + // ------------------------------------------------------------------------------------------- + [Fact] + public void AGuardThatDoesNotParse_IsLoggedOnceUnderItsName() + { + RecordingLogger logger = new(); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml( + """ apiVersion: agentcore/v1 guards: impossible: { "no_such_operator": [ 1, 2 ] } @@ -309,157 +309,158 @@ public void AGuardThatDoesNotParse_IsLoggedOnceUnderItsName() agent: only """); - _ = new GuardEvaluator(document.Guards, logger); - - var line = Assert.Single(logger.Of(4)); - Assert.Equal(LogLevel.Warning, line.Level); - Assert.Contains("impossible", line.Message, StringComparison.Ordinal); - Assert.NotNull(line.Exception); - } + _ = new GuardEvaluator(document.Guards, logger); - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - /// Runs three turns of one conversation and collects every metric attribute the library wrote. - /// The id of the conversation. - /// Every attribute of every measurement, flattened. - /// - /// The three turns cover the three outcomes: one answers, one meets a section 8.7 row, and one - /// ends the conversation. That reaches every instrument the library owns. - /// - private static async Task>> MeasureAsync(string conversationId) - { - List> tags = []; - using MeterListener listener = new(); + LogLine line = Assert.Single(logger.Of(4)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Contains("impossible", line.Message, StringComparison.Ordinal); + Assert.NotNull(line.Exception); + } - listener.InstrumentPublished = (instrument, active) => + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + /// Runs three turns of one conversation and collects every metric attribute the library wrote. + /// The id of the conversation. + /// Every attribute of every measurement, flattened. + /// + /// The three turns cover the three outcomes: one answers, one meets a section 8.7 row, and one + /// ends the conversation. That reaches every instrument the library owns. + /// + private static async Task>> MeasureAsync(string conversationId) { - if (string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal)) + List> tags = []; + using MeterListener listener = new(); + + listener.InstrumentPublished = (instrument, active) => { - active.EnableMeasurementEvents(instrument); - } - }; + if (string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal)) + { + active.EnableMeasurementEvents(instrument); + } + }; - listener.SetMeasurementEventCallback((_, _, measured, _) => Collect(tags, measured)); - listener.SetMeasurementEventCallback((_, _, measured, _) => Collect(tags, measured)); - listener.Start(); + listener.SetMeasurementEventCallback((_, _, measured, _) => Collect(tags, measured)); + listener.SetMeasurementEventCallback((_, _, measured, _) => Collect(tags, measured)); + listener.Start(); - using SequencedChatClient reply = new("hello there.", " ", "goodbye."); - using SequencedChatClient fill = new(StayingNull, StayingNull, """{ "callerSaidGoodbye": true }"""); - var session = Build(PolicyYaml, reply, fill, auditSink: new Application.Audit.Memory.InMemoryAuditSink()) - .Create(conversationId); + using SequencedChatClient reply = new("hello there.", " ", "goodbye."); + using SequencedChatClient fill = new(StayingNull, StayingNull, /*lang=json,strict*/ """{ "callerSaidGoodbye": true }"""); + ConversationSession session = Build(PolicyYaml, reply, fill, auditSink: new InMemoryAuditSink()) + .Create(conversationId); - var token = TestContext.Current.CancellationToken; - await session.RunTurnAsync("hi", token); - await session.RunTurnAsync("still there?", token); - await session.RunTurnAsync("goodbye", token); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await session.RunTurnAsync("hi", token); + _ = await session.RunTurnAsync("still there?", token); + _ = await session.RunTurnAsync("goodbye", token); - listener.Dispose(); - return tags; - } + listener.Dispose(); + return tags; + } - /// Adds the attributes of one measurement to the list. - private static void Collect( - List> tags, - ReadOnlySpan> measured) - { - var copy = measured.ToArray(); - lock (tags) + /// Adds the attributes of one measurement to the list. + private static void Collect( + List> tags, + ReadOnlySpan> measured) { - tags.AddRange(copy); + KeyValuePair[] copy = measured.ToArray(); + lock (tags) + { + tags.AddRange(copy); + } } - } - /// Runs one turn and collects the spans of this library. - private static async Task> RecordSpansAsync(string conversationId) - { - List spans = []; - using var listener = ListenTo(spans); + /// Runs one turn and collects the spans of this library. + private static async Task> RecordSpansAsync(string conversationId) + { + List spans = []; + using ActivityListener listener = ListenTo(spans); - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(conversationId); + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(conversationId); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - return [.. Snapshot(spans).Where(span => string.Equals( - span.GetTagItem("gen_ai.conversation.id") as string, conversationId, StringComparison.Ordinal))]; - } + return [.. Snapshot(spans).Where(span => string.Equals( + span.GetTagItem("gen_ai.conversation.id") as string, conversationId, StringComparison.Ordinal))]; + } - /// Copies what the listener has collected so far. - /// The list the listener writes into. - /// The copy, which no other thread can change. - /// - /// An subscribes to the source of the whole process, so a span - /// that another test class produces at the same time lands in this list as well. The listener - /// writes under the lock, so a reader takes the same lock and asserts against a copy. Reading - /// the list itself races, and the race reports "Collection was modified". - /// - private static List Snapshot(List spans) - { - lock (spans) + /// Copies what the listener has collected so far. + /// The list the listener writes into. + /// The copy, which no other thread can change. + /// + /// An subscribes to the source of the whole process, so a span + /// that another test class produces at the same time lands in this list as well. The listener + /// writes under the lock, so a reader takes the same lock and asserts against a copy. Reading + /// the list itself races, and the race reports "Collection was modified". + /// + private static List Snapshot(List spans) { - return [.. spans]; + lock (spans) + { + return [.. spans]; + } } - } - /// Subscribes to the one activity source of this library. - private static ActivityListener ListenTo(List spans) - { - ActivityListener listener = new() + /// Subscribes to the one activity source of this library. + private static ActivityListener ListenTo(List spans) { - ShouldListenTo = source => - string.Equals(source.Name, AgentCoreTelemetry.ActivitySourceName, StringComparison.Ordinal), - Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, - ActivityStopped = activity => + ActivityListener listener = new() { - lock (spans) + ShouldListenTo = source => + string.Equals(source.Name, AgentCoreTelemetry.ActivitySourceName, StringComparison.Ordinal), + Sample = (ref _) => ActivitySamplingResult.AllData, + ActivityStopped = activity => { - spans.Add(activity); - } - }, - }; - - ActivitySource.AddActivityListener(listener); - return listener; - } - - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IChatClient? fill, - Func? tools = null, - TimeProvider? timeProvider = null, - IAuditSinkPort? auditSink = null, - ILogger? logger = null) - { - // There is always a sink now: ConversationObservers.Standard takes a required one, because the - // composition root resolves providers.audit for every host and falls back to the in-process - // memory kind. An optional parameter has to be a compile-time constant, so the default is - // spelled here instead — a fact that does not care where its events land gets a fresh - // in-memory sink and reads exactly as it did when it passed nothing. - IAuditSinkPort sink = auditSink ?? new InMemoryAuditSink(); - - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(reply); - if (fill is not null) - { - chatClients.Route("fill", fill); + lock (spans) + { + spans.Add(activity); + } + }, + }; + + ActivitySource.AddActivityListener(listener); + return listener; } - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IChatClient? fill, + Func? tools = null, + TimeProvider? timeProvider = null, + IAuditSinkPort? auditSink = null, + ILogger? logger = null) + { + // There is always a sink now: ConversationObservers.Standard takes a required one, because the + // composition root resolves providers.audit for every host and falls back to the in-process + // memory kind. An optional parameter has to be a compile-time constant, so the default is + // spelled here instead — a fact that does not care where its events land gets a fresh + // in-memory sink and reads exactly as it did when it passed nothing. + IAuditSinkPort sink = auditSink ?? new InMemoryAuditSink(); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + if (fill is not null) { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - timeProvider, - logger, - ConversationObservers.Standard(sink, logger)); + _ = chatClients.Route("fill", fill); + } + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + timeProvider, + logger, + ConversationObservers.Standard(sink, logger)); + } } } diff --git a/tests/AgentCore.Application.Tests/Embeddings/CompositeEmbeddingGeneratorFactoryTests.cs b/tests/AgentCore.Application.Tests/Embeddings/CompositeEmbeddingGeneratorFactoryTests.cs index f7e7049d..99c9a3b5 100644 --- a/tests/AgentCore.Application.Tests/Embeddings/CompositeEmbeddingGeneratorFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Embeddings/CompositeEmbeddingGeneratorFactoryTests.cs @@ -4,21 +4,22 @@ using AgentCore.Application.Ports; using AgentCore.Application.Tests.Embeddings.Fakes; using Xunit; +using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Embeddings; - -/// -/// The composite behind UseEmbeddings. It routes providers.embeddings.kind to the -/// adapter whose matches. -/// -/// -/// Every adapter here is a fake, so every test runs offline. The document names the vendor and the -/// host registers the adapters; these tests prove the document alone decides which adapter answers. -/// -public sealed class CompositeEmbeddingGeneratorFactoryTests +namespace AgentCore.Application.Tests.Embeddings { - private const string NoEmbeddingsYaml = - """ + /// + /// The composite behind UseEmbeddings. It routes providers.embeddings.kind to the + /// adapter whose matches. + /// + /// + /// Every adapter here is a fake, so every test runs offline. The document names the vendor and the + /// host registers the adapters; these tests prove the document alone decides which adapter answers. + /// + public sealed class CompositeEmbeddingGeneratorFactoryTests + { + private const string NoEmbeddingsYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -28,8 +29,8 @@ public sealed class CompositeEmbeddingGeneratorFactoryTests agent: only """; - private const string OneKindYaml = - """ + private const string OneKindYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -45,8 +46,8 @@ public sealed class CompositeEmbeddingGeneratorFactoryTests agent: only """; - private const string ShoutedKindYaml = - """ + private const string ShoutedKindYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -62,97 +63,102 @@ public sealed class CompositeEmbeddingGeneratorFactoryTests agent: only """; - // --------------------------------------------------------------------------------------------- - // Routing: the document names the vendor, and the matching adapter builds it. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindWrittenInAnotherCase_StillFindsItsAdapter() - { - RecordingEmbeddingGeneratorAdapter openai = new("openai"); - - var generator = await Create(ShoutedKindYaml, openai); - - Assert.Same(openai.Generator, generator); - } - - [Fact] - public async Task NoEmbeddingsBlockAtAll_BuildsNothingAndAsksNoAdapter() - { - RecordingEmbeddingGeneratorAdapter openai = new("openai"); - - var generator = await Create(NoEmbeddingsYaml, openai); - - Assert.Null(generator); - Assert.False(openai.CreateGeneratorCalled); - } - - [Fact] - public async Task TheAdapter_ReceivesTheEntryAndTheResolverChainTheHostBound() - { - RecordingEmbeddingGeneratorAdapter openai = new("openai"); - MapSecretResolver resolver = new(); - - await Create(OneKindYaml, resolver, openai); - - Assert.Same(resolver, openai.LastSecrets); - Assert.Equal("text-embedding-3-small", openai.LastEntry?.Model); + // --------------------------------------------------------------------------------------------- + // Routing: the document names the vendor, and the matching adapter builds it. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindWrittenInAnotherCase_StillFindsItsAdapter() + { + RecordingEmbeddingGeneratorAdapter openai = new("openai"); + + IEmbeddingGenerator>? generator = await Create(ShoutedKindYaml, openai); + + Assert.Same(openai.Generator, generator); + } + + [Fact] + public async Task NoEmbeddingsBlockAtAll_BuildsNothingAndAsksNoAdapter() + { + RecordingEmbeddingGeneratorAdapter openai = new("openai"); + + IEmbeddingGenerator>? generator = await Create(NoEmbeddingsYaml, openai); + + Assert.Null(generator); + Assert.False(openai.CreateGeneratorCalled); + } + + [Fact] + public async Task TheAdapter_ReceivesTheEntryAndTheResolverChainTheHostBound() + { + RecordingEmbeddingGeneratorAdapter openai = new("openai"); + MapSecretResolver resolver = new(); + + _ = await Create(OneKindYaml, resolver, openai); + + Assert.Same(resolver, openai.LastSecrets); + Assert.Equal("text-embedding-3-small", openai.LastEntry?.Model); + } + + // --------------------------------------------------------------------------------------------- + // What it refuses, at startup and never on the first conversation. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindNoAdapterServes_FailsAndNamesTheRegisteredKinds() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(OneKindYaml, new RecordingEmbeddingGeneratorAdapter("azure"))); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/embeddings/kind", error.Pointer); + Assert.Contains("openai", error.Message, StringComparison.Ordinal); + Assert.Contains("'azure'", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task TwoAdaptersOfOneKind_FailTheBuild() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => await Create( + OneKindYaml, + new RecordingEmbeddingGeneratorAdapter("openai"), + new RecordingEmbeddingGeneratorAdapter("OpenAI"))); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/embeddings/kind", error.Pointer); + Assert.Contains("openai", error.Message, StringComparison.OrdinalIgnoreCase); + } + + [Fact] + public async Task AHostThatRegistersNoAdapter_FailsAndSaysSo() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(OneKindYaml)); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/embeddings/kind", error.Pointer); + Assert.Contains("no adapter", error.Message, StringComparison.Ordinal); + Assert.Contains("options.UseEmbeddings(...)", error.Message, StringComparison.Ordinal); + } + + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private static ValueTask>?> Create( + string yaml, + params IEmbeddingGeneratorAdapter[] adapters) + { + return Create(yaml, null, adapters); + } + + private static ValueTask>?> Create( + string yaml, + ISecretResolverPort? secrets, + params IEmbeddingGeneratorAdapter[] adapters) + { + return CompositeEmbeddingGeneratorFactory.CreateAsync( + ConfigurationLoader.LoadYaml(yaml), + secrets, + adapters, + TestContext.Current.CancellationToken); + } } - - // --------------------------------------------------------------------------------------------- - // What it refuses, at startup and never on the first conversation. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindNoAdapterServes_FailsAndNamesTheRegisteredKinds() - { - var failure = await Assert.ThrowsAsync( - async () => await Create(OneKindYaml, new RecordingEmbeddingGeneratorAdapter("azure"))); - - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/embeddings/kind", error.Pointer); - Assert.Contains("openai", error.Message, StringComparison.Ordinal); - Assert.Contains("'azure'", error.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task TwoAdaptersOfOneKind_FailTheBuild() - { - var failure = await Assert.ThrowsAsync(async () => await Create( - OneKindYaml, - new RecordingEmbeddingGeneratorAdapter("openai"), - new RecordingEmbeddingGeneratorAdapter("OpenAI"))); - - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/embeddings/kind", error.Pointer); - Assert.Contains("openai", error.Message, StringComparison.OrdinalIgnoreCase); - } - - [Fact] - public async Task AHostThatRegistersNoAdapter_FailsAndSaysSo() - { - var failure = await Assert.ThrowsAsync( - async () => await Create(OneKindYaml)); - - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/embeddings/kind", error.Pointer); - Assert.Contains("no adapter", error.Message, StringComparison.Ordinal); - Assert.Contains("options.UseEmbeddings(...)", error.Message, StringComparison.Ordinal); - } - - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private static ValueTask>?> Create( - string yaml, - params IEmbeddingGeneratorAdapter[] adapters) - => Create(yaml, null, adapters); - - private static ValueTask>?> Create( - string yaml, - ISecretResolverPort? secrets, - params IEmbeddingGeneratorAdapter[] adapters) - => CompositeEmbeddingGeneratorFactory.CreateAsync( - ConfigurationLoader.LoadYaml(yaml), - secrets, - adapters, - TestContext.Current.CancellationToken); } diff --git a/tests/AgentCore.Application.Tests/Embeddings/Fakes/CountingEmbeddingGenerator.cs b/tests/AgentCore.Application.Tests/Embeddings/Fakes/CountingEmbeddingGenerator.cs index e1e972fa..75e50ecb 100644 --- a/tests/AgentCore.Application.Tests/Embeddings/Fakes/CountingEmbeddingGenerator.cs +++ b/tests/AgentCore.Application.Tests/Embeddings/Fakes/CountingEmbeddingGenerator.cs @@ -1,32 +1,35 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Embeddings.Fakes; - -/// -/// A vendor that counts how many texts it was asked to embed and answers each with its length. -/// -internal sealed class CountingEmbeddingGenerator(string defaultModel) : IEmbeddingGenerator> +namespace AgentCore.Application.Tests.Embeddings.Fakes { - private readonly EmbeddingGeneratorMetadata _metadata = new(defaultModelId: defaultModel); + /// + /// A vendor that counts how many texts it was asked to embed and answers each with its length. + /// + internal sealed class CountingEmbeddingGenerator(string defaultModel) : IEmbeddingGenerator> + { + private readonly EmbeddingGeneratorMetadata _metadata = new(defaultModelId: defaultModel); - /// Gets how many texts reached the vendor, across every call. - public int TextsEmbedded { get; private set; } + /// Gets how many texts reached the vendor, across every call. + public int TextsEmbedded { get; private set; } - public Task>> GenerateAsync( - IEnumerable values, - EmbeddingGenerationOptions? options = null, - CancellationToken cancellationToken = default) - { - var texts = values.ToList(); - TextsEmbedded += texts.Count; - return Task.FromResult(new GeneratedEmbeddings>( - texts.Select(text => new Embedding(new float[] { text.Length })))); - } + public Task>> GenerateAsync( + IEnumerable values, + EmbeddingGenerationOptions? options = null, + CancellationToken cancellationToken = default) + { + List texts = [.. values]; + TextsEmbedded += texts.Count; + return Task.FromResult(new GeneratedEmbeddings>( + texts.Select(text => new Embedding(new float[] { text.Length })))); + } - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceType == typeof(EmbeddingGeneratorMetadata) ? _metadata : null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceType == typeof(EmbeddingGeneratorMetadata) ? _metadata : null; + } - public void Dispose() - { + public void Dispose() + { + } } } diff --git a/tests/AgentCore.Application.Tests/Embeddings/Fakes/RecordingEmbeddingGeneratorAdapter.cs b/tests/AgentCore.Application.Tests/Embeddings/Fakes/RecordingEmbeddingGeneratorAdapter.cs index f18087e0..78a384da 100644 --- a/tests/AgentCore.Application.Tests/Embeddings/Fakes/RecordingEmbeddingGeneratorAdapter.cs +++ b/tests/AgentCore.Application.Tests/Embeddings/Fakes/RecordingEmbeddingGeneratorAdapter.cs @@ -2,60 +2,63 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Embeddings.Fakes; - -/// -/// An offline embedding vendor. It answers one kind and records what it was asked to build. -/// -internal sealed class RecordingEmbeddingGeneratorAdapter : IEmbeddingGeneratorAdapter +namespace AgentCore.Application.Tests.Embeddings.Fakes { - public RecordingEmbeddingGeneratorAdapter(string kind) - => Kind = kind; - - public string Kind { get; } + /// + /// An offline embedding vendor. It answers one kind and records what it was asked to build. + /// + internal sealed class RecordingEmbeddingGeneratorAdapter(string kind) : IEmbeddingGeneratorAdapter + { + public string Kind { get; } = kind; - /// Gets whether the composite asked this adapter to build. - public bool CreateGeneratorCalled { get; private set; } + /// Gets whether the composite asked this adapter to build. + public bool CreateGeneratorCalled { get; private set; } - /// Gets the entry the last build received. - public EmbeddingProviderConfiguration? LastEntry { get; private set; } + /// Gets the entry the last build received. + public EmbeddingProviderConfiguration? LastEntry { get; private set; } - /// Gets the resolver chain the last build received. - public ISecretResolverPort? LastSecrets { get; private set; } + /// Gets the resolver chain the last build received. + public ISecretResolverPort? LastSecrets { get; private set; } - /// Gets the object the last build returned. - public IEmbeddingGenerator>? Generator { get; private set; } + /// Gets the object the last build returned. + public IEmbeddingGenerator>? Generator { get; private set; } - public ValueTask>> CreateGeneratorAsync( - EmbeddingProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); + public ValueTask>> CreateGeneratorAsync( + EmbeddingProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(entry); - CreateGeneratorCalled = true; - LastEntry = entry; - LastSecrets = secrets; - Generator = new FakeEmbeddingGenerator(); - return ValueTask.FromResult(Generator); + CreateGeneratorCalled = true; + LastEntry = entry; + LastSecrets = secrets; + Generator = new FakeEmbeddingGenerator(); + return ValueTask.FromResult(Generator); + } } -} -/// A generator that answers every value with the same three-wide vector. -internal sealed class FakeEmbeddingGenerator : IEmbeddingGenerator> -{ - private static readonly float[] Vector = [0f, 0f, 0f]; + /// A generator that answers every value with the same three-wide vector. + internal sealed class FakeEmbeddingGenerator : IEmbeddingGenerator> + { + private static readonly float[] Vector = [0f, 0f, 0f]; - public Task>> GenerateAsync( - IEnumerable values, - EmbeddingGenerationOptions? options = null, - CancellationToken cancellationToken = default) - => Task.FromResult(new GeneratedEmbeddings>( - values.Select(_ => new Embedding(Vector)))); + public Task>> GenerateAsync( + IEnumerable values, + EmbeddingGenerationOptions? options = null, + CancellationToken cancellationToken = default) + { + return Task.FromResult(new GeneratedEmbeddings>( + values.Select(_ => new Embedding(Vector)))); + } - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - public void Dispose() - { + public void Dispose() + { + } } } diff --git a/tests/AgentCore.Application.Tests/Embeddings/HybridCachingEmbeddingGeneratorTests.cs b/tests/AgentCore.Application.Tests/Embeddings/HybridCachingEmbeddingGeneratorTests.cs index 50eb6d54..c52ae676 100644 --- a/tests/AgentCore.Application.Tests/Embeddings/HybridCachingEmbeddingGeneratorTests.cs +++ b/tests/AgentCore.Application.Tests/Embeddings/HybridCachingEmbeddingGeneratorTests.cs @@ -5,76 +5,77 @@ using Microsoft.Extensions.DependencyInjection; using Xunit; -namespace AgentCore.Application.Tests.Embeddings; - -/// -/// The cache in front of the embedding vendor. A repeat of one text under one model must not -/// reach the vendor again; a different model must. -/// -public sealed class HybridCachingEmbeddingGeneratorTests +namespace AgentCore.Application.Tests.Embeddings { - private static HybridCache NewCache() + /// + /// The cache in front of the embedding vendor. A repeat of one text under one model must not + /// reach the vendor again; a different model must. + /// + public sealed class HybridCachingEmbeddingGeneratorTests { - ServiceCollection services = new(); - services.AddHybridCache(); - return services.BuildServiceProvider().GetRequiredService(); - } + private static HybridCache NewCache() + { + ServiceCollection services = new(); + _ = services.AddHybridCache(); + return services.BuildServiceProvider().GetRequiredService(); + } - [Fact] - public async Task Repeat_of_one_text_skips_the_vendor() - { - CountingEmbeddingGenerator vendor = new("model-a"); - using HybridCachingEmbeddingGenerator generator = new(vendor, NewCache()); + [Fact] + public async Task Repeat_of_one_text_skips_the_vendor() + { + CountingEmbeddingGenerator vendor = new("model-a"); + using HybridCachingEmbeddingGenerator generator = new(vendor, NewCache()); - var first = await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); - var second = await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); + GeneratedEmbeddings> first = await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); + GeneratedEmbeddings> second = await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); - Assert.Equal(1, vendor.TextsEmbedded); - Assert.Equal(first[0].Vector.ToArray(), second[0].Vector.ToArray()); - } + Assert.Equal(1, vendor.TextsEmbedded); + Assert.Equal(first[0].Vector.ToArray(), second[0].Vector.ToArray()); + } - [Fact] - public async Task Only_the_new_text_in_a_batch_reaches_the_vendor() - { - CountingEmbeddingGenerator vendor = new("model-a"); - using HybridCachingEmbeddingGenerator generator = new(vendor, NewCache()); + [Fact] + public async Task Only_the_new_text_in_a_batch_reaches_the_vendor() + { + CountingEmbeddingGenerator vendor = new("model-a"); + using HybridCachingEmbeddingGenerator generator = new(vendor, NewCache()); - await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); - var batch = await generator.GenerateAsync(["hello", "world!"], cancellationToken: TestContext.Current.CancellationToken); + _ = await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); + GeneratedEmbeddings> batch = await generator.GenerateAsync(["hello", "world!"], cancellationToken: TestContext.Current.CancellationToken); - Assert.Equal(2, vendor.TextsEmbedded); - Assert.Equal([5f], batch[0].Vector.ToArray()); - Assert.Equal([6f], batch[1].Vector.ToArray()); - } + Assert.Equal(2, vendor.TextsEmbedded); + Assert.Equal([5f], batch[0].Vector.ToArray()); + Assert.Equal([6f], batch[1].Vector.ToArray()); + } - [Fact] - public async Task A_different_model_gets_its_own_entry() - { - CountingEmbeddingGenerator vendor = new("model-a"); - using HybridCachingEmbeddingGenerator generator = new(vendor, NewCache()); + [Fact] + public async Task A_different_model_gets_its_own_entry() + { + CountingEmbeddingGenerator vendor = new("model-a"); + using HybridCachingEmbeddingGenerator generator = new(vendor, NewCache()); - await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); - await generator.GenerateAsync( - ["hello"], - new EmbeddingGenerationOptions { ModelId = "model-b" }, - TestContext.Current.CancellationToken); + _ = await generator.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); + _ = await generator.GenerateAsync( + ["hello"], + new EmbeddingGenerationOptions { ModelId = "model-b" }, + TestContext.Current.CancellationToken); - Assert.Equal(2, vendor.TextsEmbedded); - } + Assert.Equal(2, vendor.TextsEmbedded); + } - [Fact] - public async Task Two_vendors_with_different_default_models_do_not_share_entries() - { - var cache = NewCache(); - CountingEmbeddingGenerator vendorA = new("model-a"); - CountingEmbeddingGenerator vendorB = new("model-b"); - using HybridCachingEmbeddingGenerator generatorA = new(vendorA, cache); - using HybridCachingEmbeddingGenerator generatorB = new(vendorB, cache); + [Fact] + public async Task Two_vendors_with_different_default_models_do_not_share_entries() + { + HybridCache cache = NewCache(); + CountingEmbeddingGenerator vendorA = new("model-a"); + CountingEmbeddingGenerator vendorB = new("model-b"); + using HybridCachingEmbeddingGenerator generatorA = new(vendorA, cache); + using HybridCachingEmbeddingGenerator generatorB = new(vendorB, cache); - await generatorA.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); - await generatorB.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); + _ = await generatorA.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); + _ = await generatorB.GenerateAsync(["hello"], cancellationToken: TestContext.Current.CancellationToken); - Assert.Equal(1, vendorA.TextsEmbedded); - Assert.Equal(1, vendorB.TextsEmbedded); + Assert.Equal(1, vendorA.TextsEmbedded); + Assert.Equal(1, vendorB.TextsEmbedded); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/DocumentRecallEvaluatorTests.cs b/tests/AgentCore.Application.Tests/Evaluation/DocumentRecallEvaluatorTests.cs index 2afca209..7ff9d354 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/DocumentRecallEvaluatorTests.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/DocumentRecallEvaluatorTests.cs @@ -3,146 +3,147 @@ using Microsoft.Extensions.AI.Evaluation; using Xunit; -namespace AgentCore.Application.Tests.Evaluation; - -/// -/// The retrieval half of the offline set: did the search return the file that holds the answer. -/// -/// -/// The design measures the file and not the passage, so every row here compares document ids. The -/// evaluator calls no model, so each row has one answer and the suite runs where no key is set. -/// -public sealed class DocumentRecallEvaluatorTests +namespace AgentCore.Application.Tests.Evaluation { - private const string AnswerDocument = "faults/e7.md"; - private const string OtherDocument = "manual/folding.md"; - - private static readonly ChatMessage[] Turn = - [new(ChatRole.User, "My treadmill shows E7 and stops.")]; - - private static async Task EvaluateAsync(string[] expected, string[] retrieved) - { - EvaluationResult result = await new DocumentRecallEvaluator().EvaluateAsync( - Turn, - new ChatResponse(), - additionalContext: [new RetrievedDocumentsContext(expected, retrieved)], - cancellationToken: TestContext.Current.CancellationToken); - - return result.Get(DocumentRecallEvaluator.DocumentRecallMetricName); - } - - [Fact] - public void TheEvaluatorNamesOneMetric() - { - // Arrange - var evaluator = new DocumentRecallEvaluator(); - - // Act - var names = evaluator.EvaluationMetricNames; - - // Assert - Assert.Equal([DocumentRecallEvaluator.DocumentRecallMetricName], names); - } - - [Fact] - public async Task EvaluateAsync_SearchReturnsTheExpectedDocument_ScoresOneAndPasses() + /// + /// The retrieval half of the offline set: did the search return the file that holds the answer. + /// + /// + /// The design measures the file and not the passage, so every row here compares document ids. The + /// evaluator calls no model, so each row has one answer and the suite runs where no key is set. + /// + public sealed class DocumentRecallEvaluatorTests { - // Arrange, Act - var metric = await EvaluateAsync([AnswerDocument], [AnswerDocument]); - - // Assert - Assert.Equal(1.0, metric.Value); - Assert.False(metric.Interpretation!.Failed); - } - - [Fact] - public async Task EvaluateAsync_SearchReturnsTheExpectedDocumentAmongOthers_ScoresOne() - { - // The metric is recall and never precision. A store that returns the answer plus other files - // still answered the question, because the model reads what comes back. - - // Arrange, Act - var metric = await EvaluateAsync([AnswerDocument], [OtherDocument, AnswerDocument]); - - // Assert - Assert.Equal(1.0, metric.Value); - Assert.False(metric.Interpretation!.Failed); - } - - [Fact] - public async Task EvaluateAsync_SearchMissesTheExpectedDocument_ScoresZeroAndFails() - { - // Arrange, Act - var metric = await EvaluateAsync([AnswerDocument], [OtherDocument]); - - // Assert - Assert.Equal(0.0, metric.Value); - Assert.True(metric.Interpretation!.Failed); - } - - [Fact] - public async Task EvaluateAsync_SearchReturnsOneOfTwoExpectedDocuments_ScoresAHalfAndFails() - { - // Arrange, Act - var metric = await EvaluateAsync([AnswerDocument, OtherDocument], [AnswerDocument]); - - // Assert - Assert.Equal(0.5, metric.Value); - Assert.True(metric.Interpretation!.Failed); - } - - [Fact] - public async Task EvaluateAsync_SearchMissesADocument_NamesThatDocumentInTheReason() - { - // Arrange, Act - var metric = await EvaluateAsync([AnswerDocument], [OtherDocument]); - - // Assert - Assert.Contains(AnswerDocument, metric.Reason, StringComparison.Ordinal); - } - - [Fact] - public async Task EvaluateAsync_DocumentIdsDifferInCase_CountsAsAMiss() - { - // A document id is compared with Ordinal, the same as every other name in the library. - - // Arrange, Act - var metric = await EvaluateAsync([AnswerDocument], ["FAULTS/E7.MD"]); - - // Assert - Assert.Equal(0.0, metric.Value); - } - - [Fact] - public async Task EvaluateAsync_NoContext_ReportsNoValueAndDoesNotFail() - { - // A row that names nothing measures nothing. It must not read as a pass, and it must not read - // as a retrieval failure either. - - // Arrange - var evaluator = new DocumentRecallEvaluator(); - - // Act - EvaluationResult result = await evaluator.EvaluateAsync( - Turn, - new ChatResponse(), - cancellationToken: TestContext.Current.CancellationToken); - - // Assert - var metric = result.Get(DocumentRecallEvaluator.DocumentRecallMetricName); - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.False(metric.Interpretation.Failed); - } - - [Fact] - public async Task EvaluateAsync_ContextExpectsNoDocument_ReportsNoValue() - { - // Arrange, Act - var metric = await EvaluateAsync([], [AnswerDocument]); - - // Assert - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + private const string AnswerDocument = "faults/e7.md"; + private const string OtherDocument = "manual/folding.md"; + + private static readonly ChatMessage[] Turn = + [new(ChatRole.User, "My treadmill shows E7 and stops.")]; + + private static async Task EvaluateAsync(string[] expected, string[] retrieved) + { + EvaluationResult result = await new DocumentRecallEvaluator().EvaluateAsync( + Turn, + new ChatResponse(), + additionalContext: [new RetrievedDocumentsContext(expected, retrieved)], + cancellationToken: TestContext.Current.CancellationToken); + + return result.Get(DocumentRecallEvaluator.DocumentRecallMetricName); + } + + [Fact] + public void TheEvaluatorNamesOneMetric() + { + // Arrange + DocumentRecallEvaluator evaluator = new(); + + // Act + IReadOnlyCollection names = evaluator.EvaluationMetricNames; + + // Assert + Assert.Equal([DocumentRecallEvaluator.DocumentRecallMetricName], names); + } + + [Fact] + public async Task EvaluateAsync_SearchReturnsTheExpectedDocument_ScoresOneAndPasses() + { + // Arrange, Act + NumericMetric metric = await EvaluateAsync([AnswerDocument], [AnswerDocument]); + + // Assert + Assert.Equal(1.0, metric.Value); + Assert.False(metric.Interpretation!.Failed); + } + + [Fact] + public async Task EvaluateAsync_SearchReturnsTheExpectedDocumentAmongOthers_ScoresOne() + { + // The metric is recall and never precision. A store that returns the answer plus other files + // still answered the question, because the model reads what comes back. + + // Arrange, Act + NumericMetric metric = await EvaluateAsync([AnswerDocument], [OtherDocument, AnswerDocument]); + + // Assert + Assert.Equal(1.0, metric.Value); + Assert.False(metric.Interpretation!.Failed); + } + + [Fact] + public async Task EvaluateAsync_SearchMissesTheExpectedDocument_ScoresZeroAndFails() + { + // Arrange, Act + NumericMetric metric = await EvaluateAsync([AnswerDocument], [OtherDocument]); + + // Assert + Assert.Equal(0.0, metric.Value); + Assert.True(metric.Interpretation!.Failed); + } + + [Fact] + public async Task EvaluateAsync_SearchReturnsOneOfTwoExpectedDocuments_ScoresAHalfAndFails() + { + // Arrange, Act + NumericMetric metric = await EvaluateAsync([AnswerDocument, OtherDocument], [AnswerDocument]); + + // Assert + Assert.Equal(0.5, metric.Value); + Assert.True(metric.Interpretation!.Failed); + } + + [Fact] + public async Task EvaluateAsync_SearchMissesADocument_NamesThatDocumentInTheReason() + { + // Arrange, Act + NumericMetric metric = await EvaluateAsync([AnswerDocument], [OtherDocument]); + + // Assert + Assert.Contains(AnswerDocument, metric.Reason, StringComparison.Ordinal); + } + + [Fact] + public async Task EvaluateAsync_DocumentIdsDifferInCase_CountsAsAMiss() + { + // A document id is compared with Ordinal, the same as every other name in the library. + + // Arrange, Act + NumericMetric metric = await EvaluateAsync([AnswerDocument], ["FAULTS/E7.MD"]); + + // Assert + Assert.Equal(0.0, metric.Value); + } + + [Fact] + public async Task EvaluateAsync_NoContext_ReportsNoValueAndDoesNotFail() + { + // A row that names nothing measures nothing. It must not read as a pass, and it must not read + // as a retrieval failure either. + + // Arrange + DocumentRecallEvaluator evaluator = new(); + + // Act + EvaluationResult result = await evaluator.EvaluateAsync( + Turn, + new ChatResponse(), + cancellationToken: TestContext.Current.CancellationToken); + + // Assert + NumericMetric metric = result.Get(DocumentRecallEvaluator.DocumentRecallMetricName); + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.False(metric.Interpretation.Failed); + } + + [Fact] + public async Task EvaluateAsync_ContextExpectsNoDocument_ReportsNoValue() + { + // Arrange, Act + NumericMetric metric = await EvaluateAsync([], [AnswerDocument]); + + // Assert + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/EvaluationSamplerTests.cs b/tests/AgentCore.Application.Tests/Evaluation/EvaluationSamplerTests.cs index bff60a4e..00b9d31d 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/EvaluationSamplerTests.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/EvaluationSamplerTests.cs @@ -1,81 +1,82 @@ using AgentCore.Application.Evaluation; using Xunit; -namespace AgentCore.Application.Tests.Evaluation; - -/// -/// The sampling decision triage row T18 defers, and decision D9 keeps off the turn. -/// -/// -/// The sampler answers one question and runs nothing. The two ends of the range answer without a -/// draw, and every rate between them draws once from a source a test supplies. -/// -public sealed class EvaluationSamplerTests +namespace AgentCore.Application.Tests.Evaluation { - [Fact] - public void ARateOfZero_SamplesNothingAndDrawsNothing() + /// + /// The sampling decision triage row T18 defers, and decision D9 keeps off the turn. + /// + /// + /// The sampler answers one question and runs nothing. The two ends of the range answer without a + /// draw, and every rate between them draws once from a source a test supplies. + /// + public sealed class EvaluationSamplerTests { - int draws = 0; - EvaluationSampler sampler = new(0, () => { draws++; return 0; }); + [Fact] + public void ARateOfZero_SamplesNothingAndDrawsNothing() + { + int draws = 0; + EvaluationSampler sampler = new(0, () => { draws++; return 0; }); - Assert.False(sampler.ShouldSample()); - Assert.False(sampler.ShouldSample()); - Assert.Equal(0, draws); - } + Assert.False(sampler.ShouldSample()); + Assert.False(sampler.ShouldSample()); + Assert.Equal(0, draws); + } - [Fact] - public void ARateOfOne_SamplesEveryTurnAndDrawsNothing() - { - int draws = 0; - EvaluationSampler sampler = new(1, () => { draws++; return 1; }); + [Fact] + public void ARateOfOne_SamplesEveryTurnAndDrawsNothing() + { + int draws = 0; + EvaluationSampler sampler = new(1, () => { draws++; return 1; }); - Assert.True(sampler.ShouldSample()); - Assert.True(sampler.ShouldSample()); - Assert.Equal(0, draws); - } + Assert.True(sampler.ShouldSample()); + Assert.True(sampler.ShouldSample()); + Assert.Equal(0, draws); + } - [Theory] - [InlineData(0.0, true)] - [InlineData(0.09, true)] - [InlineData(0.1, false)] - [InlineData(0.9, false)] - public void ARateBetweenTheEnds_ComparesTheDrawAgainstTheRate(double draw, bool sampled) - { - EvaluationSampler sampler = new(0.1, () => draw); + [Theory] + [InlineData(0.0, true)] + [InlineData(0.09, true)] + [InlineData(0.1, false)] + [InlineData(0.9, false)] + public void ARateBetweenTheEnds_ComparesTheDrawAgainstTheRate(double draw, bool sampled) + { + EvaluationSampler sampler = new(0.1, () => draw); - Assert.Equal(sampled, sampler.ShouldSample()); - } + Assert.Equal(sampled, sampler.ShouldSample()); + } - [Fact] - public void TheSamplerDrawsOncePerDecision() - { - Queue draws = new([0.05, 0.5, 0.05]); - EvaluationSampler sampler = new(0.1, draws.Dequeue); + [Fact] + public void TheSamplerDrawsOncePerDecision() + { + Queue draws = new([0.05, 0.5, 0.05]); + EvaluationSampler sampler = new(0.1, draws.Dequeue); - Assert.True(sampler.ShouldSample()); - Assert.False(sampler.ShouldSample()); - Assert.True(sampler.ShouldSample()); - Assert.Empty(draws); - } + Assert.True(sampler.ShouldSample()); + Assert.False(sampler.ShouldSample()); + Assert.True(sampler.ShouldSample()); + Assert.Empty(draws); + } - [Fact] - public void TheSamplerReportsItsRate() - { - Assert.Equal(0.25, new EvaluationSampler(0.25).Rate); - } + [Fact] + public void TheSamplerReportsItsRate() + { + Assert.Equal(0.25, new EvaluationSampler(0.25).Rate); + } - [Theory] - [InlineData(-0.1)] - [InlineData(1.1)] - [InlineData(double.NaN)] - public void ARateOutsideTheRange_FailsAtStartup(double rate) - { - Assert.Throws(() => new EvaluationSampler(rate)); - } + [Theory] + [InlineData(-0.1)] + [InlineData(1.1)] + [InlineData(double.NaN)] + public void ARateOutsideTheRange_FailsAtStartup(double rate) + { + _ = Assert.Throws(() => new EvaluationSampler(rate)); + } - [Fact] - public void ANullDrawSource_FailsAtStartup() - { - Assert.Throws(() => new EvaluationSampler(0.5, null!)); + [Fact] + public void ANullDrawSource_FailsAtStartup() + { + _ = Assert.Throws(() => new EvaluationSampler(0.5, null!)); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/EvaluatorRegistryTests.cs b/tests/AgentCore.Application.Tests/Evaluation/EvaluatorRegistryTests.cs index 47e73870..c839c5e4 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/EvaluatorRegistryTests.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/EvaluatorRegistryTests.cs @@ -3,82 +3,83 @@ using Microsoft.Extensions.AI.Evaluation; using Xunit; -namespace AgentCore.Application.Tests.Evaluation; - -/// -/// The registry decision D13 asks for: names map to instances. -/// -/// -/// The registry takes the shape ToolBindingRegistry takes, so these tests read the same as -/// the binding tests do. The registry holds evaluators and never runs one. -/// -public sealed class EvaluatorRegistryTests +namespace AgentCore.Application.Tests.Evaluation { - [Fact] - public void TheRegistry_HoldsWhatTheHostRegisters() + /// + /// The registry decision D13 asks for: names map to instances. + /// + /// + /// The registry takes the shape ToolBindingRegistry takes, so these tests read the same as + /// the binding tests do. The registry holds evaluators and never runs one. + /// + public sealed class EvaluatorRegistryTests { - EvaluatorRegistry registry = new(); - registry.Register("fault_code", new FaultCodeEvaluator()); + [Fact] + public void TheRegistry_HoldsWhatTheHostRegisters() + { + EvaluatorRegistry registry = new(); + _ = registry.Register("fault_code", new FaultCodeEvaluator()); - Assert.Equal(1, registry.Count); - Assert.True(registry.Contains("fault_code")); - Assert.Equal(["fault_code"], registry.Names); - } + Assert.Equal(1, registry.Count); + Assert.True(registry.Contains("fault_code")); + Assert.Equal(["fault_code"], registry.Names); + } - [Fact] - public void ANameIsOrdinal() - { - EvaluatorRegistry registry = new(); - registry.Register("fault_code", new FaultCodeEvaluator()); + [Fact] + public void ANameIsOrdinal() + { + EvaluatorRegistry registry = new(); + _ = registry.Register("fault_code", new FaultCodeEvaluator()); - Assert.False(registry.Contains("Fault_Code")); - } + Assert.False(registry.Contains("Fault_Code")); + } - [Fact] - public void TheSameNameTwice_FailsAtStartup() - { - EvaluatorRegistry registry = new(); - registry.Register("fault_code", new FaultCodeEvaluator()); + [Fact] + public void TheSameNameTwice_FailsAtStartup() + { + EvaluatorRegistry registry = new(); + _ = registry.Register("fault_code", new FaultCodeEvaluator()); - Assert.Throws(() => registry.Register("fault_code", new FaultCodeEvaluator())); - } + _ = Assert.Throws(() => registry.Register("fault_code", new FaultCodeEvaluator())); + } - [Fact] - public void RegistrationChains() - { - EvaluatorRegistry registry = new EvaluatorRegistry() - .Register("fault_code", new FaultCodeEvaluator()) - .Register("recorded", new RecordingEvaluator()); + [Fact] + public void RegistrationChains() + { + EvaluatorRegistry registry = new EvaluatorRegistry() + .Register("fault_code", new FaultCodeEvaluator()) + .Register("recorded", new RecordingEvaluator()); - Assert.Equal(2, registry.Count); - } + Assert.Equal(2, registry.Count); + } - [Fact] - public void TheRegistryReadsBackTheSameInstance() - { - FaultCodeEvaluator evaluator = new(); - EvaluatorRegistry registry = new(); - registry.Register("fault_code", evaluator); + [Fact] + public void TheRegistryReadsBackTheSameInstance() + { + FaultCodeEvaluator evaluator = new(); + EvaluatorRegistry registry = new(); + _ = registry.Register("fault_code", evaluator); - Assert.True(registry.TryGetEvaluator("fault_code", out IEvaluator? read)); - Assert.Same(evaluator, read); - } + Assert.True(registry.TryGetEvaluator("fault_code", out IEvaluator? read)); + Assert.Same(evaluator, read); + } - [Fact] - public void AnUnknownName_ReadsNothing() - { - EvaluatorRegistry registry = new(); + [Fact] + public void AnUnknownName_ReadsNothing() + { + EvaluatorRegistry registry = new(); - Assert.False(registry.TryGetEvaluator("fault_code", out IEvaluator? read)); - Assert.Null(read); - } + Assert.False(registry.TryGetEvaluator("fault_code", out IEvaluator? read)); + Assert.Null(read); + } - [Fact] - public void AnEmptyNameOrANullEvaluator_FailsAtStartup() - { - EvaluatorRegistry registry = new(); + [Fact] + public void AnEmptyNameOrANullEvaluator_FailsAtStartup() + { + EvaluatorRegistry registry = new(); - Assert.Throws(() => registry.Register(string.Empty, new FaultCodeEvaluator())); - Assert.Throws(() => registry.Register("fault_code", null!)); + _ = Assert.Throws(() => registry.Register(string.Empty, new FaultCodeEvaluator())); + _ = Assert.Throws(() => registry.Register("fault_code", null!)); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/Fakes/RecordingEvaluator.cs b/tests/AgentCore.Application.Tests/Evaluation/Fakes/RecordingEvaluator.cs index ecfc5a97..9ad520ce 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/Fakes/RecordingEvaluator.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/Fakes/RecordingEvaluator.cs @@ -1,35 +1,36 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.AI.Evaluation; -namespace AgentCore.Application.Tests.Evaluation.Fakes; - -/// -/// An evaluator that answers with one fixed metric and counts its conversations. -/// -/// -/// The registry and the publisher hold evaluators and scores. Neither reads a real metric, so the -/// tests for them need an evaluator that calls no model. -/// -public sealed class RecordingEvaluator : IEvaluator +namespace AgentCore.Application.Tests.Evaluation.Fakes { - /// The name of the metric this evaluator produces. - public const string MetricName = "Recorded"; + /// + /// An evaluator that answers with one fixed metric and counts its conversations. + /// + /// + /// The registry and the publisher hold evaluators and scores. Neither reads a real metric, so the + /// tests for them need an evaluator that calls no model. + /// + public sealed class RecordingEvaluator : IEvaluator + { + /// The name of the metric this evaluator produces. + public const string MetricName = "Recorded"; - /// Gets the number of times a caller evaluated something. - public int Calls { get; private set; } + /// Gets the number of times a caller evaluated something. + public int Calls { get; private set; } - /// - public IReadOnlyCollection EvaluationMetricNames => [MetricName]; + /// + public IReadOnlyCollection EvaluationMetricNames => [MetricName]; - /// - public ValueTask EvaluateAsync( - IEnumerable messages, - ChatResponse modelResponse, - ChatConfiguration? chatConfiguration = null, - IEnumerable? additionalContext = null, - CancellationToken cancellationToken = default) - { - Calls++; - return ValueTask.FromResult(new EvaluationResult(new NumericMetric(MetricName, Calls))); + /// + public ValueTask EvaluateAsync( + IEnumerable messages, + ChatResponse modelResponse, + ChatConfiguration? chatConfiguration = null, + IEnumerable? additionalContext = null, + CancellationToken cancellationToken = default) + { + Calls++; + return ValueTask.FromResult(new EvaluationResult(new NumericMetric(MetricName, Calls))); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/Fakes/ScriptedModerationEvaluator.cs b/tests/AgentCore.Application.Tests/Evaluation/Fakes/ScriptedModerationEvaluator.cs index cacb59b7..18511adf 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/Fakes/ScriptedModerationEvaluator.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/Fakes/ScriptedModerationEvaluator.cs @@ -2,105 +2,122 @@ using Microsoft.Extensions.AI.Evaluation; using AgentCore.Application.Evaluation; -namespace AgentCore.Application.Tests.Evaluation.Fakes; - -/// -/// A moderation evaluator that answers from a script, and never reaches a network. -/// -/// -/// It is the moderation twin of the scripted chat client: the turn tests need an endpoint whose -/// verdict, timing, and failure they own. It records the text it was given, so a test proves which -/// words were moderated. -/// -public sealed class ScriptedModerationEvaluator : IEvaluator +namespace AgentCore.Application.Tests.Evaluation.Fakes { - /// The metric name the real adapter produces. - public const string ContentSafetyMetricName = "Content Safety"; - - private readonly List _moderated = []; - private readonly string[] _categories; - private readonly bool _answers; - private readonly Exception? _throws; - private readonly TimeSpan _takes; - - private ScriptedModerationEvaluator( - string[] categories, - bool answers, - Exception? throws = null, - TimeSpan takes = default) - { - _categories = categories; - _answers = answers; - _throws = throws; - _takes = takes; - } - - /// Gets the texts a caller asked this evaluator about, oldest first. - public IReadOnlyList Moderated => _moderated; - - /// - public IReadOnlyCollection EvaluationMetricNames => [ContentSafetyMetricName]; - - /// An endpoint that answers, and flags nothing. - public static ScriptedModerationEvaluator Clean() => new([], answers: true); - - /// An endpoint that answers, and flags the named categories in the order given. - public static ScriptedModerationEvaluator Flagging(params string[] categories) - => new(categories, answers: true); - - /// An endpoint that did not answer, the way the real adapter reports a 500 or a bad body. + /// + /// A moderation evaluator that answers from a script, and never reaches a network. + /// /// - /// It returns an inconclusive metric carrying NO , which is exactly - /// what OpenAiModerationEvaluator does for every vendor failure. The turn must go on. + /// It is the moderation twin of the scripted chat client: the turn tests need an endpoint whose + /// verdict, timing, and failure they own. It records the text it was given, so a test proves which + /// words were moderated. /// - public static ScriptedModerationEvaluator Unanswered() => new([], answers: false); + public sealed class ScriptedModerationEvaluator : IEvaluator + { + /// The metric name the real adapter produces. + public const string ContentSafetyMetricName = "Content Safety"; + + private readonly List _moderated = []; + private readonly string[] _categories; + private readonly bool _answers; + private readonly Exception? _throws; + private readonly TimeSpan _takes; + + private ScriptedModerationEvaluator( + string[] categories, + bool answers, + Exception? throws = null, + TimeSpan takes = default) + { + _categories = categories; + _answers = answers; + _throws = throws; + _takes = takes; + } - /// An endpoint that throws rather than reporting a failure. - public static ScriptedModerationEvaluator Throwing(Exception exception) => new([], answers: false, exception); + /// Gets the texts a caller asked this evaluator about, oldest first. + public IReadOnlyList Moderated => _moderated; - /// An endpoint that takes longer than the caller allows. - public static ScriptedModerationEvaluator Slow(TimeSpan takes) => new([], answers: true, throws: null, takes); + /// + public IReadOnlyCollection EvaluationMetricNames => [ContentSafetyMetricName]; - /// - public async ValueTask EvaluateAsync( - IEnumerable messages, - ChatResponse modelResponse, - ChatConfiguration? chatConfiguration = null, - IEnumerable? additionalContext = null, - CancellationToken cancellationToken = default) - { - _moderated.Add(modelResponse.Text); + /// An endpoint that answers, and flags nothing. + public static ScriptedModerationEvaluator Clean() + { + return new([], answers: true); + } - if (_throws is not null) + /// An endpoint that answers, and flags the named categories in the order given. + public static ScriptedModerationEvaluator Flagging(params string[] categories) { - throw _throws; + return new(categories, answers: true); } - if (_takes > TimeSpan.Zero) + /// An endpoint that did not answer, the way the real adapter reports a 500 or a bad body. + /// + /// It returns an inconclusive metric carrying NO , which is exactly + /// what OpenAiModerationEvaluator does for every vendor failure. The turn must go on. + /// + public static ScriptedModerationEvaluator Unanswered() { - // A real deadline, so the caller's linked token is what ends the wait. - await Task.Delay(_takes, cancellationToken).ConfigureAwait(false); + return new([], answers: false); } - if (!_answers) + /// An endpoint that throws rather than reporting a failure. + public static ScriptedModerationEvaluator Throwing(Exception exception) { - BooleanMetric unknown = new(ContentSafetyMetricName, value: null); - unknown.AddDiagnostics(EvaluationDiagnostic.Error("the endpoint did not answer.")); - unknown.Interpretation = new EvaluationMetricInterpretation( - EvaluationRating.Inconclusive, - failed: false, - reason: "the moderation endpoint did not answer, so the text is unchecked."); - - return new EvaluationResult(unknown); + return new([], answers: false, exception); } - var flagged = _categories.Length > 0; - BooleanMetric metric = new(ContentSafetyMetricName, !flagged); - metric.Interpretation = new EvaluationMetricInterpretation( - flagged ? EvaluationRating.Unacceptable : EvaluationRating.Exceptional, - failed: flagged); - metric.AddOrUpdateContext(new ModerationVerdict(flagged, _categories)); + /// An endpoint that takes longer than the caller allows. + public static ScriptedModerationEvaluator Slow(TimeSpan takes) + { + return new([], answers: true, throws: null, takes); + } - return new EvaluationResult(metric); + /// + public async ValueTask EvaluateAsync( + IEnumerable messages, + ChatResponse modelResponse, + ChatConfiguration? chatConfiguration = null, + IEnumerable? additionalContext = null, + CancellationToken cancellationToken = default) + { + _moderated.Add(modelResponse.Text); + + if (_throws is not null) + { + throw _throws; + } + + if (_takes > TimeSpan.Zero) + { + // A real deadline, so the caller's linked token is what ends the wait. + await Task.Delay(_takes, cancellationToken).ConfigureAwait(false); + } + + if (!_answers) + { + BooleanMetric unknown = new(ContentSafetyMetricName, value: null); + unknown.AddDiagnostics(EvaluationDiagnostic.Error("the endpoint did not answer.")); + unknown.Interpretation = new EvaluationMetricInterpretation( + EvaluationRating.Inconclusive, + failed: false, + reason: "the moderation endpoint did not answer, so the text is unchecked."); + + return new EvaluationResult(unknown); + } + + bool flagged = _categories.Length > 0; + BooleanMetric metric = new(ContentSafetyMetricName, !flagged) + { + Interpretation = new EvaluationMetricInterpretation( + flagged ? EvaluationRating.Unacceptable : EvaluationRating.Exceptional, + failed: flagged) + }; + metric.AddOrUpdateContext(new ModerationVerdict(flagged, _categories)); + + return new EvaluationResult(metric); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/FaultCodeEvaluatorTests.cs b/tests/AgentCore.Application.Tests/Evaluation/FaultCodeEvaluatorTests.cs index ffb6b3b5..f9cd61dc 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/FaultCodeEvaluatorTests.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/FaultCodeEvaluatorTests.cs @@ -3,238 +3,242 @@ using Microsoft.Extensions.AI.Evaluation; using Xunit; -namespace AgentCore.Application.Tests.Evaluation; - -/// -/// The custom evaluator decision D13 names: fault-code accuracy over access path 1. -/// -/// -/// Decision D10 makes the lookup deterministic and section 9 says the file contents are not. The -/// evaluator therefore measures the reply against what the lookup resolved. It calls no model, so -/// every row here is a set comparison with one answer. -/// -public sealed class FaultCodeEvaluatorTests +namespace AgentCore.Application.Tests.Evaluation { - private static readonly ChatMessage[] Turn = - [new(ChatRole.User, "My treadmill shows an error. What is wrong?")]; - - private static ChatResponse Reply(string text) => new(new ChatMessage(ChatRole.Assistant, text)); + /// + /// The custom evaluator decision D13 names: fault-code accuracy over access path 1. + /// + /// + /// Decision D10 makes the lookup deterministic and section 9 says the file contents are not. The + /// evaluator therefore measures the reply against what the lookup resolved. It calls no model, so + /// every row here is a set comparison with one answer. + /// + public sealed class FaultCodeEvaluatorTests + { + private static readonly ChatMessage[] Turn = + [new(ChatRole.User, "My treadmill shows an error. What is wrong?")]; + + private static ChatResponse Reply(string text) + { + return new(new ChatMessage(ChatRole.Assistant, text)); + } - private static async Task EvaluateAsync( - FaultCodeEvaluator evaluator, - string reply, - params string[] resolved) - { - EvaluationResult result = await evaluator.EvaluateAsync( - Turn, - Reply(reply), - additionalContext: [new FaultCodeContext(resolved)], - cancellationToken: TestContext.Current.CancellationToken); + private static async Task EvaluateAsync( + FaultCodeEvaluator evaluator, + string reply, + params string[] resolved) + { + EvaluationResult result = await evaluator.EvaluateAsync( + Turn, + Reply(reply), + additionalContext: [new FaultCodeContext(resolved)], + cancellationToken: TestContext.Current.CancellationToken); - return result.Get(FaultCodeEvaluator.FaultCodeAccuracyMetricName); - } + return result.Get(FaultCodeEvaluator.FaultCodeAccuracyMetricName); + } - // --------------------------------------------------------------------------------------------- - // The metric the evaluator reports. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TheEvaluatorNamesOneMetric() - { - Assert.Equal([FaultCodeEvaluator.FaultCodeAccuracyMetricName], new FaultCodeEvaluator().EvaluationMetricNames); - } + // --------------------------------------------------------------------------------------------- + // The metric the evaluator reports. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TheEvaluatorNamesOneMetric() + { + Assert.Equal([FaultCodeEvaluator.FaultCodeAccuracyMetricName], new FaultCodeEvaluator().EvaluationMetricNames); + } - // --------------------------------------------------------------------------------------------- - // The reply states what the lookup resolved. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AReplyThatStatesTheResolvedCode_Passes() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "The console shows E7. That means the motor controller lost the speed signal.", - "E7"); + // --------------------------------------------------------------------------------------------- + // The reply states what the lookup resolved. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AReplyThatStatesTheResolvedCode_Passes() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "The console shows E7. That means the motor controller lost the speed signal.", + "E7"); - Assert.True(metric.Value); - Assert.False(metric.Interpretation!.Failed); - } + Assert.True(metric.Value); + Assert.False(metric.Interpretation!.Failed); + } - [Fact] - public async Task AReplyThatStatesEveryResolvedCode_Passes() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "Two codes apply here. E7 covers the speed signal and E2 covers the incline motor.", - "E7", - "E2"); + [Fact] + public async Task AReplyThatStatesEveryResolvedCode_Passes() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "Two codes apply here. E7 covers the speed signal and E2 covers the incline motor.", + "E7", + "E2"); - Assert.True(metric.Value); - } + Assert.True(metric.Value); + } - // --------------------------------------------------------------------------------------------- - // The first failure: the reply drops a code the lookup resolved. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AReplyThatOmitsTheResolvedCode_Fails() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "That fault means the motor controller lost the speed signal.", - "E7"); - - Assert.False(metric.Value); - Assert.Contains("E7", metric.Reason, StringComparison.Ordinal); - Assert.True(metric.Interpretation!.Failed); - } + // --------------------------------------------------------------------------------------------- + // The first failure: the reply drops a code the lookup resolved. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AReplyThatOmitsTheResolvedCode_Fails() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "That fault means the motor controller lost the speed signal.", + "E7"); + + Assert.False(metric.Value); + Assert.Contains("E7", metric.Reason, StringComparison.Ordinal); + Assert.True(metric.Interpretation!.Failed); + } - [Fact] - public async Task AReplyThatOmitsOneOfTwoResolvedCodes_Fails() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "The console shows E7, which covers the speed signal.", - "E7", - "E2"); - - Assert.False(metric.Value); - Assert.Contains("E2", metric.Reason, StringComparison.Ordinal); - } + [Fact] + public async Task AReplyThatOmitsOneOfTwoResolvedCodes_Fails() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "The console shows E7, which covers the speed signal.", + "E7", + "E2"); + + Assert.False(metric.Value); + Assert.Contains("E2", metric.Reason, StringComparison.Ordinal); + } - [Fact] - public async Task AReplyThatChangesTheCase_Fails() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "The console shows e7, which covers the speed signal.", - "E7"); + [Fact] + public async Task AReplyThatChangesTheCase_Fails() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "The console shows e7, which covers the speed signal.", + "E7"); - Assert.False(metric.Value); - } + Assert.False(metric.Value); + } - // --------------------------------------------------------------------------------------------- - // The second failure: the reply states a code the lookup did not resolve. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AReplyThatInventsACode_Fails() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "The console shows E7. Check E9 as well, because it usually follows.", - "E7"); + // --------------------------------------------------------------------------------------------- + // The second failure: the reply states a code the lookup did not resolve. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AReplyThatInventsACode_Fails() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "The console shows E7. Check E9 as well, because it usually follows.", + "E7"); - Assert.False(metric.Value); - Assert.Contains("E9", metric.Reason, StringComparison.Ordinal); - } + Assert.False(metric.Value); + Assert.Contains("E9", metric.Reason, StringComparison.Ordinal); + } - [Fact] - public async Task AReplyThatStatesACodeWhenTheLookupResolvedNone_Fails() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "That reading is code LS-12 on this model."); + [Fact] + public async Task AReplyThatStatesACodeWhenTheLookupResolvedNone_Fails() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "That reading is code LS-12 on this model."); - Assert.False(metric.Value); - Assert.Contains("LS-12", metric.Reason, StringComparison.Ordinal); - } + Assert.False(metric.Value); + Assert.Contains("LS-12", metric.Reason, StringComparison.Ordinal); + } - [Fact] - public async Task AReplyThatStatesNoCodeWhenTheLookupResolvedNone_Passes() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(), - "Please read me the message on the console and I will look it up."); + [Fact] + public async Task AReplyThatStatesNoCodeWhenTheLookupResolvedNone_Passes() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(), + "Please read me the message on the console and I will look it up."); - Assert.True(metric.Value); - } + Assert.True(metric.Value); + } - // --------------------------------------------------------------------------------------------- - // The shape of a code belongs to the knowledge base. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AHostPattern_ReadsTheCodesThatHostWrites() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(@"\bERR[0-9]{3}\b"), - "The console shows ERR104. It also reports ERR250.", - "ERR104"); + // --------------------------------------------------------------------------------------------- + // The shape of a code belongs to the knowledge base. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AHostPattern_ReadsTheCodesThatHostWrites() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(@"\bERR[0-9]{3}\b"), + "The console shows ERR104. It also reports ERR250.", + "ERR104"); - Assert.False(metric.Value); - Assert.Contains("ERR250", metric.Reason, StringComparison.Ordinal); - } + Assert.False(metric.Value); + Assert.Contains("ERR250", metric.Reason, StringComparison.Ordinal); + } - [Fact] - public async Task AHostPattern_IgnoresAShapeItDoesNotName() - { - BooleanMetric metric = await EvaluateAsync( - new FaultCodeEvaluator(@"\bERR[0-9]{3}\b"), - "The console shows ERR104 on the F85 frame.", - "ERR104"); + [Fact] + public async Task AHostPattern_IgnoresAShapeItDoesNotName() + { + BooleanMetric metric = await EvaluateAsync( + new FaultCodeEvaluator(@"\bERR[0-9]{3}\b"), + "The console shows ERR104 on the F85 frame.", + "ERR104"); - Assert.True(metric.Value); - } + Assert.True(metric.Value); + } - [Fact] - public void AnEmptyPattern_FailsAtStartup() - { - Assert.Throws(() => new FaultCodeEvaluator(string.Empty)); - } + [Fact] + public void AnEmptyPattern_FailsAtStartup() + { + _ = Assert.Throws(() => new FaultCodeEvaluator(string.Empty)); + } - // --------------------------------------------------------------------------------------------- - // Without the context the evaluator knows nothing, and says so. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task WithoutTheContext_TheEvaluatorReportsNoValueAndAnError() - { - EvaluationResult result = await new FaultCodeEvaluator().EvaluateAsync( - Turn, - Reply("The console shows E7."), - cancellationToken: TestContext.Current.CancellationToken); - - BooleanMetric metric = result.Get(FaultCodeEvaluator.FaultCodeAccuracyMetricName); - Assert.Null(metric.Value); - Assert.True(metric.ContainsDiagnostics(diagnostic => diagnostic.Severity == EvaluationDiagnosticSeverity.Error)); - Assert.False(metric.Interpretation!.Failed); - } + // --------------------------------------------------------------------------------------------- + // Without the context the evaluator knows nothing, and says so. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task WithoutTheContext_TheEvaluatorReportsNoValueAndAnError() + { + EvaluationResult result = await new FaultCodeEvaluator().EvaluateAsync( + Turn, + Reply("The console shows E7."), + cancellationToken: TestContext.Current.CancellationToken); + + BooleanMetric metric = result.Get(FaultCodeEvaluator.FaultCodeAccuracyMetricName); + Assert.Null(metric.Value); + Assert.True(metric.ContainsDiagnostics(diagnostic => diagnostic.Severity == EvaluationDiagnosticSeverity.Error)); + Assert.False(metric.Interpretation!.Failed); + } - [Fact] - public async Task TheEvaluatorReadsTheContextOutOfAMixedList() - { - EvaluationResult result = await new FaultCodeEvaluator().EvaluateAsync( - Turn, - Reply("The console shows E7."), - additionalContext: [new OtherContext(), new FaultCodeContext(["E7"])], - cancellationToken: TestContext.Current.CancellationToken); + [Fact] + public async Task TheEvaluatorReadsTheContextOutOfAMixedList() + { + EvaluationResult result = await new FaultCodeEvaluator().EvaluateAsync( + Turn, + Reply("The console shows E7."), + additionalContext: [new OtherContext(), new FaultCodeContext(["E7"])], + cancellationToken: TestContext.Current.CancellationToken); - Assert.True(result.Get(FaultCodeEvaluator.FaultCodeAccuracyMetricName).Value); - } + Assert.True(result.Get(FaultCodeEvaluator.FaultCodeAccuracyMetricName).Value); + } - // --------------------------------------------------------------------------------------------- - // The context. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TheContextCarriesTheCodesTheLookupResolved() - { - FaultCodeContext context = new(["E7", "E2"]); + // --------------------------------------------------------------------------------------------- + // The context. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TheContextCarriesTheCodesTheLookupResolved() + { + FaultCodeContext context = new(["E7", "E2"]); - Assert.Equal(["E7", "E2"], context.Codes); - Assert.Equal(FaultCodeContext.FaultCodeContextName, context.Name); - } + Assert.Equal(["E7", "E2"], context.Codes); + Assert.Equal(FaultCodeContext.FaultCodeContextName, context.Name); + } - [Fact] - public void TheContextReadsALazySequenceOnce() - { - int enumerations = 0; - FaultCodeContext context = new(Codes()); + [Fact] + public void TheContextReadsALazySequenceOnce() + { + int enumerations = 0; + FaultCodeContext context = new(Codes()); - Assert.Equal(["E7"], context.Codes); - Assert.Equal(1, enumerations); + Assert.Equal(["E7"], context.Codes); + Assert.Equal(1, enumerations); - IEnumerable Codes() - { - enumerations++; - yield return "E7"; + IEnumerable Codes() + { + enumerations++; + yield return "E7"; + } } - } - /// A context the evaluator must walk past. - private sealed class OtherContext() : EvaluationContext("Other", "text"); + /// A context the evaluator must walk past. + private sealed class OtherContext() : EvaluationContext("Other", "text"); + } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/PromptModeratorTests.cs b/tests/AgentCore.Application.Tests/Evaluation/PromptModeratorTests.cs index 2cc04cab..f6dcff1b 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/PromptModeratorTests.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/PromptModeratorTests.cs @@ -2,109 +2,116 @@ using AgentCore.Application.Tests.Evaluation.Fakes; using Xunit; -namespace AgentCore.Application.Tests.Evaluation; - -/// -/// The seam that turns a moderation evaluation into the fact the audit chain records. -/// -public sealed class PromptModeratorTests +namespace AgentCore.Application.Tests.Evaluation { - [Fact] - public async Task AnEndpointThatFlagsNothing_NamesNoCategory() - { - PromptModerator moderator = new(ScriptedModerationEvaluator.Clean()); - - var categories = await moderator.FlaggedCategoriesAsync("where is my order", TestContext.Current.CancellationToken); - - Assert.Empty(categories); - } - - [Fact] - public async Task AnEndpointThatFlags_NamesEveryCategoryInTheOrderItReturnedThem() - { - PromptModerator moderator = new(ScriptedModerationEvaluator.Flagging("violence", "harassment")); - - var categories = await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken); - - // The order is the endpoint's, and nothing sorts it. AuditPayloadKeys.ModerationCategories - // promises a reader that order, so a sort here would break the promise at the far end. - Assert.Equal(["violence", "harassment"], categories); - } - - [Fact] - public async Task TheModeratedText_IsWhatTheCallerSaid() - { - var endpoint = ScriptedModerationEvaluator.Clean(); - PromptModerator moderator = new(endpoint); - - await moderator.FlaggedCategoriesAsync("how do I reset the console", TestContext.Current.CancellationToken); - - Assert.Equal(["how do I reset the console"], endpoint.Moderated); - } - - [Fact] - public async Task AnEndpointThatDidNotAnswer_ReadsAsNothingFlagged() - { - // Fail open. A vendor outage must not refuse every caller, so an evaluation carrying no - // verdict reads the same as a clean one here. ConversationSession tells the two apart on a metric. - PromptModerator moderator = new(ScriptedModerationEvaluator.Unanswered()); - - var categories = await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken); - - Assert.Empty(categories); - } - - [Fact] - public async Task AnEndpointThatThrows_Propagates() - { - // The moderator does not swallow. ConversationSession owns the catch, because it owns the log line - // and the metric that report a turn went unchecked. - PromptModerator moderator = new(ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))); - - await Assert.ThrowsAsync( - async () => await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken)); - } - - [Fact] - public void ARegistryWithNoModerationEvaluator_BuildsNoModerator() - => Assert.Null(PromptModerator.FromRegistry(new EvaluatorRegistry())); - - [Fact] - public async Task ARegistryWithAModerationEvaluator_BuildsOneThatCallsIt() + /// + /// The seam that turns a moderation evaluation into the fact the audit chain records. + /// + public sealed class PromptModeratorTests { - var endpoint = ScriptedModerationEvaluator.Flagging("hate"); - EvaluatorRegistry registry = new(); - registry.Register(PromptModerator.ModerationEvaluatorName, endpoint); - - var moderator = PromptModerator.FromRegistry(registry); - - Assert.NotNull(moderator); - Assert.Equal(["hate"], await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken)); - } - - [Fact] - public void ARegistryHoldingOnlyAnotherEvaluator_BuildsNoModerator() - { - EvaluatorRegistry registry = new(); - registry.Register("fault_code", new FaultCodeEvaluator()); - - Assert.Null(PromptModerator.FromRegistry(registry)); - } - - [Fact] - public void TheModeratorRefusesANullEvaluator() - => Assert.Throws(() => new PromptModerator(null!)); - - [Fact] - public void FromRegistryRefusesANullRegistry() - => Assert.Throws(() => PromptModerator.FromRegistry(null!)); - - [Fact] - public async Task TheModeratorRefusesNullText() - { - PromptModerator moderator = new(ScriptedModerationEvaluator.Clean()); - - await Assert.ThrowsAsync( - async () => await moderator.FlaggedCategoriesAsync(null!, TestContext.Current.CancellationToken)); + [Fact] + public async Task AnEndpointThatFlagsNothing_NamesNoCategory() + { + PromptModerator moderator = new(ScriptedModerationEvaluator.Clean()); + + IReadOnlyList categories = await moderator.FlaggedCategoriesAsync("where is my order", TestContext.Current.CancellationToken); + + Assert.Empty(categories); + } + + [Fact] + public async Task AnEndpointThatFlags_NamesEveryCategoryInTheOrderItReturnedThem() + { + PromptModerator moderator = new(ScriptedModerationEvaluator.Flagging("violence", "harassment")); + + IReadOnlyList categories = await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken); + + // The order is the endpoint's, and nothing sorts it. AuditPayloadKeys.ModerationCategories + // promises a reader that order, so a sort here would break the promise at the far end. + Assert.Equal(["violence", "harassment"], categories); + } + + [Fact] + public async Task TheModeratedText_IsWhatTheCallerSaid() + { + ScriptedModerationEvaluator endpoint = ScriptedModerationEvaluator.Clean(); + PromptModerator moderator = new(endpoint); + + _ = await moderator.FlaggedCategoriesAsync("how do I reset the console", TestContext.Current.CancellationToken); + + Assert.Equal(["how do I reset the console"], endpoint.Moderated); + } + + [Fact] + public async Task AnEndpointThatDidNotAnswer_ReadsAsNothingFlagged() + { + // Fail open. A vendor outage must not refuse every caller, so an evaluation carrying no + // verdict reads the same as a clean one here. ConversationSession tells the two apart on a metric. + PromptModerator moderator = new(ScriptedModerationEvaluator.Unanswered()); + + IReadOnlyList categories = await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken); + + Assert.Empty(categories); + } + + [Fact] + public async Task AnEndpointThatThrows_Propagates() + { + // The moderator does not swallow. ConversationSession owns the catch, because it owns the log line + // and the metric that report a turn went unchecked. + PromptModerator moderator = new(ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))); + + _ = await Assert.ThrowsAsync( + async () => await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken)); + } + + [Fact] + public void ARegistryWithNoModerationEvaluator_BuildsNoModerator() + { + Assert.Null(PromptModerator.FromRegistry(new EvaluatorRegistry())); + } + + [Fact] + public async Task ARegistryWithAModerationEvaluator_BuildsOneThatCallsIt() + { + ScriptedModerationEvaluator endpoint = ScriptedModerationEvaluator.Flagging("hate"); + EvaluatorRegistry registry = new(); + _ = registry.Register(PromptModerator.ModerationEvaluatorName, endpoint); + + PromptModerator? moderator = PromptModerator.FromRegistry(registry); + + Assert.NotNull(moderator); + Assert.Equal(["hate"], await moderator.FlaggedCategoriesAsync("...", TestContext.Current.CancellationToken)); + } + + [Fact] + public void ARegistryHoldingOnlyAnotherEvaluator_BuildsNoModerator() + { + EvaluatorRegistry registry = new(); + _ = registry.Register("fault_code", new FaultCodeEvaluator()); + + Assert.Null(PromptModerator.FromRegistry(registry)); + } + + [Fact] + public void TheModeratorRefusesANullEvaluator() + { + _ = Assert.Throws(() => new PromptModerator(null!)); + } + + [Fact] + public void FromRegistryRefusesANullRegistry() + { + _ = Assert.Throws(() => PromptModerator.FromRegistry(null!)); + } + + [Fact] + public async Task TheModeratorRefusesNullText() + { + PromptModerator moderator = new(ScriptedModerationEvaluator.Clean()); + + _ = await Assert.ThrowsAsync( + async () => await moderator.FlaggedCategoriesAsync(null!, TestContext.Current.CancellationToken)); + } } } diff --git a/tests/AgentCore.Application.Tests/Evaluation/ScorePublishingTests.cs b/tests/AgentCore.Application.Tests/Evaluation/ScorePublishingTests.cs index 166dcc1e..a160a32d 100644 --- a/tests/AgentCore.Application.Tests/Evaluation/ScorePublishingTests.cs +++ b/tests/AgentCore.Application.Tests/Evaluation/ScorePublishingTests.cs @@ -2,95 +2,98 @@ using Microsoft.Extensions.AI.Evaluation; using Xunit; -namespace AgentCore.Application.Tests.Evaluation; - -/// -/// The seam that carries a finished evaluation out of the library. -/// -/// -/// The in-memory publisher is the default the seam ships with. It keeps the order scores arrive in, -/// it hands out a copy, and it takes scores from several turns at once. -/// -public sealed class ScorePublishingTests +namespace AgentCore.Application.Tests.Evaluation { - private static EvaluationScore Score(string evaluator, double value) => - new(evaluator, new EvaluationResult(new NumericMetric("Recorded", value))); - - [Fact] - public async Task ThePublisherKeepsTheOrderScoresArriveIn() - { - InMemoryEvaluationScorePublisher publisher = new(); - - await publisher.PublishAsync(Score("fault_code", 1), TestContext.Current.CancellationToken); - await publisher.PublishAsync(Score("moderation", 2), TestContext.Current.CancellationToken); - - Assert.Equal(["fault_code", "moderation"], publisher.Scores.Select(score => score.Evaluator)); - } - - [Fact] - public async Task ThePublisherCarriesTheMetricsUnchanged() + /// + /// The seam that carries a finished evaluation out of the library. + /// + /// + /// The in-memory publisher is the default the seam ships with. It keeps the order scores arrive in, + /// it hands out a copy, and it takes scores from several turns at once. + /// + public sealed class ScorePublishingTests { - InMemoryEvaluationScorePublisher publisher = new(); - EvaluationScore score = Score("fault_code", 0.75); - - await publisher.PublishAsync(score, TestContext.Current.CancellationToken); - - EvaluationScore published = Assert.Single(publisher.Scores); - Assert.Same(score, published); - Assert.Equal(0.75, published.Result.Get("Recorded").Value); - } - - [Fact] - public void ANewPublisherHoldsNothing() - { - Assert.Empty(new InMemoryEvaluationScorePublisher().Scores); - } - - [Fact] - public async Task TheScoresPropertyHandsOutACopy() - { - InMemoryEvaluationScorePublisher publisher = new(); - await publisher.PublishAsync(Score("fault_code", 1), TestContext.Current.CancellationToken); - - IReadOnlyList read = publisher.Scores; - await publisher.PublishAsync(Score("moderation", 2), TestContext.Current.CancellationToken); - - Assert.Single(read); - Assert.Equal(2, publisher.Scores.Count); - } - - [Fact] - public async Task ThePublisherTakesScoresFromManyTurnsAtOnce() - { - InMemoryEvaluationScorePublisher publisher = new(); - CancellationToken cancellationToken = TestContext.Current.CancellationToken; - - await Task.WhenAll(Enumerable.Range(0, 64).Select(index => - Task.Run( - async () => await publisher.PublishAsync(Score("fault_code", index), cancellationToken), - cancellationToken))); - - Assert.Equal(64, publisher.Scores.Count); - } - - [Fact] - public async Task ANullScore_Fails() - { - InMemoryEvaluationScorePublisher publisher = new(); - - await Assert.ThrowsAsync( - async () => await publisher.PublishAsync(null!, TestContext.Current.CancellationToken)); - } - - [Fact] - public async Task ACancelledPublish_Fails() - { - InMemoryEvaluationScorePublisher publisher = new(); - using CancellationTokenSource cancellation = new(); - await cancellation.CancelAsync(); - - await Assert.ThrowsAsync( - async () => await publisher.PublishAsync(Score("fault_code", 1), cancellation.Token)); - Assert.Empty(publisher.Scores); + private static EvaluationScore Score(string evaluator, double value) + { + return new(evaluator, new EvaluationResult(new NumericMetric("Recorded", value))); + } + + [Fact] + public async Task ThePublisherKeepsTheOrderScoresArriveIn() + { + InMemoryEvaluationScorePublisher publisher = new(); + + await publisher.PublishAsync(Score("fault_code", 1), TestContext.Current.CancellationToken); + await publisher.PublishAsync(Score("moderation", 2), TestContext.Current.CancellationToken); + + Assert.Equal(["fault_code", "moderation"], publisher.Scores.Select(score => score.Evaluator)); + } + + [Fact] + public async Task ThePublisherCarriesTheMetricsUnchanged() + { + InMemoryEvaluationScorePublisher publisher = new(); + EvaluationScore score = Score("fault_code", 0.75); + + await publisher.PublishAsync(score, TestContext.Current.CancellationToken); + + EvaluationScore published = Assert.Single(publisher.Scores); + Assert.Same(score, published); + Assert.Equal(0.75, published.Result.Get("Recorded").Value); + } + + [Fact] + public void ANewPublisherHoldsNothing() + { + Assert.Empty(new InMemoryEvaluationScorePublisher().Scores); + } + + [Fact] + public async Task TheScoresPropertyHandsOutACopy() + { + InMemoryEvaluationScorePublisher publisher = new(); + await publisher.PublishAsync(Score("fault_code", 1), TestContext.Current.CancellationToken); + + IReadOnlyList read = publisher.Scores; + await publisher.PublishAsync(Score("moderation", 2), TestContext.Current.CancellationToken); + + _ = Assert.Single(read); + Assert.Equal(2, publisher.Scores.Count); + } + + [Fact] + public async Task ThePublisherTakesScoresFromManyTurnsAtOnce() + { + InMemoryEvaluationScorePublisher publisher = new(); + CancellationToken cancellationToken = TestContext.Current.CancellationToken; + + await Task.WhenAll(Enumerable.Range(0, 64).Select(index => + Task.Run( + async () => await publisher.PublishAsync(Score("fault_code", index), cancellationToken), + cancellationToken))); + + Assert.Equal(64, publisher.Scores.Count); + } + + [Fact] + public async Task ANullScore_Fails() + { + InMemoryEvaluationScorePublisher publisher = new(); + + _ = await Assert.ThrowsAsync( + async () => await publisher.PublishAsync(null!, TestContext.Current.CancellationToken)); + } + + [Fact] + public async Task ACancelledPublish_Fails() + { + InMemoryEvaluationScorePublisher publisher = new(); + using CancellationTokenSource cancellation = new(); + await cancellation.CancelAsync(); + + _ = await Assert.ThrowsAsync( + async () => await publisher.PublishAsync(Score("fault_code", 1), cancellation.Token)); + Assert.Empty(publisher.Scores); + } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs b/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs index b4d5c170..87ebbf53 100644 --- a/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs +++ b/tests/AgentCore.Application.Tests/Fakes/FakeChatClientFactory.cs @@ -2,34 +2,32 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// -/// Hands the same offline client to every model reference. No network, and no API key. -/// -internal sealed class FakeChatClientFactory : IChatClientFactory +namespace AgentCore.Application.Tests.Fakes { - private readonly IChatClient _client; - private readonly int _contextWindow; - - public FakeChatClientFactory(IChatClient client, int contextWindow = 128_000) + /// + /// Hands the same offline client to every model reference. No network, and no API key. + /// + internal sealed class FakeChatClientFactory(IChatClient client, int contextWindow = 128_000) : IChatClientFactory { - _client = client; - _contextWindow = contextWindow; - } + private readonly IChatClient _client = client; + private readonly int _contextWindow = contextWindow; - /// Gets every model reference this factory was asked for, in call order. - public List Requested { get; } = []; + /// Gets every model reference this factory was asked for, in call order. + public List Requested { get; } = []; - public IChatClient GetChatClient(ModelReference? model) - { - lock (Requested) + public IChatClient GetChatClient(ModelReference? model) { - Requested.Add(model); + lock (Requested) + { + Requested.Add(model); + } + + return _client; } - return _client; + public int? GetContextWindow(ModelReference? model) + { + return _contextWindow; + } } - - public int? GetContextWindow(ModelReference? model) => _contextWindow; } diff --git a/tests/AgentCore.Application.Tests/Fakes/RecordingBlobStore.cs b/tests/AgentCore.Application.Tests/Fakes/RecordingBlobStore.cs index e44baf81..ac538c47 100644 --- a/tests/AgentCore.Application.Tests/Fakes/RecordingBlobStore.cs +++ b/tests/AgentCore.Application.Tests/Fakes/RecordingBlobStore.cs @@ -1,45 +1,52 @@ using AgentCore.Application.Blobs; using AgentCore.Application.Ports; -namespace AgentCore.Application.Tests.Fakes; - -/// An in-memory that keeps every write, so a test reads what was stored. -internal sealed class RecordingBlobStore : IBlobStore +namespace AgentCore.Application.Tests.Fakes { - private readonly Dictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> _blobs = []; - - /// Gets every blob stored, keyed by owner and name, in no particular order. - public IReadOnlyDictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> Blobs => _blobs; - - public async ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) + /// An in-memory that keeps every write, so a test reads what was stored. + internal sealed class RecordingBlobStore : IBlobStore { - using MemoryStream copy = new(); - await write.Content.CopyToAsync(copy, cancellationToken); - _blobs[(write.OwnerId, write.Name)] = (write.MediaType, copy.ToArray()); - return new BlobRef(write.OwnerId, write.Name, write.MediaType, write.Length); - } + private readonly Dictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> _blobs = []; - public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out var blob) - ? new BlobRead(blob.MediaType, blob.Bytes.Length, new MemoryStream(blob.Bytes)) - : null); + /// Gets every blob stored, keyed by owner and name, in no particular order. + public IReadOnlyDictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> Blobs => _blobs; - public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out var blob) - ? new BlobRef(ownerId, name, blob.MediaType, blob.Bytes.Length) - : null); + public async ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) + { + using MemoryStream copy = new(); + await write.Content.CopyToAsync(copy, cancellationToken); + _blobs[(write.OwnerId, write.Name)] = (write.MediaType, copy.ToArray()); + return new BlobRef(write.OwnerId, write.Name, write.MediaType, write.Length); + } - /// A recognisable fake link, so a test can see what was linked and for how long. - public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) - => ValueTask.FromResult(new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}")); + public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out (string MediaType, byte[] Bytes) blob) + ? new BlobRead(blob.MediaType, blob.Bytes.Length, new MemoryStream(blob.Bytes)) + : null); + } - public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) - { - foreach (var key in _blobs.Keys.Where(key => key.Owner == ownerId).ToList()) + public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out (string MediaType, byte[] Bytes) blob) + ? new BlobRef(ownerId, name, blob.MediaType, blob.Bytes.Length) + : null); + } + + /// A recognisable fake link, so a test can see what was linked and for how long. + public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) { - _blobs.Remove(key); + return ValueTask.FromResult(new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}")); } - return ValueTask.CompletedTask; + public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) + { + foreach ((string Owner, string Name) key in _blobs.Keys.Where(key => key.Owner == ownerId).ToList()) + { + _ = _blobs.Remove(key); + } + + return ValueTask.CompletedTask; + } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs b/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs index 3e056cbb..bf18d0f0 100644 --- a/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs +++ b/tests/AgentCore.Application.Tests/Fakes/RecordingChatClientAdapter.cs @@ -3,91 +3,99 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// -/// An offline vendor adapter. It answers one kind and records what it was asked to build. -/// -internal sealed class RecordingChatClientAdapter : IChatClientAdapter +namespace AgentCore.Application.Tests.Fakes { - private readonly List _builtNames = []; - private readonly Dictionary _clients = new(StringComparer.Ordinal); - - public RecordingChatClientAdapter(string kind) => Kind = kind; - - public string Kind { get; } - - /// Gets or sets the value answers, or . - public int? ContextWindow { get; set; } - - /// Gets the as names this adapter built a client for, in build order. - public IReadOnlyList BuiltNames => _builtNames; - - /// Gets the resolver chain the last build received. - public ISecretResolverPort? LastSecrets { get; private set; } - - /// Gets the client built for one as name. - public IChatClient ClientOf(string asName) => _clients[asName]; - - /// Gets the same client, typed so a test reads what a conversation carried. - public RecordingChatClient RecorderOf(string asName) => _clients[asName]; - - public ValueTask CreateClientAsync( - LlmProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); - - _builtNames.Add(entry.As); - LastSecrets = secrets; - - RecordingChatClient client = new(); - _clients[entry.As] = client; - return ValueTask.FromResult(client); - } - - public int? GetContextWindow(LlmProviderConfiguration entry) => ContextWindow; -} - -/// -/// A chat client that keeps the options of its last conversation, so a test reads what the seam set. -/// -internal sealed class RecordingChatClient : IChatClient -{ - /// Gets the options of the last conversation, or before one. - public ChatOptions? LastOptions { get; private set; } - - /// Gets how many times ran, so a test can catch a double dispose. - public int DisposeCount { get; private set; } - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - LastOptions = options; - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); - } - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - LastOptions = options; - await Task.CompletedTask.ConfigureAwait(false); - yield return new ChatResponseUpdate(ChatRole.Assistant, "ok"); - } - - public object? GetService(Type serviceType, object? serviceKey = null) + /// + /// An offline vendor adapter. It answers one kind and records what it was asked to build. + /// + internal sealed class RecordingChatClientAdapter(string kind) : IChatClientAdapter { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + private readonly List _builtNames = []; + private readonly Dictionary _clients = new(StringComparer.Ordinal); + + public string Kind { get; } = kind; + + /// Gets or sets the value answers, or . + public int? ContextWindow { get; set; } + + /// Gets the as names this adapter built a client for, in build order. + public IReadOnlyList BuiltNames => _builtNames; + + /// Gets the resolver chain the last build received. + public ISecretResolverPort? LastSecrets { get; private set; } + + /// Gets the client built for one as name. + public IChatClient ClientOf(string asName) + { + return _clients[asName]; + } + + /// Gets the same client, typed so a test reads what a conversation carried. + public RecordingChatClient RecorderOf(string asName) + { + return _clients[asName]; + } + + public ValueTask CreateClientAsync( + LlmProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(entry); + + _builtNames.Add(entry.As); + LastSecrets = secrets; + + RecordingChatClient client = new(); + _clients[entry.As] = client; + return ValueTask.FromResult(client); + } + + public int? GetContextWindow(LlmProviderConfiguration entry) + { + return ContextWindow; + } } - public void Dispose() + /// + /// A chat client that keeps the options of its last conversation, so a test reads what the seam set. + /// + internal sealed class RecordingChatClient : IChatClient { - DisposeCount++; + /// Gets the options of the last conversation, or before one. + public ChatOptions? LastOptions { get; private set; } + + /// Gets how many times ran, so a test can catch a double dispose. + public int DisposeCount { get; private set; } + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + LastOptions = options; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + LastOptions = options; + await Task.CompletedTask.ConfigureAwait(false); + yield return new ChatResponseUpdate(ChatRole.Assistant, "ok"); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + DisposeCount++; + } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs b/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs index 050ed828..038c915b 100644 --- a/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs +++ b/tests/AgentCore.Application.Tests/Fakes/RecordingConversationStore.cs @@ -1,111 +1,113 @@ using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.TestSupport; -using AgentCore.Application.Runtime; using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// A store kept in this process, with the conversations made against its words recorded. -internal sealed class RecordingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) +namespace AgentCore.Application.Tests.Fakes { - private readonly Lock _lock = new(); + /// A store kept in this process, with the conversations made against its words recorded. + internal sealed class RecordingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) + { + private readonly Lock _lock = new(); - /// The words as the store holds them now. It backs , not . - private readonly Dictionary<(string ConversationId, int Ordinal), ConversationMessage> _rows = []; + /// The words as the store holds them now. It backs , not . + private readonly Dictionary<(string ConversationId, int Ordinal), ConversationMessage> _rows = []; - /// Gets every row the provider appended, in the order it appended them. - public List Rows { get; } = []; + /// Gets every row the provider appended, in the order it appended them. + public List Rows { get; } = []; - /// Gets every rewrite the provider asked for, in order. - public List Rewrites { get; } = []; + /// Gets every rewrite the provider asked for, in order. + public List Rewrites { get; } = []; - /// Gets how many times a conversation was read back, by a consumer or by its session. - public int Reads { get; private set; } + /// Gets how many times a conversation was read back, by a consumer or by its session. + public int Reads { get; private set; } - /// Reads one conversation as the store holds it now, oldest message first. - /// The conversation to read. - public IReadOnlyList Live(string conversationId) - { - lock (_lock) + /// Reads one conversation as the store holds it now, oldest message first. + /// The conversation to read. + public IReadOnlyList Live(string conversationId) { - return [.. _rows.Values.Where(row => row.ConversationId == conversationId).OrderBy(row => row.Ordinal)]; + lock (_lock) + { + return [.. _rows.Values.Where(row => row.ConversationId == conversationId).OrderBy(row => row.Ordinal)]; + } } - } - - /// - public override async ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - { - var rows = await base.AppendAsync(conversationId, messages, state, cancellationToken).ConfigureAwait(false); - lock (_lock) + /// + public override async ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) { - Rows.AddRange(rows); - foreach (var row in rows) + IReadOnlyList rows = await base.AppendAsync(conversationId, messages, state, cancellationToken).ConfigureAwait(false); + + lock (_lock) { - _rows[(row.ConversationId, row.Ordinal)] = row; + Rows.AddRange(rows); + foreach (ConversationMessage row in rows) + { + _rows[(row.ConversationId, row.Ordinal)] = row; + } } - } - return rows; - } - - /// - public override async ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - { - await base.RewriteAsync(conversationId, messageId, content, cancellationToken).ConfigureAwait(false); + return rows; + } - lock (_lock) + /// + public override async ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) { - foreach (var pair in _rows) + await base.RewriteAsync(conversationId, messageId, content, cancellationToken).ConfigureAwait(false); + + lock (_lock) { - if (pair.Key.ConversationId != conversationId || pair.Value.MessageId != messageId) + foreach (KeyValuePair<(string ConversationId, int Ordinal), ConversationMessage> pair in _rows) { - continue; + if (pair.Key.ConversationId != conversationId || pair.Value.MessageId != messageId) + { + continue; + } + + ConversationMessage rewritten = pair.Value with { Content = content }; + _rows[pair.Key] = rewritten; + Rewrites.Add(rewritten); + break; } - - var rewritten = pair.Value with { Content = content }; - _rows[pair.Key] = rewritten; - Rewrites.Add(rewritten); - break; } } - } - - /// - /// The rows are the ones somebody said: nothing here writes a summary row. - public override ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - => Read(conversationId); - private ValueTask> Read(string conversationId) - { - lock (_lock) + /// + /// The rows are the ones somebody said: nothing here writes a summary row. + public override ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) { - Reads++; + return Read(conversationId); } - return ValueTask.FromResult(Live(conversationId)); - } - - /// - public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - { - lock (_lock) + private ValueTask> Read(string conversationId) { - var going = _rows.Keys.Where(key => key.ConversationId == conversationId).ToList(); - foreach (var key in going) + lock (_lock) { - _rows.Remove(key); + Reads++; } - return ValueTask.FromResult(going.Count); + return ValueTask.FromResult(Live(conversationId)); + } + + /// + public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + lock (_lock) + { + List<(string ConversationId, int Ordinal)> going = [.. _rows.Keys.Where(key => key.ConversationId == conversationId)]; + foreach ((string ConversationId, int Ordinal) key in going) + { + _ = _rows.Remove(key); + } + + return ValueTask.FromResult(going.Count); + } } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/RequestRecordingChatClient.cs b/tests/AgentCore.Application.Tests/Fakes/RequestRecordingChatClient.cs index 7060363c..a5f0a848 100644 --- a/tests/AgentCore.Application.Tests/Fakes/RequestRecordingChatClient.cs +++ b/tests/AgentCore.Application.Tests/Fakes/RequestRecordingChatClient.cs @@ -1,45 +1,49 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// Answers each request in turn, and keeps what it was asked. -/// -/// It drives the buffered path only. is what a fact about the prompt reads: -/// one role-prefixed line per message, in the order the run sent them. -/// -internal sealed class RequestRecordingChatClient : IChatClient +namespace AgentCore.Application.Tests.Fakes { - private readonly string[] _replies; - - public RequestRecordingChatClient(params string[] replies) => _replies = replies; - - /// Gets every request this client answered, one role-prefixed line per message. - public List> Requests { get; } = []; - - /// Gets the instructions of each request, in call order. A per-invocation context lands here. - public List Instructions { get; } = []; - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Requests.Add([.. messages.Select(message => $"{message.Role}:{message.Text}")]); - Instructions.Add(options?.Instructions); - return Task.FromResult( - new ChatResponse(new ChatMessage(ChatRole.Assistant, _replies[Requests.Count - 1]))); - } - - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException("These facts drive the buffered path only."); - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() + /// Answers each request in turn, and keeps what it was asked. + /// + /// It drives the buffered path only. is what a fact about the prompt reads: + /// one role-prefixed line per message, in the order the run sent them. + /// + internal sealed class RequestRecordingChatClient(params string[] replies) : IChatClient { + private readonly string[] _replies = replies; + + /// Gets every request this client answered, one role-prefixed line per message. + public List> Requests { get; } = []; + + /// Gets the instructions of each request, in call order. A per-invocation context lands here. + public List Instructions { get; } = []; + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + Requests.Add([.. messages.Select(message => $"{message.Role}:{message.Text}")]); + Instructions.Add(options?.Instructions); + return Task.FromResult( + new ChatResponse(new ChatMessage(ChatRole.Assistant, _replies[Requests.Count - 1]))); + } + + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException("These facts drive the buffered path only."); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/ScriptedChatClient.cs b/tests/AgentCore.Application.Tests/Fakes/ScriptedChatClient.cs index e3ecbc43..8ad20d3d 100644 --- a/tests/AgentCore.Application.Tests/Fakes/ScriptedChatClient.cs +++ b/tests/AgentCore.Application.Tests/Fakes/ScriptedChatClient.cs @@ -1,84 +1,86 @@ using System.Runtime.CompilerServices; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// -/// A deterministic offline stand-in for a chat model. No socket, no key. -/// -/// -/// The streaming path yields one update for each fragment. A test may hold the stream open after the -/// first fragment with , which turns "does the seam stream?" into -/// a question a test answers without a stopwatch. -/// -internal sealed class ScriptedChatClient : IChatClient +namespace AgentCore.Application.Tests.Fakes { - private readonly string[] _fragments; - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private int _calls; + /// + /// A deterministic offline stand-in for a chat model. No socket, no key. + /// + /// + /// The streaming path yields one update for each fragment. A test may hold the stream open after the + /// first fragment with , which turns "does the seam stream?" into + /// a question a test answers without a stopwatch. + /// + internal sealed class ScriptedChatClient(params string[] fragments) : IChatClient + { + private readonly string[] _fragments = fragments; + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private int _calls; - public ScriptedChatClient(params string[] fragments) => _fragments = fragments; + /// Gets the text the model produces, as one string. + public string FullText => string.Concat(_fragments); - /// Gets the text the model produces, as one string. - public string FullText => string.Concat(_fragments); + /// Gets or sets whether the stream stops after the first fragment until the gate opens. + public bool GateAfterFirstFragment { get; set; } - /// Gets or sets whether the stream stops after the first fragment until the gate opens. - public bool GateAfterFirstFragment { get; set; } + /// Gets how many requests this client answered. + public int Calls => Volatile.Read(ref _calls); - /// Gets how many requests this client answered. - public int Calls => Volatile.Read(ref _calls); + /// Lets the rest of the fragments flow. + public void OpenGate() + { + _ = _gate.TrySetResult(); + } - /// Lets the rest of the fragments flow. - public void OpenGate() => _gate.TrySetResult(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + _ = Interlocked.Increment(ref _calls); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Interlocked.Increment(ref _calls); + string responseId = Guid.NewGuid().ToString("N"); - var responseId = Guid.NewGuid().ToString("N"); + for (int index = 0; index < _fragments.Length; index++) + { + if (index == 1 && GateAfterFirstFragment) + { + await _gate.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + } - for (var index = 0; index < _fragments.Length; index++) + yield return new ChatResponseUpdate(ChatRole.Assistant, _fragments[index]) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - if (index == 1 && GateAfterFirstFragment) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - await _gate.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + updates.Add(update); } - yield return new ChatResponseUpdate(ChatRole.Assistant, _fragments[index]) - { - ResponseId = responseId, - MessageId = responseId, - }; + return updates.ToChatResponse(); } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } - - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/ShellScriptedClient.cs b/tests/AgentCore.Application.Tests/Fakes/ShellScriptedClient.cs index 986498d2..a05b53c4 100644 --- a/tests/AgentCore.Application.Tests/Fakes/ShellScriptedClient.cs +++ b/tests/AgentCore.Application.Tests/Fakes/ShellScriptedClient.cs @@ -1,97 +1,92 @@ using System.Runtime.CompilerServices; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// One request a answered: what it saw, and what it was offered. -internal sealed record RecordedRequest(IReadOnlyList Messages, ChatOptions? Options); - -/// -/// A deterministic offline model that calls the shell tool once per queued command, feeding the -/// prior tool result back into before asking for the next, then answers -/// "done" once the queue is empty. -/// -internal sealed class ShellScriptedClient : IChatClient +namespace AgentCore.Application.Tests.Fakes { - private readonly string _toolName; - private readonly Queue _commands; - - public ShellScriptedClient(string toolName, params string[] commands) + /// One request a answered: what it saw, and what it was offered. + internal sealed record RecordedRequest(IReadOnlyList Messages, ChatOptions? Options); + + /// + /// A deterministic offline model that calls the shell tool once per queued command, feeding the + /// prior tool result back into before asking for the next, then answers + /// "done" once the queue is empty. + /// + internal sealed class ShellScriptedClient(string toolName, params string[] commands) : IChatClient { - _toolName = toolName; - _commands = new(commands); - } + private readonly string _toolName = toolName; + private readonly Queue _commands = new(commands); - public List Requests { get; } = []; + public List Requests { get; } = []; - public List ToolResults { get; } = []; + public List ToolResults { get; } = []; - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - var transcript = messages.ToList(); - Requests.Add(new RecordedRequest(transcript, options)); - var responseId = Guid.NewGuid().ToString("N"); + List transcript = [.. messages]; + Requests.Add(new RecordedRequest(transcript, options)); + string responseId = Guid.NewGuid().ToString("N"); - var lastResults = transcript.Count > 0 - ? transcript[^1].Contents.OfType().ToList() - : []; + List lastResults = transcript.Count > 0 + ? [.. transcript[^1].Contents.OfType()] + : []; - foreach (var result in lastResults) - { - ToolResults.Add(result.Result?.ToString() ?? string.Empty); - } + foreach (FunctionResultContent? result in lastResults) + { + ToolResults.Add(result.Result?.ToString() ?? string.Empty); + } - if (_commands.Count > 0) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_" + Guid.NewGuid().ToString("N"), - _toolName, - new Dictionary(StringComparer.Ordinal) { ["command"] = _commands.Dequeue() })]) + if (_commands.Count > 0) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_" + Guid.NewGuid().ToString("N"), + _toolName, + new Dictionary(StringComparer.Ordinal) { ["command"] = _commands.Dequeue() })]) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "done") { ResponseId = responseId, MessageId = responseId, }; - yield break; } - yield return new ChatResponseUpdate(ChatRole.Assistant, "done") + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } diff --git a/tests/AgentCore.Application.Tests/Fakes/TestGuardEvaluator.cs b/tests/AgentCore.Application.Tests/Fakes/TestGuardEvaluator.cs index 960629a8..fba6cf62 100644 --- a/tests/AgentCore.Application.Tests/Fakes/TestGuardEvaluator.cs +++ b/tests/AgentCore.Application.Tests/Fakes/TestGuardEvaluator.cs @@ -3,71 +3,72 @@ using AgentCore.Application.Configuration.Validation; using Json.Logic; -namespace AgentCore.Application.Tests.Fakes; - -/// -/// The test double for . -/// -/// -/// The real implementation belongs to the validator. This double exists so the policy runtime and the -/// counter writer can be tested on their own, and it holds the two rules section 8.7 fixes: a guard -/// that throws is not a defect, and a name the table does not hold is false at run time. -/// -internal sealed class TestGuardEvaluator : IGuardEvaluator +namespace AgentCore.Application.Tests.Fakes { - private readonly IReadOnlyDictionary _guards; - - public TestGuardEvaluator(AgentCoreConfiguration configuration) - { - ArgumentNullException.ThrowIfNull(configuration); - _guards = configuration.Guards; - } - - /// Gets how many guards this evaluator failed to run. - public int Failures { get; private set; } - - public bool Evaluate(GuardReference guard, IReadOnlyDictionary state) + /// + /// The test double for . + /// + /// + /// The real implementation belongs to the validator. This double exists so the policy runtime and the + /// counter writer can be tested on their own, and it holds the two rules section 8.7 fixes: a guard + /// that throws is not a defect, and a name the table does not hold is false at run time. + /// + internal sealed class TestGuardEvaluator : IGuardEvaluator { - ArgumentNullException.ThrowIfNull(guard); + private readonly IReadOnlyDictionary _guards; - if (guard.Rule is { } inline) + public TestGuardEvaluator(AgentCoreConfiguration configuration) { - return Evaluate(inline, state); + ArgumentNullException.ThrowIfNull(configuration); + _guards = configuration.Guards; } - return guard.Name is { } name && _guards.TryGetValue(name, out var named) && Evaluate(named, state); - } + /// Gets how many guards this evaluator failed to run. + public int Failures { get; private set; } - public bool Evaluate(JsonNode rule, IReadOnlyDictionary state) - { - ArgumentNullException.ThrowIfNull(rule); - ArgumentNullException.ThrowIfNull(state); - - JsonObject data = []; - foreach (var (name, value) in state) + public bool Evaluate(GuardReference guard, IReadOnlyDictionary state) { - data[name] = value?.DeepClone(); + ArgumentNullException.ThrowIfNull(guard); + + return guard.Rule is { } inline + ? Evaluate(inline, state) + : guard.Name is { } name && _guards.TryGetValue(name, out JsonNode? named) && Evaluate(named, state); } - try + public bool Evaluate(JsonNode rule, IReadOnlyDictionary state) { - return IsTruthy(JsonLogic.Apply(rule, data)); + ArgumentNullException.ThrowIfNull(rule); + ArgumentNullException.ThrowIfNull(state); + + JsonObject data = []; + foreach ((string? name, JsonNode? value) in state) + { + data[name] = value?.DeepClone(); + } + + try + { + return IsTruthy(JsonLogic.Apply(rule, data)); + } + catch (JsonLogicException) + { + // Log once, treat the guard as false, and continue. Section 8.7. + Failures++; + return false; + } } - catch (JsonLogicException) + + private static bool IsTruthy(JsonNode? result) { - // Log once, treat the guard as false, and continue. Section 8.7. - Failures++; - return false; + return result switch + { + null => false, + JsonValue value when value.TryGetValue(out bool flag) => flag, + JsonValue value when value.TryGetValue(out double number) => number != 0, + JsonValue value when value.TryGetValue(out string? text) => !string.IsNullOrEmpty(text), + JsonArray list => list.Count > 0, + _ => true, + }; } } - - private static bool IsTruthy(JsonNode? result) => result switch - { - null => false, - JsonValue value when value.TryGetValue(out bool flag) => flag, - JsonValue value when value.TryGetValue(out double number) => number != 0, - JsonValue value when value.TryGetValue(out string? text) => !string.IsNullOrEmpty(text), - JsonArray list => list.Count > 0, - _ => true, - }; } diff --git a/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs b/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs index 54b88692..80fb5e06 100644 --- a/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs +++ b/tests/AgentCore.Application.Tests/Fakes/ThrowingConversationStore.cs @@ -4,26 +4,35 @@ using AgentCore.TestSupport; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// Refuses every write of words, the way a backing that is down does. -internal sealed class ThrowingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) +namespace AgentCore.Application.Tests.Fakes { - public override ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - => throw new InvalidOperationException("the conversation store is down."); + /// Refuses every write of words, the way a backing that is down does. + internal sealed class ThrowingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) + { + public override ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("the conversation store is down."); + } - public override ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - => throw new InvalidOperationException("the conversation store is down."); + public override ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("the conversation store is down."); + } - public override ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - => throw new InvalidOperationException("the conversation store is down."); + public override ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("the conversation store is down."); + } - public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) - => throw new InvalidOperationException("the conversation store is down."); + public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("the conversation store is down."); + } + } } diff --git a/tests/AgentCore.Application.Tests/Fakes/ToolCallingChatClient.cs b/tests/AgentCore.Application.Tests/Fakes/ToolCallingChatClient.cs index 8071c3c0..e02d7f1f 100644 --- a/tests/AgentCore.Application.Tests/Fakes/ToolCallingChatClient.cs +++ b/tests/AgentCore.Application.Tests/Fakes/ToolCallingChatClient.cs @@ -1,140 +1,135 @@ using System.Runtime.CompilerServices; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Fakes; - -/// -/// A deterministic offline model that calls the first tool it is offered, once, then answers. -/// -/// -/// -/// A delegating agent needs a model that actually emits a tool call, and -/// only emits text. This client emits one -/// when the request carries a tool and the transcript holds no -/// tool result yet. Every other request answers with text, so the inner agent of a -/// kind: agent tool, which is offered no tool, always replies. -/// -/// -/// The one call and the "no result yet" test together keep the run finite. Nothing here depends on -/// the 40-iteration cap of section 8.7. -/// -/// -internal sealed class ToolCallingChatClient : IChatClient +namespace AgentCore.Application.Tests.Fakes { - private const string ConversationId = "conversation_1"; - - private readonly string _reply; - private readonly Dictionary _arguments; - private int _calls; - - public ToolCallingChatClient(string reply, Dictionary? arguments = null) + /// + /// A deterministic offline model that calls the first tool it is offered, once, then answers. + /// + /// + /// + /// A delegating agent needs a model that actually emits a tool call, and + /// only emits text. This client emits one + /// when the request carries a tool and the transcript holds no + /// tool result yet. Every other request answers with text, so the inner agent of a + /// kind: agent tool, which is offered no tool, always replies. + /// + /// + /// The one call and the "no result yet" test together keep the run finite. Nothing here depends on + /// the 40-iteration cap of section 8.7. + /// + /// + internal sealed class ToolCallingChatClient(string reply, Dictionary? arguments = null) : IChatClient { - _reply = reply; - _arguments = arguments ?? new Dictionary(StringComparer.Ordinal); - } + private const string ConversationId = "conversation_1"; - /// Gets the text of the last user message of each request, in call order. - public List Prompts { get; } = []; + private readonly string _reply = reply; + private readonly Dictionary _arguments = arguments ?? new Dictionary(StringComparer.Ordinal); + private int _calls; - /// Gets every tool result this client read back, in call order. - public List ToolResults { get; } = []; + /// Gets the text of the last user message of each request, in call order. + public List Prompts { get; } = []; - /// Gets the name of each tool this client asked to call. - public List Called { get; } = []; + /// Gets every tool result this client read back, in call order. + public List ToolResults { get; } = []; - /// Gets every function this client was offered, in call order. This is what the model reads. - public List Offered { get; } = []; + /// Gets the name of each tool this client asked to call. + public List Called { get; } = []; - /// Gets how many requests this client answered. - public int Calls => Volatile.Read(ref _calls); - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Interlocked.Increment(ref _calls); - await Task.Yield(); + /// Gets every function this client was offered, in call order. This is what the model reads. + public List Offered { get; } = []; - var transcript = messages.ToList(); - var answered = false; + /// Gets how many requests this client answered. + public int Calls => Volatile.Read(ref _calls); - lock (Prompts) + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - foreach (var message in transcript) + ArgumentNullException.ThrowIfNull(messages); + _ = Interlocked.Increment(ref _calls); + await Task.Yield(); + + List transcript = [.. messages]; + bool answered = false; + + lock (Prompts) { - foreach (var content in message.Contents) + foreach (ChatMessage? message in transcript) { - if (content is FunctionResultContent result) + foreach (AIContent content in message.Contents) { - answered = true; - ToolResults.Add(result.Result?.ToString() ?? string.Empty); + if (content is FunctionResultContent result) + { + answered = true; + ToolResults.Add(result.Result?.ToString() ?? string.Empty); + } } } - } - var prompt = transcript.LastOrDefault(message => message.Role == ChatRole.User); - Prompts.Add(prompt?.Text ?? string.Empty); - } + ChatMessage? prompt = transcript.LastOrDefault(message => message.Role == ChatRole.User); + Prompts.Add(prompt?.Text ?? string.Empty); + } - var responseId = Guid.NewGuid().ToString("N"); - var functions = options?.Tools?.OfType().ToList() ?? []; - var tool = functions.FirstOrDefault(); + string responseId = Guid.NewGuid().ToString("N"); + List functions = options?.Tools?.OfType().ToList() ?? []; + AIFunction? tool = functions.FirstOrDefault(); - lock (Prompts) - { - Offered.AddRange(functions); - } - - if (tool is not null && !answered) - { lock (Prompts) { - Called.Add(tool.Name); + Offered.AddRange(functions); + } + + if (tool is not null && !answered) + { + lock (Prompts) + { + Called.Add(tool.Name); + } + + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent(ConversationId, tool.Name, _arguments)]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; } - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent(ConversationId, tool.Name, _arguments)]) + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) { ResponseId = responseId, MessageId = responseId, }; - - yield break; } - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/CompositeKnowledgeStoreFactoryTests.cs b/tests/AgentCore.Application.Tests/Knowledge/CompositeKnowledgeStoreFactoryTests.cs index cf3d044e..ecc2d202 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/CompositeKnowledgeStoreFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/CompositeKnowledgeStoreFactoryTests.cs @@ -6,20 +6,20 @@ using AgentCore.Application.Tests.Knowledge.Fakes; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The composite behind UseKnowledgeStores. It routes providers.knowledge.kind to the -/// adapter whose matches. -/// -/// -/// Every adapter here is a fake, so every test runs offline. The document names the vendor and the -/// host registers the adapters; these tests prove the document alone decides which adapter answers. -/// -public sealed class CompositeKnowledgeStoreFactoryTests +namespace AgentCore.Application.Tests.Knowledge { - private const string NoKnowledgeYaml = - """ + /// + /// The composite behind UseKnowledgeStores. It routes providers.knowledge.kind to the + /// adapter whose matches. + /// + /// + /// Every adapter here is a fake, so every test runs offline. The document names the vendor and the + /// host registers the adapters; these tests prove the document alone decides which adapter answers. + /// + public sealed class CompositeKnowledgeStoreFactoryTests + { + private const string NoKnowledgeYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -29,8 +29,8 @@ public sealed class CompositeKnowledgeStoreFactoryTests agent: only """; - private const string OneKindYaml = - """ + private const string OneKindYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -50,8 +50,8 @@ public sealed class CompositeKnowledgeStoreFactoryTests agent: only """; - private const string ShoutedKindYaml = - """ + private const string ShoutedKindYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -70,136 +70,136 @@ public sealed class CompositeKnowledgeStoreFactoryTests agent: only """; - // --------------------------------------------------------------------------------------------- - // Routing: the document names the vendor, and the matching adapter builds it. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindWrittenInAnotherCase_StillFindsItsAdapter() - { - RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - - var port = await Create(ShoutedKindYaml, qdrant); - - Assert.Same(qdrant.Search, port); - } - - [Fact] - public async Task NoKnowledgeBlockAtAll_FailsWithAPointerAtTheBlock() - { - // There is no entry to invent. A standing-in default would guess the vendor, the collection - // name AND the payload shape, then fail somewhere further in against a store nobody named. - RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); + // --------------------------------------------------------------------------------------------- + // Routing: the document names the vendor, and the matching adapter builds it. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindWrittenInAnotherCase_StillFindsItsAdapter() + { + RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - var failure = await Assert.ThrowsAsync( - async () => await Create(NoKnowledgeYaml, qdrant)); + IKnowledgeRetrievalPort? port = await Create(ShoutedKindYaml, qdrant); - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/knowledge"); - Assert.False(qdrant.CreateSearchCalled); - } + Assert.Same(qdrant.Search, port); + } - [Fact] - public async Task TheAdapter_ReceivesTheGeneratorTheHostBuilt() - { - RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - Embeddings.Fakes.FakeEmbeddingGenerator embeddings = new(); - - await CompositeKnowledgeStoreFactory.CreateAsync( - ConfigurationLoader.LoadYaml(OneKindYaml), - secrets: null, - [qdrant], - embeddings, - scopeDeclared: false, - requireScope: false, - TestContext.Current.CancellationToken); - - Assert.Same(embeddings, qdrant.LastEmbeddings); - } - - [Fact] - public async Task TheAdapter_ReceivesTheEntryAndTheResolverChainTheHostBound() - { - RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - MapSecretResolver resolver = new(); + [Fact] + public async Task NoKnowledgeBlockAtAll_FailsWithAPointerAtTheBlock() + { + // There is no entry to invent. A standing-in default would guess the vendor, the collection + // name AND the payload shape, then fail somewhere further in against a store nobody named. + RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - await Create(OneKindYaml, resolver, qdrant); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(NoKnowledgeYaml, qdrant)); - Assert.Same(resolver, qdrant.LastSecrets); - Assert.Equal("manuals", qdrant.LastEntry?.Collection); - } + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/knowledge"); + Assert.False(qdrant.CreateSearchCalled); + } - [Fact] - public async Task TheAdapter_ReceivesRequireScopeSeparatelyFromScopeDeclared() - { - // Ruling 14(a): requireScope (ALL agents scoped) is a different question from the - // scopeDeclared this factory already validates CanScope against (ANY agent scoped), and it - // must reach the adapter even when scopeDeclared itself is false. - RecordingKnowledgeStoreAdapter qdrant = new("qdrant") { CanScope = true }; + [Fact] + public async Task TheAdapter_ReceivesTheGeneratorTheHostBuilt() + { + RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); + Embeddings.Fakes.FakeEmbeddingGenerator embeddings = new(); + + _ = await CompositeKnowledgeStoreFactory.CreateAsync( + ConfigurationLoader.LoadYaml(OneKindYaml), + secrets: null, + [qdrant], + embeddings, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken); + + Assert.Same(embeddings, qdrant.LastEmbeddings); + } + + [Fact] + public async Task TheAdapter_ReceivesTheEntryAndTheResolverChainTheHostBound() + { + RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); + MapSecretResolver resolver = new(); - var port = await CompositeKnowledgeStoreFactory.CreateAsync( - Document(kind: "qdrant"), secrets: null, [qdrant], embeddings: null, scopeDeclared: false, requireScope: true, CancellationToken.None); + _ = await Create(OneKindYaml, resolver, qdrant); - Assert.NotNull(port); - Assert.True(qdrant.LastRequireScope); - } + Assert.Same(resolver, qdrant.LastSecrets); + Assert.Equal("manuals", qdrant.LastEntry?.Collection); + } - // --------------------------------------------------------------------------------------------- - // What it refuses, at startup and never on the first conversation. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindNoAdapterServes_FailsAndNamesTheRegisteredKinds() - { - var failure = await Assert.ThrowsAsync( - async () => await Create(OneKindYaml, new RecordingKnowledgeStoreAdapter("filesystem"))); - - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/knowledge/kind", error.Pointer); - Assert.Contains("qdrant", error.Message, StringComparison.Ordinal); - Assert.Contains("'filesystem'", error.Message, StringComparison.Ordinal); - } + [Fact] + public async Task TheAdapter_ReceivesRequireScopeSeparatelyFromScopeDeclared() + { + // Ruling 14(a): requireScope (ALL agents scoped) is a different question from the + // scopeDeclared this factory already validates CanScope against (ANY agent scoped), and it + // must reach the adapter even when scopeDeclared itself is false. + RecordingKnowledgeStoreAdapter qdrant = new("qdrant") { CanScope = true }; + + IKnowledgeRetrievalPort? port = await CompositeKnowledgeStoreFactory.CreateAsync( + Document(kind: "qdrant"), secrets: null, [qdrant], embeddings: null, scopeDeclared: false, requireScope: true, CancellationToken.None); + + Assert.NotNull(port); + Assert.True(qdrant.LastRequireScope); + } + + // --------------------------------------------------------------------------------------------- + // What it refuses, at startup and never on the first conversation. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindNoAdapterServes_FailsAndNamesTheRegisteredKinds() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(OneKindYaml, new RecordingKnowledgeStoreAdapter("filesystem"))); - [Fact] - public async Task AnAdapterThatDoesNotServeSearch_FailsAndNamesThePort() - { - RecordingKnowledgeStoreAdapter qdrant = new("qdrant") { CanServeSearch = false }; + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/knowledge/kind", error.Pointer); + Assert.Contains("qdrant", error.Message, StringComparison.Ordinal); + Assert.Contains("'filesystem'", error.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - async () => await Create(OneKindYaml, qdrant)); + [Fact] + public async Task AnAdapterThatDoesNotServeSearch_FailsAndNamesThePort() + { + RecordingKnowledgeStoreAdapter qdrant = new("qdrant") { CanServeSearch = false }; - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/knowledge/kind", error.Pointer); - Assert.Contains(nameof(IKnowledgeRetrievalPort), error.Message, StringComparison.Ordinal); - Assert.False(qdrant.CreateSearchCalled); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(OneKindYaml, qdrant)); - [Fact] - public async Task TwoAdaptersOfOneKind_FailTheBuild() - { - var failure = await Assert.ThrowsAsync(async () => await Create( - OneKindYaml, - new RecordingKnowledgeStoreAdapter("qdrant"), - new RecordingKnowledgeStoreAdapter("QDrant"))); - - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/knowledge/kind", error.Pointer); - Assert.Contains("qdrant", error.Message, StringComparison.OrdinalIgnoreCase); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/knowledge/kind", error.Pointer); + Assert.Contains(nameof(IKnowledgeRetrievalPort), error.Message, StringComparison.Ordinal); + Assert.False(qdrant.CreateSearchCalled); + } - [Fact] - public async Task AHostThatRegistersNoAdapter_FailsAndSaysSo() - { - var failure = await Assert.ThrowsAsync( - async () => await Create(OneKindYaml)); + [Fact] + public async Task TwoAdaptersOfOneKind_FailTheBuild() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => await Create( + OneKindYaml, + new RecordingKnowledgeStoreAdapter("qdrant"), + new RecordingKnowledgeStoreAdapter("QDrant"))); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/knowledge/kind", error.Pointer); + Assert.Contains("qdrant", error.Message, StringComparison.OrdinalIgnoreCase); + } + + [Fact] + public async Task AHostThatRegistersNoAdapter_FailsAndSaysSo() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(OneKindYaml)); - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/knowledge/kind", error.Pointer); - Assert.Contains("no adapter", error.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/knowledge/kind", error.Pointer); + Assert.Contains("no adapter", error.Message, StringComparison.Ordinal); + } - [Fact] - public async Task CitationsWithBothCitationFieldsDisabled_FailsTheLoadPointingAtFieldsSource() - { - const string yaml = - """ + [Fact] + public async Task CitationsWithBothCitationFieldsDisabled_FailsTheLoadPointingAtFieldsSource() + { + const string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -219,20 +219,20 @@ public async Task CitationsWithBothCitationFieldsDisabled_FailsTheLoadPointingAt main: agent: only """; - RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); + RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - var failure = await Assert.ThrowsAsync( - async () => await Create(yaml, qdrant)); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(yaml, qdrant)); - Assert.Equal("/providers/knowledge/fields/source", failure.Pointer); - Assert.False(qdrant.CreateSearchCalled); - } + Assert.Equal("/providers/knowledge/fields/source", failure.Pointer); + Assert.False(qdrant.CreateSearchCalled); + } - [Fact] - public async Task CitationsWithOnlyTheLocatorMapped_StillLoads() - { - const string yaml = - """ + [Fact] + public async Task CitationsWithOnlyTheLocatorMapped_StillLoads() + { + const string yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -252,85 +252,93 @@ public async Task CitationsWithOnlyTheLocatorMapped_StillLoads() main: agent: only """; - RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); + RecordingKnowledgeStoreAdapter qdrant = new("qdrant"); - var port = await Create(yaml, qdrant); + IKnowledgeRetrievalPort? port = await Create(yaml, qdrant); - Assert.NotNull(port); - } + Assert.NotNull(port); + } - // --------------------------------------------------------------------------------------------- - // The CanScope startup rule. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task CreateAsync_ScopeDeclaredAndAdapterCannotScope_FailsTheStart() - { - var configuration = Document(kind: "flat"); - var adapter = new RecordingKnowledgeStoreAdapter("flat") { CanScope = false }; - - var thrown = await Assert.ThrowsAsync( - async () => await CompositeKnowledgeStoreFactory.CreateAsync( - configuration, secrets: null, [adapter], embeddings: null, scopeDeclared: true, requireScope: true, CancellationToken.None)); - - Assert.Contains("/providers/knowledge/kind", thrown.Message, StringComparison.Ordinal); - Assert.Contains("cannot apply a scope", thrown.Message, StringComparison.Ordinal); - Assert.False(adapter.CreateSearchCalled); - } - - [Fact] - public async Task CreateAsync_ScopeDeclaredAndAdapterCanScope_Opens() - { - var configuration = Document(kind: "scoped"); - var adapter = new RecordingKnowledgeStoreAdapter("scoped") { CanScope = true }; + // --------------------------------------------------------------------------------------------- + // The CanScope startup rule. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task CreateAsync_ScopeDeclaredAndAdapterCannotScope_FailsTheStart() + { + AgentCoreConfiguration configuration = Document(kind: "flat"); + RecordingKnowledgeStoreAdapter adapter = new("flat") { CanScope = false }; - var port = await CompositeKnowledgeStoreFactory.CreateAsync( - configuration, secrets: null, [adapter], embeddings: null, scopeDeclared: true, requireScope: true, CancellationToken.None); + ConfigurationLoadException thrown = await Assert.ThrowsAsync( + async () => await CompositeKnowledgeStoreFactory.CreateAsync( + configuration, secrets: null, [adapter], embeddings: null, scopeDeclared: true, requireScope: true, CancellationToken.None)); - Assert.NotNull(port); - Assert.True(adapter.CreateSearchCalled); - } + Assert.Contains("/providers/knowledge/kind", thrown.Message, StringComparison.Ordinal); + Assert.Contains("cannot apply a scope", thrown.Message, StringComparison.Ordinal); + Assert.False(adapter.CreateSearchCalled); + } - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - /// Builds a document whose only interesting field is providers.knowledge.kind. - /// - /// The rest of the block is here because the composite requires it, not because these tests are - /// about it: a body to map, and a scope template for the tests that declare a scope. Neither has - /// a default to fall back on. - /// - private static AgentCoreConfiguration Document(string kind) - => new() + [Fact] + public async Task CreateAsync_ScopeDeclaredAndAdapterCanScope_Opens() + { + AgentCoreConfiguration configuration = Document(kind: "scoped"); + RecordingKnowledgeStoreAdapter adapter = new("scoped") { CanScope = true }; + + IKnowledgeRetrievalPort? port = await CompositeKnowledgeStoreFactory.CreateAsync( + configuration, secrets: null, [adapter], embeddings: null, scopeDeclared: true, requireScope: true, CancellationToken.None); + + Assert.NotNull(port); + Assert.True(adapter.CreateSearchCalled); + } + + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + /// Builds a document whose only interesting field is providers.knowledge.kind. + /// + /// The rest of the block is here because the composite requires it, not because these tests are + /// about it: a body to map, and a scope template for the tests that declare a scope. Neither has + /// a default to fall back on. + /// + private static AgentCoreConfiguration Document(string kind) { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Providers = new ProvidersConfiguration + return new() { - Knowledge = new KnowledgeProviderConfiguration + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Providers = new ProvidersConfiguration { - Kind = kind, - Collection = "manuals", - Fields = new KnowledgeFieldsConfiguration { Body = "body" }, - Scope = new KnowledgeScopeConfiguration { Template = "facets.{key}" }, + Knowledge = new KnowledgeProviderConfiguration + { + Kind = kind, + Collection = "manuals", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + Scope = new KnowledgeScopeConfiguration { Template = "facets.{key}" }, + }, }, - }, - }; - - private static ValueTask Create( - string yaml, - params IKnowledgeStoreAdapter[] adapters) - => Create(yaml, null, adapters); - - private static ValueTask Create( - string yaml, - ISecretResolverPort? secrets, - params IKnowledgeStoreAdapter[] adapters) - => CompositeKnowledgeStoreFactory.CreateAsync( - ConfigurationLoader.LoadYaml(yaml), - secrets, - adapters, - embeddings: null, - scopeDeclared: false, - requireScope: false, - TestContext.Current.CancellationToken); + }; + } + + private static ValueTask Create( + string yaml, + params IKnowledgeStoreAdapter[] adapters) + { + return Create(yaml, null, adapters); + } + + private static ValueTask Create( + string yaml, + ISecretResolverPort? secrets, + params IKnowledgeStoreAdapter[] adapters) + { + return CompositeKnowledgeStoreFactory.CreateAsync( + ConfigurationLoader.LoadYaml(yaml), + secrets, + adapters, + embeddings: null, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken); + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs b/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs index bcaf431c..5755ccd0 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs @@ -15,333 +15,343 @@ using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The filters argument a tool-mode agent narrows its own search with. -/// -public sealed class FacetFilterTests +namespace AgentCore.Application.Tests.Knowledge { - private static readonly KnowledgeScopeConfiguration Declared = new() - { - Template = "facets.{key}", - Filterable = - [ - new() { Key = "model", Description = "The machine and the year, as one tag." }, - new() { Key = "section", Description = "Which part of the manual." }, - ], - }; - - [Fact] - public async Task ToolMode_NothingFilterable_OffersThePlainSearch() - { - var tool = await SearchToolAsync(new StubKnowledgePort([]), scope: null); - - Assert.False(tool.JsonSchema.GetProperty("properties").TryGetProperty("filters", out _)); - } - - [Fact] - public async Task ToolMode_FilterableDeclared_PutsEveryKeyInTheEnum() - { - var tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); - - var keys = tool.JsonSchema - .GetProperty("properties").GetProperty("filters") - .GetProperty("items").GetProperty("properties").GetProperty("key") - .GetProperty("enum") - .EnumerateArray() - .Select(value => value.GetString()) - .ToList(); - - Assert.Equal(["model", "section"], keys); - } - - [Fact] - public async Task ToolMode_FilterableDeclared_TellsTheModelWhatEachKeyMeans() + /// + /// The filters argument a tool-mode agent narrows its own search with. + /// + public sealed class FacetFilterTests { - var tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); - - var wording = tool.JsonSchema - .GetProperty("properties").GetProperty("filters") - .GetProperty("description") - .GetString(); - - Assert.Contains("model: The machine and the year, as one tag.", wording, StringComparison.Ordinal); - Assert.Contains("section: Which part of the manual.", wording, StringComparison.Ordinal); - } - - [Fact] - public async Task ToolMode_FacetWithResolve_TellsTheModelHowToFindTheValue() - { - KnowledgeScopeConfiguration scope = new() + private static readonly KnowledgeScopeConfiguration Declared = new() { Template = "facets.{key}", Filterable = [ - new() { Key = "lookup", Description = "The only value is model-numbers." }, - new() - { - Key = "model", - Description = "The machine and the year, as one tag.", - Resolve = new() - { - Via = new() { Key = "lookup", Value = "model-numbers" }, - Query = " model number", - Read = "the Tag column of the row for the person's year", - }, - }, + new() { Key = "model", Description = "The machine and the year, as one tag." }, + new() { Key = "section", Description = "Which part of the manual." }, ], }; - var tool = await SearchToolAsync(new StubKnowledgePort([]), scope); + [Fact] + public async Task ToolMode_NothingFilterable_OffersThePlainSearch() + { + AIFunction tool = await SearchToolAsync(new StubKnowledgePort([]), scope: null); - var wording = tool.JsonSchema - .GetProperty("properties").GetProperty("filters") - .GetProperty("description") - .GetString(); + Assert.False(tool.JsonSchema.GetProperty("properties").TryGetProperty("filters", out _)); + } - Assert.Contains( - "model: The machine and the year, as one tag. To find the value: search once for " - + "\" model number\" with filters [{key: lookup, value: model-numbers}], and read " - + "the Tag column of the row for the person's year. Copy it exactly; never build one.", - wording, - StringComparison.Ordinal); - } + [Fact] + public async Task ToolMode_FilterableDeclared_PutsEveryKeyInTheEnum() + { + AIFunction tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); - [Fact] - public async Task ToolMode_FilterableDeclared_SaysTheValueIsMatchedExactly() - { - var tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); - - var wording = tool.JsonSchema - .GetProperty("properties").GetProperty("filters") - .GetProperty("items").GetProperty("properties").GetProperty("value") - .GetProperty("description") - .GetString(); - - Assert.Equal( - "The value, exactly as the cards store it; it is matched exactly. A key that says how to " - + "find its value must be found that way first.", - wording); - } + List keys = [.. tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("items").GetProperty("properties").GetProperty("key") + .GetProperty("enum") + .EnumerateArray() + .Select(value => value.GetString())]; - [Fact] - public async Task Filters_NarrowTheScopeTheStoreSees() - { - StubKnowledgePort port = new([Card("a")]); - var tool = await SearchToolAsync(port, Declared); + Assert.Equal(["model", "section"], keys); + } - await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); + [Fact] + public async Task ToolMode_FilterableDeclared_TellsTheModelWhatEachKeyMeans() + { + AIFunction tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); - Assert.Equal("lcr-2023", port.ScopeAtTheStore!.Facets["model"]); - Assert.Equal(KnowledgeFacetOrigin.Tool, port.ScopeAtTheStore.Origins["model"]); - } + string? wording = tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("description") + .GetString(); - [Fact] - public async Task Filters_AreNotForwardedToTheInnerFunction() - { - StubKnowledgePort port = new([Card("a")]); - var tool = await SearchToolAsync(port, Declared); + Assert.Contains("model: The machine and the year, as one tag.", wording, StringComparison.Ordinal); + Assert.Contains("section: Which part of the manual.", wording, StringComparison.Ordinal); + } - await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); + [Fact] + public async Task ToolMode_FacetWithResolve_TellsTheModelHowToFindTheValue() + { + KnowledgeScopeConfiguration scope = new() + { + Template = "facets.{key}", + Filterable = + [ + new() { Key = "lookup", Description = "The only value is model-numbers." }, + new() + { + Key = "model", + Description = "The machine and the year, as one tag.", + Resolve = new() + { + Via = new() { Key = "lookup", Value = "model-numbers" }, + Query = " model number", + Read = "the Tag column of the row for the person's year", + }, + }, + ], + }; + + AIFunction tool = await SearchToolAsync(new StubKnowledgePort([]), scope); + + string? wording = tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("description") + .GetString(); + + Assert.Contains( + "model: The machine and the year, as one tag. To find the value: search once for " + + "\" model number\" with filters [{key: lookup, value: model-numbers}], and read " + + "the Tag column of the row for the person's year. Copy it exactly; never build one.", + wording, + StringComparison.Ordinal); + } + + [Fact] + public async Task ToolMode_FilterableDeclared_SaysTheValueIsMatchedExactly() + { + AIFunction tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); + + string? wording = tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("items").GetProperty("properties").GetProperty("value") + .GetProperty("description") + .GetString(); + + Assert.Equal( + "The value, exactly as the cards store it; it is matched exactly. A key that says how to " + + "find its value must be found that way first.", + wording); + } + + [Fact] + public async Task Filters_NarrowTheScopeTheStoreSees() + { + StubKnowledgePort port = new([Card("a")]); + AIFunction tool = await SearchToolAsync(port, Declared); - Assert.Equal("what belt fits it?", port.LastQuery); - } + _ = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); - [Fact] - public async Task Filters_AKeyNobodyDeclared_IsIgnored() - { - StubKnowledgePort port = new([Card("a")]); - var tool = await SearchToolAsync(port, Declared); + Assert.Equal("lcr-2023", port.ScopeAtTheStore!.Facets["model"]); + Assert.Equal(KnowledgeFacetOrigin.Tool, port.ScopeAtTheStore.Origins["model"]); + } - await CallAsync(tool, "anything", ("customer", "globex")); + [Fact] + public async Task Filters_AreNotForwardedToTheInnerFunction() + { + StubKnowledgePort port = new([Card("a")]); + AIFunction tool = await SearchToolAsync(port, Declared); - Assert.Empty(port.ScopeAtTheStore!.Facets); - } + _ = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); - [Fact] - public async Task Filters_ClearNoCard_TheSearchRunsAgainWithoutThem() - { - // The whole point of the safety net: a filter is the model's guess at the subject, and a - // guess that matches nothing must not become "nothing is documented". - ScopeFilteringKnowledgePort port = new( - (Card("belt"), new Dictionary(StringComparer.Ordinal) { ["model"] = "lcr-2019" })); + Assert.Equal("what belt fits it?", port.LastQuery); + } - var tool = await SearchToolAsync(port, Declared); + [Fact] + public async Task Filters_AKeyNobodyDeclared_IsIgnored() + { + StubKnowledgePort port = new([Card("a")]); + AIFunction tool = await SearchToolAsync(port, Declared); - var answer = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); + _ = await CallAsync(tool, "anything", ("customer", "globex")); - Assert.Contains("card belt", answer, StringComparison.Ordinal); - } + Assert.Empty(port.ScopeAtTheStore!.Facets); + } - [Fact] - public async Task Filters_ClearNoCardAndNothingElseDoesEither_StaysEmpty() - { - ScopeFilteringKnowledgePort port = new(); + [Fact] + public async Task Filters_ClearNoCard_TheSearchRunsAgainWithoutThem() + { + // The whole point of the safety net: a filter is the model's guess at the subject, and a + // guess that matches nothing must not become "nothing is documented". + ScopeFilteringKnowledgePort port = new( + (Card("belt"), new Dictionary(StringComparer.Ordinal) { ["model"] = "lcr-2019" })); - var tool = await SearchToolAsync(port, Declared); + AIFunction tool = await SearchToolAsync(port, Declared); - var answer = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); + string answer = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); - Assert.DoesNotContain("card ", answer, StringComparison.Ordinal); - } + Assert.Contains("card belt", answer, StringComparison.Ordinal); + } - [Fact] - public async Task Filters_AreNamedInTheRecordAnOperatorDebugsFrom() - { - // The record is written while the search's own scope is still the composed one. Built a - // line later, it names whatever the turn composed instead -- and the one thing an operator - // opens this record to see, which facet narrowed the search that found nothing, is exactly - // the part that goes missing. - RecordingLoggerFactory loggers = new(); + [Fact] + public async Task Filters_ClearNoCardAndNothingElseDoesEither_StaysEmpty() + { + ScopeFilteringKnowledgePort port = new(); - var tool = await SearchToolAsync(new StubKnowledgePort([Card("a")]), Declared, loggers: loggers); - await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); + AIFunction tool = await SearchToolAsync(port, Declared); - var line = Assert.Single(loggers.Of(11)); - var record = line.Field("Record"); + string answer = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); - Assert.NotNull(record); - Assert.Equal("model=lcr-2023 (Tool)", record!.Scope); - } + Assert.DoesNotContain("card ", answer, StringComparison.Ordinal); + } - [Fact] - public async Task Invoking_ToolFromEarlierProvider_LeavesItUnwrapped() - { - // Arrange - var skillTool = AIFunctionFactory.Create( - (string skillName) => "skill-body:" + skillName, - "load_skill", - "Loads the full content of a skill."); - var provider = KnowledgeProviderFactory.Create( - new StubKnowledgePort([Card("a")]), - new ResolvedKnowledge(KnowledgeMode.Tool, Limit: 5, Citations: false, Scoped: false), - "agent-under-test", - new SourceLocatorCitationFormatter(), - null, - Declared); + [Fact] + public async Task Filters_AreNamedInTheRecordAnOperatorDebugsFrom() + { + // The record is written while the search's own scope is still the composed one. Built a + // line later, it names whatever the turn composed instead -- and the one thing an operator + // opens this record to see, which facet narrowed the search that found nothing, is exactly + // the part that goes missing. + RecordingLoggerFactory loggers = new(); -#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - var context = new AIContextProvider.InvokingContext( - StubAgent.Instance, - new StubSession(), - new AIContext - { - Messages = [new ChatMessage(ChatRole.User, "hello")], - Tools = [skillTool], - }); -#pragma warning restore MAAI001 + AIFunction tool = await SearchToolAsync(new StubKnowledgePort([Card("a")]), Declared, loggers: loggers); + _ = await CallAsync(tool, "what belt fits it?", ("model", "lcr-2023")); - // Act - var provided = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + CapturedLine line = Assert.Single(loggers.Of(11)); + KnowledgeAuditRecord.LogView? record = line.Field("Record"); - // Assert - var tools = Assert.IsType>(provided.Tools); - Assert.Same(skillTool, tools[0]); - Assert.IsType(tools[1], exactMatch: false); - } + Assert.NotNull(record); + Assert.Equal("model=lcr-2023 (Tool)", record!.Scope); + } - private static async Task SearchToolAsync( - IKnowledgeRetrievalPort port, - KnowledgeScopeConfiguration? scope, - ILoggerFactory? loggers = null) - { - var provider = KnowledgeProviderFactory.Create( - port, - new ResolvedKnowledge(KnowledgeMode.Tool, Limit: 5, Citations: false, Scoped: false), - "agent-under-test", - new SourceLocatorCitationFormatter(), - loggers, - scope); + [Fact] + public async Task Invoking_ToolFromEarlierProvider_LeavesItUnwrapped() + { + // Arrange + AIFunction skillTool = AIFunctionFactory.Create( + (string skillName) => "skill-body:" + skillName, + "load_skill", + "Loads the full content of a skill."); + AIContextProvider provider = KnowledgeProviderFactory.Create( + new StubKnowledgePort([Card("a")]), + new ResolvedKnowledge(KnowledgeMode.Tool, Limit: 5, Citations: false, Scoped: false), + "agent-under-test", + new SourceLocatorCitationFormatter(), + null, + Declared); #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - var context = await provider.InvokingAsync( - new AIContextProvider.InvokingContext( + AIContextProvider.InvokingContext context = new( StubAgent.Instance, new StubSession(), - new AIContext { Messages = [new ChatMessage(ChatRole.User, "hello")] }), - TestContext.Current.CancellationToken); + new AIContext + { + Messages = [new ChatMessage(ChatRole.User, "hello")], + Tools = [skillTool], + }); #pragma warning restore MAAI001 - return Assert.IsType(Assert.Single(context.Tools!), exactMatch: false); - } + // Act + AIContext provided = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - private static async Task CallAsync( - AIFunction tool, string question, params (string Key, string Value)[] filters) - { - Dictionary arguments = new(StringComparer.Ordinal) + // Assert + List tools = Assert.IsType>(provided.Tools); + Assert.Same(skillTool, tools[0]); + _ = Assert.IsType(tools[1], exactMatch: false); + } + + private static async Task SearchToolAsync( + IKnowledgeRetrievalPort port, + KnowledgeScopeConfiguration? scope, + ILoggerFactory? loggers = null) { - ["userQuestion"] = question, - ["filters"] = JsonSerializer.SerializeToElement( - filters.Select(filter => new Dictionary(StringComparer.Ordinal) - { - ["key"] = filter.Key, - ["value"] = filter.Value, - })), - }; + AIContextProvider provider = KnowledgeProviderFactory.Create( + port, + new ResolvedKnowledge(KnowledgeMode.Tool, Limit: 5, Citations: false, Scoped: false), + "agent-under-test", + new SourceLocatorCitationFormatter(), + loggers, + scope); + +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + AIContext context = await provider.InvokingAsync( + new AIContextProvider.InvokingContext( + StubAgent.Instance, + new StubSession(), + new AIContext { Messages = [new ChatMessage(ChatRole.User, "hello")] }), + TestContext.Current.CancellationToken); +#pragma warning restore MAAI001 - TurnInvocation turn = new() + return Assert.IsType(Assert.Single(context.Tools!), exactMatch: false); + } + + private static async Task CallAsync( + AIFunction tool, string question, params (string Key, string Value)[] filters) { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Knowledge = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) }, - }; + Dictionary arguments = new(StringComparer.Ordinal) + { + ["userQuestion"] = question, + ["filters"] = JsonSerializer.SerializeToElement( + filters.Select(filter => new Dictionary(StringComparer.Ordinal) + { + ["key"] = filter.Key, + ["value"] = filter.Value, + })), + }; - var results = await tool.InvokeAsync( - turn.FileIn(new AIFunctionArguments(arguments)), TestContext.Current.CancellationToken) - as IReadOnlyList; + TurnInvocation turn = new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Knowledge = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) }, + }; - return results is null ? string.Empty : string.Join("\n", results.Select(result => result.Text)); - } - private sealed class StubSession : AgentSession; + return await tool.InvokeAsync( + turn.FileIn(new AIFunctionArguments(arguments)), TestContext.Current.CancellationToken) is not IReadOnlyList results ? string.Empty : string.Join("\n", results.Select(result => result.Text)); + } - /// Stands in for the agent the framework names on a context. Nothing here runs it. - private sealed class StubAgent : AIAgent - { - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - } + private sealed class StubSession : AgentSession; - private static KnowledgeCard Card(string id) - => new() + /// Stands in for the agent the framework names on a context. Nothing here runs it. + private sealed class StubAgent : AIAgent { - CardId = id, - Text = "card " + id, - Authority = 3, - SourceRef = "ct900-om", - SourceLocator = "p.27", - Score = 0.87, - ViaLink = false, - }; + public static StubAgent Instance { get; } = new(); + + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) + { + return new(new StubSession()); + } + + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } + + private static KnowledgeCard Card(string id) + { + return new() + { + CardId = id, + Text = "card " + id, + Authority = 3, + SourceRef = "ct900-om", + SourceLocator = "p.27", + Score = 0.87, + ViaLink = false, + }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/Fakes/RecordingKnowledgeStoreAdapter.cs b/tests/AgentCore.Application.Tests/Knowledge/Fakes/RecordingKnowledgeStoreAdapter.cs index 751c25b1..b403274b 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/Fakes/RecordingKnowledgeStoreAdapter.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/Fakes/RecordingKnowledgeStoreAdapter.cs @@ -3,70 +3,70 @@ using AgentCore.Domain.Knowledge; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Knowledge.Fakes; - -/// -/// An offline knowledge vendor. It answers one kind and records what it was asked to build. -/// -internal sealed class RecordingKnowledgeStoreAdapter : IKnowledgeStoreAdapter +namespace AgentCore.Application.Tests.Knowledge.Fakes { - public RecordingKnowledgeStoreAdapter(string kind) - => Kind = kind; + /// + /// An offline knowledge vendor. It answers one kind and records what it was asked to build. + /// + internal sealed class RecordingKnowledgeStoreAdapter(string kind) : IKnowledgeStoreAdapter + { + public string Kind { get; } = kind; - public string Kind { get; } + public bool CanServeSearch { get; init; } = true; - public bool CanServeSearch { get; init; } = true; + public bool CanScope { get; init; } = true; - public bool CanScope { get; init; } = true; + /// Gets whether the composite asked this adapter to build. + public bool CreateSearchCalled { get; private set; } - /// Gets whether the composite asked this adapter to build. - public bool CreateSearchCalled { get; private set; } + /// Gets the entry the last build received. + public KnowledgeProviderConfiguration? LastEntry { get; private set; } - /// Gets the entry the last build received. - public KnowledgeProviderConfiguration? LastEntry { get; private set; } + /// Gets the resolver chain the last build received. + public ISecretResolverPort? LastSecrets { get; private set; } - /// Gets the resolver chain the last build received. - public ISecretResolverPort? LastSecrets { get; private set; } + /// Gets requireScope the last build received. + public bool LastRequireScope { get; private set; } - /// Gets requireScope the last build received. - public bool LastRequireScope { get; private set; } + /// Gets the embedding generator the last build received. + public IEmbeddingGenerator>? LastEmbeddings { get; private set; } - /// Gets the embedding generator the last build received. - public IEmbeddingGenerator>? LastEmbeddings { get; private set; } + /// Gets the object the last build returned. + public IKnowledgeRetrievalPort? Search { get; private set; } - /// Gets the object the last build returned. - public IKnowledgeRetrievalPort? Search { get; private set; } + public ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(entry); - public ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(entry); + if (!CanServeSearch) + { + throw new NotSupportedException($"the '{Kind}' adapter does not rank."); + } - if (!CanServeSearch) - { - throw new NotSupportedException($"the '{Kind}' adapter does not rank."); + CreateSearchCalled = true; + LastEntry = entry; + LastSecrets = secrets; + LastEmbeddings = embeddings; + LastRequireScope = requireScope; + Search = new FakeKnowledgeStore(); + return ValueTask.FromResult(Search); } - - CreateSearchCalled = true; - LastEntry = entry; - LastSecrets = secrets; - LastEmbeddings = embeddings; - LastRequireScope = requireScope; - Search = new FakeKnowledgeStore(); - return ValueTask.FromResult(Search); } -} -/// A store that answers the knowledge port with nothing. -internal sealed class FakeKnowledgeStore : IKnowledgeRetrievalPort -{ - public ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + /// A store that answers the knowledge port with nothing. + internal sealed class FakeKnowledgeStore : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs b/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs index b48ca318..f5ed0137 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs @@ -3,132 +3,123 @@ using AgentCore.Application.Runtime; using AgentCore.Domain.Knowledge; -namespace AgentCore.Application.Tests.Knowledge.Fakes; - -/// A store that answers every query with the same cards, and records what it was asked. -internal sealed class StubKnowledgePort : IKnowledgeRetrievalPort +namespace AgentCore.Application.Tests.Knowledge.Fakes { - private readonly IReadOnlyList _cards; - - public StubKnowledgePort(IReadOnlyList cards) - => _cards = cards; - - /// Gets the query of the last search, or when none ran. - public string? LastQuery { get; private set; } + /// A store that answers every query with the same cards, and records what it was asked. + internal sealed class StubKnowledgePort(IReadOnlyList cards) : IKnowledgeRetrievalPort + { + private readonly IReadOnlyList _cards = cards; + + /// Gets the query of the last search, or when none ran. + public string? LastQuery { get; private set; } + + /// Gets how many searches reached this store. + public int Calls { get; private set; } + + /// Gets the scope the last search was handed, or when none ran. + /// + /// Read here rather than in the test body on purpose: the real store reads the passed scope at + /// exactly this point, deep inside the provider's delegate. A test that reads it anywhere else + /// proves something easier. + /// + public KnowledgeScope? ScopeAtTheStore { get; private set; } + + /// Always : the store is handed a scope, never the turn's holder. + public Clarifications? ClarificationsAtTheStore { get; private set; } + + public ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + LastQuery = query; + ScopeAtTheStore = scope; + Calls++; + return ValueTask.FromResult(_cards); + } + } - /// Gets how many searches reached this store. - public int Calls { get; private set; } + /// A store that is down. + internal sealed class ThrowingKnowledgePort(Exception failure) : IKnowledgeRetrievalPort + { + private readonly Exception _failure = failure; + + public ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + throw _failure; + } + } - /// Gets the scope the last search was handed, or when none ran. + /// + /// A store that hangs, with a deadline of its own linked into the caller's token. + /// /// - /// Read here rather than in the test body on purpose: the real store reads the passed scope at - /// exactly this point, deep inside the provider's delegate. A test that reads it anywhere else - /// proves something easier. + /// + /// This is QdrantKnowledgeStore's cancellation shape, reproduced rather than described: a + /// linked source, CancelAfter, and an await that ends when either side fires. Hand-throwing + /// an instead would let a test pass against a classifier + /// that read the exception's own token — which in the real store is the LINKED token on both paths, + /// and so tells the two cases apart in neither. + /// + /// + /// Whichever side fires, the exception is the same type and carries the same token. Only the + /// caller's own token differs between the two, which is what the provider must read. + /// /// - public KnowledgeScope? ScopeAtTheStore { get; private set; } - - /// Always : the store is handed a scope, never the turn's holder. - public Clarifications? ClarificationsAtTheStore { get; private set; } - - public ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default) + internal sealed class HangingKnowledgePort(TimeSpan deadline) : IKnowledgeRetrievalPort { - LastQuery = query; - ScopeAtTheStore = scope; - Calls++; - return ValueTask.FromResult(_cards); - } -} + private readonly TimeSpan _deadline = deadline; -/// A store that is down. -internal sealed class ThrowingKnowledgePort : IKnowledgeRetrievalPort -{ - private readonly Exception _failure; - - public ThrowingKnowledgePort(Exception failure) - => _failure = failure; + public async ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + using CancellationTokenSource deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + deadline.CancelAfter(_deadline); - public ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default) - => throw _failure; -} + await Task.Delay(Timeout.Infinite, deadline.Token).ConfigureAwait(false); -/// -/// A store that hangs, with a deadline of its own linked into the caller's token. -/// -/// -/// -/// This is QdrantKnowledgeStore's cancellation shape, reproduced rather than described: a -/// linked source, CancelAfter, and an await that ends when either side fires. Hand-throwing -/// an instead would let a test pass against a classifier -/// that read the exception's own token — which in the real store is the LINKED token on both paths, -/// and so tells the two cases apart in neither. -/// -/// -/// Whichever side fires, the exception is the same type and carries the same token. Only the -/// caller's own token differs between the two, which is what the provider must read. -/// -/// -internal sealed class HangingKnowledgePort : IKnowledgeRetrievalPort -{ - private readonly TimeSpan _deadline; - - public HangingKnowledgePort(TimeSpan deadline) - => _deadline = deadline; - - public async ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default) - { - using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - deadline.CancelAfter(_deadline); - - await Task.Delay(Timeout.Infinite, deadline.Token).ConfigureAwait(false); - - throw new UnreachableException(); + throw new UnreachableException(); + } } -} -/// -/// A store that filters the way the real one does: it folds the passed scope's facets into its answer. -/// -/// -/// ignores the scope, so it can prove which scope arrived but never -/// what the scope costs. This one answers differently under a different scope, which is what makes -/// "an unscoped agent still sees the whole corpus" a fact rather than a restatement of the wiring. -/// -internal sealed class ScopeFilteringKnowledgePort : IKnowledgeRetrievalPort -{ - private static readonly IReadOnlyDictionary NoFacets = - new Dictionary(StringComparer.Ordinal); - - private readonly IReadOnlyList<(KnowledgeCard Card, IReadOnlyDictionary Facets)> _corpus; - - public ScopeFilteringKnowledgePort( - params (KnowledgeCard Card, IReadOnlyDictionary Facets)[] corpus) - => _corpus = corpus; - - public ValueTask> SearchAsync( - string query, - KnowledgeScope? scope = null, - CancellationToken cancellationToken = default) + /// + /// A store that filters the way the real one does: it folds the passed scope's facets into its answer. + /// + /// + /// ignores the scope, so it can prove which scope arrived but never + /// what the scope costs. This one answers differently under a different scope, which is what makes + /// "an unscoped agent still sees the whole corpus" a fact rather than a restatement of the wiring. + /// + internal sealed class ScopeFilteringKnowledgePort( + params (KnowledgeCard Card, IReadOnlyDictionary Facets)[] corpus) : IKnowledgeRetrievalPort { - var wanted = scope?.Facets ?? NoFacets; - - IReadOnlyList hits = - [ - .. _corpus - .Where(entry => wanted.All(facet => - entry.Facets.TryGetValue(facet.Key, out var held) - && string.Equals(held, facet.Value, StringComparison.Ordinal))) - .Select(entry => entry.Card), - ]; - - return ValueTask.FromResult(hits); + private static readonly IReadOnlyDictionary NoFacets = + new Dictionary(StringComparer.Ordinal); + + private readonly IReadOnlyList<(KnowledgeCard Card, IReadOnlyDictionary Facets)> _corpus = corpus; + + public ValueTask> SearchAsync( + string query, + KnowledgeScope? scope = null, + CancellationToken cancellationToken = default) + { + IReadOnlyDictionary wanted = scope?.Facets ?? NoFacets; + + IReadOnlyList hits = + [ + .. _corpus + .Where(entry => wanted.All(facet => + entry.Facets.TryGetValue(facet.Key, out string? held) + && string.Equals(held, facet.Value, StringComparison.Ordinal))) + .Select(entry => entry.Card), + ]; + + return ValueTask.FromResult(hits); + } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs b/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs index cf131104..5b7e9c47 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/HybridCachingKnowledgeRetrievalPortTests.cs @@ -6,154 +6,167 @@ using Microsoft.Extensions.DependencyInjection; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The cache in front of the knowledge store. A repeat of one query under one scope must not -/// reach the store again; a different query or a different facet must. What comes back must be -/// the card the store gave, payload tree included. -/// -public sealed class HybridCachingKnowledgeRetrievalPortTests +namespace AgentCore.Application.Tests.Knowledge { - private static readonly KnowledgeCard Card = new() + /// + /// The cache in front of the knowledge store. A repeat of one query under one scope must not + /// reach the store again; a different query or a different facet must. What comes back must be + /// the card the store gave, payload tree included. + /// + public sealed class HybridCachingKnowledgeRetrievalPortTests { - CardId = "card-1", - Text = "Loosen the four bolts.", - ViaLink = false, - SourceRef = "manual-f85", - SourceLocator = "p.12", - Authority = 3, - Score = 0.91, - Extras = new Dictionary(StringComparer.Ordinal) + private static readonly KnowledgeCard Card = new() { - ["model"] = "f85-2019", - ["page"] = 12L, - ["weight"] = 1.5, - ["draft"] = false, - ["tags"] = (IReadOnlyList)["belt", "deck"], - ["source"] = new Dictionary(StringComparer.Ordinal) { ["doc"] = "owner-manual" }, - }, - }; - - private static HybridCache NewCache() - { - ServiceCollection services = new(); - services.AddHybridCache(); - return services.BuildServiceProvider().GetRequiredService(); - } - - private static KnowledgeScope Scope(params (string Key, string Value)[] facets) => new() - { - Facets = facets.ToDictionary(facet => facet.Key, facet => facet.Value, StringComparer.Ordinal), - }; - - [Fact] - public async Task Repeat_of_one_query_skips_the_store() - { - StubKnowledgePort store = new([Card]); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - - await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); - await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); - - Assert.Equal(1, store.Calls); - } - - [Fact] - public async Task A_cached_card_reads_back_whole() - { - StubKnowledgePort store = new([Card]); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - - await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); - var cards = await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); - - var card = Assert.Single(cards); - Assert.Equal(Card with { Extras = card.Extras }, card); - Assert.Equal("f85-2019", PayloadPath.Read(card.Extras, "model")); - Assert.Equal(12L, PayloadPath.Read(card.Extras, "page")); - Assert.Equal(1.5, PayloadPath.Read(card.Extras, "weight")); - Assert.False(Assert.IsType(PayloadPath.Read(card.Extras, "draft"))); - Assert.Equal("owner-manual", PayloadPath.Read(card.Extras, "source.doc")); - Assert.Equal(["belt", "deck"], Assert.IsType>(PayloadPath.Read(card.Extras, "tags"), exactMatch: false)); - } - - [Fact] - public async Task A_different_facet_value_reaches_the_store() - { - StubKnowledgePort store = new([Card]); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + CardId = "card-1", + Text = "Loosen the four bolts.", + ViaLink = false, + SourceRef = "manual-f85", + SourceLocator = "p.12", + Authority = 3, + Score = 0.91, + Extras = new Dictionary(StringComparer.Ordinal) + { + ["model"] = "f85-2019", + ["page"] = 12L, + ["weight"] = 1.5, + ["draft"] = false, + ["tags"] = (IReadOnlyList)["belt", "deck"], + ["source"] = new Dictionary(StringComparer.Ordinal) { ["doc"] = "owner-manual" }, + }, + }; + + private static HybridCache NewCache() + { + ServiceCollection services = new(); + _ = services.AddHybridCache(); + return services.BuildServiceProvider().GetRequiredService(); + } - await port.SearchAsync("belt slips", Scope(("model", "f85")), TestContext.Current.CancellationToken); - await port.SearchAsync("belt slips", Scope(("model", "f63")), TestContext.Current.CancellationToken); + private static KnowledgeScope Scope(params (string Key, string Value)[] facets) + { + return new() + { + Facets = facets.ToDictionary(facet => facet.Key, facet => facet.Value, StringComparer.Ordinal), + }; + } + + [Fact] + public async Task Repeat_of_one_query_skips_the_store() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - Assert.Equal(2, store.Calls); - } + _ = await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + _ = await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); - [Fact] - public async Task Facet_order_does_not_change_the_key() - { - StubKnowledgePort store = new([Card]); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + Assert.Equal(1, store.Calls); + } - await port.SearchAsync("belt slips", Scope(("model", "f85"), ("code", "us")), TestContext.Current.CancellationToken); - await port.SearchAsync("belt slips", Scope(("code", "us"), ("model", "f85")), TestContext.Current.CancellationToken); + [Fact] + public async Task A_cached_card_reads_back_whole() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + + _ = await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + IReadOnlyList cards = await port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken); + + KnowledgeCard card = Assert.Single(cards); + Assert.Equal(Card with { Extras = card.Extras }, card); + Assert.Equal("f85-2019", PayloadPath.Read(card.Extras, "model")); + Assert.Equal(12L, PayloadPath.Read(card.Extras, "page")); + Assert.Equal(1.5, PayloadPath.Read(card.Extras, "weight")); + Assert.False(Assert.IsType(PayloadPath.Read(card.Extras, "draft"))); + Assert.Equal("owner-manual", PayloadPath.Read(card.Extras, "source.doc")); + Assert.Equal(["belt", "deck"], Assert.IsType>(PayloadPath.Read(card.Extras, "tags"), exactMatch: false)); + } + + [Fact] + public async Task A_different_facet_value_reaches_the_store() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - Assert.Equal(1, store.Calls); - } + _ = await port.SearchAsync("belt slips", Scope(("model", "f85")), TestContext.Current.CancellationToken); + _ = await port.SearchAsync("belt slips", Scope(("model", "f63")), TestContext.Current.CancellationToken); - [Fact] - public async Task A_store_that_is_down_caches_nothing() - { - ThrowingKnowledgePort store = new(new InvalidOperationException("down")); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + Assert.Equal(2, store.Calls); + } - await Assert.ThrowsAsync( - () => port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken).AsTask()); - await Assert.ThrowsAsync( - () => port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken).AsTask()); - } + [Fact] + public async Task Facet_order_does_not_change_the_key() + { + StubKnowledgePort store = new([Card]); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - [Fact] - public void A_capability_of_the_store_is_reachable_through_the_cache() - { - FacetCapablePort store = new(); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + _ = await port.SearchAsync("belt slips", Scope(("model", "f85"), ("code", "us")), TestContext.Current.CancellationToken); + _ = await port.SearchAsync("belt slips", Scope(("code", "us"), ("model", "f85")), TestContext.Current.CancellationToken); - Assert.Same(store, port.GetService()); - Assert.Same(port, port.GetService()); - } + Assert.Equal(1, store.Calls); + } - [Fact] - public async Task Closing_the_cache_closes_the_store() - { - DisposingPort store = new(); - HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); + [Fact] + public async Task A_store_that_is_down_caches_nothing() + { + ThrowingKnowledgePort store = new(new InvalidOperationException("down")); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - await port.DisposeAsync(); + _ = await Assert.ThrowsAsync( + () => port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken).AsTask()); + _ = await Assert.ThrowsAsync( + () => port.SearchAsync("belt slips", cancellationToken: TestContext.Current.CancellationToken).AsTask()); + } - Assert.True(store.Closed); - } + [Fact] + public void A_capability_of_the_store_is_reachable_through_the_cache() + { + FacetCapablePort store = new(); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - private sealed class FacetCapablePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort - { - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + Assert.Same(store, port.GetService()); + Assert.Same(port, port.GetService()); + } - public ValueTask> ReadByFacetAsync( - string path, string value, int limit, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); - } + [Fact] + public async Task Closing_the_cache_closes_the_store() + { + DisposingPort store = new(); + HybridCachingKnowledgeRetrievalPort port = new(store, NewCache()); - private sealed class DisposingPort : IKnowledgeRetrievalPort, IDisposable - { - public bool Closed { get; private set; } + await port.DisposeAsync(); - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + Assert.True(store.Closed); + } - public void Dispose() => Closed = true; + private sealed class FacetCapablePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + + public ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + } + + private sealed class DisposingPort : IKnowledgeRetrievalPort, IDisposable + { + public bool Closed { get; private set; } + + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + + public void Dispose() + { + Closed = true; + } + } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs index 0a43254b..469782e6 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs @@ -3,184 +3,192 @@ using AgentCore.Domain.Knowledge; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The only place a Qdrant outage's real cause survives once tool mode discards it. -/// -public sealed class KnowledgeAuditRecordTests +namespace AgentCore.Application.Tests.Knowledge { - [Fact] - public void Cards_DistinguishRankedFromLinked() - { - // `via` is the mechanism the probes proved is required for correctness, three times over. - // It is therefore the thing that will need debugging. - var record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Prefetch, "e33", Scope(), - [Ranked("a", 0.87), Linked("b")], latencyMs: 106, failure: null); - - Assert.Equal("ranked", record.Cards[0].Via); - - // "link", not "see_also". How a card arrived is the audit record's own vocabulary; the old - // value was one collection's payload key, and a deployment whose link field is named - // something else read a log line naming a field it does not have. - Assert.Equal("link", record.Cards[1].Via); - Assert.Null(record.Cards[1].Score); - } - - [Fact] - public void For_ReadsTheWholeRetrievalLatencyAsOneNumber() + /// + /// The only place a Qdrant outage's real cause survives once tool mode discards it. + /// + public sealed class KnowledgeAuditRecordTests { - // Ruling 19: IKnowledgeRetrievalPort is one atomic method, so embed time and search time - // are not separately observable above it. There is one field, not two. - var record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Prefetch, "e33", Scope(), - [], latencyMs: 106, failure: null); - - Assert.Equal(106, record.LatencyMs); - } - - [Fact] - public void For_AFailedRetrieval_KeepsTheRealCause() - { - // In tool mode the framework discards the exception message. This is the only place it survives. - var record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Tool, "e33", Scope(), - [], latencyMs: 92, failure: new InvalidOperationException("qdrant is down")); + [Fact] + public void Cards_DistinguishRankedFromLinked() + { + // `via` is the mechanism the probes proved is required for correctness, three times over. + // It is therefore the thing that will need debugging. + KnowledgeAuditRecord record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Prefetch, "e33", Scope(), + [Ranked("a", 0.87), Linked("b")], latencyMs: 106, failure: null); + + Assert.Equal("ranked", record.Cards[0].Via); + + // "link", not "see_also". How a card arrived is the audit record's own vocabulary; the old + // value was one collection's payload key, and a deployment whose link field is named + // something else read a log line naming a field it does not have. + Assert.Equal("link", record.Cards[1].Via); + Assert.Null(record.Cards[1].Score); + } + + [Fact] + public void For_ReadsTheWholeRetrievalLatencyAsOneNumber() + { + // Ruling 19: IKnowledgeRetrievalPort is one atomic method, so embed time and search time + // are not separately observable above it. There is one field, not two. + KnowledgeAuditRecord record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Prefetch, "e33", Scope(), + [], latencyMs: 106, failure: null); - Assert.Contains("qdrant is down", record.Failure, StringComparison.Ordinal); - } + Assert.Equal(106, record.LatencyMs); + } - [Fact] - public void CardEntry_CarriesEveryFieldTheCitationIsRebuiltFrom() - { - // Only Via and Score were checked before, so a mapping mistake in the other four would - // survive: an engineer reading the record would be shown the wrong manual, at the wrong page, - // for the wrong card, with nothing looking broken. - var record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Prefetch, "e33", Scope(), - [Ranked("ct900-e33-incline-err", 0.87)], latencyMs: 106, failure: null); - - var card = Assert.Single(record.Cards); - Assert.Equal("ct900-e33-incline-err", card.CardId); - Assert.Equal(3, card.Authority); - Assert.Equal("ct900-om", card.SourceRef); - Assert.Equal("p.27", card.Locator); - Assert.Equal(0.87, card.Score); - } + [Fact] + public void For_AFailedRetrieval_KeepsTheRealCause() + { + // In tool mode the framework discards the exception message. This is the only place it survives. + KnowledgeAuditRecord record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Tool, "e33", Scope(), + [], latencyMs: 92, failure: new InvalidOperationException("qdrant is down")); - [Fact] - public void For_CarriesEveryFieldTheOutageIsDiagnosedFrom() - { - var record = KnowledgeAuditRecord.For("analyst", KnowledgeMode.Tool, "belt slipping", Scope(), - [], latencyMs: 106, failure: null) with { TurnId = "turn-7" }; - - Assert.Equal("turn-7", record.TurnId); - Assert.Equal("analyst", record.Agent); - Assert.Equal(KnowledgeMode.Tool, record.Mode); - Assert.Equal("belt slipping", record.Query); - Assert.Equal("ct900", record.Scope["model"]); - } + Assert.Contains("qdrant is down", record.Failure, StringComparison.Ordinal); + } - [Fact] - public void For_NoTurnIdIsReachable_LeavesTheFieldEmptyRatherThanInventingOne() - { - // Ruling 19, then Ruling 21. The provider that writes this record can reach no conversation id and no - // turn index, so it passes null. A synthesised id would read as real to whoever greps for it. - var record = KnowledgeAuditRecord.For("analyst", KnowledgeMode.Tool, "e33", scope: null, - [], latencyMs: 106, failure: null); + [Fact] + public void CardEntry_CarriesEveryFieldTheCitationIsRebuiltFrom() + { + // Only Via and Score were checked before, so a mapping mistake in the other four would + // survive: an engineer reading the record would be shown the wrong manual, at the wrong page, + // for the wrong card, with nothing looking broken. + KnowledgeAuditRecord record = KnowledgeAuditRecord.For("resolver", KnowledgeMode.Prefetch, "e33", Scope(), + [Ranked("ct900-e33-incline-err", 0.87)], latencyMs: 106, failure: null); + + KnowledgeAuditRecord.CardEntry card = Assert.Single(record.Cards); + Assert.Equal("ct900-e33-incline-err", card.CardId); + Assert.Equal(3, card.Authority); + Assert.Equal("ct900-om", card.SourceRef); + Assert.Equal("p.27", card.Locator); + Assert.Equal(0.87, card.Score); + } + + [Fact] + public void For_CarriesEveryFieldTheOutageIsDiagnosedFrom() + { + KnowledgeAuditRecord record = KnowledgeAuditRecord.For("analyst", KnowledgeMode.Tool, "belt slipping", Scope(), + [], latencyMs: 106, failure: null) with + { TurnId = "turn-7" }; + + Assert.Equal("turn-7", record.TurnId); + Assert.Equal("analyst", record.Agent); + Assert.Equal(KnowledgeMode.Tool, record.Mode); + Assert.Equal("belt slipping", record.Query); + Assert.Equal("ct900", record.Scope["model"]); + } + + [Fact] + public void For_NoTurnIdIsReachable_LeavesTheFieldEmptyRatherThanInventingOne() + { + // Ruling 19, then Ruling 21. The provider that writes this record can reach no conversation id and no + // turn index, so it passes null. A synthesised id would read as real to whoever greps for it. + KnowledgeAuditRecord record = KnowledgeAuditRecord.For("analyst", KnowledgeMode.Tool, "e33", scope: null, + [], latencyMs: 106, failure: null); - Assert.Null(record.TurnId); - Assert.Empty(record.Scope); - } + Assert.Null(record.TurnId); + Assert.Empty(record.Scope); + } - [Fact] - public void CardEntry_CardWithNoAuthorityOrSource_RecordsNulls() - { - var card = new KnowledgeCard { CardId = "plain-01", Text = "a card", ViaLink = false }; + [Fact] + public void CardEntry_CardWithNoAuthorityOrSource_RecordsNulls() + { + KnowledgeCard card = new() { CardId = "plain-01", Text = "a card", ViaLink = false }; - var entry = KnowledgeAuditRecord.CardEntry.From(card); + KnowledgeAuditRecord.CardEntry entry = KnowledgeAuditRecord.CardEntry.From(card); - Assert.Equal("plain-01", entry.CardId); - Assert.Null(entry.Authority); - Assert.Equal(string.Empty, entry.SourceRef); - Assert.Equal(string.Empty, entry.Locator); - Assert.Equal("ranked", entry.Via); - } + Assert.Equal("plain-01", entry.CardId); + Assert.Null(entry.Authority); + Assert.Equal(string.Empty, entry.SourceRef); + Assert.Equal(string.Empty, entry.Locator); + Assert.Equal("ranked", entry.Via); + } - [Fact] - public void For_CarriesTheScopeOrigins() - { - KnowledgeScope scope = new() + [Fact] + public void For_CarriesTheScopeOrigins() { - Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "*" }, - Origins = new Dictionary(StringComparer.Ordinal) + KnowledgeScope scope = new() { - ["brand"] = KnowledgeFacetOrigin.Wildcard, - }, - }; + Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "*" }, + Origins = new Dictionary(StringComparer.Ordinal) + { + ["brand"] = KnowledgeFacetOrigin.Wildcard, + }, + }; - var record = KnowledgeAuditRecord.For( - "agent", KnowledgeMode.Tool, "q", scope, [], 1.0, null); + KnowledgeAuditRecord record = KnowledgeAuditRecord.For( + "agent", KnowledgeMode.Tool, "q", scope, [], 1.0, null); - Assert.Equal(KnowledgeFacetOrigin.Wildcard, record.ScopeOrigins["brand"]); - } + Assert.Equal(KnowledgeFacetOrigin.Wildcard, record.ScopeOrigins["brand"]); + } - [Fact] - public void ForLog_WritesEachFacetWithItsOriginAsText() - { - // The log line prints the view with the record's own ToString, and a dictionary prints as - // its type name there. The one thing an operator opens the line to see, which facet - // narrowed the search, has to be in the text. - KnowledgeScope scope = new() + [Fact] + public void ForLog_WritesEachFacetWithItsOriginAsText() { - Facets = new Dictionary(StringComparer.Ordinal) + // The log line prints the view with the record's own ToString, and a dictionary prints as + // its type name there. The one thing an operator opens the line to see, which facet + // narrowed the search, has to be in the text. + KnowledgeScope scope = new() { - ["model"] = "f85-2019", - ["code"] = "*", - }, - Origins = new Dictionary(StringComparer.Ordinal) - { - ["model"] = KnowledgeFacetOrigin.Tool, - ["code"] = KnowledgeFacetOrigin.Wildcard, - }, - }; - - var view = KnowledgeAuditRecord.For("agent", KnowledgeMode.Tool, "q", scope, [], 1.0, null) - .ForLog(); - - Assert.Equal("code=* (Wildcard), model=f85-2019 (Tool)", view.Scope); - } - - [Fact] - public void ForLog_FacetWithNoRecordedOrigin_WritesTheValueAlone() - { - var view = KnowledgeAuditRecord.For("agent", KnowledgeMode.Tool, "q", Scope(), [], 1.0, null) - .ForLog(); + Facets = new Dictionary(StringComparer.Ordinal) + { + ["model"] = "f85-2019", + ["code"] = "*", + }, + Origins = new Dictionary(StringComparer.Ordinal) + { + ["model"] = KnowledgeFacetOrigin.Tool, + ["code"] = KnowledgeFacetOrigin.Wildcard, + }, + }; + + KnowledgeAuditRecord.LogView view = KnowledgeAuditRecord.For("agent", KnowledgeMode.Tool, "q", scope, [], 1.0, null) + .ForLog(); + + Assert.Equal("code=* (Wildcard), model=f85-2019 (Tool)", view.Scope); + } + + [Fact] + public void ForLog_FacetWithNoRecordedOrigin_WritesTheValueAlone() + { + KnowledgeAuditRecord.LogView view = KnowledgeAuditRecord.For("agent", KnowledgeMode.Tool, "q", Scope(), [], 1.0, null) + .ForLog(); - Assert.Equal("model=ct900", view.Scope); - } + Assert.Equal("model=ct900", view.Scope); + } - [Fact] - public void ForLog_NoScopeWasOpen_WritesAnEmptyString() - { - var view = KnowledgeAuditRecord.For("agent", KnowledgeMode.Tool, "q", scope: null, [], 1.0, null) - .ForLog(); + [Fact] + public void ForLog_NoScopeWasOpen_WritesAnEmptyString() + { + KnowledgeAuditRecord.LogView view = KnowledgeAuditRecord.For("agent", KnowledgeMode.Tool, "q", scope: null, [], 1.0, null) + .ForLog(); - Assert.Equal(string.Empty, view.Scope); - } + Assert.Equal(string.Empty, view.Scope); + } - private static KnowledgeScope Scope() - => new() { Facets = new Dictionary { ["model"] = "ct900" } }; + private static KnowledgeScope Scope() + { + return new() { Facets = new Dictionary { ["model"] = "ct900" } }; + } - private static KnowledgeCard Ranked(string id, double score) - => new() + private static KnowledgeCard Ranked(string id, double score) { - CardId = id, - Text = "card " + id, - Authority = 3, - SourceRef = "ct900-om", - SourceLocator = "p.27", - Score = score, - ViaLink = false, - }; - - private static KnowledgeCard Linked(string id) - => Ranked(id, 0) with { Score = null, ViaLink = true }; + return new() + { + CardId = id, + Text = "card " + id, + Authority = 3, + SourceRef = "ct900-om", + SourceLocator = "p.27", + Score = score, + ViaLink = false, + }; + } + + private static KnowledgeCard Linked(string id) + { + return Ranked(id, 0) with { Score = null, ViaLink = true }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCardMapperTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCardMapperTests.cs index 20c41a99..53893ff0 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCardMapperTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCardMapperTests.cs @@ -1,144 +1,154 @@ using AgentCore.Application.Knowledge; using AgentCore.Domain.Knowledge; +using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The one place a card becomes what the framework injects. citations is applied here, and -/// nowhere else. -/// -/// -/// The wording of a label is no longer this class's business: it belongs to whichever -/// the document names. What is still tested here is the -/// switch — on or off — and that a blank label is treated as no label. -/// -public sealed class KnowledgeCardMapperTests +namespace AgentCore.Application.Tests.Knowledge { - [Fact] - public void ToResult_CitationsOff_SendsNoSourceName() + /// + /// The one place a card becomes what the framework injects. citations is applied here, and + /// nowhere else. + /// + /// + /// The wording of a label is no longer this class's business: it belongs to whichever + /// the document names. What is still tested here is the + /// switch — on or off — and that a blank label is treated as no label. + /// + public sealed class KnowledgeCardMapperTests { - // The model cannot leak a label it never received. Manifest titles end in - // "(curated notes)" and ticket titles can carry a customer name. - var result = KnowledgeCardMapper.ToResult(Card(), citations: false, Formatter); + [Fact] + public void ToResult_CitationsOff_SendsNoSourceName() + { + // The model cannot leak a label it never received. Manifest titles end in + // "(curated notes)" and ticket titles can carry a customer name. + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(Card(), citations: false, Formatter); - Assert.Null(result.SourceName); - Assert.Null(result.SourceLink); - Assert.Equal("the body", result.Text); - } + Assert.Null(result.SourceName); + Assert.Null(result.SourceLink); + Assert.Equal("the body", result.Text); + } - [Fact] - public void ToResult_CitationsOn_NamesTheSourceButStillNoLink() - { - // source.ref is a manifest id and source.locator is "p.27". Neither is a URL, and a - // synthesised kb:// scheme would invite someone to click it. - var result = KnowledgeCardMapper.ToResult(Card(), citations: true, Formatter); + [Fact] + public void ToResult_CitationsOn_NamesTheSourceButStillNoLink() + { + // source.ref is a manifest id and source.locator is "p.27". Neither is a URL, and a + // synthesised kb:// scheme would invite someone to click it. + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(Card(), citations: true, Formatter); - Assert.Equal("ct900-om, p.27", result.SourceName); - Assert.Null(result.SourceLink); - } + Assert.Equal("ct900-om, p.27", result.SourceName); + Assert.Null(result.SourceLink); + } - [Fact] - public void ToResult_AlwaysCarriesTheWholeCard() - { - // TextSearchResult has no Score field, so the audit record reads it from here. - var card = Card(); + [Fact] + public void ToResult_AlwaysCarriesTheWholeCard() + { + // TextSearchResult has no Score field, so the audit record reads it from here. + KnowledgeCard card = Card(); - Assert.Same(card, KnowledgeCardMapper.ToResult(card, citations: false, Formatter).RawRepresentation); - } + Assert.Same(card, KnowledgeCardMapper.ToResult(card, citations: false, Formatter).RawRepresentation); + } - [Fact] - public void ToResult_CitationsOn_BothRefAndLocator_JoinsWithComma() - { - var card = Card() with { SourceRef = "ct900-om", SourceLocator = "p.27" }; + [Fact] + public void ToResult_CitationsOn_BothRefAndLocator_JoinsWithComma() + { + KnowledgeCard card = Card() with { SourceRef = "ct900-om", SourceLocator = "p.27" }; - var result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); - Assert.Equal("ct900-om, p.27", result.SourceName); - } + Assert.Equal("ct900-om, p.27", result.SourceName); + } - [Fact] - public void ToResult_CitationsOn_OnlyRef_OmitsTheSeparator() - { - var card = Card() with { SourceRef = "ct900-om", SourceLocator = string.Empty }; + [Fact] + public void ToResult_CitationsOn_OnlyRef_OmitsTheSeparator() + { + KnowledgeCard card = Card() with { SourceRef = "ct900-om", SourceLocator = string.Empty }; - var result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); - Assert.Equal("ct900-om", result.SourceName); - } + Assert.Equal("ct900-om", result.SourceName); + } - [Fact] - public void ToResult_CitationsOn_OnlyLocator_OmitsTheSeparator() - { - var card = Card() with { SourceRef = string.Empty, SourceLocator = "p.27" }; + [Fact] + public void ToResult_CitationsOn_OnlyLocator_OmitsTheSeparator() + { + KnowledgeCard card = Card() with { SourceRef = string.Empty, SourceLocator = "p.27" }; - var result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); - Assert.Equal("p.27", result.SourceName); - } + Assert.Equal("p.27", result.SourceName); + } - [Fact] - public void ToResult_CitationsOn_NeitherRefNorLocator_SendsNoSourceName() - { - var card = Card() with { SourceRef = string.Empty, SourceLocator = string.Empty }; + [Fact] + public void ToResult_CitationsOn_NeitherRefNorLocator_SendsNoSourceName() + { + KnowledgeCard card = Card() with { SourceRef = string.Empty, SourceLocator = string.Empty }; - var result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(card, citations: true, Formatter); - Assert.Null(result.SourceName); - } + Assert.Null(result.SourceName); + } - [Fact] - public void ToResult_CitationsOn_AFormatterThatWritesNothing_SendsNoSourceName() - { - // A bare separator in front of the model is worse than no citation, so an empty answer and - // a null answer have to mean the same thing here. - var result = KnowledgeCardMapper.ToResult(Card(), citations: true, new BlankFormatter()); + [Fact] + public void ToResult_CitationsOn_AFormatterThatWritesNothing_SendsNoSourceName() + { + // A bare separator in front of the model is worse than no citation, so an empty answer and + // a null answer have to mean the same thing here. + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(Card(), citations: true, new BlankFormatter()); - Assert.Null(result.SourceName); - } + Assert.Null(result.SourceName); + } - [Fact] - public void ToResult_CitationsOn_AFormatterReadingExtras_ShowsWhatItRead() - { - // The point of the seam: a label built from a field no KnowledgeCard property names. - var card = Card() with + [Fact] + public void ToResult_CitationsOn_AFormatterReadingExtras_ShowsWhatItRead() { - Extras = new Dictionary(StringComparer.Ordinal) { ["revision"] = "rev C" }, - }; + // The point of the seam: a label built from a field no KnowledgeCard property names. + KnowledgeCard card = Card() with + { + Extras = new Dictionary(StringComparer.Ordinal) { ["revision"] = "rev C" }, + }; - var result = KnowledgeCardMapper.ToResult(card, citations: true, new ExtrasFormatter()); + TextSearchProvider.TextSearchResult result = KnowledgeCardMapper.ToResult(card, citations: true, new ExtrasFormatter()); - Assert.Equal("rev C", result.SourceName); - } + Assert.Equal("rev C", result.SourceName); + } - /// The shipped wording, which every test above that does not say otherwise uses. - private static SourceLocatorCitationFormatter Formatter => new(); + /// The shipped wording, which every test above that does not say otherwise uses. + private static SourceLocatorCitationFormatter Formatter => new(); - /// A formatter that answers with whitespace, which must read as no citation. - private sealed class BlankFormatter : IKnowledgeCitationFormatter - { - public string Name => "blank"; + /// A formatter that answers with whitespace, which must read as no citation. + private sealed class BlankFormatter : IKnowledgeCitationFormatter + { + public string Name => "blank"; - public string? Format(KnowledgeCard card) => " "; - } + public string? Format(KnowledgeCard card) + { + return " "; + } + } - /// A formatter that cites a payload field no property on the card names. - private sealed class ExtrasFormatter : IKnowledgeCitationFormatter - { - public string Name => "extras"; + /// A formatter that cites a payload field no property on the card names. + private sealed class ExtrasFormatter : IKnowledgeCitationFormatter + { + public string Name => "extras"; - public string? Format(KnowledgeCard card) => card.Extras["revision"] as string; - } + public string? Format(KnowledgeCard card) + { + return card.Extras["revision"] as string; + } + } - private static KnowledgeCard Card() - => new() + private static KnowledgeCard Card() { - CardId = "ct900-e33-incline-err", - Text = "the body", - Authority = 3, - SourceRef = "ct900-om", - SourceLocator = "p.27", - Score = 0.87, - ViaLink = false, - }; + return new() + { + CardId = "ct900-e33-incline-err", + Text = "the body", + Authority = 3, + SourceRef = "ct900-om", + SourceLocator = "p.27", + Score = 0.87, + ViaLink = false, + }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCitationFormatterFactoryTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCitationFormatterFactoryTests.cs index a46e7ecd..24b2243e 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCitationFormatterFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeCitationFormatterFactoryTests.cs @@ -1,22 +1,23 @@ using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; using AgentCore.Domain.Knowledge; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The seam that decides how a citation is worded. -/// -/// -/// The wording used to be six lines inside KnowledgeCardMapper with no way past them. A -/// deployment whose documents are not manifest rows and page numbers had to accept "ct900-om, p.27" -/// shaped labels or turn citations off entirely. -/// -public sealed class KnowledgeCitationFormatterFactoryTests +namespace AgentCore.Application.Tests.Knowledge { - private const string BaseYaml = - """ + /// + /// The seam that decides how a citation is worded. + /// + /// + /// The wording used to be six lines inside KnowledgeCardMapper with no way past them. A + /// deployment whose documents are not manifest rows and page numbers had to accept "ct900-om, p.27" + /// shaped labels or turn citations off entirely. + /// + public sealed class KnowledgeCitationFormatterFactoryTests + { + private const string BaseYaml = + """ apiVersion: agentcore/v1 providers: conversation: { kind: telnyx-relay } @@ -35,68 +36,77 @@ public sealed class KnowledgeCitationFormatterFactoryTests agent: only """; - [Fact] - public void Resolve_ADocumentThatNamesNone_TakesTheShippedWording() - { - var formatter = KnowledgeCitationFormatterFactory.Resolve(Load(BaseYaml), registered: null); - - Assert.Equal(SourceLocatorCitationFormatter.FormatterName, formatter.Name); - } - - [Fact] - public void Resolve_ADocumentNamingAHostFormatter_TakesIt() - { - var configuration = Load(BaseYaml.Replace( - "fields: { body: body }", - "fields: { body: body }\n citation: acme-handbook", - StringComparison.Ordinal)); - - var formatter = KnowledgeCitationFormatterFactory.Resolve(configuration, [new AcmeFormatter()]); - - Assert.IsType(formatter); - } - - [Fact] - public void Resolve_AHostFormatterUnderTheShippedName_ReplacesTheShippedOne() - { - // How a deployment changes the wording for every agent without touching the document. - var formatter = KnowledgeCitationFormatterFactory.Resolve( - Load(BaseYaml), [new ShadowingFormatter()]); - - Assert.IsType(formatter); - } - - [Fact] - public void Resolve_ANameNobodyAnswersTo_FailsAndPointsAtTheField() - { - var configuration = Load(BaseYaml.Replace( - "fields: { body: body }", - "fields: { body: body }\n citation: no-such-wording", - StringComparison.Ordinal)); - - var failure = Assert.Throws( - () => KnowledgeCitationFormatterFactory.Resolve(configuration, registered: null)); - - Assert.Equal("/providers/knowledge/citation", failure.Pointer); - Assert.Contains("no-such-wording", failure.Message, StringComparison.Ordinal); - Assert.Contains("UseKnowledgeCitationFormatters", failure.Message, StringComparison.Ordinal); - } - - private static AgentCore.Application.Configuration.Schema.AgentCoreConfiguration Load(string yaml) - => ConfigurationLoader.LoadYaml(yaml); - - private sealed class AcmeFormatter : IKnowledgeCitationFormatter - { - public string Name => "acme-handbook"; - - public string? Format(KnowledgeCard card) => "handbook"; - } - - /// A host formatter answering to the shipped name. - private sealed class ShadowingFormatter : IKnowledgeCitationFormatter - { - public string Name => SourceLocatorCitationFormatter.FormatterName; - - public string? Format(KnowledgeCard card) => "shadowed"; + [Fact] + public void Resolve_ADocumentThatNamesNone_TakesTheShippedWording() + { + IKnowledgeCitationFormatter formatter = KnowledgeCitationFormatterFactory.Resolve(Load(BaseYaml), registered: null); + + Assert.Equal(SourceLocatorCitationFormatter.FormatterName, formatter.Name); + } + + [Fact] + public void Resolve_ADocumentNamingAHostFormatter_TakesIt() + { + AgentCoreConfiguration configuration = Load(BaseYaml.Replace( + "fields: { body: body }", + "fields: { body: body }\n citation: acme-handbook", + StringComparison.Ordinal)); + + IKnowledgeCitationFormatter formatter = KnowledgeCitationFormatterFactory.Resolve(configuration, [new AcmeFormatter()]); + + _ = Assert.IsType(formatter); + } + + [Fact] + public void Resolve_AHostFormatterUnderTheShippedName_ReplacesTheShippedOne() + { + // How a deployment changes the wording for every agent without touching the document. + IKnowledgeCitationFormatter formatter = KnowledgeCitationFormatterFactory.Resolve( + Load(BaseYaml), [new ShadowingFormatter()]); + + _ = Assert.IsType(formatter); + } + + [Fact] + public void Resolve_ANameNobodyAnswersTo_FailsAndPointsAtTheField() + { + AgentCoreConfiguration configuration = Load(BaseYaml.Replace( + "fields: { body: body }", + "fields: { body: body }\n citation: no-such-wording", + StringComparison.Ordinal)); + + ConfigurationLoadException failure = Assert.Throws( + () => KnowledgeCitationFormatterFactory.Resolve(configuration, registered: null)); + + Assert.Equal("/providers/knowledge/citation", failure.Pointer); + Assert.Contains("no-such-wording", failure.Message, StringComparison.Ordinal); + Assert.Contains("UseKnowledgeCitationFormatters", failure.Message, StringComparison.Ordinal); + } + + private static AgentCoreConfiguration Load(string yaml) + { + return ConfigurationLoader.LoadYaml(yaml); + } + + private sealed class AcmeFormatter : IKnowledgeCitationFormatter + { + public string Name => "acme-handbook"; + + public string? Format(KnowledgeCard card) + { + return "handbook"; + } + } + + /// A host formatter answering to the shipped name. + private sealed class ShadowingFormatter : IKnowledgeCitationFormatter + { + public string Name => SourceLocatorCitationFormatter.FormatterName; + + public string? Format(KnowledgeCard card) + { + return "shadowed"; + } + } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs index 232e8aa7..67592bfd 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs @@ -1,6 +1,5 @@ using AgentCore.Application.Configuration.Parsing; using System.Diagnostics; -using System.Reflection; using System.Text.Json; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Schema; @@ -8,7 +7,6 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Turn; -using AgentCore.Application.Tests.Runtime.Turn; using AgentCore.Domain.Knowledge; using AgentCore.TestSupport; using Microsoft.Agents.AI; @@ -16,1195 +14,1253 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// §8: the probe. Channel 2 of the ambiguity design — inside the knowledge search itself, dropping -/// one wildcard-filled facet, re-searching, and naming the values it finds. -/// -/// -/// Every test drives the search tool KnowledgeProviderFactory offers, the same way -/// KnowledgeProviderFactoryTests does, rather than through ConversationSession: the probe reads -/// only the turn (, the knowledge scope, the history flag) and the -/// resolved knowledge: block, so filing exactly those by hand proves the same mechanism a -/// real conversation would exercise, at a fraction of the setup. The genuinely two-turn and -/// delegation-shaped cases live in ConversationSessionProbeTests. -/// -public sealed class KnowledgeProbeTests +namespace AgentCore.Application.Tests.Knowledge { - private const string Description = "The model, as printed on the machine."; + /// + /// §8: the probe. Channel 2 of the ambiguity design — inside the knowledge search itself, dropping + /// one wildcard-filled facet, re-searching, and naming the values it finds. + /// + /// + /// Every test drives the search tool KnowledgeProviderFactory offers, the same way + /// KnowledgeProviderFactoryTests does, rather than through ConversationSession: the probe reads + /// only the turn (, the knowledge scope, the history flag) and the + /// resolved knowledge: block, so filing exactly those by hand proves the same mechanism a + /// real conversation would exercise, at a fraction of the setup. The genuinely two-turn and + /// delegation-shaped cases live in ConversationSessionProbeTests. + /// + public sealed class KnowledgeProbeTests + { + private const string Description = "The model, as printed on the machine."; - // §8 steps 1-2: when the probe does not run at all. + // §8 steps 1-2: when the probe does not run at all. - [Fact] - public async Task Step1_MainSearchReturnedCards_TheProbeNeverRuns() - { - var port = new ProbeFakePort((_, _) => Task.FromResult>([Card("a")])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + [Fact] + public async Task Step1_MainSearchReturnedCards_TheProbeNeverRuns() + { + ProbeFakePort port = new((_, _) => Task.FromResult>([Card("a")])); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - Assert.Contains(results, r => r.Text == "card a"); - Assert.Equal(1, port.Calls); - } + Assert.Contains(results, r => r.Text == "card a"); + Assert.Equal(1, port.Calls); + } - [Fact] - public async Task Step2_UnscopedAgentsEmptySearch_ReturnsAnEmptyList() - { - // Acceptance: "an unscoped agent's empty search returns an empty list." The probe and the - // "holds nothing" notice are for a scoped agent only (K19). - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - var turn = TurnOf(null, new Clarifications()); + [Fact] + public async Task Step2_UnscopedAgentsEmptySearch_ReturnsAnEmptyList() + { + // Acceptance: "an unscoped agent's empty search returns an empty list." The probe and the + // "holds nothing" notice are for a scoped agent only (K19). + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + TurnInvocation turn = TurnOf(null, new Clarifications()); - var results = await InvokeSearchAsync( - Provider(port, Resolved(["applies_to"], scoped: false)), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync( + Provider(port, Resolved(["applies_to"], scoped: false)), "e33", turn); - Assert.Empty(results); - Assert.Equal(1, port.Calls); - } + Assert.Empty(results); + Assert.Equal(1, port.Calls); + } - [Fact] - public async Task NoAmbiguityConfigured_StaysByteIdenticalToTheWildcardPlan() - { - // K19: with no ambiguity: (and so no wildcard, no template) configured, behaviour is - // byte-identical to the wildcard plan's own "holds nothing" notice — no second search. - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + [Fact] + public async Task NoAmbiguityConfigured_StaysByteIdenticalToTheWildcardPlan() + { + // K19: with no ambiguity: (and so no wildcard, no template) configured, behaviour is + // byte-identical to the wildcard plan's own "holds nothing" notice — no second search. + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var plain = new ResolvedKnowledge(KnowledgeMode.Tool, 5, Citations: false, Scoped: true); - var results = await InvokeSearchAsync(Provider(port, plain), "e33", turn); + ResolvedKnowledge plain = new(KnowledgeMode.Tool, 5, Citations: false, Scoped: true); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, plain), "e33", turn); - Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); - Assert.Equal(1, port.Calls); - } + Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); + Assert.Equal(1, port.Calls); + } - // §8 step 3: which facets are droppable. + // §8 step 3: which facets are droppable. - [Fact] - public async Task Step3_SingleFacetScope_IsUndroppable() - { - // K33: dropping the scope's only facet would open it empty, which a scoped store refuses. - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - var turn = TurnOf(FullScope("applies_to"), new Clarifications()); + [Fact] + public async Task Step3_SingleFacetScope_IsUndroppable() + { + // K33: dropping the scope's only facet would open it empty, which a scoped store refuses. + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + TurnInvocation turn = TurnOf(FullScope("applies_to"), new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); - // Only the main search ran. The probe never opened a second, narrowed scope. - Assert.Equal(1, port.Calls); - } + Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); + // Only the main search ran. The probe never opened a second, narrowed scope. + Assert.Equal(1, port.Calls); + } - [Fact] - public async Task Step3_MaxAsksZero_DropsNoFacet_AndEmitsW11sNotice() - { - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - var turn = TurnOf(FullScope("brand", "applies_to"), new Clarifications()); + [Fact] + public async Task Step3_MaxAsksZero_DropsNoFacet_AndEmitsW11sNotice() + { + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + TurnInvocation turn = TurnOf(FullScope("brand", "applies_to"), new Clarifications()); - var knowledge = Resolved(["brand", "applies_to"], ambiguity: new KnowledgeAmbiguityConfiguration { MaxAsks = 0 }); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + ResolvedKnowledge knowledge = Resolved(["brand", "applies_to"], ambiguity: new KnowledgeAmbiguityConfiguration { MaxAsks = 0 }); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - Assert.Single(results); - Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); - Assert.Equal(1, port.Calls); - } + _ = Assert.Single(results); + Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); + Assert.Equal(1, port.Calls); + } - [Fact] - public async Task Step3_FacetAtItsAskCap_IsSkipped_AndTheNextDroppableFacetIsTried() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task Step3_FacetAtItsAskCap_IsSkipped_AndTheNextDroppableFacetIsTried() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var clarificationsObject = new Clarifications(); - clarificationsObject.Update("brand", s => s.ProbeAsks = 2); - var turn = TurnOf(FullScope("brand", "applies_to"), clarificationsObject); + Clarifications clarificationsObject = new(); + clarificationsObject.Update("brand", s => s.ProbeAsks = 2); + TurnInvocation turn = TurnOf(FullScope("brand", "applies_to"), clarificationsObject); - var knowledge = Resolved(["brand", "applies_to"]); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + ResolvedKnowledge knowledge = Resolved(["brand", "applies_to"]); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - Assert.Contains(results, r => r.Text.Contains("ct900", StringComparison.Ordinal)); - // brand was skipped, not touched: it stays exactly where the test seeded it. - Assert.Equal(2, clarificationsObject.Read("brand").ProbeAsks); - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - } + Assert.Contains(results, r => r.Text.Contains("ct900", StringComparison.Ordinal)); + // brand was skipped, not touched: it stays exactly where the test seeded it. + Assert.Equal(2, clarificationsObject.Read("brand").ProbeAsks); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } - [Fact] - public async Task Step4_DropsTheFirstDroppableFacet_InFromStateDeclarationOrder() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task Step4_DropsTheFirstDroppableFacet_InFromStateDeclarationOrder() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var turn = TurnOf(FullScope("applies_to", "brand"), new Clarifications()); + TurnInvocation turn = TurnOf(FullScope("applies_to", "brand"), new Clarifications()); - // fromState declares applies_to before brand, so applies_to is tried first even though both - // are equally droppable. - var knowledge = Resolved(["applies_to", "brand"]); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + // fromState declares applies_to before brand, so applies_to is tried first even though both + // are equally droppable. + ResolvedKnowledge knowledge = Resolved(["applies_to", "brand"]); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - Assert.Contains(results, r => r.Text.Contains("ct900", StringComparison.Ordinal)); - } + Assert.Contains(results, r => r.Text.Contains("ct900", StringComparison.Ordinal)); + } - // §8 steps 5-6: reading candidates and choosing the message. + // §8 steps 5-6: reading candidates and choosing the message. - [Fact] - public async Task Steps5And6_FindsCandidates_RecordsWhatItNamedAndEmitsTheNote() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [CardWithFacet("a", "applies_to", "ct900"), CardWithFacet("b", "applies_to", "ct900ent")])); + [Fact] + public async Task Steps5And6_FindsCandidates_RecordsWhatItNamedAndEmitsTheNote() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [CardWithFacet("a", "applies_to", "ct900"), CardWithFacet("b", "applies_to", "ct900ent")])); - var clarificationsObject = new Clarifications(); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject, carriesHistory: true); + Clarifications clarificationsObject = new(); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject, carriesHistory: true); - var knowledge = Resolved(["applies_to"], slotDescriptions: Descriptions(("applies_to", Description))); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + ResolvedKnowledge knowledge = Resolved(["applies_to"], slotDescriptions: Descriptions(("applies_to", Description))); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - Assert.Equal( - ClarificationText.Note(Description, ["ct900", "ct900ent"], KnowledgeAmbiguityConfiguration.DefaultMaxCandidates), - Assert.Single(results).Text); + Assert.Equal( + ClarificationText.Note(Description, ["ct900", "ct900ent"], KnowledgeAmbiguityConfiguration.DefaultMaxCandidates), + Assert.Single(results).Text); - var snapshot = clarificationsObject.Read("applies_to"); - Assert.Equal(Clarifications.LastNamedKind.Set, snapshot.LastNamed.Kind); - Assert.Equal( - new HashSet(["ct900", "ct900ent"], StringComparer.Ordinal), snapshot.LastNamed.Values); - } + Clarifications.SlotSnapshot snapshot = clarificationsObject.Read("applies_to"); + Assert.Equal(Clarifications.LastNamedKind.Set, snapshot.LastNamed.Kind); + Assert.Equal( + new HashSet(["ct900", "ct900ent"], StringComparer.Ordinal), snapshot.LastNamed.Values); + } - [Fact] - public async Task Step5_ReadsAListShapedFacetValue_NotJustAString() - { - // K24's own example: a card tagged applies_to: ["ct900", "ct900ent"]. A cast straight to - // string would return null for every card on a multi-model collection. - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [CardWithFacetList("a", "applies_to", ["ct900", "ct900ent"])])); + [Fact] + public async Task Step5_ReadsAListShapedFacetValue_NotJustAString() + { + // K24's own example: a card tagged applies_to: ["ct900", "ct900ent"]. A cast straight to + // string would return null for every card on a multi-model collection. + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [CardWithFacetList("a", "applies_to", ["ct900", "ct900ent"])])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - var text = Assert.Single(results).Text; - Assert.Contains("ct900", text, StringComparison.Ordinal); - Assert.Contains("ct900ent", text, StringComparison.Ordinal); - } + string text = Assert.Single(results).Text; + Assert.Contains("ct900", text, StringComparison.Ordinal); + Assert.Contains("ct900ent", text, StringComparison.Ordinal); + } - [Fact] - public async Task Step5_WalksANestedTemplatePath() - { - const string template = "facets.{key}"; - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [CardWithFacet("a", "applies_to", "ct900", template)])); + [Fact] + public async Task Step5_WalksANestedTemplatePath() + { + const string template = "facets.{key}"; + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [CardWithFacet("a", "applies_to", "ct900", template)])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync( - Provider(port, Resolved(["applies_to"], template: template)), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync( + Provider(port, Resolved(["applies_to"], template: template)), "e33", turn); - Assert.Contains("ct900", Assert.Single(results).Text, StringComparison.Ordinal); - } + Assert.Contains("ct900", Assert.Single(results).Text, StringComparison.Ordinal); + } - [Fact] - public async Task K6_TheWildcardValueItselfIsDiscardedFromTheCandidates() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [CardWithFacet("a", "applies_to", "*"), CardWithFacet("b", "applies_to", "ct900")])); + [Fact] + public async Task K6_TheWildcardValueItselfIsDiscardedFromTheCandidates() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [CardWithFacet("a", "applies_to", "*"), CardWithFacet("b", "applies_to", "ct900")])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - var text = Assert.Single(results).Text; - Assert.Contains("ct900", text, StringComparison.Ordinal); - Assert.DoesNotContain("could be: *", text, StringComparison.Ordinal); - } + string text = Assert.Single(results).Text; + Assert.Contains("ct900", text, StringComparison.Ordinal); + Assert.DoesNotContain("could be: *", text, StringComparison.Ordinal); + } - [Fact] - public async Task K24_OneCardIsNeverASpread() - { - // Acceptance: "one card is never a spread." One value produces a confirm question, not - // "fewer than two -> holds nothing". - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task K24_OneCardIsNeverASpread() + { + // Acceptance: "one card is never a spread." One value produces a confirm question, not + // "fewer than two -> holds nothing". + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync( - Provider(port, Resolved(["applies_to"], slotDescriptions: Descriptions(("applies_to", Description)))), - "e33", turn); + IReadOnlyList results = await InvokeSearchAsync( + Provider(port, Resolved(["applies_to"], slotDescriptions: Descriptions(("applies_to", Description)))), + "e33", turn); - Assert.Equal( - ClarificationText.Note(Description, ["ct900"], KnowledgeAmbiguityConfiguration.DefaultMaxCandidates), - Assert.Single(results).Text); - } + Assert.Equal( + ClarificationText.Note(Description, ["ct900"], KnowledgeAmbiguityConfiguration.DefaultMaxCandidates), + Assert.Single(results).Text); + } - [Fact] - public async Task MoreThanMaxCandidates_NamesNone() - { - // Acceptance: "more than maxCandidates names none." The probe still speaks — this is not the - // "holds nothing" notice — but the rendered text omits every value. - var many = Enumerable.Range(0, 7).Select(i => $"model{i}").ToArray(); - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [.. many.Select((value, i) => CardWithFacet($"c{i}", "applies_to", value))])); - - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - - var knowledge = Resolved( - ["applies_to"], ambiguity: new KnowledgeAmbiguityConfiguration { MaxCandidates = 6 }); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - - var text = Assert.Single(results).Text; - Assert.DoesNotContain("holds nothing", text, StringComparison.Ordinal); - foreach (var value in many) + [Fact] + public async Task MoreThanMaxCandidates_NamesNone() { - Assert.DoesNotContain(value, text, StringComparison.Ordinal); + // Acceptance: "more than maxCandidates names none." The probe still speaks — this is not the + // "holds nothing" notice — but the rendered text omits every value. + string[] many = [.. Enumerable.Range(0, 7).Select(i => $"model{i}")]; + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [.. many.Select((value, i) => CardWithFacet($"c{i}", "applies_to", value))])); + + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + + ResolvedKnowledge knowledge = Resolved( + ["applies_to"], ambiguity: new KnowledgeAmbiguityConfiguration { MaxCandidates = 6 }); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + + string text = Assert.Single(results).Text; + Assert.DoesNotContain("holds nothing", text, StringComparison.Ordinal); + foreach (string? value in many) + { + Assert.DoesNotContain(value, text, StringComparison.Ordinal); + } } - } - - [Fact] - public async Task K34_ARepeatedIdenticalCandidateSet_EmitsHoldsNothing() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [CardWithFacet("a", "applies_to", "ct900"), CardWithFacet("b", "applies_to", "ct900ent")])); - var clarificationsObject = new Clarifications(); - clarificationsObject.Update( - "applies_to", - s => s.LastNamed = Clarifications.LastNamed.Of(new HashSet(["ct900", "ct900ent"], StringComparer.Ordinal))); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + [Fact] + public async Task K34_ARepeatedIdenticalCandidateSet_EmitsHoldsNothing() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [CardWithFacet("a", "applies_to", "ct900"), CardWithFacet("b", "applies_to", "ct900ent")])); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + Clarifications clarificationsObject = new(); + clarificationsObject.Update( + "applies_to", + s => s.LastNamed = Clarifications.LastNamed.Of(new HashSet(["ct900", "ct900ent"], StringComparer.Ordinal))); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - // probeAsks still advances -- the slot was tried, it just had nothing new to say. - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - } + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); - [Fact] - public async Task ZeroCandidatesFound_EmitsHoldsNothing() - { - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); + // probeAsks still advances -- the slot was tried, it just had nothing new to say. + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + [Fact] + public async Task ZeroCandidatesFound_EmitsHoldsNothing() + { + ProbeFakePort port = new((_, _) => Task.FromResult>([])); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); - } + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - // K39: a graph document's probe still speaks, but must not record what it named. + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + } - [Fact] - public async Task K39_AGraphDocumentsProbe_EmitsItsNote_AndRecordsNoLastNamed() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + // K39: a graph document's probe still speaks, but must not record what it named. - var clarificationsObject = new Clarifications(); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject, carriesHistory: false); + [Fact] + public async Task K39_AGraphDocumentsProbe_EmitsItsNote_AndRecordsNoLastNamed() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + Clarifications clarificationsObject = new(); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject, carriesHistory: false); - Assert.Contains("ct900", Assert.Single(results).Text, StringComparison.Ordinal); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - // The record of what was named is withheld: K21's tie-break rests on the caller having heard - // the list, which AgentCore cannot know on a graph row. - Assert.Equal(Clarifications.LastNamedKind.None, clarificationsObject.Read("applies_to").LastNamed.Kind); - } + Assert.Contains("ct900", Assert.Single(results).Text, StringComparison.Ordinal); - // K42: no holder, no probe -- but the notice is still owed to a scoped run. + // The record of what was named is withheld: K21's tie-break rests on the caller having heard + // the list, which AgentCore cannot know on a graph row. + Assert.Equal(Clarifications.LastNamedKind.None, clarificationsObject.Read("applies_to").LastNamed.Kind); + } - [Fact] - public async Task K42_NoHolderOnTheTurn_TheProbeDoesNotSearch_ButStillEmitsTheNotice() - { - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - var turn = TurnOf(FullScope("applies_to", "other"), null); + // K42: no holder, no probe -- but the notice is still owed to a scoped run. - // No Clarifications on the turn at all -- the K42 strip inside a nested tool call. - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + [Fact] + public async Task K42_NoHolderOnTheTurn_TheProbeDoesNotSearch_ButStillEmitsTheNotice() + { + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), null); - Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); - Assert.Equal(1, port.Calls); - } + // No Clarifications on the turn at all -- the K42 strip inside a nested tool call. + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - [Fact] - public async Task K42_ASubAgentThatSearchesFirst_WritesNoLastNamed_AndTheCallersOwnSearchStillCounts() - { - // Acceptance: "a sub-agent that searches first writes no lastNamed, and the caller's own - // search still counts." Simulates exactly what AuditingFunctionInvokingChatClient. - // InvokeFunctionAsync does for a NESTED tool call: it strips Clarifications from the turn, - // leaving the outer call id in place. - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + Assert.Equal(1, port.Calls); + } - var clarificationsObject = new Clarifications(); - var knowledge = Resolved(["applies_to"]); - var provider = Provider(port, knowledge); + [Fact] + public async Task K42_ASubAgentThatSearchesFirst_WritesNoLastNamed_AndTheCallersOwnSearchStillCounts() + { + // Acceptance: "a sub-agent that searches first writes no lastNamed, and the caller's own + // search still counts." Simulates exactly what AuditingFunctionInvokingChatClient. + // InvokeFunctionAsync does for a NESTED tool call: it strips Clarifications from the turn, + // leaving the outer call id in place. + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var scope = FullScope("applies_to", "other"); - var nested = await InvokeSearchAsync(provider, "the sub-agent's own question", TurnOf(scope, null)); + Clarifications clarificationsObject = new(); + ResolvedKnowledge knowledge = Resolved(["applies_to"]); + AIContextProvider provider = Provider(port, knowledge); - Assert.Contains("holds nothing", Assert.Single(nested).Text, StringComparison.Ordinal); - Assert.Equal(0, clarificationsObject.Read("applies_to").ProbeAsks); - // Only the sub-agent's own main search ran; its own probe search never reached the port. - Assert.Equal(1, port.Calls); + KnowledgeScope scope = FullScope("applies_to", "other"); + IReadOnlyList nested = await InvokeSearchAsync(provider, "the sub-agent's own question", TurnOf(scope, null)); - var callers = await InvokeSearchAsync(provider, "the caller's own question", TurnOf(scope, clarificationsObject)); + Assert.Contains("holds nothing", Assert.Single(nested).Text, StringComparison.Ordinal); + Assert.Equal(0, clarificationsObject.Read("applies_to").ProbeAsks); + // Only the sub-agent's own main search ran; its own probe search never reached the port. + Assert.Equal(1, port.Calls); - Assert.Contains("ct900", Assert.Single(callers).Text, StringComparison.Ordinal); - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - } + IReadOnlyList callers = await InvokeSearchAsync(provider, "the caller's own question", TurnOf(scope, clarificationsObject)); - // K25: every notice this design emits carries the reserved source name, and none is citable. + Assert.Contains("ct900", Assert.Single(callers).Text, StringComparison.Ordinal); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } - [Fact] - public async Task EveryOutcome_CarriesTheReservedSourceName() - { - var holdsNothing = new ProbeFakePort((_, _) => Task.FromResult>([])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync(Provider(holdsNothing, Resolved(["applies_to"])), "e33", turn); - Assert.All(results, r => Assert.Equal(KnowledgeNotices.SourceName, r.SourceName)); - - var named = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var secondTurn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var second = await InvokeSearchAsync(Provider(named, Resolved(["applies_to"])), "e33", secondTurn); - Assert.All(second, r => Assert.Equal(KnowledgeNotices.SourceName, r.SourceName)); - } + // K25: every notice this design emits carries the reserved source name, and none is citable. - [Fact] - public async Task K23_AProbeSpread_PublishesNoSources() - { - // Acceptance: "a probe spread publishes no sources." The probe runs between Kept and Cite, so - // nothing it discards -- and nothing it names -- is ever published as a citable source. - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") - ? [] - : [CardWithFacet("a", "applies_to", "ct900"), CardWithFacet("b", "applies_to", "ct900ent")])); - - var provider = Provider(port, Resolved(["applies_to"], citations: true)); - TurnSources sources = new(); - - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications(), sources: sources); - using (sources.BeginOuterCall("conversation-1")) + [Fact] + public async Task EveryOutcome_CarriesTheReservedSourceName() { - await InvokeSearchAsync(provider, "e33", turn); + ProbeFakePort holdsNothing = new((_, _) => Task.FromResult>([])); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + IReadOnlyList results = await InvokeSearchAsync(Provider(holdsNothing, Resolved(["applies_to"])), "e33", turn); + Assert.All(results, r => Assert.Equal(KnowledgeNotices.SourceName, r.SourceName)); + + ProbeFakePort named = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + TurnInvocation secondTurn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + IReadOnlyList second = await InvokeSearchAsync(Provider(named, Resolved(["applies_to"])), "e33", secondTurn); + Assert.All(second, r => Assert.Equal(KnowledgeNotices.SourceName, r.SourceName)); } - Assert.Empty(sources.TakeFor("conversation-1")); - } + [Fact] + public async Task K23_AProbeSpread_PublishesNoSources() + { + // Acceptance: "a probe spread publishes no sources." The probe runs between Kept and Cite, so + // nothing it discards -- and nothing it names -- is ever published as a citable source. + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") + ? [] + : [CardWithFacet("a", "applies_to", "ct900"), CardWithFacet("b", "applies_to", "ct900ent")])); + + AIContextProvider provider = Provider(port, Resolved(["applies_to"], citations: true)); + TurnSources sources = new(); + + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications(), sources: sources); + using (sources.BeginOuterCall("conversation-1")) + { + _ = await InvokeSearchAsync(provider, "e33", turn); + } - // K32: the probe's own try, its own budget, its own log events. + Assert.Empty(sources.TakeFor("conversation-1")); + } - [Fact] - public async Task Probe_SecondSearchThrows_EmitsHoldsNothing_AndLogsItsOwnFailureEvent() - { - InvalidOperationException boom = new("qdrant is down, second leg"); - var port = new ProbeFakePort((facets, _) => - facets.ContainsKey("applies_to") - ? Task.FromResult>([]) - : throw boom); - - RecordingLoggerFactory loggers = new(); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - - var provider = KnowledgeProviderFactory.Create( - port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); - var results = await InvokeSearchAsync(provider, "e33", turn); - - Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); - Assert.DoesNotContain("unreachable", Assert.Single(results).Text, StringComparison.OrdinalIgnoreCase); - - var line = Assert.Single(loggers.Of(17)); - Assert.Equal(LogLevel.Error, line.Level); - Assert.Equal("agent-under-test", line.Field("Agent")); - Assert.Equal("applies_to", line.Field("Facet")); - Assert.Same(boom, line.Exception); - - // The main search's own success is unaffected: nothing about it was ever a failure. - Assert.Empty(loggers.Of(12)); - } + // K32: the probe's own try, its own budget, its own log events. - [Fact] - public async Task Probe_SecondSearchTimesOut_IsTreatedAsAFailure_NeverAsUnreachable() - { - var port = new ProbeFakePort(async (facets, cancellationToken) => + [Fact] + public async Task Probe_SecondSearchThrows_EmitsHoldsNothing_AndLogsItsOwnFailureEvent() + { + InvalidOperationException boom = new("qdrant is down, second leg"); + ProbeFakePort port = new((facets, _) => + facets.ContainsKey("applies_to") + ? Task.FromResult>([]) + : throw boom); + + RecordingLoggerFactory loggers = new(); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + + AIContextProvider provider = KnowledgeProviderFactory.Create( + port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); + IReadOnlyList results = await InvokeSearchAsync(provider, "e33", turn); + + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + Assert.DoesNotContain("unreachable", Assert.Single(results).Text, StringComparison.OrdinalIgnoreCase); + + CapturedLine line = Assert.Single(loggers.Of(17)); + Assert.Equal(LogLevel.Error, line.Level); + Assert.Equal("agent-under-test", line.Field("Agent")); + Assert.Equal("applies_to", line.Field("Facet")); + Assert.Same(boom, line.Exception); + + // The main search's own success is unaffected: nothing about it was ever a failure. + Assert.Empty(loggers.Of(12)); + } + + [Fact] + public async Task Probe_SecondSearchTimesOut_IsTreatedAsAFailure_NeverAsUnreachable() { - if (facets.ContainsKey("applies_to")) + ProbeFakePort port = new(async (facets, cancellationToken) => { - return []; - } + if (facets.ContainsKey("applies_to")) + { + return []; + } - await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); - throw new UnreachableException(); - }); + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + throw new UnreachableException(); + }); - var clarificationsObject = new Clarifications(); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + Clarifications clarificationsObject = new(); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - var knowledge = Resolved( - ["applies_to"], - ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1, ProbeWaitMarginSeconds = 1 }); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + ResolvedKnowledge knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1, ProbeWaitMarginSeconds = 1 }); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); - // §8 step 4's increment ran before the search; a timeout that is not caller cancellation - // never rolls it back the way K43's own cancellation row does. - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - } + // §8 step 4's increment ran before the search; a timeout that is not caller cancellation + // never rolls it back the way K43's own cancellation row does. + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } - // K43: at most once per turn -- the latch, the replay, and cancellation. + // K43: at most once per turn -- the latch, the replay, and cancellation. - [Fact] - public async Task K43_ThreeSearchConversationsInOneTurn_RunOneProbe_AndIncrementOnce() - { - var port = new ProbeFakePort((facets, _) => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task K43_ThreeSearchConversationsInOneTurn_RunOneProbe_AndIncrementOnce() + { + ProbeFakePort port = new((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var clarificationsObject = new Clarifications(); - var provider = Provider(port, Resolved(["applies_to"])); + Clarifications clarificationsObject = new(); + AIContextProvider provider = Provider(port, Resolved(["applies_to"])); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - var first = await InvokeSearchAsync(provider, "e33", turn); - var second = await InvokeSearchAsync(provider, "e33 again", turn); - var third = await InvokeSearchAsync(provider, "e33 once more", turn); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + IReadOnlyList first = await InvokeSearchAsync(provider, "e33", turn); + IReadOnlyList second = await InvokeSearchAsync(provider, "e33 again", turn); + IReadOnlyList third = await InvokeSearchAsync(provider, "e33 once more", turn); - Assert.Same(first[0], second[0]); - Assert.Same(first[0], third[0]); + Assert.Same(first[0], second[0]); + Assert.Same(first[0], third[0]); - // Every call's own main search runs (three), and only the winner's search reached the - // narrowed scope (one): four port conversations, one probe. - Assert.Equal(4, port.Calls); - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - } + // Every call's own main search runs (three), and only the winner's search reached the + // narrowed scope (one): four port conversations, one probe. + Assert.Equal(4, port.Calls); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } - [Fact] - public async Task K43_TwoConversations_TheFirstEmittedHoldsNothing_TheSecondReplaysTheSameBytes() - { - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - var provider = Provider(port, Resolved(["applies_to"])); + [Fact] + public async Task K43_TwoConversations_TheFirstEmittedHoldsNothing_TheSecondReplaysTheSameBytes() + { + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + AIContextProvider provider = Provider(port, Resolved(["applies_to"])); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var first = await InvokeSearchAsync(provider, "e33", turn); - var second = await InvokeSearchAsync(provider, "e33 again", turn); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + IReadOnlyList first = await InvokeSearchAsync(provider, "e33", turn); + IReadOnlyList second = await InvokeSearchAsync(provider, "e33 again", turn); - // Each search returns the turn's own probe payload, so the replay proof is on the element - // the two lists share, not on the lists themselves. - Assert.Same(first[0], second[0]); - } + // Each search returns the turn's own probe payload, so the replay proof is on the element + // the two lists share, not on the lists themselves. + Assert.Same(first[0], second[0]); + } - [Fact] - public async Task K43_TwoConversations_TheFirstProbeThrows_TheSecondReplaysHoldsNothing() - { - var thrown = 0; - var port = new ProbeFakePort((facets, _) => + [Fact] + public async Task K43_TwoConversations_TheFirstProbeThrows_TheSecondReplaysHoldsNothing() { - if (facets.ContainsKey("applies_to")) + int thrown = 0; + ProbeFakePort port = new((facets, _) => { - return Task.FromResult>([]); - } - - thrown++; - throw new InvalidOperationException("down"); - }); + if (facets.ContainsKey("applies_to")) + { + return Task.FromResult>([]); + } - var provider = Provider(port, Resolved(["applies_to"])); + thrown++; + throw new InvalidOperationException("down"); + }); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var first = await InvokeSearchAsync(provider, "e33", turn); - var second = await InvokeSearchAsync(provider, "e33 again", turn); + AIContextProvider provider = Provider(port, Resolved(["applies_to"])); - Assert.Equal(1, thrown); - Assert.Same(first[0], second[0]); - Assert.Contains("holds nothing", first[0].Text, StringComparison.Ordinal); - } + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + IReadOnlyList first = await InvokeSearchAsync(provider, "e33", turn); + IReadOnlyList second = await InvokeSearchAsync(provider, "e33 again", turn); - [Fact] - public async Task K43_ACancelledProbe_RollsBackTheIncrement_FailsThePayload_AndKeepsTheLatch() - { - using CancellationTokenSource caller = new(); - TaskCompletionSource probeStarted = new(TaskCreationOptions.RunContinuationsAsynchronously); + Assert.Equal(1, thrown); + Assert.Same(first[0], second[0]); + Assert.Contains("holds nothing", first[0].Text, StringComparison.Ordinal); + } - var port = new ProbeFakePort(async (facets, cancellationToken) => + [Fact] + public async Task K43_ACancelledProbe_RollsBackTheIncrement_FailsThePayload_AndKeepsTheLatch() { - if (facets.ContainsKey("applies_to")) + using CancellationTokenSource caller = new(); + TaskCompletionSource probeStarted = new(TaskCreationOptions.RunContinuationsAsynchronously); + + ProbeFakePort port = new(async (facets, cancellationToken) => { - return []; - } + if (facets.ContainsKey("applies_to")) + { + return []; + } - probeStarted.TrySetResult(); - await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); - throw new UnreachableException(); - }); + _ = probeStarted.TrySetResult(); + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + throw new UnreachableException(); + }); - var clarificationsObject = new Clarifications(); - var provider = Provider(port, Resolved(["applies_to"])); + Clarifications clarificationsObject = new(); + AIContextProvider provider = Provider(port, Resolved(["applies_to"])); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - var winner = InvokeSearchWithCallerTokenAsync(provider, "e33", turn, caller.Token); + Task> winner = InvokeSearchWithCallerTokenAsync(provider, "e33", turn, caller.Token); - await probeStarted.Task.WaitAsync(TestContext.Current.CancellationToken); - await caller.CancelAsync(); + await probeStarted.Task.WaitAsync(TestContext.Current.CancellationToken); + await caller.CancelAsync(); - await Assert.ThrowsAnyAsync(() => winner); + _ = await Assert.ThrowsAnyAsync(() => winner); - Assert.Equal(0, clarificationsObject.Read("applies_to").ProbeAsks); + Assert.Equal(0, clarificationsObject.Read("applies_to").ProbeAsks); - // The latch stays claimed: a fresh caller this turn does not get to run a second probe search. - Assert.False(clarificationsObject.ClaimProbe().Won); - } + // The latch stays claimed: a fresh caller this turn does not get to run a second probe search. + Assert.False(clarificationsObject.ClaimProbe().Won); + } - [Fact] - public async Task K43_ACancelledProbe_WakesAGenuinelyWaitingLoser_RatherThanLettingItRunOutItsOwnClock() - { - // The row above proves the winner's own rollback and the latch staying claimed, but neither - // of those observes Probe.Fail() actually doing anything: nothing there ever constructs - // a second, genuinely waiting caller. This test does: a real second search call reaches - // Probe.WaitAsync while the winner is still blocked in its own search, and only the - // elapsed time tells correct from broken. - // - // The loser's own token is never cancelled -- deliberately unrelated to the winner's - // caller.Token, unlike a same-turn conversation that would share it. A shared token was tried first - // and measured to make this row untestable: Task.WaitAsync(timeout, token) reacts to a - // cancelled TOKEN exactly as fast as it reacts to the awaited TASK being cancelled, so with - // one shared token the loser wakes just as quickly whether or not Probe.Fail() ever - // runs -- removing the conversation and re-running this same test with a shared token still passed, - // in under 150 ms. An unrelated token closes that hole: the loser's own wait then has exactly - // one way to end early -- the shared payload being failed -- and otherwise runs out its own - // two-second clock (ProbeDeadlineSeconds + ProbeWaitMarginSeconds), which is what the timing - // assertion below tells apart. (Both outcomes return the same "holds nothing" notice: the - // loser's own catch around Probe.WaitAsync tells its caller's own cancellation apart - // from a failed payload or an expired wait, and only the latter two reach here -- so only the - // speed differs, which is why the assertion below is on speed and not on the returned text.) - using CancellationTokenSource caller = new(); - TaskCompletionSource probeStarted = new(TaskCreationOptions.RunContinuationsAsynchronously); - - var port = new ProbeFakePort(async (facets, cancellationToken) => + [Fact] + public async Task K43_ACancelledProbe_WakesAGenuinelyWaitingLoser_RatherThanLettingItRunOutItsOwnClock() { - if (facets.ContainsKey("applies_to")) + // The row above proves the winner's own rollback and the latch staying claimed, but neither + // of those observes Probe.Fail() actually doing anything: nothing there ever constructs + // a second, genuinely waiting caller. This test does: a real second search call reaches + // Probe.WaitAsync while the winner is still blocked in its own search, and only the + // elapsed time tells correct from broken. + // + // The loser's own token is never cancelled -- deliberately unrelated to the winner's + // caller.Token, unlike a same-turn conversation that would share it. A shared token was tried first + // and measured to make this row untestable: Task.WaitAsync(timeout, token) reacts to a + // cancelled TOKEN exactly as fast as it reacts to the awaited TASK being cancelled, so with + // one shared token the loser wakes just as quickly whether or not Probe.Fail() ever + // runs -- removing the conversation and re-running this same test with a shared token still passed, + // in under 150 ms. An unrelated token closes that hole: the loser's own wait then has exactly + // one way to end early -- the shared payload being failed -- and otherwise runs out its own + // two-second clock (ProbeDeadlineSeconds + ProbeWaitMarginSeconds), which is what the timing + // assertion below tells apart. (Both outcomes return the same "holds nothing" notice: the + // loser's own catch around Probe.WaitAsync tells its caller's own cancellation apart + // from a failed payload or an expired wait, and only the latter two reach here -- so only the + // speed differs, which is why the assertion below is on speed and not on the returned text.) + using CancellationTokenSource caller = new(); + TaskCompletionSource probeStarted = new(TaskCreationOptions.RunContinuationsAsynchronously); + + ProbeFakePort port = new(async (facets, cancellationToken) => { - return []; - } + if (facets.ContainsKey("applies_to")) + { + return []; + } - probeStarted.TrySetResult(); - await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); - throw new UnreachableException(); - }); + _ = probeStarted.TrySetResult(); + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + throw new UnreachableException(); + }); - // Short enough that a genuine regression fails this test in about two seconds rather than - // hanging the suite; long enough that "woke immediately" and "ran out the clock" are - // unmistakably different durations. - var knowledge = Resolved( - ["applies_to"], - ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1, ProbeWaitMarginSeconds = 1 }); - var provider = Provider(port, knowledge); + // Short enough that a genuine regression fails this test in about two seconds rather than + // hanging the suite; long enough that "woke immediately" and "ran out the clock" are + // unmistakably different durations. + ResolvedKnowledge knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1, ProbeWaitMarginSeconds = 1 }); + AIContextProvider provider = Provider(port, knowledge); - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var winner = InvokeSearchWithCallerTokenAsync(provider, "e33", turn, caller.Token); + Task> winner = InvokeSearchWithCallerTokenAsync(provider, "e33", turn, caller.Token); - // Only reached after the claim, the increment, and the narrowed scope's own search have - // all already run, so the loser below is guaranteed to lose the race, not win it. - await probeStarted.Task.WaitAsync(TestContext.Current.CancellationToken); + // Only reached after the claim, the increment, and the narrowed scope's own search have + // all already run, so the loser below is guaranteed to lose the race, not win it. + await probeStarted.Task.WaitAsync(TestContext.Current.CancellationToken); - var stopwatch = Stopwatch.StartNew(); - var loser = InvokeSearchAsync(provider, "e33 from a second caller", turn); + Stopwatch stopwatch = Stopwatch.StartNew(); + Task> loser = InvokeSearchAsync(provider, "e33 from a second caller", turn); - await caller.CancelAsync(); + await caller.CancelAsync(); - await Assert.ThrowsAnyAsync(() => winner); + _ = await Assert.ThrowsAnyAsync(() => winner); - var loserResult = await loser; - stopwatch.Stop(); + IReadOnlyList loserResult = await loser; + stopwatch.Stop(); - Assert.Contains("holds nothing", Assert.Single(loserResult).Text, StringComparison.Ordinal); + Assert.Contains("holds nothing", Assert.Single(loserResult).Text, StringComparison.Ordinal); - // The wait's own ceiling is two seconds. A loser that woke well under that woke because - // Probe.Fail() failed the shared payload; one that took close to two seconds ran out - // its own clock instead, which is exactly the defect this row exists to catch. - Assert.True( - stopwatch.Elapsed < TimeSpan.FromSeconds(1), - $"the loser took {stopwatch.Elapsed} to return; that is close enough to its own two-second " - + "wait ceiling that it may have run out its own clock rather than observed the failed payload."); - } + // The wait's own ceiling is two seconds. A loser that woke well under that woke because + // Probe.Fail() failed the shared payload; one that took close to two seconds ran out + // its own clock instead, which is exactly the defect this row exists to catch. + Assert.True( + stopwatch.Elapsed < TimeSpan.FromSeconds(1), + $"the loser took {stopwatch.Elapsed} to return; that is close enough to its own two-second " + + "wait ceiling that it may have run out its own clock rather than observed the failed payload."); + } - [Fact] - public async Task K43_ProbeThatThrowsEveryTurn_StillAdvancesProbeAsks() - { - // Acceptance: "a probe that throws every turn still advances probeAsks." Two turns, - // simulated with the same BeginTurn a real ConversationSession conversations: the latch and the per-turn mark - // reset, the counter does not. - var attempts = 0; - var port = new ProbeFakePort((facets, _) => + [Fact] + public async Task K43_ProbeThatThrowsEveryTurn_StillAdvancesProbeAsks() { - if (facets.ContainsKey("applies_to")) + // Acceptance: "a probe that throws every turn still advances probeAsks." Two turns, + // simulated with the same BeginTurn a real ConversationSession conversations: the latch and the per-turn mark + // reset, the counter does not. + int attempts = 0; + ProbeFakePort port = new((facets, _) => { - return Task.FromResult>([]); - } - - attempts++; - throw new InvalidOperationException("down"); - }); + if (facets.ContainsKey("applies_to")) + { + return Task.FromResult>([]); + } - var clarificationsObject = new Clarifications(); - var provider = Provider(port, Resolved(["applies_to"])); + attempts++; + throw new InvalidOperationException("down"); + }); - await InvokeSearchAsync(provider, "turn one", TurnOf(FullScope("applies_to", "other"), clarificationsObject)); + Clarifications clarificationsObject = new(); + AIContextProvider provider = Provider(port, Resolved(["applies_to"])); - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + _ = await InvokeSearchAsync(provider, "turn one", TurnOf(FullScope("applies_to", "other"), clarificationsObject)); - clarificationsObject.BeginTurn(); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - await InvokeSearchAsync(provider, "turn two", TurnOf(FullScope("applies_to", "other"), clarificationsObject)); + clarificationsObject.BeginTurn(); - Assert.Equal(2, clarificationsObject.Read("applies_to").ProbeAsks); - Assert.Equal(2, attempts); - } + _ = await InvokeSearchAsync(provider, "turn two", TurnOf(FullScope("applies_to", "other"), clarificationsObject)); - [Fact] - public async Task Loser_WaitExpiresBeforeAnyOutcomeIsPublished_EmitsHoldsNothing_NeverUnreachable() - { - // C1's own gap: the probe is claimed directly, exactly as a real winner's ProbeAsync would, - // but its payload is never published -- neither Publish nor Fail. With ProbeDeadlineSeconds - // and ProbeWaitMarginSeconds both 0, the loser's own wait times out almost at once, which is - // the row the fix exists for: - // a TimeoutException reaching SearchAsync's outer catch would blame the main search, which - // never ran a second time and never failed. - var port = new ProbeFakePort((_, _) => Task.FromResult>([])); - - var clarificationsObject = new Clarifications(); - Assert.True(clarificationsObject.ClaimProbe().Won); - - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - - var knowledge = Resolved( - ["applies_to"], - ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 0, ProbeWaitMarginSeconds = 0 }); - var results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); - - var text = Assert.Single(results).Text; - Assert.Contains("holds nothing", text, StringComparison.Ordinal); - Assert.DoesNotContain("unreachable", text, StringComparison.OrdinalIgnoreCase); - } + Assert.Equal(2, clarificationsObject.Read("applies_to").ProbeAsks); + Assert.Equal(2, attempts); + } - [Fact] - public void ResolvedKnowledge_TheAmbiguityMembers_RoundTripThroughInit() - { - var ambiguity = new KnowledgeAmbiguityConfiguration { MaxAsks = 3 }; - var descriptions = Descriptions(("applies_to", Description)); + [Fact] + public async Task Loser_WaitExpiresBeforeAnyOutcomeIsPublished_EmitsHoldsNothing_NeverUnreachable() + { + // C1's own gap: the probe is claimed directly, exactly as a real winner's ProbeAsync would, + // but its payload is never published -- neither Publish nor Fail. With ProbeDeadlineSeconds + // and ProbeWaitMarginSeconds both 0, the loser's own wait times out almost at once, which is + // the row the fix exists for: + // a TimeoutException reaching SearchAsync's outer catch would blame the main search, which + // never ran a second time and never failed. + ProbeFakePort port = new((_, _) => Task.FromResult>([])); + + Clarifications clarificationsObject = new(); + Assert.True(clarificationsObject.ClaimProbe().Won); + + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + + ResolvedKnowledge knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 0, ProbeWaitMarginSeconds = 0 }); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, knowledge), "e33", turn); + + string text = Assert.Single(results).Text; + Assert.Contains("holds nothing", text, StringComparison.Ordinal); + Assert.DoesNotContain("unreachable", text, StringComparison.OrdinalIgnoreCase); + } - var knowledge = new ResolvedKnowledge(KnowledgeMode.Tool, 5, Citations: false, Scoped: true) + [Fact] + public void ResolvedKnowledge_TheAmbiguityMembers_RoundTripThroughInit() { - Clarification = new ResolvedClarification + KnowledgeAmbiguityConfiguration ambiguity = new() { MaxAsks = 3 }; + Dictionary descriptions = Descriptions(("applies_to", Description)); + + ResolvedKnowledge knowledge = new(KnowledgeMode.Tool, 5, Citations: false, Scoped: true) { - WildcardValue = "*", - WildcardFacets = ["applies_to"], - FromState = ["applies_to"], - SlotDescriptions = descriptions, - Ambiguity = ambiguity, - Template = ScopeTemplate.Parse("facets.{key}"), - }, - }; - - var wiring = knowledge.Clarification; - Assert.Equal("*", wiring.WildcardValue); - Assert.Equal(["applies_to"], wiring.WildcardFacets); - Assert.Equal(["applies_to"], wiring.FromState); - Assert.Same(descriptions, wiring.SlotDescriptions); - Assert.Same(ambiguity, wiring.Ambiguity); - Assert.Equal("facets.{key}", wiring.Template?.Raw); - } + Clarification = new ResolvedClarification + { + WildcardValue = "*", + WildcardFacets = ["applies_to"], + FromState = ["applies_to"], + SlotDescriptions = descriptions, + Ambiguity = ambiguity, + Template = ScopeTemplate.Parse("facets.{key}"), + }, + }; + + ResolvedClarification wiring = knowledge.Clarification; + Assert.Equal("*", wiring.WildcardValue); + Assert.Equal(["applies_to"], wiring.WildcardFacets); + Assert.Equal(["applies_to"], wiring.FromState); + Assert.Same(descriptions, wiring.SlotDescriptions); + Assert.Same(ambiguity, wiring.Ambiguity); + Assert.Equal("facets.{key}", wiring.Template?.Raw); + } - [Fact] - public async Task Step3_HostPinnedTheWildcardValue_IsNotDropped() - { - // A host that pins a facet to the wildcard literal is saying "every value of it", not "I did - // not know". Origins is where that difference is recorded, so the value alone cannot decide - // droppability: widening here would overrule the host rather than recover a lost value. - var port = new ProbeFakePort(facets => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task Step3_HostPinnedTheWildcardValue_IsNotDropped() + { + // A host that pins a facet to the wildcard literal is saying "every value of it", not "I did + // not know". Origins is where that difference is recorded, so the value alone cannot decide + // droppability: widening here would overrule the host rather than recover a lost value. + ProbeFakePort port = new(facets => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var turn = TurnOf(ScopeWithOrigins( - ("brand", "acme", KnowledgeFacetOrigin.Host), - ("applies_to", "*", KnowledgeFacetOrigin.Host)), new Clarifications()); + TurnInvocation turn = TurnOf(ScopeWithOrigins( + ("brand", "acme", KnowledgeFacetOrigin.Host), + ("applies_to", "*", KnowledgeFacetOrigin.Host)), new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - Assert.Single(results); - Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); - Assert.Equal(1, port.Calls); - } + _ = Assert.Single(results); + Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); + Assert.Equal(1, port.Calls); + } - [Fact] - public async Task Step3_OriginsRecordTheWildcardFilledIt_SoTheFacetIsDropped() - { - // The row above's control: the same scope and the same value, differing only in what Origins - // records, does reach the probe's second search. - var port = new ProbeFakePort(facets => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task Step3_OriginsRecordTheWildcardFilledIt_SoTheFacetIsDropped() + { + // The row above's control: the same scope and the same value, differing only in what Origins + // records, does reach the probe's second search. + ProbeFakePort port = new(facets => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - var turn = TurnOf(ScopeWithOrigins( - ("brand", "acme", KnowledgeFacetOrigin.Host), - ("applies_to", "*", KnowledgeFacetOrigin.Wildcard)), new Clarifications()); + TurnInvocation turn = TurnOf(ScopeWithOrigins( + ("brand", "acme", KnowledgeFacetOrigin.Host), + ("applies_to", "*", KnowledgeFacetOrigin.Wildcard)), new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - Assert.Single(results); - Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); - Assert.Equal(2, port.Calls); - } + _ = Assert.Single(results); + Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); + Assert.Equal(2, port.Calls); + } - [Fact] - public async Task Step4_TheNarrowedScopeKeepsTheCallersOwnComparer() - { - // The probe rebuilds the scope to drop one facet. Rebuilding on a fixed ordinal comparer would - // silently narrow how a case-insensitive caller's remaining facets match, so the second search - // would run under different matching rules than the first. - var port = new ProbeFakePort(facets => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] - : facets.ContainsKey("brand") ? [CardWithFacet("a", "applies_to", "ct900")] - : [])); - - Dictionary facets = new(StringComparer.OrdinalIgnoreCase) + [Fact] + public async Task Step4_TheNarrowedScopeKeepsTheCallersOwnComparer() { - ["Brand"] = "acme", - ["applies_to"] = "*", - }; + // The probe rebuilds the scope to drop one facet. Rebuilding on a fixed ordinal comparer would + // silently narrow how a case-insensitive caller's remaining facets match, so the second search + // would run under different matching rules than the first. + ProbeFakePort port = new(facets => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] + : facets.ContainsKey("brand") ? [CardWithFacet("a", "applies_to", "ct900")] + : [])); + + Dictionary facets = new(StringComparer.OrdinalIgnoreCase) + { + ["Brand"] = "acme", + ["applies_to"] = "*", + }; - var turn = TurnOf(new KnowledgeScope { Facets = facets }, new Clarifications()); + TurnInvocation turn = TurnOf(new KnowledgeScope { Facets = facets }, new Clarifications()); - var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); + IReadOnlyList results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33", turn); - Assert.Single(results); - Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); - Assert.Equal(2, port.Calls); - } + _ = Assert.Single(results); + Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); + Assert.Equal(2, port.Calls); + } - [Fact] - public async Task Step4_TheDeadlineFiredBeforeTheCallerHungUp_KeepsTheAskCharged() - { - // K22's cap is only monotone if a timeout is charged. Classifying by "is the caller's token - // cancelled now" would refund one whenever the caller happens to hang up in the moment after - // the deadline fired, and a probe that always times out could then offer the same facet - // forever. The port below makes that order certain: it waits for its own token to be - // cancelled -- which only the deadline can do here -- and cancels the caller after. - using CancellationTokenSource caller = new(); - - var port = new ProbeFakePort(async (facets, cancellationToken) => + [Fact] + public async Task Step4_TheDeadlineFiredBeforeTheCallerHungUp_KeepsTheAskCharged() { - if (facets.ContainsKey("applies_to")) + // K22's cap is only monotone if a timeout is charged. Classifying by "is the caller's token + // cancelled now" would refund one whenever the caller happens to hang up in the moment after + // the deadline fired, and a probe that always times out could then offer the same facet + // forever. The port below makes that order certain: it waits for its own token to be + // cancelled -- which only the deadline can do here -- and cancels the caller after. + using CancellationTokenSource caller = new(); + + ProbeFakePort port = new(async (facets, cancellationToken) => { - return []; - } - - try - { - await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); - } - catch (OperationCanceledException) - { - await caller.CancelAsync().ConfigureAwait(false); - throw; - } + if (facets.ContainsKey("applies_to")) + { + return []; + } - throw new UnreachableException(); - }); + try + { + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + await caller.CancelAsync().ConfigureAwait(false); + throw; + } - var clarificationsObject = new Clarifications(); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + throw new UnreachableException(); + }); - var knowledge = Resolved( - ["applies_to"], - ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1 }); + Clarifications clarificationsObject = new(); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - var results = await InvokeSearchWithCallerTokenAsync(Provider(port, knowledge), "e33", turn, caller.Token); + ResolvedKnowledge knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1 }); - Assert.Single(results); - Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); - Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); - } + IReadOnlyList results = await InvokeSearchWithCallerTokenAsync(Provider(port, knowledge), "e33", turn, caller.Token); - [Fact] - public async Task AThrowBetweenTheProbeSearchAndThePublish_StillResolvesTheLatch() - { - // Claiming the latch and publishing an outcome are one contract. Anything that throws between - // them -- here a log sink, the one call the probe makes into host code after its search - // returned -- would otherwise leave the payload unresolved, and every other search in the turn - // would wait out its full margin for an answer that is never coming. - var port = new ProbeFakePort(facets => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - - var clarificationsObject = new Clarifications(); - var turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); - - using ThrowingLoggerFactory loggers = new(ProbeRanEventId); - var provider = KnowledgeProviderFactory.Create( - port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); - - var results = await InvokeSearchAsync(provider, "e33", turn); - - Assert.Single(results); - Assert.Contains("unreachable", results[0].Text, StringComparison.Ordinal); - - // The latch stays claimed, so the turn cannot probe again -- but it is resolved, so a second - // conversation replays at once rather than running out its own clock. - var loser = clarificationsObject.ClaimProbe(); - Assert.False(loser.Won); - await Assert.ThrowsAnyAsync( - () => loser.WaitAsync(TimeSpan.FromSeconds(2), TestContext.Current.CancellationToken)); - } + _ = Assert.Single(results); + Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } - [Fact] - public async Task TheProbesOwnSearchIsRecorded_SoAnOperatorSeesBothStoreCalls() - { - // The record is what an operator sizes store load and debugs an outage from. A turn in which - // the probe fires makes two store calls, so it has to file two records -- the second naming - // the narrowed scope that call actually ran under. - var port = new ProbeFakePort(facets => Task.FromResult>( - facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + [Fact] + public async Task AThrowBetweenTheProbeSearchAndThePublish_StillResolvesTheLatch() + { + // Claiming the latch and publishing an outcome are one contract. Anything that throws between + // them -- here a log sink, the one call the probe makes into host code after its search + // returned -- would otherwise leave the payload unresolved, and every other search in the turn + // would wait out its full margin for an answer that is never coming. + ProbeFakePort port = new(facets => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + + Clarifications clarificationsObject = new(); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), clarificationsObject); + + using ThrowingLoggerFactory loggers = new(ProbeRanEventId); + AIContextProvider provider = KnowledgeProviderFactory.Create( + port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); + + IReadOnlyList results = await InvokeSearchAsync(provider, "e33", turn); + + _ = Assert.Single(results); + Assert.Contains("unreachable", results[0].Text, StringComparison.Ordinal); + + // The latch stays claimed, so the turn cannot probe again -- but it is resolved, so a second + // conversation replays at once rather than running out its own clock. + Clarifications.Probe loser = clarificationsObject.ClaimProbe(); + Assert.False(loser.Won); + _ = await Assert.ThrowsAnyAsync( + () => loser.WaitAsync(TimeSpan.FromSeconds(2), TestContext.Current.CancellationToken)); + } - var turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); + [Fact] + public async Task TheProbesOwnSearchIsRecorded_SoAnOperatorSeesBothStoreCalls() + { + // The record is what an operator sizes store load and debugs an outage from. A turn in which + // the probe fires makes two store calls, so it has to file two records -- the second naming + // the narrowed scope that call actually ran under. + ProbeFakePort port = new(facets => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); - using CountingLoggerFactory loggers = new(RetrievedEventId); - var provider = KnowledgeProviderFactory.Create( - port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); + TurnInvocation turn = TurnOf(FullScope("applies_to", "other"), new Clarifications()); - var results = await InvokeSearchAsync(provider, "e33", turn); + using CountingLoggerFactory loggers = new(RetrievedEventId); + AIContextProvider provider = KnowledgeProviderFactory.Create( + port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); - Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); - Assert.Equal(port.Calls, loggers.Count); - Assert.Equal(2, loggers.Count); - } + IReadOnlyList results = await InvokeSearchAsync(provider, "e33", turn); - // Helpers. + Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); + Assert.Equal(port.Calls, loggers.Count); + Assert.Equal(2, loggers.Count); + } - /// Log.KnowledgeProbeRan's event id: the probe's one call into host code after its search. - private const int ProbeRanEventId = 16; + // Helpers. - private static KnowledgeScope ScopeWithOrigins( - params (string Facet, string Value, KnowledgeFacetOrigin Origin)[] entries) - { - Dictionary facets = new(StringComparer.Ordinal); - Dictionary origins = new(StringComparer.Ordinal); + /// Log.KnowledgeProbeRan's event id: the probe's one call into host code after its search. + private const int ProbeRanEventId = 16; - foreach (var (facet, value, origin) in entries) + private static KnowledgeScope ScopeWithOrigins( + params (string Facet, string Value, KnowledgeFacetOrigin Origin)[] entries) { - facets[facet] = value; - origins[facet] = origin; + Dictionary facets = new(StringComparer.Ordinal); + Dictionary origins = new(StringComparer.Ordinal); + + foreach ((string? facet, string? value, KnowledgeFacetOrigin origin) in entries) + { + facets[facet] = value; + origins[facet] = origin; + } + + return new KnowledgeScope { Facets = facets, Origins = origins }; } - return new KnowledgeScope { Facets = facets, Origins = origins }; - } + /// Log.KnowledgeRetrieved's event id: one record per store call. + private const int RetrievedEventId = 11; - /// Log.KnowledgeRetrieved's event id: one record per store call. - private const int RetrievedEventId = 11; + /// A logger factory whose loggers count one event id, for a test that sizes store calls. + private sealed class CountingLoggerFactory : ILoggerFactory + { + private readonly CountingLogger _logger; - /// A logger factory whose loggers count one event id, for a test that sizes store calls. - private sealed class CountingLoggerFactory : ILoggerFactory - { - private readonly CountingLogger _logger; + internal CountingLoggerFactory(int eventId) + { + _logger = new CountingLogger(eventId); + } - internal CountingLoggerFactory(int eventId) => _logger = new CountingLogger(eventId); + internal int Count => _logger.Count; - internal int Count => _logger.Count; + public void AddProvider(ILoggerProvider provider) + { + } - public void AddProvider(ILoggerProvider provider) - { - } + public ILogger CreateLogger(string categoryName) + { + return _logger; + } - public ILogger CreateLogger(string categoryName) => _logger; + public void Dispose() + { + } - public void Dispose() - { + private sealed class CountingLogger : ILogger + { + private readonly int _eventId; + + private int _count; + + internal CountingLogger(int eventId) + { + _eventId = eventId; + } + + internal int Count => Volatile.Read(ref _count); + + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } + + public bool IsEnabled(LogLevel logLevel) + { + return true; + } + + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + if (eventId.Id == _eventId) + { + _ = Interlocked.Increment(ref _count); + } + } + } } - private sealed class CountingLogger : ILogger + /// A logger factory whose loggers throw on one event id, standing in for a failing host sink. + private sealed class ThrowingLoggerFactory : ILoggerFactory { private readonly int _eventId; - private int _count; - - internal CountingLogger(int eventId) => _eventId = eventId; + internal ThrowingLoggerFactory(int eventId) + { + _eventId = eventId; + } - internal int Count => Volatile.Read(ref _count); + public void AddProvider(ILoggerProvider provider) + { + } - public IDisposable? BeginScope(TState state) - where TState : notnull => null; + public ILogger CreateLogger(string categoryName) + { + return new ThrowingLogger(_eventId); + } - public bool IsEnabled(LogLevel logLevel) => true; + public void Dispose() + { + } - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + private sealed class ThrowingLogger : ILogger { - if (eventId.Id == _eventId) + private readonly int _eventId; + + internal ThrowingLogger(int eventId) { - Interlocked.Increment(ref _count); + _eventId = eventId; } - } - } - } - /// A logger factory whose loggers throw on one event id, standing in for a failing host sink. - private sealed class ThrowingLoggerFactory : ILoggerFactory - { - private readonly int _eventId; + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } - internal ThrowingLoggerFactory(int eventId) => _eventId = eventId; + public bool IsEnabled(LogLevel logLevel) + { + return true; + } - public void AddProvider(ILoggerProvider provider) - { + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + if (eventId.Id == _eventId) + { + throw new InvalidOperationException("the log sink is down"); + } + } + } } - public ILogger CreateLogger(string categoryName) => new ThrowingLogger(_eventId); - - public void Dispose() + private static AIContextProvider Provider(IKnowledgeRetrievalPort port, ResolvedKnowledge knowledge) { + return KnowledgeProviderFactory.Create( + port, knowledge, "agent-under-test", new SourceLocatorCitationFormatter(), loggers: null); } - private sealed class ThrowingLogger : ILogger + private static TurnInvocation TurnOf( + KnowledgeScope? scope, + Clarifications? clarifications = null, + bool carriesHistory = false, + TurnSources? sources = null) { - private readonly int _eventId; + return new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Knowledge = scope, + Clarifications = clarifications, + CarriesHistory = carriesHistory, + Sources = sources, + }; + } - internal ThrowingLogger(int eventId) => _eventId = eventId; + private static ResolvedKnowledge Resolved( + IReadOnlyList fromState, + string wildcardValue = "*", + IReadOnlyList? wildcardFacets = null, + string template = "{key}", + KnowledgeAmbiguityConfiguration? ambiguity = null, + IReadOnlyDictionary? slotDescriptions = null, + bool citations = false, + bool scoped = true) + { + return new(KnowledgeMode.Tool, Limit: 5, Citations: citations, Scoped: scoped) + { + Clarification = new ResolvedClarification + { + WildcardValue = wildcardValue, + WildcardFacets = wildcardFacets ?? fromState, + FromState = fromState, + SlotDescriptions = slotDescriptions ?? new Dictionary(StringComparer.Ordinal), + Ambiguity = ambiguity ?? new KnowledgeAmbiguityConfiguration(), + Template = ScopeTemplate.Parse(template), + }, + }; + } - public IDisposable? BeginScope(TState state) - where TState : notnull => null; + private static Dictionary Descriptions(params (string Slot, string Text)[] entries) + { + Dictionary map = new(StringComparer.Ordinal); + foreach ((string? slot, string? text) in entries) + { + map[slot] = text; + } - public bool IsEnabled(LogLevel logLevel) => true; + return map; + } - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + private static KnowledgeScope FullScope(params string[] wildcardFacets) + { + Dictionary facets = new(StringComparer.Ordinal); + foreach (string facet in wildcardFacets) { - if (eventId.Id == _eventId) - { - throw new InvalidOperationException("the log sink is down"); - } + facets[facet] = "*"; } + + return new KnowledgeScope { Facets = facets }; } - } - private static AIContextProvider Provider(IKnowledgeRetrievalPort port, ResolvedKnowledge knowledge) - => KnowledgeProviderFactory.Create( - port, knowledge, "agent-under-test", new SourceLocatorCitationFormatter(), loggers: null); + private static KnowledgeCard Card(string id) + { + return new() { CardId = id, Text = "card " + id, ViaLink = false }; + } - private static TurnInvocation TurnOf( - KnowledgeScope? scope, - Clarifications? clarifications = null, - bool carriesHistory = false, - TurnSources? sources = null) => new() - { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Knowledge = scope, - Clarifications = clarifications, - CarriesHistory = carriesHistory, - Sources = sources, - }; - - private static ResolvedKnowledge Resolved( - IReadOnlyList fromState, - string wildcardValue = "*", - IReadOnlyList? wildcardFacets = null, - string template = "{key}", - KnowledgeAmbiguityConfiguration? ambiguity = null, - IReadOnlyDictionary? slotDescriptions = null, - bool citations = false, - bool scoped = true) - => new(KnowledgeMode.Tool, Limit: 5, Citations: citations, Scoped: scoped) + private static KnowledgeCard CardWithFacet(string id, string facetKey, string value, string template = "{key}") { - Clarification = new ResolvedClarification + return new() { - WildcardValue = wildcardValue, - WildcardFacets = wildcardFacets ?? fromState, - FromState = fromState, - SlotDescriptions = slotDescriptions ?? new Dictionary(StringComparer.Ordinal), - Ambiguity = ambiguity ?? new KnowledgeAmbiguityConfiguration(), - Template = ScopeTemplate.Parse(template), - }, - }; - - private static Dictionary Descriptions(params (string Slot, string Text)[] entries) - { - Dictionary map = new(StringComparer.Ordinal); - foreach (var (slot, text) in entries) - { - map[slot] = text; + CardId = id, + Text = "card " + id, + ViaLink = false, + Extras = NestedExtras(template.Replace("{key}", facetKey), value), + }; } - return map; - } - - private static KnowledgeScope FullScope(params string[] wildcardFacets) - { - Dictionary facets = new(StringComparer.Ordinal); - foreach (var facet in wildcardFacets) + private static KnowledgeCard CardWithFacetList(string id, string facetKey, IReadOnlyList values) { - facets[facet] = "*"; + return new() + { + CardId = id, + Text = "card " + id, + ViaLink = false, + Extras = new Dictionary(StringComparer.Ordinal) { [facetKey] = (IReadOnlyList)[.. values] }, + }; } - return new KnowledgeScope { Facets = facets }; - } + /// Builds the nested Extras shape a dotted payload path resolves into. + private static IReadOnlyDictionary NestedExtras(string path, string value) + { + string[] parts = path.Split('.'); + object? node = value; - private static KnowledgeCard Card(string id) - => new() { CardId = id, Text = "card " + id, ViaLink = false }; + for (int i = parts.Length - 1; i >= 0; i--) + { + node = new Dictionary(StringComparer.Ordinal) { [parts[i]] = node }; + } - private static KnowledgeCard CardWithFacet(string id, string facetKey, string value, string template = "{key}") - => new() + return (IReadOnlyDictionary)node!; + } + + /// + /// Invokes the search tool the provider offers, the way the model would: the turn rides along + /// as an argument, carrying the scope and the clarifications the search runs under. + /// + private static Task> InvokeSearchAsync( + AIContextProvider provider, string query, TurnInvocation turn) { - CardId = id, - Text = "card " + id, - ViaLink = false, - Extras = NestedExtras(template.Replace("{key}", facetKey), value), - }; - - private static KnowledgeCard CardWithFacetList(string id, string facetKey, IReadOnlyList values) - => new() + return InvokeSearchWithCallerTokenAsync(provider, query, turn, TestContext.Current.CancellationToken); + } + + /// + /// The cancellation row's own entry point: here is the + /// SIMULATED CALLER's own token (K43's cancellation row), never the test host's — see + /// , its + /// only caller. Named apart from + /// so a deliberately non-TestContext token at this one conversation site does not read as a mistake. + /// + private static async Task> InvokeSearchWithCallerTokenAsync( + AIContextProvider provider, string query, TurnInvocation turn, CancellationToken callerToken) { - CardId = id, - Text = "card " + id, - ViaLink = false, - Extras = new Dictionary(StringComparer.Ordinal) { [facetKey] = (IReadOnlyList)[.. values] }, - }; - - /// Builds the nested Extras shape a dotted payload path resolves into. - private static IReadOnlyDictionary NestedExtras(string path, string value) - { - var parts = path.Split('.'); - object? node = value; + StubSession session = new(); + AIContext context = await provider.InvokingAsync( + Invoking("hello", session), TestContext.Current.CancellationToken).ConfigureAwait(false); + AITool search = Assert.Single(context.Tools!, tool => tool.Name == "Search"); + IReadOnlyList? results = await ((AIFunction)search).InvokeAsync( + turn.FileIn(new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) + { + ["userQuestion"] = query, + })), + callerToken).ConfigureAwait(false) + as IReadOnlyList; + return results!; + } - for (var i = parts.Length - 1; i >= 0; i--) + /// Runs the provider the way the framework runs it, over one caller message. + private static AIContextProvider.InvokingContext Invoking(string text, AgentSession session) { - node = new Dictionary(StringComparer.Ordinal) { [parts[i]] = node }; +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + return new( + StubAgent.Instance, + session, + new AIContext { Messages = [new ChatMessage(ChatRole.User, text)] }); +#pragma warning restore MAAI001 } - return (IReadOnlyDictionary)node!; - } + private sealed class StubSession : AgentSession; - /// - /// Invokes the search tool the provider offers, the way the model would: the turn rides along - /// as an argument, carrying the scope and the clarifications the search runs under. - /// - private static Task> InvokeSearchAsync( - AIContextProvider provider, string query, TurnInvocation turn) - => InvokeSearchWithCallerTokenAsync(provider, query, turn, TestContext.Current.CancellationToken); + /// Stands in for the agent the framework names on a context. Nothing here runs it. + private sealed class StubAgent : AIAgent + { + public static StubAgent Instance { get; } = new(); - /// - /// The cancellation row's own entry point: here is the - /// SIMULATED CALLER's own token (K43's cancellation row), never the test host's — see - /// , its - /// only caller. Named apart from - /// so a deliberately non-TestContext token at this one conversation site does not read as a mistake. - /// - private static async Task> InvokeSearchWithCallerTokenAsync( - AIContextProvider provider, string query, TurnInvocation turn, CancellationToken callerToken) - { - StubSession session = new(); - var context = await provider.InvokingAsync( - Invoking("hello", session), TestContext.Current.CancellationToken).ConfigureAwait(false); - var search = Assert.Single(context.Tools!, tool => tool.Name == "Search"); - var results = await ((AIFunction)search).InvokeAsync( - turn.FileIn(new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) { - ["userQuestion"] = query, - })), - callerToken).ConfigureAwait(false) - as IReadOnlyList; - return results!; - } + return new(new StubSession()); + } - /// Runs the provider the way the framework runs it, over one caller message. - private static AIContextProvider.InvokingContext Invoking(string text, AgentSession session) - { -#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - return new( - StubAgent.Instance, - session, - new AIContext { Messages = [new ChatMessage(ChatRole.User, text)] }); -#pragma warning restore MAAI001 - } + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - private sealed class StubSession : AgentSession; + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - /// Stands in for the agent the framework names on a context. Nothing here runs it. - private sealed class StubAgent : AIAgent - { - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - } + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - /// - /// A knowledge store whose answer is a function of the passed scope's facets, so one instance can - /// stand in for both the main search (full scope) and the probe's own second search (narrowed). - /// - private sealed class ProbeFakePort : IKnowledgeRetrievalPort - { - private readonly Func, CancellationToken, Task>> _answer; + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } - internal ProbeFakePort(Func, Task>> answer) - : this((facets, _) => answer(facets)) + /// + /// A knowledge store whose answer is a function of the passed scope's facets, so one instance can + /// stand in for both the main search (full scope) and the probe's own second search (narrowed). + /// + private sealed class ProbeFakePort : IKnowledgeRetrievalPort { - } + private readonly Func, CancellationToken, Task>> _answer; - internal ProbeFakePort( - Func, CancellationToken, Task>> answer) - => _answer = answer; + internal ProbeFakePort(Func, Task>> answer) + : this((facets, _) => answer(facets)) + { + } - internal int Calls { get; private set; } + internal ProbeFakePort( + Func, CancellationToken, Task>> answer) + { + _answer = answer; + } - public async ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - { - Calls++; - var facets = scope?.Facets ?? new Dictionary(StringComparer.Ordinal); - return await _answer(facets, cancellationToken).ConfigureAwait(false); + internal int Calls { get; private set; } + + public async ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + Calls++; + IReadOnlyDictionary facets = scope?.Facets ?? new Dictionary(StringComparer.Ordinal); + return await _answer(facets, cancellationToken).ConfigureAwait(false); + } } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs index 0782417d..b6069c3c 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs @@ -1,4 +1,3 @@ -using System.Reflection; using System.Text.Json; using AgentCore.TestSupport; using AgentCore.Application.Configuration.Compilation; @@ -8,819 +7,850 @@ using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Turn; using AgentCore.Application.Tests.Knowledge.Fakes; -using AgentCore.Application.Tests.Runtime.Turn; using AgentCore.Domain.Knowledge; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Microsoft.Extensions.Logging; using Xunit; +using AgentCore.Application.Transcript; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The layer that decides, per agent, how retrieval reaches the model — and the only layer that can -/// enforce the two per-agent settings the one-method port cannot carry. -/// -/// -/// InvokingAsync returns the input context merged with what the provider added, so a test -/// that reads sees the caller's own message as well. "Injected -/// nothing" is therefore "the input message and no more". -/// -public sealed class KnowledgeProviderFactoryTests +namespace AgentCore.Application.Tests.Knowledge { - [Fact] - public async Task Create_PrefetchMode_RetrievesBeforeTheModelIsCalled() - { - var port = new StubKnowledgePort([Card("a"), Card("b")]); + /// + /// The layer that decides, per agent, how retrieval reaches the model — and the only layer that can + /// enforce the two per-agent settings the one-method port cannot carry. + /// + /// + /// InvokingAsync returns the input context merged with what the provider added, so a test + /// that reads sees the caller's own message as well. "Injected + /// nothing" is therefore "the input message and no more". + /// + public sealed class KnowledgeProviderFactoryTests + { + [Fact] + public async Task Create_PrefetchMode_RetrievesBeforeTheModelIsCalled() + { + StubKnowledgePort port = new([Card("a"), Card("b")]); - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch)); - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - Assert.Null(context.Tools); - Assert.Equal("the screen says e33", port.LastQuery); - Assert.Contains("card a", Merged(context), StringComparison.Ordinal); - Assert.Contains("card b", Merged(context), StringComparison.Ordinal); - } + Assert.Null(context.Tools); + Assert.Equal("the screen says e33", port.LastQuery); + Assert.Contains("card a", Merged(context), StringComparison.Ordinal); + Assert.Contains("card b", Merged(context), StringComparison.Ordinal); + } - [Fact] - public async Task Create_ToolMode_OffersASearchToolInstead() - { - var port = new StubKnowledgePort([Card("a")]); + [Fact] + public async Task Create_ToolMode_OffersASearchToolInstead() + { + StubKnowledgePort port = new([Card("a")]); - var provider = Provider(port, Resolved(KnowledgeMode.Tool)); - var context = await provider.InvokingAsync( - Invoking("hello", new StubSession()), TestContext.Current.CancellationToken); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Tool)); + AIContext context = await provider.InvokingAsync( + Invoking("hello", new StubSession()), TestContext.Current.CancellationToken); - Assert.NotNull(context.Tools); - Assert.Single(context.Tools); - Assert.Equal(0, port.Calls); - } + Assert.NotNull(context.Tools); + _ = Assert.Single(context.Tools); + Assert.Equal(0, port.Calls); + } - [Fact] - public async Task Create_PortThrows_InjectsANoticeAndDoesNotFailTheTurn() - { - // A16. The framework's own behaviour here is SILENT fail-open: a throwing delegate - // injects nothing at all and logs nothing, and the model then answers "E03 means - // overheating" from its own weights. So the delegate must catch and say so. - var provider = Provider( - new ThrowingKnowledgePort(new InvalidOperationException("qdrant is down")), - Resolved(KnowledgeMode.Prefetch)); - - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - var text = Merged(context); - Assert.Contains("knowledge base", text, StringComparison.OrdinalIgnoreCase); - Assert.Contains("unreachable", text, StringComparison.OrdinalIgnoreCase); - Assert.Contains("do not answer from memory", text, StringComparison.OrdinalIgnoreCase); - } + [Fact] + public async Task Create_PortThrows_InjectsANoticeAndDoesNotFailTheTurn() + { + // A16. The framework's own behaviour here is SILENT fail-open: a throwing delegate + // injects nothing at all and logs nothing, and the model then answers "E03 means + // overheating" from its own weights. So the delegate must catch and say so. + AIContextProvider provider = Provider( + new ThrowingKnowledgePort(new InvalidOperationException("qdrant is down")), + Resolved(KnowledgeMode.Prefetch)); + + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + string text = Merged(context); + Assert.Contains("knowledge base", text, StringComparison.OrdinalIgnoreCase); + Assert.Contains("unreachable", text, StringComparison.OrdinalIgnoreCase); + Assert.Contains("do not answer from memory", text, StringComparison.OrdinalIgnoreCase); + } - [Fact] - public async Task Create_TheStoresOwnDeadlineFires_InjectsTheNoticeAndWritesTheCause() - { - // A16 asks this delegate to catch every exception AND its own deadline. The store links that - // deadline into the caller's token, and the channel reports a cancelled gRPC call as - // OperationCanceledException -- so a hung Qdrant arrives as the same type a caller cancel - // does. Excluding the type outright let the deadline straight through: no notice, no record, - // no log line, and a model answering "E33 means the incline motor" from its own weights. - RecordingLoggerFactory loggers = new(); - - var provider = KnowledgeProviderFactory.Create( - new HangingKnowledgePort(TimeSpan.FromMilliseconds(20)), - Resolved(KnowledgeMode.Prefetch), - "resolver", - new SourceLocatorCitationFormatter(), - loggers); - - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - var text = Merged(context); - Assert.Contains("unreachable", text, StringComparison.OrdinalIgnoreCase); - Assert.Contains("do not answer from memory", text, StringComparison.OrdinalIgnoreCase); - - var line = Assert.Single(loggers.Of(12)); - Assert.Equal(LogLevel.Error, line.Level); - Assert.Equal("resolver", line.Field("Agent")); - Assert.IsType(line.Exception, exactMatch: false); - } + [Fact] + public async Task Create_TheStoresOwnDeadlineFires_InjectsTheNoticeAndWritesTheCause() + { + // A16 asks this delegate to catch every exception AND its own deadline. The store links that + // deadline into the caller's token, and the channel reports a cancelled gRPC call as + // OperationCanceledException -- so a hung Qdrant arrives as the same type a caller cancel + // does. Excluding the type outright let the deadline straight through: no notice, no record, + // no log line, and a model answering "E33 means the incline motor" from its own weights. + RecordingLoggerFactory loggers = new(); + + AIContextProvider provider = KnowledgeProviderFactory.Create( + new HangingKnowledgePort(TimeSpan.FromMilliseconds(20)), + Resolved(KnowledgeMode.Prefetch), + "resolver", + new SourceLocatorCitationFormatter(), + loggers); + + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + string text = Merged(context); + Assert.Contains("unreachable", text, StringComparison.OrdinalIgnoreCase); + Assert.Contains("do not answer from memory", text, StringComparison.OrdinalIgnoreCase); + + CapturedLine line = Assert.Single(loggers.Of(12)); + Assert.Equal(LogLevel.Error, line.Level); + Assert.Equal("resolver", line.Field("Agent")); + _ = Assert.IsType(line.Exception, exactMatch: false); + } - [Fact] - public async Task Create_TheCallerCancels_IsNotDressedUpAsARetrievalFailure() - { - // The other half of the same classifier, and the reason it cannot simply catch the type: a - // hung-up caller produces no answer, so a notice has nowhere to land and an Error row would - // fire on every abandoned turn of every agent. The port raises its exception carrying the - // LINKED token here, exactly as the real store does, so nothing but the caller's own token - // separates this case from the deadline above. - RecordingLoggerFactory loggers = new(); - using CancellationTokenSource caller = new(); - - var provider = KnowledgeProviderFactory.Create( - new HangingKnowledgePort(TimeSpan.FromMinutes(5)), - Resolved(KnowledgeMode.Prefetch), - "resolver", - new SourceLocatorCitationFormatter(), - loggers); - - caller.CancelAfter(TimeSpan.FromMilliseconds(20)); - - StubSession callerSession = new(); - TurnRegistry.Set(callerSession, PrefetchTurn()); - - // The framework swallows whatever escapes the delegate, so "propagated" is read off what did - // NOT happen: no notice, and neither the success row nor the failure row. A delegate that - // returned normally would have written row 11, and one that took the failure path row 12. - var context = await provider.InvokingAsync(Invoking("the screen says e33", callerSession), caller.Token); - - Assert.DoesNotContain("unreachable", Merged(context), StringComparison.OrdinalIgnoreCase); - Assert.Empty(loggers.Of(11)); - Assert.Empty(loggers.Of(12)); - } + [Fact] + public async Task Create_TheCallerCancels_IsNotDressedUpAsARetrievalFailure() + { + // The other half of the same classifier, and the reason it cannot simply catch the type: a + // hung-up caller produces no answer, so a notice has nowhere to land and an Error row would + // fire on every abandoned turn of every agent. The port raises its exception carrying the + // LINKED token here, exactly as the real store does, so nothing but the caller's own token + // separates this case from the deadline above. + RecordingLoggerFactory loggers = new(); + using CancellationTokenSource caller = new(); + + AIContextProvider provider = KnowledgeProviderFactory.Create( + new HangingKnowledgePort(TimeSpan.FromMinutes(5)), + Resolved(KnowledgeMode.Prefetch), + "resolver", + new SourceLocatorCitationFormatter(), + loggers); + + caller.CancelAfter(TimeSpan.FromMilliseconds(20)); + + StubSession callerSession = new(); + TurnRegistry.Set(callerSession, PrefetchTurn()); + + // The framework swallows whatever escapes the delegate, so "propagated" is read off what did + // NOT happen: no notice, and neither the success row nor the failure row. A delegate that + // returned normally would have written row 11, and one that took the failure path row 12. + AIContext context = await provider.InvokingAsync(Invoking("the screen says e33", callerSession), caller.Token); + + Assert.DoesNotContain("unreachable", Merged(context), StringComparison.OrdinalIgnoreCase); + Assert.Empty(loggers.Of(11)); + Assert.Empty(loggers.Of(12)); + } - [Fact] - public async Task Create_PortReturnsNothing_InjectsNothing() - { - // The score floor is the gate. An empty list must not produce an empty "Additional - // Context" block that costs tokens and says nothing. - var provider = Provider( - new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch)); + [Fact] + public async Task Create_PortReturnsNothing_InjectsNothing() + { + // The score floor is the gate. An empty list must not produce an empty "Additional + // Context" block that costs tokens and says nothing. + AIContextProvider provider = Provider( + new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch)); - var context = await InvokePrefetchAsync(provider, "hello", PrefetchTurn(), new StubSession()); + AIContext context = await InvokePrefetchAsync(provider, "hello", PrefetchTurn(), new StubSession()); - Assert.Equal(["hello"], Texts(context)); - } + Assert.Equal(["hello"], Texts(context)); + } - [Fact] - public async Task Create_ScopedAgentWithNoAmbientScope_NeverReachesThePort() - { - // Ruling 14(b). The store is shared, so it stays permissive whenever one agent is unscoped. - // Without this gate, scoped: true on THIS agent would serve every customer every card. - var port = new StubKnowledgePort([Card("a"), Card("b")]); - - var provider = Provider( - port, Resolved(KnowledgeMode.Prefetch, scoped: true)); - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - Assert.Equal(0, port.Calls); - Assert.DoesNotContain("card a", Merged(context), StringComparison.Ordinal); - Assert.Contains("no scope is open", Merged(context), StringComparison.OrdinalIgnoreCase); - Assert.Contains("do not answer from memory", Merged(context), StringComparison.OrdinalIgnoreCase); - } + [Fact] + public async Task Create_ScopedAgentWithNoAmbientScope_NeverReachesThePort() + { + // Ruling 14(b). The store is shared, so it stays permissive whenever one agent is unscoped. + // Without this gate, scoped: true on THIS agent would serve every customer every card. + StubKnowledgePort port = new([Card("a"), Card("b")]); + + AIContextProvider provider = Provider( + port, Resolved(KnowledgeMode.Prefetch, scoped: true)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + Assert.Equal(0, port.Calls); + Assert.DoesNotContain("card a", Merged(context), StringComparison.Ordinal); + Assert.Contains("no scope is open", Merged(context), StringComparison.OrdinalIgnoreCase); + Assert.Contains("do not answer from memory", Merged(context), StringComparison.OrdinalIgnoreCase); + } - [Fact] - public async Task Create_ScopedAgentWithAnEmptyScope_NeverReachesThePort() - { - // An ambient with no facets filters nothing, so it is the absent ambient wearing a hat. - var port = new StubKnowledgePort([Card("a"), Card("b")]); - var scope = new KnowledgeScope { Facets = new Dictionary() }; + [Fact] + public async Task Create_ScopedAgentWithAnEmptyScope_NeverReachesThePort() + { + // An ambient with no facets filters nothing, so it is the absent ambient wearing a hat. + StubKnowledgePort port = new([Card("a"), Card("b")]); + KnowledgeScope scope = new() { Facets = new Dictionary() }; - var provider = Provider( - port, Resolved(KnowledgeMode.Prefetch, scoped: true)); - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); + AIContextProvider provider = Provider( + port, Resolved(KnowledgeMode.Prefetch, scoped: true)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); - Assert.Equal(0, port.Calls); - Assert.Contains("no scope is open", Merged(context), StringComparison.OrdinalIgnoreCase); - } + Assert.Equal(0, port.Calls); + Assert.Contains("no scope is open", Merged(context), StringComparison.OrdinalIgnoreCase); + } - [Fact] - public async Task Create_ScopedAgentWithAScopeOpen_Searches() - { - var port = new StubKnowledgePort([Card("a")]); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + [Fact] + public async Task Create_ScopedAgentWithAScopeOpen_Searches() + { + StubKnowledgePort port = new([Card("a")]); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - var provider = Provider( - port, Resolved(KnowledgeMode.Prefetch, scoped: true)); - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); + AIContextProvider provider = Provider( + port, Resolved(KnowledgeMode.Prefetch, scoped: true)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); - Assert.Equal(1, port.Calls); - Assert.Contains("card a", Merged(context), StringComparison.Ordinal); - } + Assert.Equal(1, port.Calls); + Assert.Contains("card a", Merged(context), StringComparison.Ordinal); + } - [Fact] - public async Task Create_UnscopedAgentWithNoAmbientScope_StillSearches() - { - // The gate is keyed on the agent's own flag, not on the store's. An unscoped agent in a - // mixed deployment must keep working when no host opened a scope. - var port = new StubKnowledgePort([Card("a")]); + [Fact] + public async Task Create_UnscopedAgentWithNoAmbientScope_StillSearches() + { + // The gate is keyed on the agent's own flag, not on the store's. An unscoped agent in a + // mixed deployment must keep working when no host opened a scope. + StubKnowledgePort port = new([Card("a")]); - var provider = Provider( - port, Resolved(KnowledgeMode.Prefetch, scoped: false)); - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + AIContextProvider provider = Provider( + port, Resolved(KnowledgeMode.Prefetch, scoped: false)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - Assert.Equal(1, port.Calls); - Assert.Contains("card a", Merged(context), StringComparison.Ordinal); - } + Assert.Equal(1, port.Calls); + Assert.Contains("card a", Merged(context), StringComparison.Ordinal); + } - [Fact] - public async Task Create_UnscopedAgentUnderAScopedHostAmbient_StillSearchesTheWholeCorpus() - { - // Ruling 20, and the defect it resolves. example.yaml ships a mixed deployment: the resolver - // requires a scope, so the host sets ct900 for the whole conversation, and the analyst -- which the - // same document says "searches every product on purpose" -- was silently filtered to ct900 - // with it. The store folds whatever scope it is handed into the filter, so the turn's scope - // has to stop here for an unscoped agent. - var port = new ScopeFilteringKnowledgePort( - (Card("ct900"), Facets("ct900")), - (Card("ent"), Facets("ct900ent"))); - - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; - - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: false)); - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); - - // The card OUTSIDE the host's facet is the whole point: an unscoped agent sees it. - Assert.Contains("card ent", Merged(context), StringComparison.Ordinal); - Assert.Contains("card ct900", Merged(context), StringComparison.Ordinal); - } + [Fact] + public async Task Create_UnscopedAgentUnderAScopedHostAmbient_StillSearchesTheWholeCorpus() + { + // Ruling 20, and the defect it resolves. example.yaml ships a mixed deployment: the resolver + // requires a scope, so the host sets ct900 for the whole conversation, and the analyst -- which the + // same document says "searches every product on purpose" -- was silently filtered to ct900 + // with it. The store folds whatever scope it is handed into the filter, so the turn's scope + // has to stop here for an unscoped agent. + ScopeFilteringKnowledgePort port = new( + (Card("ct900"), Facets("ct900")), + (Card("ent"), Facets("ct900ent"))); + + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; + + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: false)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); + + // The card OUTSIDE the host's facet is the whole point: an unscoped agent sees it. + Assert.Contains("card ent", Merged(context), StringComparison.Ordinal); + Assert.Contains("card ct900", Merged(context), StringComparison.Ordinal); + } - [Fact] - public async Task Create_UnscopedAgent_ReachesTheStoreUnderAnEmptyScopeRatherThanTheHosts() - { - // The mechanism behind the fact above, asserted where the store reads it. An empty facet map - // adds no filter condition, so this is a whole-corpus read and not a differently-shaped one. - var port = new StubKnowledgePort([Card("a")]); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + [Fact] + public async Task Create_UnscopedAgent_ReachesTheStoreUnderAnEmptyScopeRatherThanTheHosts() + { + // The mechanism behind the fact above, asserted where the store reads it. An empty facet map + // adds no filter condition, so this is a whole-corpus read and not a differently-shaped one. + StubKnowledgePort port = new([Card("a")]); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: false)); - await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: false)); + _ = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); - Assert.NotNull(port.ScopeAtTheStore); - Assert.Empty(port.ScopeAtTheStore.Facets); - } + Assert.NotNull(port.ScopeAtTheStore); + Assert.Empty(port.ScopeAtTheStore.Facets); + } - [Fact] - public async Task Create_ScopedAgent_ReachesTheStoreUnderTheHostsOwnScope() - { - // The counterpart. Taking the scope away from the unscoped agent must not take it away from - // the scoped one, which is the agent the scope exists for. - var port = new StubKnowledgePort([Card("a")]); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + [Fact] + public async Task Create_ScopedAgent_ReachesTheStoreUnderTheHostsOwnScope() + { + // The counterpart. Taking the scope away from the unscoped agent must not take it away from + // the scoped one, which is the agent the scope exists for. + StubKnowledgePort port = new([Card("a")]); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: true)); - await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: true)); + _ = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); - Assert.Same(scope, port.ScopeAtTheStore); - } + Assert.Same(scope, port.ScopeAtTheStore); + } - [Fact] - public async Task Create_UnscopedAgent_PutsTheHostsScopeBackAfterTheSearch() - { - // The empty scope covers one port conversation and nothing else. Leaking it would silently unscope the - // scoped agent that runs next -- the very leak this whole design fails closed against, - // arriving from the inside. - var port = new StubKnowledgePort([Card("a")]); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + [Fact] + public async Task Create_UnscopedAgent_PutsTheHostsScopeBackAfterTheSearch() + { + // The empty scope covers one port conversation and nothing else. Leaking it would silently unscope the + // scoped agent that runs next -- the very leak this whole design fails closed against, + // arriving from the inside. + StubKnowledgePort port = new([Card("a")]); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: false)); - await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: false)); + _ = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - // The empty scope covered that one search only: a scoped turn still resolves the host's scope. - var scoped = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: true)); - await InvokePrefetchAsync(scoped, "the screen says e33", PrefetchTurn(scope), new StubSession()); + // The empty scope covered that one search only: a scoped turn still resolves the host's scope. + AIContextProvider scoped = Provider(port, Resolved(KnowledgeMode.Prefetch, scoped: true)); + _ = await InvokePrefetchAsync(scoped, "the screen says e33", PrefetchTurn(scope), new StubSession()); - Assert.Same(scope, port.ScopeAtTheStore); - } + Assert.Same(scope, port.ScopeAtTheStore); + } - [Fact] - public async Task Create_ASearchThatAnswered_WritesTheRetrievalRecord() - { - // A19. Ruling 21 gave KnowledgeAuditRecord a producer: without one the type shipped tested and - // dead, and a retrieval left no artifact of any kind. - RecordingLoggerFactory loggers = new(); - var port = new StubKnowledgePort([Card("a"), Linked("z")]); - - var provider = KnowledgeProviderFactory.Create( - port, Resolved(KnowledgeMode.Prefetch), "analyst", new SourceLocatorCitationFormatter(), loggers); - await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - var line = Assert.Single(loggers.Of(11)); - Assert.Equal("analyst", line.Field("Agent")); - Assert.Equal(2, line.Field("CardCount")); - - var record = line.Field("Record"); - Assert.NotNull(record); - // "link", not "see_also": the audit record says how the card arrived, in its own words, - // rather than repeating one collection's payload key back at the reader. - Assert.Equal(["ranked", "link"], record.Cards.Select(card => card.Via)); - Assert.Equal("analyst", record.Agent); - } + [Fact] + public async Task Create_ASearchThatAnswered_WritesTheRetrievalRecord() + { + // A19. Ruling 21 gave KnowledgeAuditRecord a producer: without one the type shipped tested and + // dead, and a retrieval left no artifact of any kind. + RecordingLoggerFactory loggers = new(); + StubKnowledgePort port = new([Card("a"), Linked("z")]); + + AIContextProvider provider = KnowledgeProviderFactory.Create( + port, Resolved(KnowledgeMode.Prefetch), "analyst", new SourceLocatorCitationFormatter(), loggers); + _ = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + CapturedLine line = Assert.Single(loggers.Of(11)); + Assert.Equal("analyst", line.Field("Agent")); + Assert.Equal(2, line.Field("CardCount")); + + KnowledgeAuditRecord.LogView? record = line.Field("Record"); + Assert.NotNull(record); + // "link", not "see_also": the audit record says how the card arrived, in its own words, + // rather than repeating one collection's payload key back at the reader. + Assert.Equal(["ranked", "link"], record.Cards.Select(card => card.Via)); + Assert.Equal("analyst", record.Agent); + } - [Fact] - public async Task Create_ASearchThatThrew_WritesTheCauseTheModelNeverSees() - { - // In tool mode the framework replaces the message with "Error: Function failed.", and in - // prefetch mode this delegate answers a notice rather than throwing. Neither channel carries - // the cause, so an outage during a live conversation turns on this one line existing. - RecordingLoggerFactory loggers = new(); - InvalidOperationException down = new("qdrant is down"); - - var provider = KnowledgeProviderFactory.Create( - new ThrowingKnowledgePort(down), Resolved(KnowledgeMode.Prefetch), "resolver", new SourceLocatorCitationFormatter(), loggers); - await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - var line = Assert.Single(loggers.Of(12)); - Assert.Equal(LogLevel.Error, line.Level); - Assert.Equal("resolver", line.Field("Agent")); - - // The cause travels as the log's own exception argument, which is where a structured sink - // stores a stack trace. Ruling 22 took the duplicate copy off the record's log view rather - // than write the same trace into a message field as well. - Assert.Same(down, line.Exception); - Assert.Contains("qdrant is down", line.Exception!.ToString(), StringComparison.Ordinal); - - var record = line.Field("Record"); - Assert.NotNull(record); - Assert.Equal("resolver", record.Agent); - } + [Fact] + public async Task Create_ASearchThatThrew_WritesTheCauseTheModelNeverSees() + { + // In tool mode the framework replaces the message with "Error: Function failed.", and in + // prefetch mode this delegate answers a notice rather than throwing. Neither channel carries + // the cause, so an outage during a live conversation turns on this one line existing. + RecordingLoggerFactory loggers = new(); + InvalidOperationException down = new("qdrant is down"); + + AIContextProvider provider = KnowledgeProviderFactory.Create( + new ThrowingKnowledgePort(down), Resolved(KnowledgeMode.Prefetch), "resolver", new SourceLocatorCitationFormatter(), loggers); + _ = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + CapturedLine line = Assert.Single(loggers.Of(12)); + Assert.Equal(LogLevel.Error, line.Level); + Assert.Equal("resolver", line.Field("Agent")); + + // The cause travels as the log's own exception argument, which is where a structured sink + // stores a stack trace. Ruling 22 took the duplicate copy off the record's log view rather + // than write the same trace into a message field as well. + Assert.Same(down, line.Exception); + Assert.Contains("qdrant is down", line.Exception!.ToString(), StringComparison.Ordinal); + + KnowledgeAuditRecord.LogView? record = line.Field("Record"); + Assert.NotNull(record); + Assert.Equal("resolver", record.Agent); + } - [Fact] - public async Task Create_NeitherLoggedRow_CarriesWhatTheCallerSaid() - { - // Ruling 22, and a regression this branch introduced. Query is the framework-composed search - // input: the caller's current utterance plus, at RecentMessageMemoryLimit = 4, up to four - // earlier messages. The failure row is an Error, which a default production configuration - // keeps on, so logging the record whole copied every caller's words into a log store once per - // agent per turn for as long as an outage lasted -- the exact thing Log.PromptRefused and - // Log.ReplyTruncated refuse a few lines apart in the same file. - const string spoken = "my ct900 shows e33 and my name is jane quimby on account 40771"; - - RecordingLoggerFactory loggers = new(); - - var answered = KnowledgeProviderFactory.Create( - new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch), "analyst", new SourceLocatorCitationFormatter(), loggers); - await InvokePrefetchAsync(answered, spoken, PrefetchTurn(), new StubSession()); - - var threw = KnowledgeProviderFactory.Create( - new ThrowingKnowledgePort(new InvalidOperationException("qdrant is down")), - Resolved(KnowledgeMode.Prefetch), - "resolver", - new SourceLocatorCitationFormatter(), - loggers); - await InvokePrefetchAsync(threw, spoken, PrefetchTurn(), new StubSession()); - - // Both rows were written -- a test that logged nothing would pass the assertions below - // vacuously, and this is exactly the fact that must not pass vacuously. - Assert.Single(loggers.Of(11)); - Assert.Single(loggers.Of(12)); - - foreach (var line in loggers.Lines) - { - // The formatted text AND every structured field: a sink reads the fields, not the string. - Assert.DoesNotContain(spoken, line.Message, StringComparison.Ordinal); - Assert.DoesNotContain(spoken, line.Exception?.ToString() ?? string.Empty, StringComparison.Ordinal); - - foreach (var field in line.Fields) + [Fact] + public async Task Create_NeitherLoggedRow_CarriesWhatTheCallerSaid() + { + // Ruling 22, and a regression this branch introduced. Query is the framework-composed search + // input: the caller's current utterance plus, at RecentMessageMemoryLimit = 4, up to four + // earlier messages. The failure row is an Error, which a default production configuration + // keeps on, so logging the record whole copied every caller's words into a log store once per + // agent per turn for as long as an outage lasted -- the exact thing Log.PromptRefused and + // Log.ReplyTruncated refuse a few lines apart in the same file. + const string spoken = "my ct900 shows e33 and my name is jane quimby on account 40771"; + + RecordingLoggerFactory loggers = new(); + + AIContextProvider answered = KnowledgeProviderFactory.Create( + new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch), "analyst", new SourceLocatorCitationFormatter(), loggers); + _ = await InvokePrefetchAsync(answered, spoken, PrefetchTurn(), new StubSession()); + + AIContextProvider threw = KnowledgeProviderFactory.Create( + new ThrowingKnowledgePort(new InvalidOperationException("qdrant is down")), + Resolved(KnowledgeMode.Prefetch), + "resolver", + new SourceLocatorCitationFormatter(), + loggers); + _ = await InvokePrefetchAsync(threw, spoken, PrefetchTurn(), new StubSession()); + + // Both rows were written -- a test that logged nothing would pass the assertions below + // vacuously, and this is exactly the fact that must not pass vacuously. + _ = Assert.Single(loggers.Of(11)); + _ = Assert.Single(loggers.Of(12)); + + foreach (CapturedLine line in loggers.Lines) { - Assert.DoesNotContain( - spoken, field.Value?.ToString() ?? string.Empty, StringComparison.Ordinal); + // The formatted text AND every structured field: a sink reads the fields, not the string. + Assert.DoesNotContain(spoken, line.Message, StringComparison.Ordinal); + Assert.DoesNotContain(spoken, line.Exception?.ToString() ?? string.Empty, StringComparison.Ordinal); + + foreach (KeyValuePair field in line.Fields) + { + Assert.DoesNotContain( + spoken, field.Value?.ToString() ?? string.Empty, StringComparison.Ordinal); + } } } - } - [Fact] - public async Task Create_TheLoggedRow_CarriesTheQuerysLengthInstead() - { - // What replaces the text, and why a length rather than a hash: an outage is diagnosed by - // whether the input was well formed. A zero-length query is a provider bug and a runaway one - // is the recent-message concatenation gone wrong; a length answers both, and a hash answers - // only "the same text again" while still being a per-caller correlation handle. - const string spoken = "the screen says e33"; - - RecordingLoggerFactory loggers = new(); - - var provider = KnowledgeProviderFactory.Create( - new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch), "analyst", new SourceLocatorCitationFormatter(), loggers); - await InvokePrefetchAsync(provider, spoken, PrefetchTurn(), new StubSession()); - - var view = Assert.Single(loggers.Of(11)).Field("Record"); - Assert.NotNull(view); - Assert.Equal(spoken.Length, view.QueryLength); - Assert.Equal("analyst", view.Agent); - Assert.Equal(KnowledgeMode.Prefetch, view.Mode); - } + [Fact] + public async Task Create_TheLoggedRow_CarriesTheQuerysLengthInstead() + { + // What replaces the text, and why a length rather than a hash: an outage is diagnosed by + // whether the input was well formed. A zero-length query is a provider bug and a runaway one + // is the recent-message concatenation gone wrong; a length answers both, and a hash answers + // only "the same text again" while still being a per-caller correlation handle. + const string spoken = "the screen says e33"; + + RecordingLoggerFactory loggers = new(); + + AIContextProvider provider = KnowledgeProviderFactory.Create( + new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch), "analyst", new SourceLocatorCitationFormatter(), loggers); + _ = await InvokePrefetchAsync(provider, spoken, PrefetchTurn(), new StubSession()); + + KnowledgeAuditRecord.LogView? view = Assert.Single(loggers.Of(11)).Field("Record"); + Assert.NotNull(view); + Assert.Equal(spoken.Length, view.QueryLength); + Assert.Equal("analyst", view.Agent); + Assert.Equal(KnowledgeMode.Prefetch, view.Mode); + } - [Theory] - [InlineData(2, "card b", "card c")] - [InlineData(3, "card c", "card d")] - public async Task Create_MoreCardsThanTheAgentAsksFor_KeepsTheBestFew( - int limit, string lastKept, string firstDropped) - { - // Ruling 14(c). The store fetches once, up to its own deployment ceiling, for every agent. - // limit: is this agent's view of that fetch, and the port returns cards best first. - // Two limits, because one cannot tell the agent's limit from a hardcoded number. - var port = new StubKnowledgePort([Card("a"), Card("b"), Card("c"), Card("d"), Card("e")]); - - var provider = Provider( - port, Resolved(KnowledgeMode.Prefetch, limit: limit)); - var context = await InvokePrefetchAsync( - provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - var text = Merged(context); - Assert.Contains("card a", text, StringComparison.Ordinal); - Assert.Contains(lastKept, text, StringComparison.Ordinal); - Assert.DoesNotContain(firstDropped, text, StringComparison.Ordinal); - Assert.DoesNotContain("card e", text, StringComparison.Ordinal); - } + [Theory] + [InlineData(2, "card b", "card c")] + [InlineData(3, "card c", "card d")] + public async Task Create_MoreCardsThanTheAgentAsksFor_KeepsTheBestFew( + int limit, string lastKept, string firstDropped) + { + // Ruling 14(c). The store fetches once, up to its own deployment ceiling, for every agent. + // limit: is this agent's view of that fetch, and the port returns cards best first. + // Two limits, because one cannot tell the agent's limit from a hardcoded number. + StubKnowledgePort port = new([Card("a"), Card("b"), Card("c"), Card("d"), Card("e")]); + + AIContextProvider provider = Provider( + port, Resolved(KnowledgeMode.Prefetch, limit: limit)); + AIContext context = await InvokePrefetchAsync( + provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + string text = Merged(context); + Assert.Contains("card a", text, StringComparison.Ordinal); + Assert.Contains(lastKept, text, StringComparison.Ordinal); + Assert.DoesNotContain(firstDropped, text, StringComparison.Ordinal); + Assert.DoesNotContain("card e", text, StringComparison.Ordinal); + } - [Fact] - public async Task Create_TheLimit_CountsRankedCardsAndLetsALinkedOneRideAlong() - { - // Ruling 16. A7 makes see_also expansion never optional, and the store appends the linked - // cards after every scored one. A plain prefix would drop every link whenever the fetch - // filled up -- which, at the shipped defaults of 5 and 5, is every full result. The winning - // probe arm was "top 5 plus see_also of the top hit": the links are additional to the five. - var port = new StubKnowledgePort([Card("a"), Card("b"), Card("c"), Linked("z")]); - - var provider = Provider( - port, Resolved(KnowledgeMode.Prefetch, limit: 2)); - var context = await InvokePrefetchAsync( - provider, "the screen says e33", PrefetchTurn(), new StubSession()); - - var text = Merged(context); - Assert.Contains("card a", text, StringComparison.Ordinal); - Assert.Contains("card b", text, StringComparison.Ordinal); - Assert.DoesNotContain("card c", text, StringComparison.Ordinal); - Assert.Contains("card z", text, StringComparison.Ordinal); - } + [Fact] + public async Task Create_TheLimit_CountsRankedCardsAndLetsALinkedOneRideAlong() + { + // Ruling 16. A7 makes see_also expansion never optional, and the store appends the linked + // cards after every scored one. A plain prefix would drop every link whenever the fetch + // filled up -- which, at the shipped defaults of 5 and 5, is every full result. The winning + // probe arm was "top 5 plus see_also of the top hit": the links are additional to the five. + StubKnowledgePort port = new([Card("a"), Card("b"), Card("c"), Linked("z")]); + + AIContextProvider provider = Provider( + port, Resolved(KnowledgeMode.Prefetch, limit: 2)); + AIContext context = await InvokePrefetchAsync( + provider, "the screen says e33", PrefetchTurn(), new StubSession()); + + string text = Merged(context); + Assert.Contains("card a", text, StringComparison.Ordinal); + Assert.Contains("card b", text, StringComparison.Ordinal); + Assert.DoesNotContain("card c", text, StringComparison.Ordinal); + Assert.Contains("card z", text, StringComparison.Ordinal); + } - [Fact] - public async Task Create_CitationsOff_AsksForNoCitationAtAll() - { - // A null CitationsPrompt is not "off": it produces the framework's own default block, - // which asks for a document name and link, and there is never a link. - var provider = Provider( - new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch, citations: false)); + [Fact] + public async Task Create_CitationsOff_AsksForNoCitationAtAll() + { + // A null CitationsPrompt is not "off": it produces the framework's own default block, + // which asks for a document name and link, and there is never a link. + AIContextProvider provider = Provider( + new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch, citations: false)); - var context = await InvokePrefetchAsync( - provider, "the screen says e33", PrefetchTurn(), new StubSession()); + AIContext context = await InvokePrefetchAsync( + provider, "the screen says e33", PrefetchTurn(), new StubSession()); - var text = Merged(context); - Assert.DoesNotContain("Include citations", text, StringComparison.Ordinal); - Assert.DoesNotContain("ct900-om", text, StringComparison.Ordinal); - } + string text = Merged(context); + Assert.DoesNotContain("Include citations", text, StringComparison.Ordinal); + Assert.DoesNotContain("ct900-om", text, StringComparison.Ordinal); + } - [Fact] - public async Task Create_CitationsOn_NamesTheSourceAndForbidsAnInventedLink() - { - var provider = Provider( - new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch, citations: true)); + [Fact] + public async Task Create_CitationsOn_NamesTheSourceAndForbidsAnInventedLink() + { + AIContextProvider provider = Provider( + new StubKnowledgePort([Card("a")]), Resolved(KnowledgeMode.Prefetch, citations: true)); - var context = await InvokePrefetchAsync( - provider, "the screen says e33", PrefetchTurn(), new StubSession()); + AIContext context = await InvokePrefetchAsync( + provider, "the screen says e33", PrefetchTurn(), new StubSession()); - var text = Merged(context); - Assert.Contains("ct900-om, p.27", text, StringComparison.Ordinal); - Assert.DoesNotContain("Include citations", text, StringComparison.Ordinal); - Assert.Contains("Do not invent a link", text, StringComparison.Ordinal); - } + string text = Merged(context); + Assert.Contains("ct900-om, p.27", text, StringComparison.Ordinal); + Assert.DoesNotContain("Include citations", text, StringComparison.Ordinal); + Assert.Contains("Do not invent a link", text, StringComparison.Ordinal); + } - [Fact] - public async Task Create_CitationsOn_PublishesASourceForEachCardShown() - { - // Task 5 fix round 1, Finding 1. Nothing in this suite drove the sources port to a - // non-null value for a citing search before this test, so the body of the publish loop had - // never executed. A collector plus an outer call, both open around the same InvokingAsync - // the other tests already drive, is what proves the wiring rather than just reading it. - var port = new StubKnowledgePort([Card("a"), Card("b")]); - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, citations: true)); + [Fact] + public async Task Create_CitationsOn_PublishesASourceForEachCardShown() + { + // Task 5 fix round 1, Finding 1. Nothing in this suite drove the sources port to a + // non-null value for a citing search before this test, so the body of the publish loop had + // never executed. A collector plus an outer call, both open around the same InvokingAsync + // the other tests already drive, is what proves the wiring rather than just reading it. + StubKnowledgePort port = new([Card("a"), Card("b")]); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, citations: true)); + + TurnSources sources = new(); + + StubSession session = new(); + TurnRegistry.Set(session, PrefetchTurn(sources: sources)); + using (sources.BeginOuterCall("conversation-1")) + { + _ = await provider.InvokingAsync( + Invoking("the screen says e33", session), TestContext.Current.CancellationToken); + } - TurnSources sources = new(); + IReadOnlyList cited = sources.TakeFor("conversation-1"); + Assert.Equal(2, cited.Count); + Assert.Equal( + ["a", "b"], cited.Select(content => content.Source.SourceId).OrderBy(id => id)); + Assert.All(cited, content => Assert.Equal("ct900-om, p.27", content.Source.Title)); + } - StubSession session = new(); - TurnRegistry.Set(session, PrefetchTurn(sources: sources)); - using (sources.BeginOuterCall("conversation-1")) + [Fact] + public async Task Create_CitationsOff_PublishesNothing() { - await provider.InvokingAsync( - Invoking("the screen says e33", session), TestContext.Current.CancellationToken); + // The leak test, and the most important one in this task. citations: false is the single + // switch a deployment uses to decide whether it discloses its sources at all -- a chip on + // screen is a disclosure just as much as the label the model is shown -- so this must + // publish nothing even with a collector and an outer call both open and cards coming back. + StubKnowledgePort port = new([Card("a"), Card("b")]); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, citations: false)); + + TurnSources sources = new(); + + StubSession session = new(); + TurnRegistry.Set(session, PrefetchTurn(sources: sources)); + using (sources.BeginOuterCall("conversation-1")) + { + _ = await provider.InvokingAsync( + Invoking("the screen says e33", session), TestContext.Current.CancellationToken); + } + + Assert.Empty(sources.TakeFor("conversation-1")); } - var cited = sources.TakeFor("conversation-1"); - Assert.Equal(2, cited.Count); - Assert.Equal( - ["a", "b"], cited.Select(content => content.Source.SourceId).OrderBy(id => id)); - Assert.All(cited, content => Assert.Equal("ct900-om, p.27", content.Source.Title)); - } + [Fact] + public async Task Create_MoreCardsThanTheLimit_CitesOnlyTheCardsTheModelIsShown() + { + // Finding 2. A card ranked past the agent's limit: is never shown to the model, so citing + // it anyway would put a chip on screen for a document the answer could not possibly have + // drawn on. The cited set must match the kept set, not the store's full return. + StubKnowledgePort port = new([Card("a"), Card("b"), Card("c"), Card("d"), Card("e")]); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch, limit: 2, citations: true)); - [Fact] - public async Task Create_CitationsOff_PublishesNothing() - { - // The leak test, and the most important one in this task. citations: false is the single - // switch a deployment uses to decide whether it discloses its sources at all -- a chip on - // screen is a disclosure just as much as the label the model is shown -- so this must - // publish nothing even with a collector and an outer call both open and cards coming back. - var port = new StubKnowledgePort([Card("a"), Card("b")]); - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, citations: false)); + TurnSources sources = new(); + + StubSession session = new(); + TurnRegistry.Set(session, PrefetchTurn(sources: sources)); + using (sources.BeginOuterCall("conversation-1")) + { + _ = await provider.InvokingAsync( + Invoking("the screen says e33", session), TestContext.Current.CancellationToken); + } - TurnSources sources = new(); + IReadOnlyList cited = sources.TakeFor("conversation-1"); + Assert.Equal(2, cited.Count); + Assert.Equal( + ["a", "b"], cited.Select(content => content.Source.SourceId).OrderBy(id => id)); + } - StubSession session = new(); - TurnRegistry.Set(session, PrefetchTurn(sources: sources)); - using (sources.BeginOuterCall("conversation-1")) + [Fact] + public async Task Create_WhatAnEarlierProviderInjected_IsNotPartOfTheQuery() { - await provider.InvokingAsync( - Invoking("the screen says e33", session), TestContext.Current.CancellationToken); - } + // The knowledge provider is bound second, after TurnContextProvider, and the framework + // hands each provider what the one before it produced. The turn's own instructions are not + // a query, and a search over them retrieves the wrong cards. + StubKnowledgePort port = new([]); + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch)); + StubSession session = new(); + TurnRegistry.Set(session, PrefetchTurn()); - Assert.Empty(sources.TakeFor("conversation-1")); - } +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + AIContextProvider.InvokingContext context = new( + StubAgent.Instance, + session, + new AIContext + { + Messages = + [ + new ChatMessage(ChatRole.User, "the screen says e33"), + new ChatMessage(ChatRole.System, "ask the caller for the machine model") + .WithAgentRequestMessageSource( + AgentRequestMessageSourceType.AIContextProvider, "TurnContextProvider"), + ], + }); +#pragma warning restore MAAI001 - [Fact] - public async Task Create_MoreCardsThanTheLimit_CitesOnlyTheCardsTheModelIsShown() - { - // Finding 2. A card ranked past the agent's limit: is never shown to the model, so citing - // it anyway would put a chip on screen for a document the answer could not possibly have - // drawn on. The cited set must match the kept set, not the store's full return. - var port = new StubKnowledgePort([Card("a"), Card("b"), Card("c"), Card("d"), Card("e")]); - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch, limit: 2, citations: true)); + _ = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - TurnSources sources = new(); + Assert.Equal("the screen says e33", port.LastQuery); + } - StubSession session = new(); - TurnRegistry.Set(session, PrefetchTurn(sources: sources)); - using (sources.BeginOuterCall("conversation-1")) + [Fact] + public async Task Create_ASecondTurn_SearchesWithWhatTheCallerSaidBefore() { - await provider.InvokingAsync( + // RecentMessageMemoryLimit defaults to 0, and at 0 turn two's query is the bare new + // message: "does it need a part?" resolves its pronoun against nothing. + StubKnowledgePort port = new([Card("a")]); + StubSession session = new(); + + AIContextProvider provider = Provider(port, Resolved(KnowledgeMode.Prefetch)); + TurnRegistry.Set(session, PrefetchTurn()); + _ = await provider.InvokingAsync( Invoking("the screen says e33", session), TestContext.Current.CancellationToken); + await provider.InvokedAsync( + Invoked("the screen says e33", session), TestContext.Current.CancellationToken); + _ = await provider.InvokingAsync( + Invoking("does it need a part?", session), TestContext.Current.CancellationToken); + + Assert.Contains("the screen says e33", port.LastQuery!, StringComparison.Ordinal); + Assert.Contains("does it need a part?", port.LastQuery!, StringComparison.Ordinal); } - var cited = sources.TakeFor("conversation-1"); - Assert.Equal(2, cited.Count); - Assert.Equal( - ["a", "b"], cited.Select(content => content.Source.SourceId).OrderBy(id => id)); - } + [Fact] + public async Task Search_ToolModeWithNoResults_InjectsTheEmptyNotice() + { + AIContextProvider provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: true)); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - [Fact] - public async Task Create_WhatAnEarlierProviderInjected_IsNotPartOfTheQuery() - { - // The knowledge provider is bound second, after TurnContextProvider, and the framework - // hands each provider what the one before it produced. The turn's own instructions are not - // a query, and a search over them retrieves the wrong cards. - var port = new StubKnowledgePort([]); - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch)); - StubSession session = new(); - TurnRegistry.Set(session, PrefetchTurn()); + IReadOnlyList results = await InvokeSearchAsync(provider, "f63 error e03", ToolTurn(scope)); -#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new( - StubAgent.Instance, - session, - new AIContext - { - Messages = - [ - new ChatMessage(ChatRole.User, "the screen says e33"), - new ChatMessage(ChatRole.System, "ask the caller for the machine model") - .WithAgentRequestMessageSource( - AgentRequestMessageSourceType.AIContextProvider, "TurnContextProvider"), - ], - }); -#pragma warning restore MAAI001 + Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); + } - await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + [Fact] + public async Task Search_PrefetchModeWithNoResults_InjectsNothing() + { + AIContextProvider provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch)); - Assert.Equal("the screen says e33", port.LastQuery); - } + AIContext context = await InvokePrefetchAsync(provider, "hello", PrefetchTurn(), new StubSession()); - [Fact] - public async Task Create_ASecondTurn_SearchesWithWhatTheCallerSaidBefore() - { - // RecentMessageMemoryLimit defaults to 0, and at 0 turn two's query is the bare new - // message: "does it need a part?" resolves its pronoun against nothing. - var port = new StubKnowledgePort([Card("a")]); - StubSession session = new(); - - var provider = Provider(port, Resolved(KnowledgeMode.Prefetch)); - TurnRegistry.Set(session, PrefetchTurn()); - await provider.InvokingAsync( - Invoking("the screen says e33", session), TestContext.Current.CancellationToken); - await provider.InvokedAsync( - Invoked("the screen says e33", session), TestContext.Current.CancellationToken); - await provider.InvokingAsync( - Invoking("does it need a part?", session), TestContext.Current.CancellationToken); - - Assert.Contains("the screen says e33", port.LastQuery!, StringComparison.Ordinal); - Assert.Contains("does it need a part?", port.LastQuery!, StringComparison.Ordinal); - } + Assert.Equal(["hello"], Texts(context)); + } - [Fact] - public async Task Search_ToolModeWithNoResults_InjectsTheEmptyNotice() - { - var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: true)); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + [Fact] + public async Task Search_ScopedPrefetchModeWithNoResults_InjectsNothing() + { + // Both halves of the notice guard matter. A scoped agent with a real facet open already + // clears the Facets.Count > 0 half, so only the KnowledgeMode.Tool clause keeps a prefetch + // agent's empty search silent. + AIContextProvider provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch, scoped: true)); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - var results = await InvokeSearchAsync(provider, "f63 error e03", ToolTurn(scope)); + AIContext context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); - Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); - } + Assert.Equal(["the screen says e33"], Texts(context)); + } - [Fact] - public async Task Search_PrefetchModeWithNoResults_InjectsNothing() - { - var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch)); + [Fact] + public async Task Search_UnscopedToolModeWithNoResults_InjectsNothing() + { + // scoped: false opens WholeCorpus, which holds no facets. Such an agent's empty search stays + // byte-identical to an unscoped one: an empty list, no notice. + AIContextProvider provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: false)); - var context = await InvokePrefetchAsync(provider, "hello", PrefetchTurn(), new StubSession()); + IReadOnlyList results = await InvokeSearchAsync(provider, "f63 error e03", ToolTurn()); - Assert.Equal(["hello"], Texts(context)); - } + Assert.Empty(results); + } - [Fact] - public async Task Search_ScopedPrefetchModeWithNoResults_InjectsNothing() - { - // Both halves of the notice guard matter. A scoped agent with a real facet open already - // clears the Facets.Count > 0 half, so only the KnowledgeMode.Tool clause keeps a prefetch - // agent's empty search silent. - var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch, scoped: true)); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + [Fact] + public async Task Search_EveryNotice_CarriesTheReservedSourceName() + { + // A notice must never be citable as a card, and the reserved source name is what stops it. + AIContextProvider provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: true)); + KnowledgeScope scope = new() { Facets = new Dictionary { ["model"] = "ct900" } }; - var context = await InvokePrefetchAsync(provider, "the screen says e33", PrefetchTurn(scope), new StubSession()); + IReadOnlyList results = await InvokeSearchAsync(provider, "f63 error e03", ToolTurn(scope)); - Assert.Equal(["the screen says e33"], Texts(context)); - } + Assert.All(results, r => Assert.Equal("agentcore:notice", r.SourceName)); + } - [Fact] - public async Task Search_UnscopedToolModeWithNoResults_InjectsNothing() - { - // scoped: false opens WholeCorpus, which holds no facets. Such an agent's empty search stays - // byte-identical to an unscoped one: an empty list, no notice. - var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: false)); + [Fact] + public async Task Search_ToolModeThatThrows_StillSaysUnreachable() + { + AIContextProvider provider = Provider( + new ThrowingKnowledgePort(new InvalidOperationException("boom")), Resolved(KnowledgeMode.Tool)); - var results = await InvokeSearchAsync(provider, "f63 error e03", ToolTurn()); + IReadOnlyList results = await InvokeSearchAsync(provider, "f63", ToolTurn()); - Assert.Empty(results); - } + Assert.Contains(results, r => r.Text.Contains("unreachable", StringComparison.Ordinal)); + } - [Fact] - public async Task Search_EveryNotice_CarriesTheReservedSourceName() - { - // A notice must never be citable as a card, and the reserved source name is what stops it. - var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: true)); - var scope = new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }; + /// Builds the provider under test, with the agent id and logger these facts do not read. + /// The store the provider searches. + /// The agent's resolved knowledge: block. + /// The provider. + private static TurnInvocation PrefetchTurn(KnowledgeScope? scope = null, TurnSources? sources = null) + { + return new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Knowledge = scope, + Sources = sources, + }; + } - var results = await InvokeSearchAsync(provider, "f63 error e03", ToolTurn(scope)); + private static TurnInvocation ToolTurn( + KnowledgeScope? scope = null, Clarifications? clarifications = null, TurnSources? sources = null) + { + return new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Knowledge = scope, + Clarifications = clarifications ?? new Clarifications(), + Sources = sources, + }; + } - Assert.All(results, r => Assert.Equal("agentcore:notice", r.SourceName)); - } + private static async Task InvokePrefetchAsync( + AIContextProvider provider, string text, TurnInvocation turn, AgentSession session) + { + TurnRegistry.Set(session, turn); + return await provider.InvokingAsync( + Invoking(text, session), TestContext.Current.CancellationToken).ConfigureAwait(false); + } - [Fact] - public async Task Search_ToolModeThatThrows_StillSaysUnreachable() - { - var provider = Provider( - new ThrowingKnowledgePort(new InvalidOperationException("boom")), Resolved(KnowledgeMode.Tool)); + private static AIContextProvider Provider(IKnowledgeRetrievalPort port, ResolvedKnowledge knowledge) + { + return KnowledgeProviderFactory.Create( + port, knowledge, "agent-under-test", new SourceLocatorCitationFormatter(), loggers: null); + } - var results = await InvokeSearchAsync(provider, "f63", ToolTurn()); + /// + /// Invokes the search tool the provider offers, the way the model would: the turn rides along + /// as an argument, carrying the scope and the clarifications the search runs under. + /// + /// The provider built. + /// The search text. + /// The turn the search runs under. + /// What the search returned. + private static async Task> InvokeSearchAsync( + AIContextProvider provider, string query, TurnInvocation turn) + { + StubSession session = new(); + AIContext context = await provider.InvokingAsync( + Invoking("hello", session), TestContext.Current.CancellationToken).ConfigureAwait(false); + AITool search = Assert.Single(context.Tools!, tool => tool.Name == "Search"); + IReadOnlyList? results = await ((AIFunction)search).InvokeAsync( + turn.FileIn(new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) + { + ["userQuestion"] = query, + })), + TestContext.Current.CancellationToken).ConfigureAwait(false) + as IReadOnlyList; + return results!; + } - Assert.Contains(results, r => r.Text.Contains("unreachable", StringComparison.Ordinal)); - } + /// Every message text of a returned context, in one string. + private static string Merged(AIContext context) + { + return string.Join('\n', Texts(context)); + } - /// Builds the provider under test, with the agent id and logger these facts do not read. - /// The store the provider searches. - /// The agent's resolved knowledge: block. - /// The provider. - private static TurnInvocation PrefetchTurn(KnowledgeScope? scope = null, TurnSources? sources = null) => new() - { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Knowledge = scope, - Sources = sources, - }; - - private static TurnInvocation ToolTurn( - KnowledgeScope? scope = null, Clarifications? clarifications = null, TurnSources? sources = null) => new() - { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Knowledge = scope, - Clarifications = clarifications ?? new Clarifications(), - Sources = sources, - }; - - private static async Task InvokePrefetchAsync( - AIContextProvider provider, string text, TurnInvocation turn, AgentSession session) - { - TurnRegistry.Set(session, turn); - return await provider.InvokingAsync( - Invoking(text, session), TestContext.Current.CancellationToken).ConfigureAwait(false); - } + private static IEnumerable Texts(AIContext context) + { + return (context.Messages ?? []).Select(message => message.Text); + } - private static AIContextProvider Provider(IKnowledgeRetrievalPort port, ResolvedKnowledge knowledge) - => KnowledgeProviderFactory.Create( - port, knowledge, "agent-under-test", new SourceLocatorCitationFormatter(), loggers: null); + private static ResolvedKnowledge Resolved( + KnowledgeMode mode, int limit = 5, bool citations = false, bool scoped = false) + { + return new(mode, limit, citations, scoped); + } - /// - /// Invokes the search tool the provider offers, the way the model would: the turn rides along - /// as an argument, carrying the scope and the clarifications the search runs under. - /// - /// The provider built. - /// The search text. - /// The turn the search runs under. - /// What the search returned. - private static async Task> InvokeSearchAsync( - AIContextProvider provider, string query, TurnInvocation turn) - { - StubSession session = new(); - var context = await provider.InvokingAsync( - Invoking("hello", session), TestContext.Current.CancellationToken).ConfigureAwait(false); - var search = Assert.Single(context.Tools!, tool => tool.Name == "Search"); - var results = await ((AIFunction)search).InvokeAsync( - turn.FileIn(new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) + /// The facet map one card of the scope-filtering corpus carries. + private static Dictionary Facets(string model) + { + return new(StringComparer.Ordinal) { ["model"] = model }; + } + + private static KnowledgeCard Card(string id) + { + return new() { - ["userQuestion"] = query, - })), - TestContext.Current.CancellationToken).ConfigureAwait(false) - as IReadOnlyList; - return results!; - } + CardId = id, + Text = "card " + id, + Authority = 3, + SourceRef = "ct900-om", + SourceLocator = "p.27", + Score = 0.87, + ViaLink = false, + }; + } - /// Every message text of a returned context, in one string. - private static string Merged(AIContext context) - => string.Join('\n', Texts(context)); + /// A card see_also pulled in. The store appends these after every scored card. + private static KnowledgeCard Linked(string id) + { + return Card(id) with { Score = null, ViaLink = true }; + } - private static IEnumerable Texts(AIContext context) - => (context.Messages ?? []).Select(message => message.Text); + /// Runs the provider the way the framework runs it, over one caller message. + private static AIContextProvider.InvokingContext Invoking(string text, AgentSession session) + { +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + return new( + StubAgent.Instance, + session, + new AIContext { Messages = [new ChatMessage(ChatRole.User, text)] }); +#pragma warning restore MAAI001 + } - private static ResolvedKnowledge Resolved( - KnowledgeMode mode, int limit = 5, bool citations = false, bool scoped = false) - => new(mode, limit, citations, scoped); + /// Closes a turn, so the provider stores what it should remember of it. + private static AIContextProvider.InvokedContext Invoked(string text, AgentSession session) + { +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + return new( + StubAgent.Instance, + session, + [new ChatMessage(ChatRole.User, text)], + [new ChatMessage(ChatRole.Assistant, "let me look")]); +#pragma warning restore MAAI001 + } - /// The facet map one card of the scope-filtering corpus carries. - private static Dictionary Facets(string model) - => new(StringComparer.Ordinal) { ["model"] = model }; + private sealed class StubSession : AgentSession; - private static KnowledgeCard Card(string id) - => new() + /// Stands in for the agent the framework names on a context. Nothing here runs it. + private sealed class StubAgent : AIAgent { - CardId = id, - Text = "card " + id, - Authority = 3, - SourceRef = "ct900-om", - SourceLocator = "p.27", - Score = 0.87, - ViaLink = false, - }; + public static StubAgent Instance { get; } = new(); - /// A card see_also pulled in. The store appends these after every scored card. - private static KnowledgeCard Linked(string id) - => Card(id) with { Score = null, ViaLink = true }; + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) + { + return new(new StubSession()); + } - /// Runs the provider the way the framework runs it, over one caller message. - private static AIContextProvider.InvokingContext Invoking(string text, AgentSession session) - { -#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - return new( - StubAgent.Instance, - session, - new AIContext { Messages = [new ChatMessage(ChatRole.User, text)] }); -#pragma warning restore MAAI001 - } + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - /// Closes a turn, so the provider stores what it should remember of it. - private static AIContextProvider.InvokedContext Invoked(string text, AgentSession session) - { -#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - return new( - StubAgent.Instance, - session, - [new ChatMessage(ChatRole.User, text)], - [new ChatMessage(ChatRole.Assistant, "let me look")]); -#pragma warning restore MAAI001 - } + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - private sealed class StubSession : AgentSession; + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - /// Stands in for the agent the framework names on a context. Nothing here runs it. - private sealed class StubAgent : AIAgent - { - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeQueryAnalyzerTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeQueryAnalyzerTests.cs index abcda49a..57c9f1e6 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeQueryAnalyzerTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeQueryAnalyzerTests.cs @@ -1,20 +1,28 @@ using AgentCore.Application.Knowledge; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -public sealed class NoQueryAnalyzerTests +namespace AgentCore.Application.Tests.Knowledge { - private static readonly NoQueryAnalyzer Analyzer = new(); + public sealed class NoQueryAnalyzerTests + { + private static readonly NoQueryAnalyzer Analyzer = new(); - [Fact] - public void Name_IsTheConfigurationValue() => Assert.Equal("none", Analyzer.Name); + [Fact] + public void Name_IsTheConfigurationValue() + { + Assert.Equal("none", Analyzer.Name); + } - [Fact] - public void RequiredTerms_AlwaysEmpty() - => Assert.Empty(Analyzer.RequiredTerms("the screen says e33")); + [Fact] + public void RequiredTerms_AlwaysEmpty() + { + Assert.Empty(Analyzer.RequiredTerms("the screen says e33")); + } - [Fact] - public void RequiredTerms_Null_Throws() - => Assert.Throws(() => Analyzer.RequiredTerms(null!)); + [Fact] + public void RequiredTerms_Null_Throws() + { + _ = Assert.Throws(() => Analyzer.RequiredTerms(null!)); + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeSourceMapperTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeSourceMapperTests.cs index 220df6d8..80687d0e 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeSourceMapperTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeSourceMapperTests.cs @@ -3,61 +3,65 @@ using AgentCore.Domain.Sources; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// The one place a card becomes the chip the caller sees. -/// -/// -/// The title is the same label the model was shown. Two wordings of one citation — one for the -/// model, another for the screen — is a way for the two to disagree in front of a customer, so -/// there is one formatter and this reads it. -/// -public sealed class KnowledgeSourceMapperTests +namespace AgentCore.Application.Tests.Knowledge { - private static readonly IKnowledgeCitationFormatter Formatter = new SourceLocatorCitationFormatter(); - - [Fact] - public void ToSource_ReadsTheFormattersLabelAsTheTitle() + /// + /// The one place a card becomes the chip the caller sees. + /// + /// + /// The title is the same label the model was shown. Two wordings of one citation — one for the + /// model, another for the screen — is a way for the two to disagree in front of a customer, so + /// there is one formatter and this reads it. + /// + public sealed class KnowledgeSourceMapperTests { - var source = KnowledgeSourceMapper.ToSource(Card(), Formatter); - - Assert.NotNull(source); - Assert.Equal("ct900-om, p.27", source!.Title); - Assert.Equal("card-1", source.SourceId); - Assert.Equal(SourceKind.Document, source.Kind); - Assert.Equal("knowledge", source.Origin); - Assert.Equal("p.27", source.Locator); - Assert.Null(source.Url); - } + private static readonly IKnowledgeCitationFormatter Formatter = new SourceLocatorCitationFormatter(); - [Fact] - public void ToSource_ACardTheFormatterCitesNothingFor_IsNotACitation() - { - // A collection that maps neither source nor locator cites nothing. A chip reading "card-1" - // would show the caller an internal id and tell them nothing. - var card = Card() with { SourceRef = "", SourceLocator = "" }; + [Fact] + public void ToSource_ReadsTheFormattersLabelAsTheTitle() + { + SourceReference? source = KnowledgeSourceMapper.ToSource(Card(), Formatter); - Assert.Null(KnowledgeSourceMapper.ToSource(card, Formatter)); - } + Assert.NotNull(source); + Assert.Equal("ct900-om, p.27", source!.Title); + Assert.Equal("card-1", source.SourceId); + Assert.Equal(SourceKind.Document, source.Kind); + Assert.Equal("knowledge", source.Origin); + Assert.Equal("p.27", source.Locator); + Assert.Null(source.Url); + } - [Fact] - public void ToSource_NeverInventsALink() - { - // A card has no URL. SourceLocatorCitationFormatter's whole point is that a synthesised - // kb:// scheme would invite a click that goes nowhere. - var source = KnowledgeSourceMapper.ToSource(Card(), Formatter); + [Fact] + public void ToSource_ACardTheFormatterCitesNothingFor_IsNotACitation() + { + // A collection that maps neither source nor locator cites nothing. A chip reading "card-1" + // would show the caller an internal id and tell them nothing. + KnowledgeCard card = Card() with { SourceRef = "", SourceLocator = "" }; - Assert.Null(source!.Url); - Assert.Equal(SourceKind.Document, source.Kind); - } + Assert.Null(KnowledgeSourceMapper.ToSource(card, Formatter)); + } - private static KnowledgeCard Card() => new() - { - CardId = "card-1", - Text = "the body", - ViaLink = false, - SourceRef = "ct900-om", - SourceLocator = "p.27", - }; + [Fact] + public void ToSource_NeverInventsALink() + { + // A card has no URL. SourceLocatorCitationFormatter's whole point is that a synthesised + // kb:// scheme would invite a click that goes nowhere. + SourceReference? source = KnowledgeSourceMapper.ToSource(Card(), Formatter); + + Assert.Null(source!.Url); + Assert.Equal(SourceKind.Document, source.Kind); + } + + private static KnowledgeCard Card() + { + return new() + { + CardId = "card-1", + Text = "the body", + ViaLink = false, + SourceRef = "ct900-om", + SourceLocator = "p.27", + }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs b/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs index 5b46e7be..c43ceae5 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs @@ -5,111 +5,116 @@ using AgentCore.Domain.Knowledge; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -public sealed class StateKnowledgeScopeTests +namespace AgentCore.Application.Tests.Knowledge { - private static readonly KnowledgeScopeConfiguration Configured = new() - { - Template = "facets.{key}", - Wildcard = new() { Value = "*", Facets = ["brand", "applies_to"] }, - FromState = ["brand", "applies_to"], - }; - - private static StateDocument Document() + public sealed class StateKnowledgeScopeTests { - StateSlotConfiguration Slot(params string[] members) => new() + private static readonly KnowledgeScopeConfiguration Configured = new() { - Type = StateSlotType.String, - Writer = StateWriter.Extractor, - EnumValues = [.. members.Select(m => (JsonNode)JsonValue.Create(m)!)], + Template = "facets.{key}", + Wildcard = new() { Value = "*", Facets = ["brand", "applies_to"] }, + FromState = ["brand", "applies_to"], }; - return new StateDocument(new AgentCoreConfiguration + private static StateDocument Document() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - State = new Dictionary(StringComparer.Ordinal) + static StateSlotConfiguration Slot(params string[] members) { - ["brand"] = Slot("sole", "spirit"), - ["applies_to"] = Slot("f63", "f80"), - }, - }); - } - - [Fact] - public void Compose_NothingKnown_IsAllWildcard() - { - var scope = StateKnowledgeScope.Compose(Document(), Configured, hostScope: null); + return new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [.. members.Select(m => (JsonNode)JsonValue.Create(m)!)], + }; + } + + return new StateDocument(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + State = new Dictionary(StringComparer.Ordinal) + { + ["brand"] = Slot("sole", "spirit"), + ["applies_to"] = Slot("f63", "f80"), + }, + }); + } + + [Fact] + public void Compose_NothingKnown_IsAllWildcard() + { + KnowledgeScope? scope = StateKnowledgeScope.Compose(Document(), Configured, hostScope: null); - Assert.Equal("*", scope!.Facets["brand"]); - Assert.Equal("*", scope.Facets["applies_to"]); - } + Assert.Equal("*", scope!.Facets["brand"]); + Assert.Equal("*", scope.Facets["applies_to"]); + } - [Fact] - public void Compose_BrandKnown_LeavesTheMachineWildcard() - { - var state = Document(); - state.TryWrite("brand", JsonValue.Create("sole")); + [Fact] + public void Compose_BrandKnown_LeavesTheMachineWildcard() + { + StateDocument state = Document(); + _ = state.TryWrite("brand", JsonValue.Create("sole")); - var scope = StateKnowledgeScope.Compose(state, Configured, hostScope: null); + KnowledgeScope? scope = StateKnowledgeScope.Compose(state, Configured, hostScope: null); - Assert.Equal("sole", scope!.Facets["brand"]); - Assert.Equal("*", scope.Facets["applies_to"]); - } + Assert.Equal("sole", scope!.Facets["brand"]); + Assert.Equal("*", scope.Facets["applies_to"]); + } - [Fact] - public void Compose_HostAlreadySetTheKey_DoesNotOverwriteIt() - { - var state = Document(); - state.TryWrite("brand", JsonValue.Create("sole")); - KnowledgeScope host = new() + [Fact] + public void Compose_HostAlreadySetTheKey_DoesNotOverwriteIt() { - Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "spirit" }, - }; + StateDocument state = Document(); + _ = state.TryWrite("brand", JsonValue.Create("sole")); + KnowledgeScope host = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "spirit" }, + }; - var scope = StateKnowledgeScope.Compose(state, Configured, host); + KnowledgeScope? scope = StateKnowledgeScope.Compose(state, Configured, host); - Assert.Equal("spirit", scope!.Facets["brand"]); - } + Assert.Equal("spirit", scope!.Facets["brand"]); + } - [Fact] - public void Compose_NoFromState_ReturnsTheHostInstance() - { - KnowledgeScope host = new() + [Fact] + public void Compose_NoFromState_ReturnsTheHostInstance() { - Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "sole" }, - }; + KnowledgeScope host = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "sole" }, + }; - var scope = StateKnowledgeScope.Compose( - Document(), Configured with { FromState = [] }, host); + KnowledgeScope? scope = StateKnowledgeScope.Compose( + Document(), Configured with { FromState = [] }, host); - Assert.Same(host, scope); - } + Assert.Same(host, scope); + } - [Fact] - public void Compose_NoWildcard_ReturnsNull() - { - var scope = StateKnowledgeScope.Compose( - Document(), Configured with { Wildcard = null }, hostScope: null); + [Fact] + public void Compose_NoWildcard_ReturnsNull() + { + KnowledgeScope? scope = StateKnowledgeScope.Compose( + Document(), Configured with { Wildcard = null }, hostScope: null); - Assert.Null(scope); - } + Assert.Null(scope); + } - [Fact] - public void Compose_MarksEachFacetWithItsOrigin() - { - var state = Document(); - state.TryWrite("brand", JsonValue.Create("sole")); - KnowledgeScope ambient = new() + [Fact] + public void Compose_MarksEachFacetWithItsOrigin() { - Facets = new Dictionary(StringComparer.Ordinal) { ["region"] = "uk" }, - }; + StateDocument state = Document(); + _ = state.TryWrite("brand", JsonValue.Create("sole")); + KnowledgeScope ambient = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["region"] = "uk" }, + }; - var scope = StateKnowledgeScope.Compose(state, Configured, ambient)!; + KnowledgeScope scope = StateKnowledgeScope.Compose(state, Configured, ambient)!; - Assert.Equal(KnowledgeFacetOrigin.Host, scope.Origins["region"]); - Assert.Equal(KnowledgeFacetOrigin.Extractor, scope.Origins["brand"]); - Assert.Equal(KnowledgeFacetOrigin.Wildcard, scope.Origins["applies_to"]); + Assert.Equal(KnowledgeFacetOrigin.Host, scope.Origins["region"]); + Assert.Equal(KnowledgeFacetOrigin.Extractor, scope.Origins["brand"]); + Assert.Equal(KnowledgeFacetOrigin.Wildcard, scope.Origins["applies_to"]); + } } } diff --git a/tests/AgentCore.Application.Tests/Knowledge/ToolFacetOverlayTests.cs b/tests/AgentCore.Application.Tests/Knowledge/ToolFacetOverlayTests.cs index 54f906ff..d2b35649 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/ToolFacetOverlayTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/ToolFacetOverlayTests.cs @@ -2,106 +2,111 @@ using AgentCore.Domain.Knowledge; using Xunit; -namespace AgentCore.Application.Tests.Knowledge; - -/// -/// What a tool argument is allowed to change about the scope a turn already composed. -/// -/// -/// The rule these hold is an isolation rule, not a retrieval one. A host facet is who is asking and -/// an extractor facet is what they said; a facet off a tool argument is a guess about the subject. A -/// guess that could overwrite either would be an argument that moves the caller into another tenant. -/// -public sealed class ToolFacetOverlayTests +namespace AgentCore.Application.Tests.Knowledge { - [Fact] - public void Apply_NamedNothing_LeavesTheScopeAlone() + /// + /// What a tool argument is allowed to change about the scope a turn already composed. + /// + /// + /// The rule these hold is an isolation rule, not a retrieval one. A host facet is who is asking and + /// an extractor facet is what they said; a facet off a tool argument is a guess about the subject. A + /// guess that could overwrite either would be an argument that moves the caller into another tenant. + /// + public sealed class ToolFacetOverlayTests { - var composed = Scope((KnowledgeFacetOrigin.Host, "customer", "acme")); + [Fact] + public void Apply_NamedNothing_LeavesTheScopeAlone() + { + KnowledgeScope composed = Scope((KnowledgeFacetOrigin.Host, "customer", "acme")); - var (scope, narrowed) = ToolFacetOverlay.Apply(composed, named: null); + (KnowledgeScope? scope, bool narrowed) = ToolFacetOverlay.Apply(composed, named: null); - Assert.Same(composed, scope); - Assert.False(narrowed); - } + Assert.Same(composed, scope); + Assert.False(narrowed); + } - [Fact] - public void Apply_HostFacet_IsNotOverwritten() - { - var composed = Scope((KnowledgeFacetOrigin.Host, "customer", "acme")); + [Fact] + public void Apply_HostFacet_IsNotOverwritten() + { + KnowledgeScope composed = Scope((KnowledgeFacetOrigin.Host, "customer", "acme")); - var (scope, narrowed) = ToolFacetOverlay.Apply(composed, Named(("customer", "globex"))); + (KnowledgeScope? scope, bool narrowed) = ToolFacetOverlay.Apply(composed, Named(("customer", "globex"))); - Assert.Equal("acme", scope.Facets["customer"]); - Assert.Equal(KnowledgeFacetOrigin.Host, scope.Origins["customer"]); - Assert.False(narrowed); - } + Assert.Equal("acme", scope.Facets["customer"]); + Assert.Equal(KnowledgeFacetOrigin.Host, scope.Origins["customer"]); + Assert.False(narrowed); + } - [Fact] - public void Apply_ExtractorFacet_IsNotOverwritten() - { - var composed = Scope((KnowledgeFacetOrigin.Extractor, "product_line", "treadmill")); + [Fact] + public void Apply_ExtractorFacet_IsNotOverwritten() + { + KnowledgeScope composed = Scope((KnowledgeFacetOrigin.Extractor, "product_line", "treadmill")); - var (scope, narrowed) = ToolFacetOverlay.Apply(composed, Named(("product_line", "bike"))); + (KnowledgeScope? scope, bool narrowed) = ToolFacetOverlay.Apply(composed, Named(("product_line", "bike"))); - Assert.Equal("treadmill", scope.Facets["product_line"]); - Assert.False(narrowed); - } + Assert.Equal("treadmill", scope.Facets["product_line"]); + Assert.False(narrowed); + } - [Fact] - public void Apply_WildcardFacet_IsNarrowed() - { - var composed = Scope((KnowledgeFacetOrigin.Wildcard, "model", "*")); + [Fact] + public void Apply_WildcardFacet_IsNarrowed() + { + KnowledgeScope composed = Scope((KnowledgeFacetOrigin.Wildcard, "model", "*")); - var (scope, narrowed) = ToolFacetOverlay.Apply(composed, Named(("model", "lcr-2023"))); + (KnowledgeScope? scope, bool narrowed) = ToolFacetOverlay.Apply(composed, Named(("model", "lcr-2023"))); - Assert.Equal("lcr-2023", scope.Facets["model"]); - Assert.Equal(KnowledgeFacetOrigin.Tool, scope.Origins["model"]); - Assert.True(narrowed); - } + Assert.Equal("lcr-2023", scope.Facets["model"]); + Assert.Equal(KnowledgeFacetOrigin.Tool, scope.Origins["model"]); + Assert.True(narrowed); + } - [Fact] - public void Apply_FacetTheScopeDoesNotHold_IsAdded() - { - var (scope, narrowed) = ToolFacetOverlay.Apply(Scope(), Named(("model", "lcr-2023"))); + [Fact] + public void Apply_FacetTheScopeDoesNotHold_IsAdded() + { + (KnowledgeScope? scope, bool narrowed) = ToolFacetOverlay.Apply(Scope(), Named(("model", "lcr-2023"))); - Assert.Equal("lcr-2023", scope.Facets["model"]); - Assert.Equal(KnowledgeFacetOrigin.Tool, scope.Origins["model"]); - Assert.True(narrowed); - } + Assert.Equal("lcr-2023", scope.Facets["model"]); + Assert.Equal(KnowledgeFacetOrigin.Tool, scope.Origins["model"]); + Assert.True(narrowed); + } - [Fact] - public void Apply_OneNarrowsAndOneIsRefused_KeepsBoth() - { - var composed = Scope( - (KnowledgeFacetOrigin.Host, "customer", "acme"), - (KnowledgeFacetOrigin.Wildcard, "model", "*")); + [Fact] + public void Apply_OneNarrowsAndOneIsRefused_KeepsBoth() + { + KnowledgeScope composed = Scope( + (KnowledgeFacetOrigin.Host, "customer", "acme"), + (KnowledgeFacetOrigin.Wildcard, "model", "*")); - var (scope, narrowed) = ToolFacetOverlay.Apply( - composed, Named(("customer", "globex"), ("model", "lcr-2023"))); + (KnowledgeScope? scope, bool narrowed) = ToolFacetOverlay.Apply( + composed, Named(("customer", "globex"), ("model", "lcr-2023"))); - Assert.Equal("acme", scope.Facets["customer"]); - Assert.Equal("lcr-2023", scope.Facets["model"]); - Assert.True(narrowed); - } + Assert.Equal("acme", scope.Facets["customer"]); + Assert.Equal("lcr-2023", scope.Facets["model"]); + Assert.True(narrowed); + } - [Fact] - public void Apply_DoesNotMutateTheScopeItWasGiven() - { - var composed = Scope((KnowledgeFacetOrigin.Wildcard, "model", "*")); + [Fact] + public void Apply_DoesNotMutateTheScopeItWasGiven() + { + KnowledgeScope composed = Scope((KnowledgeFacetOrigin.Wildcard, "model", "*")); - ToolFacetOverlay.Apply(composed, Named(("model", "lcr-2023"))); + _ = ToolFacetOverlay.Apply(composed, Named(("model", "lcr-2023"))); - Assert.Equal("*", composed.Facets["model"]); - } + Assert.Equal("*", composed.Facets["model"]); + } - private static KnowledgeScope Scope(params (KnowledgeFacetOrigin Origin, string Key, string Value)[] facets) - => new() + private static KnowledgeScope Scope(params (KnowledgeFacetOrigin Origin, string Key, string Value)[] facets) { - Facets = facets.ToDictionary(f => f.Key, f => f.Value, StringComparer.Ordinal), - Origins = facets.ToDictionary(f => f.Key, f => f.Origin, StringComparer.Ordinal), - }; - - private static Dictionary Named(params (string Key, string Value)[] facets) - => facets.ToDictionary(f => f.Key, f => f.Value, StringComparer.Ordinal); + return new() + { + Facets = facets.ToDictionary(f => f.Key, f => f.Value, StringComparer.Ordinal), + Origins = facets.ToDictionary(f => f.Key, f => f.Origin, StringComparer.Ordinal), + }; + } + + private static Dictionary Named(params (string Key, string Value)[] facets) + { + return facets.ToDictionary(f => f.Key, f => f.Value, StringComparer.Ordinal); + } + } } diff --git a/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs b/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs index fa7caf25..4daa3058 100644 --- a/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Llm/CompositeChatClientFactoryTests.cs @@ -7,22 +7,22 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Llm; - -/// -/// The composite behind UseChatClients. It routes each providers.llm[] entry to the -/// adapter whose matches, and it owns everything no vendor owns: -/// the as map, the default entry, the temperature wrapper, and the client cache. -/// -/// -/// Every adapter here is a fake, so every test runs offline. The document names the vendor and the -/// host registers the adapters; these tests prove the document alone decides which adapter builds -/// which client. -/// -public sealed class CompositeChatClientFactoryTests +namespace AgentCore.Application.Tests.Llm { - private const string TwoVendorsYaml = - """ + /// + /// The composite behind UseChatClients. It routes each providers.llm[] entry to the + /// adapter whose matches, and it owns everything no vendor owns: + /// the as map, the default entry, the temperature wrapper, and the client cache. + /// + /// + /// Every adapter here is a fake, so every test runs offline. The document names the vendor and the + /// host registers the adapters; these tests prove the document alone decides which adapter builds + /// which client. + /// + public sealed class CompositeChatClientFactoryTests + { + private const string TwoVendorsYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -40,8 +40,8 @@ public sealed class CompositeChatClientFactoryTests agent: only """; - private const string OneVendorYaml = - """ + private const string OneVendorYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -59,8 +59,8 @@ public sealed class CompositeChatClientFactoryTests agent: only """; - private const string UpperCaseKindYaml = - """ + private const string UpperCaseKindYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -77,8 +77,8 @@ public sealed class CompositeChatClientFactoryTests agent: only """; - private const string DuplicateAsYaml = - """ + private const string DuplicateAsYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -96,8 +96,8 @@ public sealed class CompositeChatClientFactoryTests agent: only """; - private const string NoModelYaml = - """ + private const string NoModelYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -107,279 +107,284 @@ public sealed class CompositeChatClientFactoryTests agent: only """; - // --------------------------------------------------------------------------------------------- - // Routing: the document names the vendor, and the matching adapter builds the client. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TwoKinds_RouteToTheTwoAdaptersTheHostRegistered() - { - RecordingChatClientAdapter openai = new("openai"); - RecordingChatClientAdapter anthropic = new("anthropic"); + // --------------------------------------------------------------------------------------------- + // Routing: the document names the vendor, and the matching adapter builds the client. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TwoKinds_RouteToTheTwoAdaptersTheHostRegistered() + { + RecordingChatClientAdapter openai = new("openai"); + RecordingChatClientAdapter anthropic = new("anthropic"); - using var factory = await Create(TwoVendorsYaml, openai, anthropic); + using CompositeChatClientFactory factory = await Create(TwoVendorsYaml, openai, anthropic); - Assert.Same(openai.ClientOf("reply"), factory.GetChatClient(new ModelReference { Ref = "reply" })); - Assert.Same(anthropic.ClientOf("fill"), factory.GetChatClient(new ModelReference { Ref = "fill" })); - } + Assert.Same(openai.ClientOf("reply"), factory.GetChatClient(new ModelReference { Ref = "reply" })); + Assert.Same(anthropic.ClientOf("fill"), factory.GetChatClient(new ModelReference { Ref = "fill" })); + } - [Fact] - public async Task AKindWrittenInAnotherCase_StillFindsItsAdapter() - { - RecordingChatClientAdapter openai = new("openai"); + [Fact] + public async Task AKindWrittenInAnotherCase_StillFindsItsAdapter() + { + RecordingChatClientAdapter openai = new("openai"); - using var factory = await Create(UpperCaseKindYaml, openai); + using CompositeChatClientFactory factory = await Create(UpperCaseKindYaml, openai); - Assert.Same(openai.ClientOf("reply"), factory.GetChatClient(new ModelReference { Ref = "reply" })); - } + Assert.Same(openai.ClientOf("reply"), factory.GetChatClient(new ModelReference { Ref = "reply" })); + } - [Fact] - public async Task EveryClient_IsBuiltWhileTheFactoryBuildsAndNeverAgain() - { - RecordingChatClientAdapter openai = new("openai"); + [Fact] + public async Task EveryClient_IsBuiltWhileTheFactoryBuildsAndNeverAgain() + { + RecordingChatClientAdapter openai = new("openai"); - using var factory = await Create(OneVendorYaml, openai); - factory.GetChatClient(new ModelReference { Ref = "reply" }); - factory.GetChatClient(new ModelReference { Ref = "reply" }); - factory.GetChatClient(new ModelReference { Ref = "fill" }); + using CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); + _ = factory.GetChatClient(new ModelReference { Ref = "reply" }); + _ = factory.GetChatClient(new ModelReference { Ref = "reply" }); + _ = factory.GetChatClient(new ModelReference { Ref = "fill" }); - // One build for each 'as' name, at startup. A conversation costs no build. - Assert.Equal(["reply", "fill"], openai.BuiltNames); - } + // One build for each 'as' name, at startup. A conversation costs no build. + Assert.Equal(["reply", "fill"], openai.BuiltNames); + } - [Fact] - public async Task TheAdapter_ReceivesTheResolverChainTheHostBound() - { - RecordingChatClientAdapter openai = new("openai"); - MapSecretResolver resolver = new(); + [Fact] + public async Task TheAdapter_ReceivesTheResolverChainTheHostBound() + { + RecordingChatClientAdapter openai = new("openai"); + MapSecretResolver resolver = new(); - using var factory = await Create(UpperCaseKindYaml, resolver, openai); + using CompositeChatClientFactory factory = await Create(UpperCaseKindYaml, resolver, openai); - Assert.Same(resolver, openai.LastSecrets); - } + Assert.Same(resolver, openai.LastSecrets); + } - // --------------------------------------------------------------------------------------------- - // The 'as' map and the default entry, exactly as the one-vendor factory held them. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AReferenceWithNoModel_TakesTheFirstDeclaredEntry() - { - RecordingChatClientAdapter openai = new("openai"); + // --------------------------------------------------------------------------------------------- + // The 'as' map and the default entry, exactly as the one-vendor factory held them. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AReferenceWithNoModel_TakesTheFirstDeclaredEntry() + { + RecordingChatClientAdapter openai = new("openai"); - using var factory = await Create(OneVendorYaml, openai); + using CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); - Assert.Same(factory.GetChatClient(new ModelReference { Ref = "reply" }), factory.GetChatClient(null)); - } + Assert.Same(factory.GetChatClient(new ModelReference { Ref = "reply" }), factory.GetChatClient(null)); + } - [Fact] - public async Task AnUnknownAsName_FailsAndNamesWhatTheDocumentDoesDeclare() - { - using var factory = await Create(OneVendorYaml, new RecordingChatClientAdapter("openai")); + [Fact] + public async Task AnUnknownAsName_FailsAndNamesWhatTheDocumentDoesDeclare() + { + using CompositeChatClientFactory factory = await Create(OneVendorYaml, new RecordingChatClientAdapter("openai")); - var failure = Assert.Throws( - () => factory.GetChatClient(new ModelReference { Ref = "summarise" })); + ConfigurationLoadException failure = Assert.Throws( + () => factory.GetChatClient(new ModelReference { Ref = "summarise" })); - Assert.Contains("'summarise'", failure.Message, StringComparison.Ordinal); - Assert.Contains("'reply'", failure.Message, StringComparison.Ordinal); - Assert.Contains("'fill'", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("'summarise'", failure.Message, StringComparison.Ordinal); + Assert.Contains("'reply'", failure.Message, StringComparison.Ordinal); + Assert.Contains("'fill'", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task ADocumentWithNoModel_FailsAReferenceThatNamesNone() - { - using var factory = await Create(NoModelYaml, new RecordingChatClientAdapter("openai")); + [Fact] + public async Task ADocumentWithNoModel_FailsAReferenceThatNamesNone() + { + using CompositeChatClientFactory factory = await Create(NoModelYaml, new RecordingChatClientAdapter("openai")); - var failure = Assert.Throws(() => factory.GetChatClient(null)); + ConfigurationLoadException failure = Assert.Throws(() => factory.GetChatClient(null)); - Assert.Contains("declares no model", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("declares no model", failure.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // GetContextWindow: forwards to the adapter of the entry the reference names. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task GetContextWindow_ANamedReference_ForwardsToItsOwnAdapter() - { - RecordingChatClientAdapter openai = new("openai") { ContextWindow = 128_000 }; - RecordingChatClientAdapter anthropic = new("anthropic") { ContextWindow = 200_000 }; + // --------------------------------------------------------------------------------------------- + // GetContextWindow: forwards to the adapter of the entry the reference names. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task GetContextWindow_ANamedReference_ForwardsToItsOwnAdapter() + { + RecordingChatClientAdapter openai = new("openai") { ContextWindow = 128_000 }; + RecordingChatClientAdapter anthropic = new("anthropic") { ContextWindow = 200_000 }; - using var factory = await Create(TwoVendorsYaml, openai, anthropic); + using CompositeChatClientFactory factory = await Create(TwoVendorsYaml, openai, anthropic); - Assert.Equal(128_000, factory.GetContextWindow(new ModelReference { Ref = "reply" })); - Assert.Equal(200_000, factory.GetContextWindow(new ModelReference { Ref = "fill" })); - } + Assert.Equal(128_000, factory.GetContextWindow(new ModelReference { Ref = "reply" })); + Assert.Equal(200_000, factory.GetContextWindow(new ModelReference { Ref = "fill" })); + } - // --------------------------------------------------------------------------------------------- - // The temperature wrapper: the document keeps its setting, the vendor client stays one. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ATemperature_ReachesTheConversationWithoutASecondVendorClient() - { - RecordingChatClientAdapter openai = new("openai"); + // --------------------------------------------------------------------------------------------- + // The temperature wrapper: the document keeps its setting, the vendor client stays one. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ATemperature_ReachesTheConversationWithoutASecondVendorClient() + { + RecordingChatClientAdapter openai = new("openai"); - using var factory = await Create(OneVendorYaml, openai); - var shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); - await shaped.GetResponseAsync([new ChatMessage(ChatRole.User, "hi")], null, TestContext.Current.CancellationToken); + using CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); + IChatClient shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); + _ = await shaped.GetResponseAsync([new ChatMessage(ChatRole.User, "hi")], null, TestContext.Current.CancellationToken); - Assert.Equal(0.2f, openai.RecorderOf("reply").LastOptions?.Temperature); - Assert.Equal(["reply", "fill"], openai.BuiltNames); - } + Assert.Equal(0.2f, openai.RecorderOf("reply").LastOptions?.Temperature); + Assert.Equal(["reply", "fill"], openai.BuiltNames); + } - [Fact] - public async Task OneTemperature_TakesOneWrapperHoweverOftenItIsAsked() - { - using var factory = await Create(OneVendorYaml, new RecordingChatClientAdapter("openai")); + [Fact] + public async Task OneTemperature_TakesOneWrapperHoweverOftenItIsAsked() + { + using CompositeChatClientFactory factory = await Create(OneVendorYaml, new RecordingChatClientAdapter("openai")); - var first = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); - var second = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); + IChatClient first = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); + IChatClient second = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); - Assert.Same(first, second); - Assert.NotSame(first, factory.GetChatClient(new ModelReference { Ref = "reply" })); - } + Assert.Same(first, second); + Assert.NotSame(first, factory.GetChatClient(new ModelReference { Ref = "reply" })); + } - [Fact] - public async Task ACallerSuppliedTemperature_WinsOverTheDocumentDefault() - { - RecordingChatClientAdapter openai = new("openai"); + [Fact] + public async Task ACallerSuppliedTemperature_WinsOverTheDocumentDefault() + { + RecordingChatClientAdapter openai = new("openai"); - using var factory = await Create(OneVendorYaml, openai); - var shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); + using CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); + IChatClient shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); - // The document sets the default; a caller that sets its own keeps it. - await shaped.GetResponseAsync( - [new ChatMessage(ChatRole.User, "hi")], - new ChatOptions { Temperature = 0.9f }, - TestContext.Current.CancellationToken); + // The document sets the default; a caller that sets its own keeps it. + _ = await shaped.GetResponseAsync( + [new ChatMessage(ChatRole.User, "hi")], + new ChatOptions { Temperature = 0.9f }, + TestContext.Current.CancellationToken); - Assert.Equal(0.9f, openai.RecorderOf("reply").LastOptions?.Temperature); - } + Assert.Equal(0.9f, openai.RecorderOf("reply").LastOptions?.Temperature); + } - [Fact] - public async Task AConversationWithNoOptions_StillGetsTheDocumentTemperature() - { - RecordingChatClientAdapter openai = new("openai"); + [Fact] + public async Task AConversationWithNoOptions_StillGetsTheDocumentTemperature() + { + RecordingChatClientAdapter openai = new("openai"); - using var factory = await Create(OneVendorYaml, openai); - var shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); + using CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); + IChatClient shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.2 }); - await shaped.GetResponseAsync( - [new ChatMessage(ChatRole.User, "hi")], - null, - TestContext.Current.CancellationToken); + _ = await shaped.GetResponseAsync( + [new ChatMessage(ChatRole.User, "hi")], + null, + TestContext.Current.CancellationToken); - Assert.Equal(0.2f, openai.RecorderOf("reply").LastOptions?.Temperature); - } + Assert.Equal(0.2f, openai.RecorderOf("reply").LastOptions?.Temperature); + } - [Fact] - public async Task ATemperature_ReachesAStreamingConversationToo() - { - RecordingChatClientAdapter openai = new("openai"); + [Fact] + public async Task ATemperature_ReachesAStreamingConversationToo() + { + RecordingChatClientAdapter openai = new("openai"); + + using CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); + IChatClient shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.3 }); - using var factory = await Create(OneVendorYaml, openai); - var shaped = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.3 }); + await foreach (ChatResponseUpdate _ in shaped.GetStreamingResponseAsync( + [new ChatMessage(ChatRole.User, "hi")], + null, + TestContext.Current.CancellationToken)) + { + // Draining the stream is enough to run the wrapper's Shape/Configure step. + } + + Assert.Equal(0.3f, openai.RecorderOf("reply").LastOptions?.Temperature); + } - await foreach (var _ in shaped.GetStreamingResponseAsync( - [new ChatMessage(ChatRole.User, "hi")], - null, - TestContext.Current.CancellationToken)) + // --------------------------------------------------------------------------------------------- + // Disposal: the factory owns the vendor client. A shaped wrapper is only a view over it, so + // disposing the factory must not dispose the shared vendor client more than once. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task Dispose_ReleasesTheVendorClientExactlyOnce_EvenWithTwoShapedWrappersOverIt() { - // Draining the stream is enough to run the wrapper's Shape/Configure step. + RecordingChatClientAdapter openai = new("openai"); + CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); + + // Two different temperatures over the same 'as' name take two different shaped wrappers, + // both delegating to the one shared vendor client underneath. + _ = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.1 }); + _ = factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.9 }); + + factory.Dispose(); + + // A shaped wrapper's own Dispose() chains to the vendor client (that's how + // DelegatingChatClient/ConfigureOptionsChatClient work). If the factory disposed the + // wrappers too, the vendor client would be disposed three times here: once through each + // wrapper's cascade, and once directly. Ownership says only the factory's own disposal of + // the vendor client counts. + Assert.Equal(1, openai.RecorderOf("reply").DisposeCount); } - Assert.Equal(0.3f, openai.RecorderOf("reply").LastOptions?.Temperature); - } + [Fact] + public async Task Dispose_ReleasesEveryVendorClientExactlyOnce() + { + RecordingChatClientAdapter openai = new("openai"); + CompositeChatClientFactory factory = await Create(OneVendorYaml, openai); - // --------------------------------------------------------------------------------------------- - // Disposal: the factory owns the vendor client. A shaped wrapper is only a view over it, so - // disposing the factory must not dispose the shared vendor client more than once. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task Dispose_ReleasesTheVendorClientExactlyOnce_EvenWithTwoShapedWrappersOverIt() - { - RecordingChatClientAdapter openai = new("openai"); - var factory = await Create(OneVendorYaml, openai); - - // Two different temperatures over the same 'as' name take two different shaped wrappers, - // both delegating to the one shared vendor client underneath. - factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.1 }); - factory.GetChatClient(new ModelReference { Ref = "reply", Temperature = 0.9 }); - - factory.Dispose(); - - // A shaped wrapper's own Dispose() chains to the vendor client (that's how - // DelegatingChatClient/ConfigureOptionsChatClient work). If the factory disposed the - // wrappers too, the vendor client would be disposed three times here: once through each - // wrapper's cascade, and once directly. Ownership says only the factory's own disposal of - // the vendor client counts. - Assert.Equal(1, openai.RecorderOf("reply").DisposeCount); - } + _ = factory.GetChatClient(new ModelReference { Ref = "reply" }); + _ = factory.GetChatClient(new ModelReference { Ref = "fill", Temperature = 0.5 }); - [Fact] - public async Task Dispose_ReleasesEveryVendorClientExactlyOnce() - { - RecordingChatClientAdapter openai = new("openai"); - var factory = await Create(OneVendorYaml, openai); + factory.Dispose(); - factory.GetChatClient(new ModelReference { Ref = "reply" }); - factory.GetChatClient(new ModelReference { Ref = "fill", Temperature = 0.5 }); + Assert.Equal(1, openai.RecorderOf("reply").DisposeCount); + Assert.Equal(1, openai.RecorderOf("fill").DisposeCount); + } - factory.Dispose(); + // --------------------------------------------------------------------------------------------- + // What it refuses, at startup and never on the first call. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AKindNoAdapterServes_FailsTheBuildAndNamesTheRegisteredKinds() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(TwoVendorsYaml, new RecordingChatClientAdapter("openai"))); - Assert.Equal(1, openai.RecorderOf("reply").DisposeCount); - Assert.Equal(1, openai.RecorderOf("fill").DisposeCount); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/llm/1/kind", error.Pointer); + Assert.Contains("anthropic", error.Message, StringComparison.Ordinal); + Assert.Contains("'openai'", error.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // What it refuses, at startup and never on the first call. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AKindNoAdapterServes_FailsTheBuildAndNamesTheRegisteredKinds() - { - var failure = await Assert.ThrowsAsync( - async () => await Create(TwoVendorsYaml, new RecordingChatClientAdapter("openai"))); + [Fact] + public async Task TwoAdaptersForOneKindFailTheStart() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create( + OneVendorYaml, + new RecordingChatClientAdapter("openai"), + new RecordingChatClientAdapter("openai"))); + + Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + Assert.Contains("providers.llm", failure.Message, StringComparison.Ordinal); + } - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/llm/1/kind", error.Pointer); - Assert.Contains("anthropic", error.Message, StringComparison.Ordinal); - Assert.Contains("'openai'", error.Message, StringComparison.Ordinal); - } + [Fact] + public async Task TwoEntriesWithOneAsName_FailTheBuild() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await Create(DuplicateAsYaml, new RecordingChatClientAdapter("openai"))); - [Fact] - public async Task TwoAdaptersForOneKindFailTheStart() - { - var failure = await Assert.ThrowsAsync( - async () => await Create( - OneVendorYaml, - new RecordingChatClientAdapter("openai"), - new RecordingChatClientAdapter("openai"))); - - Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); - Assert.Contains("providers.llm", failure.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal("/providers/llm/1/as", error.Pointer); + Assert.Contains("'reply'", error.Message, StringComparison.Ordinal); + } - [Fact] - public async Task TwoEntriesWithOneAsName_FailTheBuild() - { - var failure = await Assert.ThrowsAsync( - async () => await Create(DuplicateAsYaml, new RecordingChatClientAdapter("openai"))); + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private static ValueTask Create(string yaml, params IChatClientAdapter[] adapters) + { + return Create(yaml, null, adapters); + } - var error = Assert.Single(failure.Errors); - Assert.Equal("/providers/llm/1/as", error.Pointer); - Assert.Contains("'reply'", error.Message, StringComparison.Ordinal); + private static ValueTask Create( + string yaml, + ISecretResolverPort? secrets, + params IChatClientAdapter[] adapters) + { + return CompositeChatClientFactory.CreateAsync( + ConfigurationLoader.LoadYaml(yaml), + secrets, + adapters, + TestContext.Current.CancellationToken); + } } - - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private static ValueTask Create(string yaml, params IChatClientAdapter[] adapters) - => Create(yaml, null, adapters); - - private static ValueTask Create( - string yaml, - ISecretResolverPort? secrets, - params IChatClientAdapter[] adapters) - => CompositeChatClientFactory.CreateAsync( - ConfigurationLoader.LoadYaml(yaml), - secrets, - adapters, - TestContext.Current.CancellationToken); } diff --git a/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs b/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs index adfab483..e5f899c3 100644 --- a/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs +++ b/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs @@ -4,49 +4,55 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Llm; - -/// -/// Which vendors resolve a hosted marker, and the operator's per-entry veto. -/// -public sealed class HostedWebSearchCapabilityTests +namespace AgentCore.Application.Tests.Llm { - [Fact] - public void Adapter_DefaultMember_AnswersNull() + /// + /// Which vendors resolve a hosted marker, and the operator's per-entry veto. + /// + public sealed class HostedWebSearchCapabilityTests { - // A host that wrote an adapter before this member existed keeps compiling, and keeps - // answering null, so its models never meet a tool they cannot call. - IChatClientAdapter adapter = new SilentAdapter(); + [Fact] + public void Adapter_DefaultMember_AnswersNull() + { + // A host that wrote an adapter before this member existed keeps compiling, and keeps + // answering null, so its models never meet a tool they cannot call. + IChatClientAdapter adapter = new SilentAdapter(); - Assert.Null(adapter.ResolveHostedTool(new HostedWebSearchTool(), Entry(webSearch: null))); - } + Assert.Null(adapter.ResolveHostedTool(new HostedWebSearchTool(), Entry(webSearch: null))); + } - [Fact] - public void Factory_UnknownReference_AnswersNull() - { - // A reference the document does not declare must not throw here. The compiler asks this - // question while deciding whether to add a tool, and a missing model is reported elsewhere. - // The interface default is under test; it is reachable only through the interface type. - Assert.Null(((IChatClientFactory)new RecordingChatClientFactory()) - .ResolveHostedTool(new HostedWebSearchTool(), new ModelReference { Ref = "absent" })); - } + [Fact] + public void Factory_UnknownReference_AnswersNull() + { + // A reference the document does not declare must not throw here. The compiler asks this + // question while deciding whether to add a tool, and a missing model is reported elsewhere. + // The interface default is under test; it is reachable only through the interface type. + Assert.Null(((IChatClientFactory)new RecordingChatClientFactory()) + .ResolveHostedTool(new HostedWebSearchTool(), new ModelReference { Ref = "absent" })); + } - private static LlmProviderConfiguration Entry(bool? webSearch) => new() - { - Kind = "silent", - Model = "m", - As = "reply", - WebSearch = webSearch, - }; + private static LlmProviderConfiguration Entry(bool? webSearch) + { + return new() + { + Kind = "silent", + Model = "m", + As = "reply", + WebSearch = webSearch, + }; + } - private sealed class SilentAdapter : IChatClientAdapter - { - public string Kind => "silent"; + private sealed class SilentAdapter : IChatClientAdapter + { + public string Kind => "silent"; - public ValueTask CreateClientAsync( - LlmProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public ValueTask CreateClientAsync( + LlmProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Policy/ConversationPolicyGoldenSet.cs b/tests/AgentCore.Application.Tests/Policy/ConversationPolicyGoldenSet.cs index 9b733d59..8154db0e 100644 --- a/tests/AgentCore.Application.Tests/Policy/ConversationPolicyGoldenSet.cs +++ b/tests/AgentCore.Application.Tests/Policy/ConversationPolicyGoldenSet.cs @@ -1,200 +1,209 @@ using System.Text.Json.Nodes; -namespace AgentCore.Application.Tests.Policy; - -/// The stage of a service call. The stage set of spike/callpolicy. -internal enum ConversationStage +namespace AgentCore.Application.Tests.Policy { - Greeting, - Identify, - Classify, - Resolve, - Escalate, - Close, -} + /// The stage of a service call. The stage set of spike/callpolicy. + internal enum ConversationStage + { + Greeting, + Identify, + Classify, + Resolve, + Escalate, + Close, + } -/// -/// Everything the turn loop learned about the conversation so far. The externalized, typed state. -/// -internal sealed record CallFacts -{ - public static readonly CallFacts Empty = new(); + /// + /// Everything the turn loop learned about the conversation so far. The externalized, typed state. + /// + internal sealed record CallFacts + { + public static readonly CallFacts Empty = new(); - public string? Model { get; init; } + public string? Model { get; init; } - public string? Serial { get; init; } + public string? Serial { get; init; } - public string? FaultCode { get; init; } + public string? FaultCode { get; init; } - public bool ProblemDescribed { get; init; } + public bool ProblemDescribed { get; init; } - public bool Resolved { get; init; } + public bool Resolved { get; init; } - public bool CallerAskedForHuman { get; init; } + public bool CallerAskedForHuman { get; init; } - public bool CallerSaidGoodbye { get; init; } + public bool CallerSaidGoodbye { get; init; } - public int FailedResolveTurns { get; init; } + public int FailedResolveTurns { get; init; } - public bool MachineIdentified => Model is not null && Serial is not null; + public bool MachineIdentified => Model is not null && Serial is not null; - public bool ProblemKnown => FaultCode is not null || ProblemDescribed; + public bool ProblemKnown => FaultCode is not null || ProblemDescribed; - /// Writes the facts as the state snapshot a configuration-declared guard reads. - public IReadOnlyDictionary ToSnapshot(string stage, int turnIndex) - => new Dictionary(StringComparer.Ordinal) + /// Writes the facts as the state snapshot a configuration-declared guard reads. + public IReadOnlyDictionary ToSnapshot(string stage, int turnIndex) { - ["model"] = Model is null ? null : JsonValue.Create(Model), - ["serial"] = Serial is null ? null : JsonValue.Create(Serial), - ["faultCode"] = FaultCode is null ? null : JsonValue.Create(FaultCode), - ["problemDescribed"] = JsonValue.Create(ProblemDescribed), - ["resolved"] = JsonValue.Create(Resolved), - ["callerAskedForHuman"] = JsonValue.Create(CallerAskedForHuman), - ["callerSaidGoodbye"] = JsonValue.Create(CallerSaidGoodbye), - ["failedResolveTurns"] = JsonValue.Create(FailedResolveTurns), - ["stage"] = JsonValue.Create(stage), - ["turnIndex"] = JsonValue.Create(turnIndex), - ["conversationDurationSeconds"] = JsonValue.Create(0d), - }; -} - -/// -/// The hand-written transition table of spike/callpolicy, copied unchanged. -/// -/// -/// Rule 15 of section 11: the six golden conversations replay against a configuration-declared policy and -/// reproduce this machine exactly. Nothing else in the test holds a transition rule, so the -/// comparison stays about the runtime and not about the rules. -/// -internal static class Transitions -{ - public const int EscalateAfterTurns = 3; + return new Dictionary(StringComparer.Ordinal) + { + ["model"] = Model is null ? null : JsonValue.Create(Model), + ["serial"] = Serial is null ? null : JsonValue.Create(Serial), + ["faultCode"] = FaultCode is null ? null : JsonValue.Create(FaultCode), + ["problemDescribed"] = JsonValue.Create(ProblemDescribed), + ["resolved"] = JsonValue.Create(Resolved), + ["callerAskedForHuman"] = JsonValue.Create(CallerAskedForHuman), + ["callerSaidGoodbye"] = JsonValue.Create(CallerSaidGoodbye), + ["failedResolveTurns"] = JsonValue.Create(FailedResolveTurns), + ["stage"] = JsonValue.Create(stage), + ["turnIndex"] = JsonValue.Create(turnIndex), + ["conversationDurationSeconds"] = JsonValue.Create(0d), + }; + } + } - public static ConversationStage Next(ConversationStage current, CallFacts f) => current switch + /// + /// The hand-written transition table of spike/callpolicy, copied unchanged. + /// + /// + /// Rule 15 of section 11: the six golden conversations replay against a configuration-declared policy and + /// reproduce this machine exactly. Nothing else in the test holds a transition rule, so the + /// comparison stays about the runtime and not about the rules. + /// + internal static class Transitions { - ConversationStage.Greeting => ConversationStage.Identify, - - ConversationStage.Identify when f.CallerSaidGoodbye => ConversationStage.Close, - ConversationStage.Identify when f.CallerAskedForHuman => ConversationStage.Escalate, - ConversationStage.Identify when f.MachineIdentified => ConversationStage.Classify, - ConversationStage.Identify => ConversationStage.Identify, + public const int EscalateAfterTurns = 3; - ConversationStage.Classify when f.CallerSaidGoodbye => ConversationStage.Close, - ConversationStage.Classify when f.CallerAskedForHuman => ConversationStage.Escalate, - ConversationStage.Classify when f.ProblemKnown => ConversationStage.Resolve, - ConversationStage.Classify => ConversationStage.Classify, + public static ConversationStage Next(ConversationStage current, CallFacts f) + { + return current switch + { + ConversationStage.Greeting => ConversationStage.Identify, + + ConversationStage.Identify when f.CallerSaidGoodbye => ConversationStage.Close, + ConversationStage.Identify when f.CallerAskedForHuman => ConversationStage.Escalate, + ConversationStage.Identify when f.MachineIdentified => ConversationStage.Classify, + ConversationStage.Identify => ConversationStage.Identify, + + ConversationStage.Classify when f.CallerSaidGoodbye => ConversationStage.Close, + ConversationStage.Classify when f.CallerAskedForHuman => ConversationStage.Escalate, + ConversationStage.Classify when f.ProblemKnown => ConversationStage.Resolve, + ConversationStage.Classify => ConversationStage.Classify, + + ConversationStage.Resolve when f.CallerSaidGoodbye => ConversationStage.Close, + ConversationStage.Resolve when f.CallerAskedForHuman => ConversationStage.Escalate, + ConversationStage.Resolve when f.Resolved => ConversationStage.Close, + ConversationStage.Resolve when f.FailedResolveTurns >= EscalateAfterTurns => ConversationStage.Escalate, + ConversationStage.Resolve => ConversationStage.Resolve, + + ConversationStage.Escalate => ConversationStage.Close, + ConversationStage.Close => ConversationStage.Close, + + _ => throw new ArgumentOutOfRangeException(nameof(current), current, null), + }; + } - ConversationStage.Resolve when f.CallerSaidGoodbye => ConversationStage.Close, - ConversationStage.Resolve when f.CallerAskedForHuman => ConversationStage.Escalate, - ConversationStage.Resolve when f.Resolved => ConversationStage.Close, - ConversationStage.Resolve when f.FailedResolveTurns >= EscalateAfterTurns => ConversationStage.Escalate, - ConversationStage.Resolve => ConversationStage.Resolve, + /// Maps one stage to the id the configuration declares. + public static string ToStageId(ConversationStage stage) + { + return stage switch + { + ConversationStage.Greeting => "greeting", + ConversationStage.Identify => "identify", + ConversationStage.Classify => "classify", + ConversationStage.Resolve => "resolve", + ConversationStage.Escalate => "escalate", + ConversationStage.Close => "close", + _ => throw new ArgumentOutOfRangeException(nameof(stage), stage, null), + }; + } + } - ConversationStage.Escalate => ConversationStage.Close, - ConversationStage.Close => ConversationStage.Close, + /// One caller turn: the facts the turn loop observed after it ended. + internal sealed record GoldenTurn(string Label, CallFacts Facts); - _ => throw new ArgumentOutOfRangeException(nameof(current), current, null), - }; + /// One whole conversation, replayed against a policy. + internal sealed record GoldenConversation(string Name, IReadOnlyList Turns); - /// Maps one stage to the id the configuration declares. - public static string ToStageId(ConversationStage stage) => stage switch + /// + /// The six deterministic conversation scenarios of spike/callpolicy. No model runs. + /// + internal static class GoldenSet { - ConversationStage.Greeting => "greeting", - ConversationStage.Identify => "identify", - ConversationStage.Classify => "classify", - ConversationStage.Resolve => "resolve", - ConversationStage.Escalate => "escalate", - _ => "close", - }; -} - -/// One caller turn: the facts the turn loop observed after it ended. -internal sealed record GoldenTurn(string Label, CallFacts Facts); - -/// One whole conversation, replayed against a policy. -internal sealed record GoldenConversation(string Name, IReadOnlyList Turns); - -/// -/// The six deterministic conversation scenarios of spike/callpolicy. No model runs. -/// -internal static class GoldenSet -{ - public static IReadOnlyList Conversations { get; } = - [ - new("happy-path-fault-code", + public static IReadOnlyList Conversations { get; } = [ - new("caller says hello", CallFacts.Empty), - new("gives model and serial", new CallFacts { Model = "F85", Serial = "SF240117" }), - new("reads the fault code", new CallFacts { Model = "F85", Serial = "SF240117", FaultCode = "E7" }), - new("follows the fix", new CallFacts { Model = "F85", Serial = "SF240117", FaultCode = "E7", Resolved = true }), - ]), - - new("slow-identification", - [ - new("caller says hello", CallFacts.Empty), - new("gives model only", new CallFacts { Model = "F80" }), - new("cannot find the serial", new CallFacts { Model = "F80" }), - new("finds the serial", new CallFacts { Model = "F80", Serial = "SF230902" }), - new("describes a noise", new CallFacts { Model = "F80", Serial = "SF230902", ProblemDescribed = true }), - new("fix works", new CallFacts { Model = "F80", Serial = "SF230902", ProblemDescribed = true, Resolved = true }), - ]), - - new("escalate-after-three-failures", - [ - new("caller says hello", CallFacts.Empty), - new("gives model and serial", new CallFacts { Model = "TT8", Serial = "SF251103" }), - new("describes the problem", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true }), - new("fix 1 fails", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 1 }), - new("fix 2 fails", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 2 }), - new("fix 3 fails", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 3 }), - new("transfer completes", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 3 }), - ]), - - new("caller-demands-a-human-immediately", - [ - new("caller says hello", CallFacts.Empty), - new("asks for a person", new CallFacts { CallerAskedForHuman = true }), - new("transfer completes", new CallFacts { CallerAskedForHuman = true }), - ]), - - new("caller-hangs-up-mid-diagnosis", - [ - new("caller says hello", CallFacts.Empty), - new("gives model and serial", new CallFacts { Model = "F63", Serial = "SF221201" }), - new("says goodbye", new CallFacts { Model = "F63", Serial = "SF221201", CallerSaidGoodbye = true }), - ]), - - new("human-request-beats-a-resolved-fix", - [ - new("caller says hello", CallFacts.Empty), - new("gives model and serial", new CallFacts { Model = "E95", Serial = "SF260401" }), - new("gives the fault code", new CallFacts { Model = "E95", Serial = "SF260401", FaultCode = "E1" }), - - // Both Resolved and CallerAskedForHuman are true. Precedence must be deterministic. - new("fixed but still wants a person", - new CallFacts { Model = "E95", Serial = "SF260401", FaultCode = "E1", Resolved = true, CallerAskedForHuman = true }), - ]), - ]; - - /// Replays one conversation against the hand-written table. - public static IReadOnlyList ReplayHandWritten(GoldenConversation conversation) - { - var stage = ConversationStage.Greeting; - List stages = new(conversation.Turns.Count); - foreach (var turn in conversation.Turns) + new("happy-path-fault-code", + [ + new("caller says hello", CallFacts.Empty), + new("gives model and serial", new CallFacts { Model = "F85", Serial = "SF240117" }), + new("reads the fault code", new CallFacts { Model = "F85", Serial = "SF240117", FaultCode = "E7" }), + new("follows the fix", new CallFacts { Model = "F85", Serial = "SF240117", FaultCode = "E7", Resolved = true }), + ]), + + new("slow-identification", + [ + new("caller says hello", CallFacts.Empty), + new("gives model only", new CallFacts { Model = "F80" }), + new("cannot find the serial", new CallFacts { Model = "F80" }), + new("finds the serial", new CallFacts { Model = "F80", Serial = "SF230902" }), + new("describes a noise", new CallFacts { Model = "F80", Serial = "SF230902", ProblemDescribed = true }), + new("fix works", new CallFacts { Model = "F80", Serial = "SF230902", ProblemDescribed = true, Resolved = true }), + ]), + + new("escalate-after-three-failures", + [ + new("caller says hello", CallFacts.Empty), + new("gives model and serial", new CallFacts { Model = "TT8", Serial = "SF251103" }), + new("describes the problem", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true }), + new("fix 1 fails", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 1 }), + new("fix 2 fails", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 2 }), + new("fix 3 fails", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 3 }), + new("transfer completes", new CallFacts { Model = "TT8", Serial = "SF251103", ProblemDescribed = true, FailedResolveTurns = 3 }), + ]), + + new("caller-demands-a-human-immediately", + [ + new("caller says hello", CallFacts.Empty), + new("asks for a person", new CallFacts { CallerAskedForHuman = true }), + new("transfer completes", new CallFacts { CallerAskedForHuman = true }), + ]), + + new("caller-hangs-up-mid-diagnosis", + [ + new("caller says hello", CallFacts.Empty), + new("gives model and serial", new CallFacts { Model = "F63", Serial = "SF221201" }), + new("says goodbye", new CallFacts { Model = "F63", Serial = "SF221201", CallerSaidGoodbye = true }), + ]), + + new("human-request-beats-a-resolved-fix", + [ + new("caller says hello", CallFacts.Empty), + new("gives model and serial", new CallFacts { Model = "E95", Serial = "SF260401" }), + new("gives the fault code", new CallFacts { Model = "E95", Serial = "SF260401", FaultCode = "E1" }), + + // Both Resolved and CallerAskedForHuman are true. Precedence must be deterministic. + new("fixed but still wants a person", + new CallFacts { Model = "E95", Serial = "SF260401", FaultCode = "E1", Resolved = true, CallerAskedForHuman = true }), + ]), + ]; + + /// Replays one conversation against the hand-written table. + public static IReadOnlyList ReplayHandWritten(GoldenConversation conversation) { - stage = Transitions.Next(stage, turn.Facts); - stages.Add(stage); + ConversationStage stage = ConversationStage.Greeting; + List stages = new(conversation.Turns.Count); + foreach (GoldenTurn turn in conversation.Turns) + { + stage = Transitions.Next(stage, turn.Facts); + stages.Add(stage); + } + + return stages; } - return stages; - } - - /// - /// The same six stages, declared in configuration. This is the document rule 15 replays against. - /// - public const string Yaml = - """ + /// + /// The same six stages, declared in configuration. This is the document rule 15 replays against. + /// + public const string Yaml = + """ apiVersion: agentcore/v1 state: @@ -317,4 +326,5 @@ public static IReadOnlyList ReplayHandWritten(GoldenConversat - { kind: openai, model: gpt-4.1-mini, as: reply } - { kind: openai, model: gpt-5.4-nano, as: fill } """; - } + } +} diff --git a/tests/AgentCore.Application.Tests/Policy/GoldenConversationReplayTests.cs b/tests/AgentCore.Application.Tests/Policy/GoldenConversationReplayTests.cs index 2578e738..c4c3586b 100644 --- a/tests/AgentCore.Application.Tests/Policy/GoldenConversationReplayTests.cs +++ b/tests/AgentCore.Application.Tests/Policy/GoldenConversationReplayTests.cs @@ -1,89 +1,94 @@ +using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Policy; using AgentCore.Application.Tests.Fakes; using Xunit; -namespace AgentCore.Application.Tests.Policy; - -/// -/// Rule 15 of section 11. The six golden conversations of spike/callpolicy replay against a -/// configuration-declared policy and reproduce the hand-written machine exactly. -/// -public sealed class GoldenConversationReplayTests +namespace AgentCore.Application.Tests.Policy { - private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(GoldenSet.Yaml); - - public static TheoryData ConversationNames() + /// + /// Rule 15 of section 11. The six golden conversations of spike/callpolicy replay against a + /// configuration-declared policy and reproduce the hand-written machine exactly. + /// + public sealed class GoldenConversationReplayTests { - TheoryData names = []; - foreach (var conversation in GoldenSet.Conversations) + private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(GoldenSet.Yaml); + + public static TheoryData ConversationNames() { - names.Add(conversation.Name); - } + TheoryData names = []; + foreach (GoldenConversation conversation in GoldenSet.Conversations) + { + names.Add(conversation.Name); + } - return names; - } + return names; + } - [Fact] - public void GoldenSet_HoldsSixConversations() => Assert.Equal(6, GoldenSet.Conversations.Count); + [Fact] + public void GoldenSet_HoldsSixConversations() + { + Assert.Equal(6, GoldenSet.Conversations.Count); + } - [Theory] - [MemberData(nameof(ConversationNames))] - public void GoldenConversation_ReplaysThroughTheDeclaredPolicyExactly(string name) - { - var conversation = GoldenSet.Conversations.Single(candidate => string.Equals(candidate.Name, name, StringComparison.Ordinal)); + [Theory] + [MemberData(nameof(ConversationNames))] + public void GoldenConversation_ReplaysThroughTheDeclaredPolicyExactly(string name) + { + GoldenConversation conversation = GoldenSet.Conversations.Single(candidate => string.Equals(candidate.Name, name, StringComparison.Ordinal)); - var expected = GoldenSet.ReplayHandWritten(conversation).Select(Transitions.ToStageId).ToList(); - var actual = ReplayDeclared(conversation); + List expected = [.. GoldenSet.ReplayHandWritten(conversation).Select(Transitions.ToStageId)]; + List actual = ReplayDeclared(conversation); - Assert.Equal(expected, actual); - } + Assert.Equal(expected, actual); + } - [Fact] - public void EveryGoldenConversation_ReplaysThroughTheDeclaredPolicyExactly() - { - foreach (var conversation in GoldenSet.Conversations) + [Fact] + public void EveryGoldenConversation_ReplaysThroughTheDeclaredPolicyExactly() { - var expected = GoldenSet.ReplayHandWritten(conversation).Select(Transitions.ToStageId).ToList(); - Assert.Equal(expected, ReplayDeclared(conversation)); + foreach (GoldenConversation conversation in GoldenSet.Conversations) + { + List expected = [.. GoldenSet.ReplayHandWritten(conversation).Select(Transitions.ToStageId)]; + Assert.Equal(expected, ReplayDeclared(conversation)); + } } - } - [Fact] - public void HumanRequest_BeatsAResolvedFix() - { - var conversation = GoldenSet.Conversations.Single(candidate => - string.Equals(candidate.Name, "human-request-beats-a-resolved-fix", StringComparison.Ordinal)); + [Fact] + public void HumanRequest_BeatsAResolvedFix() + { + GoldenConversation conversation = GoldenSet.Conversations.Single(candidate => + string.Equals(candidate.Name, "human-request-beats-a-resolved-fix", StringComparison.Ordinal)); - // Both resolved and callerAskedForHuman are true on the last turn, and the answer is escalate. - Assert.Equal("escalate", ReplayDeclared(conversation)[^1]); - } + // Both resolved and callerAskedForHuman are true on the last turn, and the answer is escalate. + Assert.Equal("escalate", ReplayDeclared(conversation)[^1]); + } - [Fact] - public void DeclaredPolicy_RendersEachGuardNameNextToItsEdge() - { - StagePolicy policy = new(Document.Entries["main"].Policy!, new TestGuardEvaluator(Document)); + [Fact] + public void DeclaredPolicy_RendersEachGuardNameNextToItsEdge() + { + StagePolicy policy = new(Document.Entries["main"].Policy!, new TestGuardEvaluator(Document)); - var mermaid = policy.ToMermaid(); + string mermaid = policy.ToMermaid(); - // Section 8.4: a name renders, and an inline JSONLogic tree renders as an unreadable blob. - Assert.Contains("wantsHuman", mermaid, StringComparison.Ordinal); - Assert.Contains("humanOrExhausted", mermaid, StringComparison.Ordinal); - Assert.DoesNotContain("callerSaidGoodbye", mermaid, StringComparison.Ordinal); - } - - private static List ReplayDeclared(GoldenConversation conversation) - { - StagePolicy policy = new(Document.Entries["main"].Policy!, new TestGuardEvaluator(Document)); + // Section 8.4: a name renders, and an inline JSONLogic tree renders as an unreadable blob. + Assert.Contains("wantsHuman", mermaid, StringComparison.Ordinal); + Assert.Contains("humanOrExhausted", mermaid, StringComparison.Ordinal); + Assert.DoesNotContain("callerSaidGoodbye", mermaid, StringComparison.Ordinal); + } - List stages = new(conversation.Turns.Count); - for (var index = 0; index < conversation.Turns.Count; index++) + private static List ReplayDeclared(GoldenConversation conversation) { - var snapshot = conversation.Turns[index].Facts.ToSnapshot(policy.Stage, index); - stages.Add(policy.Advance(snapshot)); - } + StagePolicy policy = new(Document.Entries["main"].Policy!, new TestGuardEvaluator(Document)); + + List stages = new(conversation.Turns.Count); + for (int index = 0; index < conversation.Turns.Count; index++) + { + IReadOnlyDictionary snapshot = conversation.Turns[index].Facts.ToSnapshot(policy.Stage, index); + stages.Add(policy.Advance(snapshot)); + } - return stages; + return stages; + } } } diff --git a/tests/AgentCore.Application.Tests/Policy/StagePolicyTests.cs b/tests/AgentCore.Application.Tests/Policy/StagePolicyTests.cs index 5afc2703..db8e0a8f 100644 --- a/tests/AgentCore.Application.Tests/Policy/StagePolicyTests.cs +++ b/tests/AgentCore.Application.Tests/Policy/StagePolicyTests.cs @@ -5,15 +5,15 @@ using AgentCore.Application.Tests.Fakes; using Xunit; -namespace AgentCore.Application.Tests.Policy; - -/// -/// The stage machine of row 2 of the section 8.2 compile table. -/// -public sealed class StagePolicyTests +namespace AgentCore.Application.Tests.Policy { - private const string StayDocument = - """ + /// + /// The stage machine of row 2 of the section 8.2 compile table. + /// + public sealed class StagePolicyTests + { + private const string StayDocument = + """ apiVersion: agentcore/v1 state: ready: { type: boolean, default: false, writer: extractor } @@ -36,8 +36,8 @@ public sealed class StagePolicyTests terminal: true """; - private const string ErrorDocument = - """ + private const string ErrorDocument = + """ apiVersion: agentcore/v1 state: ready: { type: boolean, default: false, writer: extractor } @@ -61,8 +61,8 @@ public sealed class StagePolicyTests terminal: true """; - private const string OverlapDocument = - """ + private const string OverlapDocument = + """ apiVersion: agentcore/v1 state: ready: { type: boolean, default: false, writer: extractor } @@ -92,59 +92,59 @@ public sealed class StagePolicyTests terminal: true """; - [Fact] - public void ZeroGuardsTrue_KeepsTheStageWhereItIs() - { - var (policy, _) = Build(StayDocument); + [Fact] + public void ZeroGuardsTrue_KeepsTheStageWhereItIs() + { + (StagePolicy? policy, TestGuardEvaluator _) = Build(StayDocument); - // Zero guards true is the normal case, and it matches OnUnhandledTrigger. - Assert.Equal("one", policy.Advance(Snapshot(ready: false))); - Assert.Equal("one", policy.Advance(Snapshot(ready: false))); - } + // Zero guards true is the normal case, and it matches OnUnhandledTrigger. + Assert.Equal("one", policy.Advance(Snapshot(ready: false))); + Assert.Equal("one", policy.Advance(Snapshot(ready: false))); + } - [Fact] - public void OneGuardTrue_MovesToThatStage() - { - var (policy, _) = Build(StayDocument); + [Fact] + public void OneGuardTrue_MovesToThatStage() + { + (StagePolicy? policy, TestGuardEvaluator _) = Build(StayDocument); - Assert.Equal("two", policy.Advance(Snapshot(ready: true))); - Assert.True(policy.IsTerminal); - Assert.Equal("second", policy.CurrentAgentId); - } + Assert.Equal("two", policy.Advance(Snapshot(ready: true))); + Assert.True(policy.IsTerminal); + Assert.Equal("second", policy.CurrentAgentId); + } - [Fact] - public void ATerminalStage_StaysTerminal() - { - var (policy, _) = Build(StayDocument); + [Fact] + public void ATerminalStage_StaysTerminal() + { + (StagePolicy? policy, _) = Build(StayDocument); - policy.Advance(Snapshot(ready: true)); - Assert.Equal("two", policy.Advance(Snapshot(ready: true))); - } + _ = policy.Advance(Snapshot(ready: true)); + Assert.Equal("two", policy.Advance(Snapshot(ready: true))); + } - [Fact] - public void OnNoMatchError_RejectsTheZeroGuardsTrueCase() - { - var (policy, _) = Build(ErrorDocument); + [Fact] + public void OnNoMatchError_RejectsTheZeroGuardsTrueCase() + { + (StagePolicy? policy, TestGuardEvaluator _) = Build(ErrorDocument); - var failure = Assert.Throws(() => policy.Advance(Snapshot(ready: false))); + InvalidOperationException failure = Assert.Throws(() => policy.Advance(Snapshot(ready: false))); - Assert.Contains("onNoMatch: error", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("onNoMatch: error", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void TwoSiblingGuardsTrue_Throws() - { - var (policy, _) = Build(OverlapDocument); + [Fact] + public void TwoSiblingGuardsTrue_Throws() + { + (StagePolicy? policy, _) = Build(OverlapDocument); - // Stateless throws on the first overlap. Check 5 of section 8.5 finds every one at startup. - Assert.ThrowsAny(() => policy.Advance(Snapshot(ready: true))); - } + // Stateless throws on the first overlap. Check 5 of section 8.5 finds every one at startup. + _ = Assert.ThrowsAny(() => policy.Advance(Snapshot(ready: true))); + } - [Fact] - public void AGuardThatThrows_IsFalseAndTheConversationContinues() - { - var (policy, guards) = Build( - """ + [Fact] + public void AGuardThatThrows_IsFalseAndTheConversationContinues() + { + (StagePolicy? policy, TestGuardEvaluator? guards) = Build( + """ apiVersion: agentcore/v1 state: count: { type: integer, default: 0, writer: counter, increment: { var: count } } @@ -167,36 +167,39 @@ public void AGuardThatThrows_IsFalseAndTheConversationContinues() terminal: true """); - var snapshot = new Dictionary(StringComparer.Ordinal) - { - ["count"] = JsonValue.Create(1), - }; + Dictionary snapshot = new(StringComparer.Ordinal) + { + ["count"] = JsonValue.Create(1), + }; - // The rule is the operand shorthand the library refuses at run time, and check 4 cannot see - // every such case. Section 8.7: log once, treat the guard as false, and continue. - Assert.Equal("one", policy.Advance(snapshot)); - Assert.Equal(1, guards.Failures); - } + // The rule is the operand shorthand the library refuses at run time, and check 4 cannot see + // every such case. Section 8.7: log once, treat the guard as false, and continue. + Assert.Equal("one", policy.Advance(snapshot)); + Assert.Equal(1, guards.Failures); + } - [Fact] - public void AnUndeclaredInitialStage_Throws() - { - AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(StayDocument); - PolicyConfiguration broken = document.Entries["main"].Policy! with { Initial = "nowhere" }; + [Fact] + public void AnUndeclaredInitialStage_Throws() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(StayDocument); + PolicyConfiguration broken = document.Entries["main"].Policy! with { Initial = "nowhere" }; - Assert.Throws(() => new StagePolicy(broken, new TestGuardEvaluator(document))); - } + _ = Assert.Throws(() => new StagePolicy(broken, new TestGuardEvaluator(document))); + } - private static (StagePolicy Policy, TestGuardEvaluator Guards) Build(string yaml) - { - var document = ConfigurationLoader.LoadYaml(yaml); - TestGuardEvaluator guards = new(document); - return (new StagePolicy(document.Entries["main"].Policy!, guards), guards); - } + private static (StagePolicy Policy, TestGuardEvaluator Guards) Build(string yaml) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + TestGuardEvaluator guards = new(document); + return (new StagePolicy(document.Entries["main"].Policy!, guards), guards); + } - private static Dictionary Snapshot(bool ready) - => new Dictionary(StringComparer.Ordinal) + private static Dictionary Snapshot(bool ready) { - ["ready"] = JsonValue.Create(ready), - }; + return new Dictionary(StringComparer.Ordinal) + { + ["ready"] = JsonValue.Create(ready), + }; + } + } } diff --git a/tests/AgentCore.Application.Tests/Ports/VendorAdapterTests.cs b/tests/AgentCore.Application.Tests/Ports/VendorAdapterTests.cs index 97895a58..286412af 100644 --- a/tests/AgentCore.Application.Tests/Ports/VendorAdapterTests.cs +++ b/tests/AgentCore.Application.Tests/Ports/VendorAdapterTests.cs @@ -1,32 +1,34 @@ +using System.Reflection; using AgentCore.Application.Ports; using Xunit; -namespace AgentCore.Application.Tests.Ports; - -/// Pins that every vendor seam shares one base, so one selector can serve them all. -public sealed class VendorAdapterTests +namespace AgentCore.Application.Tests.Ports { - [Theory] - [InlineData(typeof(IChatClientAdapter))] - [InlineData(typeof(IKnowledgeStoreAdapter))] - [InlineData(typeof(IModerationAdapter))] - [InlineData(typeof(ITelemetryAdapter))] - [InlineData(typeof(ISpeechAdapter))] - [InlineData(typeof(IConversationAdapter))] - public void EveryVendorSeamDerivesFromTheOneBase(Type seam) + /// Pins that every vendor seam shares one base, so one selector can serve them all. + public sealed class VendorAdapterTests { - Assert.True( - typeof(IVendorAdapter).IsAssignableFrom(seam), - $"{seam.Name} must derive from IVendorAdapter so VendorAdapterSelector can serve it."); - } + [Theory] + [InlineData(typeof(IChatClientAdapter))] + [InlineData(typeof(IKnowledgeStoreAdapter))] + [InlineData(typeof(IModerationAdapter))] + [InlineData(typeof(ITelemetryAdapter))] + [InlineData(typeof(ISpeechAdapter))] + [InlineData(typeof(IConversationAdapter))] + public void EveryVendorSeamDerivesFromTheOneBase(Type seam) + { + Assert.True( + typeof(IVendorAdapter).IsAssignableFrom(seam), + $"{seam.Name} must derive from IVendorAdapter so VendorAdapterSelector can serve it."); + } - [Fact] - public void TheBaseCarriesOnlyTheKind() - { - var members = typeof(IVendorAdapter).GetMembers(); + [Fact] + public void TheBaseCarriesOnlyTheKind() + { + MemberInfo[] members = typeof(IVendorAdapter).GetMembers(); - // One property means one getter method plus the property itself. - Assert.Equal(2, members.Length); - Assert.NotNull(typeof(IVendorAdapter).GetProperty("Kind")); + // One property means one getter method plus the property itself. + Assert.Equal(2, members.Length); + Assert.NotNull(typeof(IVendorAdapter).GetProperty("Kind")); + } } } diff --git a/tests/AgentCore.Application.Tests/Providers/VendorAdapterSelectorTests.cs b/tests/AgentCore.Application.Tests/Providers/VendorAdapterSelectorTests.cs index ebc61348..ddee479d 100644 --- a/tests/AgentCore.Application.Tests/Providers/VendorAdapterSelectorTests.cs +++ b/tests/AgentCore.Application.Tests/Providers/VendorAdapterSelectorTests.cs @@ -3,133 +3,134 @@ using AgentCore.Application.Providers; using Xunit; -namespace AgentCore.Application.Tests.Providers; - -/// -/// The one selection every vendor seam shares: a kind in the document, and the one adapter -/// the host registered for it. -/// -/// -/// This replaces SpeechAdapterSelectorTests. The seam it is proven through is still speech, -/// because that is the seam whose wording the shared selector was lifted from, but nothing here is -/// speech-specific: the adapter is an and the seam is a parameter. -/// -public sealed class VendorAdapterSelectorTests +namespace AgentCore.Application.Tests.Providers { - private static readonly VendorSeam SpeechSeam = - new("providers.speech", "/providers/speech/stt/kind", "options.UseSpeech(...)"); - - private sealed class FakeAdapter(string kind) : IVendorAdapter - { - public string Kind { get; } = kind; - } - - [Fact] - public void TheNamedKindIsSelected() - { - var relay = new FakeAdapter("telnyx-relay"); - - var selected = VendorAdapterSelector.Select( - "telnyx-relay", [new FakeAdapter("deepgram"), relay], SpeechSeam); - - Assert.Same(relay, selected); - } - - [Fact] - public void TheKindMatchesWithoutRegardToCase() - { - var relay = new FakeAdapter("telnyx-relay"); - - var selected = VendorAdapterSelector.Select("TELNYX-RELAY", [relay], SpeechSeam); - - Assert.Same(relay, selected); - } - - [Fact] - public void AKindNoAdapterServesFailsTheStart() - { - var failure = Assert.Throws( - () => VendorAdapterSelector.Select( - "deepgram", [new FakeAdapter("telnyx-relay")], SpeechSeam)); - - Assert.Contains("deepgram", failure.Message, StringComparison.Ordinal); - Assert.Contains("'telnyx-relay'", failure.Message, StringComparison.Ordinal); - Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); - Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Errors[0].Check); - } - - [Fact] - public void AHostThatRegisteredNothingIsToldWhichConversationToMake() - { - var failure = Assert.Throws( - // The type argument is written out because an empty list infers no adapter type. - () => VendorAdapterSelector.Select("deepgram", [], SpeechSeam)); - - Assert.Contains("no adapter", failure.Message, StringComparison.Ordinal); - Assert.Contains("options.UseSpeech(...)", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void TwoAdaptersForOneKindFailTheStart() - { - var failure = Assert.Throws( - () => VendorAdapterSelector.Select( - "telnyx-relay", - [new FakeAdapter("telnyx-relay"), new FakeAdapter("telnyx-relay")], - SpeechSeam)); - - Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); - Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); - } - - [Fact] - public void TheSeamNamesItselfInEveryMessage() - { - var telemetrySeam = new VendorSeam( - "providers.telemetry", "/providers/telemetry/kind", "options.UseTelemetry(...)"); - - var failure = Assert.Throws( - () => VendorAdapterSelector.Select("grafana", [], telemetrySeam)); - - Assert.Contains("providers.telemetry", failure.Message, StringComparison.Ordinal); - Assert.Contains("options.UseTelemetry(...)", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void NullAdaptersAreRefused() - { - Assert.Throws( - () => VendorAdapterSelector.Select("openai", null!, SpeechSeam)); - } - - [Fact] - public void EachSeamKeepsItsOwnPluralNoun() - { - // Four seams wrote "stores", "collectors", "endpoints", and "vendors" before they shared one - // selector. The plural noun is a seam's own word, so it travels with the seam. - var knowledgeSeam = new VendorSeam( - "providers.knowledge.search", "/providers/knowledge/search", "options.UseKnowledge(...)", "stores"); - - var failure = Assert.Throws( - () => VendorAdapterSelector.Select( - "filesystem", - [new FakeAdapter("filesystem"), new FakeAdapter("filesystem")], - knowledgeSeam)); - - Assert.Contains("names two stores", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public void ASeamThatNamesNoPluralSaysVendors() + /// + /// The one selection every vendor seam shares: a kind in the document, and the one adapter + /// the host registered for it. + /// + /// + /// This replaces SpeechAdapterSelectorTests. The seam it is proven through is still speech, + /// because that is the seam whose wording the shared selector was lifted from, but nothing here is + /// speech-specific: the adapter is an and the seam is a parameter. + /// + public sealed class VendorAdapterSelectorTests { - var failure = Assert.Throws( - () => VendorAdapterSelector.Select( - "telnyx-relay", - [new FakeAdapter("telnyx-relay"), new FakeAdapter("telnyx-relay")], - SpeechSeam)); - - // The three-argument constructor is what keeps the speech wording, and it is the default - // every seam that never had a noun of its own gets. - Assert.Contains("names two vendors", failure.Message, StringComparison.Ordinal); + private static readonly VendorSeam SpeechSeam = + new("providers.speech", "/providers/speech/stt/kind", "options.UseSpeech(...)"); + + private sealed class FakeAdapter(string kind) : IVendorAdapter + { + public string Kind { get; } = kind; + } + + [Fact] + public void TheNamedKindIsSelected() + { + FakeAdapter relay = new("telnyx-relay"); + + FakeAdapter selected = VendorAdapterSelector.Select( + "telnyx-relay", [new FakeAdapter("deepgram"), relay], SpeechSeam); + + Assert.Same(relay, selected); + } + + [Fact] + public void TheKindMatchesWithoutRegardToCase() + { + FakeAdapter relay = new("telnyx-relay"); + + FakeAdapter selected = VendorAdapterSelector.Select("TELNYX-RELAY", [relay], SpeechSeam); + + Assert.Same(relay, selected); + } + + [Fact] + public void AKindNoAdapterServesFailsTheStart() + { + ConfigurationLoadException failure = Assert.Throws( + () => VendorAdapterSelector.Select( + "deepgram", [new FakeAdapter("telnyx-relay")], SpeechSeam)); + + Assert.Contains("deepgram", failure.Message, StringComparison.Ordinal); + Assert.Contains("'telnyx-relay'", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); + Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Errors[0].Check); + } + + [Fact] + public void AHostThatRegisteredNothingIsToldWhichConversationToMake() + { + ConfigurationLoadException failure = Assert.Throws( + // The type argument is written out because an empty list infers no adapter type. + () => VendorAdapterSelector.Select("deepgram", [], SpeechSeam)); + + Assert.Contains("no adapter", failure.Message, StringComparison.Ordinal); + Assert.Contains("options.UseSpeech(...)", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void TwoAdaptersForOneKindFailTheStart() + { + ConfigurationLoadException failure = Assert.Throws( + () => VendorAdapterSelector.Select( + "telnyx-relay", + [new FakeAdapter("telnyx-relay"), new FakeAdapter("telnyx-relay")], + SpeechSeam)); + + Assert.Contains("two adapters", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); + } + + [Fact] + public void TheSeamNamesItselfInEveryMessage() + { + VendorSeam telemetrySeam = new( + "providers.telemetry", "/providers/telemetry/kind", "options.UseTelemetry(...)"); + + ConfigurationLoadException failure = Assert.Throws( + () => VendorAdapterSelector.Select("grafana", [], telemetrySeam)); + + Assert.Contains("providers.telemetry", failure.Message, StringComparison.Ordinal); + Assert.Contains("options.UseTelemetry(...)", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void NullAdaptersAreRefused() + { + _ = Assert.Throws( + () => VendorAdapterSelector.Select("openai", null!, SpeechSeam)); + } + + [Fact] + public void EachSeamKeepsItsOwnPluralNoun() + { + // Four seams wrote "stores", "collectors", "endpoints", and "vendors" before they shared one + // selector. The plural noun is a seam's own word, so it travels with the seam. + VendorSeam knowledgeSeam = new( + "providers.knowledge.search", "/providers/knowledge/search", "options.UseKnowledge(...)", "stores"); + + ConfigurationLoadException failure = Assert.Throws( + () => VendorAdapterSelector.Select( + "filesystem", + [new FakeAdapter("filesystem"), new FakeAdapter("filesystem")], + knowledgeSeam)); + + Assert.Contains("names two stores", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public void ASeamThatNamesNoPluralSaysVendors() + { + ConfigurationLoadException failure = Assert.Throws( + () => VendorAdapterSelector.Select( + "telnyx-relay", + [new FakeAdapter("telnyx-relay"), new FakeAdapter("telnyx-relay")], + SpeechSeam)); + + // The three-argument constructor is what keeps the speech wording, and it is the default + // every seam that never had a noun of its own gets. + Assert.Contains("names two vendors", failure.Message, StringComparison.Ordinal); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentSessionTests.cs b/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentSessionTests.cs index f4be8079..9ce1eee8 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentSessionTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentSessionTests.cs @@ -8,357 +8,359 @@ using System.Text.Json.Nodes; using Xunit; using static AgentCore.Application.Tests.Runtime.AgentCoreAgentTestSupport; +using Microsoft.Agents.AI; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The shim's session envelope: what -/// SerializeSessionAsync/DeserializeSessionAsync carry across a checkpoint, and what a -/// resumed conversation keeps of store 0's own record. -/// -public sealed class AgentCoreAgentSessionTests +namespace AgentCore.Application.Tests.Runtime { - [Fact] - public async Task SerializeSessionAsync_WritesTheStateTheConversationHolds() + /// + /// The shim's session envelope: what + /// SerializeSessionAsync/DeserializeSessionAsync carry across a checkpoint, and what a + /// resumed conversation keeps of store 0's own record. + /// + public sealed class AgentCoreAgentSessionTests { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); + [Fact] + public async Task SerializeSessionAsync_WritesTheStateTheConversationHolds() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); - var conversation = session.GetService(); - Assert.NotNull(conversation); - Assert.True(conversation.State.TryWrite("escalate", JsonValue.Create(true))); + ConversationSession? conversation = session.GetService(); + Assert.NotNull(conversation); + Assert.True(conversation.State.TryWrite("escalate", JsonValue.Create(true))); - var serialized = await agent.SerializeSessionAsync( - session, cancellationToken: TestContext.Current.CancellationToken); + JsonElement serialized = await agent.SerializeSessionAsync( + session, cancellationToken: TestContext.Current.CancellationToken); - var read = serialized.GetProperty("state").Deserialize(ConversationStateJson.Options); + ConversationSessionState? read = serialized.GetProperty("state").Deserialize(ConversationStateJson.Options); - Assert.NotNull(read); - Assert.Equal(ConversationSessionState.CurrentVersion, read.Version); - Assert.Equal(conversation.Stage, read.Stage); - Assert.True(read.Slots["escalate"]!.GetValue()); - } - - [Fact] - public async Task SerializeSessionAsync_NamesTheConversationTheStateBelongsTo() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _); - var session = await agent.CreateSessionAsync("conversation-42", TestContext.Current.CancellationToken); + Assert.NotNull(read); + Assert.Equal(ConversationSessionState.CurrentVersion, read.Version); + Assert.Equal(conversation.Stage, read.Stage); + Assert.True(read.Slots["escalate"]!.GetValue()); + } - var serialized = await agent.SerializeSessionAsync( - session, cancellationToken: TestContext.Current.CancellationToken); + [Fact] + public async Task SerializeSessionAsync_NamesTheConversationTheStateBelongsTo() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _); + AgentSession session = await agent.CreateSessionAsync("conversation-42"); - // Store 1 is keyed by conversation id. State that travelled without one would come back on a conversation - // that has no words behind it, which is the one failure this envelope exists to prevent. - Assert.Equal("conversation-42", serialized.GetProperty("conversationId").GetString()); - } + JsonElement serialized = await agent.SerializeSessionAsync( + session, cancellationToken: TestContext.Current.CancellationToken); - [Fact] - public async Task SerializeSessionAsync_NoSession_IsRefusedRatherThanAnsweredWithAFreshConversation() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _); - - // A run answers a null session by making one — the framework's one-shot shape, a conversation nothing - // continues. There is no one-shot serialize: the envelope would name a fresh random id beside - // an empty state, and a host would keep that as its checkpoint and never learn it points at - // nothing. - await Assert.ThrowsAsync(async () => - await agent.SerializeSessionAsync(null!, cancellationToken: TestContext.Current.CancellationToken)); - } + // Store 1 is keyed by conversation id. State that travelled without one would come back on a conversation + // that has no words behind it, which is the one failure this envelope exists to prevent. + Assert.Equal("conversation-42", serialized.GetProperty("conversationId").GetString()); + } - [Fact] - public async Task ARoundTrip_ComesBackOnTheSameConversation() - { - var agent = BuildAgent(new SequencedChatClient("a reply", "another reply"), out _); - var session = await agent.CreateSessionAsync("conversation-42", TestContext.Current.CancellationToken); - _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); - - var serialized = await agent.SerializeSessionAsync( - session, cancellationToken: TestContext.Current.CancellationToken); - var revived = await agent.DeserializeSessionAsync( - serialized, cancellationToken: TestContext.Current.CancellationToken); + [Fact] + public async Task SerializeSessionAsync_NoSession_IsRefusedRatherThanAnsweredWithAFreshConversation() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _); + + // A run answers a null session by making one — the framework's one-shot shape, a conversation nothing + // continues. There is no one-shot serialize: the envelope would name a fresh random id beside + // an empty state, and a host would keep that as its checkpoint and never learn it points at + // nothing. + _ = await Assert.ThrowsAsync(async () => + await agent.SerializeSessionAsync(null!, cancellationToken: TestContext.Current.CancellationToken)); + } + + [Fact] + public async Task ARoundTrip_ComesBackOnTheSameConversation() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply", "another reply"), out _); + AgentSession session = await agent.CreateSessionAsync("conversation-42"); + _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); - Assert.Equal("conversation-42", revived.GetService()?.ConversationId); - } + JsonElement serialized = await agent.SerializeSessionAsync( + session, cancellationToken: TestContext.Current.CancellationToken); + AgentSession revived = await agent.DeserializeSessionAsync( + serialized, cancellationToken: TestContext.Current.CancellationToken); - [Fact] - public async Task DeserializeSessionAsync_BringsBackAConversationThatCarriesThatState() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + Assert.Equal("conversation-42", revived.GetService()?.ConversationId); + } - ConversationSessionState stored = new() + [Fact] + public async Task DeserializeSessionAsync_BringsBackAConversationThatCarriesThatState() { - Stage = string.Empty, - Slots = new Dictionary(StringComparer.Ordinal) - { - ["escalate"] = JsonValue.Create(true), - }, - }; + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); - var revived = await agent.DeserializeSessionAsync( - Envelope("conversation-42", stored), cancellationToken: TestContext.Current.CancellationToken); + ConversationSessionState stored = new() + { + Stage = string.Empty, + Slots = new Dictionary(StringComparer.Ordinal) + { + ["escalate"] = JsonValue.Create(true), + }, + }; - // The turn is what opens the session, and the session is the one place a conversation resumes from, - // whichever of the two sources it resumes out of. - _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); + AgentSession revived = await agent.DeserializeSessionAsync( + Envelope("conversation-42", stored), cancellationToken: TestContext.Current.CancellationToken); - var conversation = revived.GetService(); + // The turn is what opens the session, and the session is the one place a conversation resumes from, + // whichever of the two sources it resumes out of. + _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); - Assert.NotNull(conversation); - Assert.False(conversation.IsComplete); - Assert.True(conversation.State.Read("escalate")!.GetValue()); - } + ConversationSession? conversation = revived.GetService(); - [Fact] - public async Task ARoundTripBeforeTheFirstTurn_LosesNothing() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + Assert.NotNull(conversation); + Assert.False(conversation.IsComplete); + Assert.True(conversation.State.Read("escalate")!.GetValue()); + } - ConversationSessionState checkpoint = new() + [Fact] + public async Task ARoundTripBeforeTheFirstTurn_LosesNothing() { - Slots = new Dictionary(StringComparer.Ordinal) + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + + ConversationSessionState checkpoint = new() { - ["escalate"] = JsonValue.Create(true), - ["note"] = JsonValue.Create("carried"), - }, - }; - - var revived = await agent.DeserializeSessionAsync( - Envelope("conversation-42", checkpoint), cancellationToken: TestContext.Current.CancellationToken); - - // No turn in between. The restore has not run yet, so a snapshot taken off the state - // document would answer nothing at all — and this host would then write that nothing over - // the checkpoint it just handed in. The seam has to read back what it was given. - var serialized = await agent.SerializeSessionAsync( - revived, cancellationToken: TestContext.Current.CancellationToken); - - Assert.Equal("conversation-42", serialized.GetProperty("conversationId").GetString()); - - var read = serialized.GetProperty("state").Deserialize(ConversationStateJson.Options); - - Assert.NotNull(read); - Assert.True(read.Slots["escalate"]!.GetValue()); - Assert.Equal("carried", read.Slots["note"]!.GetValue()); - - // And the ordinary path is untouched. Once the turn opens the conversation, the document is what - // the conversation would resume from and the checkpoint is spent — so a value written after that - // turn is what comes back, not the one the checkpoint still holds. Store 1's writer reads - // this same method, so a snapshot that kept answering the checkpoint would freeze store 0 - // at the moment the conversation was revived and never record another thing the conversation learned. - _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); - - var conversation = revived.GetService(); - Assert.NotNull(conversation); - Assert.True(conversation.State.TryWrite("note", JsonValue.Create("learned after the turn"))); - - var again = await agent.SerializeSessionAsync( - revived, cancellationToken: TestContext.Current.CancellationToken); - var after = again.GetProperty("state").Deserialize(ConversationStateJson.Options); - - Assert.NotNull(after); - Assert.True(after.Slots["escalate"]!.GetValue()); - Assert.Equal("learned after the turn", after.Slots["note"]!.GetValue()); - } + Slots = new Dictionary(StringComparer.Ordinal) + { + ["escalate"] = JsonValue.Create(true), + ["note"] = JsonValue.Create("carried"), + }, + }; - [Fact] - public async Task DeserializeSessionAsync_WithStateTheDocumentRefuses_StillRunsTheTurn() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + AgentSession revived = await agent.DeserializeSessionAsync( + Envelope("conversation-42", checkpoint), cancellationToken: TestContext.Current.CancellationToken); - // Nothing here is anything Snapshot would write. DeserializeSessionAsync is host-facing, so - // the blob is arbitrary JSON: Restore is best effort and drops each of these with its own - // diagnostic rather than refusing the conversation. - ConversationSessionState stored = new() - { - Stage = "a stage this document never declared", - IsComplete = true, - Slots = new Dictionary(StringComparer.Ordinal) - { - [ReservedStateSlots.Stage] = JsonValue.Create("reserved"), - ["a slot this document never declared"] = JsonValue.Create(1), - }, - }; + // No turn in between. The restore has not run yet, so a snapshot taken off the state + // document would answer nothing at all — and this host would then write that nothing over + // the checkpoint it just handed in. The seam has to read back what it was given. + JsonElement serialized = await agent.SerializeSessionAsync( + revived, cancellationToken: TestContext.Current.CancellationToken); - var revived = await agent.DeserializeSessionAsync( - Envelope("conversation-42", stored), cancellationToken: TestContext.Current.CancellationToken); + Assert.Equal("conversation-42", serialized.GetProperty("conversationId").GetString()); - var reply = await agent.RunAsync( - "hello", revived, cancellationToken: TestContext.Current.CancellationToken); + ConversationSessionState? read = serialized.GetProperty("state").Deserialize(ConversationStateJson.Options); - Assert.Equal("a reply", reply.Text); + Assert.NotNull(read); + Assert.True(read.Slots["escalate"]!.GetValue()); + Assert.Equal("carried", read.Slots["note"]!.GetValue()); - // The refused stage took IsComplete with it: a conversation brought back complete would turn every - // turn away, which is the outcome the best-effort restore exists to avoid. - Assert.False(revived.GetService()?.IsComplete); - } + // And the ordinary path is untouched. Once the turn opens the conversation, the document is what + // the conversation would resume from and the checkpoint is spent — so a value written after that + // turn is what comes back, not the one the checkpoint still holds. Store 1's writer reads + // this same method, so a snapshot that kept answering the checkpoint would freeze store 0 + // at the moment the conversation was revived and never record another thing the conversation learned. + _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); - [Fact] - public async Task SerializeSessionAsync_CarriesNoWords() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - _ = await agent.RunAsync( - "remember this sentence", session, cancellationToken: TestContext.Current.CancellationToken); - - var conversation = session.GetService(); - Assert.NotNull(conversation); - Assert.True(conversation.State.TryWrite("escalate", JsonValue.Create(true))); - - var serialized = await agent.SerializeSessionAsync( - session, cancellationToken: TestContext.Current.CancellationToken); - var raw = serialized.GetRawText(); - - // Something to lose first. On a document with no slots the whole blob is a handful of short - // scalars, and an implementation that wrote {} would pass the two assertions below. - Assert.Contains("escalate", raw, StringComparison.Ordinal); - - // Store 1 is durable already. A checkpoint that carried the words would give one conversation - // two records and one chance to disagree. - Assert.DoesNotContain("remember this sentence", raw, StringComparison.Ordinal); - Assert.DoesNotContain("a reply", raw, StringComparison.Ordinal); - } + ConversationSession? conversation = revived.GetService(); + Assert.NotNull(conversation); + Assert.True(conversation.State.TryWrite("note", JsonValue.Create("learned after the turn"))); - [Fact] - public async Task DeserializeSessionAsync_WhenStore0KnowsTheConversation_Store0Wins() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("conversation-42", TestContext.Current.CancellationToken); - - // Store 0's own copy of this conversation: one word, and the state written in the same batch. - await store.AppendAsync( - "conversation-42", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "an earlier turn"), "m0")], - new ConversationSessionState + JsonElement again = await agent.SerializeSessionAsync( + revived, cancellationToken: TestContext.Current.CancellationToken); + ConversationSessionState? after = again.GetProperty("state").Deserialize(ConversationStateJson.Options); + + Assert.NotNull(after); + Assert.True(after.Slots["escalate"]!.GetValue()); + Assert.Equal("learned after the turn", after.Slots["note"]!.GetValue()); + } + + [Fact] + public async Task DeserializeSessionAsync_WithStateTheDocumentRefuses_StillRunsTheTurn() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + + // Nothing here is anything Snapshot would write. DeserializeSessionAsync is host-facing, so + // the blob is arbitrary JSON: Restore is best effort and drops each of these with its own + // diagnostic rather than refusing the conversation. + ConversationSessionState stored = new() { + Stage = "a stage this document never declared", + IsComplete = true, Slots = new Dictionary(StringComparer.Ordinal) { - ["escalate"] = JsonValue.Create(false), + [ReservedStateSlots.Stage] = JsonValue.Create("reserved"), + ["a slot this document never declared"] = JsonValue.Create(1), }, - }, - TestContext.Current.CancellationToken); + }; + + AgentSession revived = await agent.DeserializeSessionAsync( + Envelope("conversation-42", stored), cancellationToken: TestContext.Current.CancellationToken); - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml, store); + AgentResponse reply = await agent.RunAsync( + "hello", revived, cancellationToken: TestContext.Current.CancellationToken); - // It disagrees with store 0 on one slot and carries a second store 0 knows nothing about. - // The second is what a merge would leak: store 0 has no value to write over it. - ConversationSessionState checkpoint = new() + Assert.Equal("a reply", reply.Text); + + // The refused stage took IsComplete with it: a conversation brought back complete would turn every + // turn away, which is the outcome the best-effort restore exists to avoid. + Assert.False(revived.GetService()?.IsComplete); + } + + [Fact] + public async Task SerializeSessionAsync_CarriesNoWords() { - Slots = new Dictionary(StringComparer.Ordinal) + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + _ = await agent.RunAsync( + "remember this sentence", session, cancellationToken: TestContext.Current.CancellationToken); + + ConversationSession? conversation = session.GetService(); + Assert.NotNull(conversation); + Assert.True(conversation.State.TryWrite("escalate", JsonValue.Create(true))); + + JsonElement serialized = await agent.SerializeSessionAsync( + session, cancellationToken: TestContext.Current.CancellationToken); + string raw = serialized.GetRawText(); + + // Something to lose first. On a document with no slots the whole blob is a handful of short + // scalars, and an implementation that wrote {} would pass the two assertions below. + Assert.Contains("escalate", raw, StringComparison.Ordinal); + + // Store 1 is durable already. A checkpoint that carried the words would give one conversation + // two records and one chance to disagree. + Assert.DoesNotContain("remember this sentence", raw, StringComparison.Ordinal); + Assert.DoesNotContain("a reply", raw, StringComparison.Ordinal); + } + + [Fact] + public async Task DeserializeSessionAsync_WhenStore0KnowsTheConversation_Store0Wins() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("conversation-42", TestContext.Current.CancellationToken); + + // Store 0's own copy of this conversation: one word, and the state written in the same batch. + _ = await store.AppendAsync( + "conversation-42", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "an earlier turn"), "m0")], + new ConversationSessionState + { + Slots = new Dictionary(StringComparer.Ordinal) + { + ["escalate"] = JsonValue.Create(false), + }, + }, + TestContext.Current.CancellationToken); + + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml, store); + + // It disagrees with store 0 on one slot and carries a second store 0 knows nothing about. + // The second is what a merge would leak: store 0 has no value to write over it. + ConversationSessionState checkpoint = new() { - ["escalate"] = JsonValue.Create(true), - ["note"] = JsonValue.Create("from the checkpoint"), - }, - }; + Slots = new Dictionary(StringComparer.Ordinal) + { + ["escalate"] = JsonValue.Create(true), + ["note"] = JsonValue.Create("from the checkpoint"), + }, + }; - var revived = await agent.DeserializeSessionAsync( - Envelope("conversation-42", checkpoint), cancellationToken: TestContext.Current.CancellationToken); + AgentSession revived = await agent.DeserializeSessionAsync( + Envelope("conversation-42", checkpoint), cancellationToken: TestContext.Current.CancellationToken); - _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); + _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); - var conversation = revived.GetService(); - Assert.NotNull(conversation); + ConversationSession? conversation = revived.GetService(); + Assert.NotNull(conversation); - // False, which is store 0's value and not the checkpoint's. Store 0's blob rides the same - // batch as the words above, so its state and store 1's words are of one moment; a - // checkpoint's state beside those same words can be of two. One precedence, stated. - Assert.False(conversation.State.Read("escalate")!.GetValue()); + // False, which is store 0's value and not the checkpoint's. Store 0's blob rides the same + // batch as the words above, so its state and store 1's words are of one moment; a + // checkpoint's state beside those same words can be of two. One precedence, stated. + Assert.False(conversation.State.Read("escalate")!.GetValue()); - // And store 0 wins outright rather than per slot. Where store 0 holds state, the checkpoint - // contributes nothing at all — not even the slot store 0 never heard of. - Assert.True(conversation.State.IsUnfilled("note")); - } + // And store 0 wins outright rather than per slot. Where store 0 holds state, the checkpoint + // contributes nothing at all — not even the slot store 0 never heard of. + Assert.True(conversation.State.IsUnfilled("note")); + } - [Fact] - public async Task DeserializeSessionAsync_WithNeitherMember_Throws() - { - var agent = BuildAgent(new SequencedChatClient("unused"), out _, SlottedAgentYaml); + [Fact] + public async Task DeserializeSessionAsync_WithNeitherMember_Throws() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("unused"), out _, SlottedAgentYaml); - // The bare ConversationSessionState: the literal value store 0 keeps in conversation.state, and the other - // of the two shapes in this system. Read as an envelope it names no conversation, and a new random - // id would take the conversation's whole transcript with it. - var bare = JsonSerializer.SerializeToElement( - new ConversationSessionState { Stage = string.Empty }, ConversationStateJson.Options); + // The bare ConversationSessionState: the literal value store 0 keeps in conversation.state, and the other + // of the two shapes in this system. Read as an envelope it names no conversation, and a new random + // id would take the conversation's whole transcript with it. + JsonElement bare = JsonSerializer.SerializeToElement( + new ConversationSessionState { Stage = string.Empty }, ConversationStateJson.Options); - var failure = await Assert.ThrowsAsync( - async () => await agent.DeserializeSessionAsync( - bare, cancellationToken: TestContext.Current.CancellationToken)); + ArgumentException failure = await Assert.ThrowsAsync( + async () => await agent.DeserializeSessionAsync( + bare, cancellationToken: TestContext.Current.CancellationToken)); - Assert.Contains("{ conversationId, state }", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("{ conversationId, state }", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task DeserializeSessionAsync_WithStateButNoConversationId_StartsANewConversation() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + [Fact] + public async Task DeserializeSessionAsync_WithStateButNoConversationId_StartsANewConversation() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); - // Lenient on purpose, and the remark promises it: state without an id is still state, and a - // conversation that names none gets one made up, exactly as CreateSessionAsync does. - var named = JsonSerializer.SerializeToElement( - new Dictionary(StringComparer.Ordinal) - { - ["state"] = JsonSerializer.SerializeToNode( - new ConversationSessionState - { - Slots = new Dictionary(StringComparer.Ordinal) + // Lenient on purpose, and the remark promises it: state without an id is still state, and a + // conversation that names none gets one made up, exactly as CreateSessionAsync does. + JsonElement named = JsonSerializer.SerializeToElement( + new Dictionary(StringComparer.Ordinal) + { + ["state"] = JsonSerializer.SerializeToNode( + new ConversationSessionState { - ["escalate"] = JsonValue.Create(true), + Slots = new Dictionary(StringComparer.Ordinal) + { + ["escalate"] = JsonValue.Create(true), + }, }, - }, - ConversationStateJson.Options), - }, - ConversationStateJson.Options); + ConversationStateJson.Options), + }, + ConversationStateJson.Options); - var revived = await agent.DeserializeSessionAsync( - named, cancellationToken: TestContext.Current.CancellationToken); + AgentSession revived = await agent.DeserializeSessionAsync( + named, cancellationToken: TestContext.Current.CancellationToken); - var conversation = revived.GetService(); + ConversationSession? conversation = revived.GetService(); - Assert.NotNull(conversation); - Assert.NotEmpty(conversation.ConversationId); + Assert.NotNull(conversation); + Assert.NotEmpty(conversation.ConversationId); - _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); + _ = await agent.RunAsync("hello", revived, cancellationToken: TestContext.Current.CancellationToken); - Assert.True(conversation.State.Read("escalate")!.GetValue()); - } + Assert.True(conversation.State.Read("escalate")!.GetValue()); + } - [Fact] - public async Task ARoundTripOfATerminalConversation_ComesBackTerminalAndRefusesItsTurn() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, TerminalAgentYaml); - var session = await agent.CreateSessionAsync("conversation-42", TestContext.Current.CancellationToken); + [Fact] + public async Task ARoundTripOfATerminalConversation_ComesBackTerminalAndRefusesItsTurn() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, TerminalAgentYaml); + AgentSession session = await agent.CreateSessionAsync("conversation-42"); - _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); - Assert.True(session.GetService()!.IsComplete); + _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); + Assert.True(session.GetService()!.IsComplete); - var serialized = await agent.SerializeSessionAsync( - session, cancellationToken: TestContext.Current.CancellationToken); - var revived = await agent.DeserializeSessionAsync( - serialized, cancellationToken: TestContext.Current.CancellationToken); + JsonElement serialized = await agent.SerializeSessionAsync( + session, cancellationToken: TestContext.Current.CancellationToken); + AgentSession revived = await agent.DeserializeSessionAsync( + serialized, cancellationToken: TestContext.Current.CancellationToken); - // A behaviour change worth pinning rather than inferring: before the conversation state blob, a - // reloaded page met a conversation that had forgotten it ended and answered one more turn. - var failure = await Assert.ThrowsAsync( - () => agent.RunAsync("again", revived, cancellationToken: TestContext.Current.CancellationToken)); + // A behaviour change worth pinning rather than inferring: before the conversation state blob, a + // reloaded page met a conversation that had forgotten it ended and answered one more turn. + InvalidOperationException failure = await Assert.ThrowsAsync( + () => agent.RunAsync("again", revived, cancellationToken: TestContext.Current.CancellationToken)); - Assert.Contains("runs no further turn", failure.Message, StringComparison.Ordinal); - Assert.True(revived.GetService()!.IsComplete); - } + Assert.Contains("runs no further turn", failure.Message, StringComparison.Ordinal); + Assert.True(revived.GetService()!.IsComplete); + } - [Fact] - public async Task Resume_AfterTheConversationHasOpened_ThrowsRatherThanDoingNothing() - { - var agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); + [Fact] + public async Task Resume_AfterTheConversationHasOpened_ThrowsRatherThanDoingNothing() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("a reply"), out _, SlottedAgentYaml); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + _ = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); - var conversation = session.GetService(); - Assert.NotNull(conversation); + ConversationSession? conversation = session.GetService(); + Assert.NotNull(conversation); - // The state is read as the session opens and never again, so a late hand-off would be a - // silent no-op. Saying so is the whole reason the guard is here. - var failure = Assert.Throws(() => conversation.Resume(new ConversationSessionState())); + // The state is read as the session opens and never again, so a late hand-off would be a + // silent no-op. Saying so is the whole reason the guard is here. + InvalidOperationException failure = Assert.Throws(() => conversation.Resume(new ConversationSessionState())); - Assert.Contains("already run a turn", failure.Message, StringComparison.Ordinal); + Assert.Contains("already run a turn", failure.Message, StringComparison.Ordinal); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTestSupport.cs b/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTestSupport.cs index 0bfbb8c1..7d3c2c46 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTestSupport.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTestSupport.cs @@ -8,14 +8,15 @@ using Microsoft.Extensions.AI; using System.Text.Json; using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Runtime; - -/// The documents and the shim-building helper the tests share. -internal static class AgentCoreAgentTestSupport +namespace AgentCore.Application.Tests.Runtime { - internal const string SingleAgentYaml = - """ + /// The documents and the shim-building helper the tests share. + internal static class AgentCoreAgentTestSupport + { + internal const string SingleAgentYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -27,10 +28,10 @@ internal static class AgentCoreAgentTestSupport agent: solo """; - // The same row with one declared slot, so the round trip has something of its own to carry. - // SingleAgentYaml declares none, and a document with no slots proves nothing about slots. - internal const string SlottedAgentYaml = - """ + // The same row with one declared slot, so the round trip has something of its own to carry. + // SingleAgentYaml declares none, and a document with no slots proves nothing about slots. + internal const string SlottedAgentYaml = + """ apiVersion: agentcore/v1 state: escalate: { type: boolean, writer: extractor, default: false } @@ -45,10 +46,10 @@ internal static class AgentCoreAgentTestSupport agent: solo """; - // A policy that ends itself after one turn, so a conversation can be driven terminal and then round - // tripped. The guard reads the reserved turnIndex slot, so no extractor and no tool is needed. - internal const string TerminalAgentYaml = - """ + // A policy that ends itself after one turn, so a conversation can be driven terminal and then round + // tripped. The guard reads the reserved turnIndex slot, so no extractor and no tool is needed. + internal const string TerminalAgentYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -66,30 +67,33 @@ internal static class AgentCoreAgentTestSupport - { id: done, agent: solo, terminal: true } """; - internal static AgentCoreAgent BuildAgent( - IChatClient reply, - out CompiledAgent compiled, - string yaml = SingleAgentYaml, - IConversationStore? store = null, - string entryName = "main") - { - var document = ConfigurationLoader.LoadYaml(yaml); - compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new RoutingChatClientFactory(reply)) { ConversationStore = store })[entryName]; + internal static AgentCoreAgent BuildAgent( + IChatClient reply, + out CompiledAgent compiled, + string yaml = SingleAgentYaml, + IConversationStore? store = null, + string entryName = "main") + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new RoutingChatClientFactory(reply)) { ConversationStore = store })[entryName]; - ConversationSessionFactory sessions = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - return new AgentCoreAgent(sessions, entryName); - } + ConversationSessionFactory sessions = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + return new AgentCoreAgent(sessions, entryName); + } - /// Writes what a host hands to DeserializeSessionAsync: a conversation id, its state, and its entry. - internal static JsonElement Envelope(string conversationId, ConversationSessionState state, string entryName = "main") - => JsonSerializer.SerializeToElement( - new Dictionary(StringComparer.Ordinal) - { - ["conversationId"] = JsonValue.Create(conversationId), - ["state"] = JsonSerializer.SerializeToNode(state, ConversationStateJson.Options), - ["entry"] = JsonValue.Create(entryName), - }, - ConversationStateJson.Options); + /// Writes what a host hands to DeserializeSessionAsync: a conversation id, its state, and its entry. + internal static JsonElement Envelope(string conversationId, ConversationSessionState state, string entryName = "main") + { + return JsonSerializer.SerializeToElement( + new Dictionary(StringComparer.Ordinal) + { + ["conversationId"] = JsonValue.Create(conversationId), + ["state"] = JsonSerializer.SerializeToNode(state, ConversationStateJson.Options), + ["entry"] = JsonValue.Create(entryName), + }, + ConversationStateJson.Options); + } + } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTests.cs b/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTests.cs index 1b9e40d9..8b6a95ce 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AgentCoreAgentTests.cs @@ -1,152 +1,154 @@ +using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Runtime; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; using static AgentCore.Application.Tests.Runtime.AgentCoreAgentTestSupport; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The shim: the whole turn loop behind the framework's own -/// seam. One session is one conversation, one run is one turn. -/// -public sealed class AgentCoreAgentTests +namespace AgentCore.Application.Tests.Runtime { - [Fact] - public async Task RunAsync_WithOneSession_RunsTurnsOfOneConversation() + /// + /// The shim: the whole turn loop behind the framework's own + /// seam. One session is one conversation, one run is one turn. + /// + public sealed class AgentCoreAgentTests { - var reply = new SequencedChatClient("first reply", "second reply"); - var agent = BuildAgent(reply, out _); + [Fact] + public async Task RunAsync_WithOneSession_RunsTurnsOfOneConversation() + { + SequencedChatClient reply = new("first reply", "second reply"); + AgentCoreAgent agent = BuildAgent(reply, out _); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - var first = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); - var second = await agent.RunAsync("and again", session, cancellationToken: TestContext.Current.CancellationToken); + AgentResponse first = await agent.RunAsync("hello", session, cancellationToken: TestContext.Current.CancellationToken); + AgentResponse second = await agent.RunAsync("and again", session, cancellationToken: TestContext.Current.CancellationToken); - Assert.Equal("first reply", first.Text); - Assert.Equal("second reply", second.Text); + Assert.Equal("first reply", first.Text); + Assert.Equal("second reply", second.Text); - // The second run carried the whole conversation: turn one's exchange sits in front of turn two. - var request = reply.Requests[1]; - Assert.Contains(request, message => message.Role == ChatRole.User && message.Text == "hello"); - Assert.Contains(request, message => message.Role == ChatRole.Assistant && message.Text == "first reply"); - Assert.Equal("and again", reply.LastUserText(1)); - } - - [Fact] - public async Task RunStreamingAsync_StreamsTheFilteredReply() - { - var reply = new SequencedChatClient("streamed reply"); - var agent = BuildAgent(reply, out _); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + // The second run carried the whole conversation: turn one's exchange sits in front of turn two. + List request = reply.Requests[1]; + Assert.Contains(request, message => message.Role == ChatRole.User && message.Text == "hello"); + Assert.Contains(request, message => message.Role == ChatRole.Assistant && message.Text == "first reply"); + Assert.Equal("and again", reply.LastUserText(1)); + } - List updates = []; - await foreach (var update in agent.RunStreamingAsync( - "hello", session, cancellationToken: TestContext.Current.CancellationToken)) + [Fact] + public async Task RunStreamingAsync_StreamsTheFilteredReply() { - updates.Add(update); + SequencedChatClient reply = new("streamed reply"); + AgentCoreAgent agent = BuildAgent(reply, out _); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + + List updates = []; + await foreach (AgentResponseUpdate update in agent.RunStreamingAsync( + "hello", session, cancellationToken: TestContext.Current.CancellationToken)) + { + updates.Add(update); + } + + Assert.NotEmpty(updates); + Assert.Equal("streamed reply", string.Concat(updates.Select(update => update.Text))); + + // The turn committed: the session's conversation holds the finished turn. + ConversationSession? conversation = session.GetService(); + Assert.NotNull(conversation); + Assert.Equal("streamed reply", conversation.LastTurn?.ReplyText); } - Assert.NotEmpty(updates); - Assert.Equal("streamed reply", string.Concat(updates.Select(update => update.Text))); - - // The turn committed: the session's conversation holds the finished turn. - var conversation = session.GetService(); - Assert.NotNull(conversation); - Assert.Equal("streamed reply", conversation.LastTurn?.ReplyText); - } - - [Fact] - public async Task RunAsync_TakesTheLastUserMessage_AndIgnoresTheHistoryInFront() - { - var reply = new SequencedChatClient("the reply"); - var agent = BuildAgent(reply, out _); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - - // The shape a protocol host sends: history first, the new message last. The session owns - // the transcript, so only the last user message is new. - List messages = - [ - new(ChatRole.User, "an old turn"), - new(ChatRole.Assistant, "an old reply"), - new(ChatRole.User, "the new turn"), - ]; - - _ = await agent.RunAsync(messages, session, cancellationToken: TestContext.Current.CancellationToken); - - Assert.Equal("the new turn", reply.LastUserText(0)); - Assert.DoesNotContain(reply.Requests[0], message => message.Text == "an old reply"); - } + [Fact] + public async Task RunAsync_TakesTheLastUserMessage_AndIgnoresTheHistoryInFront() + { + SequencedChatClient reply = new("the reply"); + AgentCoreAgent agent = BuildAgent(reply, out _); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + + // The shape a protocol host sends: history first, the new message last. The session owns + // the transcript, so only the last user message is new. + List messages = + [ + new(ChatRole.User, "an old turn"), + new(ChatRole.Assistant, "an old reply"), + new(ChatRole.User, "the new turn"), + ]; + + _ = await agent.RunAsync(messages, session, cancellationToken: TestContext.Current.CancellationToken); + + Assert.Equal("the new turn", reply.LastUserText(0)); + Assert.DoesNotContain(reply.Requests[0], message => message.Text == "an old reply"); + } - [Fact] - public async Task RunAsync_WithNoUserMessage_Throws() - { - var agent = BuildAgent(new SequencedChatClient("unused"), out _); + [Fact] + public async Task RunAsync_WithNoUserMessage_Throws() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("unused"), out _); - var failure = await Assert.ThrowsAsync( - () => agent.RunAsync( - [new ChatMessage(ChatRole.Assistant, "not a prompt")], - cancellationToken: TestContext.Current.CancellationToken)); + ArgumentException failure = await Assert.ThrowsAsync( + () => agent.RunAsync( + [new ChatMessage(ChatRole.Assistant, "not a prompt")], + cancellationToken: TestContext.Current.CancellationToken)); - Assert.Contains("no user message", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("no user message", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task RunAsync_WithNoSession_RunsOneShotConversations() - { - var reply = new SequencedChatClient("one", "two"); - var agent = BuildAgent(reply, out _); + [Fact] + public async Task RunAsync_WithNoSession_RunsOneShotConversations() + { + SequencedChatClient reply = new("one", "two"); + AgentCoreAgent agent = BuildAgent(reply, out _); - _ = await agent.RunAsync("first", cancellationToken: TestContext.Current.CancellationToken); - _ = await agent.RunAsync("second", cancellationToken: TestContext.Current.CancellationToken); + _ = await agent.RunAsync("first", cancellationToken: TestContext.Current.CancellationToken); + _ = await agent.RunAsync("second", cancellationToken: TestContext.Current.CancellationToken); - // No session, no continuity: the second run is a new conversation and saw nothing of the first. - Assert.DoesNotContain(reply.Requests[1], message => message.Text == "first"); - Assert.DoesNotContain(reply.Requests[1], message => message.Text == "one"); - } + // No session, no continuity: the second run is a new conversation and saw nothing of the first. + Assert.DoesNotContain(reply.Requests[1], message => message.Text == "first"); + Assert.DoesNotContain(reply.Requests[1], message => message.Text == "one"); + } - [Fact] - public async Task RunAsync_WithAForeignSession_Throws() - { - var agent = BuildAgent(new SequencedChatClient("unused"), out _); + [Fact] + public async Task RunAsync_WithAForeignSession_Throws() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("unused"), out _); - // A session another agent kind created. ChatClientAgent builds one of its own type. - var foreign = await new ChatClientAgent(new SequencedChatClient("other")) - .CreateSessionAsync(TestContext.Current.CancellationToken); + // A session another agent kind created. ChatClientAgent builds one of its own type. + AgentSession foreign = await new ChatClientAgent(new SequencedChatClient("other")) + .CreateSessionAsync(TestContext.Current.CancellationToken); - var failure = await Assert.ThrowsAsync( - () => agent.RunAsync("hello", foreign, cancellationToken: TestContext.Current.CancellationToken)); + ArgumentException failure = await Assert.ThrowsAsync( + () => agent.RunAsync("hello", foreign, cancellationToken: TestContext.Current.CancellationToken)); - Assert.Contains("Incompatible session type", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("Incompatible session type", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task CreateSessionAsync_WithAConversationId_NamesTheConversation() - { - var agent = BuildAgent(new SequencedChatClient("unused"), out _); + [Fact] + public async Task CreateSessionAsync_WithAConversationId_NamesTheConversation() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("unused"), out _); - var session = await agent.CreateSessionAsync("conversation-42", TestContext.Current.CancellationToken); + AgentSession session = await agent.CreateSessionAsync("conversation-42"); - Assert.Equal("conversation-42", session.GetService()?.ConversationId); - } + Assert.Equal("conversation-42", session.GetService()?.ConversationId); + } - [Fact] - public async Task GetService_OnTheSession_AnswersTheConversationSession() - { - var agent = BuildAgent(new SequencedChatClient("unused"), out _); - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + [Fact] + public async Task GetService_OnTheSession_AnswersTheConversationSession() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("unused"), out _); + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - var conversation = session.GetService(); + ConversationSession? conversation = session.GetService(); - Assert.NotNull(conversation); - Assert.Same(conversation, session.GetService()); - } + Assert.NotNull(conversation); + Assert.Same(conversation, session.GetService()); + } - [Fact] - public void Name_ReportsWhatTheHostNamedIt() - { - var agent = BuildAgent(new SequencedChatClient("unused"), out var compiled); + [Fact] + public void Name_ReportsWhatTheHostNamedIt() + { + AgentCoreAgent agent = BuildAgent(new SequencedChatClient("unused"), out CompiledAgent? compiled); - Assert.Equal(compiled.Name, agent.Name); + Assert.Equal(compiled.Name, agent.Name); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AgentSessionAcrossAgentsTests.cs b/tests/AgentCore.Application.Tests/Runtime/AgentSessionAcrossAgentsTests.cs index be52db44..c2e18967 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AgentSessionAcrossAgentsTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AgentSessionAcrossAgentsTests.cs @@ -2,113 +2,117 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// Pins the library fact the transcript paragraph of -/// stands on: one carries a conversation that changes agent. -/// -/// -/// -/// The paragraph used to claim the opposite — "a conversation bound to one agent cannot carry a conversation -/// that changes agent" — and this test is the disproof, kept so a library upgrade that breaks the -/// corrected claim fails here instead of silently re-validating the old design reason. Each agent -/// holds its own ; sharing the -/// is what makes both providers read and -/// write the same state in the one session's bag. -/// -/// -/// The session still owns the transcript, for the reasons the corrected paragraph gives: the -/// barge-in amendment and the failed-turn reshaping have no seam in a library history provider, and -/// the graph rows accept no foreign session. This test guards the FACT, not a design choice. -/// -/// -public sealed class AgentSessionAcrossAgentsTests +namespace AgentCore.Application.Tests.Runtime { - private const string SharedKey = "agentcore.test.transcript"; - - [Fact] - public async Task OneSession_CarriesAConversation_AcrossTwoAgents() + /// + /// Pins the library fact the transcript paragraph of + /// stands on: one carries a conversation that changes agent. + /// + /// + /// + /// The paragraph used to claim the opposite — "a conversation bound to one agent cannot carry a conversation + /// that changes agent" — and this test is the disproof, kept so a library upgrade that breaks the + /// corrected claim fails here instead of silently re-validating the old design reason. Each agent + /// holds its own ; sharing the + /// is what makes both providers read and + /// write the same state in the one session's bag. + /// + /// + /// The session still owns the transcript, for the reasons the corrected paragraph gives: the + /// barge-in amendment and the failed-turn reshaping have no seam in a library history provider, and + /// the graph rows accept no foreign session. This test guards the FACT, not a design choice. + /// + /// + public sealed class AgentSessionAcrossAgentsTests { - var clientA = new EchoingChatClient("A"); - var clientB = new EchoingChatClient("B"); + private const string SharedKey = "agentcore.test.transcript"; - ChatClientAgent agentA = new(clientA, new ChatClientAgentOptions - { - Name = "agent-a", - ChatHistoryProvider = new InMemoryChatHistoryProvider( - new InMemoryChatHistoryProviderOptions { StateKey = SharedKey }), - }); - ChatClientAgent agentB = new(clientB, new ChatClientAgentOptions + [Fact] + public async Task OneSession_CarriesAConversation_AcrossTwoAgents() { - Name = "agent-b", - ChatHistoryProvider = new InMemoryChatHistoryProvider( - new InMemoryChatHistoryProviderOptions { StateKey = SharedKey }), - }); + EchoingChatClient clientA = new("A"); + EchoingChatClient clientB = new("B"); - // One session, created by agent A, then driven across both agents: A, B, A again. - var session = await agentA.CreateSessionAsync(TestContext.Current.CancellationToken); + ChatClientAgent agentA = new(clientA, new ChatClientAgentOptions + { + Name = "agent-a", + ChatHistoryProvider = new InMemoryChatHistoryProvider( + new InMemoryChatHistoryProviderOptions { StateKey = SharedKey }), + }); + ChatClientAgent agentB = new(clientB, new ChatClientAgentOptions + { + Name = "agent-b", + ChatHistoryProvider = new InMemoryChatHistoryProvider( + new InMemoryChatHistoryProviderOptions { StateKey = SharedKey }), + }); - _ = await agentA.RunAsync("turn one", session, cancellationToken: TestContext.Current.CancellationToken); - _ = await agentB.RunAsync("turn two", session, cancellationToken: TestContext.Current.CancellationToken); - _ = await agentA.RunAsync("turn three", session, cancellationToken: TestContext.Current.CancellationToken); + // One session, created by agent A, then driven across both agents: A, B, A again. + AgentSession session = await agentA.CreateSessionAsync(TestContext.Current.CancellationToken); - // What each model actually received: the agent of turn 2 saw turn 1's whole exchange, and - // the agent of turn 3 saw everything, including the turn the OTHER agent spoke. - Assert.Equal(["user:turn one"], clientA.Requests[0]); - Assert.Equal( - ["user:turn one", "assistant:A answered turn 1", "user:turn two"], - clientB.Requests[0]); - Assert.Equal( - [ - "user:turn one", "assistant:A answered turn 1", - "user:turn two", "assistant:B answered turn 1", - "user:turn three", - ], - clientA.Requests[1]); + _ = await agentA.RunAsync("turn one", session, cancellationToken: TestContext.Current.CancellationToken); + _ = await agentB.RunAsync("turn two", session, cancellationToken: TestContext.Current.CancellationToken); + _ = await agentA.RunAsync("turn three", session, cancellationToken: TestContext.Current.CancellationToken); - // The session's own record holds the one whole conversation, in order. - Assert.True(session.TryGetInMemoryChatHistory(out var history, SharedKey)); - Assert.Equal( - [ - "turn one", "A answered turn 1", - "turn two", "B answered turn 1", - "turn three", "A answered turn 2", - ], - history.Select(message => message.Text)); - } + // What each model actually received: the agent of turn 2 saw turn 1's whole exchange, and + // the agent of turn 3 saw everything, including the turn the OTHER agent spoke. + Assert.Equal(["user:turn one"], clientA.Requests[0]); + Assert.Equal( + ["user:turn one", "assistant:A answered turn 1", "user:turn two"], + clientB.Requests[0]); + Assert.Equal( + [ + "user:turn one", "assistant:A answered turn 1", + "user:turn two", "assistant:B answered turn 1", + "user:turn three", + ], + clientA.Requests[1]); - /// Answers every request with a text reply, and records what it was asked. - private sealed class EchoingChatClient : IChatClient - { - private readonly string _name; + // The session's own record holds the one whole conversation, in order. + Assert.True(session.TryGetInMemoryChatHistory(out List? history, SharedKey)); + Assert.Equal( + [ + "turn one", "A answered turn 1", + "turn two", "B answered turn 1", + "turn three", "A answered turn 2", + ], + history.Select(message => message.Text)); + } - public EchoingChatClient(string name) => _name = name; + /// Answers every request with a text reply, and records what it was asked. + private sealed class EchoingChatClient(string name) : IChatClient + { + private readonly string _name = name; - /// Gets every request this client answered, one role-prefixed line per message. - public List> Requests { get; } = []; + /// Gets every request this client answered, one role-prefixed line per message. + public List> Requests { get; } = []; - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Requests.Add([.. messages.Select(message => $"{message.Role}:{message.Text}")]); - return Task.FromResult( - new ChatResponse(new ChatMessage(ChatRole.Assistant, $"{_name} answered turn {Requests.Count}"))); - } + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + Requests.Add([.. messages.Select(message => $"{message.Role}:{message.Text}")]); + return Task.FromResult( + new ChatResponse(new ChatMessage(ChatRole.Assistant, $"{_name} answered turn {Requests.Count}"))); + } - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException("This experiment only runs the non-streaming path."); + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException("This experiment only runs the non-streaming path."); + } - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - public void Dispose() - { + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientCallRecordTests.cs b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientCallRecordTests.cs index b42b7d3e..41840050 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientCallRecordTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientCallRecordTests.cs @@ -4,48 +4,49 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The call record the model wrote is the model's alone. The turn a tool reads arrives beside it, -/// through , never among its keys — so what a checkpoint -/// persists is exactly what the model said, and a live turn is never asked to survive JSON. -/// -public sealed class AuditingFunctionInvokingChatClientCallRecordTests +namespace AgentCore.Application.Tests.Runtime { - [Fact] - public async Task TheTurnReachesTheTool_AndTheModelsCallRecordKeepsOnlyItsOwnKeys() + /// + /// The call record the model wrote is the model's alone. The turn a tool reads arrives beside it, + /// through , never among its keys — so what a checkpoint + /// persists is exactly what the model said, and a live turn is never asked to survive JSON. + /// + public sealed class AuditingFunctionInvokingChatClientCallRecordTests { - TurnInvocation? seen = null; - - var tool = AIFunctionFactory.Create( - (string city, TurnInvocation? turn) => - { - seen = turn; - return $"sunny in {city}"; - }, - new AIFunctionFactoryOptions - { - Name = "weather", - ConfigureParameterBinding = ToolParameterBindings.For, - }); - - TurnInvocation invocation = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "" }; - - ToolCallingChatClient inner = new( - "the loop continues.", - new Dictionary(StringComparer.Ordinal) { ["city"] = "Taipei" }); - using AuditingFunctionInvokingChatClient client = new(inner); - - var response = await client.GetResponseAsync( - [new ChatMessage(ChatRole.User, "weather")], - new ChatOptions { Tools = [tool], AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = invocation } }, - TestContext.Current.CancellationToken); - - Assert.Equal("conversation", seen?.ConversationId); - - var call = response.Messages.SelectMany(message => message.Contents).OfType().Single(); - Assert.Equal(["city"], call.Arguments!.Keys); - Assert.Equal("Taipei", call.Arguments["city"]); + [Fact] + public async Task TheTurnReachesTheTool_AndTheModelsCallRecordKeepsOnlyItsOwnKeys() + { + TurnInvocation? seen = null; + + AIFunction tool = AIFunctionFactory.Create( + (string city, TurnInvocation? turn) => + { + seen = turn; + return $"sunny in {city}"; + }, + new AIFunctionFactoryOptions + { + Name = "weather", + ConfigureParameterBinding = ToolParameterBindings.For, + }); + + TurnInvocation invocation = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "" }; + + ToolCallingChatClient inner = new( + "the loop continues.", + new Dictionary(StringComparer.Ordinal) { ["city"] = "Taipei" }); + using AuditingFunctionInvokingChatClient client = new(inner); + + ChatResponse response = await client.GetResponseAsync( + [new ChatMessage(ChatRole.User, "weather")], + new ChatOptions { Tools = [tool], AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = invocation } }, + TestContext.Current.CancellationToken); + + Assert.Equal("conversation", seen?.ConversationId); + + FunctionCallContent call = response.Messages.SelectMany(message => message.Contents).OfType().Single(); + Assert.Equal(["city"], call.Arguments!.Keys); + Assert.Equal("Taipei", call.Arguments["city"]); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientErrorPolicyTests.cs b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientErrorPolicyTests.cs index 2b74c041..f8797280 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientErrorPolicyTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientErrorPolicyTests.cs @@ -8,282 +8,280 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// Task 7a: the tool error policy moved out of and into -/// , the framework's single choke -/// point for every tool call. These tests pin the caller-observable behaviour that move must not -/// change, and prove the reason for the move: a plain AIFunctionFactory.Create(...) tool, which -/// is not a at all, now gets identical treatment. -/// -/// -/// Every test drives directly against a fake inner -/// , with no YAML document and no ConversationSession, so a failure here -/// isolates the seam itself rather than the turn loop built on top of it. -/// -public sealed class AuditingFunctionInvokingChatClientErrorPolicyTests +namespace AgentCore.Application.Tests.Runtime { - private static readonly ToolConfiguration LookupOrder = new() - { - Id = "lookup_order", - Kind = ToolKind.Binding, - Binds = "LookupOrder", - Description = "Read one order by its identifier.", - }; - - // --------------------------------------------------------------------------------------- - // 3. A fault the model CAN answer still becomes a ToolErrorResult the model reads. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task AFaultTheModelCanAnswer_BecomesTheErrorResultTheModelReads() - { - var tool = new ThrowingDeclaredTool(LookupOrder, new InvalidOperationException("the order is already closed.")); - - var result = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken); - - Assert.True(ToolErrorResult.IsError(result)); - Assert.Equal("lookup_order", result[ToolErrorResult.ToolProperty]!.GetValue()); - Assert.Contains( - "the order is already closed.", - result[ToolErrorResult.MessageProperty]!.GetValue(), - StringComparison.Ordinal); - } - - // --------------------------------------------------------------------------------------- - // 4. Reporting must not change: an answerable fault never leaves the tool as an exception, - // so it must never reach the turn's failure listener. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task AFaultTheModelCanAnswer_IsNeverReported() + /// + /// Task 7a: the tool error policy moved out of and into + /// , the framework's single choke + /// point for every tool call. These tests pin the caller-observable behaviour that move must not + /// change, and prove the reason for the move: a plain AIFunctionFactory.Create(...) tool, which + /// is not a at all, now gets identical treatment. + /// + /// + /// Every test drives directly against a fake inner + /// , with no YAML document and no ConversationSession, so a failure here + /// isolates the seam itself rather than the turn loop built on top of it. + /// + public sealed class AuditingFunctionInvokingChatClientErrorPolicyTests { - List reported = []; - var turn = new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", OnToolFailure = failure => reported.Add(failure) }; - - var tool = new ThrowingDeclaredTool(LookupOrder, new InvalidOperationException("the order is already closed.")); - await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken, turn: turn); - - Assert.Empty(reported); - } + private static readonly ToolConfiguration LookupOrder = new() + { + Id = "lookup_order", + Kind = ToolKind.Binding, + Binds = "LookupOrder", + Description = "Read one order by its identifier.", + }; - // --------------------------------------------------------------------------------------- - // 2. A fault the model CANNOT answer still propagates, so the framework's own consecutive- - // error budget (MaximumConsecutiveErrorsPerRequest = 3) counts it and the 4th round throws. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task AFaultTheModelCannotAnswer_PropagatesAndSpendsTheConsecutiveErrorBudget() - { - var failure = new TimeoutException("the endpoint did not answer."); - var tool = new ThrowingDeclaredTool(LookupOrder, failure); + // --------------------------------------------------------------------------------------- + // 3. A fault the model CAN answer still becomes a ToolErrorResult the model reads. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task AFaultTheModelCanAnswer_BecomesTheErrorResultTheModelReads() + { + ThrowingDeclaredTool tool = new(LookupOrder, new InvalidOperationException("the order is already closed.")); - var thrown = await RunUntilTheBudgetThrowsAsync(tool, TestContext.Current.CancellationToken); + JsonObject result = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken); - // The very exception, and not a copy: the framework rethrows it by ExceptionDispatchInfo - // when the budget runs out. - Assert.Same(failure, thrown); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Equal("lookup_order", result[ToolErrorResult.ToolProperty]!.GetValue()); + Assert.Contains( + "the order is already closed.", + result[ToolErrorResult.MessageProperty]!.GetValue(), + StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------- - // 5. Stacks are preserved: the middleware uses an exception FILTER for the one case that must - // never be caught (caller cancellation) and a bare `throw;` for the propagating case, so the - // stack a beyond-the-model fault carries out still names the tool body that threw it. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task AFaultTheModelCannotAnswer_KeepsItsOriginalStack() - { - var failure = new TimeoutException("the endpoint did not answer."); - var tool = new ThrowingDeclaredTool(LookupOrder, failure); + // --------------------------------------------------------------------------------------- + // 4. Reporting must not change: an answerable fault never leaves the tool as an exception, + // so it must never reach the turn's failure listener. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task AFaultTheModelCanAnswer_IsNeverReported() + { + List reported = []; + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", OnToolFailure = reported.Add }; - var thrown = await RunUntilTheBudgetThrowsAsync(tool, TestContext.Current.CancellationToken); + ThrowingDeclaredTool tool = new(LookupOrder, new InvalidOperationException("the order is already closed.")); + _ = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken, turn: turn); - Assert.NotNull(thrown.StackTrace); - Assert.Contains(nameof(ThrowingDeclaredTool), thrown.StackTrace, StringComparison.Ordinal); - Assert.Contains("CallAsync", thrown.StackTrace, StringComparison.Ordinal); - } + Assert.Empty(reported); + } - // --------------------------------------------------------------------------------------- - // 4 (other half). Reporting must not change: a propagating fault is still reported once for - // every round it spends of the budget, exactly as it is today. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task AFaultTheModelCannotAnswer_IsReportedOnceForEveryPropagatingRound() - { - List reported = []; - var turn = new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", OnToolFailure = failure => reported.Add(failure) }; + // --------------------------------------------------------------------------------------- + // 2. A fault the model CANNOT answer still propagates, so the framework's own consecutive- + // error budget (MaximumConsecutiveErrorsPerRequest = 3) counts it and the 4th round throws. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task AFaultTheModelCannotAnswer_PropagatesAndSpendsTheConsecutiveErrorBudget() + { + TimeoutException failure = new("the endpoint did not answer."); + ThrowingDeclaredTool tool = new(LookupOrder, failure); - var failure = new TimeoutException("the endpoint did not answer."); - var tool = new ThrowingDeclaredTool(LookupOrder, failure); - await RunUntilTheBudgetThrowsAsync(tool, TestContext.Current.CancellationToken, turn); + Exception thrown = await RunUntilTheBudgetThrowsAsync(tool, TestContext.Current.CancellationToken); - // MaximumConsecutiveErrorsPerRequest is 3, so the 4th round is the one that spends the - // budget, and all four reached this middleware and were reported before they propagated. - Assert.Equal(4, reported.Count); - } + // The very exception, and not a copy: the framework rethrows it by ExceptionDispatchInfo + // when the budget runs out. + Assert.Same(failure, thrown); + } - // --------------------------------------------------------------------------------------- - // 1. Caller cancellation passes through untouched. The TOKEN decides, never the exception - // type, and it is never reported. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task ACallerThatHungUp_PassesTheCancellationThroughUnreported() - { - List reported = []; - var turn = new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", OnToolFailure = failure => reported.Add(failure) }; - using CancellationTokenSource source = new(); - - // The tool cancels the very token the call was made with and then throws, exactly as a - // caller hanging up looks from inside a tool body: the token and the exception type agree. - var tool = new CancelingDeclaredTool(LookupOrder, source); - LoopingToolCallingChatClient inner = new(); - using AuditingFunctionInvokingChatClient client = new(inner); - ChatOptions options = new() + // --------------------------------------------------------------------------------------- + // 5. Stacks are preserved: the middleware uses an exception FILTER for the one case that must + // never be caught (caller cancellation) and a bare `throw;` for the propagating case, so the + // stack a beyond-the-model fault carries out still names the tool body that threw it. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task AFaultTheModelCannotAnswer_KeepsItsOriginalStack() { - Tools = [tool], - AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }, - }; + TimeoutException failure = new("the endpoint did not answer."); + ThrowingDeclaredTool tool = new(LookupOrder, failure); - await Assert.ThrowsAnyAsync(() => - client.GetResponseAsync( - [new ChatMessage(ChatRole.User, "where is my order")], - options, - source.Token)); + Exception thrown = await RunUntilTheBudgetThrowsAsync(tool, TestContext.Current.CancellationToken); - Assert.Empty(reported); - } + Assert.NotNull(thrown.StackTrace); + Assert.Contains(nameof(ThrowingDeclaredTool), thrown.StackTrace, StringComparison.Ordinal); + Assert.Contains("CallAsync", thrown.StackTrace, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------- - // THE UNLOCK: a plain AIFunctionFactory.Create(...) tool is not a DeclaredTool at all, so - // before Task 7a moved the policy into this middleware, nothing classified its faults — see - // ThrowingToolBuilder in RuntimeFakes.cs, which throws straight at the framework today. After - // the move it gets the identical answerable-fault treatment a DeclaredTool gets. - // --------------------------------------------------------------------------------------- - [Fact] - public async Task APlainAIFunctionFactoryTool_GetsTheSameErrorResultAsADeclaredTool() - { - Func body = () => throw new InvalidOperationException("the order is already closed."); - AIFunction tool = AIFunctionFactory.Create(body, "lookup_order", "Read one order by its identifier."); + // --------------------------------------------------------------------------------------- + // 4 (other half). Reporting must not change: a propagating fault is still reported once for + // every round it spends of the budget, exactly as it is today. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task AFaultTheModelCannotAnswer_IsReportedOnceForEveryPropagatingRound() + { + List reported = []; + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", OnToolFailure = reported.Add }; - var result = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken); + TimeoutException failure = new("the endpoint did not answer."); + ThrowingDeclaredTool tool = new(LookupOrder, failure); + _ = await RunUntilTheBudgetThrowsAsync(tool, TestContext.Current.CancellationToken, turn); - Assert.True(ToolErrorResult.IsError(result)); - Assert.Equal("lookup_order", result[ToolErrorResult.ToolProperty]!.GetValue()); - Assert.Contains( - "the order is already closed.", - result[ToolErrorResult.MessageProperty]!.GetValue(), - StringComparison.Ordinal); - } + // MaximumConsecutiveErrorsPerRequest is 3, so the 4th round is the one that spends the + // budget, and all four reached this middleware and were reported before they propagated. + Assert.Equal(4, reported.Count); + } - [Fact] - public async Task ARealBindingTool_GetsTheSameErrorResultThroughTheRealMiddleware() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) - => throw new InvalidOperationException("the case system is down")); - ToolConfiguration createCase = new() + // --------------------------------------------------------------------------------------- + // 1. Caller cancellation passes through untouched. The TOKEN decides, never the exception + // type, and it is never reported. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task ACallerThatHungUp_PassesTheCancellationThroughUnreported() { - Id = "create_case", - Kind = ToolKind.Binding, - Binds = "CreateCase", - Description = "Open a service case for a human agent.", - }; - BindingToolSource source = new(registry); - var registrations = await source.ProvideAsync( - new ToolSourceContext(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Tools = [createCase] }), - TestContext.Current.CancellationToken); - var tool = Assert.IsType(Assert.Single(registrations).Materialise(), exactMatch: false); - - var result = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken); - - Assert.True(ToolErrorResult.IsError(result)); - Assert.Equal("create_case", result[ToolErrorResult.ToolProperty]!.GetValue()); - Assert.Contains( - "the case system is down", - result[ToolErrorResult.MessageProperty]!.GetValue(), - StringComparison.Ordinal); - } + List reported = []; + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", OnToolFailure = reported.Add }; + using CancellationTokenSource source = new(); + + // The tool cancels the very token the call was made with and then throws, exactly as a + // caller hanging up looks from inside a tool body: the token and the exception type agree. + CancelingDeclaredTool tool = new(LookupOrder, source); + LoopingToolCallingChatClient inner = new(); + using AuditingFunctionInvokingChatClient client = new(inner); + ChatOptions options = new() + { + Tools = [tool], + AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }, + }; + + _ = await Assert.ThrowsAnyAsync(() => + client.GetResponseAsync( + [new ChatMessage(ChatRole.User, "where is my order")], + options, + source.Token)); + + Assert.Empty(reported); + } - /// Runs one request/response round and returns the JSON the tool result carried. - /// The tool the fake model calls. - /// Cancels the conversation. - /// - /// The arguments the fake model fills, or for none — enough for a tool - /// that validates its own arguments before it ever reaches its adapter. - /// - private static async Task RunSingleRoundAsync( - AIFunction tool, - CancellationToken cancellationToken, - Dictionary? arguments = null, - TurnInvocation? turn = null) - { - ToolCallingChatClient inner = new("the loop continues.", arguments); - using AuditingFunctionInvokingChatClient client = new(inner); - ChatOptions options = new() { Tools = [tool] }; - if (turn is not null) + // --------------------------------------------------------------------------------------- + // THE UNLOCK: a plain AIFunctionFactory.Create(...) tool is not a DeclaredTool at all, so + // before Task 7a moved the policy into this middleware, nothing classified its faults — see + // ThrowingToolBuilder in RuntimeFakes.cs, which throws straight at the framework today. After + // the move it gets the identical answerable-fault treatment a DeclaredTool gets. + // --------------------------------------------------------------------------------------- + [Fact] + public async Task APlainAIFunctionFactoryTool_GetsTheSameErrorResultAsADeclaredTool() { - options.AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }; - } + Func body = () => throw new InvalidOperationException("the order is already closed."); + AIFunction tool = AIFunctionFactory.Create(body, "lookup_order", "Read one order by its identifier."); - await client.GetResponseAsync( - [new ChatMessage(ChatRole.User, "where is my order")], - options, - cancellationToken); + JsonObject result = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken); - var raw = Assert.Single(inner.ToolResults); - return Assert.IsType(JsonNode.Parse(raw)); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Equal("lookup_order", result[ToolErrorResult.ToolProperty]!.GetValue()); + Assert.Contains( + "the order is already closed.", + result[ToolErrorResult.MessageProperty]!.GetValue(), + StringComparison.Ordinal); + } - /// - /// Runs rounds until the framework's own MaximumConsecutiveErrorsPerRequest budget throws, - /// and returns what it threw. - /// - /// - /// never stops calling the tool, so a fault that - /// propagates on every round spends the budget on the fourth. - /// - private static async Task RunUntilTheBudgetThrowsAsync(AIFunction tool, CancellationToken cancellationToken, TurnInvocation? turn = null) - { - LoopingToolCallingChatClient inner = new(); - using AuditingFunctionInvokingChatClient client = new(inner); - ChatOptions options = new() { Tools = [tool] }; - if (turn is not null) + [Fact] + public async Task ARealBindingTool_GetsTheSameErrorResultThroughTheRealMiddleware() { - options.AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }; + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) + => throw new InvalidOperationException("the case system is down")); + ToolConfiguration createCase = new() + { + Id = "create_case", + Kind = ToolKind.Binding, + Binds = "CreateCase", + Description = "Open a service case for a human agent.", + }; + BindingToolSource source = new(registry); + IReadOnlyList registrations = await source.ProvideAsync( + new ToolSourceContext(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Tools = [createCase] }), + TestContext.Current.CancellationToken); + AIFunction tool = Assert.IsType(Assert.Single(registrations).Materialise(), exactMatch: false); + + JsonObject result = await RunSingleRoundAsync(tool, TestContext.Current.CancellationToken); + + Assert.True(ToolErrorResult.IsError(result)); + Assert.Equal("create_case", result[ToolErrorResult.ToolProperty]!.GetValue()); + Assert.Contains( + "the case system is down", + result[ToolErrorResult.MessageProperty]!.GetValue(), + StringComparison.Ordinal); } - return await Assert.ThrowsAnyAsync(() => - client.GetResponseAsync( + /// Runs one request/response round and returns the JSON the tool result carried. + /// The tool the fake model calls. + /// Cancels the conversation. + /// + /// The arguments the fake model fills, or for none — enough for a tool + /// that validates its own arguments before it ever reaches its adapter. + /// + private static async Task RunSingleRoundAsync( + AIFunction tool, + CancellationToken cancellationToken, + Dictionary? arguments = null, + TurnInvocation? turn = null) + { + ToolCallingChatClient inner = new("the loop continues.", arguments); + using AuditingFunctionInvokingChatClient client = new(inner); + ChatOptions options = new() { Tools = [tool] }; + if (turn is not null) + { + options.AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }; + } + + _ = await client.GetResponseAsync( [new ChatMessage(ChatRole.User, "where is my order")], options, - cancellationToken)); - } - - /// A whose body throws whatever the test hands it. - private sealed class ThrowingDeclaredTool : DeclaredTool - { - private readonly Exception _failure; + cancellationToken); - public ThrowingDeclaredTool(ToolConfiguration tool, Exception failure) - : base(tool) => _failure = failure; - - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) => throw _failure; - } + string raw = Assert.Single(inner.ToolResults); + return Assert.IsType(JsonNode.Parse(raw)); + } - /// A whose body cancels the caller's own token and then throws. - private sealed class CancelingDeclaredTool : DeclaredTool - { - private readonly CancellationTokenSource _source; + /// + /// Runs rounds until the framework's own MaximumConsecutiveErrorsPerRequest budget throws, + /// and returns what it threw. + /// + /// + /// never stops calling the tool, so a fault that + /// propagates on every round spends the budget on the fourth. + /// + private static async Task RunUntilTheBudgetThrowsAsync(AIFunction tool, CancellationToken cancellationToken, TurnInvocation? turn = null) + { + LoopingToolCallingChatClient inner = new(); + using AuditingFunctionInvokingChatClient client = new(inner); + ChatOptions options = new() { Tools = [tool] }; + if (turn is not null) + { + options.AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }; + } + + return await Assert.ThrowsAnyAsync(() => + client.GetResponseAsync( + [new ChatMessage(ChatRole.User, "where is my order")], + options, + cancellationToken)); + } - public CancelingDeclaredTool(ToolConfiguration tool, CancellationTokenSource source) - : base(tool) => _source = source; + /// A whose body throws whatever the test hands it. + private sealed class ThrowingDeclaredTool(ToolConfiguration tool, Exception failure) : DeclaredTool(tool) + { + private readonly Exception _failure = failure; + + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + throw _failure; + } + } - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) + /// A whose body cancels the caller's own token and then throws. + private sealed class CancelingDeclaredTool(ToolConfiguration tool, CancellationTokenSource source) : DeclaredTool(tool) { - _source.Cancel(); - throw new OperationCanceledException(); + private readonly CancellationTokenSource _source = source; + + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + _source.Cancel(); + throw new OperationCanceledException(); + } } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs index 6155f51f..fa0a6e0a 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs @@ -5,147 +5,149 @@ using AgentCore.Application.Tools.Binding; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Knowledge.Fakes; -using AgentCore.Domain.Knowledge; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// K42's strip: hands a -/// nested tool call the turn with its stripped, and hands the -/// outermost call the whole turn. -/// -/// -/// The first two facts drive directly, the same way -/// does, with the turn filed -/// on the conversation's own options. The third drives a real turn, -/// because that is the only place that proves the session actually threads its -/// own Clarifications instance through — a fact the first two cannot see, since they file the -/// turn by hand. -/// -public sealed class AuditingFunctionInvokingChatClientStripTests +namespace AgentCore.Application.Tests.Runtime { - [Fact] - public async Task TheCallersOwnToolCall_SeesTheHolder() + /// + /// K42's strip: hands a + /// nested tool call the turn with its stripped, and hands the + /// outermost call the whole turn. + /// + /// + /// The first two facts drive directly, the same way + /// does, with the turn filed + /// on the conversation's own options. The third drives a real turn, + /// because that is the only place that proves the session actually threads its + /// own Clarifications instance through — a fact the first two cannot see, since they file the + /// turn by hand. + /// + public sealed class AuditingFunctionInvokingChatClientStripTests { - var clarifications = new Clarifications(); - Clarifications? seen = null; - - var tool = AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - seen = turn?.Clarifications; - return "done."; - }, - new AIFunctionFactoryOptions - { - Name = "search_tool", - Description = "Reads the turn.", - ConfigureParameterBinding = ToolParameterBindings.For, - }); - - var invocation = TurnOf(clarifications); - - ToolCallingChatClient inner = new("the loop continues."); - using AuditingFunctionInvokingChatClient client = new(inner); - ChatOptions options = new() + [Fact] + public async Task TheCallersOwnToolCall_SeesTheHolder() { - Tools = [tool], - AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = invocation }, - }; + Clarifications clarifications = new(); + Clarifications? seen = null; - await client.GetResponseAsync( - [new ChatMessage(ChatRole.User, "search")], options, TestContext.Current.CancellationToken); + AIFunction tool = AIFunctionFactory.Create( + (TurnInvocation? turn) => + { + seen = turn?.Clarifications; + return "done."; + }, + new AIFunctionFactoryOptions + { + Name = "search_tool", + Description = "Reads the turn.", + ConfigureParameterBinding = ToolParameterBindings.For, + }); - Assert.Same(clarifications, seen); - } + TurnInvocation invocation = TurnOf(clarifications); - [Fact] - public async Task ANestedToolCall_HasNoHolder_WhileTheOuterCallStillDoes() - { - // The outer tool's own invocation reads the filed turn before starting the nested loop, and the - // inner tool reads it from inside that nested loop's own InvokeFunctionAsync. The two reads - // must disagree: K42's strip is conditional on being nested, not on being any tool call at - // all, or it would blind the caller's own search too. - var clarifications = new Clarifications(); - Clarifications? seenOutside = null; - Clarifications? seenNested = null; - - var innerTool = AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - seenNested = turn?.Clarifications; - return "inner done."; - }, - new AIFunctionFactoryOptions + ToolCallingChatClient inner = new("the loop continues."); + using AuditingFunctionInvokingChatClient client = new(inner); + ChatOptions options = new() { - Name = "inner_tool", - Description = "Reads the turn from inside a nested loop.", - ConfigureParameterBinding = ToolParameterBindings.For, - }); + Tools = [tool], + AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = invocation }, + }; - var outerTool = AIFunctionFactory.Create( - async (TurnInvocation? outerTurn) => - { - seenOutside = outerTurn?.Clarifications; + _ = await client.GetResponseAsync( + [new ChatMessage(ChatRole.User, "search")], options, TestContext.Current.CancellationToken); + + Assert.Same(clarifications, seen); + } + + [Fact] + public async Task ANestedToolCall_HasNoHolder_WhileTheOuterCallStillDoes() + { + // The outer tool's own invocation reads the filed turn before starting the nested loop, and the + // inner tool reads it from inside that nested loop's own InvokeFunctionAsync. The two reads + // must disagree: K42's strip is conditional on being nested, not on being any tool call at + // all, or it would blind the caller's own search too. + Clarifications clarifications = new(); + Clarifications? seenOutside = null; + Clarifications? seenNested = null; + + AIFunction innerTool = AIFunctionFactory.Create( + (TurnInvocation? turn) => + { + seenNested = turn?.Clarifications; + return "inner done."; + }, + new AIFunctionFactoryOptions + { + Name = "inner_tool", + Description = "Reads the turn from inside a nested loop.", + ConfigureParameterBinding = ToolParameterBindings.For, + }); - ToolCallingChatClient innerModel = new("nested done."); - using AuditingFunctionInvokingChatClient innerClient = new(innerModel); - ChatOptions innerOptions = new() + AIFunction outerTool = AIFunctionFactory.Create( + async (TurnInvocation? outerTurn) => { - Tools = [innerTool], - AdditionalProperties = new AdditionalPropertiesDictionary + seenOutside = outerTurn?.Clarifications; + + ToolCallingChatClient innerModel = new("nested done."); + using AuditingFunctionInvokingChatClient innerClient = new(innerModel); + ChatOptions innerOptions = new() { - [TurnInvocation.ArgumentsKey] = outerTurn! with { Nested = true, Clarifications = null }, - }, - }; - await innerClient.GetResponseAsync( - [new ChatMessage(ChatRole.User, "go")], innerOptions, TestContext.Current.CancellationToken); - - return "outer done."; - }, - new AIFunctionFactoryOptions - { - Name = "outer_tool", - Description = "Runs a nested loop.", - ConfigureParameterBinding = ToolParameterBindings.For, - }); + Tools = [innerTool], + AdditionalProperties = new AdditionalPropertiesDictionary + { + [TurnInvocation.ArgumentsKey] = outerTurn! with { Nested = true, Clarifications = null }, + }, + }; + _ = await innerClient.GetResponseAsync( + [new ChatMessage(ChatRole.User, "go")], innerOptions, TestContext.Current.CancellationToken); + + return "outer done."; + }, + new AIFunctionFactoryOptions + { + Name = "outer_tool", + Description = "Runs a nested loop.", + ConfigureParameterBinding = ToolParameterBindings.For, + }); - var invocation = TurnOf(clarifications); + TurnInvocation invocation = TurnOf(clarifications); - ToolCallingChatClient outerModel = new("done."); - using AuditingFunctionInvokingChatClient outerClient = new(outerModel); - ChatOptions outerOptions = new() - { - Tools = [outerTool], - AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = invocation }, - }; + ToolCallingChatClient outerModel = new("done."); + using AuditingFunctionInvokingChatClient outerClient = new(outerModel); + ChatOptions outerOptions = new() + { + Tools = [outerTool], + AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = invocation }, + }; - await outerClient.GetResponseAsync( - [new ChatMessage(ChatRole.User, "go")], outerOptions, TestContext.Current.CancellationToken); + _ = await outerClient.GetResponseAsync( + [new ChatMessage(ChatRole.User, "go")], outerOptions, TestContext.Current.CancellationToken); - Assert.Same(clarifications, seenOutside); - Assert.Null(seenNested); - } + Assert.Same(clarifications, seenOutside); + Assert.Null(seenNested); + } - private static TurnInvocation TurnOf(Clarifications clarifications) => new() - { - ConversationId = "conversation", - TurnIndex = 0, - Stage = "", - Clarifications = clarifications, - }; - - // ------------------------------------------------------------------------------------------- - // The wiring fact: a real ConversationSession turn opens its own Clarifications and files it on the - // run, so the probe — not the store — sees it. The increment below proves both halves: no - // holder, or no filing, and the probe's search never runs. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task RunTurnAsync_AToolModeKnowledgeSearch_SeesTheHolder() - { - const string yaml = """ + private static TurnInvocation TurnOf(Clarifications clarifications) + { + return new() + { + ConversationId = "conversation", + TurnIndex = 0, + Stage = "", + Clarifications = clarifications, + }; + } + + // ------------------------------------------------------------------------------------------- + // The wiring fact: a real ConversationSession turn opens its own Clarifications and files it on the + // run, so the probe — not the store — sees it. The increment below proves both halves: no + // holder, or no filing, and the probe's search never runs. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task RunTurnAsync_AToolModeKnowledgeSearch_SeesTheHolder() + { + const string yaml = """ apiVersion: agentcore/v1 state: applies_to: @@ -186,36 +188,25 @@ public async Task RunTurnAsync_AToolModeKnowledgeSearch_SeesTheHolder() agent: only """; - var port = new StubKnowledgePort([]); + StubKnowledgePort port = new([]); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory( - new ToolCallingChatClient( - "done.", - new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = "what is it" }))) - { - Knowledge = port, - })["main"]; + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory( + new ToolCallingChatClient( + "done.", + new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = "what is it" }))) + { + Knowledge = port, + })["main"]; - var factory = new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - var session = factory.Create("conversation-strip-1"); + ConversationSessionFactory factory = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + ConversationSession session = factory.Create("conversation-strip-1"); - await session.RunTurnAsync("what is it", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("what is it", TestContext.Current.CancellationToken); - Assert.Equal(2, port.Calls); - Assert.Equal(1, session.Clarifications.Read("applies_to").ProbeAsks); + Assert.Equal(2, port.Calls); + Assert.Equal(1, session.Clarifications.Read("applies_to").ProbeAsks); + } } - - private static KnowledgeCard Card(string id) - => new() - { - CardId = id, - Text = "card " + id, - Authority = 3, - SourceRef = "ct900-om", - SourceLocator = "p.27", - Score = 0.87, - ViaLink = false, - }; } diff --git a/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs b/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs index b13b8bde..3a7d42b9 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs @@ -1,55 +1,53 @@ using AgentCore.Application.Runtime; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The probe's note (§8), rendered against §4's own description: values so a human can read -/// the result as English rather than a template. -/// -public sealed class ClarificationTextTests +namespace AgentCore.Application.Tests.Runtime { - // §4's own value, verbatim: "The model, as printed on the machine." - private const string AppliesToDescription = "The model, as printed on the machine."; - - // §4's own value, verbatim: "The brand of the caller's machine." - private const string BrandDescription = "The brand of the caller's machine."; - - [Fact] - public void Note_TwoCandidates_JoinsWithAPlainComma_NotOr() - { - var text = ClarificationText.Note(AppliesToDescription, ["ct900", "ct900ent"], maxCandidates: 6); - - Assert.Equal( - "One thing decides the answer here and is not yet known: The model, as printed on the machine. " - + "It could be: ct900, ct900ent. Ask the caller which, and do not answer from the knowledge base " - + "about it until they say.", - text); - } - - [Fact] - public void Note_OneCandidate_RendersTheConfirmSentence() - { - var text = ClarificationText.Note(AppliesToDescription, ["ct900"], maxCandidates: 6); - - Assert.Equal( - "One thing decides the answer here and is not yet confirmed: The model, as printed on the " - + "machine. Everything found is for ct900. Ask the caller whether that is what they have before " - + "answering from the knowledge base about it.", - text); - } - - [Fact] - public void Note_OverMaxCandidates_OmitsTheList() + /// + /// The probe's note (§8), rendered against §4's own description: values so a human can read + /// the result as English rather than a template. + /// + public sealed class ClarificationTextTests { - var text = ClarificationText.Note( - AppliesToDescription, - ["ct800", "ct800ent", "ct900", "ct900ent", "xt285", "xt385", "xt485"], - maxCandidates: 6); - - Assert.Equal( - "One thing decides the answer here and is not yet known: The model, as printed on the machine. " - + "Ask the caller, and do not answer from the knowledge base about it until they say.", - text); + // §4's own value, verbatim: "The model, as printed on the machine." + private const string AppliesToDescription = "The model, as printed on the machine."; + + [Fact] + public void Note_TwoCandidates_JoinsWithAPlainComma_NotOr() + { + string text = ClarificationText.Note(AppliesToDescription, ["ct900", "ct900ent"], maxCandidates: 6); + + Assert.Equal( + "One thing decides the answer here and is not yet known: The model, as printed on the machine. " + + "It could be: ct900, ct900ent. Ask the caller which, and do not answer from the knowledge base " + + "about it until they say.", + text); + } + + [Fact] + public void Note_OneCandidate_RendersTheConfirmSentence() + { + string text = ClarificationText.Note(AppliesToDescription, ["ct900"], maxCandidates: 6); + + Assert.Equal( + "One thing decides the answer here and is not yet confirmed: The model, as printed on the " + + "machine. Everything found is for ct900. Ask the caller whether that is what they have before " + + "answering from the knowledge base about it.", + text); + } + + [Fact] + public void Note_OverMaxCandidates_OmitsTheList() + { + string text = ClarificationText.Note( + AppliesToDescription, + ["ct800", "ct800ent", "ct900", "ct900ent", "xt285", "xt385", "xt485"], + maxCandidates: 6); + + Assert.Equal( + "One thing decides the answer here and is not yet known: The model, as printed on the machine. " + + "Ask the caller, and do not answer from the knowledge base about it until they say.", + text); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs b/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs index 4632407c..d74985c6 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs @@ -1,316 +1,316 @@ +using AgentCore.Application.Conversation; using AgentCore.Application.Runtime; using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// : the per-conversation holder K36 describes, K41's per-turn mark, and K43's -/// probe latch and replay payload. -/// -public sealed class ClarificationsTests +namespace AgentCore.Application.Tests.Runtime { - // ----------------------------------------------------------------------------------------- - // K43: the probe latch is a compare-and-set. Several search-tool calls in one turn, or several - // graph participants sharing this conversation, must cost exactly one probe. - // ----------------------------------------------------------------------------------------- - [Fact] - public void ClaimProbe_ManyConcurrentCallers_ExactlyOneClaimsEachTrial() + /// + /// : the per-conversation holder K36 describes, K41's per-turn mark, and K43's + /// probe latch and replay payload. + /// + public sealed class ClarificationsTests { - // A single trial of three threads can pass a broken compare-and-set by luck, so this runs - // many trials with a Barrier forcing all callers to race the same instant, and demands every - // trial land on exactly one winner. - const int trials = 200; - const int callers = 8; - - for (var trial = 0; trial < trials; trial++) + // ----------------------------------------------------------------------------------------- + // K43: the probe latch is a compare-and-set. Several search-tool calls in one turn, or several + // graph participants sharing this conversation, must cost exactly one probe. + // ----------------------------------------------------------------------------------------- + [Fact] + public void ClaimProbe_ManyConcurrentCallers_ExactlyOneClaimsEachTrial() { - var clarifications = new Clarifications(); - using var barrier = new Barrier(callers); - var claims = 0; - - // A raw Thread whose body throws takes the whole test process down with it, so every - // caller's exception is caught and reported through Assert instead of left to escape. - Exception? escaped = null; + // A single trial of three threads can pass a broken compare-and-set by luck, so this runs + // many trials with a Barrier forcing all callers to race the same instant, and demands every + // trial land on exactly one winner. + const int trials = 200; + const int callers = 8; - var threads = new Thread[callers]; - for (var i = 0; i < callers; i++) + for (int trial = 0; trial < trials; trial++) { - threads[i] = new Thread(() => + Clarifications clarifications = new(); + using Barrier barrier = new(callers); + int claims = 0; + + // A raw Thread whose body throws takes the whole test process down with it, so every + // caller's exception is caught and reported through Assert instead of left to escape. + Exception? escaped = null; + + Thread[] threads = new Thread[callers]; + for (int i = 0; i < callers; i++) { - try + threads[i] = new Thread(() => { - barrier.SignalAndWait(); - if (clarifications.ClaimProbe().Won) + try { - Interlocked.Increment(ref claims); + barrier.SignalAndWait(); + if (clarifications.ClaimProbe().Won) + { + _ = Interlocked.Increment(ref claims); + } } - } - catch (Exception failure) - { - Interlocked.CompareExchange(ref escaped, failure, null); - } - }); - threads[i].Start(); - } + catch (Exception failure) + { + _ = Interlocked.CompareExchange(ref escaped, failure, null); + } + }); + threads[i].Start(); + } - foreach (var thread in threads) - { - thread.Join(); - } + foreach (Thread thread in threads) + { + thread.Join(); + } - if (escaped is not null) - { - throw escaped; - } + if (escaped is not null) + { + throw escaped; + } - Assert.True(claims == 1, $"trial {trial}: expected exactly one claim, got {claims}."); + Assert.True(claims == 1, $"trial {trial}: expected exactly one claim, got {claims}."); + } } - } - // ----------------------------------------------------------------------------------------- - // K43: the caller hanging up mid-probe must fail the payload, not merely drop it, so every - // loser waiting on it wakes rather than burning its full wait margin on a corpse. - // ----------------------------------------------------------------------------------------- - [Fact] - public async Task Fail_WakesEveryWaiter_AndLeavesTheLatchClaimed() - { - var clarifications = new Clarifications(); - var winner = clarifications.ClaimProbe(); - Assert.True(winner.Won); + // ----------------------------------------------------------------------------------------- + // K43: the caller hanging up mid-probe must fail the payload, not merely drop it, so every + // loser waiting on it wakes rather than burning its full wait margin on a corpse. + // ----------------------------------------------------------------------------------------- + [Fact] + public async Task Fail_WakesEveryWaiter_AndLeavesTheLatchClaimed() + { + Clarifications clarifications = new(); + Clarifications.Probe winner = clarifications.ClaimProbe(); + Assert.True(winner.Won); - var waiters = Enumerable.Range(0, 5) - .Select(_ => clarifications.ClaimProbe().WaitAsync( - TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken)) - .ToArray(); + Task>[] waiters = [.. Enumerable.Range(0, 5) + .Select(_ => clarifications.ClaimProbe().WaitAsync( + TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken))]; - winner.Fail(); + winner.Fail(); - var all = Task.WhenAll(waiters); - var completed = await Task.WhenAny( - all, Task.Delay(TimeSpan.FromSeconds(2), TestContext.Current.CancellationToken)); + Task[]> all = Task.WhenAll(waiters); + Task completed = await Task.WhenAny( + all, Task.Delay(TimeSpan.FromSeconds(2), TestContext.Current.CancellationToken)); - Assert.Same(all, completed); + Assert.Same(all, completed); - foreach (var waiter in waiters) - { - await Assert.ThrowsAnyAsync(() => waiter); - } + foreach (Task>? waiter in waiters) + { + _ = await Assert.ThrowsAnyAsync(() => waiter); + } - // Nothing was asked and nothing was learned, so the facet must not be charged for a second - // probe search this turn: the latch stays claimed and a fresh claim is refused. - Assert.False(clarifications.ClaimProbe().Won); - } + // Nothing was asked and nothing was learned, so the facet must not be charged for a second + // probe search this turn: the latch stays claimed and a fresh claim is refused. + Assert.False(clarifications.ClaimProbe().Won); + } - [Fact] - public async Task Publish_LetsEveryWaiterReplayTheSameCards() - { - var clarifications = new Clarifications(); - var winner = clarifications.ClaimProbe(); - Assert.True(winner.Won); + [Fact] + public async Task Publish_LetsEveryWaiterReplayTheSameCards() + { + Clarifications clarifications = new(); + Clarifications.Probe winner = clarifications.ClaimProbe(); + Assert.True(winner.Won); - var waiters = Enumerable.Range(0, 3) - .Select(_ => clarifications.ClaimProbe().WaitAsync( - TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken)) - .ToArray(); + Task>[] waiters = [.. Enumerable.Range(0, 3) + .Select(_ => clarifications.ClaimProbe().WaitAsync( + TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken))]; - IReadOnlyList cards = [new TextSearchProvider.TextSearchResult { Text = "note" }]; - winner.Publish(cards); + IReadOnlyList cards = [new TextSearchProvider.TextSearchResult { Text = "note" }]; + winner.Publish(cards); - var results = await Task.WhenAll(waiters); + IReadOnlyList[] results = await Task.WhenAll(waiters); - Assert.All(results, result => Assert.Same(cards, result)); - } + Assert.All(results, result => Assert.Same(cards, result)); + } - // ----------------------------------------------------------------------------------------- - // K43: BeginTurn opens a fresh turn. It clears the probe latch and its payload together, and - // never the counter — that is per-conversation, not per-turn. - // ----------------------------------------------------------------------------------------- - [Fact] - public void BeginTurn_ClearsTheLatch_AndLeavesTheCounter() - { - var clarifications = new Clarifications(); + // ----------------------------------------------------------------------------------------- + // K43: BeginTurn opens a fresh turn. It clears the probe latch and its payload together, and + // never the counter — that is per-conversation, not per-turn. + // ----------------------------------------------------------------------------------------- + [Fact] + public void BeginTurn_ClearsTheLatch_AndLeavesTheCounter() + { + Clarifications clarifications = new(); - clarifications.ClaimProbe().Publish([]); + clarifications.ClaimProbe().Publish([]); - clarifications.Update("brand", s => s.ProbeAsks = 3); + clarifications.Update("brand", s => s.ProbeAsks = 3); - clarifications.BeginTurn(); + clarifications.BeginTurn(); - Assert.Equal(3, clarifications.Read("brand").ProbeAsks); + Assert.Equal(3, clarifications.Read("brand").ProbeAsks); - // The latch is free again. - Assert.True(clarifications.ClaimProbe().Won); - } + // The latch is free again. + Assert.True(clarifications.ClaimProbe().Won); + } - [Fact] - public async Task BeginTurn_ThePayloadFromTheLastTurn_IsGoneAndNotJustUnclaimed() - { - var clarifications = new Clarifications(); - IReadOnlyList turn1 = [new TextSearchProvider.TextSearchResult { Text = "turn 1" }]; - clarifications.ClaimProbe().Publish(turn1); + [Fact] + public async Task BeginTurn_ThePayloadFromTheLastTurn_IsGoneAndNotJustUnclaimed() + { + Clarifications clarifications = new(); + IReadOnlyList turn1 = [new TextSearchProvider.TextSearchResult { Text = "turn 1" }]; + clarifications.ClaimProbe().Publish(turn1); - clarifications.BeginTurn(); + clarifications.BeginTurn(); - // Turn 2's own winner and loser share a payload of their own. A loser that replayed turn 1's - // note would be F148's shape, a stale payload leaking across the boundary BeginTurn draws. - Assert.True(clarifications.ClaimProbe().Won); - var loser = clarifications.ClaimProbe(); - Assert.False(loser.Won); + // Turn 2's own winner and loser share a payload of their own. A loser that replayed turn 1's + // note would be F148's shape, a stale payload leaking across the boundary BeginTurn draws. + Assert.True(clarifications.ClaimProbe().Won); + Clarifications.Probe loser = clarifications.ClaimProbe(); + Assert.False(loser.Won); - await Assert.ThrowsAsync( - () => loser.WaitAsync(TimeSpan.FromMilliseconds(1), TestContext.Current.CancellationToken)); - } + _ = await Assert.ThrowsAsync( + () => loser.WaitAsync(TimeSpan.FromMilliseconds(1), TestContext.Current.CancellationToken)); + } - // ----------------------------------------------------------------------------------------- - // A search that outlives its turn holds turn N's handle. Publishing through it must not resolve - // the latch turn N+1 opened, or every loser of the new turn replays the old turn's cards. - // ----------------------------------------------------------------------------------------- - [Fact] - public async Task Publish_FromTheTurnBefore_LeavesTheNewTurnsLatchAlone() - { - var clarifications = new Clarifications(); - var stale = clarifications.ClaimProbe(); + // ----------------------------------------------------------------------------------------- + // A search that outlives its turn holds turn N's handle. Publishing through it must not resolve + // the latch turn N+1 opened, or every loser of the new turn replays the old turn's cards. + // ----------------------------------------------------------------------------------------- + [Fact] + public async Task Publish_FromTheTurnBefore_LeavesTheNewTurnsLatchAlone() + { + Clarifications clarifications = new(); + Clarifications.Probe stale = clarifications.ClaimProbe(); - clarifications.BeginTurn(); + clarifications.BeginTurn(); - Assert.True(clarifications.ClaimProbe().Won); - var loser = clarifications.ClaimProbe(); + Assert.True(clarifications.ClaimProbe().Won); + Clarifications.Probe loser = clarifications.ClaimProbe(); - stale.Publish([new TextSearchProvider.TextSearchResult { Text = "turn 1" }]); - stale.Fail(); + stale.Publish([new TextSearchProvider.TextSearchResult { Text = "turn 1" }]); + stale.Fail(); - await Assert.ThrowsAsync( - () => loser.WaitAsync(TimeSpan.FromMilliseconds(1), TestContext.Current.CancellationToken)); - } + _ = await Assert.ThrowsAsync( + () => loser.WaitAsync(TimeSpan.FromMilliseconds(1), TestContext.Current.CancellationToken)); + } - // ----------------------------------------------------------------------------------------- - // Reconnect: the ask budget is per conversation, not per session, so what one session spent must reach - // the next one through the conversation's stored state. - // ----------------------------------------------------------------------------------------- - [Fact] - public void SpentAndRestoreSpent_CarryTheBudget_AndNotWhatWasNamed() - { - var first = new Clarifications(); - first.Update("applies_to", s => + // ----------------------------------------------------------------------------------------- + // Reconnect: the ask budget is per conversation, not per session, so what one session spent must reach + // the next one through the conversation's stored state. + // ----------------------------------------------------------------------------------------- + [Fact] + public void SpentAndRestoreSpent_CarryTheBudget_AndNotWhatWasNamed() { - s.ProbeAsks = 2; - s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900" }); - }); - - var spent = first.Spent(); + Clarifications first = new(); + first.Update("applies_to", s => + { + s.ProbeAsks = 2; + s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900" }); + }); - var resumed = new Clarifications(); - resumed.RestoreSpent(spent); + IReadOnlyDictionary spent = first.Spent(); - var slot = resumed.Read("applies_to"); - Assert.Equal(2, slot.ProbeAsks); + Clarifications resumed = new(); + resumed.RestoreSpent(spent); - // What was named belongs to a turn the reconnected caller is not in. - Assert.Equal(Clarifications.LastNamedKind.None, slot.LastNamed.Kind); - } + Clarifications.SlotSnapshot slot = resumed.Read("applies_to"); + Assert.Equal(2, slot.ProbeAsks); - [Fact] - public void Spent_LeavesOutASlotNothingHasAskedAbout() - { - var clarifications = new Clarifications(); - clarifications.Update( - "brand", - s => s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "sole" })); + // What was named belongs to a turn the reconnected caller is not in. + Assert.Equal(Clarifications.LastNamedKind.None, slot.LastNamed.Kind); + } - Assert.Empty(clarifications.Spent()); - } + [Fact] + public void Spent_LeavesOutASlotNothingHasAskedAbout() + { + Clarifications clarifications = new(); + clarifications.Update( + "brand", + s => s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "sole" })); - // ----------------------------------------------------------------------------------------- - // Edit-and-resend: Withdraw clears what was named, and leaves the ask counter untouched so a - // withdrawn segment cannot buy a fresh maxAsks budget. - // ----------------------------------------------------------------------------------------- - [Fact] - public void Withdraw_ClearsLastNamed_AndLeavesTheCounter() - { - var clarifications = new Clarifications(); + Assert.Empty(clarifications.Spent()); + } - clarifications.Update("brand", s => + // ----------------------------------------------------------------------------------------- + // Edit-and-resend: Withdraw clears what was named, and leaves the ask counter untouched so a + // withdrawn segment cannot buy a fresh maxAsks budget. + // ----------------------------------------------------------------------------------------- + [Fact] + public void Withdraw_ClearsLastNamed_AndLeavesTheCounter() { - s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900", "ct900ent" }); - s.ProbeAsks = 4; - }); + Clarifications clarifications = new(); - clarifications.Withdraw(); - - var after = clarifications.Read("brand"); - Assert.Equal(Clarifications.LastNamed.None, after.LastNamed); - Assert.Equal(4, after.ProbeAsks); - } + clarifications.Update("brand", s => + { + s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900", "ct900ent" }); + s.ProbeAsks = 4; + }); - [Fact] - public void Read_ANameNeverSeenBefore_StartsAtItsZeroValues() - { - var clarifications = new Clarifications(); + clarifications.Withdraw(); - var slot = clarifications.Read("applies_to"); + Clarifications.SlotSnapshot after = clarifications.Read("brand"); + Assert.Equal(Clarifications.LastNamed.None, after.LastNamed); + Assert.Equal(4, after.ProbeAsks); + } - Assert.Equal(Clarifications.LastNamed.None, slot.LastNamed); - Assert.Equal(0, slot.ProbeAsks); - } + [Fact] + public void Read_ANameNeverSeenBefore_StartsAtItsZeroValues() + { + Clarifications clarifications = new(); - [Fact] - public void Update_TheSameName_SharesOneUnderlyingState() - { - var clarifications = new Clarifications(); + Clarifications.SlotSnapshot slot = clarifications.Read("applies_to"); - clarifications.Update("brand", s => s.ProbeAsks = 7); + Assert.Equal(Clarifications.LastNamed.None, slot.LastNamed); + Assert.Equal(0, slot.ProbeAsks); + } - Assert.Equal(7, clarifications.Read("brand").ProbeAsks); - } + [Fact] + public void Update_TheSameName_SharesOneUnderlyingState() + { + Clarifications clarifications = new(); - // ----------------------------------------------------------------------------------------- - // §8's compound transitions (K36): a slot's fields must move together as one step, or a - // concurrent reader can catch it between the two writes. This is the §8-step-6 shape - record - // what was named and move a counter - reduced to its atomicity core: LastNamed is set exactly - // when ProbeAsks is odd, and a reader that ever sees them disagree caught a torn write. - // ----------------------------------------------------------------------------------------- - [Fact] - public async Task Update_ACompoundTransition_IsNeverObservedHalfApplied() - { - var clarifications = new Clarifications(); - const string slot = "brand"; - const int iterations = 20_000; + clarifications.Update("brand", s => s.ProbeAsks = 7); - using var stop = new CancellationTokenSource(); - var tornObservations = 0; + Assert.Equal(7, clarifications.Read("brand").ProbeAsks); + } - var reader = Task.Run(() => + // ----------------------------------------------------------------------------------------- + // §8's compound transitions (K36): a slot's fields must move together as one step, or a + // concurrent reader can catch it between the two writes. This is the §8-step-6 shape - record + // what was named and move a counter - reduced to its atomicity core: LastNamed is set exactly + // when ProbeAsks is odd, and a reader that ever sees them disagree caught a torn write. + // ----------------------------------------------------------------------------------------- + [Fact] + public async Task Update_ACompoundTransition_IsNeverObservedHalfApplied() { - while (!stop.IsCancellationRequested) - { - var snapshot = clarifications.Read(slot); - var namedIsSet = snapshot.LastNamed.Kind == Clarifications.LastNamedKind.Set; - var probeAsksIsOdd = snapshot.ProbeAsks % 2 != 0; + Clarifications clarifications = new(); + const string slot = "brand"; + const int iterations = 20_000; + + using CancellationTokenSource stop = new(); + int tornObservations = 0; - if (namedIsSet != probeAsksIsOdd) + Task reader = Task.Run(() => + { + while (!stop.IsCancellationRequested) { - Interlocked.Increment(ref tornObservations); - } - } - }, TestContext.Current.CancellationToken); + Clarifications.SlotSnapshot snapshot = clarifications.Read(slot); + bool namedIsSet = snapshot.LastNamed.Kind == Clarifications.LastNamedKind.Set; + bool probeAsksIsOdd = snapshot.ProbeAsks % 2 != 0; - var named = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900", "ct900ent" }); + if (namedIsSet != probeAsksIsOdd) + { + _ = Interlocked.Increment(ref tornObservations); + } + } + }, TestContext.Current.CancellationToken); - for (var i = 0; i < iterations; i++) - { - var opening = i % 2 == 0; + Clarifications.LastNamed named = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900", "ct900ent" }); - clarifications.Update(slot, state => + for (int i = 0; i < iterations; i++) { - state.LastNamed = opening ? named : Clarifications.LastNamed.None; - state.ProbeAsks++; - }); - } + bool opening = i % 2 == 0; - await stop.CancelAsync(); - await reader; + clarifications.Update(slot, state => + { + state.LastNamed = opening ? named : Clarifications.LastNamed.None; + state.ProbeAsks++; + }); + } - Assert.Equal(0, tornObservations); + await stop.CancelAsync(); + await reader; + + Assert.Equal(0, tornObservations); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs index f2d3cf95..ce2584ff 100644 --- a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs @@ -9,166 +9,173 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// : the one fixed Cap -> Summary pair (D7, D9), -/// sized off the model's window, and the compiler's refusal when the window is unknown (D14, D15). -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class CompactionStrategyFactoryTests +namespace AgentCore.Application.Tests.Runtime { - [Theory] - [InlineData(0)] - [InlineData(-1)] - public void Create_AContextWindowThatIsNotPositive_Throws(int window) + /// + /// : the one fixed Cap -> Summary pair (D7, D9), + /// sized off the model's window, and the compiler's refusal when the window is unknown (D14, D15). + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class CompactionStrategyFactoryTests { - using SequencedChatClient summariser = new("summary."); + [Theory] + [InlineData(0)] + [InlineData(-1)] + public void Create_AContextWindowThatIsNotPositive_Throws(int window) + { + using SequencedChatClient summariser = new("summary."); - Assert.Throws(() => CompactionStrategyFactory.Create(summariser, window)); - } + _ = Assert.Throws(() => CompactionStrategyFactory.Create(summariser, window)); + } - [Fact] - public async Task Create_AViewAt76PercentOfTheWindow_FiresAndLandsAtOrUnderTheTarget() - { - // window = 1000: fire above 750 (75%), stop at or below 500 (50%). 20 pairs of 76-char - // messages sum to exactly 3040 UTF-8 bytes, which MAF's byte/4 estimator (no tokenizer - // supplied) reads as exactly 760 tokens - over the fire line. - using SequencedChatClient summariser = new("summary."); - var stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); + [Fact] + public async Task Create_AViewAt76PercentOfTheWindow_FiresAndLandsAtOrUnderTheTarget() + { + // window = 1000: fire above 750 (75%), stop at or below 500 (50%). 20 pairs of 76-char + // messages sum to exactly 3040 UTF-8 bytes, which MAF's byte/4 estimator (no tokenizer + // supplied) reads as exactly 760 tokens - over the fire line. + using SequencedChatClient summariser = new("summary."); + CompactionStages stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); - var view = Conversation(pairs: 20, charsPerMessage: 76); + List view = Conversation(pairs: 20, charsPerMessage: 76); - var compacted = (await CompactionProvider.CompactAsync( - stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)).ToList(); + List compacted = [.. await CompactionProvider.CompactAsync( + stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; - var after = EstimatedTokens(compacted); - Assert.True(after <= 500, $"expected at or under the 500-token target, got {after}."); - } + int after = EstimatedTokens(compacted); + Assert.True(after <= 500, $"expected at or under the 500-token target, got {after}."); + } - [Fact] - public async Task Create_AViewAt74PercentOfTheWindow_ComesBackUnchanged() - { - // Same shape, one token under the fire line: 20 pairs of 74-char messages are exactly - // 2960 bytes, which the byte/4 estimator reads as 740 tokens - at or under 750, so the - // summary compacts nothing. - using SequencedChatClient summariser = new("summary."); - var stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); + [Fact] + public async Task Create_AViewAt74PercentOfTheWindow_ComesBackUnchanged() + { + // Same shape, one token under the fire line: 20 pairs of 74-char messages are exactly + // 2960 bytes, which the byte/4 estimator reads as 740 tokens - at or under 750, so the + // summary compacts nothing. + using SequencedChatClient summariser = new("summary."); + CompactionStages stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); - var view = Conversation(pairs: 20, charsPerMessage: 74); + List view = Conversation(pairs: 20, charsPerMessage: 74); - var compacted = (await CompactionProvider.CompactAsync( - stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)).ToList(); + List compacted = [.. await CompactionProvider.CompactAsync( + stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; - Assert.Equal(view.Count, compacted.Count); - for (var index = 0; index < view.Count; index++) - { - Assert.Same(view[index], compacted[index]); + Assert.Equal(view.Count, compacted.Count); + for (int index = 0; index < view.Count; index++) + { + Assert.Same(view[index], compacted[index]); + } } - } - [Fact] - public void Compile_AnUnknownModel_FailsNamingTheAgentAtThePointerEndingInModel() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public void Compile_AnUnknownModel_FailsNamingTheAgentAtThePointerEndingInModel() + { + using SequencedChatClient reply = new("hello there."); - var failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration + ConfigurationLoadException failure = Assert.Throws(() => ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - Items = [new AgentConfiguration { Id = "only" }], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration { Agent = "only" }, + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only" }], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "only" }, + }, }, - }, - new AgentCompilationContext(new NullWindowChatClientFactory(reply)))); + new AgentCompilationContext(new NullWindowChatClientFactory(reply)))); - Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); - Assert.EndsWith("/model", Assert.Single(failure.Errors).Pointer, StringComparison.Ordinal); - } + Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); + Assert.EndsWith("/model", Assert.Single(failure.Errors).Pointer, StringComparison.Ordinal); + } - [Fact] - public void Compile_EveryAgentOfATwoAgentDocument_HasBothCompactionProviders() - { - using SequencedChatClient reply = new("hello there."); + [Fact] + public void Compile_EveryAgentOfATwoAgentDocument_HasBothCompactionProviders() + { + using SequencedChatClient reply = new("hello there."); - var compiled = ConfigurationCompiler.CompileAll( - new AgentCoreConfiguration - { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration { Id = "first" }, - new AgentConfiguration { Id = "second" }, - ], - }, - Entries = new Dictionary + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + new AgentCoreConfiguration { - ["main"] = new EntryConfiguration + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration { - Policy = new PolicyConfiguration + Items = + [ + new AgentConfiguration { Id = "first" }, + new AgentConfiguration { Id = "second" }, + ], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { - Initial = "opening", - Stages = - [ - new StageConfiguration { Id = "opening", Agent = "first" }, - new StageConfiguration { Id = "closing", Agent = "second" }, - ], + Policy = new PolicyConfiguration + { + Initial = "opening", + Stages = + [ + new StageConfiguration { Id = "opening", Agent = "first" }, + new StageConfiguration { Id = "closing", Agent = "second" }, + ], + }, }, }, }, - }, - new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - Assert.All( - compiled.Agents.Values, - agent => - { - var providers = Providers(agent).ToList(); - var cap = Assert.Single(providers, provider => provider is ToolResultCapProvider); - var summary = Assert.Single(providers, provider => provider is SummaryRowProvider); - Assert.True(providers.IndexOf(cap) < providers.IndexOf(summary), "the cap runs before the summary."); - }); - } + new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - private static int EstimatedTokens(IReadOnlyList messages) - => messages.Sum(message => System.Text.Encoding.UTF8.GetByteCount(message.Text)) / 4; + Assert.All( + compiled.Agents.Values, + agent => + { + List providers = [.. Providers(agent)]; + AIContextProvider cap = Assert.Single(providers, provider => provider is ToolResultCapProvider); + AIContextProvider summary = Assert.Single(providers, provider => provider is SummaryRowProvider); + Assert.True(providers.IndexOf(cap) < providers.IndexOf(summary), "the cap runs before the summary."); + }); + } - private static List Conversation(int pairs, int charsPerMessage) - { - List messages = []; - for (var index = 0; index < pairs; index++) + private static int EstimatedTokens(IReadOnlyList messages) { - messages.Add(new ChatMessage(ChatRole.User, new string('x', charsPerMessage))); - messages.Add(new ChatMessage(ChatRole.Assistant, new string('x', charsPerMessage))); + return messages.Sum(message => System.Text.Encoding.UTF8.GetByteCount(message.Text)) / 4; } - return messages; - } + private static List Conversation(int pairs, int charsPerMessage) + { + List messages = []; + for (int index = 0; index < pairs; index++) + { + messages.Add(new ChatMessage(ChatRole.User, new string('x', charsPerMessage))); + messages.Add(new ChatMessage(ChatRole.Assistant, new string('x', charsPerMessage))); + } - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; - } + return messages; + } - /// Answers no window, as an adapter would for a model id its table does not carry. - private sealed class NullWindowChatClientFactory : IChatClientFactory - { - private readonly IChatClient _client; + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } - public NullWindowChatClientFactory(IChatClient client) => _client = client; + /// Answers no window, as an adapter would for a model id its table does not carry. + private sealed class NullWindowChatClientFactory(IChatClient client) : IChatClientFactory + { + private readonly IChatClient _client = client; - public IChatClient GetChatClient(ModelReference? model) => _client; + public IChatClient GetChatClient(ModelReference? model) + { + return _client; + } - public int? GetContextWindow(ModelReference? model) => null; + public int? GetContextWindow(ModelReference? model) + { + return null; + } + } } -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationEventKindsTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationEventKindsTests.cs index 6364a4a6..003f0998 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationEventKindsTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationEventKindsTests.cs @@ -2,78 +2,79 @@ using AgentCore.Domain.Audit; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// What one conversation event kind is to the audit vocabulary, and what it is called in a log line. -/// -public sealed class ConversationEventKindsTests +namespace AgentCore.Application.Tests.Runtime { - /// Every kind the chain stores, beside the row it writes and the token it hashes. - public static TheoryData StoredKinds => - new() - { - { ConversationEventKind.ConversationStarted, AuditEventKind.ConversationStarted, "conversation.started" }, - { ConversationEventKind.PromptFlagged, AuditEventKind.PromptFlagged, "prompt.flagged" }, - { ConversationEventKind.ToolFailed, AuditEventKind.ToolFailed, "tool.failed" }, - { ConversationEventKind.TurnCompleted, AuditEventKind.TurnCompleted, "turn.completed" }, - { ConversationEventKind.ReplyInterrupted, AuditEventKind.ReplyInterrupted, "reply.interrupted" }, - { ConversationEventKind.ConversationEnded, AuditEventKind.ConversationEnded, "conversation.ended" }, - { ConversationEventKind.TurnSuperseded, AuditEventKind.TurnSuperseded, "turn.superseded" }, - }; + /// + /// What one conversation event kind is to the audit vocabulary, and what it is called in a log line. + /// + public sealed class ConversationEventKindsTests + { + /// Every kind the chain stores, beside the row it writes and the token it hashes. + public static TheoryData StoredKinds => + new() + { + { ConversationEventKind.ConversationStarted, AuditEventKind.ConversationStarted, "conversation.started" }, + { ConversationEventKind.PromptFlagged, AuditEventKind.PromptFlagged, "prompt.flagged" }, + { ConversationEventKind.ToolFailed, AuditEventKind.ToolFailed, "tool.failed" }, + { ConversationEventKind.TurnCompleted, AuditEventKind.TurnCompleted, "turn.completed" }, + { ConversationEventKind.ReplyInterrupted, AuditEventKind.ReplyInterrupted, "reply.interrupted" }, + { ConversationEventKind.ConversationEnded, AuditEventKind.ConversationEnded, "conversation.ended" }, + { ConversationEventKind.TurnSuperseded, AuditEventKind.TurnSuperseded, "turn.superseded" }, + }; - /// Every diagnostic kind, beside the name a log line gives it. - public static TheoryData DiagnosticKinds => - new() - { - { ConversationEventKind.ModerationUnavailable, "moderation.unavailable" }, - { ConversationEventKind.ModerationClean, "moderation.clean" }, - { ConversationEventKind.EmptyReply, "reply.empty" }, - { ConversationEventKind.ExtractionFailed, "extraction.failed" }, - { ConversationEventKind.TranscriptWriteFailed, "transcript.write.failed" }, - { ConversationEventKind.StateRestorePartial, "state.restore.partial" }, - { ConversationEventKind.TranscriptResyncFailed, "transcript.resync.failed" }, - }; + /// Every diagnostic kind, beside the name a log line gives it. + public static TheoryData DiagnosticKinds => + new() + { + { ConversationEventKind.ModerationUnavailable, "moderation.unavailable" }, + { ConversationEventKind.ModerationClean, "moderation.clean" }, + { ConversationEventKind.EmptyReply, "reply.empty" }, + { ConversationEventKind.ExtractionFailed, "extraction.failed" }, + { ConversationEventKind.TranscriptWriteFailed, "transcript.write.failed" }, + { ConversationEventKind.StateRestorePartial, "state.restore.partial" }, + { ConversationEventKind.TranscriptResyncFailed, "transcript.resync.failed" }, + }; - [Theory] - [MemberData(nameof(StoredKinds))] - public void AStoredKind_NamesItsRowAndItsToken(ConversationEventKind kind, AuditEventKind expected, string token) - { - Assert.True(ConversationEventKinds.TryGetAuditKind(kind, out AuditEventKind mapped)); - Assert.Equal(expected, mapped); + [Theory] + [MemberData(nameof(StoredKinds))] + public void AStoredKind_NamesItsRowAndItsToken(ConversationEventKind kind, AuditEventKind expected, string token) + { + Assert.True(ConversationEventKinds.TryGetAuditKind(kind, out AuditEventKind mapped)); + Assert.Equal(expected, mapped); - // The token is the chain's, and it is a permanent promise. Nothing here invents one. - Assert.Equal(token, ConversationEventKinds.ToToken(kind)); - Assert.Equal(AuditEventKinds.ToToken(expected), ConversationEventKinds.ToToken(kind)); - } + // The token is the chain's, and it is a permanent promise. Nothing here invents one. + Assert.Equal(token, ConversationEventKinds.ToToken(kind)); + Assert.Equal(AuditEventKinds.ToToken(expected), ConversationEventKinds.ToToken(kind)); + } - [Theory] - [MemberData(nameof(DiagnosticKinds))] - public void ADiagnosticKind_MapsToNoRowAndIsStillNamed(ConversationEventKind kind, string token) - { - Assert.False(ConversationEventKinds.TryGetAuditKind(kind, out _)); + [Theory] + [MemberData(nameof(DiagnosticKinds))] + public void ADiagnosticKind_MapsToNoRowAndIsStillNamed(ConversationEventKind kind, string token) + { + Assert.False(ConversationEventKinds.TryGetAuditKind(kind, out _)); - // It reaches no chain, so AuditEventKinds knows no token for it. A report still has to name it. - Assert.Equal(token, ConversationEventKinds.ToToken(kind)); - } + // It reaches no chain, so AuditEventKinds knows no token for it. A report still has to name it. + Assert.Equal(token, ConversationEventKinds.ToToken(kind)); + } - [Fact] - public void EveryKind_IsEitherStoredOrDiagnostic_AndEveryOneIsCovered() - { - var stored = Enum.GetValues() - .Count(kind => ConversationEventKinds.TryGetAuditKind(kind, out _)); + [Fact] + public void EveryKind_IsEitherStoredOrDiagnostic_AndEveryOneIsCovered() + { + int stored = Enum.GetValues() + .Count(kind => ConversationEventKinds.TryGetAuditKind(kind, out _)); - Assert.Equal(14, Enum.GetValues().Length); - Assert.Equal(7, stored); - } + Assert.Equal(14, Enum.GetValues().Length); + Assert.Equal(7, stored); + } - [Fact] - public void AValueOutsideTheClosedSet_IsNamedRatherThanThrownOver() - { - // A kind the enum does not hold must not cost a report the fault it is carrying. - const ConversationEventKind Unknown = (ConversationEventKind)999; + [Fact] + public void AValueOutsideTheClosedSet_IsNamedRatherThanThrownOver() + { + // A kind the enum does not hold must not cost a report the fault it is carrying. + const ConversationEventKind Unknown = (ConversationEventKind)999; - Assert.False(ConversationEventKinds.TryGetAuditKind(Unknown, out _)); - Assert.Equal("999", ConversationEventKinds.ToToken(Unknown)); + Assert.False(ConversationEventKinds.TryGetAuditKind(Unknown, out _)); + Assert.Equal("999", ConversationEventKinds.ToToken(Unknown)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationObserverDispatcherTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationObserverDispatcherTests.cs index 05f7a22f..6bebcfdf 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationObserverDispatcherTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationObserverDispatcherTests.cs @@ -4,359 +4,370 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The one seam between the turn loop and everything that watches it. -/// -/// -/// Section 7 measures a durable insert at 13 ms p50 against 91 nanoseconds to enqueue, so the rule -/// these tests fix is that no observer ever sits on the turn: a fast one costs the caller nothing but -/// the conversation itself, a slow one is watched off-turn, and one that throws is reported and forgotten. -/// The fourth rule is the one the old fire-and-forget code did not have. The chain of D23 is a record -/// of a conversation, so the facts of one conversation must reach an observer in the order the conversation produced them, -/// however long any one of them takes. -/// -public sealed class ConversationObserverDispatcherTests +namespace AgentCore.Application.Tests.Runtime { - private const string ConversationId = "conversation-1"; - - /// The id Log.AuditAppendFailed carries. It is unchanged by the hook. - private const int AuditAppendFailedEventId = 5; - - [Fact] - public void AnObserverThatAnswersAtOnce_HasTheEventBeforeDispatchReturns() + /// + /// The one seam between the turn loop and everything that watches it. + /// + /// + /// Section 7 measures a durable insert at 13 ms p50 against 91 nanoseconds to enqueue, so the rule + /// these tests fix is that no observer ever sits on the turn: a fast one costs the caller nothing but + /// the conversation itself, a slow one is watched off-turn, and one that throws is reported and forgotten. + /// The fourth rule is the one the old fire-and-forget code did not have. The chain of D23 is a record + /// of a conversation, so the facts of one conversation must reach an observer in the order the conversation produced them, + /// however long any one of them takes. + /// + public sealed class ConversationObserverDispatcherTests { - var observer = new RecordingObserver(); - var dispatcher = new ConversationObserverDispatcher([observer]); + private const string ConversationId = "conversation-1"; - dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); + /// The id Log.AuditAppendFailed carries. It is unchanged by the hook. + private const int AuditAppendFailedEventId = 5; - // No await anywhere: a synchronous observer runs on the caller's thread, which is what makes - // the fast path cost the turn the enqueue and nothing else. - Assert.Equal([ConversationEventKind.ConversationStarted], observer.Seen); - } + [Fact] + public void AnObserverThatAnswersAtOnce_HasTheEventBeforeDispatchReturns() + { + RecordingObserver observer = new(); + ConversationObserverDispatcher dispatcher = new([observer]); - [Fact] - public void ManyEventsThroughTheFastPath_ArriveInOrder() - { - var observer = new RecordingObserver(); - var dispatcher = new ConversationObserverDispatcher([observer]); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); - dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); - dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); - dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); + // No await anywhere: a synchronous observer runs on the caller's thread, which is what makes + // the fast path cost the turn the enqueue and nothing else. + Assert.Equal([ConversationEventKind.ConversationStarted], observer.Seen); + } - Assert.Equal( - [ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], - observer.Seen); - } + [Fact] + public void ManyEventsThroughTheFastPath_ArriveInOrder() + { + RecordingObserver observer = new(); + ConversationObserverDispatcher dispatcher = new([observer]); - [Fact] - public void EveryObserver_ReadsTheSameEvent_InTheOrderTheyWereGiven() - { - var first = new RecordingObserver(); - var second = new RecordingObserver(); - var order = new List(); - first.OnEvent = _ => order.Add("first"); - second.OnEvent = _ => order.Add("second"); - var dispatcher = new ConversationObserverDispatcher([first, second]); - - dispatcher.Dispatch(Event(ConversationEventKind.ToolFailed)); - - Assert.Equal([ConversationEventKind.ToolFailed], first.Seen); - Assert.Equal([ConversationEventKind.ToolFailed], second.Seen); - Assert.Equal(["first", "second"], order); - } + dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); + dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); - [Fact] - public void NoObserversAtAll_IsANoOp() - { - var dispatcher = new ConversationObserverDispatcher([]); + Assert.Equal( + [ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], + observer.Seen); + } - dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); + [Fact] + public void EveryObserver_ReadsTheSameEvent_InTheOrderTheyWereGiven() + { + RecordingObserver first = new(); + RecordingObserver second = new(); + List order = []; + first.OnEvent = _ => order.Add("first"); + second.OnEvent = _ => order.Add("second"); + ConversationObserverDispatcher dispatcher = new([first, second]); + + dispatcher.Dispatch(Event(ConversationEventKind.ToolFailed)); + + Assert.Equal([ConversationEventKind.ToolFailed], first.Seen); + Assert.Equal([ConversationEventKind.ToolFailed], second.Seen); + Assert.Equal(["first", "second"], order); + } - Assert.Equal(0, dispatcher.Count); - } + [Fact] + public void NoObserversAtAll_IsANoOp() + { + ConversationObserverDispatcher dispatcher = new([]); - [Fact] - public async Task AnObserverThatBlocks_DoesNotBlockTheCaller() - { - var observer = new GatedObserver(); - var dispatcher = new ConversationObserverDispatcher([observer]); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); - // The observer is inside OnConversationEventAsync and will stay there until the test releases it. - // Dispatch still returns, which is the whole contract of the port. - dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); + Assert.Equal(0, dispatcher.Count); + } - await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); - Assert.Empty(observer.Seen); + [Fact] + public async Task AnObserverThatBlocks_DoesNotBlockTheCaller() + { + GatedObserver observer = new(); + ConversationObserverDispatcher dispatcher = new([observer]); - observer.Release(); - await WaitFor(() => observer.Seen.Count == 1); - } + // The observer is inside OnConversationEventAsync and will stay there until the test releases it. + // Dispatch still returns, which is the whole contract of the port. + dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); - [Fact] - public async Task TwoSlowEvents_ReachTheObserverInTheOrderTheConversationRaisedThem() - { - // The old code was `_ = ObserveAppendAsync(...)`, so the second event overtook the first - // whenever the first was slower. The second gate is released FIRST here, which is exactly - // the race that used to shuffle the chain. - var observer = new GatedObserver(); - var dispatcher = new ConversationObserverDispatcher([observer]); + await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); + Assert.Empty(observer.Seen); - dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); - await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); + observer.Release(); + await WaitFor(() => observer.Seen.Count == 1); + } - dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); + [Fact] + public async Task TwoSlowEvents_ReachTheObserverInTheOrderTheConversationRaisedThem() + { + // The old code was `_ = ObserveAppendAsync(...)`, so the second event overtook the first + // whenever the first was slower. The second gate is released FIRST here, which is exactly + // the race that used to shuffle the chain. + GatedObserver observer = new(); + ConversationObserverDispatcher dispatcher = new([observer]); - // The second event is queued behind the first, so the observer has not even been asked about - // it yet. There is nothing to release. - Assert.Equal(1, observer.Entries); + dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); + await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); - observer.Release(); - await WaitFor(() => observer.Seen.Count == 2); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); - Assert.Equal([ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], observer.Seen); - } + // The second event is queued behind the first, so the observer has not even been asked about + // it yet. There is nothing to release. + Assert.Equal(1, observer.Entries); - [Fact] - public async Task ASlowObserver_DoesNotDelayALaterEventForAFastOne() - { - // Order is a guarantee per observer, and only per observer. A single shared tail would put - // the counters and the log lines of every later fact behind the sink still writing an earlier - // row, which is the cost section 8.6 and section 8.7 are not allowed to pay. - var slow = new GatedObserver(); - var fast = new RecordingObserver(); - var dispatcher = new ConversationObserverDispatcher([slow, fast]); + observer.Release(); + await WaitFor(() => observer.Seen.Count == 2); - dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); - await slow.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); + Assert.Equal([ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], observer.Seen); + } - // The slow observer is inside OnConversationEventAsync for the first event and stays there. - dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); + [Fact] + public async Task ASlowObserver_DoesNotDelayALaterEventForAFastOne() + { + // Order is a guarantee per observer, and only per observer. A single shared tail would put + // the counters and the log lines of every later fact behind the sink still writing an earlier + // row, which is the cost section 8.6 and section 8.7 are not allowed to pay. + GatedObserver slow = new(); + RecordingObserver fast = new(); + ConversationObserverDispatcher dispatcher = new([slow, fast]); - // No await anywhere between the dispatch and this assertion: the second fact reached the fast - // observer on the caller's thread while the first one was still open at the slow one. - Assert.Equal([ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], fast.Seen); + dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); + await slow.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); - // And the slow observer was never asked about the second fact, because its own first one is - // still open. Its order is kept while it costs nobody else anything. - Assert.Equal(1, slow.Entries); + // The slow observer is inside OnConversationEventAsync for the first event and stays there. + dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); - slow.Release(); - await WaitFor(() => slow.Seen.Count == 2); + // No await anywhere between the dispatch and this assertion: the second fact reached the fast + // observer on the caller's thread while the first one was still open at the slow one. + Assert.Equal([ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], fast.Seen); - Assert.Equal([ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], slow.Seen); - } + // And the slow observer was never asked about the second fact, because its own first one is + // still open. Its order is kept while it costs nobody else anything. + Assert.Equal(1, slow.Entries); - [Fact] - public async Task AQueuedEvent_StillArrivesWhenTheEventBeforeItFailed() - { - var observer = new GatedObserver { ThrowsOn = ConversationEventKind.TurnCompleted }; - var dispatcher = new ConversationObserverDispatcher([observer]); + slow.Release(); + await WaitFor(() => slow.Seen.Count == 2); - dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); - await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); + Assert.Equal([ConversationEventKind.TurnCompleted, ConversationEventKind.ConversationEnded], slow.Seen); + } - dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); - observer.Release(); + [Fact] + public async Task AQueuedEvent_StillArrivesWhenTheEventBeforeItFailed() + { + GatedObserver observer = new() { ThrowsOn = ConversationEventKind.TurnCompleted }; + ConversationObserverDispatcher dispatcher = new([observer]); - await WaitFor(() => observer.Seen.Count == 1); - Assert.Equal([ConversationEventKind.ConversationEnded], observer.Seen); - } + dispatcher.Dispatch(Event(ConversationEventKind.TurnCompleted)); + await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); - [Fact] - public void AnObserverThatThrowsAtOnce_NeitherPropagatesNorCostsTheOthersTheEvent() - { - var logger = new RecordingLogger(); - var throwing = new ThrowingObserver(); - var recording = new RecordingObserver(); - var dispatcher = new ConversationObserverDispatcher([throwing, recording], logger); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); + observer.Release(); - // Audit is a record of the conversation and never a part of it, so nothing here reaches the turn. - dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); + await WaitFor(() => observer.Seen.Count == 1); + Assert.Equal([ConversationEventKind.ConversationEnded], observer.Seen); + } - Assert.Equal([ConversationEventKind.ConversationStarted], recording.Seen); + [Fact] + public void AnObserverThatThrowsAtOnce_NeitherPropagatesNorCostsTheOthersTheEvent() + { + RecordingLogger logger = new(); + ThrowingObserver throwing = new(); + RecordingObserver recording = new(); + ConversationObserverDispatcher dispatcher = new([throwing, recording], logger); - var line = Assert.Single(logger.Of(AuditAppendFailedEventId)); - Assert.Equal(LogLevel.Error, line.Level); - Assert.Contains("conversation.started", line.Message, StringComparison.Ordinal); - Assert.Contains(ConversationId, line.Message, StringComparison.Ordinal); - Assert.IsType(line.Exception); - } + // Audit is a record of the conversation and never a part of it, so nothing here reaches the turn. + dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); - [Fact] - public async Task AnObserverThatThrowsLongAfterTheTurn_IsReportedAndNothingElseHappens() - { - var logger = new RecordingLogger(); - var observer = new GatedObserver { ThrowsOn = ConversationEventKind.ConversationEnded }; - var dispatcher = new ConversationObserverDispatcher([observer], logger); + Assert.Equal([ConversationEventKind.ConversationStarted], recording.Seen); - dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); - await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); + LogLine line = Assert.Single(logger.Of(AuditAppendFailedEventId)); + Assert.Equal(LogLevel.Error, line.Level); + Assert.Contains("conversation.started", line.Message, StringComparison.Ordinal); + Assert.Contains(ConversationId, line.Message, StringComparison.Ordinal); + _ = Assert.IsType(line.Exception); + } - observer.Release(); - await WaitFor(() => logger.Of(AuditAppendFailedEventId).Count == 1); + [Fact] + public async Task AnObserverThatThrowsLongAfterTheTurn_IsReportedAndNothingElseHappens() + { + RecordingLogger logger = new(); + GatedObserver observer = new() { ThrowsOn = ConversationEventKind.ConversationEnded }; + ConversationObserverDispatcher dispatcher = new([observer], logger); - var line = Assert.Single(logger.Of(AuditAppendFailedEventId)); - Assert.Contains("conversation.ended", line.Message, StringComparison.Ordinal); - Assert.IsType(line.Exception); - } + dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); + await observer.Entered.Task.WaitAsync(TestContext.Current.CancellationToken); - [Fact] - public void ADiagnosticKind_IsReportedUnderItsOwnToken() - { - var logger = new RecordingLogger(); - var dispatcher = new ConversationObserverDispatcher([new ThrowingObserver()], logger); + observer.Release(); + await WaitFor(() => logger.Of(AuditAppendFailedEventId).Count == 1); - // The four diagnostic kinds reach no chain, so AuditEventKinds knows no token for them. The - // report still has to name what failed. - dispatcher.Dispatch(Event(ConversationEventKind.ExtractionFailed)); + LogLine line = Assert.Single(logger.Of(AuditAppendFailedEventId)); + Assert.Contains("conversation.ended", line.Message, StringComparison.Ordinal); + _ = Assert.IsType(line.Exception); + } - var line = Assert.Single(logger.Of(AuditAppendFailedEventId)); - Assert.Contains("extraction.failed", line.Message, StringComparison.Ordinal); - } + [Fact] + public void ADiagnosticKind_IsReportedUnderItsOwnToken() + { + RecordingLogger logger = new(); + ConversationObserverDispatcher dispatcher = new([new ThrowingObserver()], logger); - [Fact] - public void AFailingObserver_DoesNotStopTheNextEvent() - { - var throwing = new ThrowingObserver(); - var recording = new RecordingObserver(); - var dispatcher = new ConversationObserverDispatcher([throwing, recording]); + // The four diagnostic kinds reach no chain, so AuditEventKinds knows no token for them. The + // report still has to name what failed. + dispatcher.Dispatch(Event(ConversationEventKind.ExtractionFailed)); - dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); - dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); + LogLine line = Assert.Single(logger.Of(AuditAppendFailedEventId)); + Assert.Contains("extraction.failed", line.Message, StringComparison.Ordinal); + } - Assert.Equal([ConversationEventKind.ConversationStarted, ConversationEventKind.ConversationEnded], recording.Seen); - } + [Fact] + public void AFailingObserver_DoesNotStopTheNextEvent() + { + ThrowingObserver throwing = new(); + RecordingObserver recording = new(); + ConversationObserverDispatcher dispatcher = new([throwing, recording]); - [Fact] - public void NoEvent_IsRefused() - => Assert.Throws( - () => new ConversationObserverDispatcher([new RecordingObserver()]).Dispatch(null!)); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationStarted)); + dispatcher.Dispatch(Event(ConversationEventKind.ConversationEnded)); - private static ConversationEvent Event(ConversationEventKind kind) => new() - { - ConversationId = ConversationId, - Kind = kind, - OccurredAt = DateTimeOffset.UnixEpoch, - }; + Assert.Equal([ConversationEventKind.ConversationStarted, ConversationEventKind.ConversationEnded], recording.Seen); + } - /// Waits for something an observer does off-turn, and fails rather than hanging. - private static async Task WaitFor(Func condition) - { - using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(10)); - while (!condition()) + [Fact] + public void NoEvent_IsRefused() { - await Task.Delay(5, deadline.Token); + _ = Assert.Throws( + () => new ConversationObserverDispatcher([new RecordingObserver()]).Dispatch(null!)); } - } - /// - /// An observer that answers at once and remembers what it read. - /// - private sealed class RecordingObserver : IConversationObserver - { - private readonly Lock _gate = new(); - private readonly List _seen = []; + private static ConversationEvent Event(ConversationEventKind kind) + { + return new() + { + ConversationId = ConversationId, + Kind = kind, + OccurredAt = DateTimeOffset.UnixEpoch, + }; + } - /// Gets what the observer read, oldest first. - public IReadOnlyList Seen + /// Waits for something an observer does off-turn, and fails rather than hanging. + private static async Task WaitFor(Func condition) { - get + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + while (!condition()) { - lock (_gate) - { - return [.. _seen]; - } + await Task.Delay(5, deadline.Token); } } - /// Runs beside the recording, so a test can watch the order across observers. - public Action? OnEvent { get; set; } - - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + /// + /// An observer that answers at once and remembers what it read. + /// + private sealed class RecordingObserver : IConversationObserver { - Assert.False(cancellationToken.CanBeCanceled, "The dispatcher passes CancellationToken.None."); + private readonly Lock _gate = new(); + private readonly List _seen = []; - lock (_gate) + /// Gets what the observer read, oldest first. + public IReadOnlyList Seen { - _seen.Add(conversationEvent.Kind); + get + { + lock (_gate) + { + return [.. _seen]; + } + } } - OnEvent?.Invoke(conversationEvent); - return ValueTask.CompletedTask; - } - } + /// Runs beside the recording, so a test can watch the order across observers. + public Action? OnEvent { get; set; } - /// - /// An observer that holds every event open until a test releases it. - /// - /// - /// It records AFTER the gate, so answers what the observer finished and - /// answers what it was asked about. The difference is what an ordering test - /// reads. - /// - private sealed class GatedObserver : IConversationObserver - { - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly Lock _lock = new(); - private readonly List _seen = []; - private int _entries; - - /// Gets the events the observer accepted, oldest first. - public IReadOnlyList Seen - { - get + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - lock (_lock) + Assert.False(cancellationToken.CanBeCanceled, "The dispatcher passes CancellationToken.None."); + + lock (_gate) { - return [.. _seen]; + _seen.Add(conversationEvent.Kind); } + + OnEvent?.Invoke(conversationEvent); + return ValueTask.CompletedTask; } } - /// Gets the number of times the dispatcher has called the observer. - public int Entries => Volatile.Read(ref _entries); - - /// Set when the dispatcher first calls the observer. - public TaskCompletionSource Entered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); + /// + /// An observer that holds every event open until a test releases it. + /// + /// + /// It records AFTER the gate, so answers what the observer finished and + /// answers what it was asked about. The difference is what an ordering test + /// reads. + /// + private sealed class GatedObserver : IConversationObserver + { + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly Lock _lock = new(); + private readonly List _seen = []; + private int _entries; - /// The one kind the observer refuses, or when it refuses none. - public ConversationEventKind? ThrowsOn { get; init; } + /// Gets the events the observer accepted, oldest first. + public IReadOnlyList Seen + { + get + { + lock (_lock) + { + return [.. _seen]; + } + } + } - /// Lets every open conversation complete. - public void Release() => _gate.TrySetResult(); + /// Gets the number of times the dispatcher has called the observer. + public int Entries => Volatile.Read(ref _entries); - public async ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - { - Interlocked.Increment(ref _entries); - Entered.TrySetResult(); + /// Set when the dispatcher first calls the observer. + public TaskCompletionSource Entered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); - await _gate.Task.ConfigureAwait(false); + /// The one kind the observer refuses, or when it refuses none. + public ConversationEventKind? ThrowsOn { get; init; } - if (ThrowsOn == conversationEvent.Kind) + /// Lets every open conversation complete. + public void Release() { - throw new InvalidOperationException(ThrowingObserver.Message); + _ = _gate.TrySetResult(); } - lock (_lock) + public async ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - _seen.Add(conversationEvent.Kind); + _ = Interlocked.Increment(ref _entries); + _ = Entered.TrySetResult(); + + await _gate.Task.ConfigureAwait(false); + + if (ThrowsOn == conversationEvent.Kind) + { + throw new InvalidOperationException(ThrowingObserver.Message); + } + + lock (_lock) + { + _seen.Add(conversationEvent.Kind); + } } } - } - /// - /// An observer that refuses every event before it has awaited anything. - /// - private sealed class ThrowingObserver : IConversationObserver - { - /// The message every refusal carries. - public const string Message = "the observer is broken."; + /// + /// An observer that refuses every event before it has awaited anything. + /// + private sealed class ThrowingObserver : IConversationObserver + { + /// The message every refusal carries. + public const string Message = "the observer is broken."; - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - => throw new InvalidOperationException(Message); + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + { + throw new InvalidOperationException(Message); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationObserversTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationObserversTests.cs index 9cb9f6c1..17bef96d 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationObserversTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationObserversTests.cs @@ -5,81 +5,86 @@ using AgentCore.Domain.Audit; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// assembles the readings of one conversation, in the order the cost -/// story of section 7 asks for. -/// -/// -/// The order is the contract: the counters of section 8.6 and the rows of section 8.7 are taken -/// above the enqueue, and code this library did not write goes after all three. The list is what -/// is handed, so this is where the rule is tested rather than -/// inside the factory that no longer knows it. -/// -public sealed class ConversationObserversTests +namespace AgentCore.Application.Tests.Runtime { - /// A host reading that records nothing and only has to be found in the list. - private sealed class HostObserver : IConversationObserver + /// + /// assembles the readings of one conversation, in the order the cost + /// story of section 7 asks for. + /// + /// + /// The order is the contract: the counters of section 8.6 and the rows of section 8.7 are taken + /// above the enqueue, and code this library did not write goes after all three. The list is what + /// is handed, so this is where the rule is tested rather than + /// inside the factory that no longer knows it. + /// + public sealed class ConversationObserversTests { - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - => ValueTask.CompletedTask; - } + /// A host reading that records nothing and only has to be found in the list. + private sealed class HostObserver : IConversationObserver + { + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + { + return ValueTask.CompletedTask; + } + } - /// A sink that accepts everything, so that the audit reading has something to write to. - private sealed class AcceptingSink : IAuditSinkPort - { - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken) - => ValueTask.CompletedTask; - } + /// A sink that accepts everything, so that the audit reading has something to write to. + private sealed class AcceptingSink : IAuditSinkPort + { + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken) + { + return ValueTask.CompletedTask; + } + } - [Fact] - public void EveryLibraryReadingIsTaken() - { - // The audit reading is no longer conditional on a host having bound something. The - // composition root resolves providers.audit for every host and falls back to the in-process - // memory kind, so all three readings of a conversation are always built and the chain of D23 is - // written whatever the document names. - var observers = ConversationObservers.Standard(new AcceptingSink(), logger: null); + [Fact] + public void EveryLibraryReadingIsTaken() + { + // The audit reading is no longer conditional on a host having bound something. The + // composition root resolves providers.audit for every host and falls back to the in-process + // memory kind, so all three readings of a conversation are always built and the chain of D23 is + // written whatever the document names. + IReadOnlyList observers = ConversationObservers.Standard(new AcceptingSink(), logger: null); - Assert.Equal(3, observers.Count); - Assert.IsType(observers[2]); - } + Assert.Equal(3, observers.Count); + _ = Assert.IsType(observers[2]); + } - [Fact] - public void NoSinkIsNotAShapeTheListCanHave() - { - // There is no "bound nothing" list to build, so asking for one is a caller's mistake rather - // than a two-observer reading of the conversation. - Assert.Throws( - "auditSink", - () => ConversationObservers.Standard(auditSink: null!, logger: null)); - } + [Fact] + public void NoSinkIsNotAShapeTheListCanHave() + { + // There is no "bound nothing" list to build, so asking for one is a caller's mistake rather + // than a two-observer reading of the conversation. + _ = Assert.Throws( + "auditSink", + () => ConversationObservers.Standard(auditSink: null!, logger: null)); + } - [Fact] - public void BoundSinkPutsTheAuditReadingLast() - { - var observers = ConversationObservers.Standard(new AcceptingSink(), logger: null); + [Fact] + public void BoundSinkPutsTheAuditReadingLast() + { + IReadOnlyList observers = ConversationObservers.Standard(new AcceptingSink(), logger: null); - Assert.Collection( - observers, - observer => Assert.IsType(observer), - observer => Assert.IsType(observer), - observer => Assert.IsType(observer)); - } + Assert.Collection( + observers, + observer => Assert.IsType(observer), + observer => Assert.IsType(observer), + observer => Assert.IsType(observer)); + } - [Fact] - public void HostReadingsComeAfterEveryLibraryReading() - { - HostObserver host = new(); + [Fact] + public void HostReadingsComeAfterEveryLibraryReading() + { + HostObserver host = new(); - var observers = ConversationObservers.Standard(new AcceptingSink(), logger: null, [host]); + IReadOnlyList observers = ConversationObservers.Standard(new AcceptingSink(), logger: null, [host]); - Assert.Collection( - observers, - observer => Assert.IsType(observer), - observer => Assert.IsType(observer), - observer => Assert.IsType(observer), - observer => Assert.Same(host, observer)); + Assert.Collection( + observers, + observer => Assert.IsType(observer), + observer => Assert.IsType(observer), + observer => Assert.IsType(observer), + observer => Assert.Same(host, observer)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionApprovalTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionApprovalTests.cs index c1606d75..cc888dfa 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionApprovalTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionApprovalTests.cs @@ -2,25 +2,25 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Runtime; -using AgentCore.Application.State; using AgentCore.Application.Tests.Fakes; +using AgentCore.Domain; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The approval round trip through the turn loop: a gated tool suspends the turn with a request -/// instead of failing it, and the caller's answer on the same conversation runs the tool. -/// -/// -/// Every test here runs offline. There is no network conversation and no API key anywhere in this file. -/// -public sealed class ConversationSessionApprovalTests +namespace AgentCore.Application.Tests.Runtime { - private const string GatedYaml = - """ + /// + /// The approval round trip through the turn loop: a gated tool suspends the turn with a request + /// instead of failing it, and the caller's answer on the same conversation runs the tool. + /// + /// + /// Every test here runs offline. There is no network conversation and no API key anywhere in this file. + /// + public sealed class ConversationSessionApprovalTests + { + private const string GatedYaml = + """ apiVersion: agentcore/v1 tools: - { id: send_email, kind: builtin, uses: test.send, description: "Send an email." } @@ -34,144 +34,148 @@ public sealed class ConversationSessionApprovalTests agent: only """; - [Fact] - public async Task AGatedToolCall_EndsTheTurnWithTheRequestAndNoFailure() - { - var token = TestContext.Current.CancellationToken; - int sent = 0; - var session = Session(GatedYaml, () => sent++, token); - - var turn = await session.RunTurnAsync("send it", token); - - Assert.Null(turn.Failure); - Assert.Equal(string.Empty, turn.ReplyText); - Assert.Equal(0, sent); - var approval = Assert.Single(turn.Approvals); - Assert.False(string.IsNullOrEmpty(approval.RequestId)); - Assert.Equal("send_email", approval.ToolName); - Assert.Equal("a@b.com", approval.Arguments.GetProperty("to").GetString()); - } - - [Fact] - public async Task AnApprovalAnswer_RunsTheToolAndReplies() - { - var token = TestContext.Current.CancellationToken; - int sent = 0; - var session = Session(GatedYaml, () => sent++, token); - - var asked = await session.RunTurnAsync("send it", token); - var answer = session.TryCreateApprovalAnswer(asked.Approvals[0].RequestId, approved: true); - Assert.NotNull(answer); - var replied = await session.RunTurnMessageAsync(answer!, token); - - Assert.Equal(1, sent); - Assert.Null(replied.Failure); - Assert.Equal("done.", replied.ReplyText); - Assert.Empty(replied.Approvals); - } + [Fact] + public async Task AGatedToolCall_EndsTheTurnWithTheRequestAndNoFailure() + { + CancellationToken token = TestContext.Current.CancellationToken; + int sent = 0; + ConversationSession session = Session(GatedYaml, () => sent++, token); + + TurnResult turn = await session.RunTurnAsync("send it", token); + + Assert.Null(turn.Failure); + Assert.Equal(string.Empty, turn.ReplyText); + Assert.Equal(0, sent); + PendingApproval approval = Assert.Single(turn.Approvals); + Assert.False(string.IsNullOrEmpty(approval.RequestId)); + Assert.Equal("send_email", approval.ToolName); + Assert.Equal("a@b.com", approval.Arguments.GetProperty("to").GetString()); + } - [Fact] - public async Task ARejection_LeavesTheToolUnrun() - { - var token = TestContext.Current.CancellationToken; - int sent = 0; - var session = Session(GatedYaml, () => sent++, token); + [Fact] + public async Task AnApprovalAnswer_RunsTheToolAndReplies() + { + CancellationToken token = TestContext.Current.CancellationToken; + int sent = 0; + ConversationSession session = Session(GatedYaml, () => sent++, token); + + TurnResult asked = await session.RunTurnAsync("send it", token); + ChatMessage? answer = session.TryCreateApprovalAnswer(asked.Approvals[0].RequestId, approved: true); + Assert.NotNull(answer); + TurnResult replied = await session.RunTurnMessageAsync(answer!, token); + + Assert.Equal(1, sent); + Assert.Null(replied.Failure); + Assert.Equal("done.", replied.ReplyText); + Assert.Empty(replied.Approvals); + } - var asked = await session.RunTurnAsync("send it", token); - var answer = session.TryCreateApprovalAnswer(asked.Approvals[0].RequestId, approved: false); - Assert.NotNull(answer); - var replied = await session.RunTurnMessageAsync(answer!, token); + [Fact] + public async Task ARejection_LeavesTheToolUnrun() + { + CancellationToken token = TestContext.Current.CancellationToken; + int sent = 0; + ConversationSession session = Session(GatedYaml, () => sent++, token); - Assert.Equal(0, sent); - Assert.Null(replied.Failure); - } + TurnResult asked = await session.RunTurnAsync("send it", token); + ChatMessage? answer = session.TryCreateApprovalAnswer(asked.Approvals[0].RequestId, approved: false); + Assert.NotNull(answer); + TurnResult replied = await session.RunTurnMessageAsync(answer!, token); - [Fact] - public async Task AnUnknownRequestId_BuildsNoAnswer() - { - var token = TestContext.Current.CancellationToken; - var session = Session(GatedYaml, () => { }, token); + Assert.Equal(0, sent); + Assert.Null(replied.Failure); + } - _ = await session.RunTurnAsync("send it", token); + [Fact] + public async Task AnUnknownRequestId_BuildsNoAnswer() + { + CancellationToken token = TestContext.Current.CancellationToken; + ConversationSession session = Session(GatedYaml, () => { }, token); - Assert.Null(session.TryCreateApprovalAnswer("no-such-request", approved: true)); - } + _ = await session.RunTurnAsync("send it", token); - [Fact] - public async Task AnAnsweredRequest_BuildsNoSecondAnswer() - { - var token = TestContext.Current.CancellationToken; - var session = Session(GatedYaml, () => { }, token); + Assert.Null(session.TryCreateApprovalAnswer("no-such-request", approved: true)); + } - var asked = await session.RunTurnAsync("send it", token); - var requestId = asked.Approvals[0].RequestId; - var answer = session.TryCreateApprovalAnswer(requestId, approved: true); + [Fact] + public async Task AnAnsweredRequest_BuildsNoSecondAnswer() + { + CancellationToken token = TestContext.Current.CancellationToken; + ConversationSession session = Session(GatedYaml, () => { }, token); - Assert.NotNull(answer); - _ = await session.RunTurnMessageAsync(answer, token); + TurnResult asked = await session.RunTurnAsync("send it", token); + string requestId = asked.Approvals[0].RequestId; + ChatMessage? answer = session.TryCreateApprovalAnswer(requestId, approved: true); - Assert.Null(session.TryCreateApprovalAnswer(requestId, approved: true)); - } + Assert.NotNull(answer); + _ = await session.RunTurnMessageAsync(answer, token); - [Fact] - public async Task AGatedToolCall_StreamsTheRequestToTheHost() - { - var token = TestContext.Current.CancellationToken; - var session = Session(GatedYaml, () => { }, token); + Assert.Null(session.TryCreateApprovalAnswer(requestId, approved: true)); + } - List updates = []; - await foreach (var update in session.RunTurnStreamingAsync("send it", token)) + [Fact] + public async Task AGatedToolCall_StreamsTheRequestToTheHost() { - updates.Add(update); + CancellationToken token = TestContext.Current.CancellationToken; + ConversationSession session = Session(GatedYaml, () => { }, token); + + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("send it", token)) + { + updates.Add(update); + } + + Assert.Contains( + updates.SelectMany(update => update.Contents), + content => content is ToolApprovalRequestContent); + Assert.Null(session.LastTurn?.Failure); + Assert.NotEmpty(session.LastTurn?.Approvals ?? []); } - Assert.Contains( - updates.SelectMany(update => update.Contents), - content => content is ToolApprovalRequestContent); - Assert.Null(session.LastTurn?.Failure); - Assert.NotEmpty(session.LastTurn?.Approvals ?? []); - } + [Fact] + public async Task AGatedToolCall_KeepsTheQueueInTheSnapshot() + { + CancellationToken token = TestContext.Current.CancellationToken; + ConversationSession session = Session(GatedYaml, () => { }, token); - [Fact] - public async Task AGatedToolCall_KeepsTheQueueInTheSnapshot() - { - var token = TestContext.Current.CancellationToken; - var session = Session(GatedYaml, () => { }, token); + _ = await session.RunTurnAsync("send it", token); - _ = await session.RunTurnAsync("send it", token); + Assert.True(session.Snapshot().Providers.ContainsKey("_pendingApprovalRequests")); + } - Assert.True(session.Snapshot().Providers.ContainsKey("_pendingApprovalRequests")); - } + private static ConversationSession Session(string yaml, Action onSend, CancellationToken token) + { + ToolCallingChatClient client = new( + "done.", + new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" }); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(client)) + { + Tools = TestToolRegistry.From( + document, + declared => declared.Uses == "test.send" ? GatedSendEmail(onSend) : null, + token), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new TestGuardEvaluator(document), + extractor: null, + timeProvider: null).Create(); + } - private static ConversationSession Session(string yaml, Action onSend, CancellationToken token) - { - ToolCallingChatClient client = new( - "done.", - new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" }); - var document = ConfigurationLoader.LoadYaml(yaml); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(client)) + private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) + { + return new(AIFunctionFactory.Create( + (string to) => { - Tools = TestToolRegistry.From( - document, - declared => declared.Uses == "test.send" ? GatedSendEmail(onSend) : null, - token), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new TestGuardEvaluator(document), - extractor: null, - timeProvider: null).Create(); + onSend(); + return "sent"; + }, + "send_email", + "Send an email.")); + } } - - private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) => new(AIFunctionFactory.Create( - (string to) => - { - onSend(); - return "sent"; - }, - "send_email", - "Send an email.")); } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionEditTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionEditTests.cs index 25d25918..799a8cec 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionEditTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionEditTests.cs @@ -9,15 +9,16 @@ using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// A caller sends an earlier message again, and the conversation takes back what it said after it. -/// -public sealed class ConversationSessionEditTests +namespace AgentCore.Application.Tests.Runtime { - private const string OneAgentYaml = """ + /// + /// A caller sends an earlier message again, and the conversation takes back what it said after it. + /// + public sealed class ConversationSessionEditTests + { + private const string OneAgentYaml = """ apiVersion: agentcore/v1 agents: items: @@ -27,7 +28,7 @@ public sealed class ConversationSessionEditTests agent: only """; - private const string TerminalYaml = """ + private const string TerminalYaml = """ apiVersion: agentcore/v1 agents: items: @@ -40,158 +41,159 @@ public sealed class ConversationSessionEditTests - { id: done, agent: only, terminal: true } """; - [Fact] - public async Task AnEdit_TakesTheReplacedWordsOutOfWhatTheModelReads() - { - using ScriptedChatClient scripted = new("an answer."); - RequestCapturingChatClient reply = new(scripted); - var session = CreateSession(OneAgentYaml, reply); - - await session.RunTurnAtOriginAsync( - "first question", - new ConversationTurnOrigin("caller-1", null) { NamesParent = true }, - TestContext.Current.CancellationToken); - var firstReply = session.LastReplyMessageId; - - await session.RunTurnAtOriginAsync( - "second question", - new ConversationTurnOrigin("caller-2", firstReply) { NamesParent = true }, - TestContext.Current.CancellationToken); - - await session.RunTurnAtOriginAsync( - "second question, rewritten", - new ConversationTurnOrigin("caller-3", firstReply) { NamesParent = true }, - TestContext.Current.CancellationToken); - - // What the model was actually handed, not what the reply says: a stub controls the reply - // whatever the history did. - var seen = reply.Requests[^1].Select(message => message.Text).ToList(); - Assert.Contains("first question", seen); - Assert.Contains("second question, rewritten", seen); - Assert.DoesNotContain("second question", seen); - } - - [Fact] - public async Task AnEdit_NamesTheTurnsItWithdrew() - { - using ScriptedChatClient reply = new("an answer."); - RecordingObserver observer = new(); - var session = CreateSession(OneAgentYaml, reply, observer); - - await session.RunTurnAtOriginAsync( - "q1", - new ConversationTurnOrigin("caller-1", null) { NamesParent = true }, - TestContext.Current.CancellationToken); - var firstReply = session.LastReplyMessageId; - - await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - - await session.RunTurnAtOriginAsync( - "q2, rewritten", - new ConversationTurnOrigin("caller-4", firstReply) { NamesParent = true }, - TestContext.Current.CancellationToken); - - // The rows of turns 1 and 2 are deleted by now, so the trail can only say what it was told. - var superseded = Assert.Single( - observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); - Assert.Equal("1", superseded.Payload[AuditPayloadKeys.WithdrewFromTurnIndex]); - Assert.Equal("2", superseded.Payload[AuditPayloadKeys.WithdrewThroughTurnIndex]); - Assert.Equal(3, superseded.TurnIndex); - } - - [Fact] - public async Task AnEditOnATerminalConversation_IsRefusedAndTakesNothing() - { - using ScriptedChatClient reply = new("an answer."); - var session = CreateSession(TerminalYaml, reply); - - await session.RunTurnAtOriginAsync( - "q1", - new ConversationTurnOrigin("caller-1", null) { NamesParent = true }, - TestContext.Current.CancellationToken); - var firstReply = session.LastReplyMessageId; - Assert.True(session.IsComplete); - - await Assert.ThrowsAsync( - () => session.RunTurnAtOriginAsync( - "q1, rewritten", - new ConversationTurnOrigin("caller-2", null) { NamesParent = true }, - TestContext.Current.CancellationToken)); - - // The withdrawal deletes. A turn the guards refuse must not have taken the tail of the conversation - // with it on the way out, or the caller is left with neither the old words nor the new. - Assert.Equal(2, session.Transcript.Count); - Assert.NotNull(firstReply); - } - - [Fact] - public async Task AnOriginThatNamesNoParent_WithdrawsNothing() - { - using ScriptedChatClient reply = new("an answer."); - RecordingObserver observer = new(); - var session = CreateSession(OneAgentYaml, reply, observer); - - await session.RunTurnAsync("q1", TestContext.Current.CancellationToken); - - // A null parent means the start of the conversation and would take every word of it. A caller that - // named its own message and said nothing about a parent has asked for no such thing. - await session.RunTurnAtOriginAsync( - "q2", - new ConversationTurnOrigin("caller-2", null) { NamesParent = false }, - TestContext.Current.CancellationToken); - - Assert.Equal(4, session.Transcript.Count); - Assert.DoesNotContain(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); - } - - private static ConversationSession CreateSession( - string yaml, IChatClient reply, IConversationObserver? observer = null) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new FakeChatClientFactory(reply); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - ConversationStore = new InMemoryConversationStore(), - Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), - })["main"]; - - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null, - observers: observer is null ? null : [observer]); - - return factory.Create("conversation-1"); - } - - /// Keeps every fact of the conversation, in the order the turn loop raised them. - private sealed class RecordingObserver : IConversationObserver - { - private readonly Lock _gate = new(); - private readonly List _events = []; - - public IReadOnlyList Events - { - get - { - lock (_gate) - { - return [.. _events]; - } - } - } - - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - { - lock (_gate) - { - _events.Add(conversationEvent); - } - - return ValueTask.CompletedTask; - } - } - } + [Fact] + public async Task AnEdit_TakesTheReplacedWordsOutOfWhatTheModelReads() + { + using ScriptedChatClient scripted = new("an answer."); + RequestCapturingChatClient reply = new(scripted); + ConversationSession session = CreateSession(OneAgentYaml, reply); + + _ = await session.RunTurnAtOriginAsync( + "first question", + new ConversationTurnOrigin("caller-1", null) { NamesParent = true }, + TestContext.Current.CancellationToken); + string? firstReply = session.LastReplyMessageId; + + _ = await session.RunTurnAtOriginAsync( + "second question", + new ConversationTurnOrigin("caller-2", firstReply) { NamesParent = true }, + TestContext.Current.CancellationToken); + + _ = await session.RunTurnAtOriginAsync( + "second question, rewritten", + new ConversationTurnOrigin("caller-3", firstReply) { NamesParent = true }, + TestContext.Current.CancellationToken); + + // What the model was actually handed, not what the reply says: a stub controls the reply + // whatever the history did. + List seen = [.. reply.Requests[^1].Select(message => message.Text)]; + Assert.Contains("first question", seen); + Assert.Contains("second question, rewritten", seen); + Assert.DoesNotContain("second question", seen); + } + + [Fact] + public async Task AnEdit_NamesTheTurnsItWithdrew() + { + using ScriptedChatClient reply = new("an answer."); + RecordingObserver observer = new(); + ConversationSession session = CreateSession(OneAgentYaml, reply, observer); + + _ = await session.RunTurnAtOriginAsync( + "q1", + new ConversationTurnOrigin("caller-1", null) { NamesParent = true }, + TestContext.Current.CancellationToken); + string? firstReply = session.LastReplyMessageId; + + _ = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + + _ = await session.RunTurnAtOriginAsync( + "q2, rewritten", + new ConversationTurnOrigin("caller-4", firstReply) { NamesParent = true }, + TestContext.Current.CancellationToken); + + // The rows of turns 1 and 2 are deleted by now, so the trail can only say what it was told. + ConversationEvent superseded = Assert.Single( + observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); + Assert.Equal("1", superseded.Payload[AuditPayloadKeys.WithdrewFromTurnIndex]); + Assert.Equal("2", superseded.Payload[AuditPayloadKeys.WithdrewThroughTurnIndex]); + Assert.Equal(3, superseded.TurnIndex); + } + + [Fact] + public async Task AnEditOnATerminalConversation_IsRefusedAndTakesNothing() + { + using ScriptedChatClient reply = new("an answer."); + ConversationSession session = CreateSession(TerminalYaml, reply); + + _ = await session.RunTurnAtOriginAsync( + "q1", + new ConversationTurnOrigin("caller-1", null) { NamesParent = true }, + TestContext.Current.CancellationToken); + string? firstReply = session.LastReplyMessageId; + Assert.True(session.IsComplete); + + _ = await Assert.ThrowsAsync( + () => session.RunTurnAtOriginAsync( + "q1, rewritten", + new ConversationTurnOrigin("caller-2", null) { NamesParent = true }, + TestContext.Current.CancellationToken)); + + // The withdrawal deletes. A turn the guards refuse must not have taken the tail of the conversation + // with it on the way out, or the caller is left with neither the old words nor the new. + Assert.Equal(2, session.Transcript.Count); + Assert.NotNull(firstReply); + } + + [Fact] + public async Task AnOriginThatNamesNoParent_WithdrawsNothing() + { + using ScriptedChatClient reply = new("an answer."); + RecordingObserver observer = new(); + ConversationSession session = CreateSession(OneAgentYaml, reply, observer); + + _ = await session.RunTurnAsync("q1", TestContext.Current.CancellationToken); + + // A null parent means the start of the conversation and would take every word of it. A caller that + // named its own message and said nothing about a parent has asked for no such thing. + _ = await session.RunTurnAtOriginAsync( + "q2", + new ConversationTurnOrigin("caller-2", null) { NamesParent = false }, + TestContext.Current.CancellationToken); + + Assert.Equal(4, session.Transcript.Count); + Assert.DoesNotContain(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); + } + + private static ConversationSession CreateSession( + string yaml, IChatClient reply, IConversationObserver? observer = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + FakeChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + ConversationStore = new InMemoryConversationStore(), + Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), + })["main"]; + + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null, + observers: observer is null ? null : [observer]); + + return factory.Create("conversation-1"); + } + + /// Keeps every fact of the conversation, in the order the turn loop raised them. + private sealed class RecordingObserver : IConversationObserver + { + private readonly Lock _gate = new(); + private readonly List _events = []; + + public IReadOnlyList Events + { + get + { + lock (_gate) + { + return [.. _events]; + } + } + } + + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + { + lock (_gate) + { + _events.Add(conversationEvent); + } + + return ValueTask.CompletedTask; + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs index 772670e6..daf905cc 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs @@ -1,6 +1,7 @@ using System.Text.Json; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Runtime; using AgentCore.Application.State; using AgentCore.Application.Tests.Fakes; @@ -9,19 +10,19 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// ConversationSessionFactory.CreateExtractor is the third site that must strip a -/// before a model reads it — ConversationSession.ExtractAsync hands the -/// extractor [turn.Spoken, .. response.Messages], and response.Messages is exactly the -/// list a drawing tool attaches to. This proves the extractor builds, -/// not a hand-constructed ModelFacingChatClient. -/// -public sealed class ConversationSessionFactoryModelFacingTests +namespace AgentCore.Application.Tests.Runtime { - private const string Yaml = - """ + /// + /// ConversationSessionFactory.CreateExtractor is the third site that must strip a + /// before a model reads it — ConversationSession.ExtractAsync hands the + /// extractor [turn.Spoken, .. response.Messages], and response.Messages is exactly the + /// list a drawing tool attaches to. This proves the extractor builds, + /// not a hand-constructed ModelFacingChatClient. + /// + public sealed class ConversationSessionFactoryModelFacingTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: { type: boolean, default: false, writer: extractor } @@ -36,34 +37,35 @@ public sealed class ConversationSessionFactoryModelFacingTests agent: only """; - [Fact] - public async Task TheExtractorTheFactoryBuilds_NeverForwardsARenderContentTheTurnAttached() - { - var document = ConfigurationLoader.LoadYaml(Yaml); - var compiled = ConfigurationCompiler.CompileAll( - document, new AgentCompilationContext(new FakeChatClientFactory(new ScriptedChatClient("ok"))))["main"]; + [Fact] + public async Task TheExtractorTheFactoryBuilds_NeverForwardsARenderContentTheTurnAttached() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, new AgentCompilationContext(new FakeChatClientFactory(new ScriptedChatClient("ok"))))["main"]; - RequestCapturingChatClient recorder = new( - new ScriptedChatClient("""{ "callerSaidGoodbye": null }""")); + RequestCapturingChatClient recorder = new( + new ScriptedChatClient(/*lang=json,strict*/ """{ "callerSaidGoodbye": null }""")); - var extractor = ConversationSessionFactory.CreateExtractor( - compiled, new RoutingChatClientFactory(new ScriptedChatClient("ok")).Route("fill", recorder)); + StateExtractor? extractor = ConversationSessionFactory.CreateExtractor( + compiled, new RoutingChatClientFactory(new ScriptedChatClient("ok")).Route("fill", recorder)); - Assert.NotNull(extractor); + Assert.NotNull(extractor); - var payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); - var drew = new ChatMessage(ChatRole.Assistant, - [ - new TextContent("here's the order."), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = payload }, - ]); + JsonElement payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); + ChatMessage drew = new(ChatRole.Assistant, + [ + new TextContent("here's the order."), + new RenderContent { Name = "order-card", RenderId = "order-41", Data = payload }, + ]); - await extractor!.ExtractAsync( - new StateDocument(compiled.Configuration), - [new ChatMessage(ChatRole.User, "show me the order"), drew], - TestContext.Current.CancellationToken); + _ = await extractor!.ExtractAsync( + new StateDocument(compiled.Configuration), + [new ChatMessage(ChatRole.User, "show me the order"), drew], + TestContext.Current.CancellationToken); - var forwarded = Assert.Single(recorder.Requests); - Assert.DoesNotContain(forwarded, message => message.Contents.Any(content => content is RenderContent)); + IReadOnlyList forwarded = Assert.Single(recorder.Requests); + Assert.DoesNotContain(forwarded, message => message.Contents.Any(content => content is RenderContent)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionGraphReplyTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionGraphReplyTests.cs index 3555a2c9..26d96a90 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionGraphReplyTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionGraphReplyTests.cs @@ -1,6 +1,5 @@ using AgentCore.TestSupport; using AgentCore.Application.Audit.Memory; -using AgentCore.Application.Audit; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -11,33 +10,34 @@ using AgentCore.Domain.Audit; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// What the caller hears is one reply, on every compiled shape. -/// -/// -/// -/// AgentResponse.Text concatenates every message of the response. On a graph row that is -/// every node's reply, so the caller hears the graph deliberating and the audit row records the -/// deliberation as the spoken words. The turn loop takes the last message instead. -/// -/// -/// Every test here runs offline. There is no network conversation and no API key in this file. -/// -/// -public sealed class ConversationSessionGraphReplyTests +namespace AgentCore.Application.Tests.Runtime { - /// What the first node of the graph says while it works. The caller must not hear it. - private const string Thinking = "Let me check the order system."; + /// + /// What the caller hears is one reply, on every compiled shape. + /// + /// + /// + /// AgentResponse.Text concatenates every message of the response. On a graph row that is + /// every node's reply, so the caller hears the graph deliberating and the audit row records the + /// deliberation as the spoken words. The turn loop takes the last message instead. + /// + /// + /// Every test here runs offline. There is no network conversation and no API key in this file. + /// + /// + public sealed class ConversationSessionGraphReplyTests + { + /// What the first node of the graph says while it works. The caller must not hear it. + private const string Thinking = "Let me check the order system."; - /// What the last node of the graph says. This is the whole spoken reply. - private const string Spoken = "Order 41 ships Friday."; + /// What the last node of the graph says. This is the whole spoken reply. + private const string Spoken = "Order 41 ships Friday."; - /// Two nodes, run in order. Both speak, and only the second one is an answer. - private const string GraphYaml = - """ + /// Two nodes, run in order. Both speak, and only the second one is an answer. + private const string GraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -50,9 +50,9 @@ public sealed class ConversationSessionGraphReplyTests agents: [ researcher, responder ] """; - /// One agent with one tool. A tool-calling turn returns three messages, not one. - private const string ToolYaml = - """ + /// One agent with one tool. A tool-calling turn returns three messages, not one. + private const string ToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: lookup_order, kind: builtin, uses: orders.read, description: "Look up an order by its id." } @@ -66,154 +66,155 @@ public sealed class ConversationSessionGraphReplyTests agent: only """; - [Fact] - public async Task CompleteTurn_GraphRow_SpeaksFinalNodeReplyOnly() - { - // Arrange. Each node answers with its own line, so a concatenated reply is visible. - using ScriptedChatClient researcher = new(Thinking); - using ScriptedChatClient responder = new(Spoken); - InMemoryAuditSink sink = new(); - var session = Build(GraphYaml, researcher, responder, sink).Create("conversation-graph"); - - // Act. - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert. The caller hears the answer, and the chain records the answer. - Assert.Equal(Spoken, turn.ReplyText); - Assert.DoesNotContain(Thinking, turn.ReplyText, StringComparison.Ordinal); - - var completed = Assert.Single( - sink.EventsOf("conversation-graph"), - entry => entry.Kind == AuditEventKind.TurnCompleted); - Assert.Equal(AuditHash.OfText(Spoken).Value, completed.Payload[AuditPayloadKeys.ReplyTextSha256]); - } - - [Fact] - public async Task CompleteTurn_ToolCallingTurn_SpeaksFinalAssistantMessage() - { - // Arrange. The model calls the tool once, reads the result, then answers. - using ToolCallingChatClient reply = new(Spoken); - InMemoryAuditSink sink = new(); - var session = Build(ToolYaml, reply, null, sink, new StubToolBuilder("""{ "status": "shipped" }""").Create) - .Create("conversation-tool"); - - // Act. - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert. A tool call and a tool result carry no text, so rows 1 and 2 are unchanged. - Assert.Equal(["lookup_order"], reply.Called); - Assert.Equal(Spoken, turn.ReplyText); - - var completed = Assert.Single( - sink.EventsOf("conversation-tool"), - entry => entry.Kind == AuditEventKind.TurnCompleted); - Assert.Equal(AuditHash.OfText(Spoken).Value, completed.Payload[AuditPayloadKeys.ReplyTextSha256]); - } - - [Fact] - public async Task CompleteTurn_GraphRowWhoseFinalNodeGoesQuiet_SpeaksTheFallback() - { - // Arrange. The node that answers the caller says nothing at all. - using ScriptedChatClient researcher = new(Thinking); - using ScriptedChatClient responder = new(" "); - InMemoryAuditSink sink = new(); - var session = Build(GraphYaml, researcher, responder, sink).Create("conversation-quiet"); - - // Act. - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert. A quiet answer is silence on a voice conversation, so the turn speaks the fallback. It must - // never fall back to the node before it, which is the graph thinking out loud. - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); - Assert.DoesNotContain(Thinking, turn.ReplyText, StringComparison.Ordinal); - - var completed = Assert.Single( - sink.EventsOf("conversation-quiet"), - entry => entry.Kind == AuditEventKind.TurnCompleted); - Assert.Equal( - AuditHash.OfText(ConversationSession.FallbackReply).Value, - completed.Payload[AuditPayloadKeys.ReplyTextSha256]); - } - - [Fact] - public async Task Streaming_GraphRowWhoseFinalNodeGoesQuiet_SpeaksTheFallback() - { - // Arrange. The same graph, on the run shape that hands each piece over as it arrives. - using ScriptedChatClient researcher = new(Thinking); - using ScriptedChatClient responder = new(" "); - var session = Build(GraphYaml, researcher, responder, new InMemoryAuditSink()).Create("conversation-quiet"); - - // Act. - List spoken = []; - await foreach (var update in session.RunTurnStreamingAsync( - "where is my order", TestContext.Current.CancellationToken)) + [Fact] + public async Task CompleteTurn_GraphRow_SpeaksFinalNodeReplyOnly() { - spoken.Add(update.Text); + // Arrange. Each node answers with its own line, so a concatenated reply is visible. + using ScriptedChatClient researcher = new(Thinking); + using ScriptedChatClient responder = new(Spoken); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(GraphYaml, researcher, responder, sink).Create("conversation-graph"); + + // Act. + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert. The caller hears the answer, and the chain records the answer. + Assert.Equal(Spoken, turn.ReplyText); + Assert.DoesNotContain(Thinking, turn.ReplyText, StringComparison.Ordinal); + + AuditEvent completed = Assert.Single( + sink.EventsOf("conversation-graph"), + entry => entry.Kind == AuditEventKind.TurnCompleted); + Assert.Equal(AuditHash.OfText(Spoken).Value, completed.Payload[AuditPayloadKeys.ReplyTextSha256]); } - // Assert. The host hears one fallback and none of the deliberation. The quiet node's own - // whitespace still passes the seam — a space between two words is speech, so the filter - // cannot drop one — and it is inaudible. - Assert.Equal(ConversationSession.FallbackReply, string.Concat(spoken).Trim()); - Assert.DoesNotContain(Thinking, string.Concat(spoken), StringComparison.Ordinal); - Assert.NotNull(session.LastTurn); - Assert.Equal(ConversationSession.EmptyReplyReason, session.LastTurn.Failure); - } - - [Fact] - public async Task Streaming_GraphRow_StreamsEveryFragmentOfTheFinalNodeAndNoneOfTheFirst() - { - // Arrange. The node that answers speaks in pieces, the way a real model streams. - using ScriptedChatClient researcher = new(Thinking); - using ScriptedChatClient responder = new("Order 41 ", "ships Friday."); - var session = Build(GraphYaml, researcher, responder, new InMemoryAuditSink()).Create("conversation-stream"); - - // Act. - List spoken = []; - await foreach (var update in session.RunTurnStreamingAsync( - "where is my order", TestContext.Current.CancellationToken)) + [Fact] + public async Task CompleteTurn_ToolCallingTurn_SpeaksFinalAssistantMessage() { - spoken.Add(update.Text); + // Arrange. The model calls the tool once, reads the result, then answers. + using ToolCallingChatClient reply = new(Spoken); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(ToolYaml, reply, null, sink, new StubToolBuilder(/*lang=json,strict*/ """{ "status": "shipped" }""").Create) + .Create("conversation-tool"); + + // Act. + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert. A tool call and a tool result carry no text, so rows 1 and 2 are unchanged. + Assert.Equal(["lookup_order"], reply.Called); + Assert.Equal(Spoken, turn.ReplyText); + + AuditEvent completed = Assert.Single( + sink.EventsOf("conversation-tool"), + entry => entry.Kind == AuditEventKind.TurnCompleted); + Assert.Equal(AuditHash.OfText(Spoken).Value, completed.Payload[AuditPayloadKeys.ReplyTextSha256]); } - // Assert. Every piece of the answer reaches the host, and none of the deliberation does. - Assert.Equal(Spoken, string.Concat(spoken)); - Assert.NotNull(session.LastTurn); - Assert.Null(session.LastTurn.Failure); - } + [Fact] + public async Task CompleteTurn_GraphRowWhoseFinalNodeGoesQuiet_SpeaksTheFallback() + { + // Arrange. The node that answers the caller says nothing at all. + using ScriptedChatClient researcher = new(Thinking); + using ScriptedChatClient responder = new(" "); + InMemoryAuditSink sink = new(); + ConversationSession session = Build(GraphYaml, researcher, responder, sink).Create("conversation-quiet"); + + // Act. + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert. A quiet answer is silence on a voice conversation, so the turn speaks the fallback. It must + // never fall back to the node before it, which is the graph thinking out loud. + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); + Assert.DoesNotContain(Thinking, turn.ReplyText, StringComparison.Ordinal); + + AuditEvent completed = Assert.Single( + sink.EventsOf("conversation-quiet"), + entry => entry.Kind == AuditEventKind.TurnCompleted); + Assert.Equal( + AuditHash.OfText(ConversationSession.FallbackReply).Value, + completed.Payload[AuditPayloadKeys.ReplyTextSha256]); + } - /// Compiles one configuration over offline models and returns the session factory. - /// The configuration to compile. - /// The model every unrouted agent uses. - /// The model routed to responder, if the graph needs a second one. - /// Where the turn's events land. - /// The tool factory, if the configuration declares a tool. - /// The factory. - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IChatClient? responder, - IAuditSinkPort sink, - Func? tools = null) - { - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(reply); - if (responder is not null) + [Fact] + public async Task Streaming_GraphRowWhoseFinalNodeGoesQuiet_SpeaksTheFallback() { - chatClients.Route("responder", responder); + // Arrange. The same graph, on the run shape that hands each piece over as it arrives. + using ScriptedChatClient researcher = new(Thinking); + using ScriptedChatClient responder = new(" "); + ConversationSession session = Build(GraphYaml, researcher, responder, new InMemoryAuditSink()).Create("conversation-quiet"); + + // Act. + List spoken = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync( + "where is my order", TestContext.Current.CancellationToken)) + { + spoken.Add(update.Text); + } + + // Assert. The host hears one fallback and none of the deliberation. The quiet node's own + // whitespace still passes the seam — a space between two words is speech, so the filter + // cannot drop one — and it is inaudible. + Assert.Equal(ConversationSession.FallbackReply, string.Concat(spoken).Trim()); + Assert.DoesNotContain(Thinking, string.Concat(spoken), StringComparison.Ordinal); + Assert.NotNull(session.LastTurn); + Assert.Equal(ConversationSession.EmptyReplyReason, session.LastTurn.Failure); } - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) + [Fact] + public async Task Streaming_GraphRow_StreamsEveryFragmentOfTheFinalNodeAndNoneOfTheFirst() + { + // Arrange. The node that answers speaks in pieces, the way a real model streams. + using ScriptedChatClient researcher = new(Thinking); + using ScriptedChatClient responder = new("Order 41 ", "ships Friday."); + ConversationSession session = Build(GraphYaml, researcher, responder, new InMemoryAuditSink()).Create("conversation-stream"); + + // Act. + List spoken = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync( + "where is my order", TestContext.Current.CancellationToken)) { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; + spoken.Add(update.Text); + } + + // Assert. Every piece of the answer reaches the host, and none of the deliberation does. + Assert.Equal(Spoken, string.Concat(spoken)); + Assert.NotNull(session.LastTurn); + Assert.Null(session.LastTurn.Failure); + } - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - observers: ConversationObservers.Standard(sink, logger: null)); + /// Compiles one configuration over offline models and returns the session factory. + /// The configuration to compile. + /// The model every unrouted agent uses. + /// The model routed to responder, if the graph needs a second one. + /// Where the turn's events land. + /// The tool factory, if the configuration declares a tool. + /// The factory. + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IChatClient? responder, + IAuditSinkPort sink, + Func? tools = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + if (responder is not null) + { + _ = chatClients.Route("responder", responder); + } + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + observers: ConversationObservers.Standard(sink, logger: null)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionInterruptionTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionInterruptionTests.cs index e1bb7e7f..8ccedb62 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionInterruptionTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionInterruptionTests.cs @@ -1,6 +1,5 @@ using AgentCore.TestSupport; using AgentCore.Application.Audit.Memory; -using AgentCore.Application.Audit; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -14,19 +13,19 @@ using System.Runtime.CompilerServices; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// What the transcript and the reply text hold once a barge-in cuts a turn off. Item 6a of section -/// 11: the record holds the text the caller heard, and a side effect that already ran is not dropped. -/// -/// -/// Every test here runs offline. There is no network conversation and no API key anywhere in this file. -/// -public sealed class ConversationSessionInterruptionTests +namespace AgentCore.Application.Tests.Runtime { - private const string NoToolYaml = - """ + /// + /// What the transcript and the reply text hold once a barge-in cuts a turn off. Item 6a of section + /// 11: the record holds the text the caller heard, and a side effect that already ran is not dropped. + /// + /// + /// Every test here runs offline. There is no network conversation and no API key anywhere in this file. + /// + public sealed class ConversationSessionInterruptionTests + { + private const string NoToolYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -36,8 +35,8 @@ public sealed class ConversationSessionInterruptionTests agent: only """; - private const string ToolYaml = - """ + private const string ToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: price_lookup, kind: builtin, uses: orders.read, description: "Look up the price of an item." } @@ -49,8 +48,8 @@ public sealed class ConversationSessionInterruptionTests agent: only """; - private const string ParallelToolYaml = - """ + private const string ParallelToolYaml = + """ apiVersion: agentcore/v1 tools: - { id: quote, kind: builtin, uses: orders.read, description: "Get a price quote for an item." } @@ -62,8 +61,8 @@ public sealed class ConversationSessionInterruptionTests agent: only """; - private const string ExtractorYaml = - """ + private const string ExtractorYaml = + """ apiVersion: agentcore/v1 state: callerName: @@ -81,1069 +80,1073 @@ public sealed class ConversationSessionInterruptionTests agent: only """; - // ------------------------------------------------------------------------------------------- - // What the transcript holds after the caller cuts the reply off. - // ------------------------------------------------------------------------------------------- + // ------------------------------------------------------------------------------------------- + // What the transcript holds after the caller cuts the reply off. + // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ABargeInBeforeTheFirstWord_AddsNoAssistantMessage() - { - // The relay reports an empty heard text when the caller speaks over the greeting at once. - await using var fixture = InterruptionFixture.Start(reply: "one two three four five"); + [Fact] + public async Task ABargeInBeforeTheFirstWord_AddsNoAssistantMessage() + { + // The relay reports an empty heard text when the caller speaks over the greeting at once. + await using InterruptionFixture fixture = InterruptionFixture.Start(reply: "one two three four five"); - var turn = await fixture.InterruptAfterFirstUpdateAsync(heard: string.Empty); + TurnResult turn = await fixture.InterruptAfterFirstUpdateAsync(heard: string.Empty); - Assert.Equal(string.Empty, turn.ReplyText); - Assert.DoesNotContain(fixture.Session.Transcript, m => m.Role == ChatRole.Assistant); - } + Assert.Equal(string.Empty, turn.ReplyText); + Assert.DoesNotContain(fixture.Session.Transcript, m => m.Role == ChatRole.Assistant); + } - [Fact] - public async Task TheHeardText_IsStoredTrimmed() - { - // The model streams "Hello ", and the caller heard "Hello". A trailing space is not speech. - await using var fixture = InterruptionFixture.Start(reply: "Hello there"); + [Fact] + public async Task TheHeardText_IsStoredTrimmed() + { + // The model streams "Hello ", and the caller heard "Hello". A trailing space is not speech. + await using InterruptionFixture fixture = InterruptionFixture.Start(reply: "Hello there"); - var turn = await fixture.InterruptAfterFirstUpdateAsync(heard: "Hello "); + TurnResult turn = await fixture.InterruptAfterFirstUpdateAsync(heard: "Hello "); - Assert.Equal("Hello", turn.ReplyText); - var last = Assert.Single(fixture.Session.Transcript, m => m.Role == ChatRole.Assistant); - Assert.Equal("Hello", last.Text); - } + Assert.Equal("Hello", turn.ReplyText); + ChatMessage last = Assert.Single(fixture.Session.Transcript, m => m.Role == ChatRole.Assistant); + Assert.Equal("Hello", last.Text); + } - [Fact] - public async Task AToolCallThatFinishedBeforeTheBargeIn_StaysInTheTranscript() - { - // The side effect ran, so the next turn must see it. Only an unpaired call is dropped. - await using var fixture = InterruptionFixture.StartWithFinishedTool(reply: "the price is fifty"); + [Fact] + public async Task AToolCallThatFinishedBeforeTheBargeIn_StaysInTheTranscript() + { + // The side effect ran, so the next turn must see it. Only an unpaired call is dropped. + await using InterruptionFixture fixture = InterruptionFixture.StartWithFinishedTool(reply: "the price is fifty"); - await fixture.InterruptAfterFirstUpdateAsync(heard: "the price"); + _ = await fixture.InterruptAfterFirstUpdateAsync(heard: "the price"); - Assert.Contains( - fixture.Session.Transcript, - m => m.Contents.OfType().Any()); - Assert.Contains( - fixture.Session.Transcript, - m => m.Contents.OfType().Any()); - } + Assert.Contains( + fixture.Session.Transcript, + m => m.Contents.OfType().Any()); + Assert.Contains( + fixture.Session.Transcript, + m => m.Contents.OfType().Any()); + } - [Fact] - public async Task AParallelToolRound_KeepsTheConversationThatFinishedAndDropsTheOneThatDidNot() - { - // A parallel round can pair one call and leave a sibling call, in the same message, mid- - // flight. The rule is per conversation id, so only the unfinished conversation is dropped. - using ParallelToolCallChatClient reply = new(); - PartiallyAnsweredToolFactory tools = new(); - var session = CreateSession(ParallelToolYaml, reply, tools.Create); - - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); - - // Only the streaming entry point is ever cut in flight — a turn that never streams is never - // audible, so a barge-in cannot cancel it mid-round. The streaming shape is also the one a - // relay actually drives. - var pump = Task.Run( - async () => - { - await foreach (var _ in session.RunTurnStreamingAsync("price both items", linked.Token) - .ConfigureAwait(false)) + [Fact] + public async Task AParallelToolRound_KeepsTheConversationThatFinishedAndDropsTheOneThatDidNot() + { + // A parallel round can pair one call and leave a sibling call, in the same message, mid- + // flight. The rule is per conversation id, so only the unfinished conversation is dropped. + using ParallelToolCallChatClient reply = new(); + PartiallyAnsweredToolFactory tools = new(); + ConversationSession session = CreateSession(ParallelToolYaml, reply, tools.Create); + + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); + + // Only the streaming entry point is ever cut in flight — a turn that never streams is never + // audible, so a barge-in cannot cancel it mid-round. The streaming shape is also the one a + // relay actually drives. + Task pump = Task.Run( + async () => { - // Neither fact of this test reads an update; it reads the finished transcript. - } - }, - CancellationToken.None); - - // The first call already answered by the time the second call is blocked in flight. - await tools.SecondConversationStarted.Task.WaitAsync(linked.Token); - Assert.True(session.Interrupt("the first one is", TimeSpan.FromMilliseconds(1820))); - - await pump; - - Assert.DoesNotContain( - session.Transcript, - m => m.Contents.OfType().Any(call => call.CallId == ParallelToolCallChatClient.SecondCallId)); - - // Round one's own message, holding only the finished call, survives either way and is not - // what pins the defect. What pins it is round two's message: a per-message rule drops it - // whole because it also carries the unfinished call, so the finished call only ever shows up - // once (from round one). The per-call-id rule instead trims round two down to the finished - // call and keeps it, so the finished call shows up twice. - var callAMessages = session.Transcript - .Where(m => m.Contents.OfType().Any(call => call.CallId == ParallelToolCallChatClient.FirstCallId)) - .ToList(); - Assert.Equal(2, callAMessages.Count); - - var trimmedRoundTwo = callAMessages[^1]; - Assert.Equal( - ParallelToolCallChatClient.FirstCallId, - Assert.Single(trimmedRoundTwo.Contents.OfType()).CallId); - } - - [Fact(Timeout = 30_000)] - public async Task ProseBesideAFinishedToolCall_LeavesTheTranscriptOnTheHeardTextAlone() - { - // A real model routinely puts a line of prose and the tool call it announces in one - // assistant message. The heard text replaces the prose, so keeping both would put the - // reply into the transcript twice — once as the words the model produced and once as the - // words the caller actually heard. Item 6a: the record holds what the caller heard. - await using var fixture = InterruptionFixture.StartWithProseBesideTool(reply: "the price is fifty"); - - await fixture.InterruptAfterFirstUpdateAsync(heard: "the price"); - - // The side effect ran, so the pair stays. That is the rule this fact must not break. - Assert.Contains(fixture.Session.Transcript, m => m.Contents.OfType().Any()); - Assert.Contains(fixture.Session.Transcript, m => m.Contents.OfType().Any()); - - Assert.DoesNotContain( - fixture.Session.Transcript.SelectMany(m => m.Contents).OfType(), - text => text.Text.Contains(ProseBesideToolChatClient.Prose, StringComparison.Ordinal)); - - var heard = Assert.Single( - fixture.Session.Transcript, - m => m.Role == ChatRole.Assistant && m.Contents.All(content => content is TextContent)); - Assert.Equal("the price", heard.Text); - } - - // ------------------------------------------------------------------------------------------- - // A barge-in that arrives after the turn task already ended. Telnyx paces the audio, so the - // model finishes streaming long before the vendor finishes speaking, and this is the common - // shape on a real conversation rather than an edge case. - // ------------------------------------------------------------------------------------------- + await foreach (ChatResponseUpdate? _ in session.RunTurnStreamingAsync("price both items", linked.Token) + .ConfigureAwait(false)) + { + // Neither fact of this test reads an update; it reads the finished transcript. + } + }, + CancellationToken.None); + + // The first call already answered by the time the second call is blocked in flight. + await tools.SecondConversationStarted.Task.WaitAsync(linked.Token); + Assert.True(session.Interrupt("the first one is", TimeSpan.FromMilliseconds(1820))); + + await pump; + + Assert.DoesNotContain( + session.Transcript, + m => m.Contents.OfType().Any(call => call.CallId == ParallelToolCallChatClient.SecondCallId)); + + // Round one's own message, holding only the finished call, survives either way and is not + // what pins the defect. What pins it is round two's message: a per-message rule drops it + // whole because it also carries the unfinished call, so the finished call only ever shows up + // once (from round one). The per-call-id rule instead trims round two down to the finished + // call and keeps it, so the finished call shows up twice. + List callAMessages = [.. session.Transcript.Where(m => m.Contents.OfType().Any(call => call.CallId == ParallelToolCallChatClient.FirstCallId))]; + Assert.Equal(2, callAMessages.Count); + + ChatMessage trimmedRoundTwo = callAMessages[^1]; + Assert.Equal( + ParallelToolCallChatClient.FirstCallId, + Assert.Single(trimmedRoundTwo.Contents.OfType()).CallId); + } - [Fact(Timeout = 30_000)] - public async Task AnInterruptAfterTheTurnEnded_AmendsTheFinishedTurn() - { - // No gate and no blocking client: the whole point is that the turn is already over when - // the frame lands. D28 and item 6a still hold — both vendor values pass through unchanged. - using ScriptedChatClient reply = new("Hello", " there", " caller"); - InMemoryAuditSink sink = new(); - var session = CreateSession(NoToolYaml, reply, auditSink: sink); - - await foreach (var _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken) - .ConfigureAwait(false)) + [Fact(Timeout = 30_000)] + public async Task ProseBesideAFinishedToolCall_LeavesTheTranscriptOnTheHeardTextAlone() { - // The turn runs to its end. Nothing here interrupts it. + // A real model routinely puts a line of prose and the tool call it announces in one + // assistant message. The heard text replaces the prose, so keeping both would put the + // reply into the transcript twice — once as the words the model produced and once as the + // words the caller actually heard. Item 6a: the record holds what the caller heard. + await using InterruptionFixture fixture = InterruptionFixture.StartWithProseBesideTool(reply: "the price is fifty"); + + _ = await fixture.InterruptAfterFirstUpdateAsync(heard: "the price"); + + // The side effect ran, so the pair stays. That is the rule this fact must not break. + Assert.Contains(fixture.Session.Transcript, m => m.Contents.OfType().Any()); + Assert.Contains(fixture.Session.Transcript, m => m.Contents.OfType().Any()); + + Assert.DoesNotContain( + fixture.Session.Transcript.SelectMany(m => m.Contents).OfType(), + text => text.Text.Contains(ProseBesideToolChatClient.Prose, StringComparison.Ordinal)); + + ChatMessage heard = Assert.Single( + fixture.Session.Transcript, + m => m.Role == ChatRole.Assistant && m.Contents.All(content => content is TextContent)); + Assert.Equal("the price", heard.Text); } - Assert.NotNull(session.LastTurn); - Assert.Null(session.LastTurn!.InterruptedAfter); + // ------------------------------------------------------------------------------------------- + // A barge-in that arrives after the turn task already ended. Telnyx paces the audio, so the + // model finishes streaming long before the vendor finishes speaking, and this is the common + // shape on a real conversation rather than an edge case. + // ------------------------------------------------------------------------------------------- - Assert.True(session.Interrupt("Hello there", TimeSpan.FromMilliseconds(1820))); + [Fact(Timeout = 30_000)] + public async Task AnInterruptAfterTheTurnEnded_AmendsTheFinishedTurn() + { + // No gate and no blocking client: the whole point is that the turn is already over when + // the frame lands. D28 and item 6a still hold — both vendor values pass through unchanged. + using ScriptedChatClient reply = new("Hello", " there", " caller"); + InMemoryAuditSink sink = new(); + ConversationSession session = CreateSession(NoToolYaml, reply, auditSink: sink); - Assert.Equal("Hello there", session.LastTurn!.ReplyText); - Assert.Equal(TimeSpan.FromMilliseconds(1820), session.LastTurn.InterruptedAfter); + await foreach (ChatResponseUpdate? _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken) + .ConfigureAwait(false)) + { + // The turn runs to its end. Nothing here interrupts it. + } - // The transcript holds what the caller heard, not what the model produced. - var assistant = Assert.Single(session.Transcript, m => m.Role == ChatRole.Assistant); - Assert.Equal("Hello there", assistant.Text); + Assert.NotNull(session.LastTurn); + Assert.Null(session.LastTurn!.InterruptedAfter); - // T23: the chain is append-only, so the correction is a second event that names the first. - var events = sink.EventsOf(session.ConversationId); - var completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); - var amendment = Assert.Single(events, item => item.Kind == AuditEventKind.ReplyInterrupted); - Assert.Equal(completed.EventId, amendment.AmendsEventId); - Assert.Equal(completed.TurnIndex, amendment.TurnIndex); - Assert.Equal( - AuditHash.OfText("Hello there").Value, - amendment.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); - Assert.Equal("1820", amendment.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); + Assert.True(session.Interrupt("Hello there", TimeSpan.FromMilliseconds(1820))); - // One barge-in cuts one reply once. A repeat frame amends nothing a second time. - Assert.False(session.Interrupt("Hello there caller", TimeSpan.FromMilliseconds(2400))); - Assert.Single(sink.EventsOf(session.ConversationId), item => item.Kind == AuditEventKind.ReplyInterrupted); - } + Assert.Equal("Hello there", session.LastTurn!.ReplyText); + Assert.Equal(TimeSpan.FromMilliseconds(1820), session.LastTurn.InterruptedAfter); + + // The transcript holds what the caller heard, not what the model produced. + ChatMessage assistant = Assert.Single(session.Transcript, m => m.Role == ChatRole.Assistant); + Assert.Equal("Hello there", assistant.Text); + + // T23: the chain is append-only, so the correction is a second event that names the first. + IReadOnlyList events = sink.EventsOf(session.ConversationId); + AuditEvent completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); + AuditEvent amendment = Assert.Single(events, item => item.Kind == AuditEventKind.ReplyInterrupted); + Assert.Equal(completed.EventId, amendment.AmendsEventId); + Assert.Equal(completed.TurnIndex, amendment.TurnIndex); + Assert.Equal( + AuditHash.OfText("Hello there").Value, + amendment.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); + Assert.Equal("1820", amendment.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); + + // One barge-in cuts one reply once. A repeat frame amends nothing a second time. + Assert.False(session.Interrupt("Hello there caller", TimeSpan.FromMilliseconds(2400))); + _ = Assert.Single(sink.EventsOf(session.ConversationId), item => item.Kind == AuditEventKind.ReplyInterrupted); + } - [Fact(Timeout = 30_000)] - public void AnInterruptBeforeAnyTurnEverRan_ChangesNothingAndThrowsNothing() - { - using ScriptedChatClient reply = new("hello"); - InMemoryAuditSink sink = new(); - var session = CreateSession(NoToolYaml, reply, auditSink: sink); + [Fact(Timeout = 30_000)] + public void AnInterruptBeforeAnyTurnEverRan_ChangesNothingAndThrowsNothing() + { + using ScriptedChatClient reply = new("hello"); + InMemoryAuditSink sink = new(); + ConversationSession session = CreateSession(NoToolYaml, reply, auditSink: sink); - Assert.False(session.Interrupt("nothing played", TimeSpan.FromMilliseconds(10))); + Assert.False(session.Interrupt("nothing played", TimeSpan.FromMilliseconds(10))); - Assert.Null(session.LastTurn); - Assert.Empty(session.Transcript); - Assert.DoesNotContain( - sink.EventsOf(session.ConversationId), - item => item.Kind == AuditEventKind.ReplyInterrupted); - } + Assert.Null(session.LastTurn); + Assert.Empty(session.Transcript); + Assert.DoesNotContain( + sink.EventsOf(session.ConversationId), + item => item.Kind == AuditEventKind.ReplyInterrupted); + } - [Fact(Timeout = 30_000)] - public async Task AnInterruptWhileAnUnheardSecondTurnRuns_AmendsTheFirstTurnAndLetsTheSecondSpeak() - { - // The held prompt of item 6a starts turn two inside turn one's own finally, while the - // vendor is still speaking turn one. The barge-in belongs to the turn the caller was - // hearing, so turn two must not be cut off before it has said a word. - using SecondTurnGatedChatClient reply = new("first reply", "second reply"); - InMemoryAuditSink sink = new(); - var session = CreateSession(NoToolYaml, reply, auditSink: sink); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await foreach (var _ in session.RunTurnStreamingAsync("one", bounded.Token).ConfigureAwait(false)) + [Fact(Timeout = 30_000)] + public async Task AnInterruptWhileAnUnheardSecondTurnRuns_AmendsTheFirstTurnAndLetsTheSecondSpeak() { - // Turn one runs to its end, exactly as it does on a real conversation. - } + // The held prompt of item 6a starts turn two inside turn one's own finally, while the + // vendor is still speaking turn one. The barge-in belongs to the turn the caller was + // hearing, so turn two must not be cut off before it has said a word. + using SecondTurnGatedChatClient reply = new("first reply", "second reply"); + InMemoryAuditSink sink = new(); + ConversationSession session = CreateSession(NoToolYaml, reply, auditSink: sink); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + await foreach (ChatResponseUpdate? _ in session.RunTurnStreamingAsync("one", bounded.Token).ConfigureAwait(false)) + { + // Turn one runs to its end, exactly as it does on a real conversation. + } - var first = session.LastTurn; - Assert.NotNull(first); + TurnResult? first = session.LastTurn; + Assert.NotNull(first); - List spoken = []; - var second = Task.Run( - async () => + List spoken = []; + Task second = Task.Run( + async () => + { + await foreach (ChatResponseUpdate? update in session.RunTurnStreamingAsync("two", bounded.Token) + .ConfigureAwait(false)) + { + spoken.Add(update.Text); + } + }, + CancellationToken.None); + + try { - await foreach (var update in session.RunTurnStreamingAsync("two", bounded.Token) - .ConfigureAwait(false)) + try + { + await reply.SecondTurnStarted.Task.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - spoken.Add(update.Text); + Assert.Fail("the second turn never started within ten seconds."); } - }, - CancellationToken.None); - try - { + Assert.True(session.Interrupt("first", TimeSpan.FromMilliseconds(1820))); + } + finally + { + // The gate ignores cancellation, so a failed assertion above must still release it. + reply.OpenGate(); + } + try { - await reply.SecondTurnStarted.Task.WaitAsync(bounded.Token); + await second.WaitAsync(bounded.Token); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the second turn never started within ten seconds."); + Assert.Fail("the second turn never finished within ten seconds."); } - Assert.True(session.Interrupt("first", TimeSpan.FromMilliseconds(1820))); - } - finally - { - // The gate ignores cancellation, so a failed assertion above must still release it. - reply.OpenGate(); + // The second turn spoke every word it had. Nothing silenced it. + Assert.Equal("second reply", string.Concat(spoken)); + Assert.Null(session.LastTurn!.InterruptedAfter); + + AuditEvent amendment = Assert.Single( + sink.EventsOf(session.ConversationId), + item => item.Kind == AuditEventKind.ReplyInterrupted); + Assert.Equal(first!.TurnIndex, amendment.TurnIndex); + Assert.Equal( + AuditHash.OfText("first").Value, + amendment.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); } - try - { - await second.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + // ------------------------------------------------------------------------------------------- + // A barge-in that lands while the turn is still finishing itself. The reply is over, the writers + // are running, and the extractor can hold the turn for up to TurnCompletionTimeout — five whole + // seconds in which the run still looks live to Interrupt. + // ------------------------------------------------------------------------------------------- + + [Fact(Timeout = 30_000)] + public async Task AnInterruptWhileTheExtractorRuns_IsRecordedAndNotOnlyReported() { - Assert.Fail("the second turn never finished within ten seconds."); - } + // CompleteTurnAsync reads the interruption once, before it awaits the extractor. EndRun runs + // later still, in the finally of whichever method opened the turn, so a frame that lands + // inside that await finds a live run and — on a streaming turn, audible since its first + // yielded fragment — takes the in-flight path, sets the record, and answers true. And true, + // on Interrupt's own contract, means "this conversation recorded the barge-in". The commit lock + // reads the field a second time for exactly this frame. Without that read the turn commits + // as an ordinary completed turn: InterruptedAfter stays null, the transcript keeps the whole + // reply the model produced rather than the words the caller heard, and the chain carries no + // reply.interrupted event at all. Only the streaming shape reaches this window: a turn that + // never streams is never audible, and its frame amends the turn before it instead. + using ScriptedChatClient reply = new("Hello", " there", " caller"); + using GatedExtractorChatClient extractor = new(); + RoutingChatClientFactory chatClients = new RoutingChatClientFactory(reply).Route("fill", extractor); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ExtractorYaml), new AgentCompilationContext(chatClients))["main"]; + InMemoryAuditSink sink = new(); + ConversationSession session = new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + observers: ConversationObservers.Standard(sink, logger: null)).Create(); - // The second turn spoke every word it had. Nothing silenced it. - Assert.Equal("second reply", string.Concat(spoken)); - Assert.Null(session.LastTurn!.InterruptedAfter); - - var amendment = Assert.Single( - sink.EventsOf(session.ConversationId), - item => item.Kind == AuditEventKind.ReplyInterrupted); - Assert.Equal(first!.TurnIndex, amendment.TurnIndex); - Assert.Equal( - AuditHash.OfText("first").Value, - amendment.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); - } + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // A barge-in that lands while the turn is still finishing itself. The reply is over, the writers - // are running, and the extractor can hold the turn for up to TurnCompletionTimeout — five whole - // seconds in which the run still looks live to Interrupt. - // ------------------------------------------------------------------------------------------- + Task running = Task.Run( + async () => + { + await foreach (ChatResponseUpdate? _ in session.RunTurnStreamingAsync("hi", bounded.Token) + .ConfigureAwait(false)) + { + // The reply is consumed whole; the frame lands later, inside the extractor. + } + }, + CancellationToken.None); - [Fact(Timeout = 30_000)] - public async Task AnInterruptWhileTheExtractorRuns_IsRecordedAndNotOnlyReported() - { - // CompleteTurnAsync reads the interruption once, before it awaits the extractor. EndRun runs - // later still, in the finally of whichever method opened the turn, so a frame that lands - // inside that await finds a live run and — on a streaming turn, audible since its first - // yielded fragment — takes the in-flight path, sets the record, and answers true. And true, - // on Interrupt's own contract, means "this conversation recorded the barge-in". The commit lock - // reads the field a second time for exactly this frame. Without that read the turn commits - // as an ordinary completed turn: InterruptedAfter stays null, the transcript keeps the whole - // reply the model produced rather than the words the caller heard, and the chain carries no - // reply.interrupted event at all. Only the streaming shape reaches this window: a turn that - // never streams is never audible, and its frame amends the turn before it instead. - using ScriptedChatClient reply = new("Hello", " there", " caller"); - using GatedExtractorChatClient extractor = new(); - var chatClients = new RoutingChatClientFactory(reply).Route("fill", extractor); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ExtractorYaml), new AgentCompilationContext(chatClients))["main"]; - InMemoryAuditSink sink = new(); - var session = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - observers: ConversationObservers.Standard(sink, logger: null)).Create(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - var running = Task.Run( - async () => + try { - await foreach (var _ in session.RunTurnStreamingAsync("hi", bounded.Token) - .ConfigureAwait(false)) + try + { + await extractor.Started.Task.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - // The reply is consumed whole; the frame lands later, inside the extractor. + Assert.Fail("the extractor never started within ten seconds."); } - }, - CancellationToken.None); - try - { - try - { - await extractor.Started.Task.WaitAsync(bounded.Token); + // The reply is complete and the turn is inside the extractor await. Interrupt says it + // recorded this, so the rest of this test holds it to that answer. + Assert.True(session.Interrupt("Hello there", TimeSpan.FromMilliseconds(1820))); } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + finally { - Assert.Fail("the extractor never started within ten seconds."); + // The gate ignores cancellation, so a failed assertion above must still release it + // rather than leave the turn parked until TurnCompletionTimeout expires. + extractor.OpenGate(); } - // The reply is complete and the turn is inside the extractor await. Interrupt says it - // recorded this, so the rest of this test holds it to that answer. - Assert.True(session.Interrupt("Hello there", TimeSpan.FromMilliseconds(1820))); - } - finally - { - // The gate ignores cancellation, so a failed assertion above must still release it - // rather than leave the turn parked until TurnCompletionTimeout expires. - extractor.OpenGate(); + await running.WaitAsync(bounded.Token); + TurnResult? turn = session.LastTurn; + + // D28: both values are the ones the relay reported, unchanged. + Assert.NotNull(turn); + Assert.Equal(TimeSpan.FromMilliseconds(1820), turn.InterruptedAfter); + Assert.Equal("Hello there", turn.ReplyText); + + // The transcript holds what the caller heard, and never the tail the model produced. + ChatMessage assistant = Assert.Single(session.Transcript, message => message.Role == ChatRole.Assistant); + Assert.Equal("Hello there", assistant.Text); + + // T23: the correction is a second event that names the first, and never an edit of it. + IReadOnlyList events = sink.EventsOf(session.ConversationId); + AuditEvent completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); + AuditEvent amendment = Assert.Single(events, item => item.Kind == AuditEventKind.ReplyInterrupted); + Assert.Equal(completed.EventId, amendment.AmendsEventId); + Assert.Equal(completed.TurnIndex, amendment.TurnIndex); + Assert.Equal( + AuditHash.OfText("Hello there").Value, + amendment.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); + Assert.Equal("1820", amendment.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); + + // One barge-in cuts one reply once. The turn is no longer amendable, so a repeat says so. + Assert.False(session.Interrupt("Hello there caller", TimeSpan.FromMilliseconds(2400))); + _ = Assert.Single(sink.EventsOf(session.ConversationId), item => item.Kind == AuditEventKind.ReplyInterrupted); } - await running.WaitAsync(bounded.Token); - var turn = session.LastTurn; - - // D28: both values are the ones the relay reported, unchanged. - Assert.NotNull(turn); - Assert.Equal(TimeSpan.FromMilliseconds(1820), turn.InterruptedAfter); - Assert.Equal("Hello there", turn.ReplyText); - - // The transcript holds what the caller heard, and never the tail the model produced. - var assistant = Assert.Single(session.Transcript, message => message.Role == ChatRole.Assistant); - Assert.Equal("Hello there", assistant.Text); - - // T23: the correction is a second event that names the first, and never an edit of it. - var events = sink.EventsOf(session.ConversationId); - var completed = Assert.Single(events, item => item.Kind == AuditEventKind.TurnCompleted); - var amendment = Assert.Single(events, item => item.Kind == AuditEventKind.ReplyInterrupted); - Assert.Equal(completed.EventId, amendment.AmendsEventId); - Assert.Equal(completed.TurnIndex, amendment.TurnIndex); - Assert.Equal( - AuditHash.OfText("Hello there").Value, - amendment.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]); - Assert.Equal("1820", amendment.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); - - // One barge-in cuts one reply once. The turn is no longer amendable, so a repeat says so. - Assert.False(session.Interrupt("Hello there caller", TimeSpan.FromMilliseconds(2400))); - Assert.Single(sink.EventsOf(session.ConversationId), item => item.Kind == AuditEventKind.ReplyInterrupted); - } - - // ------------------------------------------------------------------------------------------- - // The deadline that bounds the work after the reply. - // ------------------------------------------------------------------------------------------- - - [Fact] - public async Task AnExtractorThatNeverReturns_DoesNotHoldTheConversationOpenForever() - { - // The extractor runs on the host token on purpose, so a barge-in never cancels it. Nothing - // else bounds it, and a hung extractor would hold the conversation. livekit carries a five-second - // watchdog for the same reason. - await using var fixture = InterruptionFixture.StartWithHangingExtractor(reply: "hello"); - - var turn = await fixture.RunTurnAsync("hi").WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken); - - Assert.NotNull(turn); - Assert.Equal(ConversationSession.ExtractionTimedOutReason, fixture.LastExtractionFailure); - } - - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - - private static ConversationSession CreateSession( - string yaml, - IChatClient reply, - Func? tools = null, - IAuditSinkPort? auditSink = null) - { - // There is always a sink now: ConversationObservers.Standard takes a required one, because the - // composition root resolves providers.audit for every host and falls back to the in-process - // memory kind. An optional parameter has to be a compile-time constant, so the default is - // spelled here instead — a fact that does not care where its events land gets a fresh - // in-memory sink and reads exactly as it did when it passed nothing. - IAuditSinkPort sink = auditSink ?? new InMemoryAuditSink(); - - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new FakeChatClientFactory(reply); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; + // ------------------------------------------------------------------------------------------- + // The deadline that bounds the work after the reply. + // ------------------------------------------------------------------------------------------- - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - observers: ConversationObservers.Standard(sink, logger: null)); - - return factory.Create(); - } - - /// - /// Drives one streaming turn on a background task, far enough to interrupt it. - /// - /// - /// Every fact of this file wants the same shape: a model that streams its first piece of content, - /// then holds until the test releases it. This fixture builds that turn once, over - /// and , so each fact - /// reads as one line of setup and one assertion of what the interruption left behind. - /// - private sealed class InterruptionFixture : IAsyncDisposable - { - private readonly CancellationTokenSource _cancellation; - private readonly IReadOnlyList _disposables; - private readonly Action _openGate; - private readonly TaskCompletionSource _firstUpdate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly Task _run; - - private InterruptionFixture(ConversationSession session, IChatClient reply, Action openGate, CancellationToken hostToken) + [Fact] + public async Task AnExtractorThatNeverReturns_DoesNotHoldTheConversationOpenForever() { - Session = session; - _disposables = [reply]; - _openGate = openGate; - _cancellation = CancellationTokenSource.CreateLinkedTokenSource(hostToken); - _cancellation.CancelAfter(TimeSpan.FromSeconds(30)); - // The run reads its own token, _cancellation.Token, from inside PumpAsync, so the token - // Task.Run offers here is deliberately unused. - _run = Task.Run(PumpAsync, CancellationToken.None); - } + // The extractor runs on the host token on purpose, so a barge-in never cancels it. Nothing + // else bounds it, and a hung extractor would hold the conversation. livekit carries a five-second + // watchdog for the same reason. + await using InterruptionFixture fixture = InterruptionFixture.StartWithHangingExtractor(reply: "hello"); - /// Builds a fixture over a turn that runs directly, with no streaming pump behind it. - private InterruptionFixture(ConversationSession session, IReadOnlyList disposables, CancellationToken hostToken) - { - Session = session; - _disposables = disposables; - _openGate = static () => { }; - _cancellation = CancellationTokenSource.CreateLinkedTokenSource(hostToken); - _cancellation.CancelAfter(TimeSpan.FromSeconds(30)); - // RunTurnAsync drives the turn itself, on the caller's own conversation. There is no round to - // stream and gate, so there is nothing here for a background pump to do. - _run = Task.CompletedTask; + TurnResult turn = await fixture.RunTurnAsync("hi").WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken); + + Assert.NotNull(turn); + Assert.Equal(ConversationSession.ExtractionTimedOutReason, fixture.LastExtractionFailure); } - /// Gets the session the turn runs on. - public ConversationSession Session { get; } + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- - /// Starts a turn over a plain text reply, gated after its first fragment. - public static InterruptionFixture Start(string reply) + private static ConversationSession CreateSession( + string yaml, + IChatClient reply, + Func? tools = null, + IAuditSinkPort? auditSink = null) { - ScriptedChatClient client = new(reply.Split(' ')) { GateAfterFirstFragment = true }; - var session = CreateSession(NoToolYaml, client); - return new InterruptionFixture(session, client, client.OpenGate, TestContext.Current.CancellationToken); - } + // There is always a sink now: ConversationObservers.Standard takes a required one, because the + // composition root resolves providers.audit for every host and falls back to the in-process + // memory kind. An optional parameter has to be a compile-time constant, so the default is + // spelled here instead — a fact that does not care where its events land gets a fresh + // in-memory sink and reads exactly as it did when it passed nothing. + IAuditSinkPort sink = auditSink ?? new InMemoryAuditSink(); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + FakeChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; - /// Starts a turn whose tool call and result finish before the reply that follows them. - public static InterruptionFixture StartWithFinishedTool(string reply) - { - GatedToolThenReplyChatClient client = new(reply); - var session = CreateSession(ToolYaml, client, new StubToolBuilder("""{ "price": 50 }""").Create); - return new InterruptionFixture(session, client, client.OpenGate, TestContext.Current.CancellationToken); - } + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + observers: ConversationObservers.Standard(sink, logger: null)); - /// Starts a turn whose tool round also carries the prose the model spoke before the call. - public static InterruptionFixture StartWithProseBesideTool(string reply) - { - ProseBesideToolChatClient client = new(reply); - var session = CreateSession(ToolYaml, client, new StubToolBuilder("""{ "price": 50 }""").Create); - return new InterruptionFixture(session, client, client.OpenGate, TestContext.Current.CancellationToken); + return factory.Create(); } - /// Builds a session whose extractor model never answers, so the deadline of §8.7 must act. + /// + /// Drives one streaming turn on a background task, far enough to interrupt it. + /// /// - /// The extractor runs on fill, the route gives a - /// test to script apart from the reply model. answers that - /// route, and it awaits a nobody ever sets, so nothing but - /// ends the conversation. + /// Every fact of this file wants the same shape: a model that streams its first piece of content, + /// then holds until the test releases it. This fixture builds that turn once, over + /// and , so each fact + /// reads as one line of setup and one assertion of what the interruption left behind. /// - public static InterruptionFixture StartWithHangingExtractor(string reply) + private sealed class InterruptionFixture : IAsyncDisposable { - ScriptedChatClient replyClient = new(reply.Split(' ')); - HangingChatClient extractorClient = new(); - var chatClients = new RoutingChatClientFactory(replyClient).Route("fill", extractorClient); - - var document = ConfigurationLoader.LoadYaml(ExtractorYaml); - var compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(chatClients))["main"]; - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients)); + private readonly CancellationTokenSource _cancellation; + private readonly IReadOnlyList _disposables; + private readonly Action _openGate; + private readonly TaskCompletionSource _firstUpdate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly Task _run; - return new InterruptionFixture( - factory.Create(), - [replyClient, extractorClient], - TestContext.Current.CancellationToken); - } + private InterruptionFixture(ConversationSession session, IChatClient reply, Action openGate, CancellationToken hostToken) + { + Session = session; + _disposables = [reply]; + _openGate = openGate; + _cancellation = CancellationTokenSource.CreateLinkedTokenSource(hostToken); + _cancellation.CancelAfter(TimeSpan.FromSeconds(30)); + // The run reads its own token, _cancellation.Token, from inside PumpAsync, so the token + // Task.Run offers here is deliberately unused. + _run = Task.Run(PumpAsync, CancellationToken.None); + } - /// Runs one turn directly on the session, the way a host that never streams drives it. - public Task RunTurnAsync(string userInput) => Session.RunTurnAsync(userInput, _cancellation.Token); + /// Builds a fixture over a turn that runs directly, with no streaming pump behind it. + private InterruptionFixture(ConversationSession session, IReadOnlyList disposables, CancellationToken hostToken) + { + Session = session; + _disposables = disposables; + _openGate = static () => { }; + _cancellation = CancellationTokenSource.CreateLinkedTokenSource(hostToken); + _cancellation.CancelAfter(TimeSpan.FromSeconds(30)); + // RunTurnAsync drives the turn itself, on the caller's own conversation. There is no round to + // stream and gate, so there is nothing here for a background pump to do. + _run = Task.CompletedTask; + } - /// Gets the extraction failure the last finished turn recorded, or . - public string? LastExtractionFailure => Session.LastTurn?.ExtractionFailure; + /// Gets the session the turn runs on. + public ConversationSession Session { get; } - /// Waits for the first update, interrupts with what the caller heard, and returns the finished turn. - public async Task InterruptAfterFirstUpdateAsync(string heard) - { - await _firstUpdate.Task.WaitAsync(_cancellation.Token).ConfigureAwait(false); + /// Starts a turn over a plain text reply, gated after its first fragment. + public static InterruptionFixture Start(string reply) + { + ScriptedChatClient client = new(reply.Split(' ')) { GateAfterFirstFragment = true }; + ConversationSession session = CreateSession(NoToolYaml, client); + return new InterruptionFixture(session, client, client.OpenGate, TestContext.Current.CancellationToken); + } - // Section 7.1: the relay reports both the heard text and the played duration together. - Session.Interrupt(heard, TimeSpan.FromMilliseconds(1820)); - _openGate(); + /// Starts a turn whose tool call and result finish before the reply that follows them. + public static InterruptionFixture StartWithFinishedTool(string reply) + { + GatedToolThenReplyChatClient client = new(reply); + ConversationSession session = CreateSession(ToolYaml, client, new StubToolBuilder(/*lang=json,strict*/ """{ "price": 50 }""").Create); + return new InterruptionFixture(session, client, client.OpenGate, TestContext.Current.CancellationToken); + } - await _run.WaitAsync(_cancellation.Token).ConfigureAwait(false); - Assert.NotNull(Session.LastTurn); - return Session.LastTurn; - } + /// Starts a turn whose tool round also carries the prose the model spoke before the call. + public static InterruptionFixture StartWithProseBesideTool(string reply) + { + ProseBesideToolChatClient client = new(reply); + ConversationSession session = CreateSession(ToolYaml, client, new StubToolBuilder(/*lang=json,strict*/ """{ "price": 50 }""").Create); + return new InterruptionFixture(session, client, client.OpenGate, TestContext.Current.CancellationToken); + } - public async ValueTask DisposeAsync() - { - // A fact that stops before it interrupts must not leave the background task hanging. - _openGate(); - _firstUpdate.TrySetResult(); + /// Builds a session whose extractor model never answers, so the deadline of §8.7 must act. + /// + /// The extractor runs on fill, the route gives a + /// test to script apart from the reply model. answers that + /// route, and it awaits a nobody ever sets, so nothing but + /// ends the conversation. + /// + public static InterruptionFixture StartWithHangingExtractor(string reply) + { + ScriptedChatClient replyClient = new(reply.Split(' ')); + HangingChatClient extractorClient = new(); + RoutingChatClientFactory chatClients = new RoutingChatClientFactory(replyClient).Route("fill", extractorClient); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExtractorYaml); + CompiledAgent compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(chatClients))["main"]; + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients)); + + return new InterruptionFixture( + factory.Create(), + [replyClient, extractorClient], + TestContext.Current.CancellationToken); + } - try + /// Runs one turn directly on the session, the way a host that never streams drives it. + public Task RunTurnAsync(string userInput) { - await _run.ConfigureAwait(false); + return Session.RunTurnAsync(userInput, _cancellation.Token); } - catch (OperationCanceledException) + + /// Gets the extraction failure the last finished turn recorded, or . + public string? LastExtractionFailure => Session.LastTurn?.ExtractionFailure; + + /// Waits for the first update, interrupts with what the caller heard, and returns the finished turn. + public async Task InterruptAfterFirstUpdateAsync(string heard) { - // The host token already ended the run. Nothing here is left to observe. + await _firstUpdate.Task.WaitAsync(_cancellation.Token).ConfigureAwait(false); + + // Section 7.1: the relay reports both the heard text and the played duration together. + _ = Session.Interrupt(heard, TimeSpan.FromMilliseconds(1820)); + _openGate(); + + await _run.WaitAsync(_cancellation.Token).ConfigureAwait(false); + Assert.NotNull(Session.LastTurn); + return Session.LastTurn; } - _cancellation.Dispose(); - foreach (var disposable in _disposables) + public async ValueTask DisposeAsync() { - disposable.Dispose(); + // A fact that stops before it interrupts must not leave the background task hanging. + _openGate(); + _ = _firstUpdate.TrySetResult(); + + try + { + await _run.ConfigureAwait(false); + } + catch (OperationCanceledException) + { + // The host token already ended the run. Nothing here is left to observe. + } + + _cancellation.Dispose(); + foreach (IDisposable disposable in _disposables) + { + disposable.Dispose(); + } } - } - private async Task PumpAsync() - { - await foreach (var update in Session.RunTurnStreamingAsync("hi", _cancellation.Token) - .ConfigureAwait(false)) + private async Task PumpAsync() { - // The tool-call and tool-result updates carry no TextContent, so only the reply - // itself opens the window in which a test may interrupt. - if (update.Contents.OfType().Any(text => text.Text.Length > 0)) + await foreach (ChatResponseUpdate? update in Session.RunTurnStreamingAsync("hi", _cancellation.Token) + .ConfigureAwait(false)) { - _firstUpdate.TrySetResult(); + // The tool-call and tool-result updates carry no TextContent, so only the reply + // itself opens the window in which a test may interrupt. + if (update.Contents.OfType().Any(text => text.Text.Length > 0)) + { + _ = _firstUpdate.TrySetResult(); + } } } } - } - /// - /// Calls the one tool it is offered, then streams its final reply and blocks after the first - /// fragment until the test opens the gate. - /// - /// - /// covers the tool round, and - /// covers a gated round, but the finished-tool fact of this file needs both in one run: a tool - /// conversation whose result already arrived before the barge-in reaches the reply that follows it. - /// - private sealed class GatedToolThenReplyChatClient : IChatClient - { - private const string ToolCallId = "conversation_1"; - - private readonly string[] _fragments; - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + /// + /// Calls the one tool it is offered, then streams its final reply and blocks after the first + /// fragment until the test opens the gate. + /// + /// + /// covers the tool round, and + /// covers a gated round, but the finished-tool fact of this file needs both in one run: a tool + /// conversation whose result already arrived before the barge-in reaches the reply that follows it. + /// + private sealed class GatedToolThenReplyChatClient(string reply) : IChatClient + { + private const string ToolCallId = "conversation_1"; - public GatedToolThenReplyChatClient(string reply) => _fragments = reply.Split(' '); + private readonly string[] _fragments = reply.Split(' '); + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - /// Lets every fragment after the first flow. - public void OpenGate() => _gate.TrySetResult(); + /// Lets every fragment after the first flow. + public void OpenGate() + { + _ = _gate.TrySetResult(); + } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - var answered = messages.Any(message => message.Contents.OfType().Any()); - var responseId = Guid.NewGuid().ToString("N"); + bool answered = messages.Any(message => message.Contents.OfType().Any()); + string responseId = Guid.NewGuid().ToString("N"); - if (!answered && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent(ToolCallId, tool.Name, new Dictionary(StringComparer.Ordinal))]) + if (!answered && options?.Tools?.OfType().FirstOrDefault() is { } tool) { - ResponseId = responseId, - MessageId = responseId, - }; + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent(ToolCallId, tool.Name, new Dictionary(StringComparer.Ordinal))]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } - yield break; + for (int index = 0; index < _fragments.Length; index++) + { + if (index == 1) + { + // The tool round already finished, so this is the round a barge-in interrupts. + await _gate.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + } + + string text = index == 0 ? _fragments[index] : " " + _fragments[index]; + yield return new ChatResponseUpdate(ChatRole.Assistant, text) + { + ResponseId = responseId, + MessageId = responseId, + }; + } } - for (var index = 0; index < _fragments.Length; index++) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - if (index == 1) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - // The tool round already finished, so this is the round a barge-in interrupts. - await _gate.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + updates.Add(update); } - var text = index == 0 ? _fragments[index] : " " + _fragments[index]; - yield return new ChatResponseUpdate(ChatRole.Assistant, text) - { - ResponseId = responseId, - MessageId = responseId, - }; + return updates.ToChatResponse(); } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public void Dispose() + { + // Nothing to release. + } } - public void Dispose() + /// + /// Announces the tool in prose and calls it, both on one assistant message, then streams its + /// final reply and blocks after the first fragment until the test opens the gate. + /// + /// + /// yields a tool round that carries nothing but the + /// conversation. A real model routinely writes a line first — "Let me check that for you" — and puts the + /// conversation beside it on the same message. No other fake in this project can produce that shape, and + /// it is the shape the transcript rule of item 6a has to survive. + /// + private sealed class ProseBesideToolChatClient(string reply) : IChatClient { - // Nothing to release. - } - } - - /// - /// Announces the tool in prose and calls it, both on one assistant message, then streams its - /// final reply and blocks after the first fragment until the test opens the gate. - /// - /// - /// yields a tool round that carries nothing but the - /// conversation. A real model routinely writes a line first — "Let me check that for you" — and puts the - /// conversation beside it on the same message. No other fake in this project can produce that shape, and - /// it is the shape the transcript rule of item 6a has to survive. - /// - private sealed class ProseBesideToolChatClient : IChatClient - { - /// The line the model speaks before it calls the tool. - public const string Prose = "Let me check that for you"; + /// The line the model speaks before it calls the tool. + public const string Prose = "Let me check that for you"; - private const string ToolCallId = "conversation_1"; + private const string ToolCallId = "conversation_1"; - private readonly string[] _fragments; - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly string[] _fragments = reply.Split(' '); + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - public ProseBesideToolChatClient(string reply) => _fragments = reply.Split(' '); - - /// Lets every fragment after the first flow. - public void OpenGate() => _gate.TrySetResult(); + /// Lets every fragment after the first flow. + public void OpenGate() + { + _ = _gate.TrySetResult(); + } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - var answered = messages.Any(message => message.Contents.OfType().Any()); - var responseId = Guid.NewGuid().ToString("N"); + bool answered = messages.Any(message => message.Contents.OfType().Any()); + string responseId = Guid.NewGuid().ToString("N"); - if (!answered && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - // The prose and the conversation ride one message, which is what a real model produces. - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [ - new TextContent(Prose), - new FunctionCallContent(ToolCallId, tool.Name, new Dictionary(StringComparer.Ordinal)), - ]) + if (!answered && options?.Tools?.OfType().FirstOrDefault() is { } tool) { - ResponseId = responseId, - MessageId = responseId, - }; + // The prose and the conversation ride one message, which is what a real model produces. + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [ + new TextContent(Prose), + new FunctionCallContent(ToolCallId, tool.Name, new Dictionary(StringComparer.Ordinal)), + ]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } - yield break; + for (int index = 0; index < _fragments.Length; index++) + { + if (index == 1) + { + // The tool round already finished, so this is the round a barge-in interrupts. + await _gate.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + } + + string text = index == 0 ? _fragments[index] : " " + _fragments[index]; + yield return new ChatResponseUpdate(ChatRole.Assistant, text) + { + ResponseId = responseId, + MessageId = responseId, + }; + } } - for (var index = 0; index < _fragments.Length; index++) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - if (index == 1) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - // The tool round already finished, so this is the round a barge-in interrupts. - await _gate.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + updates.Add(update); } - var text = index == 0 ? _fragments[index] : " " + _fragments[index]; - yield return new ChatResponseUpdate(ChatRole.Assistant, text) - { - ResponseId = responseId, - MessageId = responseId, - }; + return updates.ToChatResponse(); } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); + public void Dispose() + { + // Nothing to release. + } } - public object? GetService(Type serviceType, object? serviceKey = null) + /// + /// Streams its first reply to the end, then blocks the second one before it says a word. + /// + /// + /// This is the shape a held prompt produces: turn one finishes streaming, turn two starts at + /// once, and the vendor is still speaking turn one. A barge-in that lands in that window belongs + /// to turn one, and turn two has produced nothing for anyone to have heard. + /// + private sealed class SecondTurnGatedChatClient(string first, string second) : IChatClient { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + private readonly string _first = first; + private readonly string _second = second; + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private int _calls; - public void Dispose() - { - // Nothing to release. - } - } + /// Signals once the second turn's own model call is in flight and blocked. + public TaskCompletionSource SecondTurnStarted { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); - /// - /// Streams its first reply to the end, then blocks the second one before it says a word. - /// - /// - /// This is the shape a held prompt produces: turn one finishes streaming, turn two starts at - /// once, and the vendor is still speaking turn one. A barge-in that lands in that window belongs - /// to turn one, and turn two has produced nothing for anyone to have heard. - /// - private sealed class SecondTurnGatedChatClient : IChatClient - { - private readonly string _first; - private readonly string _second; - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private int _calls; + /// Lets the second reply flow. + public void OpenGate() + { + _ = _gate.TrySetResult(); + } - public SecondTurnGatedChatClient(string first, string second) - { - _first = first; - _second = second; - } + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - /// Signals once the second turn's own model call is in flight and blocked. - public TaskCompletionSource SecondTurnStarted { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); + int index = Interlocked.Increment(ref _calls); + string responseId = Guid.NewGuid().ToString("N"); - /// Lets the second reply flow. - public void OpenGate() => _gate.TrySetResult(); + if (index > 1) + { + _ = SecondTurnStarted.TrySetResult(); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + // Not WaitAsync(cancellationToken): a defect that cancelled this turn would then + // look like the pass this test is trying to disprove. + await _gate.Task.ConfigureAwait(false); + } - var index = Interlocked.Increment(ref _calls); - var responseId = Guid.NewGuid().ToString("N"); + foreach (string? word in (index == 1 ? _first : _second).Split(' ') + .Select((word, position) => position == 0 ? word : " " + word)) + { + yield return new ChatResponseUpdate(ChatRole.Assistant, word) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + } - if (index > 1) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - SecondTurnStarted.TrySetResult(); + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - // Not WaitAsync(cancellationToken): a defect that cancelled this turn would then - // look like the pass this test is trying to disprove. - await _gate.Task.ConfigureAwait(false); + return updates.ToChatResponse(); } - foreach (var word in (index == 1 ? _first : _second).Split(' ') - .Select((word, position) => position == 0 ? word : " " + word)) + public object? GetService(Type serviceType, object? serviceKey = null) { - yield return new ChatResponseUpdate(ChatRole.Assistant, word) - { - ResponseId = responseId, - MessageId = responseId, - }; + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public void Dispose() { - updates.Add(update); + // Nothing to release. } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - public void Dispose() + /// + /// Answers with one call, then, once that call's result is in context, answers with that same + /// call again alongside a brand new one, both on a single message. + /// + /// + /// The runtime commits a round's tool results as one batch, so a round that never finishes + /// invoking surfaces no message at all, finished or not. Round one is a single call and finishes + /// on its own, so its result is already on the transcript when round two's message asks for two + /// conversations at once. That is the only way to reach the shape the multi-conversation fact needs: a message + /// with two calls where the finished-tool filter must trim rather than drop or keep it whole. + /// + private sealed class ParallelToolCallChatClient : IChatClient { - // Nothing to release. - } - } + /// The id of the conversation whose result arrives before the barge-in. + public const string FirstCallId = "conversation_a"; - /// - /// Answers with one call, then, once that call's result is in context, answers with that same - /// call again alongside a brand new one, both on a single message. - /// - /// - /// The runtime commits a round's tool results as one batch, so a round that never finishes - /// invoking surfaces no message at all, finished or not. Round one is a single call and finishes - /// on its own, so its result is already on the transcript when round two's message asks for two - /// conversations at once. That is the only way to reach the shape the multi-conversation fact needs: a message - /// with two calls where the finished-tool filter must trim rather than drop or keep it whole. - /// - private sealed class ParallelToolCallChatClient : IChatClient - { - /// The id of the conversation whose result arrives before the barge-in. - public const string FirstCallId = "conversation_a"; + /// The id of the conversation still in flight when the barge-in arrives. + public const string SecondCallId = "conversation_b"; - /// The id of the conversation still in flight when the barge-in arrives. - public const string SecondCallId = "conversation_b"; + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + HashSet answered = messages + .SelectMany(message => message.Contents.OfType()) + .Select(result => result.CallId) + .ToHashSet(StringComparer.Ordinal); - var answered = messages - .SelectMany(message => message.Contents.OfType()) - .Select(result => result.CallId) - .ToHashSet(StringComparer.Ordinal); + AIFunction tool = options?.Tools?.OfType().FirstOrDefault() + ?? throw new InvalidOperationException("The turn offers no tool to call."); + string responseId = Guid.NewGuid().ToString("N"); - var tool = options?.Tools?.OfType().FirstOrDefault() - ?? throw new InvalidOperationException("The turn offers no tool to call."); - var responseId = Guid.NewGuid().ToString("N"); + if (!answered.Contains(FirstCallId)) + { + // Round one. One call, so the runtime's batch commits alone and finishes at once. + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [ + new FunctionCallContent( + FirstCallId, tool.Name, new Dictionary(StringComparer.Ordinal) { ["index"] = 1 }), + ]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } - if (!answered.Contains(FirstCallId)) - { - // Round one. One call, so the runtime's batch commits alone and finishes at once. + // Round two. The already-answered conversation rides again beside the new one, on one message. yield return new ChatResponseUpdate( ChatRole.Assistant, [ new FunctionCallContent( FirstCallId, tool.Name, new Dictionary(StringComparer.Ordinal) { ["index"] = 1 }), + new FunctionCallContent( + SecondCallId, tool.Name, new Dictionary(StringComparer.Ordinal) { ["index"] = 2 }), ]) { ResponseId = responseId, MessageId = responseId, }; - - yield break; } - // Round two. The already-answered conversation rides again beside the new one, on one message. - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [ - new FunctionCallContent( - FirstCallId, tool.Name, new Dictionary(StringComparer.Ordinal) { ["index"] = 1 }), - new FunctionCallContent( - SecondCallId, tool.Name, new Dictionary(StringComparer.Ordinal) { ["index"] = 2 }), - ]) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } - } - /// - /// Answers the first call to the one declared tool at once, and blocks the second call until the - /// run's own cancellation ends it. - /// - /// - /// The barge-in cancels the run's token, and nothing else ever completes the second call, so its - /// result never joins . tells - /// a test the first conversation already finished and the second is now the one in flight, which is the - /// instant a test must interrupt to pin the per-conversation-id rule. - /// - private sealed class PartiallyAnsweredToolFactory - { - /// Signals once the second call is in flight and blocked. - public TaskCompletionSource SecondConversationStarted { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); - - public AIFunction? Create(ToolConfiguration tool) + /// + /// Answers the first call to the one declared tool at once, and blocks the second call until the + /// run's own cancellation ends it. + /// + /// + /// The barge-in cancels the run's token, and nothing else ever completes the second call, so its + /// result never joins . tells + /// a test the first conversation already finished and the second is now the one in flight, which is the + /// instant a test must interrupt to pin the per-conversation-id rule. + /// + private sealed class PartiallyAnsweredToolFactory { - ArgumentNullException.ThrowIfNull(tool); - return AIFunctionFactory.Create(AnswerAsync, tool.Id, tool.Description ?? tool.Id); - } + /// Signals once the second call is in flight and blocked. + public TaskCompletionSource SecondConversationStarted { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); - private async Task AnswerAsync(int index, CancellationToken cancellationToken) - { - if (index == 1) + public AIFunction? Create(ToolConfiguration tool) { - return "50"; + ArgumentNullException.ThrowIfNull(tool); + return AIFunctionFactory.Create(AnswerAsync, tool.Id, tool.Description ?? tool.Id); } - SecondConversationStarted.TrySetResult(); - await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + private async Task AnswerAsync(int index, CancellationToken cancellationToken) + { + if (index == 1) + { + return "50"; + } + + _ = SecondConversationStarted.TrySetResult(); + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); - // Unreachable: the delay above only ever ends in cancellation. - return string.Empty; + // Unreachable: the delay above only ever ends in cancellation. + return string.Empty; + } } - } - /// - /// Reports that the extractor call is in flight, then holds it until the test lets it answer. - /// - /// - /// never answers at all, which is what §8.7's deadline needs. - /// This one has to answer, because the fact it serves is about what the turn commits *after* the - /// extractor returns: the window a late barge-in lands in is exactly the width of this conversation, and - /// nothing else in the turn loop opens one that a test can stand inside of. The gate is not read - /// through on purpose — the extractor runs on the host token so - /// a barge-in never cancels it, and a defect that did cancel it would end this wait quietly and - /// look like the pass this fake exists to disprove. - /// - private sealed class GatedExtractorChatClient : IChatClient - { - private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + /// + /// Reports that the extractor call is in flight, then holds it until the test lets it answer. + /// + /// + /// never answers at all, which is what §8.7's deadline needs. + /// This one has to answer, because the fact it serves is about what the turn commits *after* the + /// extractor returns: the window a late barge-in lands in is exactly the width of this conversation, and + /// nothing else in the turn loop opens one that a test can stand inside of. The gate is not read + /// through on purpose — the extractor runs on the host token so + /// a barge-in never cancels it, and a defect that did cancel it would end this wait quietly and + /// look like the pass this fake exists to disprove. + /// + private sealed class GatedExtractorChatClient : IChatClient + { + private readonly TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); - /// Gets a task that completes once the extractor's own model call is in flight. - public TaskCompletionSource Started { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); + /// Gets a task that completes once the extractor's own model call is in flight. + public TaskCompletionSource Started { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); - /// Lets the extractor answer. - public void OpenGate() => _gate.TrySetResult(); + /// Lets the extractor answer. + public void OpenGate() + { + _ = _gate.TrySetResult(); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Started.TrySetResult(); - await _gate.Task.ConfigureAwait(false); + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + _ = Started.TrySetResult(); + await _gate.Task.ConfigureAwait(false); - // An empty document fills no slot, which is all this fake owes the writer order. - return new ChatResponse(new ChatMessage(ChatRole.Assistant, "{}")); - } + // An empty document fills no slot, which is all this fake owes the writer order. + return new ChatResponse(new ChatMessage(ChatRole.Assistant, "{}")); + } - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - // StateExtractor.ExtractAsync calls GetResponseAsync and never streams. - throw new NotSupportedException("The extractor calls GetResponseAsync, and never streams."); - } + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + // StateExtractor.ExtractAsync calls GetResponseAsync and never streams. + throw new NotSupportedException("The extractor calls GetResponseAsync, and never streams."); + } - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } - } - - /// Answers nothing, ever. It stands in for the extractor model hanging past its deadline. - /// - /// §8.7's deadline is what ends this conversation, not the model, so awaits - /// a nobody ever sets. It returns only when its own - /// cancels. - /// - private sealed class HangingChatClient : IChatClient - { - private readonly TaskCompletionSource _neverSet = new(TaskCreationOptions.RunContinuationsAsynchronously); - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) + /// Answers nothing, ever. It stands in for the extractor model hanging past its deadline. + /// + /// §8.7's deadline is what ends this conversation, not the model, so awaits + /// a nobody ever sets. It returns only when its own + /// cancels. + /// + private sealed class HangingChatClient : IChatClient { - ArgumentNullException.ThrowIfNull(messages); - await _neverSet.Task.WaitAsync(cancellationToken).ConfigureAwait(false); + private readonly TaskCompletionSource _neverSet = new(TaskCreationOptions.RunContinuationsAsynchronously); - // Unreachable: nothing ever completes _neverSet, so the wait above only ever cancels. - return new ChatResponse(new ChatMessage(ChatRole.Assistant, string.Empty)); - } + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await _neverSet.Task.WaitAsync(cancellationToken).ConfigureAwait(false); - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - // StateExtractor.ExtractAsync calls GetResponseAsync and never streams. - throw new NotSupportedException("The extractor calls GetResponseAsync, and never streams."); - } + // Unreachable: nothing ever completes _neverSet, so the wait above only ever cancels. + return new ChatResponse(new ChatMessage(ChatRole.Assistant, string.Empty)); + } - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + // StateExtractor.ExtractAsync calls GetResponseAsync and never streams. + throw new NotSupportedException("The extractor calls GetResponseAsync, and never streams."); + } - public void Dispose() - { - // Nothing to release. + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + // Nothing to release. + } } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionProbeTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionProbeTests.cs index 36bd2688..3cdf5f4b 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionProbeTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionProbeTests.cs @@ -4,24 +4,25 @@ using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; +using AgentCore.Application.State; using AgentCore.Domain.Knowledge; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// §8's probe, driven through real turns rather than by seeding the -/// ambient: the genuinely two-turn row (K43's latch reset against K22's persistent counter) needs -/// the real turn loop's own BeginTurn, which KnowledgeProbeTests's ambient-level -/// tests cannot exercise. -/// -public sealed class ConversationSessionProbeTests +namespace AgentCore.Application.Tests.Runtime { - /// One tool-mode, scoped agent over two droppable facets, so K33 never blocks the drop. - private const string ProbeYaml = - """ + /// + /// §8's probe, driven through real turns rather than by seeding the + /// ambient: the genuinely two-turn row (K43's latch reset against K22's persistent counter) needs + /// the real turn loop's own BeginTurn, which KnowledgeProbeTests's ambient-level + /// tests cannot exercise. + /// + public sealed class ConversationSessionProbeTests + { + /// One tool-mode, scoped agent over two droppable facets, so K33 never blocks the drop. + private const string ProbeYaml = + """ apiVersion: agentcore/v1 state: applies_to: @@ -62,140 +63,142 @@ public sealed class ConversationSessionProbeTests agent: only """; - [Fact] - public async Task TwoTurns_TheProbeAlwaysThrows_TheSecondTurnStillRunsAFreshProbeSearch() - { - // K43's latch is per-turn (cleared by BeginTurn); K22's probeAsks counter is not. A second - // turn that attempts a genuinely new probe search -- rather than replaying turn one's stored - // failure -- is what proves BeginTurn actually ran, wired through the real turn loop rather - // than asserted directly against Clarifications (KnowledgeProbeTests already covers that unit - // in isolation, without needing a live ConversationSession). - var narrowedCalls = 0; - var port = new ThrowingOnNarrowedScopePort(() => Interlocked.Increment(ref narrowedCalls)); - - ScriptedToolCallingChatClient reply = new( - (ToolName: "Search", Text: null), - (ToolName: null, Text: "let me note that."), - (ToolName: "Search", Text: null), - (ToolName: null, Text: "noted again.")); - SequencedChatClient extractor = new("{}", "{}"); - - RoutingChatClientFactory chatClients = new(reply); - chatClients.Route("reply", reply); - chatClients.Route("fill", extractor); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ProbeYaml), - new AgentCompilationContext(chatClients) { Knowledge = port })["main"]; - var stateExtractor = ConversationSessionFactory.CreateExtractor(compiled, chatClients); - - var session = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), stateExtractor) - .Create("conversation-probe-two-turn"); - - await session.RunTurnAsync("what model is it", TestContext.Current.CancellationToken); - await session.RunTurnAsync("still not sure", TestContext.Current.CancellationToken); - - // Both turns actually reached the port's narrowed-scope leg: a latch left claimed across the - // turn boundary would have made turn two replay turn one's stored "holds nothing" instead. - Assert.Equal(2, narrowedCalls); - } - - /// - /// A knowledge store that answers the full scope with nothing and throws for any narrowed one -- - /// the shape §8 step 4's own search takes once a facet is dropped. - /// - private sealed class ThrowingOnNarrowedScopePort : IKnowledgeRetrievalPort - { - private readonly Action _onNarrowedCall; - - internal ThrowingOnNarrowedScopePort(Action onNarrowedCall) => _onNarrowedCall = onNarrowedCall; + [Fact] + public async Task TwoTurns_TheProbeAlwaysThrows_TheSecondTurnStillRunsAFreshProbeSearch() + { + // K43's latch is per-turn (cleared by BeginTurn); K22's probeAsks counter is not. A second + // turn that attempts a genuinely new probe search -- rather than replaying turn one's stored + // failure -- is what proves BeginTurn actually ran, wired through the real turn loop rather + // than asserted directly against Clarifications (KnowledgeProbeTests already covers that unit + // in isolation, without needing a live ConversationSession). + int narrowedCalls = 0; + ThrowingOnNarrowedScopePort port = new(() => Interlocked.Increment(ref narrowedCalls)); + + ScriptedToolCallingChatClient reply = new( + (ToolName: "Search", Text: null), + (ToolName: null, Text: "let me note that."), + (ToolName: "Search", Text: null), + (ToolName: null, Text: "noted again.")); + SequencedChatClient extractor = new("{}", "{}"); + + RoutingChatClientFactory chatClients = new(reply); + _ = chatClients.Route("reply", reply); + _ = chatClients.Route("fill", extractor); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ProbeYaml), + new AgentCompilationContext(chatClients) { Knowledge = port })["main"]; + StateExtractor? stateExtractor = ConversationSessionFactory.CreateExtractor(compiled, chatClients); + + ConversationSession session = new ConversationSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), stateExtractor) + .Create("conversation-probe-two-turn"); + + _ = await session.RunTurnAsync("what model is it", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("still not sure", TestContext.Current.CancellationToken); + + // Both turns actually reached the port's narrowed-scope leg: a latch left claimed across the + // turn boundary would have made turn two replay turn one's stored "holds nothing" instead. + Assert.Equal(2, narrowedCalls); + } - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + /// + /// A knowledge store that answers the full scope with nothing and throws for any narrowed one -- + /// the shape §8 step 4's own search takes once a facet is dropped. + /// + private sealed class ThrowingOnNarrowedScopePort : IKnowledgeRetrievalPort { - if (scope is { Facets.Count: 2 }) + private readonly Action _onNarrowedCall; + + internal ThrowingOnNarrowedScopePort(Action onNarrowedCall) { - return ValueTask.FromResult>([]); + _onNarrowedCall = onNarrowedCall; } - _onNarrowedCall(); - throw new InvalidOperationException("the probe's own second search is down"); - } - } - - /// - /// A model that calls the framework's own "Search" tool (or none) on each request, in a fixed - /// script -- TextSearchProviderOptions.FunctionToolName's default, taking one required - /// string argument named userQuestion, both verified against real - /// Microsoft.Agents.AI 1.17.0. - /// - private sealed class ScriptedToolCallingChatClient : IChatClient - { - private readonly (string? ToolName, string? Text)[] _script; - private int _calls; + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + if (scope is { Facets.Count: 2 }) + { + return ValueTask.FromResult>([]); + } - public ScriptedToolCallingChatClient(params (string? ToolName, string? Text)[] script) => _script = script; + _onNarrowedCall(); + throw new InvalidOperationException("the probe's own second search is down"); + } + } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + /// + /// A model that calls the framework's own "Search" tool (or none) on each request, in a fixed + /// script -- TextSearchProviderOptions.FunctionToolName's default, taking one required + /// string argument named userQuestion, both verified against real + /// Microsoft.Agents.AI 1.17.0. + /// + private sealed class ScriptedToolCallingChatClient(params (string? ToolName, string? Text)[] script) : IChatClient { - ArgumentNullException.ThrowIfNull(messages); + private readonly (string? ToolName, string? Text)[] _script = script; + private int _calls; - var index = Interlocked.Increment(ref _calls) - 1; - await Task.Yield(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - var (toolName, text) = _script[Math.Min(index, _script.Length - 1)]; - var responseId = Guid.NewGuid().ToString("N"); + int index = Interlocked.Increment(ref _calls) - 1; + await Task.Yield(); - if (toolName is not null) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - $"conversation_{index}", - toolName, - new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = "what model is it" })]) + (string? toolName, string? text) = _script[Math.Min(index, _script.Length - 1)]; + string responseId = Guid.NewGuid().ToString("N"); + + if (toolName is not null) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + $"conversation_{index}", + toolName, + new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = "what model is it" })]) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, text ?? string.Empty) { ResponseId = responseId, MessageId = responseId, }; - yield break; } - yield return new ChatResponseUpdate(ChatRole.Assistant, text ?? string.Empty) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionTests.cs index 0c7fd07c..8379b9ab 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionTests.cs @@ -9,19 +9,20 @@ using AgentCore.Application.Tests.Fakes; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The turn loop. One session runs one conversation, and one turn walks the writers in one fixed order. -/// -/// -/// Every test here runs offline. There is no network conversation and no API key anywhere in this file. -/// -public sealed class ConversationSessionTests +namespace AgentCore.Application.Tests.Runtime { - private const string PolicyYaml = - """ + /// + /// The turn loop. One session runs one conversation, and one turn walks the writers in one fixed order. + /// + /// + /// Every test here runs offline. There is no network conversation and no API key anywhere in this file. + /// + public sealed class ConversationSessionTests + { + private const string PolicyYaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: @@ -59,8 +60,8 @@ public sealed class ConversationSessionTests terminal: true """; - private const string ReminderYaml = - """ + private const string ReminderYaml = + """ apiVersion: agentcore/v1 state: machineModel: { type: string, writer: extractor, description: the machine model } @@ -92,8 +93,8 @@ public sealed class ConversationSessionTests terminal: true """; - private const string TwoStagesYaml = - """ + private const string TwoStagesYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -110,8 +111,8 @@ public sealed class ConversationSessionTests - { id: close, agent: closer, to: [ { stage: greeting } ] } """; - private const string ToolYaml = - """ + private const string ToolYaml = + """ apiVersion: agentcore/v1 state: orderStatus: { type: string, writer: tool, from: lookup_order.status } @@ -143,8 +144,8 @@ public sealed class ConversationSessionTests - { id: close, agent: closer, terminal: true } """; - private const string OneAgentYaml = - """ + private const string OneAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -154,974 +155,977 @@ public sealed class ConversationSessionTests agent: only """; - private const string StayingNull = """{ "callerSaidGoodbye": null }"""; - private const string SaidGoodbye = """{ "callerSaidGoodbye": true }"""; + private const string StayingNull = /*lang=json,strict*/ """{ "callerSaidGoodbye": null }"""; + private const string SaidGoodbye = /*lang=json,strict*/ """{ "callerSaidGoodbye": true }"""; - // ------------------------------------------------------------------------------------------- - // One turn, end to end. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ATurn_RunsTheAgentOfTheCurrentStageAndReportsWhatItDid() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create("conversation-1"); - - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.Equal("conversation-1", turn.ConversationId); - Assert.Equal(0, turn.TurnIndex); - Assert.Equal("greeting", turn.StageBefore); - Assert.Equal("greeting", turn.StageAfter); - Assert.Equal("hello there.", turn.ReplyText); - Assert.False(turn.IsTerminal); - Assert.Null(turn.ExtractionFailure); - Assert.Same(turn, session.LastTurn); - } - - [Fact] - public async Task ATurn_MakesTwoModelCalls_TheReplyAndTheExtractor() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + // ------------------------------------------------------------------------------------------- + // One turn, end to end. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task ATurn_RunsTheAgentOfTheCurrentStageAndReportsWhatItDid() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.Equal("conversation-1", turn.ConversationId); + Assert.Equal(0, turn.TurnIndex); + Assert.Equal("greeting", turn.StageBefore); + Assert.Equal("greeting", turn.StageAfter); + Assert.Equal("hello there.", turn.ReplyText); + Assert.False(turn.IsTerminal); + Assert.Null(turn.ExtractionFailure); + Assert.Same(turn, session.LastTurn); + } - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + [Fact] + public async Task ATurn_MakesTwoModelCalls_TheReplyAndTheExtractor() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // The extractor has no retry: one reply conversation, and one extractor call. - Assert.Equal(1, reply.Calls); - Assert.Equal(1, fill.Calls); - } + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - [Fact] - public async Task TheTranscript_HoldsWhatTheCallerSaidAndWhatTheAgentAnswered() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + // The extractor has no retry: one reply conversation, and one extractor call. + Assert.Equal(1, reply.Calls); + Assert.Equal(1, fill.Calls); + } - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + [Fact] + public async Task TheTranscript_HoldsWhatTheCallerSaidAndWhatTheAgentAnswered() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - Assert.Equal(2, session.Transcript.Count); - Assert.Equal(ChatRole.User, session.Transcript[0].Role); - Assert.Equal("hi", session.Transcript[0].Text); - Assert.Equal(ChatRole.Assistant, session.Transcript[1].Role); - Assert.Equal("hello there.", session.Transcript[1].Text); - } + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - [Fact] - public async Task TheTranscript_HandsOutACopyAndNeverTheListTheSessionWritesTo() - { - using SequencedChatClient reply = new("hello there.", "and again."); - using SequencedChatClient fill = new(StayingNull, StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + Assert.Equal(2, session.Transcript.Count); + Assert.Equal(ChatRole.User, session.Transcript[0].Role); + Assert.Equal("hi", session.Transcript[0].Text); + Assert.Equal(ChatRole.Assistant, session.Transcript[1].Role); + Assert.Equal("hello there.", session.Transcript[1].Text); + } - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - var taken = session.Transcript; + [Fact] + public async Task TheTranscript_HandsOutACopyAndNeverTheListTheSessionWritesTo() + { + using SequencedChatClient reply = new("hello there.", "and again."); + using SequencedChatClient fill = new(StayingNull, StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + IReadOnlyList taken = session.Transcript; - // A live view would grow behind the reader's back, and an amendment splicing the list under - // an enumeration would throw rather than return a torn conversation. What was handed out is - // one whole conversation as it stood at one instant, and the session went on without it. - Assert.Equal(2, taken.Count); - Assert.Equal(4, session.Transcript.Count); - Assert.NotSame(taken, session.Transcript); - } + _ = await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // The reminder rides one request. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheReminder_ReachesTheReplyAgentAndLeavesTheCallersMessageAlone() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(ReminderYaml, reply, fill).Create(); + // A live view would grow behind the reader's back, and an amendment splicing the list under + // an enumeration would throw rather than return a torn conversation. What was handed out is + // one whole conversation as it stood at one instant, and the session went on without it. + Assert.Equal(2, taken.Count); + Assert.Equal(4, session.Transcript.Count); + Assert.NotSame(taken, session.Transcript); + } - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + // ------------------------------------------------------------------------------------------- + // The reminder rides one request. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheReminder_ReachesTheReplyAgentAndLeavesTheCallersMessageAlone() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(ReminderYaml, reply, fill).Create(); - // The stage waits on two slots the caller supplies, and no writer has filled either yet. - Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(0), StringComparison.Ordinal); - Assert.Contains( - "the machine model and the serial number", reply.SystemText(0), StringComparison.Ordinal); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - // The caller's utterance is the caller's. It goes to the model, to store 1 and to the - // extractor as it was spoken. - Assert.Equal("hi", reply.LastUserText(0)); - Assert.Equal("hi", session.Transcript[0].Text); - } + // The stage waits on two slots the caller supplies, and no writer has filled either yet. + Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(0), StringComparison.Ordinal); + Assert.Contains( + "the machine model and the serial number", reply.SystemText(0), StringComparison.Ordinal); - [Fact] - public async Task TheReminder_DropsASlotOnceAWriterFillsIt() - { - using SequencedChatClient reply = new("hello there.", "still here."); - using SequencedChatClient fill = new("""{ "machineModel": "F85" }""", StayingNull); - var session = Build(ReminderYaml, reply, fill).Create(); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // Turn 2 still waits on the serial number, so the reminder survives and names only that one. - Assert.Contains( - "the machine model and the serial number", reply.SystemText(0), StringComparison.Ordinal); - Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(1), StringComparison.Ordinal); - Assert.Contains("the serial number.", reply.SystemText(1), StringComparison.Ordinal); - Assert.DoesNotContain("the machine model", reply.SystemText(1), StringComparison.Ordinal); - } + // The caller's utterance is the caller's. It goes to the model, to store 1 and to the + // extractor as it was spoken. + Assert.Equal("hi", reply.LastUserText(0)); + Assert.Equal("hi", session.Transcript[0].Text); + } - [Fact] - public async Task TheReminder_ReachesAStreamingTurnToo() - { - // The run is inside the async iterator, and an iterator restores its caller's execution - // context at every yield. A per-turn ambient value has to be opened again for each round or - // the streaming path silently loses the reminder the buffered path carries. - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(ReminderYaml, reply, fill).Create(); - - await foreach (var _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + [Fact] + public async Task TheReminder_DropsASlotOnceAWriterFillsIt() { + using SequencedChatClient reply = new("hello there.", "still here."); + using SequencedChatClient fill = new(/*lang=json,strict*/ """{ "machineModel": "F85" }""", StayingNull); + ConversationSession session = Build(ReminderYaml, reply, fill).Create(); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // Turn 2 still waits on the serial number, so the reminder survives and names only that one. + Assert.Contains( + "the machine model and the serial number", reply.SystemText(0), StringComparison.Ordinal); + Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(1), StringComparison.Ordinal); + Assert.Contains("the serial number.", reply.SystemText(1), StringComparison.Ordinal); + Assert.DoesNotContain("the machine model", reply.SystemText(1), StringComparison.Ordinal); } - Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(0), StringComparison.Ordinal); - Assert.Equal("hi", reply.LastUserText(0)); - } + [Fact] + public async Task TheReminder_ReachesAStreamingTurnToo() + { + // The run is inside the async iterator, and an iterator restores its caller's execution + // context at every yield. A per-turn ambient value has to be opened again for each round or + // the streaming path silently loses the reminder the buffered path carries. + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(ReminderYaml, reply, fill).Create(); + + await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + } - [Fact] - public async Task TheReminder_NeverAsksTheCallerForAnInferredFlag() - { - // config/local.yaml ships this shape: one boolean the extractor infers from the turn, read by - // the exit guard of the talking stage, carrying a default. Section 8.3 reminds on a slot that - // is "still null", and a default is never null, so nothing is owed and the caller is not asked. - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var turnContext = reply.SystemText(0); - Assert.DoesNotContain(UnfilledSlotReminder.OpenTag, turnContext, StringComparison.Ordinal); - Assert.DoesNotContain("callerSaidGoodbye", turnContext, StringComparison.Ordinal); - } + Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(0), StringComparison.Ordinal); + Assert.Equal("hi", reply.LastUserText(0)); + } - // ------------------------------------------------------------------------------------------- - // The session owns the transcript, and the stage switches the agent. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheStage_SwitchesTheAgentAndTheTranscriptCarriesTheWholeConversation() - { - using SequencedChatClient reply = new("first reply.", "second reply."); - var session = Build(TwoStagesYaml, reply, null).Create(); + [Fact] + public async Task TheReminder_NeverAsksTheCallerForAnInferredFlag() + { + // config/local.yaml ships this shape: one boolean the extractor infers from the turn, read by + // the exit guard of the talking stage, carrying a default. Section 8.3 reminds on a slot that + // is "still null", and a default is never null, so nothing is owed and the caller is not asked. + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + string turnContext = reply.SystemText(0); + Assert.DoesNotContain(UnfilledSlotReminder.OpenTag, turnContext, StringComparison.Ordinal); + Assert.DoesNotContain("callerSaidGoodbye", turnContext, StringComparison.Ordinal); + } - await session.RunTurnAsync("one", TestContext.Current.CancellationToken); - Assert.Equal("close", session.Stage); + // ------------------------------------------------------------------------------------------- + // The session owns the transcript, and the stage switches the agent. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheStage_SwitchesTheAgentAndTheTranscriptCarriesTheWholeConversation() + { + using SequencedChatClient reply = new("first reply.", "second reply."); + ConversationSession session = Build(TwoStagesYaml, reply, null).Create(); - await session.RunTurnAsync("two", TestContext.Current.CancellationToken); - Assert.Equal("greeting", session.Stage); + _ = await session.RunTurnAsync("one", TestContext.Current.CancellationToken); + Assert.Equal("close", session.Stage); - // Each stage names its own agent, so the instructions change between the two requests. - Assert.Contains("I am the greeter", reply.Options[0]!.Instructions, StringComparison.Ordinal); - Assert.Contains("I am the closer", reply.Options[1]!.Instructions, StringComparison.Ordinal); + _ = await session.RunTurnAsync("two", TestContext.Current.CancellationToken); + Assert.Equal("greeting", session.Stage); - // A session bound to one agent could not carry this. The turn loop owns the transcript, so - // the second agent reads the first turn. - Assert.Contains(reply.Requests[1], message => Contains(message, "one")); - Assert.Contains(reply.Requests[1], message => Contains(message, "first reply.")); - } + // Each stage names its own agent, so the instructions change between the two requests. + Assert.Contains("I am the greeter", reply.Options[0]!.Instructions, StringComparison.Ordinal); + Assert.Contains("I am the closer", reply.Options[1]!.Instructions, StringComparison.Ordinal); - // ------------------------------------------------------------------------------------------- - // The writers, in order. - // ------------------------------------------------------------------------------------------- - [Fact] - public void TheConstWriter_RunsOnceWhenTheSessionStarts() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); + // A session bound to one agent could not carry this. The turn loop owns the transcript, so + // the second agent reads the first turn. + Assert.Contains(reply.Requests[1], message => Contains(message, "one")); + Assert.Contains(reply.Requests[1], message => Contains(message, "first reply.")); + } - var session = Build(PolicyYaml, reply, fill).Create(); + // ------------------------------------------------------------------------------------------- + // The writers, in order. + // ------------------------------------------------------------------------------------------- + [Fact] + public void TheConstWriter_RunsOnceWhenTheSessionStarts() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); - // A constant never changes, so it is written before the first turn and never again. - Assert.Equal("sole", session.State.Read("brand")!.GetValue()); - Assert.False(session.State.IsUnfilled("brand")); - } + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - [Fact] - public async Task TheCounter_RunsBeforeTheTransitionAndReadsTheStageTheTurnSpokeIn() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(SaidGoodbye); - var session = Build(PolicyYaml, reply, fill).Create(); + // A constant never changes, so it is written before the first turn and never again. + Assert.Equal("sole", session.State.Read("brand")!.GetValue()); + Assert.False(session.State.IsUnfilled("brand")); + } - var turn = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); + [Fact] + public async Task TheCounter_RunsBeforeTheTransitionAndReadsTheStageTheTurnSpokeIn() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(SaidGoodbye); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // The turn spoke in greeting and the machine then moved to close. The counter rule reads - // stage === greeting, so a counter that ran after the transition would report zero. - Assert.Equal("greeting", turn.StageBefore); - Assert.Equal("close", turn.StageAfter); - Assert.Equal(1, session.State.Read("greetingTurns")!.GetValue()); - } + TurnResult turn = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); - [Fact] - public async Task TheToolWriter_RunsBeforeTheCounterThatReadsItsSlot() - { - using ToolCallingChatClient reply = new("your order is on the way."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(ToolYaml, reply, fill, new StubToolBuilder("""{ "status": "shipped" }""").Create).Create(); + // The turn spoke in greeting and the machine then moved to close. The counter rule reads + // stage === greeting, so a counter that ran after the transition would report zero. + Assert.Equal("greeting", turn.StageBefore); + Assert.Equal("close", turn.StageAfter); + Assert.Equal(1, session.State.Read("greetingTurns")!.GetValue()); + } - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + [Fact] + public async Task TheToolWriter_RunsBeforeTheCounterThatReadsItsSlot() + { + using ToolCallingChatClient reply = new("your order is on the way."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(ToolYaml, reply, fill, new StubToolBuilder(/*lang=json,strict*/ """{ "status": "shipped" }""").Create).Create(); - Assert.Equal(["lookup_order"], reply.Called); - Assert.Equal("shipped", session.State.Read("orderStatus")!.GetValue()); + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - // The counter rule reads orderStatus. It is one only because the tool writer went first. - Assert.Equal(1, session.State.Read("shippedTurns")!.GetValue()); - Assert.Equal("greeting", turn.StageAfter); - } + Assert.Equal(["lookup_order"], reply.Called); + Assert.Equal("shipped", session.State.Read("orderStatus")!.GetValue()); - [Fact] - public async Task TheToolWriter_ReadsAResultTheToolAnsweredAsText() - { - using ToolCallingChatClient reply = new("your order is on the way."); - using SequencedChatClient fill = new(StayingNull); - var tools = new StubToolBuilder("""{ "status": "shipped" }""", asText: true); - var session = Build(ToolYaml, reply, fill, tools.Create).Create(); + // The counter rule reads orderStatus. It is one only because the tool writer went first. + Assert.Equal(1, session.State.Read("shippedTurns")!.GetValue()); + Assert.Equal("greeting", turn.StageAfter); + } - await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + [Fact] + public async Task TheToolWriter_ReadsAResultTheToolAnsweredAsText() + { + using ToolCallingChatClient reply = new("your order is on the way."); + using SequencedChatClient fill = new(StayingNull); + StubToolBuilder tools = new(/*lang=json,strict*/ """{ "status": "shipped" }""", asText: true); + ConversationSession session = Build(ToolYaml, reply, fill, tools.Create).Create(); - // A tool result has no declared shape, so a document answered as one string still resolves. - Assert.Equal("shipped", session.State.Read("orderStatus")!.GetValue()); - } + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - [Fact] - public async Task TheExtractor_RunsBeforeTheTransitionThatReadsItsSlot() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(SaidGoodbye); - var session = Build(PolicyYaml, reply, fill).Create(); + // A tool result has no declared shape, so a document answered as one string still resolves. + Assert.Equal("shipped", session.State.Read("orderStatus")!.GetValue()); + } - var turn = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); + [Fact] + public async Task TheExtractor_RunsBeforeTheTransitionThatReadsItsSlot() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(SaidGoodbye); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // The guard reads callerSaidGoodbye, and only the extractor writes it. - Assert.True(session.State.Read("callerSaidGoodbye")!.GetValue()); - Assert.Equal("close", turn.StageAfter); - Assert.True(turn.IsTerminal); - Assert.True(session.IsComplete); - } + TurnResult turn = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); - [Fact] - public async Task TheExtractor_ReadsTheFinishedTurn() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // extractor.when: after_reply. The request holds what the caller said and what the agent - // answered, and the caller's message carries no reminder. - var request = fill.Requests[0]; - Assert.Contains(request, message => Contains(message, "hi")); - Assert.Contains(request, message => Contains(message, "hello there.")); - Assert.DoesNotContain(request, message => Contains(message, UnfilledSlotReminder.OpenTag)); - } + // The guard reads callerSaidGoodbye, and only the extractor writes it. + Assert.True(session.State.Read("callerSaidGoodbye")!.GetValue()); + Assert.Equal("close", turn.StageAfter); + Assert.True(turn.IsTerminal); + Assert.True(session.IsComplete); + } - [Fact] - public async Task TheExtractor_ReadsTheAgentsPreviousMessageBeforeTheFinishedTurn() - { - using SequencedChatClient reply = new("is it the CT900 or the CT900ENT?", "got it."); - using SequencedChatClient fill = new(StayingNull, StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); - - await session.RunTurnAsync("my belt slips", TestContext.Current.CancellationToken); - await session.RunTurnAsync("the ENT one", TestContext.Current.CancellationToken); - - // Turn 1 has no earlier agent message, so the finished turn stands alone. - var first = fill.Requests[0].Where(message => message.Role != ChatRole.System).ToList(); - Assert.Equal([ChatRole.User, ChatRole.Assistant], first.Select(message => message.Role)); - - // Turn 2: the caller is answering a question. Measured 2026-09-02: without the question in - // view the extractor reads "the ENT one" and fills nothing; with it, it fills the machine. - var second = fill.Requests[1].Where(message => message.Role != ChatRole.System).ToList(); - Assert.Equal([ChatRole.Assistant, ChatRole.User, ChatRole.Assistant], second.Select(message => message.Role)); - Assert.Equal("is it the CT900 or the CT900ENT?", second[0].Text); - Assert.Equal("the ENT one", second[1].Text); - Assert.Equal("got it.", second[2].Text); - } + [Fact] + public async Task TheExtractor_ReadsTheFinishedTurn() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // extractor.when: after_reply. The request holds what the caller said and what the agent + // answered, and the caller's message carries no reminder. + List request = fill.Requests[0]; + Assert.Contains(request, message => Contains(message, "hi")); + Assert.Contains(request, message => Contains(message, "hello there.")); + Assert.DoesNotContain(request, message => Contains(message, UnfilledSlotReminder.OpenTag)); + } - [Fact] - public async Task AFailedExtraction_DoesNotDropTheTurn() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new("I am sorry, I cannot do that."); - var session = Build(PolicyYaml, reply, fill).Create(); + [Fact] + public async Task TheExtractor_ReadsTheAgentsPreviousMessageBeforeTheFinishedTurn() + { + using SequencedChatClient reply = new("is it the CT900 or the CT900ENT?", "got it."); + using SequencedChatClient fill = new(StayingNull, StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); + + _ = await session.RunTurnAsync("my belt slips", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("the ENT one", TestContext.Current.CancellationToken); + + // Turn 1 has no earlier agent message, so the finished turn stands alone. + List first = [.. fill.Requests[0].Where(message => message.Role != ChatRole.System)]; + Assert.Equal([ChatRole.User, ChatRole.Assistant], first.Select(message => message.Role)); + + // Turn 2: the caller is answering a question. Measured 2026-09-02: without the question in + // view the extractor reads "the ENT one" and fills nothing; with it, it fills the machine. + List second = [.. fill.Requests[1].Where(message => message.Role != ChatRole.System)]; + Assert.Equal([ChatRole.Assistant, ChatRole.User, ChatRole.Assistant], second.Select(message => message.Role)); + Assert.Equal("is it the CT900 or the CT900ENT?", second[0].Text); + Assert.Equal("the ENT one", second[1].Text); + Assert.Equal("got it.", second[2].Text); + } - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + [Fact] + public async Task AFailedExtraction_DoesNotDropTheTurn() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new("I am sorry, I cannot do that."); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // Section 8.7: the extractor never drops a conversation. The turn ends, and it carries the reason. - Assert.NotNull(turn.ExtractionFailure); - Assert.Equal("hello there.", turn.ReplyText); - Assert.Equal("greeting", turn.StageAfter); - Assert.True(session.State.IsUnfilled("callerSaidGoodbye")); - } + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - [Fact] - public async Task ADocumentWithNoExtractor_RunsATurnAndReportsNoFailure() - { - using SequencedChatClient reply = new("first reply."); - var session = Build(TwoStagesYaml, reply, null).Create(); + // Section 8.7: the extractor never drops a conversation. The turn ends, and it carries the reason. + Assert.NotNull(turn.ExtractionFailure); + Assert.Equal("hello there.", turn.ReplyText); + Assert.Equal("greeting", turn.StageAfter); + Assert.True(session.State.IsUnfilled("callerSaidGoodbye")); + } - var turn = await session.RunTurnAsync("one", TestContext.Current.CancellationToken); + [Fact] + public async Task ADocumentWithNoExtractor_RunsATurnAndReportsNoFailure() + { + using SequencedChatClient reply = new("first reply."); + ConversationSession session = Build(TwoStagesYaml, reply, null).Create(); - Assert.Null(turn.ExtractionFailure); - Assert.Equal(1, reply.Calls); - } + TurnResult turn = await session.RunTurnAsync("one", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // The reserved slots. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheReservedSlots_CountTheFinishedTurnsAndReadTheInjectedClock() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - TestTimeProvider clock = new(); - var session = Build(PolicyYaml, reply, fill, timeProvider: clock).Create(); + Assert.Null(turn.ExtractionFailure); + Assert.Equal(1, reply.Calls); + } - Assert.Equal(0, session.State.TurnIndex); - Assert.Equal(0, session.State.ConversationDurationSeconds); + // ------------------------------------------------------------------------------------------- + // The reserved slots. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheReservedSlots_CountTheFinishedTurnsAndReadTheInjectedClock() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + TestTimeProvider clock = new(); + ConversationSession session = Build(PolicyYaml, reply, fill, timeProvider: clock).Create(); - clock.Advance(TimeSpan.FromSeconds(12.5)); - var first = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + Assert.Equal(0, session.State.TurnIndex); + Assert.Equal(0, session.State.ConversationDurationSeconds); - Assert.Equal(0, first.TurnIndex); - Assert.Equal(1, session.State.TurnIndex); - Assert.Equal(12.5, session.State.ConversationDurationSeconds); + clock.Advance(TimeSpan.FromSeconds(12.5)); + TurnResult first = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - clock.Advance(TimeSpan.FromSeconds(7.5)); - var second = await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + Assert.Equal(0, first.TurnIndex); + Assert.Equal(1, session.State.TurnIndex); + Assert.Equal(12.5, session.State.ConversationDurationSeconds); - Assert.Equal(1, second.TurnIndex); - Assert.Equal(2, session.State.TurnIndex); - Assert.Equal(20, session.State.ConversationDurationSeconds); - } + clock.Advance(TimeSpan.FromSeconds(7.5)); + TurnResult second = await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - [Fact] - public async Task TheStage_ReachesTheStateDocumentSoAGuardReadsIt() - { - using SequencedChatClient reply = new("first reply."); - var session = Build(TwoStagesYaml, reply, null).Create(); + Assert.Equal(1, second.TurnIndex); + Assert.Equal(2, session.State.TurnIndex); + Assert.Equal(20, session.State.ConversationDurationSeconds); + } - await session.RunTurnAsync("one", TestContext.Current.CancellationToken); + [Fact] + public async Task TheStage_ReachesTheStateDocumentSoAGuardReadsIt() + { + using SequencedChatClient reply = new("first reply."); + ConversationSession session = Build(TwoStagesYaml, reply, null).Create(); - Assert.Equal("close", session.Stage); - Assert.Equal("close", session.State.Stage); - Assert.Equal("close", session.State.Snapshot()[ReservedStateSlots.Stage]!.GetValue()); - } + _ = await session.RunTurnAsync("one", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // A finished conversation. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ACompleteConversation_RejectsAFurtherTurn() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(SaidGoodbye); - var session = Build(PolicyYaml, reply, fill).Create(); + Assert.Equal("close", session.Stage); + Assert.Equal("close", session.State.Stage); + Assert.Equal("close", session.State.Snapshot()[ReservedStateSlots.Stage]!.GetValue()); + } - await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); - Assert.True(session.IsComplete); + // ------------------------------------------------------------------------------------------- + // A finished conversation. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task ACompleteConversation_RejectsAFurtherTurn() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(SaidGoodbye); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - var failure = await Assert.ThrowsAsync( - () => session.RunTurnAsync("hello again", TestContext.Current.CancellationToken)); + _ = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); + Assert.True(session.IsComplete); - Assert.Contains("close", failure.Message, StringComparison.Ordinal); - Assert.Equal(1, reply.Calls); - } + InvalidOperationException failure = await Assert.ThrowsAsync( + () => session.RunTurnAsync("hello again", TestContext.Current.CancellationToken)); - [Fact] - public async Task ADocumentWithNoPolicy_RunsTheOneAgentAndNeverEnds() - { - using SequencedChatClient reply = new("I answered."); - var session = Build(OneAgentYaml, reply, null).Create(); + Assert.Contains("close", failure.Message, StringComparison.Ordinal); + Assert.Equal(1, reply.Calls); + } - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + [Fact] + public async Task ADocumentWithNoPolicy_RunsTheOneAgentAndNeverEnds() + { + using SequencedChatClient reply = new("I answered."); + ConversationSession session = Build(OneAgentYaml, reply, null).Create(); - Assert.Equal(string.Empty, session.Stage); - Assert.Equal(string.Empty, turn.StageBefore); - Assert.Equal(string.Empty, turn.StageAfter); - Assert.False(turn.IsTerminal); - Assert.False(session.IsComplete); + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - await session.RunTurnAsync("again", TestContext.Current.CancellationToken); - Assert.Equal(2, reply.Calls); - } + Assert.Equal(string.Empty, session.Stage); + Assert.Equal(string.Empty, turn.StageBefore); + Assert.Equal(string.Empty, turn.StageAfter); + Assert.False(turn.IsTerminal); + Assert.False(session.IsComplete); - // ------------------------------------------------------------------------------------------- - // Streaming. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Streaming_CarriesTheWholeReplyAndThenFinishesTheTurn() - { - using ScriptedChatClient reply = new("hello", " there."); - using SequencedChatClient fill = new(SaidGoodbye); - var session = Build(PolicyYaml, reply, fill).Create(); + _ = await session.RunTurnAsync("again", TestContext.Current.CancellationToken); + Assert.Equal(2, reply.Calls); + } - List updates = []; - await foreach (var update in session.RunTurnStreamingAsync("goodbye", TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // Streaming. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Streaming_CarriesTheWholeReplyAndThenFinishesTheTurn() { - updates.Add(update); + using ScriptedChatClient reply = new("hello", " there."); + using SequencedChatClient fill = new(SaidGoodbye); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); + + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("goodbye", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } + + string text = string.Concat(updates.Select(update => update.Text)); + Assert.Equal("hello there.", text); + + Assert.NotNull(session.LastTurn); + Assert.Equal("hello there.", session.LastTurn.ReplyText); + Assert.Equal("close", session.LastTurn.StageAfter); + Assert.True(session.IsComplete); } - var text = string.Concat(updates.Select(update => update.Text)); - Assert.Equal("hello there.", text); + [Fact] + public async Task Streaming_MovesNothingUntilTheEnumerationCompletes() + { + using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; + using SequencedChatClient fill = new(SaidGoodbye); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - Assert.NotNull(session.LastTurn); - Assert.Equal("hello there.", session.LastTurn.ReplyText); - Assert.Equal("close", session.LastTurn.StageAfter); - Assert.True(session.IsComplete); - } + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); - [Fact] - public async Task Streaming_MovesNothingUntilTheEnumerationCompletes() - { - using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; - using SequencedChatClient fill = new(SaidGoodbye); - var session = Build(PolicyYaml, reply, fill).Create(); + await using IAsyncEnumerator updates = session.RunTurnStreamingAsync("goodbye", linked.Token).GetAsyncEnumerator(linked.Token); - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); + // The model holds every fragment after the first, so this line runs mid-reply. + Assert.True(await updates.MoveNextAsync()); + Assert.Equal("hello", updates.Current.Text); + Assert.Null(session.LastTurn); + Assert.Equal("greeting", session.Stage); + Assert.Equal(0, session.State.TurnIndex); - await using var updates = session.RunTurnStreamingAsync("goodbye", linked.Token).GetAsyncEnumerator(linked.Token); + reply.OpenGate(); + while (await updates.MoveNextAsync()) + { + // Drain the rest of the reply. + } - // The model holds every fragment after the first, so this line runs mid-reply. - Assert.True(await updates.MoveNextAsync()); - Assert.Equal("hello", updates.Current.Text); - Assert.Null(session.LastTurn); - Assert.Equal("greeting", session.Stage); - Assert.Equal(0, session.State.TurnIndex); + Assert.NotNull(session.LastTurn); + Assert.Equal("close", session.Stage); + Assert.Equal(1, session.State.TurnIndex); + } - reply.OpenGate(); - while (await updates.MoveNextAsync()) + [Fact] + public async Task ASecondTurn_IsRejectedWhileTheFirstOneIsStillRunning() { - // Drain the rest of the reply. - } + using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - Assert.NotNull(session.LastTurn); - Assert.Equal("close", session.Stage); - Assert.Equal(1, session.State.TurnIndex); - } + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); - [Fact] - public async Task ASecondTurn_IsRejectedWhileTheFirstOneIsStillRunning() - { - using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + await using IAsyncEnumerator updates = session.RunTurnStreamingAsync("hi", linked.Token).GetAsyncEnumerator(linked.Token); + Assert.True(await updates.MoveNextAsync()); - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); + // The state document takes no lock, so a second turn must fail rather than corrupt it. + InvalidOperationException failure = await Assert.ThrowsAsync( + () => session.RunTurnAsync("hi again", linked.Token)); + Assert.Contains("one turn at a time", failure.Message, StringComparison.Ordinal); - await using var updates = session.RunTurnStreamingAsync("hi", linked.Token).GetAsyncEnumerator(linked.Token); - Assert.True(await updates.MoveNextAsync()); + reply.OpenGate(); + while (await updates.MoveNextAsync()) + { + // Drain the rest of the reply. + } - // The state document takes no lock, so a second turn must fail rather than corrupt it. - var failure = await Assert.ThrowsAsync( - () => session.RunTurnAsync("hi again", linked.Token)); - Assert.Contains("one turn at a time", failure.Message, StringComparison.Ordinal); + Assert.NotNull(session.LastTurn); + } - reply.OpenGate(); - while (await updates.MoveNextAsync()) + // ------------------------------------------------------------------------------------------- + // Section 8.7, last row: the run returns quietly with no text. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AnEmptyReply_SpeaksTheFallbackAndReportsWhyTheTurnFailed() { - // Drain the rest of the reply. + using SequencedChatClient reply = new(" "); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); + + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // Request 41 goes out with no tools and the run returns with no exception. On a voice conversation + // that is silence, so the turn loop reads the reply rather than trusting the absence of a + // failure. + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); + Assert.Null(turn.InterruptedAfter); + + // The writers still ran, and the transcript holds what the caller heard. + Assert.Equal(1, session.State.TurnIndex); + Assert.Equal(1, session.State.Read("greetingTurns")!.GetValue()); + Assert.Equal(ConversationSession.FallbackReply, session.Transcript[^1].Text); } - Assert.NotNull(session.LastTurn); - } + [Fact] + public async Task AnEmptyReply_LeavesTheSessionReadyForTheNextTurn() + { + using SequencedChatClient reply = new("", "I am back."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // ------------------------------------------------------------------------------------------- - // Section 8.7, last row: the run returns quietly with no text. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AnEmptyReply_SpeaksTheFallbackAndReportsWhyTheTurnFailed() - { - using SequencedChatClient reply = new(" "); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); - - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // Request 41 goes out with no tools and the run returns with no exception. On a voice conversation - // that is silence, so the turn loop reads the reply rather than trusting the absence of a - // failure. - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); - Assert.Null(turn.InterruptedAfter); - - // The writers still ran, and the transcript holds what the caller heard. - Assert.Equal(1, session.State.TurnIndex); - Assert.Equal(1, session.State.Read("greetingTurns")!.GetValue()); - Assert.Equal(ConversationSession.FallbackReply, session.Transcript[^1].Text); - } + TurnResult first = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + TurnResult second = await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - [Fact] - public async Task AnEmptyReply_LeavesTheSessionReadyForTheNextTurn() - { - using SequencedChatClient reply = new("", "I am back."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + Assert.Equal(ConversationSession.FallbackReply, first.ReplyText); + Assert.Equal("I am back.", second.ReplyText); + Assert.Null(second.Failure); + Assert.Equal(1, second.TurnIndex); + } - var first = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - var second = await session.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + [Fact] + public async Task Streaming_SpeaksTheFallbackWhenTheRunProducesNoText() + { + using LifecycleChatClient reply = new(); + ConversationSession session = Build(TwoStagesYaml, reply, null).Create(); - Assert.Equal(ConversationSession.FallbackReply, first.ReplyText); - Assert.Equal("I am back.", second.ReplyText); - Assert.Null(second.Failure); - Assert.Equal(1, second.TurnIndex); - } + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } - [Fact] - public async Task Streaming_SpeaksTheFallbackWhenTheRunProducesNoText() - { - using LifecycleChatClient reply = new(); - var session = Build(TwoStagesYaml, reply, null).Create(); + // The host hears the fallback rather than nothing at all: R2 makes a quiet run an ordinary + // successful one, and the spoken line leaves the seam the same way any reply does. + Assert.Equal([ConversationSession.FallbackReply], updates.Select(update => update.Text)); + Assert.NotNull(session.LastTurn); + Assert.Equal(ConversationSession.FallbackReply, session.LastTurn.ReplyText); + Assert.Equal(ConversationSession.EmptyReplyReason, session.LastTurn.Failure); + Assert.Equal("close", session.Stage); + } - List updates = []; - await foreach (var update in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // Section 8.7, sixth row: the 4th consecutive tool failure. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheFourthConsecutiveToolFailure_EndsTheTurnAndNeverKillsTheConversation() { - updates.Add(update); + using LoopingToolCallingChatClient reply = new(); + using SequencedChatClient fill = new(StayingNull); + ThrowingToolBuilder tools = new(); + ConversationSession session = Build(ToolYaml, reply, fill, tools.Create).Create(); + + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // MaximumConsecutiveErrorsPerRequest is 3, so the 4th failure throws out of the run. + Assert.Equal(4, tools.Calls); + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.NotNull(turn.Failure); + Assert.StartsWith(ConversationSession.ToolFailureReason, turn.Failure, StringComparison.Ordinal); + Assert.Contains(ThrowingToolBuilder.Message, turn.Failure, StringComparison.Ordinal); + + // The writers ran in their fixed order, and the machine picked the stage of the next turn. + Assert.Equal(1, session.State.TurnIndex); + Assert.Equal("greeting", turn.StageAfter); + Assert.False(session.IsComplete); + + // The transcript holds the spoken line alone. A half-finished tool round would otherwise + // leave a conversation with no result behind, and the next turn would send it. + Assert.Equal(2, session.Transcript.Count); + Assert.Equal(ConversationSession.FallbackReply, session.Transcript[^1].Text); } - // The host hears the fallback rather than nothing at all: R2 makes a quiet run an ordinary - // successful one, and the spoken line leaves the seam the same way any reply does. - Assert.Equal([ConversationSession.FallbackReply], updates.Select(update => update.Text)); - Assert.NotNull(session.LastTurn); - Assert.Equal(ConversationSession.FallbackReply, session.LastTurn.ReplyText); - Assert.Equal(ConversationSession.EmptyReplyReason, session.LastTurn.Failure); - Assert.Equal("close", session.Stage); - } + [Fact] + public async Task ARealDeclaredToolThatCannotReachItsEndpoint_EndsTheTurnPerRowSixAndKeepsTheConversation() + { + // The same row, reached the way a shipped tool actually reaches it. ThrowingToolBuilder + // throws straight at the framework; this goes through DeclaredTool, so the classification + // AuditingFunctionInvokingChatClient applies is what lets the fault out. Before the split + // every fault became a result and this budget could never fire at all. + using LoopingToolCallingChatClient reply = new(); + using SequencedChatClient fill = new(StayingNull); + UnreachableEndpointToolBuilder tools = new(); + ConversationSession session = Build(ToolYaml, reply, fill, tools.Create).Create(); + + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // MaximumConsecutiveErrorsPerRequest is 3, so the 4th failure throws out of the run. + Assert.Equal(4, tools.Calls); + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.NotNull(turn.Failure); + Assert.StartsWith(ConversationSession.ToolFailureReason, turn.Failure, StringComparison.Ordinal); + Assert.Contains(UnreachableEndpointToolBuilder.Message, turn.Failure, StringComparison.Ordinal); + + // The writers ran in their fixed order, the machine picked the stage of the next turn, and + // the conversation is still alive. + Assert.Equal(1, session.State.TurnIndex); + Assert.Equal("greeting", turn.StageAfter); + Assert.False(session.IsComplete); + } - // ------------------------------------------------------------------------------------------- - // Section 8.7, sixth row: the 4th consecutive tool failure. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheFourthConsecutiveToolFailure_EndsTheTurnAndNeverKillsTheConversation() - { - using LoopingToolCallingChatClient reply = new(); - using SequencedChatClient fill = new(StayingNull); - ThrowingToolBuilder tools = new(); - var session = Build(ToolYaml, reply, fill, tools.Create).Create(); - - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // MaximumConsecutiveErrorsPerRequest is 3, so the 4th failure throws out of the run. - Assert.Equal(4, tools.Calls); - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.NotNull(turn.Failure); - Assert.StartsWith(ConversationSession.ToolFailureReason, turn.Failure, StringComparison.Ordinal); - Assert.Contains(ThrowingToolBuilder.Message, turn.Failure, StringComparison.Ordinal); - - // The writers ran in their fixed order, and the machine picked the stage of the next turn. - Assert.Equal(1, session.State.TurnIndex); - Assert.Equal("greeting", turn.StageAfter); - Assert.False(session.IsComplete); - - // The transcript holds the spoken line alone. A half-finished tool round would otherwise - // leave a conversation with no result behind, and the next turn would send it. - Assert.Equal(2, session.Transcript.Count); - Assert.Equal(ConversationSession.FallbackReply, session.Transcript[^1].Text); - } + [Fact] + public async Task ARealDeclaredToolWhoseFaultTheModelCanAnswer_CompletesTheTurnNormally() + { + // The half that must not regress. The tool answers with an error result, the model reads it, + // and nothing about the turn is a failure: no budget spent, no fallback, a real reply. + using ToolCallingChatClient reply = new("That order is already closed."); + using SequencedChatClient fill = new(StayingNull); + RefusedRequestToolBuilder tools = new(); + ConversationSession session = Build(ToolYaml, reply, fill, tools.Create).Create(); + + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + Assert.Equal(1, tools.Calls); + Assert.Null(turn.Failure); + Assert.Equal("That order is already closed.", turn.ReplyText); + Assert.False(session.IsComplete); + } - [Fact] - public async Task ARealDeclaredToolThatCannotReachItsEndpoint_EndsTheTurnPerRowSixAndKeepsTheConversation() - { - // The same row, reached the way a shipped tool actually reaches it. ThrowingToolBuilder - // throws straight at the framework; this goes through DeclaredTool, so the classification - // AuditingFunctionInvokingChatClient applies is what lets the fault out. Before the split - // every fault became a result and this budget could never fire at all. - using LoopingToolCallingChatClient reply = new(); - using SequencedChatClient fill = new(StayingNull); - UnreachableEndpointToolBuilder tools = new(); - var session = Build(ToolYaml, reply, fill, tools.Create).Create(); - - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // MaximumConsecutiveErrorsPerRequest is 3, so the 4th failure throws out of the run. - Assert.Equal(4, tools.Calls); - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.NotNull(turn.Failure); - Assert.StartsWith(ConversationSession.ToolFailureReason, turn.Failure, StringComparison.Ordinal); - Assert.Contains(UnreachableEndpointToolBuilder.Message, turn.Failure, StringComparison.Ordinal); - - // The writers ran in their fixed order, the machine picked the stage of the next turn, and - // the conversation is still alive. - Assert.Equal(1, session.State.TurnIndex); - Assert.Equal("greeting", turn.StageAfter); - Assert.False(session.IsComplete); - } + [Fact] + public async Task TheFourthConsecutiveToolFailure_LeavesTheSessionUnlocked() + { + using LoopingToolCallingChatClient reply = new(); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(ToolYaml, reply, fill, new ThrowingToolBuilder().Create).Create(); - [Fact] - public async Task ARealDeclaredToolWhoseFaultTheModelCanAnswer_CompletesTheTurnNormally() - { - // The half that must not regress. The tool answers with an error result, the model reads it, - // and nothing about the turn is a failure: no budget spent, no fallback, a real reply. - using ToolCallingChatClient reply = new("That order is already closed."); - using SequencedChatClient fill = new(StayingNull); - RefusedRequestToolBuilder tools = new(); - var session = Build(ToolYaml, reply, fill, tools.Create).Create(); - - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - Assert.Equal(1, tools.Calls); - Assert.Null(turn.Failure); - Assert.Equal("That order is already closed.", turn.ReplyText); - Assert.False(session.IsComplete); - } + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - [Fact] - public async Task TheFourthConsecutiveToolFailure_LeavesTheSessionUnlocked() - { - using LoopingToolCallingChatClient reply = new(); - using SequencedChatClient fill = new(StayingNull); - var session = Build(ToolYaml, reply, fill, new ThrowingToolBuilder().Create).Create(); + // The _running flag went back to zero, so the next turn starts rather than throwing. + TurnResult second = await session.RunTurnAsync("try again", TestContext.Current.CancellationToken); - await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + Assert.Equal(1, second.TurnIndex); + Assert.Equal(ConversationSession.FallbackReply, second.ReplyText); + } - // The _running flag went back to zero, so the next turn starts rather than throwing. - var second = await session.RunTurnAsync("try again", TestContext.Current.CancellationToken); + [Fact] + public async Task Streaming_EndsTheTurnWhenTheFourthConsecutiveToolFailureThrows() + { + using LoopingToolCallingChatClient reply = new(); + using SequencedChatClient fill = new(StayingNull); + ThrowingToolBuilder tools = new(); + ConversationSession session = Build(ToolYaml, reply, fill, tools.Create).Create(); + + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync( + "where is my order", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } - Assert.Equal(1, second.TurnIndex); - Assert.Equal(ConversationSession.FallbackReply, second.ReplyText); - } + // The enumeration ends rather than throwing, so the host never sees the fault. + Assert.Equal(4, tools.Calls); + Assert.NotNull(session.LastTurn); + Assert.Equal(ConversationSession.FallbackReply, session.LastTurn.ReplyText); + Assert.StartsWith(ConversationSession.ToolFailureReason, session.LastTurn.Failure!, StringComparison.Ordinal); + Assert.Equal(1, session.State.TurnIndex); + } - [Fact] - public async Task Streaming_EndsTheTurnWhenTheFourthConsecutiveToolFailureThrows() - { - using LoopingToolCallingChatClient reply = new(); - using SequencedChatClient fill = new(StayingNull); - ThrowingToolBuilder tools = new(); - var session = Build(ToolYaml, reply, fill, tools.Create).Create(); - - List updates = []; - await foreach (var update in session.RunTurnStreamingAsync( - "where is my order", TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // Item 6a: barge-in. The record holds what the caller heard. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AnInterruption_RecordsTheHeardTextAndTheDurationTheRelayReported() { - updates.Add(update); - } + using ScriptedChatClient reply = new("I can help with that,", " and here is the long part.") + { + GateAfterFirstFragment = true, + }; + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - // The enumeration ends rather than throwing, so the host never sees the fault. - Assert.Equal(4, tools.Calls); - Assert.NotNull(session.LastTurn); - Assert.Equal(ConversationSession.FallbackReply, session.LastTurn.ReplyText); - Assert.StartsWith(ConversationSession.ToolFailureReason, session.LastTurn.Failure!, StringComparison.Ordinal); - Assert.Equal(1, session.State.TurnIndex); - } + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // Item 6a: barge-in. The record holds what the caller heard. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AnInterruption_RecordsTheHeardTextAndTheDurationTheRelayReported() - { - using ScriptedChatClient reply = new("I can help with that,", " and here is the long part.") - { - GateAfterFirstFragment = true, - }; - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); - - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); - - await using var updates = session.RunTurnStreamingAsync("hi", linked.Token).GetAsyncEnumerator(linked.Token); - Assert.True(await updates.MoveNextAsync()); - Assert.Equal("I can help with that,", updates.Current.Text); - - // Section 7.1 reports both values on the interrupt frame, at 1 ms. Nothing estimates either. - Assert.True(session.Interrupt("I can help", TimeSpan.FromMilliseconds(740))); - Assert.False(await updates.MoveNextAsync()); - - Assert.NotNull(session.LastTurn); - Assert.Equal("I can help", session.LastTurn.ReplyText); - Assert.Equal(TimeSpan.FromMilliseconds(740), session.LastTurn.InterruptedAfter); - Assert.Null(session.LastTurn.Failure); - - // The transcript holds the text the caller heard, not the text the model produced. - Assert.Equal("I can help", session.Transcript[^1].Text); - Assert.DoesNotContain(session.Transcript, message => Contains(message, "long part")); - } + await using IAsyncEnumerator updates = session.RunTurnStreamingAsync("hi", linked.Token).GetAsyncEnumerator(linked.Token); + Assert.True(await updates.MoveNextAsync()); + Assert.Equal("I can help with that,", updates.Current.Text); - [Fact] - public async Task AnInterruption_RunsEveryWriterAndLeavesTheSessionReady() - { - using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + // Section 7.1 reports both values on the interrupt frame, at 1 ms. Nothing estimates either. + Assert.True(session.Interrupt("I can help", TimeSpan.FromMilliseconds(740))); + Assert.False(await updates.MoveNextAsync()); - using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); - using var linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); + Assert.NotNull(session.LastTurn); + Assert.Equal("I can help", session.LastTurn.ReplyText); + Assert.Equal(TimeSpan.FromMilliseconds(740), session.LastTurn.InterruptedAfter); + Assert.Null(session.LastTurn.Failure); - await using (var updates = session.RunTurnStreamingAsync("hi", linked.Token).GetAsyncEnumerator(linked.Token)) + // The transcript holds the text the caller heard, not the text the model produced. + Assert.Equal("I can help", session.Transcript[^1].Text); + Assert.DoesNotContain(session.Transcript, message => Contains(message, "long part")); + } + + [Fact] + public async Task AnInterruption_RunsEveryWriterAndLeavesTheSessionReady() { - Assert.True(await updates.MoveNextAsync()); - Assert.True(session.Interrupt("hel", TimeSpan.FromMilliseconds(120))); + using ScriptedChatClient reply = new("hello", " there.") { GateAfterFirstFragment = true }; + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - while (await updates.MoveNextAsync()) + using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30)); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); + + await using (IAsyncEnumerator updates = session.RunTurnStreamingAsync("hi", linked.Token).GetAsyncEnumerator(linked.Token)) { - // The stream ends on the interruption, so nothing arrives here. - } - } + Assert.True(await updates.MoveNextAsync()); + Assert.True(session.Interrupt("hel", TimeSpan.FromMilliseconds(120))); - // The writers ran in their fixed order, and the counter read the stage the turn spoke in. - Assert.Equal(1, session.State.TurnIndex); - Assert.Equal(1, session.State.Read("greetingTurns")!.GetValue()); - Assert.Equal("greeting", session.Stage); + while (await updates.MoveNextAsync()) + { + // The stream ends on the interruption, so nothing arrives here. + } + } - // The session is not locked, so the caller who interrupted can speak next. - reply.OpenGate(); - var next = await session.RunTurnAsync("go on", linked.Token); - Assert.Equal(1, next.TurnIndex); - Assert.Null(next.InterruptedAfter); - } + // The writers ran in their fixed order, and the counter read the stage the turn spoke in. + Assert.Equal(1, session.State.TurnIndex); + Assert.Equal(1, session.State.Read("greetingTurns")!.GetValue()); + Assert.Equal("greeting", session.Stage); - [Fact] - public async Task AnInterruption_NeverCutsATurnThatDoesNotStream() - { - // One audibility rule for both run shapes, decided by the owner on 2026-08-18: a run that - // has handed the host nothing cannot be the turn the caller was hearing. A turn that does - // not stream hands the host nothing until it returns, so a barge-in during it amends the - // turn that finished last — the caller was still hearing THAT reply — and the running turn - // finishes undisturbed. It used to be the other way: the frame cut the running turn and - // recorded heard text of a reply no host had ever received. - using ScriptedChatClient reply = new("hello", " there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); - - var first = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - Assert.Equal("hello there.", first.ReplyText); - - // The second turn parks inside its model call, so the frame lands while it runs. - reply.GateAfterFirstFragment = true; - var running = session.RunTurnAsync("go on", TestContext.Current.CancellationToken); - Assert.True(session.Interrupt("hello", TimeSpan.FromMilliseconds(90))); - - // The frame amended the FIRST turn — the only reply the caller could have been hearing — - // and the record is readable before the second turn even finishes. - var amended = session.LastTurn; - Assert.NotNull(amended); - Assert.Equal(0, amended.TurnIndex); - Assert.Equal("hello", amended.ReplyText); - Assert.Equal(TimeSpan.FromMilliseconds(90), amended.InterruptedAfter); - - reply.OpenGate(); - var second = await running; - - // The running turn was never cut: it spoke its whole reply, uninterrupted. - Assert.Equal("hello there.", second.ReplyText); - Assert.Null(second.InterruptedAfter); - Assert.Null(second.Failure); - Assert.Equal(2, session.State.TurnIndex); - } + // The session is not locked, so the caller who interrupted can speak next. + reply.OpenGate(); + TurnResult next = await session.RunTurnAsync("go on", linked.Token); + Assert.Equal(1, next.TurnIndex); + Assert.Null(next.InterruptedAfter); + } - [Fact] - public void AnInterruptionWithNoRunningTurn_ReportsFalseAndChangesNothing() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(PolicyYaml, reply, fill).Create(); + [Fact] + public async Task AnInterruption_NeverCutsATurnThatDoesNotStream() + { + // One audibility rule for both run shapes, decided by the owner on 2026-08-18: a run that + // has handed the host nothing cannot be the turn the caller was hearing. A turn that does + // not stream hands the host nothing until it returns, so a barge-in during it amends the + // turn that finished last — the caller was still hearing THAT reply — and the running turn + // finishes undisturbed. It used to be the other way: the frame cut the running turn and + // recorded heard text of a reply no host had ever received. + using ScriptedChatClient reply = new("hello", " there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); + + TurnResult first = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + Assert.Equal("hello there.", first.ReplyText); + + // The second turn parks inside its model call, so the frame lands while it runs. + reply.GateAfterFirstFragment = true; + Task running = session.RunTurnAsync("go on", TestContext.Current.CancellationToken); + Assert.True(session.Interrupt("hello", TimeSpan.FromMilliseconds(90))); + + // The frame amended the FIRST turn — the only reply the caller could have been hearing — + // and the record is readable before the second turn even finishes. + TurnResult? amended = session.LastTurn; + Assert.NotNull(amended); + Assert.Equal(0, amended.TurnIndex); + Assert.Equal("hello", amended.ReplyText); + Assert.Equal(TimeSpan.FromMilliseconds(90), amended.InterruptedAfter); + + reply.OpenGate(); + TurnResult second = await running; + + // The running turn was never cut: it spoke its whole reply, uninterrupted. + Assert.Equal("hello there.", second.ReplyText); + Assert.Null(second.InterruptedAfter); + Assert.Null(second.Failure); + Assert.Equal(2, session.State.TurnIndex); + } - // A frame that arrives after the turn ended must not drop the conversation, so it answers false. - Assert.False(session.Interrupt("nothing played", TimeSpan.FromMilliseconds(5))); + [Fact] + public void AnInterruptionWithNoRunningTurn_ReportsFalseAndChangesNothing() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(PolicyYaml, reply, fill).Create(); - Assert.Null(session.LastTurn); - Assert.Equal(0, session.State.TurnIndex); - Assert.Empty(session.Transcript); - } + // A frame that arrives after the turn ended must not drop the conversation, so it answers false. + Assert.False(session.Interrupt("nothing played", TimeSpan.FromMilliseconds(5))); - // ------------------------------------------------------------------------------------------- - // Section 8.6: the update stream carries content only. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Streaming_DropsEveryUpdateThatCarriesNoContent() - { - using LifecycleChatClient reply = new("hello", " there."); - var session = Build(TwoStagesYaml, reply, null).Create(); + Assert.Null(session.LastTurn); + Assert.Equal(0, session.State.TurnIndex); + Assert.Empty(session.Transcript); + } - List updates = []; - await foreach (var update in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // Section 8.6: the update stream carries content only. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Streaming_DropsEveryUpdateThatCarriesNoContent() { - updates.Add(update); - } + using LifecycleChatClient reply = new("hello", " there."); + ConversationSession session = Build(TwoStagesYaml, reply, null).Create(); - // AsAIAgent() yields 47 updates for 40 text fragments, and seven carry no content. The seam - // filters them once, so no host writes the filter again. - Assert.Equal(6, reply.Yielded); - Assert.Equal(["hello", " there."], updates.Select(update => update.Text).ToArray()); - Assert.NotNull(session.LastTurn); - Assert.Equal("hello there.", session.LastTurn.ReplyText); - } + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } - [Fact] - public async Task Streaming_KeepsTheUpdateThatCarriesAToolCall() - { - using ToolCallingChatClient reply = new("your order is on the way."); - using SequencedChatClient fill = new(StayingNull); - var session = Build(ToolYaml, reply, fill, new StubToolBuilder("""{ "status": "shipped" }""").Create).Create(); + // AsAIAgent() yields 47 updates for 40 text fragments, and seven carry no content. The seam + // filters them once, so no host writes the filter again. + Assert.Equal(6, reply.Yielded); + Assert.Equal(["hello", " there."], [.. updates.Select(update => update.Text)]); + Assert.NotNull(session.LastTurn); + Assert.Equal("hello there.", session.LastTurn.ReplyText); + } - List updates = []; - await foreach (var update in session.RunTurnStreamingAsync( - "where is my order", TestContext.Current.CancellationToken)) + [Fact] + public async Task Streaming_KeepsTheUpdateThatCarriesAToolCall() { - updates.Add(update); + using ToolCallingChatClient reply = new("your order is on the way."); + using SequencedChatClient fill = new(StayingNull); + ConversationSession session = Build(ToolYaml, reply, fill, new StubToolBuilder(/*lang=json,strict*/ """{ "status": "shipped" }""").Create).Create(); + + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync( + "where is my order", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } + + // A tool call and a tool result are content a host may show, so the filter keeps them. + Assert.Contains(updates, update => update.Contents.OfType().Any()); + Assert.Contains(updates, update => update.Text.Length > 0); + Assert.DoesNotContain(updates, update => update.Contents.Count == 0); } - // A tool call and a tool result are content a host may show, so the filter keeps them. - Assert.Contains(updates, update => update.Contents.OfType().Any()); - Assert.Contains(updates, update => update.Text.Length > 0); - Assert.DoesNotContain(updates, update => update.Contents.Count == 0); - } + // ------------------------------------------------------------------------------------------- + // D4: the inbound port. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheSession_SatisfiesTheInboundPort() + { + using SequencedChatClient reply = new("hello there.", "still here."); + using SequencedChatClient fill = new(StayingNull); + IConversationPort port = Assert.IsType(Build(PolicyYaml, reply, fill).Create("conversation-9"), exactMatch: false); - // ------------------------------------------------------------------------------------------- - // D4: the inbound port. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheSession_SatisfiesTheInboundPort() - { - using SequencedChatClient reply = new("hello there.", "still here."); - using SequencedChatClient fill = new(StayingNull); - var port = Assert.IsType(Build(PolicyYaml, reply, fill).Create("conversation-9"), exactMatch: false); + TurnResult turn = await port.RunTurnAsync("hi", TestContext.Current.CancellationToken); - var turn = await port.RunTurnAsync("hi", TestContext.Current.CancellationToken); + // The relay shim and the SSE endpoint both drive this contract and reach past it for nothing. + Assert.Equal("conversation-9", port.ConversationId); + Assert.Equal("greeting", port.Stage); + Assert.False(port.IsComplete); + Assert.Same(turn, port.LastTurn); - // The relay shim and the SSE endpoint both drive this contract and reach past it for nothing. - Assert.Equal("conversation-9", port.ConversationId); - Assert.Equal("greeting", port.Stage); - Assert.False(port.IsComplete); - Assert.Same(turn, port.LastTurn); + // A frame that lands after the turn ended is recorded, not ignored. The vendor paces the + // audio, so the caller was still hearing this reply long after the model stopped producing + // it, and the port amends the finished turn. See the remarks on ConversationSession.Interrupt. + Assert.True(port.Interrupt("nothing played", TimeSpan.Zero)); - // A frame that lands after the turn ended is recorded, not ignored. The vendor paces the - // audio, so the caller was still hearing this reply long after the model stopped producing - // it, and the port amends the finished turn. See the remarks on ConversationSession.Interrupt. - Assert.True(port.Interrupt("nothing played", TimeSpan.Zero)); + List updates = []; + await foreach (ChatResponseUpdate update in port.RunTurnStreamingAsync("still there?", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } - List updates = []; - await foreach (var update in port.RunTurnStreamingAsync("still there?", TestContext.Current.CancellationToken)) - { - updates.Add(update); + Assert.Equal("still here.", string.Concat(updates.Select(update => update.Text))); } - Assert.Equal("still here.", string.Concat(updates.Select(update => update.Text))); - } - - // ------------------------------------------------------------------------------------------- - // The factory. - // ------------------------------------------------------------------------------------------- - [Fact] - public void TheFactory_MakesAConversationIdWhenTheHostGivesNone() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var factory = Build(PolicyYaml, reply, fill); + // ------------------------------------------------------------------------------------------- + // The factory. + // ------------------------------------------------------------------------------------------- + [Fact] + public void TheFactory_MakesAConversationIdWhenTheHostGivesNone() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + ConversationSessionFactory factory = Build(PolicyYaml, reply, fill); - var first = factory.Create(); - var second = factory.Create(); + ConversationSession first = factory.Create(); + ConversationSession second = factory.Create(); - Assert.NotEmpty(first.ConversationId); - Assert.NotEqual(first.ConversationId, second.ConversationId); - } + Assert.NotEmpty(first.ConversationId); + Assert.NotEqual(first.ConversationId, second.ConversationId); + } - [Fact] - public async Task TheFactory_GivesEachConversationItsOwnStateAndItsOwnMachine() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(SaidGoodbye, StayingNull); - var factory = Build(PolicyYaml, reply, fill); + [Fact] + public async Task TheFactory_GivesEachConversationItsOwnStateAndItsOwnMachine() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(SaidGoodbye, StayingNull); + ConversationSessionFactory factory = Build(PolicyYaml, reply, fill); - var first = factory.Create("conversation-1"); - var second = factory.Create("conversation-2"); + ConversationSession first = factory.Create("conversation-1"); + ConversationSession second = factory.Create("conversation-2"); - await first.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); + _ = await first.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); - // One machine belongs to one conversation. The first conversation ended, and the second one has not started. - Assert.True(first.IsComplete); - Assert.False(second.IsComplete); - Assert.Equal("greeting", second.Stage); - Assert.Empty(second.Transcript); - Assert.NotSame(first.State, second.State); + // One machine belongs to one conversation. The first conversation ended, and the second one has not started. + Assert.True(first.IsComplete); + Assert.False(second.IsComplete); + Assert.Equal("greeting", second.Stage); + Assert.Empty(second.Transcript); + Assert.NotSame(first.State, second.State); - // Both conversations share the one compiled agent. T44 and rule 16. - Assert.Same(first.Compiled, second.Compiled); - } + // Both conversations share the one compiled agent. T44 and rule 16. + Assert.Same(first.Compiled, second.Compiled); + } - [Fact] - public void TheFactory_BuildsNoExtractorWhenTheDocumentDeclaresNone() - { - using SequencedChatClient reply = new("hello there."); - var compiled = Compile(TwoStagesYaml, reply, null, null); + [Fact] + public void TheFactory_BuildsNoExtractorWhenTheDocumentDeclaresNone() + { + using SequencedChatClient reply = new("hello there."); + CompiledAgent compiled = Compile(TwoStagesYaml, reply, null, null); - Assert.Null(ConversationSessionFactory.CreateExtractor(compiled, new FakeChatClientFactory(reply))); - } + Assert.Null(ConversationSessionFactory.CreateExtractor(compiled, new FakeChatClientFactory(reply))); + } - [Fact] - public void TheFactory_BuildsTheExtractorTheDocumentDeclares() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new(StayingNull); - var compiled = Compile(PolicyYaml, reply, fill, null); + [Fact] + public void TheFactory_BuildsTheExtractorTheDocumentDeclares() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(StayingNull); + CompiledAgent compiled = Compile(PolicyYaml, reply, fill, null); - var extractor = ConversationSessionFactory.CreateExtractor( - compiled, - new RoutingChatClientFactory(reply).Route("fill", fill)); + StateExtractor? extractor = ConversationSessionFactory.CreateExtractor( + compiled, + new RoutingChatClientFactory(reply).Route("fill", fill)); - Assert.NotNull(extractor); - Assert.Equal(["callerSaidGoodbye"], extractor.SlotNames); - } + Assert.NotNull(extractor); + Assert.Equal(["callerSaidGoodbye"], extractor.SlotNames); + } - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - private static bool Contains(ChatMessage message, string text) - => message.Text.Contains(text, StringComparison.Ordinal); - - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IChatClient? fill, - Func? tools = null, - TimeProvider? timeProvider = null) - { - var compiled = Compile(yaml, reply, fill, tools); - var chatClients = new RoutingChatClientFactory(reply); - if (fill is not null) + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + private static bool Contains(ChatMessage message, string text) { - chatClients.Route("fill", fill); + return message.Text.Contains(text, StringComparison.Ordinal); } - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - timeProvider); - } - - private static CompiledAgent Compile(string yaml, IChatClient reply, IChatClient? fill, Func? tools) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new RoutingChatClientFactory(reply); - if (fill is not null) + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IChatClient? fill, + Func? tools = null, + TimeProvider? timeProvider = null) { - chatClients.Route("fill", fill); + CompiledAgent compiled = Compile(yaml, reply, fill, tools); + RoutingChatClientFactory chatClients = new(reply); + if (fill is not null) + { + _ = chatClients.Route("fill", fill); + } + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + timeProvider); } - return ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) + private static CompiledAgent Compile(string yaml, IChatClient reply, IChatClient? fill, Func? tools) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + if (fill is not null) { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; + _ = chatClients.Route("fill", fill); + } + + return ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionWorkspaceTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionWorkspaceTests.cs index 5cb1516a..de37dec5 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionWorkspaceTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionWorkspaceTests.cs @@ -10,20 +10,22 @@ using AgentCore.Domain.Audit; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The conversation workspace as a host sees it: bound (or not) through , -/// deleted when the conversation ends, and visible to a bound tool through . -/// -/// -/// Every test here runs offline. There is no network conversation and no API key anywhere in this file. -/// -public sealed class ConversationSessionWorkspaceTests : IDisposable +namespace AgentCore.Application.Tests.Runtime { - private const string SimpleYaml = - """ + /// + /// The conversation workspace as a host sees it: bound (or not) through , + /// deleted when the conversation ends, and visible to a bound tool through . + /// + /// + /// Every test here runs offline. There is no network conversation and no API key anywhere in this file. + /// + public sealed class ConversationSessionWorkspaceTests : IDisposable + { + private const string SimpleYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -33,8 +35,8 @@ public sealed class ConversationSessionWorkspaceTests : IDisposable agent: only """; - private const string TerminalYaml = - """ + private const string TerminalYaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: @@ -66,8 +68,8 @@ public sealed class ConversationSessionWorkspaceTests : IDisposable terminal: true """; - private const string ScopeYaml = - """ + private const string ScopeYaml = + """ apiVersion: agentcore/v1 tools: - { id: request_human, kind: binding, binds: RequestHuman, description: "Ask a human to take the conversation." } @@ -79,129 +81,130 @@ public sealed class ConversationSessionWorkspaceTests : IDisposable agent: only """; - private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-ws-" + Guid.NewGuid().ToString("N")); + private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-ws-" + Guid.NewGuid().ToString("N")); - public void Dispose() - { - if (Directory.Exists(_root)) + public void Dispose() { - Directory.Delete(_root, recursive: true); + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } } - } - - [Fact] - public void ARootBound_CreatesTheConversationsFolder() - { - using SequencedChatClient reply = new("hi there."); - var factory = Build(SimpleYaml, reply, fill: null, _root); - var session = factory.Create("conversation-1"); + [Fact] + public void ARootBound_CreatesTheConversationsFolder() + { + using SequencedChatClient reply = new("hi there."); + ConversationSessionFactory factory = Build(SimpleYaml, reply, fill: null, _root); - Assert.Equal(Path.Combine(_root, "conversation-1"), session.Workspace); - Assert.True(Directory.Exists(session.Workspace)); - } + ConversationSession session = factory.Create("conversation-1"); - [Fact] - public void NoRootBound_LeavesWorkspaceNull_AndCreatesNothing() - { - using SequencedChatClient reply = new("hi there."); - var factory = Build(SimpleYaml, reply, fill: null, workspaceRoot: null); + Assert.Equal(Path.Combine(_root, "conversation-1"), session.Workspace); + Assert.True(Directory.Exists(session.Workspace)); + } - var session = factory.Create("conversation-1"); + [Fact] + public void NoRootBound_LeavesWorkspaceNull_AndCreatesNothing() + { + using SequencedChatClient reply = new("hi there."); + ConversationSessionFactory factory = Build(SimpleYaml, reply, fill: null, workspaceRoot: null); - Assert.Null(session.Workspace); - Assert.False(Directory.Exists(_root)); - } + ConversationSession session = factory.Create("conversation-1"); - [Fact] - public void EndConversation_DeletesTheFolder_AndIsSafeToCallTwice() - { - using SequencedChatClient reply = new("hi there."); - var factory = Build(SimpleYaml, reply, fill: null, _root); - var session = factory.Create("conversation-1"); - var path = session.Workspace!; + Assert.Null(session.Workspace); + Assert.False(Directory.Exists(_root)); + } - session.EndConversation(ConversationEndReason.CallerHungUp); + [Fact] + public void EndConversation_DeletesTheFolder_AndIsSafeToCallTwice() + { + using SequencedChatClient reply = new("hi there."); + ConversationSessionFactory factory = Build(SimpleYaml, reply, fill: null, _root); + ConversationSession session = factory.Create("conversation-1"); + string path = session.Workspace!; - Assert.False(Directory.Exists(path)); - Assert.False(session.EndConversation(ConversationEndReason.CallerHungUp)); - } + _ = session.EndConversation(ConversationEndReason.CallerHungUp); - [Fact] - public async Task ATurnThatReachesATerminalStage_AlsoDeletesTheFolder() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient fill = new("""{ "callerSaidGoodbye": true }"""); - var factory = Build(TerminalYaml, reply, fill, _root); - var session = factory.Create("conversation-1"); - var path = session.Workspace!; + Assert.False(Directory.Exists(path)); + Assert.False(session.EndConversation(ConversationEndReason.CallerHungUp)); + } - var turn = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); + [Fact] + public async Task ATurnThatReachesATerminalStage_AlsoDeletesTheFolder() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient fill = new(/*lang=json,strict*/ """{ "callerSaidGoodbye": true }"""); + ConversationSessionFactory factory = Build(TerminalYaml, reply, fill, _root); + ConversationSession session = factory.Create("conversation-1"); + string path = session.Workspace!; - Assert.True(turn.IsTerminal); - Assert.True(session.IsComplete); - Assert.False(Directory.Exists(path)); - } + TurnResult turn = await session.RunTurnAsync("goodbye", TestContext.Current.CancellationToken); - [Fact] - public async Task ABoundTool_SeesTheRunningConversationsWorkspace() - { - List captured = []; - ToolBindingRegistry bindings = new(); - bindings.Register("RequestHuman", (string reason, ToolCallScope scope) => captured.Add(scope)); - - var document = ConfigurationLoader.LoadYaml(ScopeYaml); - var chatClients = new RoutingChatClientFactory( - new ToolCallingChatClient( - "connecting you now.", - new Dictionary(StringComparer.Ordinal) { ["reason"] = "the caller wants a person" })); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - Tools = await ToolRegistryBuilder.BuildAsync( - [new BindingToolSource(bindings)], - new ToolSourceContext(document), - TestContext.Current.CancellationToken), - })["main"]; - - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - workspaceRoot: _root); - var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("I need a person", TestContext.Current.CancellationToken); - - var scope = Assert.Single(captured); - Assert.Equal(session.Workspace, scope.Workspace); - Assert.NotNull(scope.Workspace); - } + Assert.True(turn.IsTerminal); + Assert.True(session.IsComplete); + Assert.False(Directory.Exists(path)); + } - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IChatClient? fill, - string? workspaceRoot) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new RoutingChatClientFactory(reply); - if (fill is not null) + [Fact] + public async Task ABoundTool_SeesTheRunningConversationsWorkspace() { - chatClients.Route("fill", fill); + List captured = []; + ToolBindingRegistry bindings = new(); + _ = bindings.Register("RequestHuman", (string reason, ToolCallScope scope) => captured.Add(scope)); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ScopeYaml); + RoutingChatClientFactory chatClients = new( + new ToolCallingChatClient( + "connecting you now.", + new Dictionary(StringComparer.Ordinal) { ["reason"] = "the caller wants a person" })); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = await ToolRegistryBuilder.BuildAsync( + [new BindingToolSource(bindings)], + new ToolSourceContext(document), + TestContext.Current.CancellationToken), + })["main"]; + + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + workspaceRoot: _root); + ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("I need a person", TestContext.Current.CancellationToken); + + ToolCallScope scope = Assert.Single(captured); + Assert.Equal(session.Workspace, scope.Workspace); + Assert.NotNull(scope.Workspace); } - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IChatClient? fill, + string? workspaceRoot) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + if (fill is not null) { - Tools = TestToolRegistry.From(document, builder: null, TestContext.Current.CancellationToken), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - workspaceRoot: workspaceRoot); + _ = chatClients.Route("fill", fill); + } + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, builder: null, TestContext.Current.CancellationToken), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + workspaceRoot: workspaceRoot); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationWorkspaceTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationWorkspaceTests.cs index fa451a33..98118741 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationWorkspaceTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationWorkspaceTests.cs @@ -1,93 +1,94 @@ using AgentCore.Application.Runtime; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// in isolation: the folder it creates and the folder it deletes. -/// -public sealed class ConversationWorkspaceTests : IDisposable +namespace AgentCore.Application.Tests.Runtime { - private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-ws-" + Guid.NewGuid().ToString("N")); - - public void Dispose() + /// + /// in isolation: the folder it creates and the folder it deletes. + /// + public sealed class ConversationWorkspaceTests : IDisposable { - if (Directory.Exists(_root)) + private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-ws-" + Guid.NewGuid().ToString("N")); + + public void Dispose() { - Directory.Delete(_root, recursive: true); + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } } - } - - [Fact] - public void Create_MakesTheFolder() - { - var workspace = ConversationWorkspace.Create(_root, "conversation-1"); - Assert.Equal(Path.Combine(_root, "conversation-1"), workspace.Path); - Assert.True(Directory.Exists(workspace.Path)); - } + [Fact] + public void Create_MakesTheFolder() + { + ConversationWorkspace workspace = ConversationWorkspace.Create(_root, "conversation-1"); - [Fact] - public void Delete_RemovesTheFolder_AndIsSafeToCallTwice() - { - var workspace = ConversationWorkspace.Create(_root, "conversation-1"); + Assert.Equal(Path.Combine(_root, "conversation-1"), workspace.Path); + Assert.True(Directory.Exists(workspace.Path)); + } - workspace.Delete(logger: null); - Assert.False(Directory.Exists(workspace.Path)); + [Fact] + public void Delete_RemovesTheFolder_AndIsSafeToCallTwice() + { + ConversationWorkspace workspace = ConversationWorkspace.Create(_root, "conversation-1"); - var exception = Record.Exception(() => workspace.Delete(logger: null)); - Assert.Null(exception); - } + workspace.Delete(logger: null); + Assert.False(Directory.Exists(workspace.Path)); - [Theory] - [InlineData("../escape")] - [InlineData("a/b")] - [InlineData(@"a\b")] - [InlineData("..")] - [InlineData(".")] - [InlineData("")] - [InlineData(" ")] - public void Create_RefusesAConversationIdThatCouldEscapeTheRoot(string conversationId) - { - Assert.Throws(() => ConversationWorkspace.Create(_root, conversationId)); - Assert.False(Directory.Exists(_root)); - } + Exception? exception = Record.Exception(() => workspace.Delete(logger: null)); + Assert.Null(exception); + } - /// - /// GetFullPath normalises a trailing space or period out of the last segment on Windows, - /// so a naive containment check would let " ." alias the root and "conversation-1." alias a sibling - /// folder. On Windows this must throw. On Linux the segment is a legal folder name and is not an - /// alias of anything, so it is fine for Create to make it — as long as the folder it makes - /// is strictly under root and named exactly what the caller asked for. - /// - [Theory] - [InlineData(" .")] - [InlineData("conversation-1.")] - public void Create_RefusesOrExactlyHonoursAConversationIdWithATrailingSpaceOrPeriod(string conversationId) - { - if (OperatingSystem.IsWindows()) + [Theory] + [InlineData("../escape")] + [InlineData("a/b")] + [InlineData(@"a\b")] + [InlineData("..")] + [InlineData(".")] + [InlineData("")] + [InlineData(" ")] + public void Create_RefusesAConversationIdThatCouldEscapeTheRoot(string conversationId) { - Assert.ThrowsAny(() => ConversationWorkspace.Create(_root, conversationId)); + _ = Assert.Throws(() => ConversationWorkspace.Create(_root, conversationId)); Assert.False(Directory.Exists(_root)); - return; } - var workspace = ConversationWorkspace.Create(_root, conversationId); + /// + /// GetFullPath normalises a trailing space or period out of the last segment on Windows, + /// so a naive containment check would let " ." alias the root and "conversation-1." alias a sibling + /// folder. On Windows this must throw. On Linux the segment is a legal folder name and is not an + /// alias of anything, so it is fine for Create to make it — as long as the folder it makes + /// is strictly under root and named exactly what the caller asked for. + /// + [Theory] + [InlineData(" .")] + [InlineData("conversation-1.")] + public void Create_RefusesOrExactlyHonoursAConversationIdWithATrailingSpaceOrPeriod(string conversationId) + { + if (OperatingSystem.IsWindows()) + { + _ = Assert.ThrowsAny(() => ConversationWorkspace.Create(_root, conversationId)); + Assert.False(Directory.Exists(_root)); + return; + } - Assert.StartsWith(_root + Path.DirectorySeparatorChar, workspace.Path, StringComparison.Ordinal); - Assert.Equal(conversationId, Path.GetFileName(workspace.Path)); - } + ConversationWorkspace workspace = ConversationWorkspace.Create(_root, conversationId); - [Fact] - public void Create_TwiceWithTheSameConversationId_ReusesTheFolderAndKeepsWhatWasWrittenIntoIt() - { - var first = ConversationWorkspace.Create(_root, "conversation-1"); - var marker = Path.Combine(first.Path, "marker.txt"); - File.WriteAllText(marker, "kept"); + Assert.StartsWith(_root + Path.DirectorySeparatorChar, workspace.Path, StringComparison.Ordinal); + Assert.Equal(conversationId, Path.GetFileName(workspace.Path)); + } - var second = ConversationWorkspace.Create(_root, "conversation-1"); + [Fact] + public void Create_TwiceWithTheSameConversationId_ReusesTheFolderAndKeepsWhatWasWrittenIntoIt() + { + ConversationWorkspace first = ConversationWorkspace.Create(_root, "conversation-1"); + string marker = Path.Combine(first.Path, "marker.txt"); + File.WriteAllText(marker, "kept"); + + ConversationWorkspace second = ConversationWorkspace.Create(_root, "conversation-1"); - Assert.Equal(first.Path, second.Path); - Assert.Equal("kept", File.ReadAllText(marker)); + Assert.Equal(first.Path, second.Path); + Assert.Equal("kept", File.ReadAllText(marker)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/DelegatedToolsTests.cs b/tests/AgentCore.Application.Tests/Runtime/DelegatedToolsTests.cs index c2005a42..a3c390b4 100644 --- a/tests/AgentCore.Application.Tests/Runtime/DelegatedToolsTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/DelegatedToolsTests.cs @@ -7,27 +7,27 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// Tools that belong to one conversation, offered to the runs that call delegates and to nothing else. -/// -/// -/// -/// The compiled agent is a process singleton, so a tool that belongs to one conversation cannot be compiled -/// onto it. It travels on the turn instead, and the gate is the id of the delegating tool the run -/// sits under. A gate on the agent NAME would be wrong: CompiledAgentRegistry makes compiled -/// agents singletons, so two kind: agent declarations can name one agent and both would be -/// handed the tool. -/// -/// -/// Every test here runs offline: no network conversation and no API key. -/// -/// -public sealed class DelegatedToolsTests +namespace AgentCore.Application.Tests.Runtime { - private const string DelegationYaml = - """ + /// + /// Tools that belong to one conversation, offered to the runs that call delegates and to nothing else. + /// + /// + /// + /// The compiled agent is a process singleton, so a tool that belongs to one conversation cannot be compiled + /// onto it. It travels on the turn instead, and the gate is the id of the delegating tool the run + /// sits under. A gate on the agent NAME would be wrong: CompiledAgentRegistry makes compiled + /// agents singletons, so two kind: agent declarations can name one agent and both would be + /// handed the tool. + /// + /// + /// Every test here runs offline: no network conversation and no API key. + /// + /// + public sealed class DelegatedToolsTests + { + private const string DelegationYaml = + """ apiVersion: agentcore/v1 tools: - { id: ask_specialist, kind: agent, agent: specialist, description: Ask the specialist. } @@ -45,105 +45,106 @@ public sealed class DelegatedToolsTests - { id: greeting, agent: greeter, terminal: true } """; - private static AIFunction DrawTool { get; } = - AIFunctionFactory.Create(() => "drawn.", "build_ui", "Draw something on the caller's screen."); - - [Fact] - public async Task AToolSetForADelegation_ReachesTheRunThatDelegationMakes() - { - var (session, greeter, specialist) = NewConversation(); - session.SetDelegatedTools("ask_specialist", [DrawTool]); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.Contains("build_ui", specialist.Offered.Select(tool => tool.Name)); - Assert.DoesNotContain("build_ui", greeter.Offered.Select(tool => tool.Name)); - } - - [Fact] - public async Task AToolSetForADelegation_ReachesAStreamingTurnToo() - { - // The framework streams the tool-call update BEFORE it invokes the function, so the first - // yield restores the caller's execution context while the delegation is still pending. Only - // the per-round re-entry in RunTurnStreamingAsync keeps the turn's tools alive across it. - var (session, _, specialist) = NewConversation(); - session.SetDelegatedTools("ask_specialist", [DrawTool]); - - await foreach (var _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) - { - } - - Assert.Contains("build_ui", specialist.Offered.Select(tool => tool.Name)); - } - - [Fact] - public async Task AToolSetForAnotherDelegation_ReachesNobody() - { - var (session, greeter, specialist) = NewConversation(); - session.SetDelegatedTools("some_other_tool", [DrawTool]); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.DoesNotContain("build_ui", specialist.Offered.Select(tool => tool.Name)); - Assert.DoesNotContain("build_ui", greeter.Offered.Select(tool => tool.Name)); - } - - [Fact] - public async Task AConversationThatSetsNoTools_OffersTheSameToolsItAlwaysDid() - { - var (session, _, specialist) = NewConversation(); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.NotEmpty(specialist.Offered.Count > 0 ? specialist.Offered : [DrawTool]); - Assert.DoesNotContain("build_ui", specialist.Offered.Select(tool => tool.Name)); - } - - [Fact] - public async Task TheSecondCallOfSetDelegatedTools_ReplacesTheFirst() - { - var replacement = AIFunctionFactory.Create(() => "drawn.", "draw_later", "The one that wins."); - var (session, _, specialist) = NewConversation(); - - session.SetDelegatedTools("ask_specialist", [DrawTool]); - session.SetDelegatedTools("ask_specialist", [replacement]); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.Contains("draw_later", specialist.Offered.Select(tool => tool.Name)); - Assert.DoesNotContain("build_ui", specialist.Offered.Select(tool => tool.Name)); - } - - [Fact] - public void SetDelegatedTools_RefusesNulls() - { - var (session, _, _) = NewConversation(); - - Assert.Throws(() => session.SetDelegatedTools(null!, [DrawTool])); - Assert.Throws(() => session.SetDelegatedTools("ask_specialist", null!)); - } - - /// Opens a conversation whose greeter delegates once, over two scripted models. - private static (ConversationSession Session, ToolCallingChatClient Greeter, ToolCallingChatClient Specialist) NewConversation() - { - ToolCallingChatClient greeter = new( - "hello there.", - new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); - ToolCallingChatClient specialist = new("the specialist answer"); - - RoutingChatClientFactory chatClients = new(greeter); - chatClients.Route("reply", greeter); - chatClients.Route("specialist", specialist); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(DelegationYaml), new AgentCompilationContext(chatClients))["main"]; - - var session = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null).Create(); - - return (session, greeter, specialist); - } - - } + private static AIFunction DrawTool { get; } = + AIFunctionFactory.Create(() => "drawn.", "build_ui", "Draw something on the caller's screen."); + + [Fact] + public async Task AToolSetForADelegation_ReachesTheRunThatDelegationMakes() + { + (ConversationSession? session, ToolCallingChatClient? greeter, ToolCallingChatClient? specialist) = NewConversation(); + session.SetDelegatedTools("ask_specialist", [DrawTool]); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.Contains("build_ui", specialist.Offered.Select(tool => tool.Name)); + Assert.DoesNotContain("build_ui", greeter.Offered.Select(tool => tool.Name)); + } + + [Fact] + public async Task AToolSetForADelegation_ReachesAStreamingTurnToo() + { + // The framework streams the tool-call update BEFORE it invokes the function, so the first + // yield restores the caller's execution context while the delegation is still pending. Only + // the per-round re-entry in RunTurnStreamingAsync keeps the turn's tools alive across it. + (ConversationSession? session, ToolCallingChatClient _, ToolCallingChatClient? specialist) = NewConversation(); + session.SetDelegatedTools("ask_specialist", [DrawTool]); + + await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + } + + Assert.Contains("build_ui", specialist.Offered.Select(tool => tool.Name)); + } + + [Fact] + public async Task AToolSetForAnotherDelegation_ReachesNobody() + { + (ConversationSession? session, ToolCallingChatClient? greeter, ToolCallingChatClient? specialist) = NewConversation(); + session.SetDelegatedTools("some_other_tool", [DrawTool]); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.DoesNotContain("build_ui", specialist.Offered.Select(tool => tool.Name)); + Assert.DoesNotContain("build_ui", greeter.Offered.Select(tool => tool.Name)); + } + + [Fact] + public async Task AConversationThatSetsNoTools_OffersTheSameToolsItAlwaysDid() + { + (ConversationSession? session, _, ToolCallingChatClient? specialist) = NewConversation(); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.NotEmpty(specialist.Offered.Count > 0 ? specialist.Offered : [DrawTool]); + Assert.DoesNotContain("build_ui", specialist.Offered.Select(tool => tool.Name)); + } + + [Fact] + public async Task TheSecondCallOfSetDelegatedTools_ReplacesTheFirst() + { + AIFunction replacement = AIFunctionFactory.Create(() => "drawn.", "draw_later", "The one that wins."); + (ConversationSession? session, _, ToolCallingChatClient? specialist) = NewConversation(); + + session.SetDelegatedTools("ask_specialist", [DrawTool]); + session.SetDelegatedTools("ask_specialist", [replacement]); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.Contains("draw_later", specialist.Offered.Select(tool => tool.Name)); + Assert.DoesNotContain("build_ui", specialist.Offered.Select(tool => tool.Name)); + } + + [Fact] + public void SetDelegatedTools_RefusesNulls() + { + (ConversationSession? session, _, _) = NewConversation(); + + _ = Assert.Throws(() => session.SetDelegatedTools(null!, [DrawTool])); + _ = Assert.Throws(() => session.SetDelegatedTools("ask_specialist", null!)); + } + + /// Opens a conversation whose greeter delegates once, over two scripted models. + private static (ConversationSession Session, ToolCallingChatClient Greeter, ToolCallingChatClient Specialist) NewConversation() + { + ToolCallingChatClient greeter = new( + "hello there.", + new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); + ToolCallingChatClient specialist = new("the specialist answer"); + + RoutingChatClientFactory chatClients = new(greeter); + _ = chatClients.Route("reply", greeter); + _ = chatClients.Route("specialist", specialist); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(DelegationYaml), new AgentCompilationContext(chatClients))["main"]; + + ConversationSession session = new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null).Create(); + + return (session, greeter, specialist); + } + + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs index 19fa07d2..679afb92 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs @@ -7,110 +7,111 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// A child session created inside the parent's run carries the parent's conversation id; one created -/// outside any run carries nothing. -/// -/// -/// BackgroundAgentsProvider creates the child session from inside the parent's tool call. -/// The test stands in for that with a provider that creates it from inside the parent's -/// InvokingAsync, which is the same run context. -/// -public sealed class BackgroundChildAgentTests +namespace AgentCore.Application.Tests.Runtime.Harness { - [Fact] - public async Task CreateSessionAsync_InsideTheParentsRun_StampsTheParentsConversationId() - { - // Arrange - var token = TestContext.Current.CancellationToken; - BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); - SessionCreatingProvider creating = new(child); - ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); - var turn = new TurnInvocation { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s" }; - - // Act - await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); - - // Assert - Assert.NotNull(creating.Created); - Assert.True(creating.Created.StateBag.TryGetValue(BlobOwnerKey.Value, out var stamped)); - Assert.Equal("conversation-9", stamped); - } - - [Fact] - public async Task CreateSessionAsync_InsideAParentRunWithAZone_StampsTheZoneOnTheChild() + /// + /// A child session created inside the parent's run carries the parent's conversation id; one created + /// outside any run carries nothing. + /// + /// + /// BackgroundAgentsProvider creates the child session from inside the parent's tool call. + /// The test stands in for that with a provider that creates it from inside the parent's + /// InvokingAsync, which is the same run context. + /// + public sealed class BackgroundChildAgentTests { - // Arrange - var token = TestContext.Current.CancellationToken; - BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); - SessionCreatingProvider creating = new(child); - ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); - var zone = TimeZoneInfo.CreateCustomTimeZone("Asia/Taipei", TimeSpan.FromHours(8), "Taipei", "Taipei"); - var turn = new TurnInvocation { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s", TimeZone = zone }; - - // Act - await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); - - // Assert - Assert.NotNull(creating.Created); - Assert.True(creating.Created.StateBag.TryGetValue(CallerTimeZone.Key, out var stamped)); - Assert.Equal("Asia/Taipei", stamped); - } - - [Fact] - public async Task CreateSessionAsync_InsideTheParentsRun_FilesTheParentsWorkspaceOnTheChild() - { - // Arrange - var token = TestContext.Current.CancellationToken; - BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); - SessionCreatingProvider creating = new(child); - ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); - var renders = new TurnRenders(); - var turn = new TurnInvocation + [Fact] + public async Task CreateSessionAsync_InsideTheParentsRun_StampsTheParentsConversationId() { - ConversationId = "conversation-9", - TurnIndex = 0, - Stage = "s", - Workspace = "/work/conversation-9", - Renders = renders, - }; - - // Act - await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); + // Arrange + CancellationToken token = TestContext.Current.CancellationToken; + BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); + SessionCreatingProvider creating = new(child); + ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); + TurnInvocation turn = new() { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s" }; + + // Act + _ = await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); + + // Assert + Assert.NotNull(creating.Created); + Assert.True(creating.Created.StateBag.TryGetValue(BlobOwnerKey.Value, out string? stamped)); + Assert.Equal("conversation-9", stamped); + } - // Assert - Assert.NotNull(creating.Created); - var filed = TurnRegistry.For(creating.Created); - Assert.NotNull(filed); - Assert.Equal("/work/conversation-9", filed.Workspace); - Assert.Equal("conversation-9", filed.ConversationId); - Assert.True(filed.Nested); - Assert.Null(filed.Renders); - } + [Fact] + public async Task CreateSessionAsync_InsideAParentRunWithAZone_StampsTheZoneOnTheChild() + { + // Arrange + CancellationToken token = TestContext.Current.CancellationToken; + BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); + SessionCreatingProvider creating = new(child); + ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); + TimeZoneInfo zone = TimeZoneInfo.CreateCustomTimeZone("Asia/Taipei", TimeSpan.FromHours(8), "Taipei", "Taipei"); + TurnInvocation turn = new() { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s", TimeZone = zone }; + + // Act + _ = await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); + + // Assert + Assert.NotNull(creating.Created); + Assert.True(creating.Created.StateBag.TryGetValue(CallerTimeZone.Key, out string? stamped)); + Assert.Equal("Asia/Taipei", stamped); + } - [Fact] - public async Task CreateSessionAsync_OutsideAnyRun_StampsNothing() - { - // Arrange - BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); + [Fact] + public async Task CreateSessionAsync_InsideTheParentsRun_FilesTheParentsWorkspaceOnTheChild() + { + // Arrange + CancellationToken token = TestContext.Current.CancellationToken; + BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); + SessionCreatingProvider creating = new(child); + ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); + TurnRenders renders = new(); + TurnInvocation turn = new() + { + ConversationId = "conversation-9", + TurnIndex = 0, + Stage = "s", + Workspace = "/work/conversation-9", + Renders = renders, + }; + + // Act + _ = await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); + + // Assert + Assert.NotNull(creating.Created); + TurnInvocation? filed = TurnRegistry.For(creating.Created); + Assert.NotNull(filed); + Assert.Equal("/work/conversation-9", filed.Workspace); + Assert.Equal("conversation-9", filed.ConversationId); + Assert.True(filed.Nested); + Assert.Null(filed.Renders); + } - // Act - var session = await child.CreateSessionAsync(TestContext.Current.CancellationToken); + [Fact] + public async Task CreateSessionAsync_OutsideAnyRun_StampsNothing() + { + // Arrange + BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); - // Assert - Assert.False(session.StateBag.TryGetValue(BlobOwnerKey.Value, out _)); - } + // Act + AgentSession session = await child.CreateSessionAsync(TestContext.Current.CancellationToken); - private sealed class SessionCreatingProvider(AIAgent child) : AIContextProvider - { - public AgentSession? Created { get; private set; } + // Assert + Assert.False(session.StateBag.TryGetValue(BlobOwnerKey.Value, out _)); + } - protected override async ValueTask InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default) + private sealed class SessionCreatingProvider(AIAgent child) : AIContextProvider { - Created = await child.CreateSessionAsync(cancellationToken); - return new AIContext(); + public AgentSession? Created { get; private set; } + + protected override async ValueTask InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default) + { + Created = await child.CreateSessionAsync(cancellationToken); + return new AIContext(); + } } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/CallerTimeZoneTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/CallerTimeZoneTests.cs index 5b65e6fc..c9de9220 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/CallerTimeZoneTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/CallerTimeZoneTests.cs @@ -1,34 +1,35 @@ using AgentCore.Application.Runtime.Harness; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// : an IANA id the system knows becomes a zone; anything else -/// becomes nothing, so a bad header never changes the clock. -/// -public sealed class CallerTimeZoneTests +namespace AgentCore.Application.Tests.Runtime.Harness { - [Theory] - [InlineData("America/Chicago")] - [InlineData(" Asia/Taipei ")] - [InlineData("UTC")] - public void Parse_AKnownId_IsThatZone(string id) + /// + /// : an IANA id the system knows becomes a zone; anything else + /// becomes nothing, so a bad header never changes the clock. + /// + public sealed class CallerTimeZoneTests { - var zone = CallerTimeZone.Parse(id); + [Theory] + [InlineData("America/Chicago")] + [InlineData(" Asia/Taipei ")] + [InlineData("UTC")] + public void Parse_AKnownId_IsThatZone(string id) + { + TimeZoneInfo? zone = CallerTimeZone.Parse(id); - Assert.NotNull(zone); - Assert.Equal(id.Trim(), zone.Id); - } + Assert.NotNull(zone); + Assert.Equal(id.Trim(), zone.Id); + } - [Theory] - [InlineData(null)] - [InlineData("")] - [InlineData(" ")] - [InlineData("Mars/Olympus_Mons")] - [InlineData("+08:00")] - public void Parse_AnythingElse_IsNothing(string? id) - { - Assert.Null(CallerTimeZone.Parse(id)); + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + [InlineData("Mars/Olympus_Mons")] + [InlineData("+08:00")] + public void Parse_AnythingElse_IsNothing(string? id) + { + Assert.Null(CallerTimeZone.Parse(id)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ClockContextProviderTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ClockContextProviderTests.cs index 5653cbe4..9ff689a9 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ClockContextProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ClockContextProviderTests.cs @@ -2,34 +2,35 @@ using AgentCore.TestSupport; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// The one line a clock: agent reads each turn: the weekday, the date, and the time in the -/// zone it is given, with the zone named so a relative date has an anchor. -/// -public sealed class ClockContextProviderTests +namespace AgentCore.Application.Tests.Runtime.Harness { - [Fact] - public void Describe_ReadsTheClockInTheGivenZone() + /// + /// The one line a clock: agent reads each turn: the weekday, the date, and the time in the + /// zone it is given, with the zone named so a relative date has an anchor. + /// + public sealed class ClockContextProviderTests { - // 2026-09-17 19:05 UTC is Thursday 14:05 in a zone five hours behind. - FakeTimeProvider clock = new(new DateTimeOffset(2026, 9, 17, 19, 5, 0, TimeSpan.Zero)); - var zone = TimeZoneInfo.CreateCustomTimeZone("America/Chicago", TimeSpan.FromHours(-5), "Central", "Central"); + [Fact] + public void Describe_ReadsTheClockInTheGivenZone() + { + // 2026-09-17 19:05 UTC is Thursday 14:05 in a zone five hours behind. + FakeTimeProvider clock = new(new DateTimeOffset(2026, 9, 17, 19, 5, 0, TimeSpan.Zero)); + TimeZoneInfo zone = TimeZoneInfo.CreateCustomTimeZone("America/Chicago", TimeSpan.FromHours(-5), "Central", "Central"); - var line = ClockContextProvider.Describe(clock, zone); + string line = ClockContextProvider.Describe(clock, zone); - Assert.Equal("Today is Thursday, 2026-09-17. The local time is 14:05, America/Chicago (UTC-05:00).", line); - } + Assert.Equal("Today is Thursday, 2026-09-17. The local time is 14:05, America/Chicago (UTC-05:00).", line); + } - [Fact] - public void Describe_AZoneAheadOfUtc_CarriesAPlusSignAndTheNextDay() - { - FakeTimeProvider clock = new(new DateTimeOffset(2026, 9, 17, 23, 30, 0, TimeSpan.Zero)); - var zone = TimeZoneInfo.CreateCustomTimeZone("Asia/Taipei", TimeSpan.FromHours(8), "Taipei", "Taipei"); + [Fact] + public void Describe_AZoneAheadOfUtc_CarriesAPlusSignAndTheNextDay() + { + FakeTimeProvider clock = new(new DateTimeOffset(2026, 9, 17, 23, 30, 0, TimeSpan.Zero)); + TimeZoneInfo zone = TimeZoneInfo.CreateCustomTimeZone("Asia/Taipei", TimeSpan.FromHours(8), "Taipei", "Taipei"); - var line = ClockContextProvider.Describe(clock, zone); + string line = ClockContextProvider.Describe(clock, zone); - Assert.Equal("Today is Friday, 2026-09-18. The local time is 07:30, Asia/Taipei (UTC+08:00).", line); + Assert.Equal("Today is Friday, 2026-09-18. The local time is 07:30, Asia/Taipei (UTC+08:00).", line); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationFilesProviderTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationFilesProviderTests.cs index b523c5aa..e871ec40 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationFilesProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationFilesProviderTests.cs @@ -7,96 +7,119 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -#pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - -/// -/// as a unit: it serves the framework's file tools rooted at the -/// workspace of the turn filed for the invoking session, and refuses to serve any when no turn -/// is filed. -/// -public sealed class ConversationFilesProviderTests : IDisposable +namespace AgentCore.Application.Tests.Runtime.Harness { - private readonly string _root = Path.Combine(Path.GetTempPath(), $"conversation-files-{Guid.NewGuid():N}"); - - public ConversationFilesProviderTests() => Directory.CreateDirectory(_root); - - public void Dispose() => Directory.Delete(_root, recursive: true); +#pragma warning disable MAAI001 // File-store types are evaluation-only in Microsoft.Agents.AI 1.21.0. - [Fact] - public async Task InvokingAsync_WithASessionFiledTurn_ServesFileTools() + /// + /// as a unit: it serves the framework's file tools rooted at the + /// workspace of the turn filed for the invoking session, and refuses to serve any when no turn + /// is filed. + /// + public sealed class ConversationFilesProviderTests : IDisposable { - using ConversationFilesProvider provider = new(_root, Options()); - StubSession session = new(); - TurnRegistry.Set( + private readonly string _root = Path.Combine(Path.GetTempPath(), $"conversation-files-{Guid.NewGuid():N}"); + + public ConversationFilesProviderTests() + { + _ = Directory.CreateDirectory(_root); + } + + public void Dispose() + { + Directory.Delete(_root, recursive: true); + } + + [Fact] + public async Task InvokingAsync_WithASessionFiledTurn_ServesFileTools() + { + using ConversationFilesProvider provider = new(_root, Options()); + StubSession session = new(); + TurnRegistry.Set( + session, + new TurnInvocation { ConversationId = "conversation-1", TurnIndex = 0, Stage = "", Workspace = _root }); + + AIContext context = await provider.InvokingAsync( + Invoking(session), TestContext.Current.CancellationToken); + + Assert.NotNull(context.Tools); + Assert.NotEmpty(context.Tools); + } + + [Fact] + public async Task InvokingAsync_WithoutATurn_ThrowsInvalidOperationException() + { + using ConversationFilesProvider provider = new(_root, Options()); + + InvalidOperationException exception = await Assert.ThrowsAsync( + () => provider.InvokingAsync( + Invoking(new StubSession()), TestContext.Current.CancellationToken).AsTask()); + + Assert.Contains("files: tool", exception.Message, StringComparison.Ordinal); + } + + private static FileAccessProviderOptions Options() + { + return new() + { + DisableReadOnlyToolApproval = true, + DisableWriteToolApproval = true, + }; + } + + private static AIContextProvider.InvokingContext Invoking(AgentSession session) + { + return new( + StubAgent.Instance, session, - new TurnInvocation { ConversationId = "conversation-1", TurnIndex = 0, Stage = "", Workspace = _root }); - - var context = await provider.InvokingAsync( - Invoking(session), TestContext.Current.CancellationToken); - - Assert.NotNull(context.Tools); - Assert.NotEmpty(context.Tools); - } - - [Fact] - public async Task InvokingAsync_WithoutATurn_ThrowsInvalidOperationException() - { - using ConversationFilesProvider provider = new(_root, Options()); - - var exception = await Assert.ThrowsAsync( - () => provider.InvokingAsync( - Invoking(new StubSession()), TestContext.Current.CancellationToken).AsTask()); - - Assert.Contains("files: tool", exception.Message, StringComparison.Ordinal); - } - - private static FileAccessProviderOptions Options() => new() - { - DisableReadOnlyToolApproval = true, - DisableWriteToolApproval = true, - }; - - private static AIContextProvider.InvokingContext Invoking(AgentSession session) => new( - StubAgent.Instance, - session, - new AIContext { Messages = [new ChatMessage(ChatRole.User, "list my files")] }); - - private sealed class StubSession : AgentSession; - - private sealed class StubAgent : AIAgent - { - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + new AIContext { Messages = [new ChatMessage(ChatRole.User, "list my files")] }); + } + + private sealed class StubSession : AgentSession; + + private sealed class StubAgent : AIAgent + { + public static StubAgent Instance { get; } = new(); + + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) + { + return new(new StubSession()); + } + + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionBackgroundTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionBackgroundTests.cs index fdfe9959..8ff5c9a7 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionBackgroundTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionBackgroundTests.cs @@ -5,21 +5,22 @@ using AgentCore.Application.Runtime; using AgentCore.Application.Sessions.Memory; using AgentCore.Application.Tests.Fakes; +using AgentCore.Domain; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// The conversation-end release of background sessions: a child still running when the conversation closes or a -/// turn reaches a terminal stage is cancelled instead of leaking past the conversation. -/// -#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class ConversationSessionBackgroundTests +namespace AgentCore.Application.Tests.Runtime.Harness { - private const string LingeringChildYaml = - """ + /// + /// The conversation-end release of background sessions: a child still running when the conversation closes or a + /// turn reaches a terminal stage is cancelled instead of leaking past the conversation. + /// +#pragma warning disable MAAI001 // BackgroundAgentsProvider is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class ConversationSessionBackgroundTests + { + private const string LingeringChildYaml = + """ apiVersion: agentcore/v1 guards: never: { "<": [ { var: turnIndex }, 0 ] } @@ -36,8 +37,8 @@ public sealed class ConversationSessionBackgroundTests - { id: done, agent: blocker, terminal: true } """; - private const string TerminalChildYaml = - """ + private const string TerminalChildYaml = + """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -54,127 +55,128 @@ public sealed class ConversationSessionBackgroundTests - { id: done, agent: blocker, terminal: true } """; - [Fact] - public async Task CloseAsync_WithAChildStillRunning_CancelsIt() - { - var token = TestContext.Current.CancellationToken; - var parent = new ToolCallingChatClient( - "started", - new Dictionary(StringComparer.Ordinal) - { - ["agentName"] = "blocker", - ["input"] = "work", - ["description"] = "d", - }); - var child = new BlockingChatClient(); - InMemoryConversationSessions sessions = new(BuildFactory(LingeringChildYaml, parent, child), TimeSpan.FromMinutes(30), TimeProvider.System); - - var session = await sessions.OpenAsync("conversation-1", token); - await session.RunTurnAsync("go", token); - - // The turn is over and the conversation is not, and the child is still in its model call: the - // leak this step closes. Nothing has cancelled it yet. - await child.Started.WaitAsync(TimeSpan.FromSeconds(10), token); - Assert.False(child.Cancelled.IsCompleted); - - await sessions.CloseAsync("conversation-1", token); - - await child.Cancelled.WaitAsync(TimeSpan.FromSeconds(10), token); - } - - [Fact] - public async Task ATurnThatReachesATerminalStage_CancelsAChildStillRunningWithoutCloseAsync() - { - var token = TestContext.Current.CancellationToken; - var parent = new ToolCallingChatClient( - "started", - new Dictionary(StringComparer.Ordinal) - { - ["agentName"] = "blocker", - ["input"] = "work", - ["description"] = "d", - }); - var child = new BlockingChatClient(); - var factory = BuildFactory(TerminalChildYaml, parent, child); - - await using var session = factory.Create("conversation-1"); - var turn = await session.RunTurnAsync("go", token); - - Assert.True(turn.IsTerminal); - await child.Started.WaitAsync(TimeSpan.FromSeconds(10), token); - await child.Cancelled.WaitAsync(TimeSpan.FromSeconds(10), token); - } - - private static ConversationSessionFactory BuildFactory(string yaml, IChatClient parent, IChatClient child) - { - var chatClients = new RoutingChatClientFactory(parent); - chatClients.Route("parent", parent); - chatClients.Route("blocker", child); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(chatClients))["main"]; - - return new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - } - - /// A model that stays inside its first request until the run is cancelled. - private sealed class BlockingChatClient : IChatClient - { - private readonly TaskCompletionSource _started = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _cancelled = new(TaskCreationOptions.RunContinuationsAsynchronously); - - /// Completes when the child enters its model call. - public Task Started => _started.Task; - - /// Completes when the child observes the cancel. - public Task Cancelled => _cancelled.Task; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - _started.TrySetResult(); - - try - { - await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); - } - catch (OperationCanceledException) - { - _cancelled.TrySetResult(); - throw; - } - - yield break; - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } - - public void Dispose() - { - // Nothing to release. - } - } - } - #pragma warning restore MAAI001 + [Fact] + public async Task CloseAsync_WithAChildStillRunning_CancelsIt() + { + CancellationToken token = TestContext.Current.CancellationToken; + ToolCallingChatClient parent = new( + "started", + new Dictionary(StringComparer.Ordinal) + { + ["agentName"] = "blocker", + ["input"] = "work", + ["description"] = "d", + }); + BlockingChatClient child = new(); + InMemoryConversationSessions sessions = new(BuildFactory(LingeringChildYaml, parent, child), TimeSpan.FromMinutes(30), TimeProvider.System); + + ConversationSession session = await sessions.OpenAsync("conversation-1", token); + _ = await session.RunTurnAsync("go", token); + + // The turn is over and the conversation is not, and the child is still in its model call: the + // leak this step closes. Nothing has cancelled it yet. + await child.Started.WaitAsync(TimeSpan.FromSeconds(10), token); + Assert.False(child.Cancelled.IsCompleted); + + await sessions.CloseAsync("conversation-1", token); + + await child.Cancelled.WaitAsync(TimeSpan.FromSeconds(10), token); + } + + [Fact] + public async Task ATurnThatReachesATerminalStage_CancelsAChildStillRunningWithoutCloseAsync() + { + CancellationToken token = TestContext.Current.CancellationToken; + ToolCallingChatClient parent = new( + "started", + new Dictionary(StringComparer.Ordinal) + { + ["agentName"] = "blocker", + ["input"] = "work", + ["description"] = "d", + }); + BlockingChatClient child = new(); + ConversationSessionFactory factory = BuildFactory(TerminalChildYaml, parent, child); + + await using ConversationSession session = factory.Create("conversation-1"); + TurnResult turn = await session.RunTurnAsync("go", token); + + Assert.True(turn.IsTerminal); + await child.Started.WaitAsync(TimeSpan.FromSeconds(10), token); + await child.Cancelled.WaitAsync(TimeSpan.FromSeconds(10), token); + } + + private static ConversationSessionFactory BuildFactory(string yaml, IChatClient parent, IChatClient child) + { + RoutingChatClientFactory chatClients = new(parent); + _ = chatClients.Route("parent", parent); + _ = chatClients.Route("blocker", child); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(chatClients))["main"]; + + return new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + } + + /// A model that stays inside its first request until the run is cancelled. + private sealed class BlockingChatClient : IChatClient + { + private readonly TaskCompletionSource _started = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _cancelled = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /// Completes when the child enters its model call. + public Task Started => _started.Task; + + /// Completes when the child observes the cancel. + public Task Cancelled => _cancelled.Task; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + _ = _started.TrySetResult(); + + try + { + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + _ = _cancelled.TrySetResult(); + throw; + } + + yield break; + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + // Nothing to release. + } + } + } +#pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionGraphStateTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionGraphStateTests.cs index d071a22c..6bd3f932 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionGraphStateTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionGraphStateTests.cs @@ -11,18 +11,20 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// Harness step: a graph row whose document declares a harness switch keeps one workflow -/// session for the whole conversation, so todos: (and mode:) survive turns and resume. -/// A graph row without one still runs every turn fresh, exactly as before. -/// -public sealed class ConversationSessionGraphStateTests +namespace AgentCore.Application.Tests.Runtime.Harness { - private const string TodosYaml = - """ + /// + /// Harness step: a graph row whose document declares a harness switch keeps one workflow + /// session for the whole conversation, so todos: (and mode:) survive turns and resume. + /// A graph row without one still runs every turn fresh, exactly as before. + /// + public sealed class ConversationSessionGraphStateTests + { + private const string TodosYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -35,8 +37,8 @@ public sealed class ConversationSessionGraphStateTests agents: [ adder, echo ] """; - private const string PlainYaml = - """ + private const string PlainYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -49,122 +51,123 @@ public sealed class ConversationSessionGraphStateTests agents: [ first, second ] """; - [Fact] - public async Task SecondTurn_AdderRequestCarriesTheRestoredTodo_AndNoRenderedHistory() - { - InMemoryConversationStore store = new(); - var adder = new ScriptedToolCallingChatClient(("todos_add", """{"todos":[{"title":"buy milk"}]}""")) { FinalText = "added" }; - var adderRequests = new RequestCapturingChatClient(adder); - var echo = new ScriptedToolCallingChatClient() { FinalText = "echo1" }; - var factory = Build(TodosYaml, store, adderRequests, echo); - var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("track this", TestContext.Current.CancellationToken); - var turn1Conversations = adderRequests.Requests.Count; - - adder.FinalText = "second"; - echo.FinalText = "echo2"; - await session.RunTurnAsync("anything new?", TestContext.Current.CancellationToken); - - // The restored session injects the todo list into the run-2 instructions… - var run2 = adderRequests.Requests[turn1Conversations]; - Assert.Contains(run2, message => message.Text.Contains("buy milk", StringComparison.Ordinal)); - - // …and the resumed conversation already carries what came before, so the turn - // renders no history of its own. Rendered plus resumed would deliver it twice. - Assert.DoesNotContain(run2, message => message.Text.Contains(TurnMessages.HistoryPreamble, StringComparison.Ordinal)); - } - - [Fact] - public async Task ResumeFromTheSameStore_AdderRequestCarriesTheRestoredTodo() - { - InMemoryConversationStore store = new(); - var adder = new ScriptedToolCallingChatClient(("todos_add", """{"todos":[{"title":"buy milk"}]}""")) { FinalText = "added" }; - var adderRequests = new RequestCapturingChatClient(adder); - var echo = new ScriptedToolCallingChatClient() { FinalText = "echo1" }; - var factory = Build(TodosYaml, store, adderRequests, echo); - - var first = factory.Create("conversation-1"); - await first.RunTurnAsync("track this", TestContext.Current.CancellationToken); - - var second = factory.Create("conversation-1"); - await second.RunTurnAsync("anything new?", TestContext.Current.CancellationToken); - - var resumed = adderRequests.Requests[^1]; - Assert.Contains(resumed, message => message.Text.Contains("buy milk", StringComparison.Ordinal)); - } - - [Fact] - public async Task NoHarnessSwitch_AfterATurn_Store0HoldsNeitherBlobNorProviders() - { - InMemoryConversationStore store = new(); - var factory = Build( - PlainYaml, - store, - new ScriptedToolCallingChatClient() { FinalText = "one" }, - new ScriptedToolCallingChatClient() { FinalText = "two" }); - var session = factory.Create("conversation-1"); - - var turn = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - - Assert.Equal("two", turn.ReplyText); - var record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); - Assert.NotNull(record?.State); - Assert.Null(record.State.WorkflowState); - Assert.Empty(record.State.Providers); - } - - [Fact] - public async Task TodosSwitch_AfterATurn_Store0HoldsTheBlobAndNoPickedKeys() - { - InMemoryConversationStore store = new(); - var adder = new ScriptedToolCallingChatClient(("todos_add", """{"todos":[{"title":"buy milk"}]}""")) { FinalText = "added" }; - var factory = Build(TodosYaml, store, adder, new ScriptedToolCallingChatClient() { FinalText = "echo1" }); - var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("track this", TestContext.Current.CancellationToken); - - var record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); - Assert.NotNull(record?.State); - Assert.NotNull(record.State.WorkflowState); - Assert.Empty(record.State.Providers); - } - - [Fact] - public async Task PickedProvidersWithoutABlob_AreIgnored_AdderStartsFresh() - { - InMemoryConversationStore store = new(); - var adder = new ScriptedToolCallingChatClient() { FinalText = "added" }; - var adderRequests = new RequestCapturingChatClient(adder); - var factory = Build(TodosYaml, store, adderRequests, new ScriptedToolCallingChatClient() { FinalText = "echo1" }); - - ConversationSessionState fabricated = new() - { - Providers = new Dictionary(StringComparer.Ordinal) - { - [new TodoProvider().StateKeys[0]] = JsonDocument.Parse( - """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}""").RootElement, - }, - }; - - var session = factory.Create("conversation-1", fabricated); - await session.RunTurnAsync("anything new?", TestContext.Current.CancellationToken); - - Assert.DoesNotContain( - adderRequests.Requests[0], - message => message.Text.Contains("buy milk", StringComparison.Ordinal)); - } - - private static ConversationSessionFactory Build(string yaml, IConversationStore store, IChatClient first, IChatClient second) - { - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(first); - chatClients.Route("echo", second); - chatClients.Route("second", second); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { ConversationStore = store })["main"]; - - return new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - } - } + [Fact] + public async Task SecondTurn_AdderRequestCarriesTheRestoredTodo_AndNoRenderedHistory() + { + InMemoryConversationStore store = new(); + ScriptedToolCallingChatClient adder = new(("todos_add", /*lang=json,strict*/ """{"todos":[{"title":"buy milk"}]}""")) { FinalText = "added" }; + RequestCapturingChatClient adderRequests = new(adder); + ScriptedToolCallingChatClient echo = new() { FinalText = "echo1" }; + ConversationSessionFactory factory = Build(TodosYaml, store, adderRequests, echo); + ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("track this", TestContext.Current.CancellationToken); + int turn1Conversations = adderRequests.Requests.Count; + + adder.FinalText = "second"; + echo.FinalText = "echo2"; + _ = await session.RunTurnAsync("anything new?", TestContext.Current.CancellationToken); + + // The restored session injects the todo list into the run-2 instructions… + IReadOnlyList run2 = adderRequests.Requests[turn1Conversations]; + Assert.Contains(run2, message => message.Text.Contains("buy milk", StringComparison.Ordinal)); + + // …and the resumed conversation already carries what came before, so the turn + // renders no history of its own. Rendered plus resumed would deliver it twice. + Assert.DoesNotContain(run2, message => message.Text.Contains(TurnMessages.HistoryPreamble, StringComparison.Ordinal)); + } + + [Fact] + public async Task ResumeFromTheSameStore_AdderRequestCarriesTheRestoredTodo() + { + InMemoryConversationStore store = new(); + ScriptedToolCallingChatClient adder = new(("todos_add", /*lang=json,strict*/ """{"todos":[{"title":"buy milk"}]}""")) { FinalText = "added" }; + RequestCapturingChatClient adderRequests = new(adder); + ScriptedToolCallingChatClient echo = new() { FinalText = "echo1" }; + ConversationSessionFactory factory = Build(TodosYaml, store, adderRequests, echo); + + ConversationSession first = factory.Create("conversation-1"); + _ = await first.RunTurnAsync("track this", TestContext.Current.CancellationToken); + + ConversationSession second = factory.Create("conversation-1"); + _ = await second.RunTurnAsync("anything new?", TestContext.Current.CancellationToken); + + IReadOnlyList resumed = adderRequests.Requests[^1]; + Assert.Contains(resumed, message => message.Text.Contains("buy milk", StringComparison.Ordinal)); + } + + [Fact] + public async Task NoHarnessSwitch_AfterATurn_Store0HoldsNeitherBlobNorProviders() + { + InMemoryConversationStore store = new(); + ConversationSessionFactory factory = Build( + PlainYaml, + store, + new ScriptedToolCallingChatClient() { FinalText = "one" }, + new ScriptedToolCallingChatClient() { FinalText = "two" }); + ConversationSession session = factory.Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + + Assert.Equal("two", turn.ReplyText); + ConversationRecord? record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); + Assert.NotNull(record?.State); + Assert.Null(record.State.WorkflowState); + Assert.Empty(record.State.Providers); + } + + [Fact] + public async Task TodosSwitch_AfterATurn_Store0HoldsTheBlobAndNoPickedKeys() + { + InMemoryConversationStore store = new(); + ScriptedToolCallingChatClient adder = new(("todos_add", /*lang=json,strict*/ """{"todos":[{"title":"buy milk"}]}""")) { FinalText = "added" }; + ConversationSessionFactory factory = Build(TodosYaml, store, adder, new ScriptedToolCallingChatClient() { FinalText = "echo1" }); + ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("track this", TestContext.Current.CancellationToken); + + ConversationRecord? record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); + Assert.NotNull(record?.State); + _ = Assert.NotNull(record.State.WorkflowState); + Assert.Empty(record.State.Providers); + } + + [Fact] + public async Task PickedProvidersWithoutABlob_AreIgnored_AdderStartsFresh() + { + InMemoryConversationStore store = new(); + ScriptedToolCallingChatClient adder = new() { FinalText = "added" }; + RequestCapturingChatClient adderRequests = new(adder); + ConversationSessionFactory factory = Build(TodosYaml, store, adderRequests, new ScriptedToolCallingChatClient() { FinalText = "echo1" }); + + ConversationSessionState fabricated = new() + { + Providers = new Dictionary(StringComparer.Ordinal) + { + [new TodoProvider().StateKeys[0]] = JsonDocument.Parse( + """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}""").RootElement, + }, + }; + + ConversationSession session = factory.Create("conversation-1", fabricated); + _ = await session.RunTurnAsync("anything new?", TestContext.Current.CancellationToken); + + Assert.DoesNotContain( + adderRequests.Requests[0], + message => message.Text.Contains("buy milk", StringComparison.Ordinal)); + } + + private static ConversationSessionFactory Build(string yaml, IConversationStore store, IChatClient first, IChatClient second) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(first); + _ = chatClients.Route("echo", second); + _ = chatClients.Route("second", second); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { ConversationStore = store })["main"]; + + return new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionProviderStateTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionProviderStateTests.cs index e3fb43b1..13202731 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionProviderStateTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionProviderStateTests.cs @@ -1,4 +1,3 @@ -using System.Linq; using System.Runtime.CompilerServices; using System.Text.Json; using AgentCore.Application.Conversation; @@ -8,23 +7,22 @@ using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; -using AgentCore.Application.Runtime.Harness; using AgentCore.Application.Tests.Fakes; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// The end-to-end path of harness step 4: a todos: item written during a turn lands in store -/// 0's Providers, and a conversation that resumes — from the same store, or from a host checkpoint — -/// gets it re-injected by the framework's own . -/// -public sealed class ConversationSessionProviderStateTests +namespace AgentCore.Application.Tests.Runtime.Harness { - private const string TodosYaml = - """ + /// + /// The end-to-end path of harness step 4: a todos: item written during a turn lands in store + /// 0's Providers, and a conversation that resumes — from the same store, or from a host checkpoint — + /// gets it re-injected by the framework's own . + /// + public sealed class ConversationSessionProviderStateTests + { + private const string TodosYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -34,8 +32,8 @@ public sealed class ConversationSessionProviderStateTests agent: only """; - private const string NoTodosYaml = - """ + private const string NoTodosYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -45,215 +43,217 @@ public sealed class ConversationSessionProviderStateTests agent: only """; - [Fact] - public async Task AfterATurn_Store0HoldsOnlyTheTodoProviderKey_WithTheTodoInIt() - { - InMemoryConversationStore store = new(); - var compiled = Compile(TodosYaml, new TodoAddThenTextChatClient(), store); - var factory = new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("please track this", TestContext.Current.CancellationToken); + [Fact] + public async Task AfterATurn_Store0HoldsOnlyTheTodoProviderKey_WithTheTodoInIt() + { + InMemoryConversationStore store = new(); + CompiledAgent compiled = Compile(TodosYaml, new TodoAddThenTextChatClient(), store); + ConversationSessionFactory factory = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + ConversationSession session = factory.Create("conversation-1"); - var record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("please track this", TestContext.Current.CancellationToken); - Assert.NotNull(record); - Assert.NotNull(record.State); - var key = Assert.Single(record.State.Providers.Keys); + ConversationRecord? record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); - // The one literal: it pins the on-disk shape of the todos: state, everywhere else the key - // comes from the real provider's own StateKeys. - Assert.Equal("TodoProvider", key); - Assert.Contains("buy milk", record.State.Providers[key].GetRawText(), StringComparison.Ordinal); - } + Assert.NotNull(record); + Assert.NotNull(record.State); + string key = Assert.Single(record.State.Providers.Keys); - [Fact] - public async Task ASecondSessionFromTheSameFactoryAndStore_ReInjectsTheTodo() - { - InMemoryConversationStore store = new(); - TodoAddThenTextChatClient chatClient = new(); - var compiled = Compile(TodosYaml, chatClient, store); - var factory = new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + // The one literal: it pins the on-disk shape of the todos: state, everywhere else the key + // comes from the real provider's own StateKeys. + Assert.Equal("TodoProvider", key); + Assert.Contains("buy milk", record.State.Providers[key].GetRawText(), StringComparison.Ordinal); + } - var first = factory.Create("conversation-1"); - await first.RunTurnAsync("please track this", TestContext.Current.CancellationToken); + [Fact] + public async Task ASecondSessionFromTheSameFactoryAndStore_ReInjectsTheTodo() + { + InMemoryConversationStore store = new(); + TodoAddThenTextChatClient chatClient = new(); + CompiledAgent compiled = Compile(TodosYaml, chatClient, store); + ConversationSessionFactory factory = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - var second = factory.Create("conversation-1"); - await second.RunTurnAsync("what's on my list", TestContext.Current.CancellationToken); + ConversationSession first = factory.Create("conversation-1"); + _ = await first.RunTurnAsync("please track this", TestContext.Current.CancellationToken); - Assert.Contains( - chatClient.Requests[^1], - message => message.Text.Contains("buy milk", StringComparison.Ordinal)); - } + ConversationSession second = factory.Create("conversation-1"); + _ = await second.RunTurnAsync("what's on my list", TestContext.Current.CancellationToken); - [Fact] - public async Task AResumeFromAHostCheckpoint_ThroughAgentCoreAgent_ReInjectsTheTodo() - { - InMemoryConversationStore firstStore = new(); - TodoAddThenTextChatClient firstChatClient = new(); - var firstCompiled = Compile(TodosYaml, firstChatClient, firstStore); - AgentCoreAgent firstAgent = new( - new ConversationSessionFactory(firstCompiled, new GuardEvaluator(firstCompiled.Configuration.Guards)), "main"); - - var firstSession = await firstAgent.CreateSessionAsync( - "conversation-1", TestContext.Current.CancellationToken); - await firstAgent.RunAsync( - "please track this", firstSession, cancellationToken: TestContext.Current.CancellationToken); - - var serialized = await firstAgent.SerializeSessionAsync( - firstSession, cancellationToken: TestContext.Current.CancellationToken); - - // A fresh store: this proves the checkpoint carries the provider state on its own, not - // because store 0 still remembers the conversation. - InMemoryConversationStore secondStore = new(); - SequencedChatClient secondChatClient = new("hello there."); - var secondCompiled = Compile(TodosYaml, secondChatClient, secondStore); - AgentCoreAgent secondAgent = new( - new ConversationSessionFactory(secondCompiled, new GuardEvaluator(secondCompiled.Configuration.Guards)), "main"); - - var revived = await secondAgent.DeserializeSessionAsync( - serialized, cancellationToken: TestContext.Current.CancellationToken); - await secondAgent.RunAsync( - "what's on my list", revived, cancellationToken: TestContext.Current.CancellationToken); - - Assert.Contains( - secondChatClient.Requests[^1], - message => message.Text.Contains("buy milk", StringComparison.Ordinal)); - } - - [Fact] - public async Task AVersion99StoredState_DropsTheProviders_TheTodoNeverReachesTheRequest() - { - InMemoryConversationStore store = new(); - SequencedChatClient chatClient = new("hello there."); - var compiled = Compile(TodosYaml, chatClient, store); - var factory = new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + Assert.Contains( + chatClient.Requests[^1], + message => message.Text.Contains("buy milk", StringComparison.Ordinal)); + } - ConversationSessionState fabricated = new() + [Fact] + public async Task AResumeFromAHostCheckpoint_ThroughAgentCoreAgent_ReInjectsTheTodo() { - Version = 99, - Providers = new Dictionary(StringComparer.Ordinal) - { - [new TodoProvider().StateKeys[0]] = JsonDocument.Parse( - """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}""").RootElement, - }, - }; + InMemoryConversationStore firstStore = new(); + TodoAddThenTextChatClient firstChatClient = new(); + CompiledAgent firstCompiled = Compile(TodosYaml, firstChatClient, firstStore); + AgentCoreAgent firstAgent = new( + new ConversationSessionFactory(firstCompiled, new GuardEvaluator(firstCompiled.Configuration.Guards)), "main"); + + AgentSession firstSession = await firstAgent.CreateSessionAsync("conversation-1"); + _ = await firstAgent.RunAsync( + "please track this", firstSession, cancellationToken: TestContext.Current.CancellationToken); + + JsonElement serialized = await firstAgent.SerializeSessionAsync( + firstSession, cancellationToken: TestContext.Current.CancellationToken); + + // A fresh store: this proves the checkpoint carries the provider state on its own, not + // because store 0 still remembers the conversation. + InMemoryConversationStore secondStore = new(); + SequencedChatClient secondChatClient = new("hello there."); + CompiledAgent secondCompiled = Compile(TodosYaml, secondChatClient, secondStore); + AgentCoreAgent secondAgent = new( + new ConversationSessionFactory(secondCompiled, new GuardEvaluator(secondCompiled.Configuration.Guards)), "main"); + + AgentSession revived = await secondAgent.DeserializeSessionAsync( + serialized, cancellationToken: TestContext.Current.CancellationToken); + _ = await secondAgent.RunAsync( + "what's on my list", revived, cancellationToken: TestContext.Current.CancellationToken); + + Assert.Contains( + secondChatClient.Requests[^1], + message => message.Text.Contains("buy milk", StringComparison.Ordinal)); + } - var session = factory.Create("conversation-1", fabricated); + [Fact] + public async Task AVersion99StoredState_DropsTheProviders_TheTodoNeverReachesTheRequest() + { + InMemoryConversationStore store = new(); + SequencedChatClient chatClient = new("hello there."); + CompiledAgent compiled = Compile(TodosYaml, chatClient, store); + ConversationSessionFactory factory = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - await session.RunTurnAsync("what's on my list", TestContext.Current.CancellationToken); + ConversationSessionState fabricated = new() + { + Version = 99, + Providers = new Dictionary(StringComparer.Ordinal) + { + [new TodoProvider().StateKeys[0]] = JsonDocument.Parse( + """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}""").RootElement, + }, + }; - Assert.DoesNotContain( - chatClient.Requests[^1], - message => message.Text.Contains("buy milk", StringComparison.Ordinal)); - } + ConversationSession session = factory.Create("conversation-1", fabricated); - [Fact] - public async Task NoTodosBlock_AfterATurn_Store0HoldsNoProviders() - { - InMemoryConversationStore store = new(); - SequencedChatClient chatClient = new("hello there."); - var compiled = Compile(NoTodosYaml, chatClient, store); - var factory = new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - var session = factory.Create("conversation-1"); + _ = await session.RunTurnAsync("what's on my list", TestContext.Current.CancellationToken); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + Assert.DoesNotContain( + chatClient.Requests[^1], + message => message.Text.Contains("buy milk", StringComparison.Ordinal)); + } - var record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); + [Fact] + public async Task NoTodosBlock_AfterATurn_Store0HoldsNoProviders() + { + InMemoryConversationStore store = new(); + SequencedChatClient chatClient = new("hello there."); + CompiledAgent compiled = Compile(NoTodosYaml, chatClient, store); + ConversationSessionFactory factory = new(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + ConversationSession session = factory.Create("conversation-1"); - Assert.NotNull(record); - Assert.NotNull(record.State); - Assert.Empty(record.State.Providers); - } + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - private static CompiledAgent Compile(string yaml, IChatClient chatClient, IConversationStore store) - => ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(chatClient)) { ConversationStore = store })["main"]; + ConversationRecord? record = await store.GetAsync("conversation-1", TestContext.Current.CancellationToken); - /// - /// Calls todos_add {"todos":[{"title":"buy milk"}]} on the very first request this - /// instance ever answers, then answers text on every request after — regardless of whether the - /// transcript already carries a tool result, so the same instance can drive two sessions of one - /// conversation: the one that adds the todo, and the one that resumes it. - /// - private sealed class TodoAddThenTextChatClient : IChatClient - { - private int _calls; + Assert.NotNull(record); + Assert.NotNull(record.State); + Assert.Empty(record.State.Providers); + } - public List> Requests { get; } = []; + private static CompiledAgent Compile(string yaml, IChatClient chatClient, IConversationStore store) + { + return ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(chatClient)) { ConversationStore = store })["main"]; + } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + /// + /// Calls todos_add {"todos":[{"title":"buy milk"}]} on the very first request this + /// instance ever answers, then answers text on every request after — regardless of whether the + /// transcript already carries a tool result, so the same instance can drive two sessions of one + /// conversation: the one that adds the todo, and the one that resumes it. + /// + private sealed class TodoAddThenTextChatClient : IChatClient { - ArgumentNullException.ThrowIfNull(messages); + private int _calls; - var index = Interlocked.Increment(ref _calls) - 1; - var transcript = messages.ToList(); - lock (Requests) + public List> Requests { get; } = []; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - Requests.Add(transcript); - } + ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + int index = Interlocked.Increment(ref _calls) - 1; + List transcript = [.. messages]; + lock (Requests) + { + Requests.Add(transcript); + } - var responseId = Guid.NewGuid().ToString("N"); - var tool = options?.Tools?.OfType().FirstOrDefault(); + await Task.Yield(); - if (index == 0 && tool is not null) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) - { - ["todos"] = new List + string responseId = Guid.NewGuid().ToString("N"); + AIFunction? tool = options?.Tools?.OfType().FirstOrDefault(); + + if (index == 0 && tool is not null) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_1", + tool.Name, + new Dictionary(StringComparer.Ordinal) { - new Dictionary(StringComparer.Ordinal) { ["title"] = "buy milk" }, - }, - })]) + ["todos"] = new List + { + new Dictionary(StringComparer.Ordinal) { ["title"] = "buy milk" }, + }, + })]) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "hello there.") { ResponseId = responseId, MessageId = responseId, }; - yield break; } - yield return new ChatResponseUpdate(ChatRole.Assistant, "hello there.") + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionShellTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionShellTests.cs index 2333f9c1..2e052bfd 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionShellTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationSessionShellTests.cs @@ -1,26 +1,27 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Runtime; -using AgentCore.Application.Runtime.Harness; using AgentCore.Application.Sessions.Memory; using AgentCore.Application.Tests.Fakes; +using AgentCore.Domain; using AgentCore.TestSupport; using Microsoft.Agents.AI.Tools.Shell; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// The end-to-end path of a shell: block: the tool the model is handed, the workspace it -/// runs in, the policy that refuses a command, and the process it starts being cleaned up when the -/// conversation closes or a turn reaches a terminal stage. -/// -public sealed class ConversationSessionShellTests : IDisposable +namespace AgentCore.Application.Tests.Runtime.Harness { - private const string ShellYaml = - """ + /// + /// The end-to-end path of a shell: block: the tool the model is handed, the workspace it + /// runs in, the policy that refuses a command, and the process it starts being cleaned up when the + /// conversation closes or a turn reaches a terminal stage. + /// + public sealed class ConversationSessionShellTests : IDisposable + { + private const string ShellYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -30,8 +31,8 @@ public sealed class ConversationSessionShellTests : IDisposable agent: only """; - private const string NoShellYaml = - """ + private const string NoShellYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -41,8 +42,8 @@ public sealed class ConversationSessionShellTests : IDisposable agent: only """; - private const string TerminalShellYaml = - """ + private const string TerminalShellYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -55,231 +56,234 @@ public sealed class ConversationSessionShellTests : IDisposable - { id: only, agent: only, terminal: true } """; - private readonly string _root = - Path.Combine(Path.GetTempPath(), "agentcore-shell-session-" + Guid.NewGuid().ToString("N")); - - /// The name the model sees for the shell tool, read off a throwaway real executor. - private static readonly string RunShellToolName = ToolName(); - - public void Dispose() - { - if (Directory.Exists(_root)) - { - Directory.Delete(_root, recursive: true); - } - } - - [Fact] - public async Task FirstRequest_ListsATool_NamedRunShell() - { - // One literal assertion, as the brief allows: it pins the name the model actually sees. - Assert.Equal("run_shell", RunShellToolName); - - var client = new ShellScriptedClient(RunShellToolName, "pwd", "rm -rf x", "echo $$"); - var factory = BuildFactory(ShellYaml, client); - await using var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - - var tools = client.Requests[0].Options?.Tools ?? []; - Assert.Contains(tools, tool => tool.Name == RunShellToolName); - } - - [Fact] - public async Task PwdResult_ContainsTheConversationsWorkspace() - { - // ShellYaml's policy declares deny: only, no allow:. If AgentHarnessProviders.BuildPolicy - // ever stopped translating the empty allow: list to null, ShellPolicy would treat it as - // deny-all and this undenied pwd would come back rejected instead of succeeding. - var client = new ShellScriptedClient(RunShellToolName, "pwd", "rm -rf x", "echo $$"); - var factory = BuildFactory(ShellYaml, client); - await using var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - - Assert.Contains(session.Workspace!, client.ToolResults[0], StringComparison.Ordinal); - } - - [Fact] - public async Task RmResult_ComesBackAsRejectedText_NotAFailedTurn() - { - var client = new ShellScriptedClient(RunShellToolName, "pwd", "rm -rf x", "echo $$"); - var factory = BuildFactory(ShellYaml, client); - await using var session = factory.Create("conversation-1"); - - var turn = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - - Assert.Contains("rejected", client.ToolResults[1], StringComparison.OrdinalIgnoreCase); - Assert.Equal("done", turn.ReplyText); - } - - [Fact] - public async Task AfterTheConversationIsClosed_TheEchoPidIsGoneFromProc() - { - var client = new ShellScriptedClient(RunShellToolName, "pwd", "rm -rf x", "echo $$"); - var factory = BuildFactory(ShellYaml, client); - InMemoryConversationSessions sessions = new(factory, TimeSpan.FromMinutes(30), TimeProvider.System); - - var session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); - await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - - var pid = ParsePid(client.ToolResults[2]); - Assert.True(Directory.Exists($"/proc/{pid}"), "the bash should be alive before the conversation closes"); - - await sessions.CloseAsync("conversation-1", TestContext.Current.CancellationToken); - - await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); - } - - [Fact] - public async Task CloseAsync_WhenTheStoreThrowsOnFlush_StillDisposesTheShell() - { - // AgentCoreChatHistoryProvider.WriteAfterAsync catches every exception a store write - // raises and reports it through TranscriptWriteDropped, whose own contract is that it - // never throws back out — "the conversation outlives a store that refuses" — so FlushTranscriptAsync - // itself surfaces nothing here, which is today's behaviour: CloseAsync completes rather than - // throw. What this proves is the part that used to be at risk: even though the flush ate the - // fault silently, the shell this conversation started is still disposed once CloseAsync returns. - var store = new ThrowingConversationStore(); - var client = new ShellScriptedClient(RunShellToolName, "echo $$"); - var document = ConfigurationLoader.LoadYaml(ShellYaml); - var chatClients = new RoutingChatClientFactory(client); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { WorkspaceRoot = _root, ConversationStore = store })["main"]; - var factory = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); - InMemoryConversationSessions sessions = new(factory, TimeSpan.FromMinutes(30), TimeProvider.System); - - var session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); - await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - var pid = ParsePid(client.ToolResults[0]); - - await sessions.CloseAsync("conversation-1", TestContext.Current.CancellationToken); - - await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); - } - - [Fact] - public async Task ASecondConversationFromTheSameFactory_GetsADifferentPid() - { - var client = new ToolCallingChatClient( - "done", new Dictionary(StringComparer.Ordinal) { ["command"] = "echo $$" }); - var factory = BuildFactory(ShellYaml, client); - - await using var sessionA = factory.Create("conversation-a"); - await sessionA.RunTurnAsync("go", TestContext.Current.CancellationToken); - - await using var sessionB = factory.Create("conversation-b"); - await sessionB.RunTurnAsync("go", TestContext.Current.CancellationToken); - - var pidA = ParsePid(client.ToolResults[0]); - var pidB = ParsePid(client.ToolResults[1]); - - Assert.NotEqual(pidA, pidB); - } - - [Fact] - public async Task NoShellBlock_NoRunShellToolInTheRequest() - { - using SequencedChatClient reply = new("hello there."); - var factory = BuildFactory(NoShellYaml, reply); - await using var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - var toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; - Assert.DoesNotContain(RunShellToolName, toolNames); - Assert.DoesNotContain( - "## Shell environment", reply.Options[^1]?.Instructions ?? string.Empty, StringComparison.Ordinal); - } - - [Fact] - public async Task ATurnThatReachesATerminalStage_DisposesTheShellWithoutCloseAsync() - { - var client = new ShellScriptedClient(RunShellToolName, "echo $$"); - var factory = BuildFactory(TerminalShellYaml, client); - var session = factory.Create("conversation-1"); - - var turn = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - Assert.True(turn.IsTerminal); - - var pid = ParsePid(client.ToolResults[0]); - - await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); - } - - [Fact] - public async Task FirstRequest_CarriesShellEnvironmentInstructions_NamingTheConversationsWorkspace() - { - var client = new ShellScriptedClient(RunShellToolName, "pwd"); - var factory = BuildFactory(ShellYaml, client); - await using var session = factory.Create("conversation-1"); - - await session.RunTurnAsync("go", TestContext.Current.CancellationToken); - - var instructions = client.Requests[0].Options?.Instructions; - Assert.Contains("## Shell environment", instructions, StringComparison.Ordinal); - Assert.Contains(session.Workspace!, instructions, StringComparison.Ordinal); - } - - [Fact] - public async Task ASecondConversation_GetsItsOwnWorkspaceInItsInstructions() - { - var client = new ShellScriptedClient(RunShellToolName); - var factory = BuildFactory(ShellYaml, client); - - await using var sessionA = factory.Create("conversation-a"); - await sessionA.RunTurnAsync("go", TestContext.Current.CancellationToken); - - await using var sessionB = factory.Create("conversation-b"); - await sessionB.RunTurnAsync("go", TestContext.Current.CancellationToken); - - var instructionsA = client.Requests[0].Options?.Instructions; - var instructionsB = client.Requests[1].Options?.Instructions; - - Assert.Contains(sessionA.Workspace!, instructionsA, StringComparison.Ordinal); - Assert.Contains(sessionB.Workspace!, instructionsB, StringComparison.Ordinal); - Assert.DoesNotContain(sessionB.Workspace!, instructionsA, StringComparison.Ordinal); - } - - /// - /// Reads the pid off the first line of a run_shell tool result: MAF's own formatting - /// appends an exit_code: line after the command's stdout. - /// - private static int ParsePid(string toolResult) => - int.Parse(toolResult.Split('\n', StringSplitOptions.TrimEntries)[0]); - - private static string ToolName() - { - var workspace = Directory.CreateTempSubdirectory("shell-tool-name-").FullName; - try - { - return new LocalShellExecutor(new LocalShellExecutorOptions - { - WorkingDirectory = workspace, - AcknowledgeUnsafe = true, - }).AsAIFunction(requireApproval: false).Name; - } - finally - { - Directory.Delete(workspace, recursive: true); - } - } - - private ConversationSessionFactory BuildFactory(string yaml, IChatClient client) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new RoutingChatClientFactory(client); - - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - workspaceRoot: _root); - } - - } + private readonly string _root = + Path.Combine(Path.GetTempPath(), "agentcore-shell-session-" + Guid.NewGuid().ToString("N")); + + /// The name the model sees for the shell tool, read off a throwaway real executor. + private static readonly string RunShellToolName = ToolName(); + + public void Dispose() + { + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } + } + + [Fact] + public async Task FirstRequest_ListsATool_NamedRunShell() + { + // One literal assertion, as the brief allows: it pins the name the model actually sees. + Assert.Equal("run_shell", RunShellToolName); + + ShellScriptedClient client = new(RunShellToolName, "pwd", "rm -rf x", "echo $$"); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + await using ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + + IList tools = client.Requests[0].Options?.Tools ?? []; + Assert.Contains(tools, tool => tool.Name == RunShellToolName); + } + + [Fact] + public async Task PwdResult_ContainsTheConversationsWorkspace() + { + // ShellYaml's policy declares deny: only, no allow:. If AgentHarnessProviders.BuildPolicy + // ever stopped translating the empty allow: list to null, ShellPolicy would treat it as + // deny-all and this undenied pwd would come back rejected instead of succeeding. + ShellScriptedClient client = new(RunShellToolName, "pwd", "rm -rf x", "echo $$"); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + await using ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + + Assert.Contains(session.Workspace!, client.ToolResults[0], StringComparison.Ordinal); + } + + [Fact] + public async Task RmResult_ComesBackAsRejectedText_NotAFailedTurn() + { + ShellScriptedClient client = new(RunShellToolName, "pwd", "rm -rf x", "echo $$"); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + await using ConversationSession session = factory.Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + + Assert.Contains("rejected", client.ToolResults[1], StringComparison.OrdinalIgnoreCase); + Assert.Equal("done", turn.ReplyText); + } + + [Fact] + public async Task AfterTheConversationIsClosed_TheEchoPidIsGoneFromProc() + { + ShellScriptedClient client = new(RunShellToolName, "pwd", "rm -rf x", "echo $$"); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + InMemoryConversationSessions sessions = new(factory, TimeSpan.FromMinutes(30), TimeProvider.System); + + ConversationSession session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + + int pid = ParsePid(client.ToolResults[2]); + Assert.True(Directory.Exists($"/proc/{pid}"), "the bash should be alive before the conversation closes"); + + await sessions.CloseAsync("conversation-1", TestContext.Current.CancellationToken); + + await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); + } + + [Fact] + public async Task CloseAsync_WhenTheStoreThrowsOnFlush_StillDisposesTheShell() + { + // AgentCoreChatHistoryProvider.WriteAfterAsync catches every exception a store write + // raises and reports it through TranscriptWriteDropped, whose own contract is that it + // never throws back out — "the conversation outlives a store that refuses" — so FlushTranscriptAsync + // itself surfaces nothing here, which is today's behaviour: CloseAsync completes rather than + // throw. What this proves is the part that used to be at risk: even though the flush ate the + // fault silently, the shell this conversation started is still disposed once CloseAsync returns. + ThrowingConversationStore store = new(); + ShellScriptedClient client = new(RunShellToolName, "echo $$"); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ShellYaml); + RoutingChatClientFactory chatClients = new(client); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { WorkspaceRoot = _root, ConversationStore = store })["main"]; + ConversationSessionFactory factory = new( + compiled, new GuardEvaluator(compiled.Configuration.Guards), workspaceRoot: _root); + InMemoryConversationSessions sessions = new(factory, TimeSpan.FromMinutes(30), TimeProvider.System); + + ConversationSession session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + int pid = ParsePid(client.ToolResults[0]); + + await sessions.CloseAsync("conversation-1", TestContext.Current.CancellationToken); + + await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); + } + + [Fact] + public async Task ASecondConversationFromTheSameFactory_GetsADifferentPid() + { + ToolCallingChatClient client = new( + "done", new Dictionary(StringComparer.Ordinal) { ["command"] = "echo $$" }); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + + await using ConversationSession sessionA = factory.Create("conversation-a"); + _ = await sessionA.RunTurnAsync("go", TestContext.Current.CancellationToken); + + await using ConversationSession sessionB = factory.Create("conversation-b"); + _ = await sessionB.RunTurnAsync("go", TestContext.Current.CancellationToken); + + int pidA = ParsePid(client.ToolResults[0]); + int pidB = ParsePid(client.ToolResults[1]); + + Assert.NotEqual(pidA, pidB); + } + + [Fact] + public async Task NoShellBlock_NoRunShellToolInTheRequest() + { + using SequencedChatClient reply = new("hello there."); + ConversationSessionFactory factory = BuildFactory(NoShellYaml, reply); + await using ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + string[] toolNames = reply.Options[^1]?.Tools?.Select(tool => tool.Name).ToArray() ?? []; + Assert.DoesNotContain(RunShellToolName, toolNames); + Assert.DoesNotContain( + "## Shell environment", reply.Options[^1]?.Instructions ?? string.Empty, StringComparison.Ordinal); + } + + [Fact] + public async Task ATurnThatReachesATerminalStage_DisposesTheShellWithoutCloseAsync() + { + ShellScriptedClient client = new(RunShellToolName, "echo $$"); + ConversationSessionFactory factory = BuildFactory(TerminalShellYaml, client); + ConversationSession session = factory.Create("conversation-1"); + + TurnResult turn = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + Assert.True(turn.IsTerminal); + + int pid = ParsePid(client.ToolResults[0]); + + await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); + } + + [Fact] + public async Task FirstRequest_CarriesShellEnvironmentInstructions_NamingTheConversationsWorkspace() + { + ShellScriptedClient client = new(RunShellToolName, "pwd"); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + await using ConversationSession session = factory.Create("conversation-1"); + + _ = await session.RunTurnAsync("go", TestContext.Current.CancellationToken); + + string? instructions = client.Requests[0].Options?.Instructions; + Assert.Contains("## Shell environment", instructions, StringComparison.Ordinal); + Assert.Contains(session.Workspace!, instructions, StringComparison.Ordinal); + } + + [Fact] + public async Task ASecondConversation_GetsItsOwnWorkspaceInItsInstructions() + { + ShellScriptedClient client = new(RunShellToolName); + ConversationSessionFactory factory = BuildFactory(ShellYaml, client); + + await using ConversationSession sessionA = factory.Create("conversation-a"); + _ = await sessionA.RunTurnAsync("go", TestContext.Current.CancellationToken); + + await using ConversationSession sessionB = factory.Create("conversation-b"); + _ = await sessionB.RunTurnAsync("go", TestContext.Current.CancellationToken); + + string? instructionsA = client.Requests[0].Options?.Instructions; + string? instructionsB = client.Requests[1].Options?.Instructions; + + Assert.Contains(sessionA.Workspace!, instructionsA, StringComparison.Ordinal); + Assert.Contains(sessionB.Workspace!, instructionsB, StringComparison.Ordinal); + Assert.DoesNotContain(sessionB.Workspace!, instructionsA, StringComparison.Ordinal); + } + + /// + /// Reads the pid off the first line of a run_shell tool result: MAF's own formatting + /// appends an exit_code: line after the command's stdout. + /// + private static int ParsePid(string toolResult) + { + return int.Parse(toolResult.Split('\n', StringSplitOptions.TrimEntries)[0]); + } + + private static string ToolName() + { + string workspace = Directory.CreateTempSubdirectory("shell-tool-name-").FullName; + try + { + return new LocalShellExecutor(new LocalShellExecutorOptions + { + WorkingDirectory = workspace, + AcknowledgeUnsafe = true, + }).AsAIFunction(requireApproval: false).Name; + } + finally + { + Directory.Delete(workspace, recursive: true); + } + } + + private ConversationSessionFactory BuildFactory(string yaml, IChatClient client) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(client); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { WorkspaceRoot = _root })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + workspaceRoot: _root); + } + + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationShellsTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationShellsTests.cs index 26fdf0b8..c588d007 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationShellsTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ConversationShellsTests.cs @@ -1,223 +1,224 @@ +using System.Diagnostics; using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Harness; using Microsoft.Agents.AI.Tools.Shell; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// : one executor per instance, created on -/// first ask, torn down together. -/// -public sealed class ConversationShellsTests : IDisposable +namespace AgentCore.Application.Tests.Runtime.Harness { - private readonly string _workspace = - Directory.CreateTempSubdirectory("conversation-shells-tests-").FullName; - - public void Dispose() + /// + /// : one executor per instance, created on + /// first ask, torn down together. + /// + public sealed class ConversationShellsTests : IDisposable { - try - { - Directory.Delete(_workspace, recursive: true); - } - catch (IOException) + private readonly string _workspace = + Directory.CreateTempSubdirectory("conversation-shells-tests-").FullName; + + public void Dispose() { + try + { + Directory.Delete(_workspace, recursive: true); + } + catch (IOException) + { + } } - } - [Fact] - public async Task Get_Local_RunsInTheConversationsWorkspace() - { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); + [Fact] + public async Task Get_Local_RunsInTheConversationsWorkspace() + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); - var result = await shells.Get(options).RunAsync("pwd", TestContext.Current.CancellationToken); + ShellResult result = await shells.Get(options).RunAsync("pwd", TestContext.Current.CancellationToken); - var expected = new DirectoryInfo(_workspace).FullName.TrimEnd('/'); - Assert.Contains(expected, result.Stdout, StringComparison.Ordinal); - } + string expected = new DirectoryInfo(_workspace).FullName.TrimEnd('/'); + Assert.Contains(expected, result.Stdout, StringComparison.Ordinal); + } - [Fact] - public async Task Get_Local_TimeoutSignalsWithoutThrowing_AndReturnsUnder3Seconds() - { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: TimeSpan.FromSeconds(1)); + [Fact] + public async Task Get_Local_TimeoutSignalsWithoutThrowing_AndReturnsUnder3Seconds() + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: TimeSpan.FromSeconds(1)); - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - var result = await shells.Get(options).RunAsync("sleep 3", TestContext.Current.CancellationToken); - stopwatch.Stop(); + Stopwatch stopwatch = Stopwatch.StartNew(); + ShellResult result = await shells.Get(options).RunAsync("sleep 3", TestContext.Current.CancellationToken); + stopwatch.Stop(); - Assert.True(stopwatch.Elapsed < TimeSpan.FromSeconds(3), - $"expected the timed-out run to return in under 3s; took {stopwatch.Elapsed}"); - Assert.True(result is { TimedOut: true, ExitCode: 124 }, - $"expected TimedOut=true and ExitCode=124; got TimedOut={result.TimedOut}, ExitCode={result.ExitCode}"); - } + Assert.True(stopwatch.Elapsed < TimeSpan.FromSeconds(3), + $"expected the timed-out run to return in under 3s; took {stopwatch.Elapsed}"); + Assert.True(result is { TimedOut: true, ExitCode: 124 }, + $"expected TimedOut=true and ExitCode=124; got TimedOut={result.TimedOut}, ExitCode={result.ExitCode}"); + } - [Fact] - public async Task Get_Local_DenyPolicyRejectsTheCommand_AndTheFileSurvives() - { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new( - ShellKind.Local, new ShellPolicy(denyList: ["^rm "]), Timeout: null); + [Fact] + public async Task Get_Local_DenyPolicyRejectsTheCommand_AndTheFileSurvives() + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new( + ShellKind.Local, new ShellPolicy(denyList: ["^rm "]), Timeout: null); - var file = Path.Combine(_workspace, "keepme.txt"); - await File.WriteAllTextAsync(file, "do not delete", TestContext.Current.CancellationToken); + string file = Path.Combine(_workspace, "keepme.txt"); + await File.WriteAllTextAsync(file, "do not delete", TestContext.Current.CancellationToken); - await Assert.ThrowsAsync( - () => shells.Get(options).RunAsync($"rm -f {file}", TestContext.Current.CancellationToken)); + _ = await Assert.ThrowsAsync( + () => shells.Get(options).RunAsync($"rm -f {file}", TestContext.Current.CancellationToken)); - Assert.True(File.Exists(file)); - } + Assert.True(File.Exists(file)); + } - [Fact] - public async Task Get_NullAllowListPlusOneDeny_AllowsWhatItDoesNotDeny() - { - // This proves ShellPolicy's own semantics directly, at the ConversationShells layer: a null - // allowList disables the allow check entirely, so only the deny list refuses a command. - // ShellPolicy also treats a supplied-but-empty allow list as deny-all (per its own remarks), - // which is why AgentHarnessProviders.BuildPolicy must translate an agent's empty allow: into - // null rather than pass it through — that compile-time translation, and the end-to-end - // consequence of getting it wrong (an undenied command like pwd being refused), is proven in - // ConversationSessionShellTests (a shell: policy with deny: and no allow: still lets pwd run). - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new( - ShellKind.Local, new ShellPolicy(denyList: ["^rm "], allowList: null), Timeout: null); - - var ok = await shells.Get(options).RunAsync("echo hi", TestContext.Current.CancellationToken); - Assert.Contains("hi", ok.Stdout, StringComparison.Ordinal); - - await Assert.ThrowsAsync( - () => shells.Get(options).RunAsync("rm -f x", TestContext.Current.CancellationToken)); - } + [Fact] + public async Task Get_NullAllowListPlusOneDeny_AllowsWhatItDoesNotDeny() + { + // This proves ShellPolicy's own semantics directly, at the ConversationShells layer: a null + // allowList disables the allow check entirely, so only the deny list refuses a command. + // ShellPolicy also treats a supplied-but-empty allow list as deny-all (per its own remarks), + // which is why AgentHarnessProviders.BuildPolicy must translate an agent's empty allow: into + // null rather than pass it through — that compile-time translation, and the end-to-end + // consequence of getting it wrong (an undenied command like pwd being refused), is proven in + // ConversationSessionShellTests (a shell: policy with deny: and no allow: still lets pwd run). + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new( + ShellKind.Local, new ShellPolicy(denyList: ["^rm "], allowList: null), Timeout: null); - [Fact] - public async Task Get_SameOptionsTwice_ReturnsTheSameExecutorInstance() - { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); + ShellResult ok = await shells.Get(options).RunAsync("echo hi", TestContext.Current.CancellationToken); + Assert.Contains("hi", ok.Stdout, StringComparison.Ordinal); - var first = shells.Get(options); - var second = shells.Get(options); + _ = await Assert.ThrowsAsync( + () => shells.Get(options).RunAsync("rm -f x", TestContext.Current.CancellationToken)); + } - Assert.Same(first, second); - } + [Fact] + public async Task Get_SameOptionsTwice_ReturnsTheSameExecutorInstance() + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); - [Fact] - public async Task Get_TwoDifferentOptions_ReturnsTwoDifferentExecutors() - { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions a = new(ShellKind.Local, Policy: null, Timeout: null); - ConversationShellOptions b = new(ShellKind.Local, Policy: null, Timeout: null); + ShellExecutor first = shells.Get(options); + ShellExecutor second = shells.Get(options); - Assert.NotSame(shells.Get(a), shells.Get(b)); - } + Assert.Same(first, second); + } - [Fact] - public async Task DisposeAsync_TwiceIsFine_AndKillsTheLocalBash() - { - ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); + [Fact] + public async Task Get_TwoDifferentOptions_ReturnsTwoDifferentExecutors() + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions a = new(ShellKind.Local, Policy: null, Timeout: null); + ConversationShellOptions b = new(ShellKind.Local, Policy: null, Timeout: null); - var pidResult = await shells.Get(options).RunAsync("echo $$", TestContext.Current.CancellationToken); - var pid = int.Parse(pidResult.Stdout.Trim()); - Assert.True(Directory.Exists($"/proc/{pid}"), "the bash should be alive before dispose"); + Assert.NotSame(shells.Get(a), shells.Get(b)); + } - await shells.DisposeAsync(); - await shells.DisposeAsync(); + [Fact] + public async Task DisposeAsync_TwiceIsFine_AndKillsTheLocalBash() + { + ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); - await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); - } + ShellResult pidResult = await shells.Get(options).RunAsync("echo $$", TestContext.Current.CancellationToken); + int pid = int.Parse(pidResult.Stdout.Trim()); + Assert.True(Directory.Exists($"/proc/{pid}"), "the bash should be alive before dispose"); - [Fact] - public async Task Get_AfterDispose_ThrowsObjectDisposedException() - { - ConversationShells shells = new(_workspace, logger: null); - await shells.DisposeAsync(); + await shells.DisposeAsync(); + await shells.DisposeAsync(); - Assert.Throws( - () => shells.Get(new ConversationShellOptions(ShellKind.Local, Policy: null, Timeout: null))); - } + await ProcHelpers.AssertGoneAsync(pid, TestContext.Current.CancellationToken); + } - [Fact] - public async Task Get_Local_CleanEnvironment_DropsTheHostsCanaryButKeepsPathAndADeclaredEnvVar() - { - Environment.SetEnvironmentVariable("AGENTCORE_TEST_CANARY", "leaked"); - try + [Fact] + public async Task Get_AfterDispose_ThrowsObjectDisposedException() { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new( - ShellKind.Local, - Policy: null, - Timeout: null, - Env: new Dictionary { ["PROBE_OK"] = "yes" }); - - var canary = await shells.Get(options).RunAsync( - "echo \"c=$AGENTCORE_TEST_CANARY\"", TestContext.Current.CancellationToken); - Assert.Equal("c=", canary.Stdout.Trim()); + ConversationShells shells = new(_workspace, logger: null); + await shells.DisposeAsync(); - var declared = await shells.Get(options).RunAsync( - "echo $PROBE_OK", TestContext.Current.CancellationToken); - Assert.Equal("yes", declared.Stdout.Trim()); - - var path = await shells.Get(options).RunAsync("ls / >/dev/null && echo ok", TestContext.Current.CancellationToken); - Assert.Equal("ok", path.Stdout.Trim()); + _ = Assert.Throws( + () => shells.Get(new ConversationShellOptions(ShellKind.Local, Policy: null, Timeout: null))); } - finally + + [Fact] + public async Task Get_Local_CleanEnvironment_DropsTheHostsCanaryButKeepsPathAndADeclaredEnvVar() { - Environment.SetEnvironmentVariable("AGENTCORE_TEST_CANARY", null); + Environment.SetEnvironmentVariable("AGENTCORE_TEST_CANARY", "leaked"); + try + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new( + ShellKind.Local, + Policy: null, + Timeout: null, + Env: new Dictionary { ["PROBE_OK"] = "yes" }); + + ShellResult canary = await shells.Get(options).RunAsync( + "echo \"c=$AGENTCORE_TEST_CANARY\"", TestContext.Current.CancellationToken); + Assert.Equal("c=", canary.Stdout.Trim()); + + ShellResult declared = await shells.Get(options).RunAsync( + "echo $PROBE_OK", TestContext.Current.CancellationToken); + Assert.Equal("yes", declared.Stdout.Trim()); + + ShellResult path = await shells.Get(options).RunAsync("ls / >/dev/null && echo ok", TestContext.Current.CancellationToken); + Assert.Equal("ok", path.Stdout.Trim()); + } + finally + { + Environment.SetEnvironmentVariable("AGENTCORE_TEST_CANARY", null); + } } - } - [Fact] - public async Task Get_Docker_ReturnsADockerShellExecutor_WithNoDockerNeeded() - { - // DockerShellExecutor construction is lazy: it never talks to docker until RunAsync, so this - // needs no docker binary on the test host. - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Docker, Policy: null, Timeout: null); + [Fact] + public async Task Get_Docker_ReturnsADockerShellExecutor_WithNoDockerNeeded() + { + // DockerShellExecutor construction is lazy: it never talks to docker until RunAsync, so this + // needs no docker binary on the test host. + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Docker, Policy: null, Timeout: null); - var executor = shells.Get(options); + ShellExecutor executor = shells.Get(options); - Assert.IsType(executor); - } + _ = Assert.IsType(executor); + } - [Fact] - public async Task GetEnvironmentAsync_ProbesThroughThisConversationsExecutor_AndCachesTheSnapshot() - { - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); + [Fact] + public async Task GetEnvironmentAsync_ProbesThroughThisConversationsExecutor_AndCachesTheSnapshot() + { + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Local, Policy: null, Timeout: null); - var first = await shells.GetEnvironmentAsync(options, TestContext.Current.CancellationToken); - var second = await shells.GetEnvironmentAsync(options, TestContext.Current.CancellationToken); + ShellEnvironmentSnapshot first = await shells.GetEnvironmentAsync(options, TestContext.Current.CancellationToken); + ShellEnvironmentSnapshot second = await shells.GetEnvironmentAsync(options, TestContext.Current.CancellationToken); - Assert.Same(first, second); - Assert.Contains( - new DirectoryInfo(_workspace).FullName, first.WorkingDirectory, StringComparison.Ordinal); - } + Assert.Same(first, second); + Assert.Contains( + new DirectoryInfo(_workspace).FullName, first.WorkingDirectory, StringComparison.Ordinal); + } - [Fact] - public async Task GetEnvironmentAsync_WithADenyAllPolicy_StillReturnsARenderableSnapshot() - { - // Every probe a deny-all policy refuses comes back a null field rather than a throw - // (MAF's own swallowing), so the instructions still render their header. - await using ConversationShells shells = new(_workspace, logger: null); - ConversationShellOptions options = new(ShellKind.Local, new ShellPolicy(denyList: ["^."]), Timeout: null); + [Fact] + public async Task GetEnvironmentAsync_WithADenyAllPolicy_StillReturnsARenderableSnapshot() + { + // Every probe a deny-all policy refuses comes back a null field rather than a throw + // (MAF's own swallowing), so the instructions still render their header. + await using ConversationShells shells = new(_workspace, logger: null); + ConversationShellOptions options = new(ShellKind.Local, new ShellPolicy(denyList: ["^."]), Timeout: null); - var snapshot = await shells.GetEnvironmentAsync(options, TestContext.Current.CancellationToken); - var text = ShellEnvironmentProvider.DefaultInstructionsFormatter(snapshot); + ShellEnvironmentSnapshot snapshot = await shells.GetEnvironmentAsync(options, TestContext.Current.CancellationToken); + string text = ShellEnvironmentProvider.DefaultInstructionsFormatter(snapshot); - Assert.StartsWith("## Shell environment", text, StringComparison.Ordinal); - } + Assert.StartsWith("## Shell environment", text, StringComparison.Ordinal); + } - [Fact] - public async Task GetEnvironmentAsync_AfterDispose_ThrowsObjectDisposedException() - { - ConversationShells shells = new(_workspace, logger: null); - await shells.DisposeAsync(); + [Fact] + public async Task GetEnvironmentAsync_AfterDispose_ThrowsObjectDisposedException() + { + ConversationShells shells = new(_workspace, logger: null); + await shells.DisposeAsync(); - await Assert.ThrowsAsync(() => shells.GetEnvironmentAsync( - new ConversationShellOptions(ShellKind.Local, Policy: null, Timeout: null), - TestContext.Current.CancellationToken)); + _ = await Assert.ThrowsAsync(() => shells.GetEnvironmentAsync( + new ConversationShellOptions(ShellKind.Local, Policy: null, Timeout: null), + TestContext.Current.CancellationToken)); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/HarnessSessionStateTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/HarnessSessionStateTests.cs index 91527598..b18b3f4e 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/HarnessSessionStateTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/HarnessSessionStateTests.cs @@ -1,72 +1,70 @@ using System.Text.Json; -using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Harness; using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// and — the two -/// halves of moving MAF's per-provider state bag beside ConversationSessionState. -/// -public sealed class HarnessSessionStateTests +namespace AgentCore.Application.Tests.Runtime.Harness { - [Fact] - public void Capture_NullSession_IsEmpty() - => Assert.Empty(HarnessSessionState.Capture(null, new HashSet(StringComparer.Ordinal) { "TodoProvider" })); - - [Fact] - public void Capture_EmptyKeys_IsEmpty() + /// + /// and — the two + /// halves of moving MAF's per-provider state bag beside ConversationSessionState. + /// + public sealed class HarnessSessionStateTests { - var element = JsonDocument.Parse("""{"TodoProvider":{"items":[],"nextId":1}}""").RootElement; - var session = new TestAgentSession(AgentSessionStateBag.Deserialize(element)); + [Fact] + public void Capture_NullSession_IsEmpty() + { + Assert.Empty(HarnessSessionState.Capture(null, new HashSet(StringComparer.Ordinal) { "TodoProvider" })); + } - Assert.Empty(HarnessSessionState.Capture(session, new HashSet(StringComparer.Ordinal))); - } + [Fact] + public void Capture_EmptyKeys_IsEmpty() + { + JsonElement element = JsonDocument.Parse("""{"TodoProvider":{"items":[],"nextId":1}}""").RootElement; + TestAgentSession session = new(AgentSessionStateBag.Deserialize(element)); - [Fact] - public void Capture_KeepsOnlyTheNamedKeys_AndClonesTheirRawText() - { - const string TodoJson = """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}"""; - var element = JsonDocument.Parse( - """{"TodoProvider":""" + TodoJson + ""","SomeForeignProvider":{"anything":1}}""").RootElement; + Assert.Empty(HarnessSessionState.Capture(session, new HashSet(StringComparer.Ordinal))); + } - var session = new TestAgentSession(AgentSessionStateBag.Deserialize(element)); - var keys = new HashSet(StringComparer.Ordinal) { "TodoProvider" }; + [Fact] + public void Capture_KeepsOnlyTheNamedKeys_AndClonesTheirRawText() + { + const string TodoJson = """{"items":[{"id":1,"title":"buy milk","isComplete":false}],"nextId":2}"""; + JsonElement element = JsonDocument.Parse( + """{"TodoProvider":""" + TodoJson + ""","SomeForeignProvider":{"anything":1}}""").RootElement; - var captured = HarnessSessionState.Capture(session, keys); + TestAgentSession session = new(AgentSessionStateBag.Deserialize(element)); + HashSet keys = new(StringComparer.Ordinal) { "TodoProvider" }; - var key = Assert.Single(captured.Keys); - Assert.Equal("TodoProvider", key); - Assert.Equal( - JsonDocument.Parse(TodoJson).RootElement.GetRawText(), - captured["TodoProvider"].GetRawText()); - } + IReadOnlyDictionary captured = HarnessSessionState.Capture(session, keys); - [Fact] - public void Wrap_OneKey_ProducesTheStateBagEnvelope() - { - var element = JsonDocument.Parse("""{"items":[],"nextId":1}""").RootElement; - var providers = new Dictionary(StringComparer.Ordinal) { ["TodoProvider"] = element }; + string key = Assert.Single(captured.Keys); + Assert.Equal("TodoProvider", key); + Assert.Equal( + JsonDocument.Parse(TodoJson).RootElement.GetRawText(), + captured["TodoProvider"].GetRawText()); + } + + [Fact] + public void Wrap_OneKey_ProducesTheStateBagEnvelope() + { + JsonElement element = JsonDocument.Parse("""{"items":[],"nextId":1}""").RootElement; + Dictionary providers = new(StringComparer.Ordinal) { ["TodoProvider"] = element }; - var wrapped = HarnessSessionState.Wrap(providers); + JsonElement wrapped = HarnessSessionState.Wrap(providers); - Assert.Equal( - JsonSerializer.Serialize(new Dictionary - { - ["stateBag"] = new Dictionary + Assert.Equal( + JsonSerializer.Serialize(new Dictionary { - ["TodoProvider"] = new Dictionary { ["items"] = Array.Empty(), ["nextId"] = 1 }, - }, - }), - wrapped.GetRawText()); - } + ["stateBag"] = new Dictionary + { + ["TodoProvider"] = new Dictionary { ["items"] = Array.Empty(), ["nextId"] = 1 }, + }, + }), + wrapped.GetRawText()); + } - private sealed class TestAgentSession : AgentSession - { - public TestAgentSession(AgentSessionStateBag stateBag) - : base(stateBag) + private sealed class TestAgentSession(AgentSessionStateBag stateBag) : AgentSession(stateBag) { } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/ProcHelpers.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/ProcHelpers.cs index e504d0db..444125dd 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/ProcHelpers.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/ProcHelpers.cs @@ -1,33 +1,36 @@ using Xunit; -namespace AgentCore.Application.Tests.Runtime.Harness; - -/// -/// Waits for a Linux process to actually be gone, instead of guessing a fixed delay: dispose is -/// async but the OS reaping a killed process is not synchronous with it. -/// -internal static class ProcHelpers +namespace AgentCore.Application.Tests.Runtime.Harness { - private static readonly TimeSpan Timeout = TimeSpan.FromSeconds(2); - - private static readonly TimeSpan PollInterval = TimeSpan.FromMilliseconds(20); - /// - /// Polls /proc/<pid> until the process is gone or a zombie, up to , - /// then asserts it. + /// Waits for a Linux process to actually be gone, instead of guessing a fixed delay: dispose is + /// async but the OS reaping a killed process is not synchronous with it. /// - public static async Task AssertGoneAsync(int pid, CancellationToken cancellationToken) + internal static class ProcHelpers { - var deadline = DateTime.UtcNow + Timeout; + private static readonly TimeSpan Timeout = TimeSpan.FromSeconds(2); - while (!IsGone(pid) && DateTime.UtcNow < deadline) + private static readonly TimeSpan PollInterval = TimeSpan.FromMilliseconds(20); + + /// + /// Polls /proc/<pid> until the process is gone or a zombie, up to , + /// then asserts it. + /// + public static async Task AssertGoneAsync(int pid, CancellationToken cancellationToken) { - await Task.Delay(PollInterval, cancellationToken); + DateTime deadline = DateTime.UtcNow + Timeout; + + while (!IsGone(pid) && DateTime.UtcNow < deadline) + { + await Task.Delay(PollInterval, cancellationToken); + } + + Assert.True(IsGone(pid), $"the bash pid {pid} should be gone (or a zombie) within {Timeout}"); } - Assert.True(IsGone(pid), $"the bash pid {pid} should be gone (or a zombie) within {Timeout}"); + private static bool IsGone(int pid) + { + return !Directory.Exists($"/proc/{pid}") || File.ReadAllText($"/proc/{pid}/stat").Contains(" Z "); + } } - - private static bool IsGone(int pid) => - !Directory.Exists($"/proc/{pid}") || File.ReadAllText($"/proc/{pid}/stat").Contains(" Z "); } diff --git a/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughConversationSessionTests.cs b/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughConversationSessionTests.cs index 4049d7a3..7657b7f4 100644 --- a/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughConversationSessionTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughConversationSessionTests.cs @@ -10,29 +10,29 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The one wiring a host can actually write: set a knowledge scope on the session, run a turn, -/// and have the scope still be there when the retrieval delegate reads it. -/// -/// -/// -/// Every other test of the scope sets it and reads it back without a turn loop in between, and -/// every one of them passed while the feature was wired shut: the loop built its turn without the -/// session's scope, so the store never saw it. The defect lives in the interaction, so the test -/// has to run the interaction. -/// -/// -/// The agent here is scoped: true, which makes the erasure visible twice over: the provider's -/// own gate refuses to call the store at all with no scope set, so a broken carry-through shows up -/// as a store nobody searched as well as a scope nobody could read. -/// -/// -public sealed class KnowledgeScopeThroughConversationSessionTests +namespace AgentCore.Application.Tests.Runtime { - private const string Yaml = - """ + /// + /// The one wiring a host can actually write: set a knowledge scope on the session, run a turn, + /// and have the scope still be there when the retrieval delegate reads it. + /// + /// + /// + /// Every other test of the scope sets it and reads it back without a turn loop in between, and + /// every one of them passed while the feature was wired shut: the loop built its turn without the + /// session's scope, so the store never saw it. The defect lives in the interaction, so the test + /// has to run the interaction. + /// + /// + /// The agent here is scoped: true, which makes the erasure visible twice over: the provider's + /// own gate refuses to call the store at all with no scope set, so a broken carry-through shows up + /// as a store nobody searched as well as a scope nobody could read. + /// + /// + public sealed class KnowledgeScopeThroughConversationSessionTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 agents: items: @@ -47,15 +47,15 @@ public sealed class KnowledgeScopeThroughConversationSessionTests - { id: greeting, agent: only } """; - /// - /// The document the three Scope_ facts run against. Unlike , it declares - /// providers.knowledge.scope, so StateKnowledgeScope.Compose builds a scope from - /// state rather than passing the host's ambient through unchanged — which is why the two - /// RunTurnAsync_UnderAHostScope_ facts above must keep using the plain : - /// their Assert.Same needs the ambient untouched. - /// - private const string ScopedYaml = - """ + /// + /// The document the three Scope_ facts run against. Unlike , it declares + /// providers.knowledge.scope, so StateKnowledgeScope.Compose builds a scope from + /// state rather than passing the host's ambient through unchanged — which is why the two + /// RunTurnAsync_UnderAHostScope_ facts above must keep using the plain : + /// their Assert.Same needs the ambient untouched. + /// + private const string ScopedYaml = + """ apiVersion: agentcore/v1 state: brand: { type: string, writer: extractor, enum: [sole, other] } @@ -90,188 +90,193 @@ public sealed class KnowledgeScopeThroughConversationSessionTests - { id: greeting, agent: only } """; - private StubKnowledgePort _port = null!; - - [Fact] - public async Task RunTurnAsync_UnderAHostScope_TheStoreStillSeesThatScope() - { - using SequencedChatClient reply = new("hello there."); - var port = new StubKnowledgePort([Card("a")]); - var session = Build(reply, port).Create("conversation-1"); - - var scope = Scope(); - session.Scope = scope; - await session.RunTurnAsync("the screen says e33", TestContext.Current.CancellationToken); - - Assert.Equal(1, port.Calls); - Assert.Same(scope, port.ScopeAtTheStore); - } - - [Fact] - public async Task RunTurnStreamingAsync_UnderAHostScope_TheStoreStillSeesThatScope() - { - // The streaming path runs the same turn through a second enumeration, so it needs its own - // fact rather than an argument from the non-streaming one. - using SequencedChatClient reply = new("hello there."); - var port = new StubKnowledgePort([Card("a")]); - var session = Build(reply, port).Create("conversation-2"); - - var scope = Scope(); - session.Scope = scope; - await foreach (var update in session - .RunTurnStreamingAsync("the screen says e33", TestContext.Current.CancellationToken)) - { - Assert.NotNull(update); - } - - Assert.Equal(1, port.Calls); - Assert.Same(scope, port.ScopeAtTheStore); - } - - [Fact] - public async Task RunTurnAsync_WithNoHostScope_LeavesTheAmbientAbsent() - { - // The counterpart fact. Carrying the scope through must not invent one: an unscoped host - // still reaches the provider's gate, and the agent is told it cannot look anything up. - using SequencedChatClient reply = new("hello there."); - var port = new StubKnowledgePort([Card("a")]); - var session = Build(reply, port).Create("conversation-3"); - - await session.RunTurnAsync("the screen says e33", TestContext.Current.CancellationToken); - - Assert.Equal(0, port.Calls); - } - - [Fact] - public async Task RunTurnAsync_AfterTheTurn_PutsBackWhatTheHostHadOpen() - { - // The turn loop opens ambients of its own over the host's. Closing them must restore the - // host's scope rather than clearing it, or a second turn of the same conversation runs unscoped. - using SequencedChatClient reply = new("hello there."); - var port = new StubKnowledgePort([Card("a")]); - var session = Build(reply, port).Create("conversation-4"); - - var scope = Scope(); - session.Scope = scope; - await session.RunTurnAsync("the screen says e33", TestContext.Current.CancellationToken); - - Assert.Same(scope, session.Scope); - } - - [Fact] - public async Task Scope_ResumedConversation_IsBuiltFromTheRestoredSlots() - { - // The host cannot do this itself: Restore runs inside OpenSessionAsync, which is the first - // statement of the run method, so session.State is empty until the turn has begun. - using SequencedChatClient reply = new("hello there."); - var session = ResumedSession(reply, stored: new Dictionary - { - ["brand"] = "sole", - ["applies_to"] = "f63", - }); - - await session.RunTurnAsync("is the belt covered?", TestContext.Current.CancellationToken); - - Assert.Equal("sole", _port.ScopeAtTheStore!.Facets["brand"]); - Assert.Equal("f63", _port.ScopeAtTheStore.Facets["applies_to"]); - } - - [Fact] - public async Task Scope_ResumedConversation_WithAnOffEnumSlot_LeavesThatSlotWildcard() - { - // "F63 Treadmill" is outside applies_to's enum: [f63, other], so Restore's TryWrite refuses - // it and the slot stays unfilled. Compose then reads it as the wildcard, same as a slot - // nothing ever wrote — the refused blob value never reaches the search filter. - using SequencedChatClient reply = new("hello there."); - var session = ResumedSession(reply, stored: new Dictionary - { - ["brand"] = "sole", - ["applies_to"] = "F63 Treadmill", - }); - - await session.RunTurnAsync("is the belt covered?", TestContext.Current.CancellationToken); - - Assert.Equal("sole", _port.ScopeAtTheStore!.Facets["brand"]); - Assert.Equal("*", _port.ScopeAtTheStore.Facets["applies_to"]); - } - - [Fact] - public async Task Scope_NothingKnown_IsAllWildcard() - { - using SequencedChatClient reply = new("hello there."); - var session = FreshSession(reply); - - await session.RunTurnAsync("what are your opening hours?", TestContext.Current.CancellationToken); - - Assert.Equal("*", _port.ScopeAtTheStore!.Facets["brand"]); - Assert.Equal("*", _port.ScopeAtTheStore.Facets["applies_to"]); - } - - [Fact] - public async Task Scope_StreamingTurn_ComposesTheSameScope() - { - // The streaming path drives the turn through its own entry point, so it needs its own - // fact rather than an argument from the single-shot one: the scope the store sees must - // match what a non-streaming turn composes. - using SequencedChatClient reply = new("hello there."); - var session = FreshSession(reply); - - await foreach (var _ in session.RunTurnStreamingAsync("what are your opening hours?", TestContext.Current.CancellationToken)) - { - } - - Assert.Equal("*", _port.ScopeAtTheStore!.Facets["brand"]); - Assert.Equal("*", _port.ScopeAtTheStore.Facets["applies_to"]); - } - - - private static ConversationSessionFactory Build(IChatClient reply, StubKnowledgePort port, string yaml = Yaml) - { - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port })["main"]; - - return new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); - } - - private ConversationSession FreshSession(IChatClient reply) - { - _port = new StubKnowledgePort([Card("a")]); - - return Build(reply, _port, ScopedYaml).Create("conversation-fresh"); - } - - private ConversationSession ResumedSession(IChatClient reply, IReadOnlyDictionary stored) - { - _port = new StubKnowledgePort([Card("a")]); - - // The real restore path: a ConversationSessionState of the shape store 0 hands back, fed through - // ConversationSessionFactory.Create so Resume/Restore write the slots, rather than the test poking - // session.State directly and skipping the coercion and enum checks Restore applies. - ConversationSessionState state = new() - { - Stage = "greeting", - Slots = stored.ToDictionary( - pair => pair.Key, - pair => (JsonNode?)JsonValue.Create(pair.Value), - StringComparer.Ordinal), - }; - - return Build(reply, _port, ScopedYaml).Create("conversation-resumed", state); - } - - private static KnowledgeScope Scope() - => new() { Facets = new Dictionary { ["model"] = "ct900" } }; - - private static KnowledgeCard Card(string id) - => new() - { - CardId = id, - Text = "card " + id, - Authority = 3, - SourceRef = "ct900-om", - SourceLocator = "p.27", - Score = 0.87, - ViaLink = false, - }; - } + private StubKnowledgePort _port = null!; + + [Fact] + public async Task RunTurnAsync_UnderAHostScope_TheStoreStillSeesThatScope() + { + using SequencedChatClient reply = new("hello there."); + StubKnowledgePort port = new([Card("a")]); + ConversationSession session = Build(reply, port).Create("conversation-1"); + + KnowledgeScope scope = Scope(); + session.Scope = scope; + _ = await session.RunTurnAsync("the screen says e33", TestContext.Current.CancellationToken); + + Assert.Equal(1, port.Calls); + Assert.Same(scope, port.ScopeAtTheStore); + } + + [Fact] + public async Task RunTurnStreamingAsync_UnderAHostScope_TheStoreStillSeesThatScope() + { + // The streaming path runs the same turn through a second enumeration, so it needs its own + // fact rather than an argument from the non-streaming one. + using SequencedChatClient reply = new("hello there."); + StubKnowledgePort port = new([Card("a")]); + ConversationSession session = Build(reply, port).Create("conversation-2"); + + KnowledgeScope scope = Scope(); + session.Scope = scope; + await foreach (ChatResponseUpdate update in session + .RunTurnStreamingAsync("the screen says e33", TestContext.Current.CancellationToken)) + { + Assert.NotNull(update); + } + + Assert.Equal(1, port.Calls); + Assert.Same(scope, port.ScopeAtTheStore); + } + + [Fact] + public async Task RunTurnAsync_WithNoHostScope_LeavesTheAmbientAbsent() + { + // The counterpart fact. Carrying the scope through must not invent one: an unscoped host + // still reaches the provider's gate, and the agent is told it cannot look anything up. + using SequencedChatClient reply = new("hello there."); + StubKnowledgePort port = new([Card("a")]); + ConversationSession session = Build(reply, port).Create("conversation-3"); + + _ = await session.RunTurnAsync("the screen says e33", TestContext.Current.CancellationToken); + + Assert.Equal(0, port.Calls); + } + + [Fact] + public async Task RunTurnAsync_AfterTheTurn_PutsBackWhatTheHostHadOpen() + { + // The turn loop opens ambients of its own over the host's. Closing them must restore the + // host's scope rather than clearing it, or a second turn of the same conversation runs unscoped. + using SequencedChatClient reply = new("hello there."); + StubKnowledgePort port = new([Card("a")]); + ConversationSession session = Build(reply, port).Create("conversation-4"); + + KnowledgeScope scope = Scope(); + session.Scope = scope; + _ = await session.RunTurnAsync("the screen says e33", TestContext.Current.CancellationToken); + + Assert.Same(scope, session.Scope); + } + + [Fact] + public async Task Scope_ResumedConversation_IsBuiltFromTheRestoredSlots() + { + // The host cannot do this itself: Restore runs inside OpenSessionAsync, which is the first + // statement of the run method, so session.State is empty until the turn has begun. + using SequencedChatClient reply = new("hello there."); + ConversationSession session = ResumedSession(reply, stored: new Dictionary + { + ["brand"] = "sole", + ["applies_to"] = "f63", + }); + + _ = await session.RunTurnAsync("is the belt covered?", TestContext.Current.CancellationToken); + + Assert.Equal("sole", _port.ScopeAtTheStore!.Facets["brand"]); + Assert.Equal("f63", _port.ScopeAtTheStore.Facets["applies_to"]); + } + + [Fact] + public async Task Scope_ResumedConversation_WithAnOffEnumSlot_LeavesThatSlotWildcard() + { + // "F63 Treadmill" is outside applies_to's enum: [f63, other], so Restore's TryWrite refuses + // it and the slot stays unfilled. Compose then reads it as the wildcard, same as a slot + // nothing ever wrote — the refused blob value never reaches the search filter. + using SequencedChatClient reply = new("hello there."); + ConversationSession session = ResumedSession(reply, stored: new Dictionary + { + ["brand"] = "sole", + ["applies_to"] = "F63 Treadmill", + }); + + _ = await session.RunTurnAsync("is the belt covered?", TestContext.Current.CancellationToken); + + Assert.Equal("sole", _port.ScopeAtTheStore!.Facets["brand"]); + Assert.Equal("*", _port.ScopeAtTheStore.Facets["applies_to"]); + } + + [Fact] + public async Task Scope_NothingKnown_IsAllWildcard() + { + using SequencedChatClient reply = new("hello there."); + ConversationSession session = FreshSession(reply); + + _ = await session.RunTurnAsync("what are your opening hours?", TestContext.Current.CancellationToken); + + Assert.Equal("*", _port.ScopeAtTheStore!.Facets["brand"]); + Assert.Equal("*", _port.ScopeAtTheStore.Facets["applies_to"]); + } + + [Fact] + public async Task Scope_StreamingTurn_ComposesTheSameScope() + { + // The streaming path drives the turn through its own entry point, so it needs its own + // fact rather than an argument from the single-shot one: the scope the store sees must + // match what a non-streaming turn composes. + using SequencedChatClient reply = new("hello there."); + ConversationSession session = FreshSession(reply); + + await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("what are your opening hours?", TestContext.Current.CancellationToken)) + { + } + + Assert.Equal("*", _port.ScopeAtTheStore!.Facets["brand"]); + Assert.Equal("*", _port.ScopeAtTheStore.Facets["applies_to"]); + } + + + private static ConversationSessionFactory Build(IChatClient reply, StubKnowledgePort port, string yaml = Yaml) + { + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port })["main"]; + + return new ConversationSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + } + + private ConversationSession FreshSession(IChatClient reply) + { + _port = new StubKnowledgePort([Card("a")]); + + return Build(reply, _port, ScopedYaml).Create("conversation-fresh"); + } + + private ConversationSession ResumedSession(IChatClient reply, IReadOnlyDictionary stored) + { + _port = new StubKnowledgePort([Card("a")]); + + // The real restore path: a ConversationSessionState of the shape store 0 hands back, fed through + // ConversationSessionFactory.Create so Resume/Restore write the slots, rather than the test poking + // session.State directly and skipping the coercion and enum checks Restore applies. + ConversationSessionState state = new() + { + Stage = "greeting", + Slots = stored.ToDictionary( + pair => pair.Key, + pair => (JsonNode?)JsonValue.Create(pair.Value), + StringComparer.Ordinal), + }; + + return Build(reply, _port, ScopedYaml).Create("conversation-resumed", state); + } + + private static KnowledgeScope Scope() + { + return new() { Facets = new Dictionary { ["model"] = "ct900" } }; + } + + private static KnowledgeCard Card(string id) + { + return new() + { + CardId = id, + Text = "card " + id, + Authority = 3, + SourceRef = "ct900-om", + SourceLocator = "p.27", + Score = 0.87, + ViaLink = false, + }; + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs b/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs index a853971e..e08c8109 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs @@ -4,109 +4,110 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// is the only seam that strips a -/// before the model reads it. Every assertion here is against what the fake inner -/// received, never against the returned response, because the strip must -/// happen to the outgoing request and nothing else. -/// -public sealed class ModelFacingChatClientTests +namespace AgentCore.Application.Tests.Runtime { - private static readonly JsonElement Payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); - - [Fact] - public async Task GetResponseAsync_StripsRenderContentBeforeTheInnerClientSeesIt() + /// + /// is the only seam that strips a + /// before the model reads it. Every assertion here is against what the fake inner + /// received, never against the returned response, because the strip must + /// happen to the outgoing request and nothing else. + /// + public sealed class ModelFacingChatClientTests { - var inner = new SequencedChatClient("ok"); - var client = new ModelFacingChatClient(inner); - var drew = new ChatMessage(ChatRole.Assistant, - [ - new TextContent("here you go"), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, - ]); - - await client.GetResponseAsync([drew], cancellationToken: TestContext.Current.CancellationToken); - - var forwarded = Assert.Single(inner.Requests); - var message = Assert.Single(forwarded); - Assert.DoesNotContain(message.Contents, c => c is RenderContent); - Assert.Single(message.Contents.OfType()); - } + private static readonly JsonElement Payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); - [Fact] - public async Task GetStreamingResponseAsync_StripsRenderContentBeforeTheInnerClientSeesIt() - { - var inner = new SequencedChatClient("ok"); - var client = new ModelFacingChatClient(inner); - var drew = new ChatMessage(ChatRole.Assistant, - [ - new TextContent("here you go"), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, - ]); - - await foreach (var _ in client.GetStreamingResponseAsync( - [drew], cancellationToken: TestContext.Current.CancellationToken)) + [Fact] + public async Task GetResponseAsync_StripsRenderContentBeforeTheInnerClientSeesIt() { + SequencedChatClient inner = new("ok"); + ModelFacingChatClient client = new(inner); + ChatMessage drew = new(ChatRole.Assistant, + [ + new TextContent("here you go"), + new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, + ]); + + _ = await client.GetResponseAsync([drew], cancellationToken: TestContext.Current.CancellationToken); + + List forwarded = Assert.Single(inner.Requests); + ChatMessage message = Assert.Single(forwarded); + Assert.DoesNotContain(message.Contents, c => c is RenderContent); + _ = Assert.Single(message.Contents.OfType()); } - var forwarded = Assert.Single(inner.Requests); - var message = Assert.Single(forwarded); - Assert.DoesNotContain(message.Contents, c => c is RenderContent); - } - - [Fact] - public async Task GetResponseAsync_PassesAMessageWithNoRenderContentThroughByReference() - { - var inner = new SequencedChatClient("ok"); - var client = new ModelFacingChatClient(inner); - var plain = new ChatMessage(ChatRole.User, "hello"); + [Fact] + public async Task GetStreamingResponseAsync_StripsRenderContentBeforeTheInnerClientSeesIt() + { + SequencedChatClient inner = new("ok"); + ModelFacingChatClient client = new(inner); + ChatMessage drew = new(ChatRole.Assistant, + [ + new TextContent("here you go"), + new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, + ]); + + await foreach (ChatResponseUpdate _ in client.GetStreamingResponseAsync( + [drew], cancellationToken: TestContext.Current.CancellationToken)) + { + } + + List forwarded = Assert.Single(inner.Requests); + ChatMessage message = Assert.Single(forwarded); + Assert.DoesNotContain(message.Contents, c => c is RenderContent); + } - await client.GetResponseAsync([plain], cancellationToken: TestContext.Current.CancellationToken); + [Fact] + public async Task GetResponseAsync_PassesAMessageWithNoRenderContentThroughByReference() + { + SequencedChatClient inner = new("ok"); + ModelFacingChatClient client = new(inner); + ChatMessage plain = new(ChatRole.User, "hello"); - var forwarded = Assert.Single(inner.Requests); - Assert.Same(plain, Assert.Single(forwarded)); - } + _ = await client.GetResponseAsync([plain], cancellationToken: TestContext.Current.CancellationToken); - [Fact] - public async Task GetStreamingResponseAsync_PassesAMessageWithNoRenderContentThroughByReference() - { - var inner = new SequencedChatClient("ok"); - var client = new ModelFacingChatClient(inner); - var plain = new ChatMessage(ChatRole.User, "hello"); + List forwarded = Assert.Single(inner.Requests); + Assert.Same(plain, Assert.Single(forwarded)); + } - await foreach (var _ in client.GetStreamingResponseAsync( - [plain], cancellationToken: TestContext.Current.CancellationToken)) + [Fact] + public async Task GetStreamingResponseAsync_PassesAMessageWithNoRenderContentThroughByReference() { - } + SequencedChatClient inner = new("ok"); + ModelFacingChatClient client = new(inner); + ChatMessage plain = new(ChatRole.User, "hello"); - var forwarded = Assert.Single(inner.Requests); - Assert.Same(plain, Assert.Single(forwarded)); - } + await foreach (ChatResponseUpdate _ in client.GetStreamingResponseAsync( + [plain], cancellationToken: TestContext.Current.CancellationToken)) + { + } - [Fact] - public async Task GetResponseAsync_RebuiltMessageCarriesAdditionalPropertiesAndIdentity() - { - var inner = new SequencedChatClient("ok"); - var client = new ModelFacingChatClient(inner); - var drew = new ChatMessage(ChatRole.Assistant, - [ - new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, - ]) + List forwarded = Assert.Single(inner.Requests); + Assert.Same(plain, Assert.Single(forwarded)); + } + + [Fact] + public async Task GetResponseAsync_RebuiltMessageCarriesAdditionalPropertiesAndIdentity() { - MessageId = "msg-1", - AuthorName = "assistant-1", - CreatedAt = DateTimeOffset.UnixEpoch, - AdditionalProperties = new AdditionalPropertiesDictionary { ["k"] = "v" }, - }; - - await client.GetResponseAsync([drew], cancellationToken: TestContext.Current.CancellationToken); - - var forwarded = Assert.Single(Assert.Single(inner.Requests)); - Assert.Equal("msg-1", forwarded.MessageId); - Assert.Equal("assistant-1", forwarded.AuthorName); - Assert.Equal(DateTimeOffset.UnixEpoch, forwarded.CreatedAt); - Assert.Equal("v", forwarded.AdditionalProperties?["k"]); + SequencedChatClient inner = new("ok"); + ModelFacingChatClient client = new(inner); + ChatMessage drew = new(ChatRole.Assistant, + [ + new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, + ]) + { + MessageId = "msg-1", + AuthorName = "assistant-1", + CreatedAt = DateTimeOffset.UnixEpoch, + AdditionalProperties = new AdditionalPropertiesDictionary { ["k"] = "v" }, + }; + + _ = await client.GetResponseAsync([drew], cancellationToken: TestContext.Current.CancellationToken); + + ChatMessage forwarded = Assert.Single(Assert.Single(inner.Requests)); + Assert.Equal("msg-1", forwarded.MessageId); + Assert.Equal("assistant-1", forwarded.AuthorName); + Assert.Equal(DateTimeOffset.UnixEpoch, forwarded.CreatedAt); + Assert.Equal("v", forwarded.AdditionalProperties?["k"]); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs b/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs index faf90aa0..ef799eee 100644 --- a/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs +++ b/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs @@ -5,708 +5,697 @@ using AgentCore.Application.Tools; using Microsoft.Extensions.AI; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// A clock a test owns. The turn loop reads conversationDurationSeconds from a -/// , so no test needs a stopwatch. -/// -internal sealed class TestTimeProvider : TimeProvider +namespace AgentCore.Application.Tests.Runtime { - private DateTimeOffset _now = new(2026, 1, 1, 12, 0, 0, TimeSpan.Zero); - - public override DateTimeOffset GetUtcNow() => _now; + /// + /// A clock a test owns. The turn loop reads conversationDurationSeconds from a + /// , so no test needs a stopwatch. + /// + internal sealed class TestTimeProvider : TimeProvider + { + private DateTimeOffset _now = new(2026, 1, 1, 12, 0, 0, TimeSpan.Zero); - /// Moves the clock forward. - public void Advance(TimeSpan span) => _now = _now.Add(span); -} + public override DateTimeOffset GetUtcNow() + { + return _now; + } -/// -/// A deterministic offline model that answers one reply for each request, in order. -/// -/// -/// The turn loop makes two model calls in one turn, the reply and the extractor, and they need -/// different answers. This client answers a list, and it holds the last answer once the list runs -/// out. -/// -internal sealed class SequencedChatClient : IChatClient -{ - private readonly string[] _replies; - private int _calls; + /// Moves the clock forward. + public void Advance(TimeSpan span) + { + _now = _now.Add(span); + } + } - public SequencedChatClient(params string[] replies) => _replies = replies; + /// + /// A deterministic offline model that answers one reply for each request, in order. + /// + /// + /// The turn loop makes two model calls in one turn, the reply and the extractor, and they need + /// different answers. This client answers a list, and it holds the last answer once the list runs + /// out. + /// + internal sealed class SequencedChatClient(params string[] replies) : IChatClient + { + private readonly string[] _replies = replies; + private int _calls; - /// Gets the messages of each request, in call order. - public List> Requests { get; } = []; + /// Gets the messages of each request, in call order. + public List> Requests { get; } = []; - /// Gets the options of each request, in call order. A ChatClientAgent sends its - /// instructions here rather than as a message. - public List Options { get; } = []; + /// Gets the options of each request, in call order. A ChatClientAgent sends its + /// instructions here rather than as a message. + public List Options { get; } = []; - /// Gets how many requests this client answered. - public int Calls => Volatile.Read(ref _calls); + /// Gets how many requests this client answered. + public int Calls => Volatile.Read(ref _calls); - /// Gets the text of the system messages of one request, joined by a newline. - public string SystemText(int request) - { - lock (Requests) + /// Gets the text of the system messages of one request, joined by a newline. + public string SystemText(int request) { - return string.Join( - '\n', - Requests[request].Where(message => message.Role == ChatRole.System).Select(message => message.Text)); + lock (Requests) + { + return string.Join( + '\n', + Requests[request].Where(message => message.Role == ChatRole.System).Select(message => message.Text)); + } } - } - /// Gets the text of the last user message of one request. - public string LastUserText(int request) - { - lock (Requests) + /// Gets the text of the last user message of one request. + public string LastUserText(int request) { - return Requests[request].LastOrDefault(message => message.Role == ChatRole.User)?.Text ?? string.Empty; + lock (Requests) + { + return Requests[request].LastOrDefault(message => message.Role == ChatRole.User)?.Text ?? string.Empty; + } } - } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - - var index = Interlocked.Increment(ref _calls) - 1; - lock (Requests) + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - Requests.Add([.. messages]); - Options.Add(options); - } + ArgumentNullException.ThrowIfNull(messages); + + int index = Interlocked.Increment(ref _calls) - 1; + lock (Requests) + { + Requests.Add([.. messages]); + Options.Add(options); + } + + await Task.Yield(); - await Task.Yield(); + string responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, _replies[Math.Min(index, _replies.Length - 1)]) + { + ResponseId = responseId, + MessageId = responseId, + }; + } - var responseId = Guid.NewGuid().ToString("N"); - yield return new ChatResponseUpdate(ChatRole.Assistant, _replies[Math.Min(index, _replies.Length - 1)]) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); + public void Dispose() + { + // Nothing to release. + } } - public object? GetService(Type serviceType, object? serviceKey = null) + /// + /// A model that yields lifecycle updates between its text fragments. + /// + /// + /// Section 8.6 measured AsAIAgent(): 47 updates for 40 text fragments, and seven of them carry + /// no content. This client reproduces both empty shapes, an update with no content at all and an + /// update whose only content is empty text, so a test proves the seam drops them. + /// + internal sealed class LifecycleChatClient(params string[] fragments) : IChatClient { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + private readonly string[] _fragments = fragments; - public void Dispose() - { - // Nothing to release. - } -} + /// Gets how many updates this client yields, content and lifecycle together. + public int Yielded { get; private set; } -/// -/// A model that yields lifecycle updates between its text fragments. -/// -/// -/// Section 8.6 measured AsAIAgent(): 47 updates for 40 text fragments, and seven of them carry -/// no content. This client reproduces both empty shapes, an update with no content at all and an -/// update whose only content is empty text, so a test proves the seam drops them. -/// -internal sealed class LifecycleChatClient : IChatClient -{ - private readonly string[] _fragments; + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - public LifecycleChatClient(params string[] fragments) => _fragments = fragments; + string responseId = Guid.NewGuid().ToString("N"); + Yielded = 0; - /// Gets how many updates this client yields, content and lifecycle together. - public int Yielded { get; private set; } + foreach (string fragment in _fragments) + { + // A lifecycle event. It carries nothing at all. + Yielded++; + yield return new ChatResponseUpdate { ResponseId = responseId, MessageId = responseId }; - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + Yielded++; + yield return new ChatResponseUpdate(ChatRole.Assistant, fragment) + { + ResponseId = responseId, + MessageId = responseId, + }; - var responseId = Guid.NewGuid().ToString("N"); - Yielded = 0; + // The other empty shape: one content, and it holds no text. + Yielded++; + yield return new ChatResponseUpdate(ChatRole.Assistant, string.Empty) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + } - foreach (var fragment in _fragments) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - // A lifecycle event. It carries nothing at all. - Yielded++; - yield return new ChatResponseUpdate { ResponseId = responseId, MessageId = responseId }; - - Yielded++; - yield return new ChatResponseUpdate(ChatRole.Assistant, fragment) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - ResponseId = responseId, - MessageId = responseId, - }; + updates.Add(update); + } - // The other empty shape: one content, and it holds no text. - Yielded++; - yield return new ChatResponseUpdate(ChatRole.Assistant, string.Empty) - { - ResponseId = responseId, - MessageId = responseId, - }; + return updates.ToChatResponse(); } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public void Dispose() + { + // Nothing to release. + } } - public void Dispose() + /// + /// A model that calls the first tool it is offered on every request, and never answers with text. + /// + /// + /// conversations one tool once, which keeps a healthy run finite. Section + /// 8.7 needs the other case: a tool that keeps failing. This client never stops calling, so the run + /// spends the error budget of MaximumConsecutiveErrorsPerRequest and the 4th failure throws. + /// + internal sealed class LoopingToolCallingChatClient : IChatClient { - // Nothing to release. - } -} + private int _calls; -/// -/// A model that calls the first tool it is offered on every request, and never answers with text. -/// -/// -/// conversations one tool once, which keeps a healthy run finite. Section -/// 8.7 needs the other case: a tool that keeps failing. This client never stops calling, so the run -/// spends the error budget of MaximumConsecutiveErrorsPerRequest and the 4th failure throws. -/// -internal sealed class LoopingToolCallingChatClient : IChatClient -{ - private int _calls; + /// Gets how many requests this client answered. + public int Calls => Volatile.Read(ref _calls); - /// Gets how many requests this client answered. - public int Calls => Volatile.Read(ref _calls); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + int index = Interlocked.Increment(ref _calls); + await Task.Yield(); - var index = Interlocked.Increment(ref _calls); - await Task.Yield(); + string responseId = Guid.NewGuid().ToString("N"); + if (options?.Tools?.OfType().FirstOrDefault() is not { } tool) + { + // The extractor is offered no tool, so it still answers. + yield return new ChatResponseUpdate(ChatRole.Assistant, "{}") + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } - var responseId = Guid.NewGuid().ToString("N"); - if (options?.Tools?.OfType().FirstOrDefault() is not { } tool) - { - // The extractor is offered no tool, so it still answers. - yield return new ChatResponseUpdate(ChatRole.Assistant, "{}") + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent($"conversation_{index}", tool.Name, new Dictionary(StringComparer.Ordinal))]) { ResponseId = responseId, MessageId = responseId, }; - yield break; } - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent($"conversation_{index}", tool.Name, new Dictionary(StringComparer.Ordinal))]) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } -} -/// -/// Builds one function for each declared tool, and every one of them throws a fault the model -/// cannot answer. -/// -/// -/// -/// A builtin tool returns an error result rather than throwing, so this factory stands for -/// the case section 8.7 keeps for a defect: the fault is beyond the model, and the 4th consecutive -/// one throws out of the run and spends the framework's own budget. -/// -/// -/// Task 7a moved that classification off and -/// into , the framework's single choke point for -/// every tool call. This factory builds a bare AIFunctionFactory tool, which is not a -/// at all, so it is the one thing in this file -/// that still exercises the classification of a fault reaching that middleware with no tool kind in -/// front of it. The exception type is deliberately one IsBeyondTheModel classifies as beyond -/// the model — before the move that was true of every exception this factory could throw, because -/// nothing classified it either way; after the move, only this arm keeps the run finite, since an -/// answerable fault would now become an error result the model reads and -/// would call the tool again forever. -/// -/// -internal sealed class ThrowingToolBuilder -{ - /// The message every fault carries. - public const string Message = "the tool is down."; - - private int _calls; - - /// Gets how many times a tool of this factory ran. - public int Calls => Volatile.Read(ref _calls); - - public AITool? Create(ToolConfiguration tool) - { - ArgumentNullException.ThrowIfNull(tool); - return AIFunctionFactory.Create(Fail, tool.Id, tool.Description ?? tool.Id); - } + /// + /// Builds one function for each declared tool, and every one of them throws a fault the model + /// cannot answer. + /// + /// + /// + /// A builtin tool returns an error result rather than throwing, so this factory stands for + /// the case section 8.7 keeps for a defect: the fault is beyond the model, and the 4th consecutive + /// one throws out of the run and spends the framework's own budget. + /// + /// + /// Task 7a moved that classification off and + /// into , the framework's single choke point for + /// every tool call. This factory builds a bare AIFunctionFactory tool, which is not a + /// at all, so it is the one thing in this file + /// that still exercises the classification of a fault reaching that middleware with no tool kind in + /// front of it. The exception type is deliberately one IsBeyondTheModel classifies as beyond + /// the model — before the move that was true of every exception this factory could throw, because + /// nothing classified it either way; after the move, only this arm keeps the run finite, since an + /// answerable fault would now become an error result the model reads and + /// would call the tool again forever. + /// + /// + internal sealed class ThrowingToolBuilder + { + /// The message every fault carries. + public const string Message = "the tool is down."; + + private int _calls; + + /// Gets how many times a tool of this factory ran. + public int Calls => Volatile.Read(ref _calls); + + public AITool? Create(ToolConfiguration tool) + { + ArgumentNullException.ThrowIfNull(tool); + return AIFunctionFactory.Create(Fail, tool.Id, tool.Description ?? tool.Id); + } - private string Fail() - { - Interlocked.Increment(ref _calls); - throw new TimeoutException(Message); + private string Fail() + { + _ = Interlocked.Increment(ref _calls); + throw new TimeoutException(Message); + } } -} -/// -/// Builds one function for each declared tool, and answers it with a fixed JSON document. -/// -/// -/// The turn loop reads a tool result out of the finished turn and hands it to -/// ToolStateWriter. This factory gives it something to read without an HTTP adapter. -/// -internal sealed class StubToolBuilder -{ - private readonly string _result; - private readonly bool _asText; - - /// Creates the factory. + /// + /// Builds one function for each declared tool, and answers it with a fixed JSON document. + /// + /// + /// The turn loop reads a tool result out of the finished turn and hands it to + /// ToolStateWriter. This factory gives it something to read without an HTTP adapter. + /// + /// Creates the factory. /// The JSON document each tool answers. /// /// Whether the tool answers the document as one string. A real tool answers either way, because a /// tool result has no declared shape. /// - public StubToolBuilder(string result, bool asText = false) + internal sealed class StubToolBuilder(string result, bool asText = false) { - _result = result; - _asText = asText; - } + private readonly string _result = result; + private readonly bool _asText = asText; - /// Gets the id of each tool this factory ran, in call order. - public List Called { get; } = []; - - public AITool? Create(ToolConfiguration tool) - { - ArgumentNullException.ThrowIfNull(tool); + /// Gets the id of each tool this factory ran, in call order. + public List Called { get; } = []; - var id = tool.Id; - var description = tool.Description ?? id; - - if (_asText) + public AITool? Create(ToolConfiguration tool) { - return AIFunctionFactory.Create( + ArgumentNullException.ThrowIfNull(tool); + + string id = tool.Id; + string description = tool.Description ?? id; + + return _asText + ? AIFunctionFactory.Create( + () => + { + Record(id); + return _result; + }, + id, + description) + : AIFunctionFactory.Create( () => { Record(id); - return _result; + using JsonDocument document = JsonDocument.Parse(_result); + return document.RootElement.Clone(); }, id, description); } - return AIFunctionFactory.Create( - () => - { - Record(id); - using var document = JsonDocument.Parse(_result); - return document.RootElement.Clone(); - }, - id, - description); - } - - private void Record(string id) - { - lock (Called) + private void Record(string id) { - Called.Add(id); + lock (Called) + { + Called.Add(id); + } } } -} - -/// -/// A model that calls one tool by a name of the test's choosing, once, then answers with text. -/// -/// -/// always calls a tool the document declares. This one calls -/// whatever name it is given, so a test can reproduce the model INVENTING a tool name — the -/// NotFound case, which the framework answers with a message and no exception, so it spends -/// none of the error budget and the turn goes on. Nothing recorded it before. -/// -internal sealed class NamedToolCallingChatClient : IChatClient -{ - private readonly string _toolName; - private readonly string _reply; - private readonly int _callsPerTurn; - private int _calls; - /// Creates the client. + /// + /// A model that calls one tool by a name of the test's choosing, once, then answers with text. + /// + /// + /// always calls a tool the document declares. This one calls + /// whatever name it is given, so a test can reproduce the model INVENTING a tool name — the + /// NotFound case, which the framework answers with a message and no exception, so it spends + /// none of the error budget and the turn goes on. Nothing recorded it before. + /// + /// Creates the client. /// The name the model calls. It need not be a name the document declares. /// What it says once the tool round is over. /// /// How many calls to that one name it emits in a single assistant message. Two reproduces the /// parallel-conversation case, where the name alone no longer identifies the conversation. /// - public NamedToolCallingChatClient(string toolName, string reply, int callsPerTurn = 1) + internal sealed class NamedToolCallingChatClient(string toolName, string reply, int callsPerTurn = 1) : IChatClient { - _toolName = toolName; - _reply = reply; - _callsPerTurn = callsPerTurn; - } + private readonly string _toolName = toolName; + private readonly string _reply = reply; + private readonly int _callsPerTurn = callsPerTurn; + private int _calls; - /// Gets the call ids this client handed out, in the order it emitted them. - public List CallIds { get; } = []; + /// Gets the call ids this client handed out, in the order it emitted them. + public List CallIds { get; } = []; - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - var responseId = Guid.NewGuid().ToString("N"); - var answered = messages.Any(message => message.Contents.Any(content => content is FunctionResultContent)); + string responseId = Guid.NewGuid().ToString("N"); + bool answered = messages.Any(message => message.Contents.Any(content => content is FunctionResultContent)); - // The extractor is offered no tool and must still answer, so a request with no tool at all - // never opens a tool round. - if (answered || options?.Tools is not { Count: > 0 }) - { - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + // The extractor is offered no tool and must still answer, so a request with no tool at all + // never opens a tool round. + if (answered || options?.Tools is not { Count: > 0 }) + { + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } + + int round = Interlocked.Increment(ref _calls); + List conversations = []; + for (int index = 0; index < _callsPerTurn; index++) + { + // Every call of one message carries its own id, exactly as a vendor emits them. This is + // the only thing that tells two calls to the same tool apart. + string conversationId = $"conversation_{round}_{index}"; + lock (CallIds) + { + CallIds.Add(conversationId); + } + + conversations.Add(new FunctionCallContent(conversationId, _toolName, new Dictionary(StringComparer.Ordinal))); + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, conversations) { ResponseId = responseId, MessageId = responseId, }; - yield break; } - var round = Interlocked.Increment(ref _calls); - List conversations = []; - for (var index = 0; index < _callsPerTurn; index++) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - // Every call of one message carries its own id, exactly as a vendor emits them. This is - // the only thing that tells two calls to the same tool apart. - var conversationId = $"conversation_{round}_{index}"; - lock (CallIds) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - CallIds.Add(conversationId); + updates.Add(update); } - conversations.Add(new FunctionCallContent(conversationId, _toolName, new Dictionary(StringComparer.Ordinal))); + return updates.ToChatResponse(); } - yield return new ChatResponseUpdate(ChatRole.Assistant, conversations) + public object? GetService(Type serviceType, object? serviceKey = null) { - ResponseId = responseId, - MessageId = responseId, - }; - } + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public void Dispose() { - updates.Add(update); + // Nothing to release. } - - return updates.ToChatResponse(); } - public object? GetService(Type serviceType, object? serviceKey = null) + /// + /// Builds one REAL for each declared tool, and every one of them throws a + /// fault the model cannot answer. + /// + /// + /// builds a bare AIFunctionFactory delegate, which throws + /// straight at the framework. This one goes through the base every shipped tool kind shares, so it + /// exercises the classification AuditingFunctionInvokingChatClient applies and not just the + /// framework's reaction to it. Section 8.7 row six is only reachable through a tool that lets a fault + /// out. + /// + internal sealed class UnreachableEndpointToolBuilder { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + /// The message every fault carries. + public const string Message = "no such host"; - public void Dispose() - { - // Nothing to release. - } -} + private int _calls; -/// -/// Builds one REAL for each declared tool, and every one of them throws a -/// fault the model cannot answer. -/// -/// -/// builds a bare AIFunctionFactory delegate, which throws -/// straight at the framework. This one goes through the base every shipped tool kind shares, so it -/// exercises the classification AuditingFunctionInvokingChatClient applies and not just the -/// framework's reaction to it. Section 8.7 row six is only reachable through a tool that lets a fault -/// out. -/// -internal sealed class UnreachableEndpointToolBuilder -{ - /// The message every fault carries. - public const string Message = "no such host"; + /// Gets how many times a tool of this factory ran. + public int Calls => Volatile.Read(ref _calls); + + public AITool? Create(ToolConfiguration tool) + { + ArgumentNullException.ThrowIfNull(tool); + return new UnreachableEndpointTool(tool, this); + } - private int _calls; + private void Record() + { + _ = Interlocked.Increment(ref _calls); + } - /// Gets how many times a tool of this factory ran. - public int Calls => Volatile.Read(ref _calls); + private sealed class UnreachableEndpointTool(ToolConfiguration tool, UnreachableEndpointToolBuilder owner) : DeclaredTool(tool) + { + private readonly UnreachableEndpointToolBuilder _owner = owner; - public AITool? Create(ToolConfiguration tool) - { - ArgumentNullException.ThrowIfNull(tool); - return new UnreachableEndpointTool(tool, this); + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + _owner.Record(); + throw new HttpRequestException(Message); + } + } } - private void Record() => Interlocked.Increment(ref _calls); - - private sealed class UnreachableEndpointTool : DeclaredTool + /// + /// Builds one REAL for each declared tool, and every one of them throws a + /// fault the model CAN answer. + /// + /// + /// The counterpart of , and the half of section 8.7 that + /// must not regress: the tool answers with an error result, the model reads it, and the turn ends + /// with a spoken reply and no failure at all. + /// + internal sealed class RefusedRequestToolBuilder { - private readonly UnreachableEndpointToolBuilder _owner; + /// The message every fault carries. + public const string Message = "the order is already closed."; + + private int _calls; - public UnreachableEndpointTool(ToolConfiguration tool, UnreachableEndpointToolBuilder owner) - : base(tool) => _owner = owner; + /// Gets how many times a tool of this factory ran. + public int Calls => Volatile.Read(ref _calls); - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) + public AITool? Create(ToolConfiguration tool) { - _owner.Record(); - throw new HttpRequestException(Message); + ArgumentNullException.ThrowIfNull(tool); + return new RefusedRequestTool(tool, this); } - } -} - -/// -/// Builds one REAL for each declared tool, and every one of them throws a -/// fault the model CAN answer. -/// -/// -/// The counterpart of , and the half of section 8.7 that -/// must not regress: the tool answers with an error result, the model reads it, and the turn ends -/// with a spoken reply and no failure at all. -/// -internal sealed class RefusedRequestToolBuilder -{ - /// The message every fault carries. - public const string Message = "the order is already closed."; - private int _calls; + private void Record() + { + _ = Interlocked.Increment(ref _calls); + } - /// Gets how many times a tool of this factory ran. - public int Calls => Volatile.Read(ref _calls); + private sealed class RefusedRequestTool(ToolConfiguration tool, RefusedRequestToolBuilder owner) : DeclaredTool(tool) + { + private readonly RefusedRequestToolBuilder _owner = owner; - public AITool? Create(ToolConfiguration tool) - { - ArgumentNullException.ThrowIfNull(tool); - return new RefusedRequestTool(tool, this); + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + _owner.Record(); + throw new InvalidOperationException(Message); + } + } } - private void Record() => Interlocked.Increment(ref _calls); - - private sealed class RefusedRequestTool : DeclaredTool + /// + /// A model that throws instead of answering, on both run shapes. + /// + /// + /// R1 reaches the turn loop through a tool that failed four times, and that path needs a tool, a + /// looping model, and four round trips to set up. The fault this client raises is the same fault as + /// far as everything above the chat pipeline is concerned, so a test of the fallback layer says what + /// it means in three lines. + /// + internal sealed class ThrowingChatClient(Exception fault) : IChatClient { - private readonly RefusedRequestToolBuilder _owner; - - public RefusedRequestTool(ToolConfiguration tool, RefusedRequestToolBuilder owner) - : base(tool) => _owner = owner; + private readonly Exception _fault = fault; - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - _owner.Record(); - throw new InvalidOperationException(Message); + throw _fault; } - } -} - -/// -/// A model that throws instead of answering, on both run shapes. -/// -/// -/// R1 reaches the turn loop through a tool that failed four times, and that path needs a tool, a -/// looping model, and four round trips to set up. The fault this client raises is the same fault as -/// far as everything above the chat pipeline is concerned, so a test of the fallback layer says what -/// it means in three lines. -/// -internal sealed class ThrowingChatClient : IChatClient -{ - private readonly Exception _fault; - public ThrowingChatClient(Exception fault) => _fault = fault; - - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => throw _fault; + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + throw _fault; + } - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => throw _fault; + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public void Dispose() + { + // Nothing to release. + } } - public void Dispose() + /// A screen that records everything it was asked to show, in the order it was shown. + internal sealed class RecordingRenderPort : IRenderPort { - // Nothing to release. + public List<(string Name, string RenderId, object Data, bool Transient)> Published { get; } = []; + + public void Publish(string name, string renderId, object data, bool transient = false) + { + Published.Add((name, renderId, data, transient)); + } } -} -/// A screen that records everything it was asked to show, in the order it was shown. -internal sealed class RecordingRenderPort : IRenderPort -{ - public List<(string Name, string RenderId, object Data, bool Transient)> Published { get; } = []; + /// + /// A model that calls a scripted list of tools by name, one per request, then answers in words. + /// + /// + /// always calls the first tool it is offered, so it + /// cannot drive an agent whose behaviour IS which tool it picks next. This one names the tool and its arguments, which is + /// what makes a multi-hop test assert on the hops rather than on the count. + /// + internal sealed class ScriptedToolCallingChatClient(params (string Tool, string Arguments)[] script) : IChatClient + { + private readonly (string Tool, string Arguments)[] _script = script; + private int _calls; - public void Publish(string name, string renderId, object data, bool transient = false) - => Published.Add((name, renderId, data, transient)); -} + /// Gets or sets the words the model ends on once the script is spent. + public string? FinalText { get; set; } -/// -/// A model that calls a scripted list of tools by name, one per request, then answers in words. -/// -/// -/// always calls the first tool it is offered, so it -/// cannot drive an agent whose behaviour IS which tool it picks next. This one names the tool and its arguments, which is -/// what makes a multi-hop test assert on the hops rather than on the count. -/// -internal sealed class ScriptedToolCallingChatClient : IChatClient -{ - private readonly (string Tool, string Arguments)[] _script; - private int _calls; + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - public ScriptedToolCallingChatClient(params (string Tool, string Arguments)[] script) => _script = script; + int index = Interlocked.Increment(ref _calls) - 1; + await Task.Yield(); - /// Gets or sets the words the model ends on once the script is spent. - public string? FinalText { get; set; } + string responseId = Guid.NewGuid().ToString("N"); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + // Past the end of the script, or offered no tool at all on the cap's last request, it + // answers in words. Answering with a conversation it cannot make would hang the loop. + if (index >= _script.Length || options?.Tools is not { Count: > 0 }) + { + yield return new ChatResponseUpdate(ChatRole.Assistant, FinalText ?? string.Empty) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } - var index = Interlocked.Increment(ref _calls) - 1; - await Task.Yield(); + (string? tool, string? arguments) = _script[index]; + Dictionary parsed = JsonSerializer.Deserialize>(arguments) + ?? throw new InvalidOperationException($"the script step for '{tool}' is not a JSON object."); - var responseId = Guid.NewGuid().ToString("N"); + Dictionary callArguments = new(StringComparer.Ordinal); + foreach ((string? name, JsonElement value) in parsed) + { + callArguments[name] = value; + } - // Past the end of the script, or offered no tool at all on the cap's last request, it - // answers in words. Answering with a conversation it cannot make would hang the loop. - if (index >= _script.Length || options?.Tools is not { Count: > 0 }) - { - yield return new ChatResponseUpdate(ChatRole.Assistant, FinalText ?? string.Empty) + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent($"conversation_{index}", tool, callArguments)]) { ResponseId = responseId, MessageId = responseId, }; - yield break; } - var (tool, arguments) = _script[index]; - var parsed = JsonSerializer.Deserialize>(arguments) - ?? throw new InvalidOperationException($"the script step for '{tool}' is not a JSON object."); - - Dictionary callArguments = new(StringComparer.Ordinal); - foreach (var (name, value) in parsed) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - callArguments[name] = value; + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); } - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent($"conversation_{index}", tool, callArguments)]) + public object? GetService(Type serviceType, object? serviceKey = null) { - ResponseId = responseId, - MessageId = responseId, - }; - } + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public void Dispose() { - updates.Add(update); } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } - - public void Dispose() - { } } diff --git a/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs b/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs index cd2ebabd..5049314f 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ToolResultCapProviderTests.cs @@ -5,65 +5,70 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// : once the trigger fires, every tool result older than the -/// kept turns is cut to the cap, one message for one, with its id; nothing else moves. -/// -#pragma warning disable MAAI001 // The context constructors and triggers are the framework's own experimental surface. -public sealed class ToolResultCapProviderTests +namespace AgentCore.Application.Tests.Runtime { - [Fact] - public async Task UnderTheTrigger_TheListComesBackAsItWas() + /// + /// : once the trigger fires, every tool result older than the + /// kept turns is cut to the cap, one message for one, with its id; nothing else moves. + /// +#pragma warning disable MAAI001 // The context constructors and triggers are the framework's own experimental surface. + public sealed class ToolResultCapProviderTests { - var provider = new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 3); - var input = new AIContext { Messages = Turns(2) }; + [Fact] + public async Task UnderTheTrigger_TheListComesBackAsItWas() + { + ToolResultCapProvider provider = new(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 3); + AIContext input = new() { Messages = Turns(2) }; - var output = await provider.InvokingAsync(Context(input), TestContext.Current.CancellationToken); + AIContext output = await provider.InvokingAsync(Context(input), TestContext.Current.CancellationToken); - Assert.Same(input, output); - } + Assert.Same(input, output); + } - [Fact] - public async Task OverTheTrigger_OldResultsAreCutInPlaceWithTheirIds_TheKeptTurnsAreNot() - { - var provider = new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 1, maxResultChars: 3); - var messages = Turns(3); - var input = new AIContext { Messages = messages }; + [Fact] + public async Task OverTheTrigger_OldResultsAreCutInPlaceWithTheirIds_TheKeptTurnsAreNot() + { + ToolResultCapProvider provider = new(CompactionTriggers.Always, keepTurns: 1, maxResultChars: 3); + List messages = Turns(3); + AIContext input = new() { Messages = messages }; - var output = (await provider.InvokingAsync(Context(input), TestContext.Current.CancellationToken)).Messages!.ToList(); + List output = [.. (await provider.InvokingAsync(Context(input), TestContext.Current.CancellationToken)).Messages!]; - Assert.Equal(["res…", "res…", "result-2"], output.Where(message => message.Role == ChatRole.Tool).Select(Result)); - Assert.Equal(messages.Select(message => message.MessageId), output.Select(message => message.MessageId)); - for (var index = 0; index < messages.Count; index++) - { - if (messages[index].Role != ChatRole.Tool) + Assert.Equal(["res…", "res…", "result-2"], output.Where(message => message.Role == ChatRole.Tool).Select(Result)); + Assert.Equal(messages.Select(message => message.MessageId), output.Select(message => message.MessageId)); + for (int index = 0; index < messages.Count; index++) { - Assert.Same(messages[index], output[index]); + if (messages[index].Role != ChatRole.Tool) + { + Assert.Same(messages[index], output[index]); + } } } - } - private static string Result(ChatMessage message) - => Assert.Single(message.Contents.OfType()).Result!.ToString()!; + private static string Result(ChatMessage message) + { + return Assert.Single(message.Contents.OfType()).Result!.ToString()!; + } - /// Turns of a question, a call, its result result-N, and a reply; four messages each. - private static List Turns(int count) - { - List messages = []; - for (var turn = 0; turn < count; turn++) + /// Turns of a question, a call, its result result-N, and a reply; four messages each. + private static List Turns(int count) { - messages.Add(new ChatMessage(ChatRole.User, $"q{turn}") { MessageId = $"m-{turn}-q" }); - messages.Add(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent($"call-{turn}", "tool")]) { MessageId = $"m-{turn}-call" }); - messages.Add(new ChatMessage(ChatRole.Tool, [new FunctionResultContent($"call-{turn}", $"result-{turn}")]) { MessageId = $"m-{turn}-result" }); - messages.Add(new ChatMessage(ChatRole.Assistant, $"a{turn}") { MessageId = $"m-{turn}-a" }); + List messages = []; + for (int turn = 0; turn < count; turn++) + { + messages.Add(new ChatMessage(ChatRole.User, $"q{turn}") { MessageId = $"m-{turn}-q" }); + messages.Add(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent($"call-{turn}", "tool")]) { MessageId = $"m-{turn}-call" }); + messages.Add(new ChatMessage(ChatRole.Tool, [new FunctionResultContent($"call-{turn}", $"result-{turn}")]) { MessageId = $"m-{turn}-result" }); + messages.Add(new ChatMessage(ChatRole.Assistant, $"a{turn}") { MessageId = $"m-{turn}-a" }); + } + + return messages; } - return messages; + private static AIContextProvider.InvokingContext Context(AIContext input) + { + return new(StubAgent.Instance, new StubSession(), input); + } } - - private static AIContextProvider.InvokingContext Context(AIContext input) - => new(StubAgent.Instance, new StubSession(), input); -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnContextProviderTests.cs b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnContextProviderTests.cs index 9cce460f..8c762d4d 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnContextProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnContextProviderTests.cs @@ -12,26 +12,26 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Turn; - -/// -/// The per-invocation seam: what one turn hands the model on top of the agent's own instructions. -/// -/// -/// -/// The compiled agent is a process singleton, so the provider bound to it is one too and may hold -/// nothing per conversation. It finds the turn in the session-keyed registry instead, and it applies what -/// it finds only to a run on the session that turn filed. That rule is what keeps a delegated -/// run — which is call and return on a session of its own — out of the turn's context. -/// -/// -/// Every test here runs offline: no network conversation and no API key. -/// -/// -public sealed class TurnContextProviderTests +namespace AgentCore.Application.Tests.Runtime.Turn { - private const string ReminderYaml = - """ + /// + /// The per-invocation seam: what one turn hands the model on top of the agent's own instructions. + /// + /// + /// + /// The compiled agent is a process singleton, so the provider bound to it is one too and may hold + /// nothing per conversation. It finds the turn in the session-keyed registry instead, and it applies what + /// it finds only to a run on the session that turn filed. That rule is what keeps a delegated + /// run — which is call and return on a session of its own — out of the turn's context. + /// + /// + /// Every test here runs offline: no network conversation and no API key. + /// + /// + public sealed class TurnContextProviderTests + { + private const string ReminderYaml = + """ apiVersion: agentcore/v1 state: machineModel: { type: string, writer: extractor, description: the machine model } @@ -62,8 +62,8 @@ public sealed class TurnContextProviderTests terminal: true """; - private const string SingleAgentYaml = - """ + private const string SingleAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -73,8 +73,8 @@ public sealed class TurnContextProviderTests agent: solo """; - private const string PatternGraphYaml = - """ + private const string PatternGraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -87,178 +87,189 @@ public sealed class TurnContextProviderTests agents: [ researcher, responder ] """; - [Fact] - public async Task TheProvider_HandsTheTurnsInstructionsToARunOnTheConversationsSession() - { - StubSession session = new(); - TurnRegistry.Set(session, new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Instructions = "ask for the model" }); - - var context = await InvokeAsync(session); - - // A message, not AIContext.Instructions. The framework folds Instructions into the system - // message at the head of the prompt, where per-turn text caps the vendor's cacheable prefix. - Assert.NotNull(context.Messages); - var message = Assert.Single(context.Messages); - Assert.Equal(ChatRole.System, message.Role); - Assert.Equal("ask for the model", message.Text); - Assert.Null(context.Instructions); - } - - [Fact] - public async Task TheProvider_HandsNothingToARunOnAnotherSession() - { - StubSession conversation = new(); - StubSession delegated = new(); - TurnRegistry.Set(conversation, new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Instructions = "ask for the model" }); - - var context = await InvokeAsync(delegated); - - Assert.Null(context.Messages); - Assert.Null(context.Instructions); - } - - [Fact] - public async Task TheProvider_HandsNothingWhenNoTurnIsOpen() - { - var context = await InvokeAsync(new StubSession()); - - Assert.Null(context.Messages); - Assert.Null(context.Instructions); - } - - [Fact] - public void TheProvider_FilesItsStateUnderAKeyOfItsOwn() - { - // Both providers go on the same agent, and ChatClientAgent throws at construction on a - // duplicate key. This is the assertion that fails first if either type is renamed. - Assert.Equal(["TurnContextProvider"], new TurnContextProvider().StateKeys); - Assert.NotEqual(new AgentCoreChatHistoryProvider().StateKeys, new TurnContextProvider().StateKeys); - } - - [Theory] - [InlineData(ReminderYaml)] - [InlineData(SingleAgentYaml)] - [InlineData(PatternGraphYaml)] - public void EveryCompiledAgent_CarriesTheProvider(string yaml) - { - using SequencedChatClient reply = new("hello there."); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; - - Assert.NotEmpty(compiled.Agents); - Assert.All( - compiled.Agents.Values, - agent => Assert.Contains( - ChatClientAgentOf(agent).AIContextProviders ?? [], - provider => provider is TurnContextProvider)); - } - - [Fact] - public async Task TheReminder_ReachesTheReplyAgentBelowTheTranscript() - { - using SequencedChatClient reply = new("hello there."); - using SequencedChatClient specialist = new("the specialist answer"); - var session = CreateSession(reply, specialist); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(0), StringComparison.Ordinal); - Assert.Contains("the machine model", reply.SystemText(0), StringComparison.Ordinal); - - // The agent's own instructions survive, and stay clean: the turn's context rides a message of - // its own so the instructions block is byte-identical from one turn to the next. - Assert.Equal("greet the caller", reply.Options[0]!.Instructions); - } - - [Fact] - public async Task TheReminder_NeverReachesADelegatedAgent() - { - // Agent-as-tool is call and return on a session of its own. The sub-agent is not the one - // talking to the caller, so a reminder about what the caller still owes is not its business. - using ToolCallingChatClient greeter = new( - "hello there.", - new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); - using SequencedChatClient specialist = new("the specialist answer"); - var session = CreateSession(greeter, specialist); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.NotEmpty(specialist.Requests); - Assert.All( - Enumerable.Range(0, specialist.Requests.Count), - request => Assert.DoesNotContain( - UnfilledSlotReminder.OpenTag, specialist.SystemText(request), StringComparison.Ordinal)); - } - - /// Runs the provider the way the framework runs it, for one run on one session. - private static async Task InvokeAsync(AgentSession session) - { - #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(StubAgent.Instance, session, new AIContext()); - #pragma warning restore MAAI001 - return await new TurnContextProvider().InvokingAsync(context, TestContext.Current.CancellationToken); - } - - /// Reads the under whatever the compiler wrapped it in. - private static ChatClientAgent ChatClientAgentOf(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner; - } - - /// Compiles over two named models and opens a conversation on it. - private static ConversationSession CreateSession(IChatClient reply, IChatClient specialist) - { - RoutingChatClientFactory chatClients = new(reply); - chatClients.Route("reply", reply); - chatClients.Route("specialist", specialist); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(ReminderYaml), new AgentCompilationContext(chatClients))["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null).Create(); - } - - private sealed class StubSession : AgentSession; - - /// Stands in for the agent the framework names on a context. Nothing here runs it. - private sealed class StubAgent : AIAgent - { - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - } - } + [Fact] + public async Task TheProvider_HandsTheTurnsInstructionsToARunOnTheConversationsSession() + { + StubSession session = new(); + TurnRegistry.Set(session, new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Instructions = "ask for the model" }); + + AIContext context = await InvokeAsync(session); + + // A message, not AIContext.Instructions. The framework folds Instructions into the system + // message at the head of the prompt, where per-turn text caps the vendor's cacheable prefix. + Assert.NotNull(context.Messages); + ChatMessage message = Assert.Single(context.Messages); + Assert.Equal(ChatRole.System, message.Role); + Assert.Equal("ask for the model", message.Text); + Assert.Null(context.Instructions); + } + + [Fact] + public async Task TheProvider_HandsNothingToARunOnAnotherSession() + { + StubSession conversation = new(); + StubSession delegated = new(); + TurnRegistry.Set(conversation, new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Instructions = "ask for the model" }); + + AIContext context = await InvokeAsync(delegated); + + Assert.Null(context.Messages); + Assert.Null(context.Instructions); + } + + [Fact] + public async Task TheProvider_HandsNothingWhenNoTurnIsOpen() + { + AIContext context = await InvokeAsync(new StubSession()); + + Assert.Null(context.Messages); + Assert.Null(context.Instructions); + } + + [Fact] + public void TheProvider_FilesItsStateUnderAKeyOfItsOwn() + { + // Both providers go on the same agent, and ChatClientAgent throws at construction on a + // duplicate key. This is the assertion that fails first if either type is renamed. + Assert.Equal(["TurnContextProvider"], new TurnContextProvider().StateKeys); + Assert.NotEqual(new AgentCoreChatHistoryProvider().StateKeys, new TurnContextProvider().StateKeys); + } + + [Theory] + [InlineData(ReminderYaml)] + [InlineData(SingleAgentYaml)] + [InlineData(PatternGraphYaml)] + public void EveryCompiledAgent_CarriesTheProvider(string yaml) + { + using SequencedChatClient reply = new("hello there."); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(new FakeChatClientFactory(reply)))["main"]; + + Assert.NotEmpty(compiled.Agents); + Assert.All( + compiled.Agents.Values, + agent => Assert.Contains( + ChatClientAgentOf(agent).AIContextProviders ?? [], + provider => provider is TurnContextProvider)); + } + + [Fact] + public async Task TheReminder_ReachesTheReplyAgentBelowTheTranscript() + { + using SequencedChatClient reply = new("hello there."); + using SequencedChatClient specialist = new("the specialist answer"); + ConversationSession session = CreateSession(reply, specialist); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.Contains(UnfilledSlotReminder.OpenTag, reply.SystemText(0), StringComparison.Ordinal); + Assert.Contains("the machine model", reply.SystemText(0), StringComparison.Ordinal); + + // The agent's own instructions survive, and stay clean: the turn's context rides a message of + // its own so the instructions block is byte-identical from one turn to the next. + Assert.Equal("greet the caller", reply.Options[0]!.Instructions); + } + + [Fact] + public async Task TheReminder_NeverReachesADelegatedAgent() + { + // Agent-as-tool is call and return on a session of its own. The sub-agent is not the one + // talking to the caller, so a reminder about what the caller still owes is not its business. + using ToolCallingChatClient greeter = new( + "hello there.", + new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); + using SequencedChatClient specialist = new("the specialist answer"); + ConversationSession session = CreateSession(greeter, specialist); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.NotEmpty(specialist.Requests); + Assert.All( + Enumerable.Range(0, specialist.Requests.Count), + request => Assert.DoesNotContain( + UnfilledSlotReminder.OpenTag, specialist.SystemText(request), StringComparison.Ordinal)); + } + + /// Runs the provider the way the framework runs it, for one run on one session. + private static async Task InvokeAsync(AgentSession session) + { +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + AIContextProvider.InvokingContext context = new(StubAgent.Instance, session, new AIContext()); +#pragma warning restore MAAI001 + return await new TurnContextProvider().InvokingAsync(context, TestContext.Current.CancellationToken); + } + + /// Reads the under whatever the compiler wrapped it in. + private static ChatClientAgent ChatClientAgentOf(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner; + } + + /// Compiles over two named models and opens a conversation on it. + private static ConversationSession CreateSession(IChatClient reply, IChatClient specialist) + { + RoutingChatClientFactory chatClients = new(reply); + _ = chatClients.Route("reply", reply); + _ = chatClients.Route("specialist", specialist); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(ReminderYaml), new AgentCompilationContext(chatClients))["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null).Create(); + } + + private sealed class StubSession : AgentSession; + + /// Stands in for the agent the framework names on a context. Nothing here runs it. + private sealed class StubAgent : AIAgent + { + public static StubAgent Instance { get; } = new(); + + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) + { + return new(new StubSession()); + } + + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnFilesTests.cs b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnFilesTests.cs index ff90fa9c..d67d78b3 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnFilesTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnFilesTests.cs @@ -2,78 +2,81 @@ using AgentCore.Application.Transcript; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Turn; - -/// -/// What a turn has published and not yet attached to a message. Keyed by the outer tool call, like -/// the render and source collectors, because the message a file card belongs on is the result of -/// the call that published it. -/// -public sealed class TurnFilesTests +namespace AgentCore.Application.Tests.Runtime.Turn { - [Fact] - public void Publish_UnderACall_IsTakenByThatCallOnce() + /// + /// What a turn has published and not yet attached to a message. Keyed by the outer tool call, like + /// the render and source collectors, because the message a file card belongs on is the result of + /// the call that published it. + /// + public sealed class TurnFilesTests { - TurnFiles files = new(); - - using (files.BeginOuterCall("call-1")) + [Fact] + public void Publish_UnderACall_IsTakenByThatCallOnce() { - files.Publish(Card("rows.csv", 8)); - } + TurnFiles files = new(); - var taken = files.TakeFor("call-1"); + using (files.BeginOuterCall("call-1")) + { + files.Publish(Card("rows.csv", 8)); + } - Assert.Equal("rows.csv", Assert.Single(taken).Name); - Assert.Empty(files.TakeFor("call-1")); - } + IReadOnlyList taken = files.TakeFor("call-1"); - [Fact] - public void Publish_WithNoCallOpen_IsDropped() - { - TurnFiles files = new(); + Assert.Equal("rows.csv", Assert.Single(taken).Name); + Assert.Empty(files.TakeFor("call-1")); + } - files.Publish(Card("rows.csv", 8)); + [Fact] + public void Publish_WithNoCallOpen_IsDropped() + { + TurnFiles files = new(); - Assert.Empty(files.TakeFor("rows.csv")); - } + files.Publish(Card("rows.csv", 8)); - [Fact] - public void Publish_TheSameNameTwice_KeepsTheLaterFactsInTheFirstPlace() - { - TurnFiles files = new(); + Assert.Empty(files.TakeFor("rows.csv")); + } - using (files.BeginOuterCall("call-1")) + [Fact] + public void Publish_TheSameNameTwice_KeepsTheLaterFactsInTheFirstPlace() { - files.Publish(Card("rows.csv", 8)); - files.Publish(Card("chart.png", 3)); - files.Publish(Card("rows.csv", 16)); - } + TurnFiles files = new(); - var taken = files.TakeFor("call-1"); + using (files.BeginOuterCall("call-1")) + { + files.Publish(Card("rows.csv", 8)); + files.Publish(Card("chart.png", 3)); + files.Publish(Card("rows.csv", 16)); + } - Assert.Equal(["rows.csv", "chart.png"], taken.Select(card => card.Name)); - Assert.Equal(16, taken[0].Length); - } + IReadOnlyList taken = files.TakeFor("call-1"); - [Fact] - public void Publish_InsideANestedCall_FilesUnderTheOuterCall() - { - TurnFiles files = new(); + Assert.Equal(["rows.csv", "chart.png"], taken.Select(card => card.Name)); + Assert.Equal(16, taken[0].Length); + } - using (files.BeginOuterCall("outer")) + [Fact] + public void Publish_InsideANestedCall_FilesUnderTheOuterCall() { - using (files.BeginOuterCall("inner")) + TurnFiles files = new(); + + using (files.BeginOuterCall("outer")) { - files.Publish(Card("rows.csv", 8)); + using (files.BeginOuterCall("inner")) + { + files.Publish(Card("rows.csv", 8)); + } + + files.Publish(Card("chart.png", 3)); } - files.Publish(Card("chart.png", 3)); + _ = Assert.Single(files.TakeFor("inner")); + _ = Assert.Single(files.TakeFor("outer")); } - Assert.Single(files.TakeFor("inner")); - Assert.Single(files.TakeFor("outer")); + private static FileContent Card(string name, long length) + { + return new() { Name = name, FileId = name, MediaType = "text/csv", Length = length, Kept = true }; + } } - - private static FileContent Card(string name, long length) - => new() { Name = name, FileId = name, MediaType = "text/csv", Length = length, Kept = true }; } diff --git a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnResultsTests.cs b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnResultsTests.cs index ded47faf..7cb01928 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnResultsTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnResultsTests.cs @@ -7,139 +7,140 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Turn; - -/// -/// : what the turn's tools answered, kept so a drawing script can read the -/// rows instead of a model retyping them. -/// -public sealed class TurnResultsTests +namespace AgentCore.Application.Tests.Runtime.Turn { - private static readonly JsonNode Orders = JsonNode.Parse("""[{"id":"SO-1"},{"id":"SO-2"}]""")!; - - [Fact] - public void ARecordedObject_IsTheLatestAndTheOnlyOne() + /// + /// : what the turn's tools answered, kept so a drawing script can read the + /// rows instead of a model retyping them. + /// + public sealed class TurnResultsTests { - TurnResults results = new(); + private static readonly JsonNode Orders = JsonNode.Parse("""[{"id":"SO-1"},{"id":"SO-2"}]""")!; - results.Record("lookup_orders", Orders); - - var data = results.Data(); - Assert.Equal(Orders.ToJsonString(), data["lookup_orders"]!.ToJsonString()); - Assert.Equal($"[{Orders.ToJsonString()}]", data["$all"]!["lookup_orders"]!.ToJsonString()); - Assert.Equal(["lookup_orders"], results.Tools); - } + [Fact] + public void ARecordedObject_IsTheLatestAndTheOnlyOne() + { + TurnResults results = new(); - [Fact] - public void ASecondRecord_BecomesTheLatest_AndBothStayInOrder() - { - TurnResults results = new(); - results.Record("lookup_order", JsonNode.Parse("""{"id":"SO-1"}""")!); + results.Record("lookup_orders", Orders); - results.Record("lookup_order", JsonNode.Parse("""{"id":"SO-2"}""")!); + JsonObject data = results.Data(); + Assert.Equal(Orders.ToJsonString(), data["lookup_orders"]!.ToJsonString()); + Assert.Equal($"[{Orders.ToJsonString()}]", data["$all"]!["lookup_orders"]!.ToJsonString()); + Assert.Equal(["lookup_orders"], results.Tools); + } - var data = results.Data(); - Assert.Equal("""{"id":"SO-2"}""", data["lookup_order"]!.ToJsonString()); - Assert.Equal("""[{"id":"SO-1"},{"id":"SO-2"}]""", data["$all"]!["lookup_order"]!.ToJsonString()); - Assert.Equal(["lookup_order"], results.Tools); - } + [Fact] + public void ASecondRecord_BecomesTheLatest_AndBothStayInOrder() + { + TurnResults results = new(); + results.Record("lookup_order", JsonNode.Parse("""{"id":"SO-1"}""")!); - [Fact] - public void TheDataHandedOut_IsACopy_SoAScriptCannotChangeWhatWasRecorded() - { - TurnResults results = new(); - results.Record("lookup_orders", Orders); + results.Record("lookup_order", JsonNode.Parse("""{"id":"SO-2"}""")!); - results.Data()["lookup_orders"]!.AsArray().Clear(); + JsonObject data = results.Data(); + Assert.Equal(/*lang=json,strict*/ """{"id":"SO-2"}""", data["lookup_order"]!.ToJsonString()); + Assert.Equal(/*lang=json,strict*/ """[{"id":"SO-1"},{"id":"SO-2"}]""", data["$all"]!["lookup_order"]!.ToJsonString()); + Assert.Equal(["lookup_order"], results.Tools); + } - Assert.Equal(Orders.ToJsonString(), results.Data()["lookup_orders"]!.ToJsonString()); - } + [Fact] + public void TheDataHandedOut_IsACopy_SoAScriptCannotChangeWhatWasRecorded() + { + TurnResults results = new(); + results.Record("lookup_orders", Orders); - [Theory] - [MemberData(nameof(StructuredResults), DisableDiscoveryEnumeration = true)] - public void AStructuredResult_IsRecorded_WhateverShapeTheToolAnsweredIn(object result, string expected) - { - TurnResults results = new(); + results.Data()["lookup_orders"]!.AsArray().Clear(); - results.Record("tool", result); + Assert.Equal(Orders.ToJsonString(), results.Data()["lookup_orders"]!.ToJsonString()); + } - Assert.Equal(expected, results.Data()["tool"]!.ToJsonString()); - } + [Theory] + [MemberData(nameof(StructuredResults), DisableDiscoveryEnumeration = true)] + public void AStructuredResult_IsRecorded_WhateverShapeTheToolAnsweredIn(object result, string expected) + { + TurnResults results = new(); - public static TheoryData StructuredResults => new() - { - { JsonNode.Parse("""{"a":1}""")!, """{"a":1}""" }, - { JsonSerializer.Deserialize("""[1,2]"""), "[1,2]" }, - { """{"from":"a string holding json"}""", """{"from":"a string holding json"}""" }, - { new { name = "an object" }, """{"name":"an object"}""" }, - }; - - [Theory] - [MemberData(nameof(UnstructuredResults), DisableDiscoveryEnumeration = true)] - public void AnUnstructuredResult_IsNotRecorded(object? result) - { - TurnResults results = new(); + results.Record("tool", result); - results.Record("tool", result); + Assert.Equal(expected, results.Data()["tool"]!.ToJsonString()); + } - Assert.Empty(results.Tools); - Assert.Null(results.Data()["tool"]); - } + public static TheoryData StructuredResults => new() + { + { JsonNode.Parse("""{"a":1}""")!, /*lang=json,strict*/ """{"a":1}""" }, + { JsonSerializer.Deserialize("""[1,2]"""), "[1,2]" }, + { /*lang=json,strict*/ """{"from":"a string holding json"}""", /*lang=json,strict*/ """{"from":"a string holding json"}""" }, + { new { name = "an object" }, /*lang=json,strict*/ """{"name":"an object"}""" }, + }; - public static TheoryData UnstructuredResults => - [ - (object?)null, - "Order SO-1 shipped on Tuesday.", - 42, - ToolErrorResult.Create("tool", "it failed."), - ]; + [Theory] + [MemberData(nameof(UnstructuredResults), DisableDiscoveryEnumeration = true)] + public void AnUnstructuredResult_IsNotRecorded(object? result) + { + TurnResults results = new(); - [Fact] - public async Task AnOutermostToolCall_IsRecordedUnderTheToolsName() - { - TurnResults results = new(); - var turn = new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Results = results }; - var tool = AIFunctionFactory.Create(() => Orders, "lookup_orders"); + results.Record("tool", result); - await Run(tool, turn); + Assert.Empty(results.Tools); + Assert.Null(results.Data()["tool"]); + } - Assert.Equal(["lookup_orders"], results.Tools); - Assert.Equal(Orders.ToJsonString(), results.Data()["lookup_orders"]!.ToJsonString()); - } + public static TheoryData UnstructuredResults => + [ + (object?)null, + "Order SO-1 shipped on Tuesday.", + 42, + ToolErrorResult.Create("tool", "it failed."), + ]; - [Fact] - public async Task AToolCallNestedInsideAnother_IsNotRecorded() - { - // The outer model never saw a nested result, so it cannot ask to draw it. - TurnResults results = new(); - var turn = new TurnInvocation { ConversationId = "conversation", TurnIndex = 0, Stage = "", Results = results }; - var inner = AIFunctionFactory.Create(() => Orders, "inner_lookup"); - var outer = AIFunctionFactory.Create( - async () => - { - await Run(inner, turn with { Nested = true, Clarifications = null }); - return JsonNode.Parse("""{"outer":true}"""); - }, - "delegate"); + [Fact] + public async Task AnOutermostToolCall_IsRecordedUnderTheToolsName() + { + TurnResults results = new(); + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", Results = results }; + AIFunction tool = AIFunctionFactory.Create(() => Orders, "lookup_orders"); - await Run(outer, turn); + await Run(tool, turn); - Assert.Equal(["delegate"], results.Tools); - } + Assert.Equal(["lookup_orders"], results.Tools); + Assert.Equal(Orders.ToJsonString(), results.Data()["lookup_orders"]!.ToJsonString()); + } - private static async Task Run(AIFunction tool, TurnInvocation turn) - { - ToolCallingChatClient model = new("done."); - using AuditingFunctionInvokingChatClient client = new(model); - var options = new ChatOptions + [Fact] + public async Task AToolCallNestedInsideAnother_IsNotRecorded() { - Tools = [tool], - AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }, - }; - - await client.GetResponseAsync( - [new ChatMessage(ChatRole.User, "go")], - options, - TestContext.Current.CancellationToken); + // The outer model never saw a nested result, so it cannot ask to draw it. + TurnResults results = new(); + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", Results = results }; + AIFunction inner = AIFunctionFactory.Create(() => Orders, "inner_lookup"); + AIFunction outer = AIFunctionFactory.Create( + async () => + { + await Run(inner, turn with { Nested = true, Clarifications = null }); + return JsonNode.Parse("""{"outer":true}"""); + }, + "delegate"); + + await Run(outer, turn); + + Assert.Equal(["delegate"], results.Tools); + } + + private static async Task Run(AIFunction tool, TurnInvocation turn) + { + ToolCallingChatClient model = new("done."); + using AuditingFunctionInvokingChatClient client = new(model); + ChatOptions options = new() + { + Tools = [tool], + AdditionalProperties = new AdditionalPropertiesDictionary { [TurnInvocation.ArgumentsKey] = turn }, + }; + + _ = await client.GetResponseAsync( + [new ChatMessage(ChatRole.User, "go")], + options, + TestContext.Current.CancellationToken); + } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnSourcesTests.cs b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnSourcesTests.cs index a5c9c474..de81924c 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Turn/TurnSourcesTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Turn/TurnSourcesTests.cs @@ -1,111 +1,119 @@ using AgentCore.Application.Runtime.Turn; +using AgentCore.Application.Transcript; using AgentCore.Domain.Sources; using Xunit; -namespace AgentCore.Application.Tests.Runtime.Turn; - -/// -/// What a turn has cited and not yet attached to a message. -/// -/// -/// Keyed by the outer tool call for the same reason the render collector is: the message a source -/// belongs on is the result of the call that produced it, and a nested call must not steal it. -/// -public sealed class TurnSourcesTests +namespace AgentCore.Application.Tests.Runtime.Turn { - [Fact] - public void Publish_UnderACall_IsTakenByThatCall() + /// + /// What a turn has cited and not yet attached to a message. + /// + /// + /// Keyed by the outer tool call for the same reason the render collector is: the message a source + /// belongs on is the result of the call that produced it, and a nested call must not steal it. + /// + public sealed class TurnSourcesTests { - TurnSources sources = new(); - - using (OpenCall(sources, "call-1")) + [Fact] + public void Publish_UnderACall_IsTakenByThatCall() { - sources.Publish(Reference("card-1")); - } + TurnSources sources = new(); - var taken = sources.TakeFor("call-1"); + using (OpenCall(sources, "call-1")) + { + sources.Publish(Reference("card-1")); + } - var content = Assert.Single(taken); - Assert.Equal("card-1", content.Source.SourceId); - } + IReadOnlyList taken = sources.TakeFor("call-1"); - [Fact] - public void Publish_WithNoCallOpen_IsDropped() - { - // mode: prefetch searches before any tool call exists. There is no message to attach to, so - // the publish is dropped rather than attached to whatever message comes next. - TurnSources sources = new(); + SourceContent content = Assert.Single(taken); + Assert.Equal("card-1", content.Source.SourceId); + } - sources.Publish(Reference("card-1")); + [Fact] + public void Publish_WithNoCallOpen_IsDropped() + { + // mode: prefetch searches before any tool call exists. There is no message to attach to, so + // the publish is dropped rather than attached to whatever message comes next. + TurnSources sources = new(); - Assert.Empty(sources.TakeFor("call-1")); - } + sources.Publish(Reference("card-1")); - [Fact] - public void Publish_TheSameIdTwice_IsShownOnce() - { - // One turn may search twice and both searches may return the same card. Two identical chips - // are noise, and the second publish is the fresher one. - TurnSources sources = new(); + Assert.Empty(sources.TakeFor("call-1")); + } - using (OpenCall(sources, "call-1")) + [Fact] + public void Publish_TheSameIdTwice_IsShownOnce() { - sources.Publish(Reference("card-1") with { Title = "first" }); - sources.Publish(Reference("card-1") with { Title = "second" }); + // One turn may search twice and both searches may return the same card. Two identical chips + // are noise, and the second publish is the fresher one. + TurnSources sources = new(); + + using (OpenCall(sources, "call-1")) + { + sources.Publish(Reference("card-1") with { Title = "first" }); + sources.Publish(Reference("card-1") with { Title = "second" }); + } + + SourceContent content = Assert.Single(sources.TakeFor("call-1")); + Assert.Equal("second", content.Source.Title); } - var content = Assert.Single(sources.TakeFor("call-1")); - Assert.Equal("second", content.Source.Title); - } - - [Fact] - public void TakeFor_TakesOnlyOnce() - { - TurnSources sources = new(); - - using (OpenCall(sources, "call-1")) + [Fact] + public void TakeFor_TakesOnlyOnce() { - sources.Publish(Reference("card-1")); - } + TurnSources sources = new(); - Assert.Single(sources.TakeFor("call-1")); - Assert.Empty(sources.TakeFor("call-1")); - } + using (OpenCall(sources, "call-1")) + { + sources.Publish(Reference("card-1")); + } - [Fact] - public void Publish_UnderTwoDifferentCalls_StampsEachSourceWithItsOwnCallId() - { - // A round can hold two parallel tool calls, and the base client batches both results onto - // one message — so the source has to carry its own call id rather than being matched to - // whichever call happens to be findable on that shared message afterward. - TurnSources sources = new(); + _ = Assert.Single(sources.TakeFor("call-1")); + Assert.Empty(sources.TakeFor("call-1")); + } - using (OpenCall(sources, "call-1")) + [Fact] + public void Publish_UnderTwoDifferentCalls_StampsEachSourceWithItsOwnCallId() { - sources.Publish(Reference("card-1")); + // A round can hold two parallel tool calls, and the base client batches both results onto + // one message — so the source has to carry its own call id rather than being matched to + // whichever call happens to be findable on that shared message afterward. + TurnSources sources = new(); + + using (OpenCall(sources, "call-1")) + { + sources.Publish(Reference("card-1")); + } + + using (OpenCall(sources, "call-2")) + { + sources.Publish(Reference("card-2")); + } + + SourceContent fromCallOne = Assert.Single(sources.TakeFor("call-1")); + Assert.Equal("call-1", fromCallOne.CallId); + Assert.Equal("card-1", fromCallOne.Source.SourceId); + + SourceContent fromCallTwo = Assert.Single(sources.TakeFor("call-2")); + Assert.Equal("call-2", fromCallTwo.CallId); + Assert.Equal("card-2", fromCallTwo.Source.SourceId); } - using (OpenCall(sources, "call-2")) + private static IDisposable OpenCall(TurnSources sources, string callId) { - sources.Publish(Reference("card-2")); + return sources.BeginOuterCall(callId); } - var fromCallOne = Assert.Single(sources.TakeFor("call-1")); - Assert.Equal("call-1", fromCallOne.CallId); - Assert.Equal("card-1", fromCallOne.Source.SourceId); - - var fromCallTwo = Assert.Single(sources.TakeFor("call-2")); - Assert.Equal("call-2", fromCallTwo.CallId); - Assert.Equal("card-2", fromCallTwo.Source.SourceId); + private static SourceReference Reference(string id) + { + return new() + { + SourceId = id, + Kind = SourceKind.Document, + Title = "a title", + Origin = "knowledge", + }; + } } - - private static IDisposable OpenCall(TurnSources sources, string callId) => sources.BeginOuterCall(callId); - - private static SourceReference Reference(string id) => new() - { - SourceId = id, - Kind = SourceKind.Document, - Title = "a title", - Origin = "knowledge", - }; } diff --git a/tests/AgentCore.Application.Tests/Runtime/TurnPipelineTests.cs b/tests/AgentCore.Application.Tests/Runtime/TurnPipelineTests.cs index 04fb3020..104b89fa 100644 --- a/tests/AgentCore.Application.Tests/Runtime/TurnPipelineTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/TurnPipelineTests.cs @@ -1,6 +1,5 @@ using AgentCore.TestSupport; using AgentCore.Application.Audit.Memory; -using AgentCore.Application.Audit; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -14,27 +13,28 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// Every audible turn is an ordinary successful run. -/// -/// -/// -/// R1, R2 and R3 used to be branches of the turn loop. They are two chat pipeline layers now: -/// ModerationChatClient refuses a flagged turn before the model runs, and -/// FallbackChatClient answers a run that threw or produced no text. Both report what they did -/// on a TurnDisposition, and the turn loop reads it to raise the rows it always raised. -/// -/// Every test here runs offline. There is no network conversation and no API key in this file. -/// -public sealed class TurnPipelineTests +namespace AgentCore.Application.Tests.Runtime { - private const string RefusalReply = "I am sorry. I cannot help with that request."; + /// + /// Every audible turn is an ordinary successful run. + /// + /// + /// + /// R1, R2 and R3 used to be branches of the turn loop. They are two chat pipeline layers now: + /// ModerationChatClient refuses a flagged turn before the model runs, and + /// FallbackChatClient answers a run that threw or produced no text. Both report what they did + /// on a TurnDisposition, and the turn loop reads it to raise the rows it always raised. + /// + /// Every test here runs offline. There is no network conversation and no API key in this file. + /// + public sealed class TurnPipelineTests + { + private const string RefusalReply = "I am sorry. I cannot help with that request."; - private const string PlainYaml = - """ + private const string PlainYaml = + """ apiVersion: agentcore/v1 refusalReply: "I am sorry. I cannot help with that request." agents: @@ -47,8 +47,8 @@ public sealed class TurnPipelineTests agent: only """; - private const string ToolYaml = - """ + private const string ToolYaml = + """ apiVersion: agentcore/v1 refusalReply: "I am sorry. I cannot help with that request." tools: @@ -63,251 +63,251 @@ public sealed class TurnPipelineTests agent: only """; - // ------------------------------------------------------------------------------------------- - // R3 — moderation judges the caller, and a flagged turn never reaches the model. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Run_FlaggedInput_CompletesWithRefusalReply() - { - // Arrange. - using SequencedChatClient model = new("never spoken"); - var session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Flagging("hate")) - .Create("conversation-1"); - - // Act. - var turn = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - - // Assert. The run succeeded, so nothing threw and the turn is not a failure. - Assert.Equal(RefusalReply, turn.ReplyText); - Assert.Null(turn.Failure); - Assert.Equal(0, model.Calls); - } - - [Fact] - public async Task RunStreaming_FlaggedInput_CompletesWithRefusalReply() - { - // Arrange. - using SequencedChatClient model = new("never spoken"); - var session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Flagging("hate")) - .Create("conversation-1"); - - // Act. The refusal arrives on the ordinary stream path, not on a branch of its own. - List spoken = []; - await foreach (var update in session.RunTurnStreamingAsync("...", TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // R3 — moderation judges the caller, and a flagged turn never reaches the model. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Run_FlaggedInput_CompletesWithRefusalReply() { - spoken.Add(update.Text); + // Arrange. + using SequencedChatClient model = new("never spoken"); + ConversationSession session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Flagging("hate")) + .Create("conversation-1"); + + // Act. + TurnResult turn = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + + // Assert. The run succeeded, so nothing threw and the turn is not a failure. + Assert.Equal(RefusalReply, turn.ReplyText); + Assert.Null(turn.Failure); + Assert.Equal(0, model.Calls); } - // Assert. - Assert.Equal(RefusalReply, string.Concat(spoken)); - Assert.Equal(0, model.Calls); - } - - [Fact] - public async Task Run_FlaggedInput_InvokesNoTools() - { - // Arrange. The model would call the tool if it ever ran. - using ToolCallingChatClient model = new("never spoken"); - StubToolBuilder tools = new("""{ "status": "shipped" }"""); - var session = Build(ToolYaml, model, tools: tools.Create, moderation: ScriptedModerationEvaluator.Flagging("hate")) - .Create("conversation-1"); + [Fact] + public async Task RunStreaming_FlaggedInput_CompletesWithRefusalReply() + { + // Arrange. + using SequencedChatClient model = new("never spoken"); + ConversationSession session = Build(PlainYaml, model, moderation: ScriptedModerationEvaluator.Flagging("hate")) + .Create("conversation-1"); + + // Act. The refusal arrives on the ordinary stream path, not on a branch of its own. + List spoken = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("...", TestContext.Current.CancellationToken)) + { + spoken.Add(update.Text); + } + + // Assert. + Assert.Equal(RefusalReply, string.Concat(spoken)); + Assert.Equal(0, model.Calls); + } - // Act. - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + [Fact] + public async Task Run_FlaggedInput_InvokesNoTools() + { + // Arrange. The model would call the tool if it ever ran. + using ToolCallingChatClient model = new("never spoken"); + StubToolBuilder tools = new(/*lang=json,strict*/ """{ "status": "shipped" }"""); + ConversationSession session = Build(ToolYaml, model, tools: tools.Create, moderation: ScriptedModerationEvaluator.Flagging("hate")) + .Create("conversation-1"); - // Assert. The refusal is returned above the function-invoking loop, so no tool ran. - Assert.Empty(model.Called); - } + // Act. + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // R1 and R2 — a failed turn and a quiet turn both speak the fallback. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Run_ModelThrows_CompletesWithFallbackReply() - { - // Arrange. - using ThrowingChatClient model = new(new InvalidOperationException("the vendor is down")); - var session = Build(PlainYaml, model).Create("conversation-1"); - - // Act. Nothing escapes: the layer below the agent caught it. - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Assert. - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.NotNull(turn.Failure); - Assert.Contains("the vendor is down", turn.Failure, StringComparison.Ordinal); - Assert.False(session.IsComplete); - } + // Assert. The refusal is returned above the function-invoking loop, so no tool ran. + Assert.Empty(model.Called); + } - [Fact] - public async Task Run_EmptyModelReply_CompletesWithFallbackReply() - { - // Arrange. Request 41 goes out with no tools and returns quietly. - using SequencedChatClient model = new(" "); - var session = Build(PlainYaml, model).Create("conversation-1"); + // ------------------------------------------------------------------------------------------- + // R1 and R2 — a failed turn and a quiet turn both speak the fallback. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Run_ModelThrows_CompletesWithFallbackReply() + { + // Arrange. + using ThrowingChatClient model = new(new InvalidOperationException("the vendor is down")); + ConversationSession session = Build(PlainYaml, model).Create("conversation-1"); + + // Act. Nothing escapes: the layer below the agent caught it. + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Assert. + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.NotNull(turn.Failure); + Assert.Contains("the vendor is down", turn.Failure, StringComparison.Ordinal); + Assert.False(session.IsComplete); + } - // Act. - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + [Fact] + public async Task Run_EmptyModelReply_CompletesWithFallbackReply() + { + // Arrange. Request 41 goes out with no tools and returns quietly. + using SequencedChatClient model = new(" "); + ConversationSession session = Build(PlainYaml, model).Create("conversation-1"); - // Assert. - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); - } + // Act. + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - [Fact] - public async Task Run_ModerationEndpointDown_RunsTurnAndReportsUnavailable() - { - // Arrange. A vendor outage must not refuse every caller on a support line. - InMemoryAuditSink sink = new(); - using SequencedChatClient model = new("the ordinary reply"); - var session = Build( - PlainYaml, - model, - sink: sink, - moderation: ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))) - .Create("conversation-1"); - - // Act. - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Assert. The turn ran unchecked rather than being refused. - Assert.Equal("the ordinary reply", turn.ReplyText); - Assert.Equal(1, model.Calls); - Assert.DoesNotContain(sink.EventsOf("conversation-1"), entry => entry.Kind == AuditEventKind.PromptFlagged); - } + // Assert. + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); + } - // ------------------------------------------------------------------------------------------- - // The chain is unchanged. The layers moved; the rows did not. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Run_FlaggedOutcome_RaisesSameAuditRowsAsBefore() - { - // Arrange. - InMemoryAuditSink sink = new(); - var session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, - moderation: ScriptedModerationEvaluator.Flagging("violence", "harassment")).Create("conversation-1"); - - // Act. - await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - - // Assert. conversation.started, prompt.flagged, turn.completed — the flag still precedes the turn - // event, because the verdict is known before the model runs. - var events = sink.EventsOf("conversation-1"); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.PromptFlagged, AuditEventKind.TurnCompleted], - events.Select(entry => entry.Kind)); - Assert.Equal("violence,harassment", events[1].Payload[AuditPayloadKeys.ModerationCategories]); - } + [Fact] + public async Task Run_ModerationEndpointDown_RunsTurnAndReportsUnavailable() + { + // Arrange. A vendor outage must not refuse every caller on a support line. + InMemoryAuditSink sink = new(); + using SequencedChatClient model = new("the ordinary reply"); + ConversationSession session = Build( + PlainYaml, + model, + sink: sink, + moderation: ScriptedModerationEvaluator.Throwing(new InvalidOperationException("boom"))) + .Create("conversation-1"); + + // Act. + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Assert. The turn ran unchecked rather than being refused. + Assert.Equal("the ordinary reply", turn.ReplyText); + Assert.Equal(1, model.Calls); + Assert.DoesNotContain(sink.EventsOf("conversation-1"), entry => entry.Kind == AuditEventKind.PromptFlagged); + } - [Fact] - public async Task Run_ThrownOutcome_RaisesSameAuditRowsAsBefore() - { - // Arrange. - InMemoryAuditSink sink = new(); - using ThrowingChatClient model = new(new InvalidOperationException("the vendor is down")); - var session = Build(PlainYaml, model, sink: sink).Create("conversation-1"); - - // Act. - await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Assert. The turn-altitude tool.failed row still names the fault, and still precedes the - // turn.completed of the same turn. - var events = sink.EventsOf("conversation-1"); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.ToolFailed, AuditEventKind.TurnCompleted], - events.Select(entry => entry.Kind)); - Assert.Contains("the vendor is down", events[1].Payload[AuditPayloadKeys.ToolError], StringComparison.Ordinal); - } + // ------------------------------------------------------------------------------------------- + // The chain is unchanged. The layers moved; the rows did not. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Run_FlaggedOutcome_RaisesSameAuditRowsAsBefore() + { + // Arrange. + InMemoryAuditSink sink = new(); + ConversationSession session = Build(PlainYaml, new SequencedChatClient("never spoken"), sink: sink, + moderation: ScriptedModerationEvaluator.Flagging("violence", "harassment")).Create("conversation-1"); + + // Act. + _ = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + + // Assert. conversation.started, prompt.flagged, turn.completed — the flag still precedes the turn + // event, because the verdict is known before the model runs. + IReadOnlyList events = sink.EventsOf("conversation-1"); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.PromptFlagged, AuditEventKind.TurnCompleted], + events.Select(entry => entry.Kind)); + Assert.Equal("violence,harassment", events[1].Payload[AuditPayloadKeys.ModerationCategories]); + } - // ------------------------------------------------------------------------------------------- - // Where the marker is readable. The read site differs by run shape, and that is measured. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Run_BufferedTurn_TurnDispositionReadableOnResponse() - { - // Arrange. - using SequencedChatClient model = new("the ordinary reply"); - var compiled = Compile(PlainYaml, model, out _, moderation: ScriptedModerationEvaluator.Clean()); - - // Act. - var response = await compiled.TurnAgent.RunAsync( - "hello", cancellationToken: TestContext.Current.CancellationToken); - - // Assert. The marker rides the run itself, so nothing about the reply is disturbed. - var properties = response.AdditionalProperties; - Assert.NotNull(properties); - Assert.True(AdditionalPropertiesExtensions.TryGetValue(properties, out var disposition)); - Assert.Equal(ModerationOutcome.Clean, disposition!.Moderation); - } + [Fact] + public async Task Run_ThrownOutcome_RaisesSameAuditRowsAsBefore() + { + // Arrange. + InMemoryAuditSink sink = new(); + using ThrowingChatClient model = new(new InvalidOperationException("the vendor is down")); + ConversationSession session = Build(PlainYaml, model, sink: sink).Create("conversation-1"); + + // Act. + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Assert. The turn-altitude tool.failed row still names the fault, and still precedes the + // turn.completed of the same turn. + IReadOnlyList events = sink.EventsOf("conversation-1"); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.ToolFailed, AuditEventKind.TurnCompleted], + events.Select(entry => entry.Kind)); + Assert.Contains("the vendor is down", events[1].Payload[AuditPayloadKeys.ToolError], StringComparison.Ordinal); + } - [Fact] - public async Task RunStreaming_CleanTurn_MarkerOnLeadingUpdateAddsNoText() - { - // Arrange. - using SequencedChatClient model = new("the ordinary reply"); - var compiled = Compile(PlainYaml, model, out _, moderation: ScriptedModerationEvaluator.Clean()); - - // Act. - List updates = []; - await foreach (var update in compiled.TurnAgent.RunStreamingAsync( - "hello", cancellationToken: TestContext.Current.CancellationToken)) + // ------------------------------------------------------------------------------------------- + // Where the marker is readable. The read site differs by run shape, and that is measured. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Run_BufferedTurn_TurnDispositionReadableOnResponse() { - updates.Add(update); + // Arrange. + using SequencedChatClient model = new("the ordinary reply"); + CompiledAgent compiled = Compile(PlainYaml, model, out _, moderation: ScriptedModerationEvaluator.Clean()); + + // Act. + AgentResponse response = await compiled.TurnAgent.RunAsync( + "hello", cancellationToken: TestContext.Current.CancellationToken); + + // Assert. The marker rides the run itself, so nothing about the reply is disturbed. + AdditionalPropertiesDictionary? properties = response.AdditionalProperties; + Assert.NotNull(properties); + Assert.True(AdditionalPropertiesExtensions.TryGetValue(properties, out TurnDisposition? disposition)); + Assert.Equal(ModerationOutcome.Clean, disposition!.Moderation); } - // Assert. The marker rides an update with empty contents, so the caller's audio is untouched. - Assert.Equal("the ordinary reply", string.Concat(updates.Select(update => update.Text))); - Assert.Contains( - updates, - update => update.AdditionalProperties is { } properties - && AdditionalPropertiesExtensions.Contains(properties)); - } + [Fact] + public async Task RunStreaming_CleanTurn_MarkerOnLeadingUpdateAddsNoText() + { + // Arrange. + using SequencedChatClient model = new("the ordinary reply"); + CompiledAgent compiled = Compile(PlainYaml, model, out _, moderation: ScriptedModerationEvaluator.Clean()); + + // Act. + List updates = []; + await foreach (AgentResponseUpdate update in compiled.TurnAgent.RunStreamingAsync( + "hello", cancellationToken: TestContext.Current.CancellationToken)) + { + updates.Add(update); + } + + // Assert. The marker rides an update with empty contents, so the caller's audio is untouched. + Assert.Equal("the ordinary reply", string.Concat(updates.Select(update => update.Text))); + Assert.Contains( + updates, + update => update.AdditionalProperties is { } properties + && AdditionalPropertiesExtensions.Contains(properties)); + } - // ------------------------------------------------------------------------------------------- - // The layers wrap the agent a TURN runs, and never a graph node. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task Run_GraphRow_ModeratesTheCallerOnceAndNotOncePerNode() - { - // Arrange. Two nodes run for one turn. - using SequencedChatClient researcher = new("Let me check the order system."); - using SequencedChatClient responder = new("Order 41 ships Friday."); - var endpoint = ScriptedModerationEvaluator.Clean(); - var session = BuildGraph(researcher, responder, endpoint).Create("conversation-1"); - - // Act. - await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert. R3 is a rule about a turn, and one turn is one run of one agent on every row. - Assert.Equal(["where is my order"], endpoint.Moderated); - Assert.Equal(1, researcher.Calls); - Assert.Equal(1, responder.Calls); - } + // ------------------------------------------------------------------------------------------- + // The layers wrap the agent a TURN runs, and never a graph node. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task Run_GraphRow_ModeratesTheCallerOnceAndNotOncePerNode() + { + // Arrange. Two nodes run for one turn. + using SequencedChatClient researcher = new("Let me check the order system."); + using SequencedChatClient responder = new("Order 41 ships Friday."); + ScriptedModerationEvaluator endpoint = ScriptedModerationEvaluator.Clean(); + ConversationSession session = BuildGraph(researcher, responder, endpoint).Create("conversation-1"); + + // Act. + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert. R3 is a rule about a turn, and one turn is one run of one agent on every row. + Assert.Equal(["where is my order"], endpoint.Moderated); + Assert.Equal(1, researcher.Calls); + Assert.Equal(1, responder.Calls); + } - [Fact] - public async Task Run_GraphRowWhereNoNodeSpeaks_SpeaksTheFallbackOnceForTheTurn() - { - // Arrange. Every node runs and none of them produces a word. - using SequencedChatClient researcher = new(" "); - using SequencedChatClient responder = new(" "); - var session = BuildGraph(researcher, responder, moderation: null).Create("conversation-1"); - - // Act. - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert. R2 is a rule about a turn: one fallback is spoken to the caller, and none of it is - // fed back into the graph as a node reply. - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); - Assert.Equal(1, researcher.Calls); - Assert.Equal(1, responder.Calls); - } + [Fact] + public async Task Run_GraphRowWhereNoNodeSpeaks_SpeaksTheFallbackOnceForTheTurn() + { + // Arrange. Every node runs and none of them produces a word. + using SequencedChatClient researcher = new(" "); + using SequencedChatClient responder = new(" "); + ConversationSession session = BuildGraph(researcher, responder, moderation: null).Create("conversation-1"); + + // Act. + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert. R2 is a rule about a turn: one fallback is spoken to the caller, and none of it is + // fed back into the graph as a node reply. + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + Assert.Equal(ConversationSession.EmptyReplyReason, turn.Failure); + Assert.Equal(1, researcher.Calls); + Assert.Equal(1, responder.Calls); + } - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - private const string GraphYaml = - """ + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + private const string GraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -320,58 +320,59 @@ public async Task Run_GraphRowWhereNoNodeSpeaks_SpeaksTheFallbackOnceForTheTurn( agents: [ researcher, responder ] """; - private static ConversationSessionFactory BuildGraph( - IChatClient researcher, - IChatClient responder, - ScriptedModerationEvaluator? moderation) - { - RoutingChatClientFactory chatClients = new(researcher); - chatClients.Route("responder", responder); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(GraphYaml), - new AgentCompilationContext(chatClients) - { - Moderation = moderation is null ? null : new PromptModerator(moderation), - })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - observers: ConversationObservers.Standard(new InMemoryAuditSink(), logger: null)); - } - - private static CompiledAgent Compile( - string yaml, - IChatClient reply, - out RoutingChatClientFactory chatClients, - Func? tools = null, - ScriptedModerationEvaluator? moderation = null) - { - var document = ConfigurationLoader.LoadYaml(yaml); - chatClients = new RoutingChatClientFactory(reply); - - return ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - Moderation = moderation is null ? null : new PromptModerator(moderation), - })["main"]; - } - - private static ConversationSessionFactory Build( - string yaml, - IChatClient reply, - IAuditSinkPort? sink = null, - Func? tools = null, - ScriptedModerationEvaluator? moderation = null) - { - var compiled = Compile(yaml, reply, out _, tools, moderation); - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - observers: ConversationObservers.Standard(sink ?? new InMemoryAuditSink(), logger: null)); - } - } + private static ConversationSessionFactory BuildGraph( + IChatClient researcher, + IChatClient responder, + ScriptedModerationEvaluator? moderation) + { + RoutingChatClientFactory chatClients = new(researcher); + _ = chatClients.Route("responder", responder); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(GraphYaml), + new AgentCompilationContext(chatClients) + { + Moderation = moderation is null ? null : new PromptModerator(moderation), + })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + observers: ConversationObservers.Standard(new InMemoryAuditSink(), logger: null)); + } + + private static CompiledAgent Compile( + string yaml, + IChatClient reply, + out RoutingChatClientFactory chatClients, + Func? tools = null, + ScriptedModerationEvaluator? moderation = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + chatClients = new RoutingChatClientFactory(reply); + + return ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + Moderation = moderation is null ? null : new PromptModerator(moderation), + })["main"]; + } + + private static ConversationSessionFactory Build( + string yaml, + IChatClient reply, + IAuditSinkPort? sink = null, + Func? tools = null, + ScriptedModerationEvaluator? moderation = null) + { + CompiledAgent compiled = Compile(yaml, reply, out _, tools, moderation); + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + observers: ConversationObservers.Standard(sink ?? new InMemoryAuditSink(), logger: null)); + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs b/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs index 4e88b6c0..298f9d97 100644 --- a/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs @@ -10,14 +10,14 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Runtime; - -/// -/// The turn reaches its tools: the screen the loop builds arriving at the tool that publishes. -/// -public sealed class TurnScreenTests +namespace AgentCore.Application.Tests.Runtime { - private const string DelegationYaml = """ + /// + /// The turn reaches its tools: the screen the loop builds arriving at the tool that publishes. + /// + public sealed class TurnScreenTests + { + private const string DelegationYaml = """ apiVersion: agentcore/v1 tools: - { id: ask_specialist, kind: agent, agent: specialist, description: Ask the specialist. } @@ -35,120 +35,123 @@ public sealed class TurnScreenTests - { id: greeting, agent: greeter, terminal: true } """; - [Fact] - public async Task ATurnThatDoesNotStream_ShowsItsToolsTheScreen() - { - var (session, probe) = NewConversation(); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // The screen a tool finds must be the SAME recorder the turn publishes into, not merely - // some TurnRenders or other: a regression that handed the tool a different instance would - // still publish, and would still lose the render, since the drain reads the turn's own. - Assert.IsType(probe.Seen); - Assert.Same(probe.TurnRenders, probe.Seen); - } - - [Fact] - public async Task ATurnThatStreams_ShowsItsToolsTheScreenToo() - { - // The hazard this pins. An async iterator restores its caller's execution context at every - // yield, and the framework streams the tool-call update BEFORE it invokes the function, so a - // scope opened once reaches no round at all. Only the per-round re-entry in - // RunTurnStreamingAsync keeps the screen alive across it. - var (session, probe) = NewConversation(); - - await foreach (var _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) - { - } - - Assert.IsType(probe.Seen); - Assert.Same(probe.TurnRenders, probe.Seen); - } - - [Fact] - public async Task AConversationThatWasGivenNoScreen_ShowsItsToolsNone() - { - // The voice path. The tool reads the null and tells the model it cannot show anything, - // rather than claiming a picture a telephone caller will never see. - var (session, probe) = NewConversation(withScreen: false); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.True(probe.Ran); - Assert.Null(probe.Seen); - } - - [Fact] - public async Task AScreenTakenBackBeforeATurn_LeavesTheToolWithNone() - { - // A host sets this per request, and the whole-reply branch of the chat endpoint sets none. - // Taking it back has to reach the tool, or a session that streamed once keeps a screen the - // next answer has nowhere to write. - var (session, probe) = NewConversation(); - - session.SetHasScreen(false); - - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.True(probe.Ran); - Assert.Null(probe.Seen); - } - - /// Opens a conversation whose specialist is handed one tool that reports the screen it found. - private static (ConversationSession Session, ScreenProbe Probe) NewConversation(bool withScreen = true) - { - ToolCallingChatClient greeter = new( - "hello there.", - new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); - ToolCallingChatClient specialist = new("the specialist answer"); - - RoutingChatClientFactory chatClients = new(greeter); - chatClients.Route("reply", greeter); - chatClients.Route("specialist", specialist); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(DelegationYaml), new AgentCompilationContext(chatClients))["main"]; - - var session = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null).Create(); - - ScreenProbe probe = new(); - - session.SetHasScreen(withScreen); - session.SetDelegatedTools("ask_specialist", [probe.Tool]); - - return (session, probe); - } - - /// A tool that reports the screen and the recorder it found, from wherever it ran. - private sealed class ScreenProbe - { - public ScreenProbe() - => Tool = AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - Ran = true; - Seen = turn?.Screen; - TurnRenders = turn?.Renders; - return "shown."; - }, - new AIFunctionFactoryOptions - { - Name = "build_ui", - Description = "Show something on the caller's screen.", - ConfigureParameterBinding = ToolParameterBindings.For, - }); - - public AIFunction Tool { get; } - - public bool Ran { get; private set; } - - public IRenderPort? Seen { get; private set; } - - /// What the turn drew into at the same moment was read. - public TurnRenders? TurnRenders { get; private set; } - } - } + [Fact] + public async Task ATurnThatDoesNotStream_ShowsItsToolsTheScreen() + { + (ConversationSession? session, ScreenProbe? probe) = NewConversation(); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // The screen a tool finds must be the SAME recorder the turn publishes into, not merely + // some TurnRenders or other: a regression that handed the tool a different instance would + // still publish, and would still lose the render, since the drain reads the turn's own. + _ = Assert.IsType(probe.Seen); + Assert.Same(probe.TurnRenders, probe.Seen); + } + + [Fact] + public async Task ATurnThatStreams_ShowsItsToolsTheScreenToo() + { + // The hazard this pins. An async iterator restores its caller's execution context at every + // yield, and the framework streams the tool-call update BEFORE it invokes the function, so a + // scope opened once reaches no round at all. Only the per-round re-entry in + // RunTurnStreamingAsync keeps the screen alive across it. + (ConversationSession? session, ScreenProbe? probe) = NewConversation(); + + await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + } + + _ = Assert.IsType(probe.Seen); + Assert.Same(probe.TurnRenders, probe.Seen); + } + + [Fact] + public async Task AConversationThatWasGivenNoScreen_ShowsItsToolsNone() + { + // The voice path. The tool reads the null and tells the model it cannot show anything, + // rather than claiming a picture a telephone caller will never see. + (ConversationSession? session, ScreenProbe? probe) = NewConversation(withScreen: false); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.True(probe.Ran); + Assert.Null(probe.Seen); + } + + [Fact] + public async Task AScreenTakenBackBeforeATurn_LeavesTheToolWithNone() + { + // A host sets this per request, and the whole-reply branch of the chat endpoint sets none. + // Taking it back has to reach the tool, or a session that streamed once keeps a screen the + // next answer has nowhere to write. + (ConversationSession? session, ScreenProbe? probe) = NewConversation(); + + session.SetHasScreen(false); + + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.True(probe.Ran); + Assert.Null(probe.Seen); + } + + /// Opens a conversation whose specialist is handed one tool that reports the screen it found. + private static (ConversationSession Session, ScreenProbe Probe) NewConversation(bool withScreen = true) + { + ToolCallingChatClient greeter = new( + "hello there.", + new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); + ToolCallingChatClient specialist = new("the specialist answer"); + + RoutingChatClientFactory chatClients = new(greeter); + _ = chatClients.Route("reply", greeter); + _ = chatClients.Route("specialist", specialist); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(DelegationYaml), new AgentCompilationContext(chatClients))["main"]; + + ConversationSession session = new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null).Create(); + + ScreenProbe probe = new(); + + session.SetHasScreen(withScreen); + session.SetDelegatedTools("ask_specialist", [probe.Tool]); + + return (session, probe); + } + + /// A tool that reports the screen and the recorder it found, from wherever it ran. + private sealed class ScreenProbe + { + public ScreenProbe() + { + Tool = AIFunctionFactory.Create( + (TurnInvocation? turn) => + { + Ran = true; + Seen = turn?.Screen; + TurnRenders = turn?.Renders; + return "shown."; + }, + new AIFunctionFactoryOptions + { + Name = "build_ui", + Description = "Show something on the caller's screen.", + ConfigureParameterBinding = ToolParameterBindings.For, + }); + } + + public AIFunction Tool { get; } + + public bool Ran { get; private set; } + + public IRenderPort? Seen { get; private set; } + + /// What the turn drew into at the same moment was read. + public TurnRenders? TurnRenders { get; private set; } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Secrets/ResolvedSecretsTests.cs b/tests/AgentCore.Application.Tests/Secrets/ResolvedSecretsTests.cs index 7878e5c5..e976631c 100644 --- a/tests/AgentCore.Application.Tests/Secrets/ResolvedSecretsTests.cs +++ b/tests/AgentCore.Application.Tests/Secrets/ResolvedSecretsTests.cs @@ -4,47 +4,48 @@ using AgentCore.Application.Secrets; using AgentCore.Application.Tests.Configuration; using Xunit; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Secrets; - -/// -/// The seam the parser leaves open: ${secret:name} is a reference and never a value. -/// -/// -/// keeps the references, and turns them -/// into values once, at startup. A tool call never reaches . -/// -public sealed class ResolvedSecretsTests +namespace AgentCore.Application.Tests.Secrets { - private const string ApiKeyName = "orders-api-key"; - private const string ApiKeyValue = "sk-live-0123456789"; - - // --------------------------------------------------------------------------------------------- - // Resolving the whole document, once. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheWorkedExample_ResolvesItsOneSecret() + /// + /// The seam the parser leaves open: ${secret:name} is a reference and never a value. + /// + /// + /// keeps the references, and turns them + /// into values once, at startup. A tool call never reaches . + /// + public sealed class ResolvedSecretsTests { - var document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - MapSecretResolver resolver = new MapSecretResolver().With(ApiKeyName, ApiKeyValue); + private const string ApiKeyName = "orders-api-key"; + private const string ApiKeyValue = "sk-live-0123456789"; + + // --------------------------------------------------------------------------------------------- + // Resolving the whole document, once. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheWorkedExample_ResolvesItsOneSecret() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + MapSecretResolver resolver = new MapSecretResolver().With(ApiKeyName, ApiKeyValue); - var secrets = await ResolvedSecrets.ResolveAsync( - document, - resolver, - TestContext.Current.CancellationToken); + ResolvedSecrets secrets = await ResolvedSecrets.ResolveAsync( + document, + resolver, + TestContext.Current.CancellationToken); - Assert.Equal(1, secrets.Count); - Assert.Equal([ApiKeyName], secrets.Names); - Assert.True(secrets.Contains(ApiKeyName)); + Assert.Equal(1, secrets.Count); + Assert.Equal([ApiKeyName], secrets.Names); + Assert.True(secrets.Contains(ApiKeyName)); - var header = document.Tools.Single(tool => tool.Id == "lookup_order").Request!.Headers["Authorization"]; - Assert.Equal("Bearer " + ApiKeyValue, secrets.Format(header)); - } + SecretTemplate header = document.Tools.Single(tool => tool.Id == "lookup_order").Request!.Headers["Authorization"]; + Assert.Equal("Bearer " + ApiKeyValue, secrets.Format(header)); + } - [Fact] - public async Task AShellEnvValue_IsResolved_LikeAnMcpEnvValue() - { - const string document = """ + [Fact] + public async Task AShellEnvValue_IsResolved_LikeAnMcpEnvValue() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -58,21 +59,21 @@ public async Task AShellEnvValue_IsResolved_LikeAnMcpEnvValue() agent: worker """; - MapSecretResolver resolver = new MapSecretResolver().With("db-password", "hunter2"); + MapSecretResolver resolver = new MapSecretResolver().With("db-password", "hunter2"); - var secrets = await ResolvedSecrets.ResolveAsync( - ConfigurationLoader.LoadYaml(document), - resolver, - TestContext.Current.CancellationToken); + ResolvedSecrets secrets = await ResolvedSecrets.ResolveAsync( + ConfigurationLoader.LoadYaml(document), + resolver, + TestContext.Current.CancellationToken); - Assert.Equal(["db-password"], secrets.Names); - Assert.Equal(["db-password"], resolver.Asked); - } + Assert.Equal(["db-password"], secrets.Names); + Assert.Equal(["db-password"], resolver.Asked); + } - [Fact] - public async Task OneName_ReadsTheResolverOnce_HoweverManyToolsReferenceIt() - { - const string document = """ + [Fact] + public async Task OneName_ReadsTheResolverOnce_HoweverManyToolsReferenceIt() + { + const string document = """ apiVersion: agentcore/v1 agents: items: @@ -95,22 +96,22 @@ public async Task OneName_ReadsTheResolverOnce_HoweverManyToolsReferenceIt() headers: { Authorization: "Bearer ${secret:orders-api-key}" } """; - MapSecretResolver resolver = new MapSecretResolver().With(ApiKeyName, ApiKeyValue); + MapSecretResolver resolver = new MapSecretResolver().With(ApiKeyName, ApiKeyValue); - var secrets = await ResolvedSecrets.ResolveAsync( - ConfigurationLoader.LoadYaml(document), - resolver, - TestContext.Current.CancellationToken); + ResolvedSecrets secrets = await ResolvedSecrets.ResolveAsync( + ConfigurationLoader.LoadYaml(document), + resolver, + TestContext.Current.CancellationToken); - // Three references, one name, one read. Startup pays for the read, and no conversation does. - Assert.Equal([ApiKeyName], resolver.Asked); - Assert.Equal(1, secrets.Count); - } + // Three references, one name, one read. Startup pays for the read, and no conversation does. + Assert.Equal([ApiKeyName], resolver.Asked); + Assert.Equal(1, secrets.Count); + } - [Fact] - public async Task ADocumentWithNoReference_ReadsNothing() - { - const string document = """ + [Fact] + public async Task ADocumentWithNoReference_ReadsNothing() + { + const string document = """ apiVersion: agentcore/v1 tools: - id: plain @@ -127,112 +128,113 @@ public async Task ADocumentWithNoReference_ReadsNothing() agent: only """; - MapSecretResolver resolver = new(); - - var secrets = await ResolvedSecrets.ResolveAsync( - ConfigurationLoader.LoadYaml(document), - resolver, - TestContext.Current.CancellationToken); - - Assert.Empty(resolver.Asked); - Assert.Equal(0, secrets.Count); - } + MapSecretResolver resolver = new(); - // --------------------------------------------------------------------------------------------- - // Failing at startup, and never in the middle of a conversation. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AnUnresolvableName_FailsAtStartupAndNamesThePointer() - { - var document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - MapSecretResolver resolver = new(); - - var failure = await Assert.ThrowsAsync( - async () => await ResolvedSecrets.ResolveAsync( - document, + ResolvedSecrets secrets = await ResolvedSecrets.ResolveAsync( + ConfigurationLoader.LoadYaml(document), resolver, - TestContext.Current.CancellationToken)); + TestContext.Current.CancellationToken); - Assert.Equal(ApiKeyName, failure.SecretName); - Assert.Contains(ApiKeyName, failure.Message, StringComparison.Ordinal); - Assert.Contains("/tools/0/request/headers/Authorization", failure.Message, StringComparison.Ordinal); - } + Assert.Empty(resolver.Asked); + Assert.Equal(0, secrets.Count); + } - [Fact] - public void FormattingAnUnknownName_Fails() - { - var secrets = ResolvedSecrets.Create([KeyValuePair.Create(ApiKeyName, ApiKeyValue)]); - var template = SecretTemplate.Parse("${secret:missing-name}"); + // --------------------------------------------------------------------------------------------- + // Failing at startup, and never in the middle of a conversation. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AnUnresolvableName_FailsAtStartupAndNamesThePointer() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + MapSecretResolver resolver = new(); + + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await ResolvedSecrets.ResolveAsync( + document, + resolver, + TestContext.Current.CancellationToken)); + + Assert.Equal(ApiKeyName, failure.SecretName); + Assert.Contains(ApiKeyName, failure.Message, StringComparison.Ordinal); + Assert.Contains("/tools/0/request/headers/Authorization", failure.Message, StringComparison.Ordinal); + } - var failure = Assert.Throws(() => secrets.Format(template)); + [Fact] + public void FormattingAnUnknownName_Fails() + { + ResolvedSecrets secrets = ResolvedSecrets.Create([KeyValuePair.Create(ApiKeyName, ApiKeyValue)]); + SecretTemplate template = SecretTemplate.Parse("${secret:missing-name}"); - Assert.Equal("missing-name", failure.SecretName); - } + SecretResolutionException failure = Assert.Throws(() => secrets.Format(template)); - // --------------------------------------------------------------------------------------------- - // A value never reaches a log or a message. - // --------------------------------------------------------------------------------------------- - [Fact] - public void NoFailureMessage_EverHoldsAValue() - { - var secrets = ResolvedSecrets.Create([KeyValuePair.Create(ApiKeyName, ApiKeyValue)]); - var template = SecretTemplate.Parse("Bearer ${secret:orders-api-key} and ${secret:missing-name}"); + Assert.Equal("missing-name", failure.SecretName); + } - var failure = Assert.Throws(() => secrets.Format(template)); + // --------------------------------------------------------------------------------------------- + // A value never reaches a log or a message. + // --------------------------------------------------------------------------------------------- + [Fact] + public void NoFailureMessage_EverHoldsAValue() + { + ResolvedSecrets secrets = ResolvedSecrets.Create([KeyValuePair.Create(ApiKeyName, ApiKeyValue)]); + SecretTemplate template = SecretTemplate.Parse("Bearer ${secret:orders-api-key} and ${secret:missing-name}"); - Assert.DoesNotContain(ApiKeyValue, failure.ToString(), StringComparison.Ordinal); - } + SecretResolutionException failure = Assert.Throws(() => secrets.Format(template)); - [Fact] - public void TheResolvedSet_NeverWritesAValueInItsOwnText() - { - var secrets = ResolvedSecrets.Create([KeyValuePair.Create(ApiKeyName, ApiKeyValue)]); + Assert.DoesNotContain(ApiKeyValue, failure.ToString(), StringComparison.Ordinal); + } - // A resolved set lands in a log line, a diagnostic dump, or a debugger tooltip sooner or - // later. It reports how many names it holds, and never what they are worth. - Assert.DoesNotContain(ApiKeyValue, secrets.ToString(), StringComparison.Ordinal); - } + [Fact] + public void TheResolvedSet_NeverWritesAValueInItsOwnText() + { + ResolvedSecrets secrets = ResolvedSecrets.Create([KeyValuePair.Create(ApiKeyName, ApiKeyValue)]); - // --------------------------------------------------------------------------------------------- - // Formatting. - // --------------------------------------------------------------------------------------------- - [Fact] - public void ATemplateWithNoReference_FormatsToItself() - { - var template = SecretTemplate.Parse("application/json"); + // A resolved set lands in a log line, a diagnostic dump, or a debugger tooltip sooner or + // later. It reports how many names it holds, and never what they are worth. + Assert.DoesNotContain(ApiKeyValue, secrets.ToString(), StringComparison.Ordinal); + } - Assert.Equal("application/json", ResolvedSecrets.Empty.Format(template)); - } + // --------------------------------------------------------------------------------------------- + // Formatting. + // --------------------------------------------------------------------------------------------- + [Fact] + public void ATemplateWithNoReference_FormatsToItself() + { + SecretTemplate template = SecretTemplate.Parse("application/json"); - [Fact] - public void TwoReferencesInOneString_BothResolve() - { - var secrets = ResolvedSecrets.Create( - [ - KeyValuePair.Create("left", "L"), - KeyValuePair.Create("right", "R"), - ]); + Assert.Equal("application/json", ResolvedSecrets.Empty.Format(template)); + } - Assert.Equal("", secrets.Format(SecretTemplate.Parse("<${secret:left}|${secret:right}>"))); - } + [Fact] + public void TwoReferencesInOneString_BothResolve() + { + ResolvedSecrets secrets = ResolvedSecrets.Create( + [ + KeyValuePair.Create("left", "L"), + KeyValuePair.Create("right", "R"), + ]); - [Fact] - public async Task TheResolver_TakesTheCancellationTokenTheCallerGives() - { - var document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - using CancellationTokenSource source = new(); - await source.CancelAsync(); + Assert.Equal("", secrets.Format(SecretTemplate.Parse("<${secret:left}|${secret:right}>"))); + } - await Assert.ThrowsAnyAsync( - async () => await ResolvedSecrets.ResolveAsync(document, new CancellingSecretResolver(), source.Token)); - } + [Fact] + public async Task TheResolver_TakesTheCancellationTokenTheCallerGives() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + using CancellationTokenSource source = new(); + await source.CancelAsync(); - private sealed class CancellingSecretResolver : ISecretResolverPort - { - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + _ = await Assert.ThrowsAnyAsync( + async () => await ResolvedSecrets.ResolveAsync(document, new CancellingSecretResolver(), source.Token)); + } + + private sealed class CancellingSecretResolver : ISecretResolverPort { - cancellationToken.ThrowIfCancellationRequested(); - return ValueTask.FromResult(null); + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + cancellationToken.ThrowIfCancellationRequested(); + return ValueTask.FromResult(null); + } } } } diff --git a/tests/AgentCore.Application.Tests/Secrets/SecretOptionalReadTests.cs b/tests/AgentCore.Application.Tests/Secrets/SecretOptionalReadTests.cs index 1f8d089e..a2532dbd 100644 --- a/tests/AgentCore.Application.Tests/Secrets/SecretOptionalReadTests.cs +++ b/tests/AgentCore.Application.Tests/Secrets/SecretOptionalReadTests.cs @@ -3,189 +3,190 @@ using AgentCore.Application.Secrets; using Xunit; -namespace AgentCore.Application.Tests.Secrets; - -/// -/// The optional read: a credential whose absence picks a path rather than failing one. -/// -/// -/// -/// answers the case where a host cannot start -/// without a key. answers the other case, and -/// is what asked for it: no instance id means -/// export to a collector with no credential, and an instance id makes the token beside it mandatory. -/// -/// -/// These tests pin two things. The optional read walks the same two places in the same order as the -/// required one, and the two agree on what a blank answer means, because the required path is now -/// written in terms of this one and a change to either would otherwise pass unnoticed. -/// -/// -/// Every test that writes an environment variable owns a name of its own and puts back whatever it -/// found, so one test never decides the answer of another. -/// -/// -public sealed class SecretOptionalReadTests +namespace AgentCore.Application.Tests.Secrets { - private const string SecretValue = "grafana-instance-123456"; - private const string OtherValue = "grafana-instance-999999"; - - [Fact] - public async Task TheChain_AnswersBeforeTheEnvironment() + /// + /// The optional read: a credential whose absence picks a path rather than failing one. + /// + /// + /// + /// answers the case where a host cannot start + /// without a key. answers the other case, and + /// is what asked for it: no instance id means + /// export to a collector with no credential, and an instance id makes the token beside it mandatory. + /// + /// + /// These tests pin two things. The optional read walks the same two places in the same order as the + /// required one, and the two agree on what a blank answer means, because the required path is now + /// written in terms of this one and a change to either would otherwise pass unnoticed. + /// + /// + /// Every test that writes an environment variable owns a name of its own and puts back whatever it + /// found, so one test never decides the answer of another. + /// + /// + public sealed class SecretOptionalReadTests { - SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_CHAIN_FIRST"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); - - try - { - MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, SecretValue); + private const string SecretValue = "grafana-instance-123456"; + private const string OtherValue = "grafana-instance-999999"; - var value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); - - // Same order as the required read. A bound resolver is the deployment saying where its - // secrets live, so the variable is a fallback and never an override. - Assert.Equal(SecretValue, value); - Assert.Equal([secret.Name], resolver.Asked); - } - finally + [Fact] + public async Task TheChain_AnswersBeforeTheEnvironment() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_CHAIN_FIRST"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); + + try + { + MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, SecretValue); + + string? value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); + + // Same order as the required read. A bound resolver is the deployment saying where its + // secrets live, so the variable is a fallback and never an override. + Assert.Equal(SecretValue, value); + Assert.Equal([secret.Name], resolver.Asked); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - [Fact] - public async Task TheVariable_AnswersWhenTheChainHoldsNothing() - { - SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_VARIABLE"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - - try - { - MapSecretResolver resolver = new(); - var value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); - - Assert.Equal(SecretValue, value); - } - finally + [Fact] + public async Task TheVariable_AnswersWhenTheChainHoldsNothing() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_VARIABLE"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); + + try + { + MapSecretResolver resolver = new(); + + string? value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); + + Assert.Equal(SecretValue, value); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - [Fact] - public async Task NeitherPlace_AnswersNullRatherThanThrowing() - { - SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_ABSENT"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, null); - try + [Fact] + public async Task NeitherPlace_AnswersNullRatherThanThrowing() { - MapSecretResolver resolver = new(); - - var value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); - - // This is the whole point of the method. A host that names no Grafana instance exports - // with no credential, and that is an answer rather than a failure. - Assert.Null(value); + SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_ABSENT"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, null); + + try + { + MapSecretResolver resolver = new(); + + string? value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); + + // This is the whole point of the method. A host that names no Grafana instance exports + // with no credential, and that is an answer rather than a failure. + Assert.Null(value); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally - { - Environment.SetEnvironmentVariable(secret.VariableName, saved); - } - } - [Fact] - public async Task ANullResolver_ReadsTheEnvironmentAlone() - { - SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_NO_CHAIN"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - - try - { - ISecretResolverPort? none = null; - - var value = await none.TryReadAsync(secret, TestContext.Current.CancellationToken); - - // A host that binds no chain is an ordinary case, so the extension takes the null rather - // than making each caller test for it. - Assert.Equal(SecretValue, value); - } - finally + [Fact] + public async Task ANullResolver_ReadsTheEnvironmentAlone() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_NO_CHAIN"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); + + try + { + ISecretResolverPort? none = null; + + string? value = await none.TryReadAsync(secret, TestContext.Current.CancellationToken); + + // A host that binds no chain is an ordinary case, so the extension takes the null rather + // than making each caller test for it. + Assert.Equal(SecretValue, value); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - [Fact] - public async Task ABlankChainAnswer_IsHeldAndEmpty_NotAMiss() - { - SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_BLANK"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); - - try - { - MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, string.Empty); - - var value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); - // The empty string is returned rather than swallowed, so the caller can tell "the store - // held this name and it is empty" from "nowhere holds it". Falling back to the variable - // here would start the host on some other key the deployment never named. - Assert.Equal(string.Empty, value); - } - finally + [Fact] + public async Task ABlankChainAnswer_IsHeldAndEmpty_NotAMiss() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + SecretName secret = new("grafana-cloud-instance-id", "AGENTCORE_TEST_TRYREAD_BLANK"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); + + try + { + MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, string.Empty); + + string? value = await resolver.TryReadAsync(secret, TestContext.Current.CancellationToken); + + // The empty string is returned rather than swallowed, so the caller can tell "the store + // held this name and it is empty" from "nowhere holds it". Falling back to the variable + // here would start the host on some other key the deployment never named. + Assert.Equal(string.Empty, value); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - [Fact] - public async Task TheRequiredRead_StillFailsOnTheBlankTheOptionalReadReturns() - { - SecretName secret = new("grafana-cloud-api-token", "AGENTCORE_TEST_TRYREAD_BLANK_REQUIRED"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); - try + [Fact] + public async Task TheRequiredRead_StillFailsOnTheBlankTheOptionalReadReturns() { - MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, string.Empty); - - // RequireAsync is now written in terms of TryReadAsync. This is the test that fails if - // that refactor ever changes what a blank answer means on the required path: a mounted - // secret file that renders empty must stop the host, not quietly read the variable. - var failure = await Assert.ThrowsAsync( - async () => await resolver.RequireAsync( - secret, - cancellationToken: TestContext.Current.CancellationToken)); - - Assert.Contains(secret.Name, failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain(OtherValue, failure.Message, StringComparison.Ordinal); + SecretName secret = new("grafana-cloud-api-token", "AGENTCORE_TEST_TRYREAD_BLANK_REQUIRED"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); + + try + { + MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, string.Empty); + + // RequireAsync is now written in terms of TryReadAsync. This is the test that fails if + // that refactor ever changes what a blank answer means on the required path: a mounted + // secret file that renders empty must stop the host, not quietly read the variable. + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await resolver.RequireAsync( + secret, + cancellationToken: TestContext.Current.CancellationToken)); + + Assert.Contains(secret.Name, failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain(OtherValue, failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally + + [Fact] + public void TheGrafanaCredential_IsNamedInBothPlaces() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + // A pair with a blank half would ask the chain for nothing and fall back to nothing, and the + // failure would arrive as a missing key rather than as the typo it is. + Assert.Equal(KnownSecrets.GrafanaCloudInstanceIdName, KnownSecrets.GrafanaCloudInstanceId.Name); + Assert.Equal(KnownSecrets.GrafanaCloudInstanceIdVariable, KnownSecrets.GrafanaCloudInstanceId.VariableName); + Assert.Equal(KnownSecrets.GrafanaCloudApiTokenName, KnownSecrets.GrafanaCloudApiToken.Name); + Assert.Equal(KnownSecrets.GrafanaCloudApiTokenVariable, KnownSecrets.GrafanaCloudApiToken.VariableName); + + // The two halves are one credential and must not collide with each other or with a vendor + // key that already exists. + Assert.NotEqual(KnownSecrets.GrafanaCloudInstanceId, KnownSecrets.GrafanaCloudApiToken); + Assert.NotEqual(KnownSecrets.GrafanaCloudApiToken, KnownSecrets.OpenAi); } } - - [Fact] - public void TheGrafanaCredential_IsNamedInBothPlaces() - { - // A pair with a blank half would ask the chain for nothing and fall back to nothing, and the - // failure would arrive as a missing key rather than as the typo it is. - Assert.Equal(KnownSecrets.GrafanaCloudInstanceIdName, KnownSecrets.GrafanaCloudInstanceId.Name); - Assert.Equal(KnownSecrets.GrafanaCloudInstanceIdVariable, KnownSecrets.GrafanaCloudInstanceId.VariableName); - Assert.Equal(KnownSecrets.GrafanaCloudApiTokenName, KnownSecrets.GrafanaCloudApiToken.Name); - Assert.Equal(KnownSecrets.GrafanaCloudApiTokenVariable, KnownSecrets.GrafanaCloudApiToken.VariableName); - - // The two halves are one credential and must not collide with each other or with a vendor - // key that already exists. - Assert.NotEqual(KnownSecrets.GrafanaCloudInstanceId, KnownSecrets.GrafanaCloudApiToken); - Assert.NotEqual(KnownSecrets.GrafanaCloudApiToken, KnownSecrets.OpenAi); - } } diff --git a/tests/AgentCore.Application.Tests/Secrets/SecretResolverExtensionsTests.cs b/tests/AgentCore.Application.Tests/Secrets/SecretResolverExtensionsTests.cs index 303449c1..89893267 100644 --- a/tests/AgentCore.Application.Tests/Secrets/SecretResolverExtensionsTests.cs +++ b/tests/AgentCore.Application.Tests/Secrets/SecretResolverExtensionsTests.cs @@ -3,292 +3,295 @@ using AgentCore.Application.Secrets; using Xunit; -namespace AgentCore.Application.Tests.Secrets; - -/// -/// The three steps every vendor adapter used to write for itself: the chain, the variable, the fail. -/// -/// -/// -/// answers for a name it does not hold, so -/// something has to decide what a miss means for a credential a host cannot start without. -/// is that decision, and these tests pin the -/// order of the two places it reads and the shape of the failure when neither holds anything. -/// -/// -/// Every test that writes an environment variable owns a name of its own and puts back whatever it -/// found, so one test never decides the answer of another. -/// -/// -public sealed class SecretResolverExtensionsTests +namespace AgentCore.Application.Tests.Secrets { - private const string SecretValue = "sk-live-0123456789"; - private const string OtherValue = "sk-live-9876543210"; - - // --------------------------------------------------------------------------------------------- - // The chain answers first. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheChain_AnswersBeforeTheEnvironment() + /// + /// The three steps every vendor adapter used to write for itself: the chain, the variable, the fail. + /// + /// + /// + /// answers for a name it does not hold, so + /// something has to decide what a miss means for a credential a host cannot start without. + /// is that decision, and these tests pin the + /// order of the two places it reads and the shape of the failure when neither holds anything. + /// + /// + /// Every test that writes an environment variable owns a name of its own and puts back whatever it + /// found, so one test never decides the answer of another. + /// + /// + public sealed class SecretResolverExtensionsTests { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_CHAIN_FIRST"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); - - try + private const string SecretValue = "sk-live-0123456789"; + private const string OtherValue = "sk-live-9876543210"; + + // --------------------------------------------------------------------------------------------- + // The chain answers first. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheChain_AnswersBeforeTheEnvironment() { - MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, SecretValue); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_CHAIN_FIRST"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, OtherValue); - var value = await resolver.RequireAsync( - secret, - cancellationToken: TestContext.Current.CancellationToken); + try + { + MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, SecretValue); - // A bound resolver is the deployment saying where its secrets live, so the variable is a - // fallback and never an override. - Assert.Equal(SecretValue, value); - Assert.Equal([secret.Name], resolver.Asked); - } - finally - { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + string value = await resolver.RequireAsync( + secret, + cancellationToken: TestContext.Current.CancellationToken); + + // A bound resolver is the deployment saying where its secrets live, so the variable is a + // fallback and never an override. + Assert.Equal(SecretValue, value); + Assert.Equal([secret.Name], resolver.Asked); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - // --------------------------------------------------------------------------------------------- - // The variable answers the miss. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AChainThatHoldsNothing_FallsBackToTheVariable() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_CHAIN_MISS"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - try + // --------------------------------------------------------------------------------------------- + // The variable answers the miss. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AChainThatHoldsNothing_FallsBackToTheVariable() { - MapSecretResolver resolver = new(); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_CHAIN_MISS"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - var value = await resolver.RequireAsync( - secret, - cancellationToken: TestContext.Current.CancellationToken); + try + { + MapSecretResolver resolver = new(); - // The chain was asked, said nothing, and the variable answered. - Assert.Equal(SecretValue, value); - Assert.Equal([secret.Name], resolver.Asked); + string value = await resolver.RequireAsync( + secret, + cancellationToken: TestContext.Current.CancellationToken); + + // The chain was asked, said nothing, and the variable answered. + Assert.Equal(SecretValue, value); + Assert.Equal([secret.Name], resolver.Asked); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally + + [Fact] + public async Task AChainThatAnswersABlankString_FailsAndNeverReadsTheVariable() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_BLANK_ANSWER"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); + + try + { + // A store that answers the empty string held the name: a mounted file that renders + // empty is a broken deployment and never a miss. Reading the variable instead would + // start the host on a key it was never told to use, and nothing would report it. + MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, string.Empty); + + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await resolver.RequireAsync( + secret, + cancellationToken: TestContext.Current.CancellationToken)); + + Assert.Contains(secret.Name, failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain(SecretValue, failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - [Fact] - public async Task AChainThatAnswersABlankString_FailsAndNeverReadsTheVariable() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_BLANK_ANSWER"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - try + [Fact] + public async Task NoChainAtAll_ReadsTheVariableAlone() { - // A store that answers the empty string held the name: a mounted file that renders - // empty is a broken deployment and never a miss. Reading the variable instead would - // start the host on a key it was never told to use, and nothing would report it. - MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, string.Empty); - - var failure = await Assert.ThrowsAsync( - async () => await resolver.RequireAsync( + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_NO_CHAIN"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); + + try + { + // A host that binds no resolver is an ordinary case, so the null is answered here rather + // than at every conversation site. + string value = await SecretResolverExtensions.RequireAsync( + null, secret, - cancellationToken: TestContext.Current.CancellationToken)); - - Assert.Contains(secret.Name, failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain(SecretValue, failure.Message, StringComparison.Ordinal); + cancellationToken: TestContext.Current.CancellationToken); + + Assert.Equal(SecretValue, value); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally - { - Environment.SetEnvironmentVariable(secret.VariableName, saved); - } - } - - [Fact] - public async Task NoChainAtAll_ReadsTheVariableAlone() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_NO_CHAIN"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - try + // --------------------------------------------------------------------------------------------- + // Failing at startup, and never with a value in the message. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task NoKeyAnywhere_FailsAndNamesBothPlacesToPutOne() { - // A host that binds no resolver is an ordinary case, so the null is answered here rather - // than at every conversation site. - var value = await SecretResolverExtensions.RequireAsync( - null, - secret, - cancellationToken: TestContext.Current.CancellationToken); - - Assert.Equal(SecretValue, value); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_NOWHERE"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, null); + + try + { + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await new MapSecretResolver().RequireAsync( + secret, + cancellationToken: TestContext.Current.CancellationToken)); + + // The reader has two places to put a key, so the message names both of them. + Assert.Contains(secret.Name, failure.Message, StringComparison.Ordinal); + Assert.Contains(secret.VariableName, failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally - { - Environment.SetEnvironmentVariable(secret.VariableName, saved); - } - } - // --------------------------------------------------------------------------------------------- - // Failing at startup, and never with a value in the message. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task NoKeyAnywhere_FailsAndNamesBothPlacesToPutOne() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_NOWHERE"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, null); - - try + [Fact] + public async Task AVariableSetToNothing_FailsLikeAnUnsetOne() { - var failure = await Assert.ThrowsAsync( - async () => await new MapSecretResolver().RequireAsync( - secret, - cancellationToken: TestContext.Current.CancellationToken)); - - // The reader has two places to put a key, so the message names both of them. - Assert.Contains(secret.Name, failure.Message, StringComparison.Ordinal); - Assert.Contains(secret.VariableName, failure.Message, StringComparison.Ordinal); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_EMPTY_VARIABLE"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, string.Empty); + + try + { + // An exported variable with nothing in it is a deployment that meant to set one and did + // not. It fails at startup, where the message can still say what to do about it. + _ = await Assert.ThrowsAsync( + async () => await new MapSecretResolver().RequireAsync( + secret, + cancellationToken: TestContext.Current.CancellationToken)); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally - { - Environment.SetEnvironmentVariable(secret.VariableName, saved); - } - } - [Fact] - public async Task AVariableSetToNothing_FailsLikeAnUnsetOne() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_EMPTY_VARIABLE"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, string.Empty); - - try + [Fact] + public async Task TheFailure_SaysWhatTheKeyWasNeededFor() { - // An exported variable with nothing in it is a deployment that meant to set one and did - // not. It fails at startup, where the message can still say what to do about it. - await Assert.ThrowsAsync( - async () => await new MapSecretResolver().RequireAsync( - secret, - cancellationToken: TestContext.Current.CancellationToken)); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_BECAUSE"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + Environment.SetEnvironmentVariable(secret.VariableName, null); + + try + { + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await new MapSecretResolver().RequireAsync( + secret, + "The zilliz store embeds every query with text-embedding-3-small.", + TestContext.Current.CancellationToken)); + + // A host that never asked for an embedding model learns why one was asking for a key. + Assert.Contains("text-embedding-3-small", failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - finally + + [Fact] + public async Task NoFailureMessage_EverHoldsAValue() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + SecretName secret = new("orders-api-key", "AGENTCORE_TEST_NO_LEAK"); + string? saved = Environment.GetEnvironmentVariable(secret.VariableName); + + // The variable holds a key, and the chain is asked for a name nothing holds. The failure + // travels through a log, an alert, and a support ticket, so it carries neither value. + Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); + + try + { + SecretName missing = new("missing-api-key", "AGENTCORE_TEST_NO_LEAK_UNSET"); + MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, OtherValue); + + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await resolver.RequireAsync( + missing, + cancellationToken: TestContext.Current.CancellationToken)); + + Assert.DoesNotContain(SecretValue, failure.ToString(), StringComparison.Ordinal); + Assert.DoesNotContain(OtherValue, failure.ToString(), StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(secret.VariableName, saved); + } } - } - - [Fact] - public async Task TheFailure_SaysWhatTheKeyWasNeededFor() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_BECAUSE"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - Environment.SetEnvironmentVariable(secret.VariableName, null); - try + // --------------------------------------------------------------------------------------------- + // The read is a read, and the caller still owns the token. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheChain_TakesTheCancellationTokenTheCallerGives() { - var failure = await Assert.ThrowsAsync( - async () => await new MapSecretResolver().RequireAsync( - secret, - "The zilliz store embeds every query with text-embedding-3-small.", - TestContext.Current.CancellationToken)); + using CancellationTokenSource source = new(); + await source.CancelAsync(); - // A host that never asked for an embedding model learns why one was asking for a key. - Assert.Contains("text-embedding-3-small", failure.Message, StringComparison.Ordinal); + _ = await Assert.ThrowsAnyAsync( + async () => await new CancellingSecretResolver().RequireAsync( + KnownSecrets.OpenAi, + cancellationToken: source.Token)); } - finally + + // --------------------------------------------------------------------------------------------- + // The catalog and the pair. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TheCatalog_PairsEachNameWithTheVariableOfItsVendor() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + // Every adapter of a vendor reads the same two strings, and this is where they are written. + Assert.Equal("openai-api-key", KnownSecrets.OpenAiApiKeyName); + Assert.Equal("OPENAI_API_KEY", KnownSecrets.OpenAiApiKeyVariable); + Assert.Equal(new SecretName("openai-api-key", "OPENAI_API_KEY"), KnownSecrets.OpenAi); + + Assert.Equal("qdrant-api-key", KnownSecrets.QdrantApiKeyName); + Assert.Equal("QDRANT_API_KEY", KnownSecrets.QdrantApiKeyVariable); + Assert.Equal(new SecretName("qdrant-api-key", "QDRANT_API_KEY"), KnownSecrets.Qdrant); } - } - - [Fact] - public async Task NoFailureMessage_EverHoldsAValue() - { - SecretName secret = new("orders-api-key", "AGENTCORE_TEST_NO_LEAK"); - var saved = Environment.GetEnvironmentVariable(secret.VariableName); - // The variable holds a key, and the chain is asked for a name nothing holds. The failure - // travels through a log, an alert, and a support ticket, so it carries neither value. - Environment.SetEnvironmentVariable(secret.VariableName, SecretValue); - - try + [Theory] + [InlineData("", "OPENAI_API_KEY")] + [InlineData(" ", "OPENAI_API_KEY")] + [InlineData("openai-api-key", "")] + [InlineData("openai-api-key", " ")] + public void APairWithABlankHalf_IsRefusedWhereItIsWritten(string name, string variable) { - SecretName missing = new("missing-api-key", "AGENTCORE_TEST_NO_LEAK_UNSET"); - MapSecretResolver resolver = new MapSecretResolver().With(secret.Name, OtherValue); - - var failure = await Assert.ThrowsAsync( - async () => await resolver.RequireAsync( - missing, - cancellationToken: TestContext.Current.CancellationToken)); - - Assert.DoesNotContain(SecretValue, failure.ToString(), StringComparison.Ordinal); - Assert.DoesNotContain(OtherValue, failure.ToString(), StringComparison.Ordinal); + // A blank half asks the chain for nothing, or falls back to nothing, and the failure would + // then arrive as a missing key rather than as the typo it is. + _ = Assert.Throws(() => new SecretName(name, variable)); } - finally + + [Fact] + public void ThePair_WritesBothNamesAndNoValue() { - Environment.SetEnvironmentVariable(secret.VariableName, saved); + Assert.Equal("openai-api-key (OPENAI_API_KEY)", KnownSecrets.OpenAi.ToString()); } - } - - // --------------------------------------------------------------------------------------------- - // The read is a read, and the caller still owns the token. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheChain_TakesTheCancellationTokenTheCallerGives() - { - using CancellationTokenSource source = new(); - await source.CancelAsync(); - - await Assert.ThrowsAnyAsync( - async () => await new CancellingSecretResolver().RequireAsync( - KnownSecrets.OpenAi, - cancellationToken: source.Token)); - } - - // --------------------------------------------------------------------------------------------- - // The catalog and the pair. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TheCatalog_PairsEachNameWithTheVariableOfItsVendor() - { - // Every adapter of a vendor reads the same two strings, and this is where they are written. - Assert.Equal("openai-api-key", KnownSecrets.OpenAiApiKeyName); - Assert.Equal("OPENAI_API_KEY", KnownSecrets.OpenAiApiKeyVariable); - Assert.Equal(new SecretName("openai-api-key", "OPENAI_API_KEY"), KnownSecrets.OpenAi); - - Assert.Equal("qdrant-api-key", KnownSecrets.QdrantApiKeyName); - Assert.Equal("QDRANT_API_KEY", KnownSecrets.QdrantApiKeyVariable); - Assert.Equal(new SecretName("qdrant-api-key", "QDRANT_API_KEY"), KnownSecrets.Qdrant); - } - [Theory] - [InlineData("", "OPENAI_API_KEY")] - [InlineData(" ", "OPENAI_API_KEY")] - [InlineData("openai-api-key", "")] - [InlineData("openai-api-key", " ")] - public void APairWithABlankHalf_IsRefusedWhereItIsWritten(string name, string variable) - { - // A blank half asks the chain for nothing, or falls back to nothing, and the failure would - // then arrive as a missing key rather than as the typo it is. - Assert.Throws(() => new SecretName(name, variable)); - } - - [Fact] - public void ThePair_WritesBothNamesAndNoValue() - => Assert.Equal("openai-api-key (OPENAI_API_KEY)", KnownSecrets.OpenAi.ToString()); - - private sealed class CancellingSecretResolver : ISecretResolverPort - { - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + private sealed class CancellingSecretResolver : ISecretResolverPort { - cancellationToken.ThrowIfCancellationRequested(); - return ValueTask.FromResult(null); + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + cancellationToken.ThrowIfCancellationRequested(); + return ValueTask.FromResult(null); + } } } } diff --git a/tests/AgentCore.Application.Tests/Sessions/ConversationSessionsTests.cs b/tests/AgentCore.Application.Tests/Sessions/ConversationSessionsTests.cs index 9fb0ff8e..c285e07d 100644 --- a/tests/AgentCore.Application.Tests/Sessions/ConversationSessionsTests.cs +++ b/tests/AgentCore.Application.Tests/Sessions/ConversationSessionsTests.cs @@ -6,135 +6,138 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using Microsoft.Extensions.AI; -using Microsoft.Extensions.DependencyInjection; using Xunit; +using AgentCore.Domain; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Sessions; - -/// -/// The lifecycle of one conversation's session: opened, found again, and closed. -/// -public sealed class ConversationSessionsTests +namespace AgentCore.Application.Tests.Sessions { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task ASessionThatWasOpenedIsFoundAgainUnderItsConversationId() + /// + /// The lifecycle of one conversation's session: opened, found again, and closed. + /// + public sealed class ConversationSessionsTests { - InMemoryConversationSessions sessions = new(Factory(), TimeSpan.FromMinutes(30), Clock()); + private static CancellationToken Token => TestContext.Current.CancellationToken; - var opened = await sessions.OpenAsync("conversation-1", Token); + [Fact] + public async Task ASessionThatWasOpenedIsFoundAgainUnderItsConversationId() + { + InMemoryConversationSessions sessions = new(Factory(), TimeSpan.FromMinutes(30), Clock()); - Assert.Same(opened, await sessions.TryGetAsync("conversation-1", Token)); - } + ConversationSession opened = await sessions.OpenAsync("conversation-1", Token); - [Fact] - public async Task ClosingAConversationWaitsForTheWordsItStillOwes() - { - // A real store answers over a network, so a write outlives the turn that queued it. This - // session is the only thing that can wait for it, and closing is the last moment anything can. - ParkingConversationStore transcript = new(); - InMemoryConversationSessions sessions = new(Factory(transcript), TimeSpan.FromMinutes(30), Clock()); - var session = await sessions.OpenAsync("conversation-1", Token); + Assert.Same(opened, await sessions.TryGetAsync("conversation-1", Token)); + } - var turn = session.RunTurnAsync("hello", Token); - await transcript.Parked; + [Fact] + public async Task ClosingAConversationWaitsForTheWordsItStillOwes() + { + // A real store answers over a network, so a write outlives the turn that queued it. This + // session is the only thing that can wait for it, and closing is the last moment anything can. + ParkingConversationStore transcript = new(); + InMemoryConversationSessions sessions = new(Factory(transcript), TimeSpan.FromMinutes(30), Clock()); + ConversationSession session = await sessions.OpenAsync("conversation-1", Token); - var closing = sessions.CloseAsync("conversation-1", Token).AsTask(); - var returnedEarly = await Task.WhenAny(closing, Task.Delay(200, Token)) == closing; - Assert.False(returnedEarly); + Task turn = session.RunTurnAsync("hello", Token); + await transcript.Parked; - transcript.Release(); - await closing; + Task closing = sessions.CloseAsync("conversation-1", Token).AsTask(); + bool returnedEarly = await Task.WhenAny(closing, Task.Delay(200, Token)) == closing; + Assert.False(returnedEarly); - Assert.True(transcript.Landed); - Assert.Null(await sessions.TryGetAsync("conversation-1", Token)); - await turn; - } + transcript.Release(); + await closing; - [Fact] - public async Task ASessionNobodyTouchedPastTheIdleTimeoutIsClosed() - { - var clock = Clock(); - InMemoryConversationSessions sessions = new(Factory(), TimeSpan.FromMinutes(30), clock); - await sessions.OpenAsync("conversation-1", Token); + Assert.True(transcript.Landed); + Assert.Null(await sessions.TryGetAsync("conversation-1", Token)); + _ = await turn; + } - clock.Advance(TimeSpan.FromMinutes(31)); - await sessions.SweepAsync(Token); + [Fact] + public async Task ASessionNobodyTouchedPastTheIdleTimeoutIsClosed() + { + FakeTimeProvider clock = Clock(); + InMemoryConversationSessions sessions = new(Factory(), TimeSpan.FromMinutes(30), clock); + _ = await sessions.OpenAsync("conversation-1", Token); - // A caller that abandons a text conversation never reaches a terminal stage, so nothing else would - // ever drop this session and the process would hold it for its whole life. - Assert.Null(await sessions.TryGetAsync("conversation-1", Token)); - Assert.Equal(0, sessions.Count); - } + clock.Advance(TimeSpan.FromMinutes(31)); + await sessions.SweepAsync(Token); - [Fact] - public async Task ReadingASessionPutsItsIdleClockBackToZero() - { - var clock = Clock(); - InMemoryConversationSessions sessions = new(Factory(), TimeSpan.FromMinutes(30), clock); - await sessions.OpenAsync("conversation-1", Token); + // A caller that abandons a text conversation never reaches a terminal stage, so nothing else would + // ever drop this session and the process would hold it for its whole life. + Assert.Null(await sessions.TryGetAsync("conversation-1", Token)); + Assert.Equal(0, sessions.Count); + } - clock.Advance(TimeSpan.FromMinutes(20)); - Assert.NotNull(await sessions.TryGetAsync("conversation-1", Token)); + [Fact] + public async Task ReadingASessionPutsItsIdleClockBackToZero() + { + FakeTimeProvider clock = Clock(); + InMemoryConversationSessions sessions = new(Factory(), TimeSpan.FromMinutes(30), clock); + _ = await sessions.OpenAsync("conversation-1", Token); - // Forty minutes since it was opened, twenty since it was last read. A conversation still being had - // must not be dropped out from under the caller. - clock.Advance(TimeSpan.FromMinutes(20)); - await sessions.SweepAsync(Token); + clock.Advance(TimeSpan.FromMinutes(20)); + Assert.NotNull(await sessions.TryGetAsync("conversation-1", Token)); - Assert.NotNull(await sessions.TryGetAsync("conversation-1", Token)); - } + // Forty minutes since it was opened, twenty since it was last read. A conversation still being had + // must not be dropped out from under the caller. + clock.Advance(TimeSpan.FromMinutes(20)); + await sessions.SweepAsync(Token); - [Fact] - public async Task AnExpiringSessionStillHandsOverTheWordsItOwed() - { - // The reason expiry goes through CloseAsync. An evictor that dropped the entry on its own - // would return with the write still in flight, and nothing left able to wait for it. - ParkingConversationStore transcript = new(); - var clock = Clock(); - InMemoryConversationSessions sessions = new(Factory(transcript), TimeSpan.FromMinutes(30), clock); - var session = await sessions.OpenAsync("conversation-1", Token); - - var turn = session.RunTurnAsync("hello", Token); - await transcript.Parked; - clock.Advance(TimeSpan.FromMinutes(31)); - - var sweeping = sessions.SweepAsync(Token).AsTask(); - var returnedEarly = await Task.WhenAny(sweeping, Task.Delay(200, Token)) == sweeping; - Assert.False(returnedEarly); - - transcript.Release(); - await sweeping; - - Assert.True(transcript.Landed); - Assert.Equal(0, sessions.Count); - await turn; - } + Assert.NotNull(await sessions.TryGetAsync("conversation-1", Token)); + } - [Fact] - public async Task AnExpiringSessionWritesTheLastEventOfItsChain() - { - // §11 item 6 makes conversation.ended the last event of every conversation. A caller who simply stops - // replying closes no socket and reaches no terminal stage, so expiry is the only thing left - // that can write it, and a chain with no end is a permanent gap in the record of D23. - RecordingConversationObserver observer = new(); - var clock = Clock(); - InMemoryConversationSessions sessions = new( - Factory(observer: observer), TimeSpan.FromMinutes(30), clock); - await sessions.OpenAsync("conversation-1", Token); - - clock.Advance(TimeSpan.FromMinutes(31)); - await sessions.SweepAsync(Token); - - Assert.Contains(observer.Kinds, kind => kind == ConversationEventKind.ConversationEnded); - } + [Fact] + public async Task AnExpiringSessionStillHandsOverTheWordsItOwed() + { + // The reason expiry goes through CloseAsync. An evictor that dropped the entry on its own + // would return with the write still in flight, and nothing left able to wait for it. + ParkingConversationStore transcript = new(); + FakeTimeProvider clock = Clock(); + InMemoryConversationSessions sessions = new(Factory(transcript), TimeSpan.FromMinutes(30), clock); + ConversationSession session = await sessions.OpenAsync("conversation-1", Token); + + Task turn = session.RunTurnAsync("hello", Token); + await transcript.Parked; + clock.Advance(TimeSpan.FromMinutes(31)); + + Task sweeping = sessions.SweepAsync(Token).AsTask(); + bool returnedEarly = await Task.WhenAny(sweeping, Task.Delay(200, Token)) == sweeping; + Assert.False(returnedEarly); + + transcript.Release(); + await sweeping; + + Assert.True(transcript.Landed); + Assert.Equal(0, sessions.Count); + _ = await turn; + } + [Fact] + public async Task AnExpiringSessionWritesTheLastEventOfItsChain() + { + // §11 item 6 makes conversation.ended the last event of every conversation. A caller who simply stops + // replying closes no socket and reaches no terminal stage, so expiry is the only thing left + // that can write it, and a chain with no end is a permanent gap in the record of D23. + RecordingConversationObserver observer = new(); + FakeTimeProvider clock = Clock(); + InMemoryConversationSessions sessions = new( + Factory(observer: observer), TimeSpan.FromMinutes(30), clock); + _ = await sessions.OpenAsync("conversation-1", Token); + + clock.Advance(TimeSpan.FromMinutes(31)); + await sessions.SweepAsync(Token); + + Assert.Contains(observer.Kinds, kind => kind == ConversationEventKind.ConversationEnded); + } - private static FakeTimeProvider Clock() - => new(new DateTimeOffset(2026, 8, 20, 12, 0, 0, TimeSpan.Zero)); - private const string Document = """ + private static FakeTimeProvider Clock() + { + return new(new DateTimeOffset(2026, 8, 20, 12, 0, 0, TimeSpan.Zero)); + } + + private const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -144,68 +147,76 @@ private static FakeTimeProvider Clock() agent: only """; - private static ConversationSessionFactory Factory( - IConversationStore? transcript = null, - string? yaml = null, - IChatClient? reply = null, - IConversationObserver? observer = null) - { - var document = ConfigurationLoader.LoadYaml(yaml ?? Document); - RoutingChatClientFactory chatClients = new(reply ?? new StubChatClient()); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { ConversationStore = transcript })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients), - observers: observer is null ? null : [observer]); - } + private static ConversationSessionFactory Factory( + IConversationStore? transcript = null, + string? yaml = null, + IChatClient? reply = null, + IConversationObserver? observer = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml ?? Document); + RoutingChatClientFactory chatClients = new(reply ?? new StubChatClient()); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { ConversationStore = transcript })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients), + observers: observer is null ? null : [observer]); + } - private sealed class StubChatClient : IChatClient - { - public Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken ct = default) - => Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "hello"))); + private sealed class StubChatClient : IChatClient + { + public Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken ct = default) + { + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "hello"))); + } - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken ct = default) - => throw new NotSupportedException(); + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken ct = default) + { + throw new NotSupportedException(); + } - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - public void Dispose() - { + public void Dispose() + { + } } - } - - /// Records the kind of every event one conversation raised. - private sealed class RecordingConversationObserver : IConversationObserver - { - private readonly List _kinds = []; - public IReadOnlyList Kinds + /// Records the kind of every event one conversation raised. + private sealed class RecordingConversationObserver : IConversationObserver { - get + private readonly List _kinds = []; + + public IReadOnlyList Kinds { - lock (_kinds) + get { - return [.. _kinds]; + lock (_kinds) + { + return [.. _kinds]; + } } } - } - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken = default) - { - lock (_kinds) + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken = default) { - _kinds.Add(conversationEvent.Kind); - } + lock (_kinds) + { + _kinds.Add(conversationEvent.Kind); + } - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } - } - /// The default store, counting the reads that keep a conversation out of the idle sweep. + /// The default store, counting the reads that keep a conversation out of the idle sweep. + } } diff --git a/tests/AgentCore.Application.Tests/Skills/PinnedSkillsProviderTests.cs b/tests/AgentCore.Application.Tests/Skills/PinnedSkillsProviderTests.cs index 61325498..3266291a 100644 --- a/tests/AgentCore.Application.Tests/Skills/PinnedSkillsProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Skills/PinnedSkillsProviderTests.cs @@ -4,86 +4,87 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Skills; - -/// -/// A pinned skill's body must reach the prompt on every turn without a tool call, with the -/// discovery frontmatter stripped, and in the order the agent listed it. -/// -public sealed class PinnedSkillsProviderTests +namespace AgentCore.Application.Tests.Skills { - [Fact] - public async Task Invoke_PutsTheBodyInTheInstructionsAndRegistersNoTool() - { - var result = await InvokeAsync(["warranty-returns"]); - - Assert.Equal("\nDo the thing.\n", result.Instructions); - Assert.Null(result.Tools); - } - - [Fact] - public async Task Invoke_StripsTheFrontmatter() - { - var result = await InvokeAsync(["warranty-returns"]); - - Assert.DoesNotContain("---", result.Instructions, StringComparison.Ordinal); - Assert.DoesNotContain("description:", result.Instructions, StringComparison.Ordinal); - } - - [Fact] - public async Task Invoke_TwoSkills_KeepsTheListedOrder() - { - var result = await InvokeAsync(["shipping-claims", "warranty-returns"]); - - var shipping = result.Instructions!.IndexOf("name=\"shipping-claims\"", StringComparison.Ordinal); - var warranty = result.Instructions.IndexOf("name=\"warranty-returns\"", StringComparison.Ordinal); - Assert.True(shipping >= 0 && warranty > shipping); - } - - [Fact] - public async Task Invoke_AppendsBelowTheInstructionsAlreadyThere() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - using AgentFileSkillsSource source = new(folder.Root); - SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); - PinnedSkillsProvider provider = new(catalog, ["warranty-returns"]); - - var result = await InvokeAsync(provider, new AIContext { Instructions = "You are support." }); - - Assert.StartsWith("You are support.", result.Instructions, StringComparison.Ordinal); - Assert.EndsWith("Do the thing.\n", result.Instructions, StringComparison.Ordinal); - } - - [Fact] - public void Constructor_NoNames_Throws() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - using AgentFileSkillsSource source = new(folder.Root); - SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); - - Assert.Throws(() => new PinnedSkillsProvider(catalog, [])); - } - - private static async Task InvokeAsync(IReadOnlyList pinned) - { - using var folder = SkillFolder.Create() - .WithSkill("warranty-returns") - .WithSkill("shipping-claims"); - - using AgentFileSkillsSource source = new(folder.Root); - SkillCatalog catalog = new(source, new HashSet(["warranty-returns", "shipping-claims"], StringComparer.Ordinal)); - - return await InvokeAsync(new PinnedSkillsProvider(catalog, pinned), new AIContext()); - } - - private static async Task InvokeAsync(AIContextProvider provider, AIContext existing) + /// + /// A pinned skill's body must reach the prompt on every turn without a tool call, with the + /// discovery frontmatter stripped, and in the order the agent listed it. + /// + public sealed class PinnedSkillsProviderTests { - using SequencedChatClient client = new("hello there."); - ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); + [Fact] + public async Task Invoke_PutsTheBodyInTheInstructionsAndRegistersNoTool() + { + AIContext result = await InvokeAsync(["warranty-returns"]); + + Assert.Equal("\nDo the thing.\n", result.Instructions); + Assert.Null(result.Tools); + } + + [Fact] + public async Task Invoke_StripsTheFrontmatter() + { + AIContext result = await InvokeAsync(["warranty-returns"]); + + Assert.DoesNotContain("---", result.Instructions, StringComparison.Ordinal); + Assert.DoesNotContain("description:", result.Instructions, StringComparison.Ordinal); + } + + [Fact] + public async Task Invoke_TwoSkills_KeepsTheListedOrder() + { + AIContext result = await InvokeAsync(["shipping-claims", "warranty-returns"]); + + int shipping = result.Instructions!.IndexOf("name=\"shipping-claims\"", StringComparison.Ordinal); + int warranty = result.Instructions.IndexOf("name=\"warranty-returns\"", StringComparison.Ordinal); + Assert.True(shipping >= 0 && warranty > shipping); + } + + [Fact] + public async Task Invoke_AppendsBelowTheInstructionsAlreadyThere() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + using AgentFileSkillsSource source = new(folder.Root); + SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); + PinnedSkillsProvider provider = new(catalog, ["warranty-returns"]); + + AIContext result = await InvokeAsync(provider, new AIContext { Instructions = "You are support." }); + + Assert.StartsWith("You are support.", result.Instructions, StringComparison.Ordinal); + Assert.EndsWith("Do the thing.\n", result.Instructions, StringComparison.Ordinal); + } + + [Fact] + public void Constructor_NoNames_Throws() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + using AgentFileSkillsSource source = new(folder.Root); + SkillCatalog catalog = new(source, new HashSet(["warranty-returns"], StringComparer.Ordinal)); + + _ = Assert.Throws(() => new PinnedSkillsProvider(catalog, [])); + } + + private static async Task InvokeAsync(IReadOnlyList pinned) + { + using SkillFolder folder = SkillFolder.Create() + .WithSkill("warranty-returns") + .WithSkill("shipping-claims"); + + using AgentFileSkillsSource source = new(folder.Root); + SkillCatalog catalog = new(source, new HashSet(["warranty-returns", "shipping-claims"], StringComparer.Ordinal)); + + return await InvokeAsync(new PinnedSkillsProvider(catalog, pinned), new AIContext()); + } + + private static async Task InvokeAsync(AIContextProvider provider, AIContext existing) + { + using SequencedChatClient client = new("hello there."); + ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(agent, null, existing); + AIContextProvider.InvokingContext context = new(agent, null, existing); #pragma warning restore MAAI001 - return await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + return await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + } } } diff --git a/tests/AgentCore.Application.Tests/Skills/ReadOnlySkillsProviderTests.cs b/tests/AgentCore.Application.Tests/Skills/ReadOnlySkillsProviderTests.cs index 5fc9eeae..0dc384fc 100644 --- a/tests/AgentCore.Application.Tests/Skills/ReadOnlySkillsProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Skills/ReadOnlySkillsProviderTests.cs @@ -5,68 +5,69 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Skills; - -/// -/// The wrapper exists for one reason: MAF registers run_skill_script even when no skill has a -/// script, and this host runs none. It must remove that tool without disturbing anything the -/// caller already put in the context — overriding the wrong method silently doubles it. -/// -public sealed class ReadOnlySkillsProviderTests +namespace AgentCore.Application.Tests.Skills { - [Fact] - public async Task InvokingAsync_RemovesTheScriptToolAndLeavesTheCallersContextIntact() + /// + /// The wrapper exists for one reason: MAF registers run_skill_script even when no skill has a + /// script, and this host runs none. It must remove that tool without disturbing anything the + /// caller already put in the context — overriding the wrong method silently doubles it. + /// + public sealed class ReadOnlySkillsProviderTests { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - using AgentFileSkillsSource source = new(folder.Root); - using AgentSkillsProvider inner = new( - source, - new AgentSkillsProviderOptions - { - DisableLoadSkillApproval = true, - DisableReadSkillResourceApproval = true, - }, - loggerFactory: null, - ownsSource: false); + [Fact] + public async Task InvokingAsync_RemovesTheScriptToolAndLeavesTheCallersContextIntact() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + using AgentFileSkillsSource source = new(folder.Root); + using AgentSkillsProvider inner = new( + source, + new AgentSkillsProviderOptions + { + DisableLoadSkillApproval = true, + DisableReadSkillResourceApproval = true, + }, + loggerFactory: null, + ownsSource: false); - using ReadOnlySkillsProvider provider = new(inner); + using ReadOnlySkillsProvider provider = new(inner); - using SequencedChatClient client = new("hello there."); - ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); - AIFunction callerTool = AIFunctionFactory.Create(() => "x", name: "caller_tool", description: "A tool the agent already had."); - AIContext seed = new() { Tools = [callerTool], Instructions = "CALLER." }; + using SequencedChatClient client = new("hello there."); + ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); + AIFunction callerTool = AIFunctionFactory.Create(() => "x", name: "caller_tool", description: "A tool the agent already had."); + AIContext seed = new() { Tools = [callerTool], Instructions = "CALLER." }; #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(agent, null, seed); + AIContextProvider.InvokingContext context = new(agent, null, seed); #pragma warning restore MAAI001 - var result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + AIContext result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - Assert.NotNull(result.Tools); - Assert.Equal( - ["caller_tool", "load_skill", "read_skill_resource"], - result.Tools.Select(tool => tool.Name)); + Assert.NotNull(result.Tools); + Assert.Equal( + ["caller_tool", "load_skill", "read_skill_resource"], + result.Tools.Select(tool => tool.Name)); - // Exactly once. Overriding ProvideAIContextAsync instead merges the caller's context twice. - Assert.Equal(1, result.Instructions!.Split("CALLER.").Length - 1); - } + // Exactly once. Overriding ProvideAIContextAsync instead merges the caller's context twice. + Assert.Equal(1, result.Instructions!.Split("CALLER.").Length - 1); + } - [Fact] - public async Task InvokingAsync_WhenTheFilterMatchesNothing_ReturnsNoToolsAndDoesNotThrow() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - using AgentFileSkillsSource source = new(folder.Root); - using FilteringAgentSkillsSource filtered = new(source, (_, _) => false); - using AgentSkillsProvider inner = new(filtered, options: null, loggerFactory: null, ownsSource: false); - using ReadOnlySkillsProvider provider = new(inner); + [Fact] + public async Task InvokingAsync_WhenTheFilterMatchesNothing_ReturnsNoToolsAndDoesNotThrow() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + using AgentFileSkillsSource source = new(folder.Root); + using FilteringAgentSkillsSource filtered = new(source, (_, _) => false); + using AgentSkillsProvider inner = new(filtered, options: null, loggerFactory: null, ownsSource: false); + using ReadOnlySkillsProvider provider = new(inner); - using SequencedChatClient client = new("hello there."); - ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); + using SequencedChatClient client = new("hello there."); + ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(agent, null, new AIContext()); + AIContextProvider.InvokingContext context = new(agent, null, new AIContext()); #pragma warning restore MAAI001 - var result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + AIContext result = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - Assert.Null(result.Tools); + Assert.Null(result.Tools); + } } } diff --git a/tests/AgentCore.Application.Tests/Skills/SkillCatalogTests.cs b/tests/AgentCore.Application.Tests/Skills/SkillCatalogTests.cs index d8b82cde..5d15d4f9 100644 --- a/tests/AgentCore.Application.Tests/Skills/SkillCatalogTests.cs +++ b/tests/AgentCore.Application.Tests/Skills/SkillCatalogTests.cs @@ -2,36 +2,39 @@ using Microsoft.Agents.AI; using Xunit; -namespace AgentCore.Application.Tests.Skills; - -/// -/// The catalog is the only thing the compiler sees of a skills folder, so it must refuse to exist -/// half-built: a source with no names, or names with no source, would fail later and further away. -/// -public sealed class SkillCatalogTests +namespace AgentCore.Application.Tests.Skills { - [Fact] - public void Constructor_CarriesTheSourceAndTheNames() + /// + /// The catalog is the only thing the compiler sees of a skills folder, so it must refuse to exist + /// half-built: a source with no names, or names with no source, would fail later and further away. + /// + public sealed class SkillCatalogTests { - using AgentFileSkillsSource source = new(Path.Combine(Path.GetTempPath(), "agentcore-empty-skills")); - HashSet names = new(["warranty-returns"], StringComparer.Ordinal); + [Fact] + public void Constructor_CarriesTheSourceAndTheNames() + { + using AgentFileSkillsSource source = new(Path.Combine(Path.GetTempPath(), "agentcore-empty-skills")); + HashSet names = new(["warranty-returns"], StringComparer.Ordinal); - SkillCatalog catalog = new(source, names); + SkillCatalog catalog = new(source, names); - Assert.Same(source, catalog.Source); - Assert.Contains("warranty-returns", catalog.Names); - } + Assert.Same(source, catalog.Source); + Assert.Contains("warranty-returns", catalog.Names); + } - [Fact] - public void Constructor_ANullSource_Throws() - => Assert.Throws( - () => new SkillCatalog(null!, new HashSet(StringComparer.Ordinal))); + [Fact] + public void Constructor_ANullSource_Throws() + { + _ = Assert.Throws( + () => new SkillCatalog(null!, new HashSet(StringComparer.Ordinal))); + } - [Fact] - public void Constructor_NullNames_Throws() - { - using AgentFileSkillsSource source = new(Path.Combine(Path.GetTempPath(), "agentcore-empty-skills")); + [Fact] + public void Constructor_NullNames_Throws() + { + using AgentFileSkillsSource source = new(Path.Combine(Path.GetTempPath(), "agentcore-empty-skills")); - Assert.Throws(() => new SkillCatalog(source, null!)); + _ = Assert.Throws(() => new SkillCatalog(source, null!)); + } } } diff --git a/tests/AgentCore.Application.Tests/Skills/SkillsProviderFactoryTests.cs b/tests/AgentCore.Application.Tests/Skills/SkillsProviderFactoryTests.cs index 4ae2dcfd..0039b50e 100644 --- a/tests/AgentCore.Application.Tests/Skills/SkillsProviderFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Skills/SkillsProviderFactoryTests.cs @@ -5,90 +5,91 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Skills; - -/// -/// One agent must see its own skills and no others, must never be asked to approve a tool call -/// mid-conversation, and must never be told a script tool exists. -/// -public sealed class SkillsProviderFactoryTests +namespace AgentCore.Application.Tests.Skills { - [Fact] - public async Task Create_AdvertisesOnlyTheSkillsTheAgentListed() + /// + /// One agent must see its own skills and no others, must never be asked to approve a tool call + /// mid-conversation, and must never be told a script tool exists. + /// + public sealed class SkillsProviderFactoryTests { - var result = await InvokeAsync(["warranty-returns"]); + [Fact] + public async Task Create_AdvertisesOnlyTheSkillsTheAgentListed() + { + AIContext result = await InvokeAsync(["warranty-returns"]); - Assert.Contains("warranty-returns", result.Instructions, StringComparison.Ordinal); - Assert.DoesNotContain("shipping-claims", result.Instructions, StringComparison.Ordinal); - } + Assert.Contains("warranty-returns", result.Instructions, StringComparison.Ordinal); + Assert.DoesNotContain("shipping-claims", result.Instructions, StringComparison.Ordinal); + } - [Fact] - public async Task Create_RegistersTheTwoReadToolsAndNoScriptTool() - { - var result = await InvokeAsync(["warranty-returns"]); + [Fact] + public async Task Create_RegistersTheTwoReadToolsAndNoScriptTool() + { + AIContext result = await InvokeAsync(["warranty-returns"]); - Assert.NotNull(result.Tools); - Assert.Equal(["load_skill", "read_skill_resource"], result.Tools.Select(tool => tool.Name)); - } + Assert.NotNull(result.Tools); + Assert.Equal(["load_skill", "read_skill_resource"], result.Tools.Select(tool => tool.Name)); + } - [Fact] - public async Task Create_TheReadToolsDoNotRequireApproval() - { - var result = await InvokeAsync(["warranty-returns"]); + [Fact] + public async Task Create_TheReadToolsDoNotRequireApproval() + { + AIContext result = await InvokeAsync(["warranty-returns"]); - Assert.DoesNotContain(result.Tools!, tool => tool is ApprovalRequiredAIFunction); - } + Assert.DoesNotContain(result.Tools!, tool => tool is ApprovalRequiredAIFunction); + } - [Fact] - public async Task Create_ThePromptNeverNamesTheScriptTool() - { - var result = await InvokeAsync(["warranty-returns"]); + [Fact] + public async Task Create_ThePromptNeverNamesTheScriptTool() + { + AIContext result = await InvokeAsync(["warranty-returns"]); - Assert.DoesNotContain("run_skill_script", result.Instructions, StringComparison.Ordinal); - } + Assert.DoesNotContain("run_skill_script", result.Instructions, StringComparison.Ordinal); + } - [Fact] - public async Task Create_TwoAgentsOverOneSource_BothKeepWorkingAfterOneIsDisposed() - { - using var folder = SkillFolder.Create() - .WithSkill("warranty-returns") - .WithSkill("shipping-claims"); + [Fact] + public async Task Create_TwoAgentsOverOneSource_BothKeepWorkingAfterOneIsDisposed() + { + using SkillFolder folder = SkillFolder.Create() + .WithSkill("warranty-returns") + .WithSkill("shipping-claims"); - using AgentFileSkillsSource source = new(folder.Root); - using CachingAgentSkillsSource shared = new(source); - SkillCatalog catalog = new(shared, new HashSet(["warranty-returns", "shipping-claims"], StringComparer.Ordinal)); + using AgentFileSkillsSource source = new(folder.Root); + using CachingAgentSkillsSource shared = new(source); + SkillCatalog catalog = new(shared, new HashSet(["warranty-returns", "shipping-claims"], StringComparer.Ordinal)); - var first = SkillsProviderFactory.Create(catalog, ["warranty-returns"], loggers: null); - var second = SkillsProviderFactory.Create(catalog, ["shipping-claims"], loggers: null); + AIContextProvider first = SkillsProviderFactory.Create(catalog, ["warranty-returns"], loggers: null); + AIContextProvider second = SkillsProviderFactory.Create(catalog, ["shipping-claims"], loggers: null); - (first as IDisposable)?.Dispose(); + (first as IDisposable)?.Dispose(); - var result = await InvokeAsync(second); + AIContext result = await InvokeAsync(second); - Assert.Contains("shipping-claims", result.Instructions, StringComparison.Ordinal); - } + Assert.Contains("shipping-claims", result.Instructions, StringComparison.Ordinal); + } - private static async Task InvokeAsync(IReadOnlyList allowed) - { - using var folder = SkillFolder.Create() - .WithSkill("warranty-returns") - .WithSkill("shipping-claims"); + private static async Task InvokeAsync(IReadOnlyList allowed) + { + using SkillFolder folder = SkillFolder.Create() + .WithSkill("warranty-returns") + .WithSkill("shipping-claims"); - using AgentFileSkillsSource source = new(folder.Root); - using CachingAgentSkillsSource shared = new(source); - SkillCatalog catalog = new(shared, new HashSet(["warranty-returns", "shipping-claims"], StringComparer.Ordinal)); + using AgentFileSkillsSource source = new(folder.Root); + using CachingAgentSkillsSource shared = new(source); + SkillCatalog catalog = new(shared, new HashSet(["warranty-returns", "shipping-claims"], StringComparer.Ordinal)); - return await InvokeAsync(SkillsProviderFactory.Create(catalog, allowed, loggers: null)); - } + return await InvokeAsync(SkillsProviderFactory.Create(catalog, allowed, loggers: null)); + } - private static async Task InvokeAsync(AIContextProvider provider) - { - using SequencedChatClient client = new("hello there."); - ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); + private static async Task InvokeAsync(AIContextProvider provider) + { + using SequencedChatClient client = new("hello there."); + ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "support" }); #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new(agent, null, new AIContext()); + AIContextProvider.InvokingContext context = new(agent, null, new AIContext()); #pragma warning restore MAAI001 - return await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + return await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + } } } diff --git a/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs b/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs index 65ba5e67..a6b76f0b 100644 --- a/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs +++ b/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs @@ -4,15 +4,15 @@ using AgentCore.Application.State; using Xunit; -namespace AgentCore.Application.Tests.State; - -/// -/// : the durable-blob view of a conversation's declared state. -/// -public sealed class StateDocumentTests +namespace AgentCore.Application.Tests.State { - private const string Yaml = - """ + /// + /// : the durable-blob view of a conversation's declared state. + /// + public sealed class StateDocumentTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 state: model: { type: string, writer: tool, from: lookup.model } @@ -27,18 +27,18 @@ public sealed class StateDocumentTests agent: only """; - private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); + private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); - /// How many slots the concurrency test fills. Enough to keep the reader busy while it does. - private const int SlotCount = 200; + /// How many slots the concurrency test fills. Enough to keep the reader busy while it does. + private const int SlotCount = 200; - /// A document of declared slots, written out rather than held as a literal. - private static string ManySlotsYaml => - $$""" + /// A document of declared slots, written out rather than held as a literal. + private static string ManySlotsYaml => + $$""" apiVersion: agentcore/v1 state: {{string.Join('\n', Enumerable.Range(0, SlotCount) - .Select(slot => $" {SlotName(slot)}: {{ type: integer, writer: tool, from: lookup.{SlotName(slot)} }}"))}} + .Select(slot => $" {SlotName(slot)}: {{ type: integer, writer: tool, from: lookup.{SlotName(slot)} }}"))}} tools: - { id: lookup, kind: builtin, uses: orders.read } agents: @@ -49,128 +49,136 @@ public sealed class StateDocumentTests agent: only """; - private static AgentCoreConfiguration WithEnumSlot() => new() - { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - State = new Dictionary(StringComparer.Ordinal) + private static AgentCoreConfiguration WithEnumSlot() { - ["applies_to"] = new() + return new() { - Type = StateSlotType.String, - Writer = StateWriter.Extractor, - EnumValues = [JsonValue.Create("f63")!, JsonValue.Create("f65")!], - }, - }, - }; - - [Fact] - public void TryWrite_ValueOutsideTheEnum_IsRefused() - { - var state = new StateDocument(WithEnumSlot()); + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + State = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [JsonValue.Create("f63")!, JsonValue.Create("f65")!], + }, + }, + }; + } - Assert.False(state.TryWrite("applies_to", JsonValue.Create("F63 Treadmill"))); - Assert.True(state.IsUnfilled("applies_to")); - } + [Fact] + public void TryWrite_ValueOutsideTheEnum_IsRefused() + { + StateDocument state = new(WithEnumSlot()); - [Fact] - public void TryWrite_ValueOutsideTheEnum_KeepsThePreviousValue() - { - var state = new StateDocument(WithEnumSlot()); - Assert.True(state.TryWrite("applies_to", JsonValue.Create("f63"))); + Assert.False(state.TryWrite("applies_to", JsonValue.Create("F63 Treadmill"))); + Assert.True(state.IsUnfilled("applies_to")); + } - Assert.False(state.TryWrite("applies_to", JsonValue.Create("f80"))); - Assert.Equal("f63", state.Read("applies_to")?.GetValue()); - } + [Fact] + public void TryWrite_ValueOutsideTheEnum_KeepsThePreviousValue() + { + StateDocument state = new(WithEnumSlot()); + Assert.True(state.TryWrite("applies_to", JsonValue.Create("f63"))); - [Fact] - public void TryWrite_ValueInsideTheEnum_IsAccepted() - { - var state = new StateDocument(WithEnumSlot()); + Assert.False(state.TryWrite("applies_to", JsonValue.Create("f80"))); + Assert.Equal("f63", state.Read("applies_to")?.GetValue()); + } - Assert.True(state.TryWrite("applies_to", JsonValue.Create("f65"))); - Assert.Equal("f65", state.Read("applies_to")?.GetValue()); - } + [Fact] + public void TryWrite_ValueInsideTheEnum_IsAccepted() + { + StateDocument state = new(WithEnumSlot()); - [Fact] - public void WrittenSlots_HandsOutAFreshCopyEveryConversation() - { - StateDocument state = new(Document); - var result = JsonNode.Parse("""{ "model": "F63" }"""); - Assert.Equal(1, ToolStateWriter.Apply(state, "lookup", result)); - - var first = state.WrittenSlots(); - var second = state.WrittenSlots(); - - // The declared state schema only ever writes scalars (section 8.3's four writers coerce - // to boolean/integer/number/string), so a scalar JsonValue is the only value shape this - // slot can hold today, and a scalar exposes no public mutator. The clone's contract is - // still checked the way a caller could actually break it without one: two conversations must not - // hand back the same node instance, because a caller free to reparent or wrap one conversation's - // node (e.g. into a JsonObject of its own) would otherwise reach into the live document, - // or into the copy a different caller was given. - Assert.NotSame(first["model"], second["model"]); - Assert.Equal("F63", second["model"]!.GetValue()); - } + Assert.True(state.TryWrite("applies_to", JsonValue.Create("f65"))); + Assert.Equal("f65", state.Read("applies_to")?.GetValue()); + } - [Fact] - public void WrittenSlots_OmitsASlotNoWriterHasFilled() - { - StateDocument state = new(Document); - var result = JsonNode.Parse("""{ "model": "F63" }"""); - Assert.Equal(1, ToolStateWriter.Apply(state, "lookup", result)); - - var written = state.WrittenSlots(); - - // "serial" is declared but no writer touched it. Absent, not present-with-its-default, - // is the distinction IsUnfilled exists to preserve; Snapshot() (which fills every - // declared slot with its default) would destroy it. - Assert.True(written.ContainsKey("model")); - Assert.False(written.ContainsKey("serial")); - Assert.True(state.IsUnfilled("serial")); - } + [Fact] + public void WrittenSlots_HandsOutAFreshCopyEveryConversation() + { + StateDocument state = new(Document); + JsonNode? result = JsonNode.Parse("""{ "model": "F63" }"""); + Assert.Equal(1, ToolStateWriter.Apply(state, "lookup", result)); + + IReadOnlyDictionary first = state.WrittenSlots(); + IReadOnlyDictionary second = state.WrittenSlots(); + + // The declared state schema only ever writes scalars (section 8.3's four writers coerce + // to boolean/integer/number/string), so a scalar JsonValue is the only value shape this + // slot can hold today, and a scalar exposes no public mutator. The clone's contract is + // still checked the way a caller could actually break it without one: two conversations must not + // hand back the same node instance, because a caller free to reparent or wrap one conversation's + // node (e.g. into a JsonObject of its own) would otherwise reach into the live document, + // or into the copy a different caller was given. + Assert.NotSame(first["model"], second["model"]); + Assert.Equal("F63", second["model"]!.GetValue()); + } - [Fact] - public async Task WrittenSlots_ReadWhileTheTurnLoopIsStillWriting_AnswersInsteadOfThrowing() - { - // The turn loop is this document's only WRITER, but it is not its only toucher. - // ConversationSession.Snapshot reads it off the turn, and AgentCoreAgent.SerializeSessionCoreAsync is - // a framework seam any host thread may conversation while a turn is running — an exposure this branch - // created, because that seam used to throw NotSupportedException instead of answering. - // Enumerating a plain Dictionary mid-write is an InvalidOperationException, and it would - // surface out of the framework's own serialization API. - var document = ConfigurationLoader.LoadYaml(ManySlotsYaml); - - for (var round = 0; round < 60; round++) + [Fact] + public void WrittenSlots_OmitsASlotNoWriterHasFilled() { - StateDocument state = new(document); - using ManualResetEventSlim reading = new(); - using CancellationTokenSource written = new(); + StateDocument state = new(Document); + JsonNode? result = JsonNode.Parse("""{ "model": "F63" }"""); + Assert.Equal(1, ToolStateWriter.Apply(state, "lookup", result)); + + IReadOnlyDictionary written = state.WrittenSlots(); + + // "serial" is declared but no writer touched it. Absent, not present-with-its-default, + // is the distinction IsUnfilled exists to preserve; Snapshot() (which fills every + // declared slot with its default) would destroy it. + Assert.True(written.ContainsKey("model")); + Assert.False(written.ContainsKey("serial")); + Assert.True(state.IsUnfilled("serial")); + } - var reader = Task.Run( - () => - { - reading.Set(); - while (!written.IsCancellationRequested) - { - // A torn read is fine and is the accepted price: the snapshot is best effort - // by D5, and the next turn's write corrects it. A throw is not fine. - _ = state.WrittenSlots(); - } - }, - TestContext.Current.CancellationToken); + [Fact] + public async Task WrittenSlots_ReadWhileTheTurnLoopIsStillWriting_AnswersInsteadOfThrowing() + { + // The turn loop is this document's only WRITER, but it is not its only toucher. + // ConversationSession.Snapshot reads it off the turn, and AgentCoreAgent.SerializeSessionCoreAsync is + // a framework seam any host thread may conversation while a turn is running — an exposure this branch + // created, because that seam used to throw NotSupportedException instead of answering. + // Enumerating a plain Dictionary mid-write is an InvalidOperationException, and it would + // surface out of the framework's own serialization API. + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ManySlotsYaml); + + for (int round = 0; round < 60; round++) + { + StateDocument state = new(document); + using ManualResetEventSlim reading = new(); + using CancellationTokenSource written = new(); - reading.Wait(TestContext.Current.CancellationToken); + Task reader = Task.Run( + () => + { + reading.Set(); + while (!written.IsCancellationRequested) + { + // A torn read is fine and is the accepted price: the snapshot is best effort + // by D5, and the next turn's write corrects it. A throw is not fine. + _ = state.WrittenSlots(); + } + }, + TestContext.Current.CancellationToken); + + reading.Wait(TestContext.Current.CancellationToken); + + for (int slot = 0; slot < SlotCount; slot++) + { + Assert.True(state.TryWrite(SlotName(slot), JsonValue.Create((long)slot))); + } - for (var slot = 0; slot < SlotCount; slot++) - { - Assert.True(state.TryWrite(SlotName(slot), JsonValue.Create((long)slot))); + await written.CancelAsync(); + await reader; } + } - await written.CancelAsync(); - await reader; + private static string SlotName(int index) + { + return $"s{index}"; } } - - private static string SlotName(int index) => $"s{index}"; } diff --git a/tests/AgentCore.Application.Tests/State/StateExtractorTests.cs b/tests/AgentCore.Application.Tests/State/StateExtractorTests.cs index 146dbf9c..51e74472 100644 --- a/tests/AgentCore.Application.Tests/State/StateExtractorTests.cs +++ b/tests/AgentCore.Application.Tests/State/StateExtractorTests.cs @@ -7,15 +7,15 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.State; - -/// -/// The extractor of section 8.3. Every slot is nullable on the wire, and that is not optional. -/// -public sealed class StateExtractorTests +namespace AgentCore.Application.Tests.State { - private const string Yaml = - """ + /// + /// The extractor of section 8.3. Every slot is nullable on the wire, and that is not optional. + /// + public sealed class StateExtractorTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 state: callerAskedForHuman: { type: boolean, default: false, writer: extractor } @@ -33,185 +33,185 @@ public sealed class StateExtractorTests agent: only """; - private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); + private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); - [Fact] - public void TheSchema_HoldsOnlyTheExtractorSlots() - { - var schema = StateExtractor.BuildSchema(Document); - - var properties = schema.GetProperty("properties"); - Assert.Equal(3, properties.EnumerateObject().Count()); - Assert.False(properties.TryGetProperty("failedResolveTurns", out _)); - } + [Fact] + public void TheSchema_HoldsOnlyTheExtractorSlots() + { + JsonElement schema = StateExtractor.BuildSchema(Document); - [Fact] - public void TheSchema_MakesEverySlotNullableAndRequired() - { - var schema = StateExtractor.BuildSchema(Document); + JsonElement properties = schema.GetProperty("properties"); + Assert.Equal(3, properties.EnumerateObject().Count()); + Assert.False(properties.TryGetProperty("failedResolveTurns", out _)); + } - foreach (var property in schema.GetProperty("properties").EnumerateObject()) + [Fact] + public void TheSchema_MakesEverySlotNullableAndRequired() { - var types = property.Value.GetProperty("type").EnumerateArray().Select(item => item.GetString()).ToList(); + JsonElement schema = StateExtractor.BuildSchema(Document); - // A missing field defaults silently, so every slot is nullable and every slot is required. - Assert.Contains("null", types); - Assert.Equal(2, types.Count); - } + foreach (JsonProperty property in schema.GetProperty("properties").EnumerateObject()) + { + List types = [.. property.Value.GetProperty("type").EnumerateArray().Select(item => item.GetString())]; - var required = schema.GetProperty("required").EnumerateArray().Select(item => item.GetString()).ToList(); - Assert.Equal(3, required.Count); - Assert.False(schema.GetProperty("additionalProperties").GetBoolean()); - } + // A missing field defaults silently, so every slot is nullable and every slot is required. + Assert.Contains("null", types); + Assert.Equal(2, types.Count); + } - [Fact] - public void TheSchema_CarriesTheSlotDescription() - { - var schema = StateExtractor.BuildSchema(Document); + List required = [.. schema.GetProperty("required").EnumerateArray().Select(item => item.GetString())]; + Assert.Equal(3, required.Count); + Assert.False(schema.GetProperty("additionalProperties").GetBoolean()); + } - Assert.Equal( - "the machine model", - schema.GetProperty("properties").GetProperty("machineModel").GetProperty("description").GetString()); - } + [Fact] + public void TheSchema_CarriesTheSlotDescription() + { + JsonElement schema = StateExtractor.BuildSchema(Document); - [Fact] - public void ANullField_LeavesThePreviousValue() - { - var (extractor, state) = Build(); - state.TryWrite("callerAskedForHuman", JsonValue.Create(true)); + Assert.Equal( + "the machine model", + schema.GetProperty("properties").GetProperty("machineModel").GetProperty("description").GetString()); + } - var result = extractor.Write(state, """{ "callerAskedForHuman": null, "callerSaidGoodbye": null, "machineModel": null }"""); + [Fact] + public void ANullField_LeavesThePreviousValue() + { + (StateExtractor? extractor, StateDocument? state) = Build(); + _ = state.TryWrite("callerAskedForHuman", JsonValue.Create(true)); - Assert.True(result.Deserialized); - Assert.Equal(3, result.LeftNull); - Assert.Equal(0, result.Filled); - Assert.True(state.Read("callerAskedForHuman")!.GetValue()); - } + StateExtractionResult result = extractor.Write(state, /*lang=json,strict*/ """{ "callerAskedForHuman": null, "callerSaidGoodbye": null, "machineModel": null }"""); - [Fact] - public void AFalseField_WritesFalse() - { - var (extractor, state) = Build(); - state.TryWrite("callerAskedForHuman", JsonValue.Create(true)); + Assert.True(result.Deserialized); + Assert.Equal(3, result.LeftNull); + Assert.Equal(0, result.Filled); + Assert.True(state.Read("callerAskedForHuman")!.GetValue()); + } - var result = extractor.Write(state, """{ "callerAskedForHuman": false, "callerSaidGoodbye": null, "machineModel": null }"""); + [Fact] + public void AFalseField_WritesFalse() + { + (StateExtractor? extractor, StateDocument? state) = Build(); + _ = state.TryWrite("callerAskedForHuman", JsonValue.Create(true)); - Assert.Equal(1, result.Filled); - Assert.False(state.Read("callerAskedForHuman")!.GetValue()); - Assert.False(state.IsUnfilled("callerAskedForHuman")); - } + StateExtractionResult result = extractor.Write(state, /*lang=json,strict*/ """{ "callerAskedForHuman": false, "callerSaidGoodbye": null, "machineModel": null }"""); - [Fact] - public void UnfilledAndFilledFalse_AreDifferentStates() - { - var (extractor, state) = Build(); + Assert.Equal(1, result.Filled); + Assert.False(state.Read("callerAskedForHuman")!.GetValue()); + Assert.False(state.IsUnfilled("callerAskedForHuman")); + } - // Both read as false. Only one of them has an answer behind it. - Assert.True(state.IsUnfilled("callerSaidGoodbye")); - Assert.False(state.Read("callerSaidGoodbye")!.GetValue()); + [Fact] + public void UnfilledAndFilledFalse_AreDifferentStates() + { + (StateExtractor? extractor, StateDocument? state) = Build(); - extractor.Write(state, """{ "callerSaidGoodbye": false }"""); + // Both read as false. Only one of them has an answer behind it. + Assert.True(state.IsUnfilled("callerSaidGoodbye")); + Assert.False(state.Read("callerSaidGoodbye")!.GetValue()); - Assert.False(state.IsUnfilled("callerSaidGoodbye")); - Assert.False(state.Read("callerSaidGoodbye")!.GetValue()); - } + _ = extractor.Write(state, /*lang=json,strict*/ """{ "callerSaidGoodbye": false }"""); - [Fact] - public void AMissingField_IsTreatedAsNull() - { - var (extractor, state) = Build(); - state.TryWrite("machineModel", JsonValue.Create("F85")); + Assert.False(state.IsUnfilled("callerSaidGoodbye")); + Assert.False(state.Read("callerSaidGoodbye")!.GetValue()); + } - var result = extractor.Write(state, """{ "callerSaidGoodbye": true }"""); + [Fact] + public void AMissingField_IsTreatedAsNull() + { + (StateExtractor? extractor, StateDocument? state) = Build(); + _ = state.TryWrite("machineModel", JsonValue.Create("F85")); - Assert.Equal(1, result.Filled); - Assert.Equal(2, result.LeftNull); - Assert.Equal("F85", state.Read("machineModel")!.GetValue()); - } + StateExtractionResult result = extractor.Write(state, /*lang=json,strict*/ """{ "callerSaidGoodbye": true }"""); - [Fact] - public void AReplyThatDoesNotDeserialize_LeavesTheSlotsUnchanged() - { - var (extractor, state) = Build(); - state.TryWrite("machineModel", JsonValue.Create("F80")); + Assert.Equal(1, result.Filled); + Assert.Equal(2, result.LeftNull); + Assert.Equal("F85", state.Read("machineModel")!.GetValue()); + } - var result = extractor.Write(state, "I am sorry, I cannot do that."); + [Fact] + public void AReplyThatDoesNotDeserialize_LeavesTheSlotsUnchanged() + { + (StateExtractor? extractor, StateDocument? state) = Build(); + _ = state.TryWrite("machineModel", JsonValue.Create("F80")); - // Section 8.7: the extractor has no retry, and a failed extraction never drops a conversation. - Assert.False(result.Deserialized); - Assert.NotNull(result.Failure); - Assert.Equal(0, result.Filled); - Assert.Equal("F80", state.Read("machineModel")!.GetValue()); - } + StateExtractionResult result = extractor.Write(state, "I am sorry, I cannot do that."); - [Fact] - public void AnEmptyReply_LeavesTheSlotsUnchanged() - { - var (extractor, state) = Build(); + // Section 8.7: the extractor has no retry, and a failed extraction never drops a conversation. + Assert.False(result.Deserialized); + Assert.NotNull(result.Failure); + Assert.Equal(0, result.Filled); + Assert.Equal("F80", state.Read("machineModel")!.GetValue()); + } - var result = extractor.Write(state, ""); + [Fact] + public void AnEmptyReply_LeavesTheSlotsUnchanged() + { + (StateExtractor? extractor, StateDocument? state) = Build(); - Assert.False(result.Deserialized); - Assert.True(state.IsUnfilled("machineModel")); - } + StateExtractionResult result = extractor.Write(state, ""); - [Fact] - public void AnAnswerThatDoesNotCoerce_IsRejectedAndTheSlotStays() - { - var (extractor, state) = Build(); + Assert.False(result.Deserialized); + Assert.True(state.IsUnfilled("machineModel")); + } - var result = extractor.Write(state, """{ "machineModel": [ "F85" ] }"""); + [Fact] + public void AnAnswerThatDoesNotCoerce_IsRejectedAndTheSlotStays() + { + (StateExtractor? extractor, StateDocument? state) = Build(); - Assert.Equal(1, result.Rejected); - Assert.True(state.IsUnfilled("machineModel")); - } + StateExtractionResult result = extractor.Write(state, /*lang=json,strict*/ """{ "machineModel": [ "F85" ] }"""); - [Fact] - public async Task TheExtractor_MakesExactlyOneModelCall() - { - using ScriptedChatClient client = new("""{ "callerAskedForHuman": null, "callerSaidGoodbye": true, "machineModel": null }"""); - StateExtractor extractor = new(Document, client); - StateDocument state = new(Document); - - var result = await extractor.ExtractAsync( - state, - [new ChatMessage(ChatRole.User, "goodbye")], - TestContext.Current.CancellationToken); - - // The extractor has no retry: one conversation, and one only. - Assert.Equal(1, client.Calls); - Assert.True(result.Deserialized); - Assert.True(state.Read("callerSaidGoodbye")!.GetValue()); - Assert.True(state.IsUnfilled("machineModel")); - } + Assert.Equal(1, result.Rejected); + Assert.True(state.IsUnfilled("machineModel")); + } - [Fact] - public async Task TheExtractor_SendsTheNullableSchemaAsTheResponseFormat() - { - using RecordingChatClient client = new("""{ "callerSaidGoodbye": null }"""); - StateExtractor extractor = new(Document, client); + [Fact] + public async Task TheExtractor_MakesExactlyOneModelCall() + { + using ScriptedChatClient client = new(/*lang=json,strict*/ """{ "callerAskedForHuman": null, "callerSaidGoodbye": true, "machineModel": null }"""); + StateExtractor extractor = new(Document, client); + StateDocument state = new(Document); + + StateExtractionResult result = await extractor.ExtractAsync( + state, + [new ChatMessage(ChatRole.User, "goodbye")], + TestContext.Current.CancellationToken); + + // The extractor has no retry: one conversation, and one only. + Assert.Equal(1, client.Calls); + Assert.True(result.Deserialized); + Assert.True(state.Read("callerSaidGoodbye")!.GetValue()); + Assert.True(state.IsUnfilled("machineModel")); + } - await extractor.ExtractAsync( - new StateDocument(Document), - [new ChatMessage(ChatRole.User, "hello")], - TestContext.Current.CancellationToken); + [Fact] + public async Task TheExtractor_SendsTheNullableSchemaAsTheResponseFormat() + { + using RecordingChatClient client = new(/*lang=json,strict*/ """{ "callerSaidGoodbye": null }"""); + StateExtractor extractor = new(Document, client); - var format = Assert.IsType(client.LastOptions!.ResponseFormat); - Assert.Equal(StateExtractor.SchemaName, format.SchemaName); - Assert.Contains("null", format.Schema!.Value.GetRawText(), StringComparison.Ordinal); - } + _ = await extractor.ExtractAsync( + new StateDocument(Document), + [new ChatMessage(ChatRole.User, "hello")], + TestContext.Current.CancellationToken); - [Fact] - public void ADocumentWithNoExtractorSection_Throws() - { - var document = ConfigurationLoader.LoadYaml(CompileTableYaml); - using ScriptedChatClient client = new("{}"); + ChatResponseFormatJson format = Assert.IsType(client.LastOptions!.ResponseFormat); + Assert.Equal(StateExtractor.SchemaName, format.SchemaName); + Assert.Contains("null", format.Schema!.Value.GetRawText(), StringComparison.Ordinal); + } - Assert.Throws(() => new StateExtractor(document, client)); - } + [Fact] + public void ADocumentWithNoExtractorSection_Throws() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(CompileTableYaml); + using ScriptedChatClient client = new("{}"); + + _ = Assert.Throws(() => new StateExtractor(document, client)); + } - private const string CompileTableYaml = - """ + private const string CompileTableYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -221,44 +221,46 @@ public void ADocumentWithNoExtractorSection_Throws() agent: only """; - private static (StateExtractor Extractor, StateDocument State) Build() - { - var client = new ScriptedChatClient("{}"); - return (new StateExtractor(Document, client), new StateDocument(Document)); - } - - private sealed class RecordingChatClient : IChatClient - { - private readonly string _reply; - - public RecordingChatClient(string reply) => _reply = reply; - - public ChatOptions? LastOptions { get; private set; } - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) + private static (StateExtractor Extractor, StateDocument State) Build() { - LastOptions = options; - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); + ScriptedChatClient client = new("{}"); + return (new StateExtractor(Document, client), new StateDocument(Document)); } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) - { - LastOptions = options; - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply); - await Task.CompletedTask.ConfigureAwait(false); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() + private sealed class RecordingChatClient(string reply) : IChatClient { - // Nothing to release. + private readonly string _reply = reply; + + public ChatOptions? LastOptions { get; private set; } + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + LastOptions = options; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + { + LastOptions = options; + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply); + await Task.CompletedTask.ConfigureAwait(false); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + // Nothing to release. + } } } } diff --git a/tests/AgentCore.Application.Tests/State/StateWriterTests.cs b/tests/AgentCore.Application.Tests/State/StateWriterTests.cs index ffd13979..684af364 100644 --- a/tests/AgentCore.Application.Tests/State/StateWriterTests.cs +++ b/tests/AgentCore.Application.Tests/State/StateWriterTests.cs @@ -5,15 +5,15 @@ using AgentCore.Application.Tests.Fakes; using Xunit; -namespace AgentCore.Application.Tests.State; - -/// -/// The four writers of section 8.3. Every slot has exactly one owner. -/// -public sealed class StateWriterTests +namespace AgentCore.Application.Tests.State { - private const string Yaml = - """ + /// + /// The four writers of section 8.3. Every slot has exactly one owner. + /// + public sealed class StateWriterTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 state: resolved: { type: boolean, default: false, writer: extractor } @@ -39,150 +39,153 @@ public sealed class StateWriterTests agent: only """; - private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); + private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); - [Fact] - public void ConstWriter_FillsItsSlot() - { - StateDocument state = new(Document); + [Fact] + public void ConstWriter_FillsItsSlot() + { + StateDocument state = new(Document); - Assert.Equal(1, ConstStateWriter.Apply(state)); + Assert.Equal(1, ConstStateWriter.Apply(state)); - Assert.Equal("sole", state.Read("brand")!.GetValue()); - Assert.False(state.IsUnfilled("brand")); - } + Assert.Equal("sole", state.Read("brand")!.GetValue()); + Assert.False(state.IsUnfilled("brand")); + } - [Fact] - public void ToolWriter_FillsItsSlotFromTheNamedField() - { - StateDocument state = new(Document); - var result = JsonNode.Parse("""{ "status": "shipped", "count": 4, "totals": { "grand": 129.5 } }"""); + [Fact] + public void ToolWriter_FillsItsSlotFromTheNamedField() + { + StateDocument state = new(Document); + JsonNode? result = JsonNode.Parse("""{ "status": "shipped", "count": 4, "totals": { "grand": 129.5 } }"""); - Assert.Equal(3, ToolStateWriter.Apply(state, "lookup_order", result)); + Assert.Equal(3, ToolStateWriter.Apply(state, "lookup_order", result)); - Assert.Equal("shipped", state.Read("orderStatus")!.GetValue()); - Assert.Equal(4, state.Read("orderCount")!.GetValue()); - Assert.Equal(129.5, state.Read("orderTotal")!.GetValue()); - } + Assert.Equal("shipped", state.Read("orderStatus")!.GetValue()); + Assert.Equal(4, state.Read("orderCount")!.GetValue()); + Assert.Equal(129.5, state.Read("orderTotal")!.GetValue()); + } - [Fact] - public void ToolWriter_IgnoresTheResultOfAnotherTool() - { - StateDocument state = new(Document); - var result = JsonNode.Parse("""{ "status": "shipped" }"""); + [Fact] + public void ToolWriter_IgnoresTheResultOfAnotherTool() + { + StateDocument state = new(Document); + JsonNode? result = JsonNode.Parse("""{ "status": "shipped" }"""); - Assert.Equal(0, ToolStateWriter.Apply(state, "some_other_tool", result)); - Assert.True(state.IsUnfilled("orderStatus")); - } + Assert.Equal(0, ToolStateWriter.Apply(state, "some_other_tool", result)); + Assert.True(state.IsUnfilled("orderStatus")); + } - [Fact] - public void ToolWriter_AFailedCoercionLeavesTheDefault() - { - StateDocument state = new(Document); + [Fact] + public void ToolWriter_AFailedCoercionLeavesTheDefault() + { + StateDocument state = new(Document); - // count is an integer slot, and the tool answered with an object. The declared type wins. - var result = JsonNode.Parse("""{ "status": "shipped", "count": { "nested": 1 } }"""); + // count is an integer slot, and the tool answered with an object. The declared type wins. + JsonNode? result = JsonNode.Parse("""{ "status": "shipped", "count": { "nested": 1 } }"""); - Assert.Equal(1, ToolStateWriter.Apply(state, "lookup_order", result)); + Assert.Equal(1, ToolStateWriter.Apply(state, "lookup_order", result)); - Assert.True(state.IsUnfilled("orderCount")); - Assert.Equal(-1, state.Read("orderCount")!.GetValue()); - } + Assert.True(state.IsUnfilled("orderCount")); + Assert.Equal(-1, state.Read("orderCount")!.GetValue()); + } - [Fact] - public void ToolWriter_APathThatReachesNothingLeavesTheDefault() - { - StateDocument state = new(Document); - var result = JsonNode.Parse("""{ "other": "value" }"""); + [Fact] + public void ToolWriter_APathThatReachesNothingLeavesTheDefault() + { + StateDocument state = new(Document); + JsonNode? result = JsonNode.Parse("""{ "other": "value" }"""); - Assert.Equal(0, ToolStateWriter.Apply(state, "lookup_order", result)); - Assert.True(state.IsUnfilled("orderStatus")); - Assert.Null(state.Read("orderStatus")); - } + Assert.Equal(0, ToolStateWriter.Apply(state, "lookup_order", result)); + Assert.True(state.IsUnfilled("orderStatus")); + Assert.Null(state.Read("orderStatus")); + } - [Fact] - public void CounterWriter_IncrementsWheneverItsRuleIsTrue() - { - StateDocument state = new(Document) { Stage = "resolve" }; - CounterStateWriter counter = new(new TestGuardEvaluator(Document)); + [Fact] + public void CounterWriter_IncrementsWheneverItsRuleIsTrue() + { + StateDocument state = new(Document) { Stage = "resolve" }; + CounterStateWriter counter = new(new TestGuardEvaluator(Document)); - Assert.Equal(1, counter.Apply(state)); - Assert.Equal(1, state.Read("failedResolveTurns")!.GetValue()); + Assert.Equal(1, counter.Apply(state)); + Assert.Equal(1, state.Read("failedResolveTurns")!.GetValue()); - counter.Apply(state); - counter.Apply(state); - Assert.Equal(3, state.Read("failedResolveTurns")!.GetValue()); - } + _ = counter.Apply(state); + _ = counter.Apply(state); + Assert.Equal(3, state.Read("failedResolveTurns")!.GetValue()); + } - [Fact] - public void CounterWriter_HoldsStillWhenItsRuleIsFalse() - { - StateDocument state = new(Document) { Stage = "greeting" }; - CounterStateWriter counter = new(new TestGuardEvaluator(Document)); + [Fact] + public void CounterWriter_HoldsStillWhenItsRuleIsFalse() + { + StateDocument state = new(Document) { Stage = "greeting" }; + CounterStateWriter counter = new(new TestGuardEvaluator(Document)); - Assert.Equal(0, counter.Apply(state)); - Assert.Equal(0, state.Read("failedResolveTurns")!.GetValue()); - Assert.True(state.IsUnfilled("failedResolveTurns")); - } + Assert.Equal(0, counter.Apply(state)); + Assert.Equal(0, state.Read("failedResolveTurns")!.GetValue()); + Assert.True(state.IsUnfilled("failedResolveTurns")); + } - [Fact] - public void CounterWriter_HoldsStillOnceTheSlotItWatchesIsTrue() - { - StateDocument state = new(Document) { Stage = "resolve" }; - CounterStateWriter counter = new(new TestGuardEvaluator(Document)); + [Fact] + public void CounterWriter_HoldsStillOnceTheSlotItWatchesIsTrue() + { + StateDocument state = new(Document) { Stage = "resolve" }; + CounterStateWriter counter = new(new TestGuardEvaluator(Document)); - counter.Apply(state); - state.TryWrite("resolved", JsonValue.Create(true)); + _ = counter.Apply(state); + _ = state.TryWrite("resolved", JsonValue.Create(true)); - Assert.Equal(0, counter.Apply(state)); - Assert.Equal(1, state.Read("failedResolveTurns")!.GetValue()); - } + Assert.Equal(0, counter.Apply(state)); + Assert.Equal(1, state.Read("failedResolveTurns")!.GetValue()); + } - [Fact] - public void TheThreeReservedSlots_AreAlwaysPresentAndReadOnly() - { - StateDocument state = new(Document) { Stage = "resolve", TurnIndex = 7, ConversationDurationSeconds = 42.5 }; + [Fact] + public void TheThreeReservedSlots_AreAlwaysPresentAndReadOnly() + { + StateDocument state = new(Document) { Stage = "resolve", TurnIndex = 7, ConversationDurationSeconds = 42.5 }; - var snapshot = state.Snapshot(); + IReadOnlyDictionary snapshot = state.Snapshot(); - Assert.Equal("resolve", snapshot[ReservedStateSlots.Stage]!.GetValue()); - Assert.Equal(7, snapshot[ReservedStateSlots.TurnIndex]!.GetValue()); - Assert.Equal(42.5, snapshot[ReservedStateSlots.ConversationDurationSeconds]!.GetValue()); + Assert.Equal("resolve", snapshot[ReservedStateSlots.Stage]!.GetValue()); + Assert.Equal(7, snapshot[ReservedStateSlots.TurnIndex]!.GetValue()); + Assert.Equal(42.5, snapshot[ReservedStateSlots.ConversationDurationSeconds]!.GetValue()); - foreach (var reserved in ReservedStateSlots.All) - { - Assert.Throws(() => state.TryWrite(reserved, JsonValue.Create(1))); + foreach (string reserved in ReservedStateSlots.All) + { + _ = Assert.Throws(() => state.TryWrite(reserved, JsonValue.Create(1))); + } } - } - [Fact] - public void ASnapshot_HoldsEveryDeclaredSlotAndTheThreeReservedOnes() - { - StateDocument state = new(Document); + [Fact] + public void ASnapshot_HoldsEveryDeclaredSlotAndTheThreeReservedOnes() + { + StateDocument state = new(Document); - var snapshot = state.Snapshot(); + IReadOnlyDictionary snapshot = state.Snapshot(); - Assert.Equal(Document.State.Count + 3, snapshot.Count); - } + Assert.Equal(Document.State.Count + 3, snapshot.Count); + } - [Theory] - [InlineData(StateSlotType.Boolean, "\"true\"", true)] - [InlineData(StateSlotType.Boolean, "1", false)] - [InlineData(StateSlotType.Integer, "\"12\"", true)] - [InlineData(StateSlotType.Integer, "12.0", true)] - [InlineData(StateSlotType.Integer, "12.5", false)] - [InlineData(StateSlotType.Integer, "true", false)] - [InlineData(StateSlotType.Number, "\"1.5\"", true)] - [InlineData(StateSlotType.String, "12", true)] - [InlineData(StateSlotType.String, "[1]", false)] - public void Coercion_FollowsTheDeclaredType(StateSlotType slotType, string json, bool expected) - { - var value = JsonNode.Parse(json); + [Theory] + [InlineData(StateSlotType.Boolean, "\"true\"", true)] + [InlineData(StateSlotType.Boolean, "1", false)] + [InlineData(StateSlotType.Integer, "\"12\"", true)] + [InlineData(StateSlotType.Integer, "12.0", true)] + [InlineData(StateSlotType.Integer, "12.5", false)] + [InlineData(StateSlotType.Integer, "true", false)] + [InlineData(StateSlotType.Number, "\"1.5\"", true)] + [InlineData(StateSlotType.String, "12", true)] + [InlineData(StateSlotType.String, "[1]", false)] + public void Coercion_FollowsTheDeclaredType(StateSlotType slotType, string json, bool expected) + { + JsonNode? value = JsonNode.Parse(json); - Assert.Equal(expected, StateValueCoercion.TryCoerce(value, slotType, out _)); - } + Assert.Equal(expected, StateValueCoercion.TryCoerce(value, slotType, out _)); + } - [Fact] - public void Coercion_RefusesNull() - => Assert.False(StateValueCoercion.TryCoerce(null, StateSlotType.Boolean, out _)); + [Fact] + public void Coercion_RefusesNull() + { + Assert.False(StateValueCoercion.TryCoerce(null, StateSlotType.Boolean, out _)); + } + } } diff --git a/tests/AgentCore.Application.Tests/State/ToolResultPathTests.cs b/tests/AgentCore.Application.Tests/State/ToolResultPathTests.cs index ca8d4dfe..d8a745d8 100644 --- a/tests/AgentCore.Application.Tests/State/ToolResultPathTests.cs +++ b/tests/AgentCore.Application.Tests/State/ToolResultPathTests.cs @@ -2,26 +2,26 @@ using AgentCore.Application.State; using Xunit; -namespace AgentCore.Application.Tests.State; - -/// -/// Section 8.3: a writer: tool path resolves against a tool result two ways - the compact -/// dotted form (lookup_order.status) and the RFC 6901 pointer form (/lookup_order/status). -/// is , reachable here only because this test -/// assembly holds an InternalsVisibleTo. -/// -/// -/// These tests pin every edge case the hand-rolled resolver handled, before and after it is backed by -/// Json.Pointer.JsonPointer: the empty path, the leading slash, array indexing, a segment -/// containing ~ or /, a missing path, and a path that walks into a non-object. A few -/// extra cases (multi-digit leading-zero array indices, the RFC 6901 - token, and a malformed -/// escape sequence) are pinned too, because they surfaced while reading the replacement library's -/// source and are exactly the kind of thing a naive dotted-to-pointer translation gets wrong. -/// -public sealed class ToolResultPathTests +namespace AgentCore.Application.Tests.State { - private static readonly JsonNode Result = JsonNode.Parse( - """ + /// + /// Section 8.3: a writer: tool path resolves against a tool result two ways - the compact + /// dotted form (lookup_order.status) and the RFC 6901 pointer form (/lookup_order/status). + /// is , reachable here only because this test + /// assembly holds an InternalsVisibleTo. + /// + /// + /// These tests pin every edge case the hand-rolled resolver handled, before and after it is backed by + /// Json.Pointer.JsonPointer: the empty path, the leading slash, array indexing, a segment + /// containing ~ or /, a missing path, and a path that walks into a non-object. A few + /// extra cases (multi-digit leading-zero array indices, the RFC 6901 - token, and a malformed + /// escape sequence) are pinned too, because they surfaced while reading the replacement library's + /// source and are exactly the kind of thing a naive dotted-to-pointer translation gets wrong. + /// + public sealed class ToolResultPathTests + { + private static readonly JsonNode Result = JsonNode.Parse( + """ { "status": "shipped", "totals": { "grand": 129.5 }, @@ -33,140 +33,179 @@ public sealed class ToolResultPathTests } """)!; - // --------------------------------------------------------------------------------------------- - // The empty path: resolves to the whole result, unchanged. - // --------------------------------------------------------------------------------------------- - [Fact] - public void EmptyPath_ResolvesToTheWholeResult() - => Assert.Same(Result, ToolResultPath.Resolve(Result, "")); - - // --------------------------------------------------------------------------------------------- - // The dotted compact form. - // --------------------------------------------------------------------------------------------- - [Fact] - public void DottedPath_ResolvesATopLevelProperty() - => Assert.Equal("shipped", ToolResultPath.Resolve(Result, "status")!.GetValue()); - - [Fact] - public void DottedPath_ResolvesANestedProperty() - => Assert.Equal(129.5, ToolResultPath.Resolve(Result, "totals.grand")!.GetValue()); - - [Fact] - public void DottedPath_IndexesAnArray() - => Assert.Equal("b", ToolResultPath.Resolve(Result, "items.1")!.GetValue()); - - [Fact] - public void DottedPath_ASegmentContainingATilde_IsTakenLiterally() - => Assert.Equal("tilde-key", ToolResultPath.Resolve(Result, "a~b")!.GetValue()); - - [Fact] - public void DottedPath_ASegmentContainingASlash_IsTakenLiterally() - => Assert.Equal("slash-key", ToolResultPath.Resolve(Result, "a/b")!.GetValue()); - - // --------------------------------------------------------------------------------------------- - // The RFC 6901 pointer form: a leading slash. - // --------------------------------------------------------------------------------------------- - [Fact] - public void PointerPath_ResolvesATopLevelProperty() - => Assert.Equal("shipped", ToolResultPath.Resolve(Result, "/status")!.GetValue()); - - [Fact] - public void PointerPath_ResolvesANestedProperty() - => Assert.Equal(129.5, ToolResultPath.Resolve(Result, "/totals/grand")!.GetValue()); - - [Fact] - public void PointerPath_IndexesAnArray() - => Assert.Equal("c", ToolResultPath.Resolve(Result, "/items/2")!.GetValue()); - - [Fact] - public void PointerPath_UnescapesTilde0ToALiteralTilde() - => Assert.Equal("tilde-key", ToolResultPath.Resolve(Result, "/a~0b")!.GetValue()); - - [Fact] - public void PointerPath_UnescapesTilde1ToALiteralSlash() - => Assert.Equal("slash-key", ToolResultPath.Resolve(Result, "/a~1b")!.GetValue()); - - [Fact] - public void PointerPath_ASingleSlash_ResolvesTheEmptyStringKey() - => Assert.Equal("empty-key", ToolResultPath.Resolve(Result, "/")!.GetValue()); - - // --------------------------------------------------------------------------------------------- - // What reaches nothing. - // --------------------------------------------------------------------------------------------- - [Fact] - public void DottedPath_AMissingProperty_ResolvesToNull() - => Assert.Null(ToolResultPath.Resolve(Result, "nope")); - - [Fact] - public void PointerPath_AMissingProperty_ResolvesToNull() - => Assert.Null(ToolResultPath.Resolve(Result, "/nope")); - - [Fact] - public void APathIntoANonObject_ResolvesToNull() - // "status" is a string; stepping past it reaches nothing. - => Assert.Null(ToolResultPath.Resolve(Result, "status.nested")); - - [Fact] - public void ANonNumericSegmentAgainstAnArray_ResolvesToNull() - => Assert.Null(ToolResultPath.Resolve(Result, "items.notanumber")); - - [Fact] - public void AnOutOfRangeArrayIndex_ResolvesToNull() - => Assert.Null(ToolResultPath.Resolve(Result, "items.99")); - - [Fact] - public void ANullResult_ResolvesToNullWhateverThePathIs() - => Assert.Null(ToolResultPath.Resolve(null, "status")); - - // --------------------------------------------------------------------------------------------- - // Extra edge cases found while reading the replacement library's own evaluator: RFC 6901 is - // stricter about array indices than the hand-rolled int.TryParse ever was. - // - // Fix round 1 (owner ruling): three divergences from the pre-swap resolver surfaced here. Two - // were accepted as a deliberate tightening - invalid input now fails instead of silently - // resolving - and are pinned below to the *new* behaviour, with the old behaviour named in the - // comment. The third (the '-' token) was rejected, because it was the one case where invalid - // input started silently *succeeding*, which could put a new, undecided value into a state - // slot; ToolResultPath now guards it explicitly, so that test still pins the original `null`. - // --------------------------------------------------------------------------------------------- - [Fact] - public void PointerPath_ALeadingZeroMultiDigitArrayIndex_ResolvesToNull() - { - // Owner ruling, fix round 1: ACCEPTED as a deliberate tightening. The pre-swap hand-rolled - // resolver used int.TryParse("01"), which happily parses to 1, so "/items/01" used to - // resolve to the element at index 1 - a document relying on that was relying on a bug. - // Json.Pointer.JsonPointer enforces RFC 6901's canonical-index rule (no leading zero except - // the literal index "0") and rejects the whole pointer, so this now resolves to nothing. - Assert.Null(ToolResultPath.Resolve(Result, "/items/01")); - } + // --------------------------------------------------------------------------------------------- + // The empty path: resolves to the whole result, unchanged. + // --------------------------------------------------------------------------------------------- + [Fact] + public void EmptyPath_ResolvesToTheWholeResult() + { + Assert.Same(Result, ToolResultPath.Resolve(Result, "")); + } - [Fact] - public void PointerPath_TheDashToken_IsRejectedAndResolvesToNull() - { - // Owner ruling, fix round 1: REJECTED - the old behaviour is preserved deliberately, not - // merely pinned. RFC 6901 defines '-' as "the (nonexistent) member after the last array - // element", and Json.Pointer.JsonPointer's TryEvaluate implements that by resolving it to - // the *existing* last element. Unlike the other two divergences, that would make a - // previously-invalid path start silently succeeding - turning "no state write" into "write - // the array's last element" as a side effect of the library swap rather than a document - // decision. ToolResultPath now rejects a '-' segment before evaluating, so this still - // resolves to null exactly as the pre-swap resolver did (int.TryParse("-") failed there). - Assert.Null(ToolResultPath.Resolve(Result, "/items/-")); - } + // --------------------------------------------------------------------------------------------- + // The dotted compact form. + // --------------------------------------------------------------------------------------------- + [Fact] + public void DottedPath_ResolvesATopLevelProperty() + { + Assert.Equal("shipped", ToolResultPath.Resolve(Result, "status")!.GetValue()); + } - [Fact] - public void PointerPath_ANegativeArrayIndex_ResolvesToNull() - => Assert.Null(ToolResultPath.Resolve(Result, "/items/-1")); + [Fact] + public void DottedPath_ResolvesANestedProperty() + { + Assert.Equal(129.5, ToolResultPath.Resolve(Result, "totals.grand")!.GetValue()); + } - [Fact] - public void PointerPath_AMalformedEscapeSequence_ResolvesToNull() - { - // Owner ruling, fix round 1: ACCEPTED as a deliberate tightening. "~2" is not a valid RFC - // 6901 escape (only ~0 and ~1 are defined). The pre-swap hand-rolled resolver's Replace - // conversations simply didn't match "~2", so the segment survived as the literal text "a~2b" and - // resolved whatever property happened to have that exact (unusual) name. Json.Pointer. - // JsonPointer validates every escape up front and rejects the whole pointer as malformed, so - // this now resolves to nothing even though the document does hold a property named "a~2b". - Assert.Null(ToolResultPath.Resolve(Result, "/a~2b")); + [Fact] + public void DottedPath_IndexesAnArray() + { + Assert.Equal("b", ToolResultPath.Resolve(Result, "items.1")!.GetValue()); + } + + [Fact] + public void DottedPath_ASegmentContainingATilde_IsTakenLiterally() + { + Assert.Equal("tilde-key", ToolResultPath.Resolve(Result, "a~b")!.GetValue()); + } + + [Fact] + public void DottedPath_ASegmentContainingASlash_IsTakenLiterally() + { + Assert.Equal("slash-key", ToolResultPath.Resolve(Result, "a/b")!.GetValue()); + } + + // --------------------------------------------------------------------------------------------- + // The RFC 6901 pointer form: a leading slash. + // --------------------------------------------------------------------------------------------- + [Fact] + public void PointerPath_ResolvesATopLevelProperty() + { + Assert.Equal("shipped", ToolResultPath.Resolve(Result, "/status")!.GetValue()); + } + + [Fact] + public void PointerPath_ResolvesANestedProperty() + { + Assert.Equal(129.5, ToolResultPath.Resolve(Result, "/totals/grand")!.GetValue()); + } + + [Fact] + public void PointerPath_IndexesAnArray() + { + Assert.Equal("c", ToolResultPath.Resolve(Result, "/items/2")!.GetValue()); + } + + [Fact] + public void PointerPath_UnescapesTilde0ToALiteralTilde() + { + Assert.Equal("tilde-key", ToolResultPath.Resolve(Result, "/a~0b")!.GetValue()); + } + + [Fact] + public void PointerPath_UnescapesTilde1ToALiteralSlash() + { + Assert.Equal("slash-key", ToolResultPath.Resolve(Result, "/a~1b")!.GetValue()); + } + + [Fact] + public void PointerPath_ASingleSlash_ResolvesTheEmptyStringKey() + { + Assert.Equal("empty-key", ToolResultPath.Resolve(Result, "/")!.GetValue()); + } + + // --------------------------------------------------------------------------------------------- + // What reaches nothing. + // --------------------------------------------------------------------------------------------- + [Fact] + public void DottedPath_AMissingProperty_ResolvesToNull() + { + Assert.Null(ToolResultPath.Resolve(Result, "nope")); + } + + [Fact] + public void PointerPath_AMissingProperty_ResolvesToNull() + { + Assert.Null(ToolResultPath.Resolve(Result, "/nope")); + } + + [Fact] + public void APathIntoANonObject_ResolvesToNull() + { + // "status" is a string; stepping past it reaches nothing. + Assert.Null(ToolResultPath.Resolve(Result, "status.nested")); + } + + [Fact] + public void ANonNumericSegmentAgainstAnArray_ResolvesToNull() + { + Assert.Null(ToolResultPath.Resolve(Result, "items.notanumber")); + } + + [Fact] + public void AnOutOfRangeArrayIndex_ResolvesToNull() + { + Assert.Null(ToolResultPath.Resolve(Result, "items.99")); + } + + [Fact] + public void ANullResult_ResolvesToNullWhateverThePathIs() + { + Assert.Null(ToolResultPath.Resolve(null, "status")); + } + + // --------------------------------------------------------------------------------------------- + // Extra edge cases found while reading the replacement library's own evaluator: RFC 6901 is + // stricter about array indices than the hand-rolled int.TryParse ever was. + // + // Fix round 1 (owner ruling): three divergences from the pre-swap resolver surfaced here. Two + // were accepted as a deliberate tightening - invalid input now fails instead of silently + // resolving - and are pinned below to the *new* behaviour, with the old behaviour named in the + // comment. The third (the '-' token) was rejected, because it was the one case where invalid + // input started silently *succeeding*, which could put a new, undecided value into a state + // slot; ToolResultPath now guards it explicitly, so that test still pins the original `null`. + // --------------------------------------------------------------------------------------------- + [Fact] + public void PointerPath_ALeadingZeroMultiDigitArrayIndex_ResolvesToNull() + { + // Owner ruling, fix round 1: ACCEPTED as a deliberate tightening. The pre-swap hand-rolled + // resolver used int.TryParse("01"), which happily parses to 1, so "/items/01" used to + // resolve to the element at index 1 - a document relying on that was relying on a bug. + // Json.Pointer.JsonPointer enforces RFC 6901's canonical-index rule (no leading zero except + // the literal index "0") and rejects the whole pointer, so this now resolves to nothing. + Assert.Null(ToolResultPath.Resolve(Result, "/items/01")); + } + + [Fact] + public void PointerPath_TheDashToken_IsRejectedAndResolvesToNull() + { + // Owner ruling, fix round 1: REJECTED - the old behaviour is preserved deliberately, not + // merely pinned. RFC 6901 defines '-' as "the (nonexistent) member after the last array + // element", and Json.Pointer.JsonPointer's TryEvaluate implements that by resolving it to + // the *existing* last element. Unlike the other two divergences, that would make a + // previously-invalid path start silently succeeding - turning "no state write" into "write + // the array's last element" as a side effect of the library swap rather than a document + // decision. ToolResultPath now rejects a '-' segment before evaluating, so this still + // resolves to null exactly as the pre-swap resolver did (int.TryParse("-") failed there). + Assert.Null(ToolResultPath.Resolve(Result, "/items/-")); + } + + [Fact] + public void PointerPath_ANegativeArrayIndex_ResolvesToNull() + { + Assert.Null(ToolResultPath.Resolve(Result, "/items/-1")); + } + + [Fact] + public void PointerPath_AMalformedEscapeSequence_ResolvesToNull() + { + // Owner ruling, fix round 1: ACCEPTED as a deliberate tightening. "~2" is not a valid RFC + // 6901 escape (only ~0 and ~1 are defined). The pre-swap hand-rolled resolver's Replace + // conversations simply didn't match "~2", so the segment survived as the literal text "a~2b" and + // resolved whatever property happened to have that exact (unusual) name. Json.Pointer. + // JsonPointer validates every escape up front and rejects the whole pointer as malformed, so + // this now resolves to nothing even though the document does hold a property named "a~2b". + Assert.Null(ToolResultPath.Resolve(Result, "/a~2b")); + } } } diff --git a/tests/AgentCore.Application.Tests/State/UnfilledSlotReminderTests.cs b/tests/AgentCore.Application.Tests/State/UnfilledSlotReminderTests.cs index 3da004cd..a06b909a 100644 --- a/tests/AgentCore.Application.Tests/State/UnfilledSlotReminderTests.cs +++ b/tests/AgentCore.Application.Tests/State/UnfilledSlotReminderTests.cs @@ -4,15 +4,15 @@ using AgentCore.Application.State; using Xunit; -namespace AgentCore.Application.Tests.State; - -/// -/// The unfilled-slot reminder of section 8.3. It costs no model request. -/// -public sealed class UnfilledSlotReminderTests +namespace AgentCore.Application.Tests.State { - private const string Yaml = - """ + /// + /// The unfilled-slot reminder of section 8.3. It costs no model request. + /// + public sealed class UnfilledSlotReminderTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 state: machineModel: { type: string, writer: extractor, description: the machine model } @@ -44,140 +44,140 @@ public sealed class UnfilledSlotReminderTests terminal: true """; - private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); - - private static StageConfiguration Identify => Document.Entries["main"].Policy!.Stages[0]; - - private static StageConfiguration Resolve => Document.Entries["main"].Policy!.Stages[1]; - - [Fact] - public void AnUnfilledSlot_ProducesTheReminder() - { - StateDocument state = new(Document); - state.TryWrite("serialNumber", JsonValue.Create("SF240117")); - - var reminder = UnfilledSlotReminder.Build(state, Identify); - - Assert.Equal( - "\n" - + "You still need this from the caller before you can continue: the machine model.\n" - + "Ask for it in your next reply.\n" - + "", - reminder); - } - - [Fact] - public void TwoUnfilledSlots_ReadAsOneSentence() - { - StateDocument state = new(Document); - - var reminder = UnfilledSlotReminder.Build(state, Identify); - - Assert.Contains("the machine model and the serial number.", reminder, StringComparison.Ordinal); - } - - [Fact] - public void AFilledSlot_ProducesNoReminder() - { - StateDocument state = new(Document); - state.TryWrite("machineModel", JsonValue.Create("F85")); - state.TryWrite("serialNumber", JsonValue.Create("SF240117")); - - Assert.Null(UnfilledSlotReminder.Build(state, Identify)); - } - - [Fact] - public void AStageWithNoGuardedExit_ProducesNoReminder() - { - StateDocument state = new(Document); - - Assert.Empty(UnfilledSlotReminder.UnfilledSlots(state, Resolve)); - Assert.Null(UnfilledSlotReminder.Build(state, Resolve)); - } - - [Fact] - public void OnlyAnExtractorSlot_Reminds() - { - StateDocument state = new(Document); - - // orderStatus is unfilled too, and no reminder names it: a tool fills it, not the caller. - Assert.DoesNotContain("orderStatus", UnfilledSlotReminder.UnfilledSlots(state, Identify)); - } - - [Fact] - public void TheReminder_IsOneTaggedBlockAndNothingElse() - { - // It travels as per-invocation instructions, not as part of the caller's message, so the - // tags are what separate it from the agent's own instructions in the merged prompt. - StateDocument state = new(Document); - - var reminder = UnfilledSlotReminder.Build(state, Identify); - - Assert.StartsWith(UnfilledSlotReminder.OpenTag, reminder, StringComparison.Ordinal); - Assert.EndsWith(UnfilledSlotReminder.CloseTag, reminder, StringComparison.Ordinal); - } - - [Fact] - public void AnExitGuardedByMissing_RemindsOnTheMissingSlot() - { - // A guard written with the JSONLogic `missing` operator (rather than `var`) still names the - // slot it waits on. The walk that collects stage-exit slots must catch both forms, or a guard - // written this way reads as waiting on no slots and the caller never gets a reminder. - var yaml = Yaml.Replace( - "- { \"!!\": [ { var: serialNumber } ] }", - "- { \"!\": { missing: [ \"serialNumber\" ] } }", - StringComparison.Ordinal); - var document = ConfigurationLoader.LoadYaml(yaml); - StateDocument state = new(document); - state.TryWrite("machineModel", JsonValue.Create("F85")); - - var reminder = UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0]); - - Assert.Contains("the serial number.", reminder, StringComparison.Ordinal); - } - - [Fact] - public void ASlotWithNoDescription_RemindsByItsName() - { - var yaml = Yaml.Replace( - "- { \"!!\": [ { var: serialNumber } ] }", - "- { \"!!\": [ { var: postcode } ] }", - StringComparison.Ordinal); - var document = ConfigurationLoader.LoadYaml(yaml); - StateDocument state = new(document); - state.TryWrite("machineModel", JsonValue.Create("F85")); - - var reminder = UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0]); - - Assert.Contains("postcode.", reminder, StringComparison.Ordinal); - } - - [Fact] - public void ASlotWithADeclaredDefault_IsNeverUnfilled() - { - // Section 8.3 reminds on a slot that is "still null". A declared default means the slot - // reads as that default and never as null, so the caller has nothing left to supply. T51 - // rests on the same rule: a missed extraction and an unanswered question both leave null. - var yaml = Yaml.Replace( - "- { \"!!\": [ { var: serialNumber } ] }", - "- { \"!\": { var: callerSaidGoodbye } }", - StringComparison.Ordinal); - var document = ConfigurationLoader.LoadYaml(yaml); - StateDocument state = new(document); - state.TryWrite("machineModel", JsonValue.Create("F85")); - - Assert.DoesNotContain("callerSaidGoodbye", UnfilledSlotReminder.UnfilledSlots(state, document.Entries["main"].Policy!.Stages[0])); - Assert.Null(UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0])); - } - - [Fact] - public void AnInferredFlagWithADefault_NeverReachesTheCaller() - { - // The shape config/local.yaml ships: one boolean the extractor infers from the turn, read by - // the exit guard of the only talking stage. Before this rule the agent was told to ask the - // caller for "callerSaidGoodbye", and it did. - var yaml = - """ + private static readonly AgentCoreConfiguration Document = ConfigurationLoader.LoadYaml(Yaml); + + private static StageConfiguration Identify => Document.Entries["main"].Policy!.Stages[0]; + + private static StageConfiguration Resolve => Document.Entries["main"].Policy!.Stages[1]; + + [Fact] + public void AnUnfilledSlot_ProducesTheReminder() + { + StateDocument state = new(Document); + _ = state.TryWrite("serialNumber", JsonValue.Create("SF240117")); + + string? reminder = UnfilledSlotReminder.Build(state, Identify); + + Assert.Equal( + "\n" + + "You still need this from the caller before you can continue: the machine model.\n" + + "Ask for it in your next reply.\n" + + "", + reminder); + } + + [Fact] + public void TwoUnfilledSlots_ReadAsOneSentence() + { + StateDocument state = new(Document); + + string? reminder = UnfilledSlotReminder.Build(state, Identify); + + Assert.Contains("the machine model and the serial number.", reminder, StringComparison.Ordinal); + } + + [Fact] + public void AFilledSlot_ProducesNoReminder() + { + StateDocument state = new(Document); + _ = state.TryWrite("machineModel", JsonValue.Create("F85")); + _ = state.TryWrite("serialNumber", JsonValue.Create("SF240117")); + + Assert.Null(UnfilledSlotReminder.Build(state, Identify)); + } + + [Fact] + public void AStageWithNoGuardedExit_ProducesNoReminder() + { + StateDocument state = new(Document); + + Assert.Empty(UnfilledSlotReminder.UnfilledSlots(state, Resolve)); + Assert.Null(UnfilledSlotReminder.Build(state, Resolve)); + } + + [Fact] + public void OnlyAnExtractorSlot_Reminds() + { + StateDocument state = new(Document); + + // orderStatus is unfilled too, and no reminder names it: a tool fills it, not the caller. + Assert.DoesNotContain("orderStatus", UnfilledSlotReminder.UnfilledSlots(state, Identify)); + } + + [Fact] + public void TheReminder_IsOneTaggedBlockAndNothingElse() + { + // It travels as per-invocation instructions, not as part of the caller's message, so the + // tags are what separate it from the agent's own instructions in the merged prompt. + StateDocument state = new(Document); + + string? reminder = UnfilledSlotReminder.Build(state, Identify); + + Assert.StartsWith(UnfilledSlotReminder.OpenTag, reminder, StringComparison.Ordinal); + Assert.EndsWith(UnfilledSlotReminder.CloseTag, reminder, StringComparison.Ordinal); + } + + [Fact] + public void AnExitGuardedByMissing_RemindsOnTheMissingSlot() + { + // A guard written with the JSONLogic `missing` operator (rather than `var`) still names the + // slot it waits on. The walk that collects stage-exit slots must catch both forms, or a guard + // written this way reads as waiting on no slots and the caller never gets a reminder. + string yaml = Yaml.Replace( + "- { \"!!\": [ { var: serialNumber } ] }", + "- { \"!\": { missing: [ \"serialNumber\" ] } }", + StringComparison.Ordinal); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + StateDocument state = new(document); + _ = state.TryWrite("machineModel", JsonValue.Create("F85")); + + string? reminder = UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0]); + + Assert.Contains("the serial number.", reminder, StringComparison.Ordinal); + } + + [Fact] + public void ASlotWithNoDescription_RemindsByItsName() + { + string yaml = Yaml.Replace( + "- { \"!!\": [ { var: serialNumber } ] }", + "- { \"!!\": [ { var: postcode } ] }", + StringComparison.Ordinal); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + StateDocument state = new(document); + _ = state.TryWrite("machineModel", JsonValue.Create("F85")); + + string? reminder = UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0]); + + Assert.Contains("postcode.", reminder, StringComparison.Ordinal); + } + + [Fact] + public void ASlotWithADeclaredDefault_IsNeverUnfilled() + { + // Section 8.3 reminds on a slot that is "still null". A declared default means the slot + // reads as that default and never as null, so the caller has nothing left to supply. T51 + // rests on the same rule: a missed extraction and an unanswered question both leave null. + string yaml = Yaml.Replace( + "- { \"!!\": [ { var: serialNumber } ] }", + "- { \"!\": { var: callerSaidGoodbye } }", + StringComparison.Ordinal); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + StateDocument state = new(document); + _ = state.TryWrite("machineModel", JsonValue.Create("F85")); + + Assert.DoesNotContain("callerSaidGoodbye", UnfilledSlotReminder.UnfilledSlots(state, document.Entries["main"].Policy!.Stages[0])); + Assert.Null(UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0])); + } + + [Fact] + public void AnInferredFlagWithADefault_NeverReachesTheCaller() + { + // The shape config/local.yaml ships: one boolean the extractor infers from the turn, read by + // the exit guard of the only talking stage. Before this rule the agent was told to ask the + // caller for "callerSaidGoodbye", and it did. + string yaml = + """ apiVersion: agentcore/v1 state: callerSaidGoodbye: { type: boolean, default: false, writer: extractor } @@ -199,9 +199,10 @@ public void AnInferredFlagWithADefault_NeverReachesTheCaller() agent: closer terminal: true """; - var document = ConfigurationLoader.LoadYaml(yaml); - StateDocument state = new(document); + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + StateDocument state = new(document); - Assert.Null(UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0])); - } - } + Assert.Null(UnfilledSlotReminder.Build(state, document.Entries["main"].Policy!.Stages[0])); + } + } +} diff --git a/tests/AgentCore.Application.Tests/Tools/BindingToolTests.cs b/tests/AgentCore.Application.Tests/Tools/BindingToolTests.cs index f7becd11..ee56e43a 100644 --- a/tests/AgentCore.Application.Tests/Tools/BindingToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/BindingToolTests.cs @@ -3,272 +3,275 @@ using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Tools; using AgentCore.Application.Tools.Binding; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// The third tool kind of section 8.1: kind: binding, which calls a host delegate. -/// -/// -/// The document writes binds: CreateCase and nothing else. The host registers the delegate -/// that name points at, so the tool crosses no port and reaches no vendor. -/// -public sealed class BindingToolTests +namespace AgentCore.Application.Tests.Tools { - private static readonly ToolConfiguration CreateCase = new() - { - Id = "create_case", - Kind = ToolKind.Binding, - Binds = "CreateCase", - Description = "Open a service case for a human agent.", - Parameters = JsonNode.Parse("""{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}"""), - }; - - private static readonly string[] Tags = ["belt", "motor"]; - - // --------------------------------------------------------------------------------------------- - // The registry. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TheRegistry_HoldsWhatTheHostRegisters() + /// + /// The third tool kind of section 8.1: kind: binding, which calls a host delegate. + /// + /// + /// The document writes binds: CreateCase and nothing else. The host registers the delegate + /// that name points at, so the tool crosses no port and reaches no vendor. + /// + public sealed class BindingToolTests { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); + private static readonly ToolConfiguration CreateCase = new() + { + Id = "create_case", + Kind = ToolKind.Binding, + Binds = "CreateCase", + Description = "Open a service case for a human agent.", + Parameters = JsonNode.Parse("""{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}"""), + }; + + private static readonly string[] Tags = ["belt", "motor"]; + + // --------------------------------------------------------------------------------------------- + // The registry. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TheRegistry_HoldsWhatTheHostRegisters() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); - Assert.Equal(1, registry.Count); - Assert.True(registry.Contains("CreateCase")); - Assert.False(registry.Contains("createcase")); - } + Assert.Equal(1, registry.Count); + Assert.True(registry.Contains("CreateCase")); + Assert.False(registry.Contains("createcase")); + } - [Fact] - public void TheSameNameTwice_FailsAtStartup() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); + [Fact] + public void TheSameNameTwice_FailsAtStartup() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); - Assert.Throws( - () => registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null))); - } + _ = Assert.Throws( + () => registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null))); + } - // --------------------------------------------------------------------------------------------- - // Calling. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheToolCallsTheDelegateTheHostRegistered() - { - JsonObject? seen = null; - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => + // --------------------------------------------------------------------------------------------- + // Calling. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheToolCallsTheDelegateTheHostRegistered() { - seen = arguments; - return ValueTask.FromResult(JsonNode.Parse("""{"caseId":"C-1"}""")); - }); - - var result = await CallAsync(await CreateAsync(registry, CreateCase), ("summary", "broken belt")); + JsonObject? seen = null; + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => + { + seen = arguments; + return ValueTask.FromResult(JsonNode.Parse("""{"caseId":"C-1"}""")); + }); + + object? result = await CallAsync(await CreateAsync(registry, CreateCase), ("summary", "broken belt")); + + Assert.NotNull(seen); + Assert.Equal("broken belt", seen["summary"]!.GetValue()); + Assert.Equal("C-1", Assert.IsType(result)["caseId"]!.GetValue()); + } - Assert.NotNull(seen); - Assert.Equal("broken belt", seen["summary"]!.GetValue()); - Assert.Equal("C-1", Assert.IsType(result)["caseId"]!.GetValue()); - } + [Fact] + public async Task EachArgumentTypeTheSwitchNames_ArrivesAsThatJsonType() + { + JsonObject? seen = null; + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => + { + seen = arguments; + return ValueTask.FromResult(null); + }); + + _ = await CallAsync( + await CreateAsync(registry, CreateCase), + ("summary", "broken belt"), + ("node", JsonNode.Parse("""{"a":1}""")), + ("element", JsonDocument.Parse("""[1,2]""").RootElement), + ("flag", true), + ("count", 7), + ("ticks", 9_000_000_000L), + ("ratio", 1.5d), + ("money", 2.25m), + ("nothing", null)); + + Assert.NotNull(seen); + Assert.Equal("broken belt", seen["summary"]!.GetValue()); + Assert.Equal(/*lang=json,strict*/ """{"a":1}""", seen["node"]!.ToJsonString()); + Assert.Equal("[1,2]", seen["element"]!.ToJsonString()); + Assert.True(seen["flag"]!.GetValue()); + Assert.Equal(7, seen["count"]!.GetValue()); + Assert.Equal(9_000_000_000L, seen["ticks"]!.GetValue()); + Assert.Equal(1.5d, seen["ratio"]!.GetValue()); + Assert.Equal(2.25m, seen["money"]!.GetValue()); + Assert.Null(seen["nothing"]); + } - [Fact] - public async Task EachArgumentTypeTheSwitchNames_ArrivesAsThatJsonType() - { - JsonObject? seen = null; - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => + // --------------------------------------------------------------------------------------------- + // The fallback arm. A type the switch does not name is carried as the text of ToString(), and + // not serialized. Any replacement for the switch has to keep answering this way. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AnArgumentTypeTheSwitchDoesNotName_ArrivesAsItsToStringText() { - seen = arguments; - return ValueTask.FromResult(null); - }); - - await CallAsync( - await CreateAsync(registry, CreateCase), - ("summary", "broken belt"), - ("node", JsonNode.Parse("""{"a":1}""")), - ("element", JsonDocument.Parse("""[1,2]""").RootElement), - ("flag", true), - ("count", 7), - ("ticks", 9_000_000_000L), - ("ratio", 1.5d), - ("money", 2.25m), - ("nothing", null)); - - Assert.NotNull(seen); - Assert.Equal("broken belt", seen["summary"]!.GetValue()); - Assert.Equal("""{"a":1}""", seen["node"]!.ToJsonString()); - Assert.Equal("[1,2]", seen["element"]!.ToJsonString()); - Assert.True(seen["flag"]!.GetValue()); - Assert.Equal(7, seen["count"]!.GetValue()); - Assert.Equal(9_000_000_000L, seen["ticks"]!.GetValue()); - Assert.Equal(1.5d, seen["ratio"]!.GetValue()); - Assert.Equal(2.25m, seen["money"]!.GetValue()); - Assert.Null(seen["nothing"]); - } + JsonObject? seen = null; + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => + { + seen = arguments; + return ValueTask.FromResult(null); + }); + + _ = await CallAsync( + await CreateAsync(registry, CreateCase), + ("tags", Tags), + ("id", Guid.Parse("2f1b7d64-0f4a-4f0a-9c1c-2b0b6a2b7c11")), + ("ratio", 1.5f)); + + Assert.NotNull(seen); + Assert.Equal("System.String[]", seen["tags"]!.GetValue()); + Assert.Equal("2f1b7d64-0f4a-4f0a-9c1c-2b0b6a2b7c11", seen["id"]!.GetValue()); + Assert.Equal(JsonValueKind.String, seen["ratio"]!.GetValueKind()); + } - // --------------------------------------------------------------------------------------------- - // The fallback arm. A type the switch does not name is carried as the text of ToString(), and - // not serialized. Any replacement for the switch has to keep answering this way. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AnArgumentTypeTheSwitchDoesNotName_ArrivesAsItsToStringText() - { - JsonObject? seen = null; - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => + [Fact] + public async Task TheDeclaredSchema_ReachesTheModelUnchanged() { - seen = arguments; - return ValueTask.FromResult(null); - }); - - await CallAsync( - await CreateAsync(registry, CreateCase), - ("tags", Tags), - ("id", Guid.Parse("2f1b7d64-0f4a-4f0a-9c1c-2b0b6a2b7c11")), - ("ratio", 1.5f)); - - Assert.NotNull(seen); - Assert.Equal("System.String[]", seen["tags"]!.GetValue()); - Assert.Equal("2f1b7d64-0f4a-4f0a-9c1c-2b0b6a2b7c11", seen["id"]!.GetValue()); - Assert.Equal(JsonValueKind.String, seen["ratio"]!.GetValueKind()); - } + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); - [Fact] - public async Task TheDeclaredSchema_ReachesTheModelUnchanged() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); + AIFunction function = Assert.IsType(await CreateAsync(registry, CreateCase), exactMatch: false); - var function = Assert.IsType(await CreateAsync(registry, CreateCase), exactMatch: false); + Assert.Equal("create_case", function.Name); + Assert.Equal("Open a service case for a human agent.", function.Description); + Assert.True(JsonNode.DeepEquals(CreateCase.Parameters, JsonNode.Parse(function.JsonSchema.GetRawText()))); + } - Assert.Equal("create_case", function.Name); - Assert.Equal("Open a service case for a human agent.", function.Description); - Assert.True(JsonNode.DeepEquals(CreateCase.Parameters, JsonNode.Parse(function.JsonSchema.GetRawText()))); - } + // --------------------------------------------------------------------------------------------- + // Section 8.7: a tool returns an error result and does not throw. Task 7a moved the + // classification that makes that true off DeclaredTool and into + // AuditingFunctionInvokingChatClient, so calling the bare tool directly now sees the exception + // the host delegate threw. See AuditingFunctionInvokingChatClientErrorPolicyTests and + // ConversationSessionTests for the end-to-end guarantee. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AHostDelegateThatThrows_PropagatesForTheMiddlewareToClassify() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) + => throw new InvalidOperationException("the case system is down")); - // --------------------------------------------------------------------------------------------- - // Section 8.7: a tool returns an error result and does not throw. Task 7a moved the - // classification that makes that true off DeclaredTool and into - // AuditingFunctionInvokingChatClient, so calling the bare tool directly now sees the exception - // the host delegate threw. See AuditingFunctionInvokingChatClientErrorPolicyTests and - // ConversationSessionTests for the end-to-end guarantee. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AHostDelegateThatThrows_PropagatesForTheMiddlewareToClassify() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) - => throw new InvalidOperationException("the case system is down")); + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await CallAsync(await CreateAsync(registry, CreateCase), ("summary", "broken belt"))); - var thrown = await Assert.ThrowsAsync( - async () => await CallAsync(await CreateAsync(registry, CreateCase), ("summary", "broken belt"))); + Assert.Equal("the case system is down", thrown.Message); + } - Assert.Equal("the case system is down", thrown.Message); - } + [Fact] + public async Task AHostDelegateThatReturnsNothing_ReturnsAnEmptyResultAndNotAFailure() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); - [Fact] - public async Task AHostDelegateThatReturnsNothing_ReturnsAnEmptyResultAndNotAFailure() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (arguments, cancellationToken) => ValueTask.FromResult(null)); + object? result = await CallAsync(await CreateAsync(registry, CreateCase), ("summary", "broken belt")); - var result = await CallAsync(await CreateAsync(registry, CreateCase), ("summary", "broken belt")); + Assert.Null(result); + } - Assert.Null(result); - } + // --------------------------------------------------------------------------------------------- + // Failing at startup. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ABindsNameTheHostNeverRegistered_FailsAtStartup() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await CreateAsync(new ToolBindingRegistry(), CreateCase)); - // --------------------------------------------------------------------------------------------- - // Failing at startup. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ABindsNameTheHostNeverRegistered_FailsAtStartup() - { - var failure = await Assert.ThrowsAsync( - async () => await CreateAsync(new ToolBindingRegistry(), CreateCase)); + Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Check); + Assert.Contains("CreateCase", failure.Message, StringComparison.Ordinal); + } - Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Check); - Assert.Contains("CreateCase", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task TheBindingSource_ServesNoOtherKind() + { + ToolBindingRegistry registry = new(); - [Fact] - public async Task TheBindingSource_ServesNoOtherKind() - { - ToolBindingRegistry registry = new(); + Assert.Null(await CreateAsync(registry, new ToolConfiguration { Id = "s", Kind = ToolKind.Builtin, Uses = "knowledge.read" })); + Assert.Null(await CreateAsync(registry, new ToolConfiguration { Id = "i", Kind = ToolKind.Agent, Agent = "a" })); + } - Assert.Null(await CreateAsync(registry, new ToolConfiguration { Id = "s", Kind = ToolKind.Builtin, Uses = "knowledge.read" })); - Assert.Null(await CreateAsync(registry, new ToolConfiguration { Id = "i", Kind = ToolKind.Agent, Agent = "a" })); - } + private static async Task CallAsync(AITool? tool, params (string Name, object? Value)[] arguments) + { + AIFunction function = Assert.IsType(tool, exactMatch: false); - private static async Task CallAsync(AITool? tool, params (string Name, object? Value)[] arguments) - { - var function = Assert.IsType(tool, exactMatch: false); + Dictionary values = new(StringComparer.Ordinal); + foreach ((string Name, object? Value) in arguments) + { + values[Name] = Value; + } - Dictionary values = new(StringComparer.Ordinal); - foreach (var argument in arguments) - { - values[argument.Name] = argument.Value; + return await function.InvokeAsync(new AIFunctionArguments(values), TestContext.Current.CancellationToken); } - return await function.InvokeAsync(new AIFunctionArguments(values), TestContext.Current.CancellationToken); - } - - private static async Task CreateAsync(ToolBindingRegistry registry, ToolConfiguration tool) - { - BindingToolSource source = new(registry); - var context = new ToolSourceContext(new AgentCoreConfiguration + private static async Task CreateAsync(ToolBindingRegistry registry, ToolConfiguration tool) { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Tools = [tool], - }); - - var registrations = await source.ProvideAsync(context, TestContext.Current.CancellationToken); - return registrations.Count == 0 ? null : registrations[0].Materialise(); - } + BindingToolSource source = new(registry); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [tool], + }); + + IReadOnlyList registrations = await source.ProvideAsync(context, TestContext.Current.CancellationToken); + return registrations.Count == 0 ? null : registrations[0].Materialise(); + } - [Fact] - public async Task AnUnregisteredBindsName_FailsTheBoot() - { - ToolBindingRegistry bindings = new(); - BindingToolSource source = new(bindings); - var context = new ToolSourceContext(new AgentCoreConfiguration + [Fact] + public async Task AnUnregisteredBindsName_FailsTheBoot() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Tools = [new ToolConfiguration { Id = "open_case", Kind = ToolKind.Binding, Binds = "CreateCase" }], - }); - - var failure = await Assert.ThrowsAsync(async () => - await source.ProvideAsync(context, TestContext.Current.CancellationToken)); - - Assert.Contains("CreateCase", failure.Message, StringComparison.Ordinal); - } + ToolBindingRegistry bindings = new(); + BindingToolSource source = new(bindings); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [new ToolConfiguration { Id = "open_case", Kind = ToolKind.Binding, Binds = "CreateCase" }], + }); + + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await source.ProvideAsync(context, TestContext.Current.CancellationToken)); + + Assert.Contains("CreateCase", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task ARegisteredBinding_BecomesOneRegistration() - { - ToolBindingRegistry bindings = new(); - bindings.Register("CreateCase", (_, _) => ValueTask.FromResult("done")); - BindingToolSource source = new(bindings); - var context = new ToolSourceContext(new AgentCoreConfiguration + [Fact] + public async Task ARegisteredBinding_BecomesOneRegistration() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Tools = - [ - new ToolConfiguration - { - Id = "open_case", Kind = ToolKind.Binding, Binds = "CreateCase", Description = "Open a case.", - }, - ], - }); - - var registrations = await source.ProvideAsync(context, TestContext.Current.CancellationToken); - - Assert.Equal("open_case", Assert.Single(registrations).Id); + ToolBindingRegistry bindings = new(); + _ = bindings.Register("CreateCase", (_, _) => ValueTask.FromResult("done")); + BindingToolSource source = new(bindings); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = + [ + new ToolConfiguration + { + Id = "open_case", Kind = ToolKind.Binding, Binds = "CreateCase", Description = "Open a case.", + }, + ], + }); + + IReadOnlyList registrations = await source.ProvideAsync(context, TestContext.Current.CancellationToken); + + Assert.Equal("open_case", Assert.Single(registrations).Id); + } } } diff --git a/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs b/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs index 923958bd..d83fb064 100644 --- a/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs @@ -3,104 +3,109 @@ using AgentCore.Application.Tests.Configuration; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tools.Registry; -using AgentCore.Application.Tools; using AgentCore.Application.Tools.Builtin; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// The first tool kind of section 8.1: kind: builtin, which AgentCore ships. -/// -/// -/// The shipped example holds two built-ins: web.search, a marker that builds one -/// HostedWebSearchTool and runs no code of its own — see HostedWebSearchDropTests for -/// what reaches a compiled agent — and file.publish, a plain function whose conversation path is -/// covered in FilePublishToolDefinitionTests. -/// -public sealed class BuiltinToolTests +namespace AgentCore.Application.Tests.Tools { - // --------------------------------------------------------------------------------------------- - // Binding the name. - // --------------------------------------------------------------------------------------------- - [Fact] - public void TheWorkedExample_BindsEveryBuiltInName() + /// + /// The first tool kind of section 8.1: kind: builtin, which AgentCore ships. + /// + /// + /// The shipped example holds two built-ins: web.search, a marker that builds one + /// HostedWebSearchTool and runs no code of its own — see HostedWebSearchDropTests for + /// what reaches a compiled agent — and file.publish, a plain function whose conversation path is + /// covered in FilePublishToolDefinitionTests. + /// + public sealed class BuiltinToolTests { - var document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); - var factory = Factory(); - - foreach (var tool in document.Tools.Where(tool => tool.Kind == ToolKind.Builtin)) + // --------------------------------------------------------------------------------------------- + // Binding the name. + // --------------------------------------------------------------------------------------------- + [Fact] + public void TheWorkedExample_BindsEveryBuiltInName() { - Assert.NotNull(factory.Create(tool)); - } - } + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + BuiltinFactory factory = Factory(); - [Fact] - public void AUsesNameNobodyShips_FailsAtStartup() - { - var tool = new ToolConfiguration { Id = "x", Kind = ToolKind.Builtin, Uses = "knowledge.summarise" }; + foreach (ToolConfiguration? tool in document.Tools.Where(tool => tool.Kind == ToolKind.Builtin)) + { + Assert.NotNull(factory.Create(tool)); + } + } - var failure = Assert.Throws(() => Factory().Create(tool)); + [Fact] + public void AUsesNameNobodyShips_FailsAtStartup() + { + ToolConfiguration tool = new() { Id = "x", Kind = ToolKind.Builtin, Uses = "knowledge.summarise" }; - Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Check); - Assert.Contains("knowledge.summarise", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = Assert.Throws(() => Factory().Create(tool)); - [Fact] - public void TheBuiltinFactory_ServesNoOtherKind() - { - Assert.Null(Factory().Create(new ToolConfiguration { Id = "other", Kind = ToolKind.Binding, Binds = "X" })); - Assert.Null(Factory().Create(new ToolConfiguration { Id = "inner", Kind = ToolKind.Agent, Agent = "a" })); - } + Assert.Equal(ConfigurationCheck.ReferenceResolution, failure.Check); + Assert.Contains("knowledge.summarise", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task AUsesNameAgentCoreDoesNotShip_FailsTheBoot() - { - BuiltinToolSource source = new(new BuiltinToolPorts(null)); - var context = new ToolSourceContext(new AgentCoreConfiguration + [Fact] + public void TheBuiltinFactory_ServesNoOtherKind() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Tools = [new ToolConfiguration { Id = "x", Kind = ToolKind.Builtin, Uses = "knowledge.invent" }], - }); + Assert.Null(Factory().Create(new ToolConfiguration { Id = "other", Kind = ToolKind.Binding, Binds = "X" })); + Assert.Null(Factory().Create(new ToolConfiguration { Id = "inner", Kind = ToolKind.Agent, Agent = "a" })); + } - var failure = await Assert.ThrowsAsync(async () => - await source.ProvideAsync(context, TestContext.Current.CancellationToken)); + [Fact] + public async Task AUsesNameAgentCoreDoesNotShip_FailsTheBoot() + { + BuiltinToolSource source = new(new BuiltinToolPorts(null)); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [new ToolConfiguration { Id = "x", Kind = ToolKind.Builtin, Uses = "knowledge.invent" }], + }); - Assert.Contains("knowledge.invent", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await source.ProvideAsync(context, TestContext.Current.CancellationToken)); - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private static BuiltinFactory Factory() => new(); + Assert.Contains("knowledge.invent", failure.Message, StringComparison.Ordinal); + } - /// Builds one declared tool through , synchronously. - private sealed class BuiltinFactory - { - private readonly BuiltinToolSource _source = new(new BuiltinToolPorts( - new RecordingChatClientFactory(), - new RecordingBlobStore(), - WorkspaceRoot: Path.Combine(Path.GetTempPath(), "agentcore-builtin-tests"))); + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private static BuiltinFactory Factory() + { + return new(); + } - public AITool? Create(ToolConfiguration tool) + /// Builds one declared tool through , synchronously. + private sealed class BuiltinFactory { - if (tool.Kind != ToolKind.Builtin) - { - return null; - } + private readonly BuiltinToolSource _source = new(new BuiltinToolPorts( + new RecordingChatClientFactory(), + new RecordingBlobStore(), + WorkspaceRoot: Path.Combine(Path.GetTempPath(), "agentcore-builtin-tests"))); - var context = new ToolSourceContext(new AgentCoreConfiguration + public AITool? Create(ToolConfiguration tool) { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), - Tools = [tool], - }); + if (tool.Kind != ToolKind.Builtin) + { + return null; + } + + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [tool], + }); - var registrations = _source.ProvideAsync(context).AsTask().GetAwaiter().GetResult(); - return Assert.Single(registrations).Materialise(); + IReadOnlyList registrations = _source.ProvideAsync(context).AsTask().GetAwaiter().GetResult(); + return Assert.Single(registrations).Materialise(); + } } } } diff --git a/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs b/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs index c34089d6..ea5022fd 100644 --- a/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/CachedToolTests.cs @@ -1,4 +1,3 @@ -using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Tools; @@ -8,185 +7,194 @@ using Microsoft.Extensions.DependencyInjection; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// cacheSeconds: on a tool. A repeat of the same arguments must not reach the tool again; -/// different arguments must; a failure must never be served twice. -/// -public sealed class CachedToolTests +namespace AgentCore.Application.Tests.Tools { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - private static HybridCache NewCache() - { - ServiceCollection services = new(); - services.AddHybridCache(); - return services.BuildServiceProvider().GetRequiredService(); - } - - [Fact] - public async Task ARepeatOfTheSameArguments_SkipsTheTool_AndReadsTheSameAnswer() - { - CountingTool counter = new(); - CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); - - var first = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - var second = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - - Assert.Equal(1, counter.Calls); - Assert.Equal(ToolResultJson.ToNode(first)!.ToJsonString(), ToolResultJson.ToNode(second)!.ToJsonString()); - } - - [Fact] - public async Task DifferentArguments_ReachTheTool() - { - CountingTool counter = new(); - CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); - - await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "B2" }, Token); - - Assert.Equal(2, counter.Calls); - } - - [Fact] - public async Task TheOrderTheModelWroteTheArgumentsIn_DoesNotChangeTheKey() + /// + /// cacheSeconds: on a tool. A repeat of the same arguments must not reach the tool again; + /// different arguments must; a failure must never be served twice. + /// + public sealed class CachedToolTests { - CountingTool counter = new(); - CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); - - await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1", ["region"] = "us" }, Token); - await tool.InvokeAsync(new AIFunctionArguments { ["region"] = "us", ["order"] = "A1" }, Token); - - Assert.Equal(1, counter.Calls); - } - - [Fact] - public async Task TheSideChannel_IsNotPartOfTheKey() - { - CountingTool counter = new(); - CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); - - await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - await tool.InvokeAsync( - WithContext(new AIFunctionArguments { ["order"] = "A1" }, new Dictionary { ["turn"] = 2 }), - Token); - - Assert.Equal(1, counter.Calls); - } - - [Fact] - public async Task AFailure_IsNotServedTwice() - { - var calls = 0; - var flaky = AIFunctionFactory.Create( - (string order) => ++calls == 1 ? ToolErrorResult.Create("lookup", "down") : new JsonObject { ["status"] = "shipped" }, - "lookup", - "Looks up an order."); - CachedTool tool = new(flaky, NewCache(), TimeSpan.FromMinutes(5)); - - var first = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - var second = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - - Assert.True(ToolErrorResult.IsError(ToolResultJson.ToNode(first))); - Assert.Equal("shipped", ToolResultJson.ToNode(second)!["status"]!.GetValue()); - Assert.Equal(2, calls); - } - - [Fact] - public void TheWrapperShowsTheSameToolToTheModel() - { - CountingTool counter = new(); - CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromSeconds(1)); - - Assert.Equal(counter.Function.Name, tool.Name); - Assert.Equal(counter.Function.Description, tool.Description); - Assert.Equal(counter.Function.JsonSchema.GetRawText(), tool.JsonSchema.GetRawText()); - } - - [Fact] - public void ALifetimeOfNothing_IsRefused() - => Assert.Throws( - () => new CachedTool(new CountingTool().Function, NewCache(), TimeSpan.Zero)); - - // --------------------------------------------------------------------------------------------- - // The registry is what applies the cache, from the declaration and the host's cache. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ADeclarationWithCacheSeconds_ResolvesToACachedTool() - { - CountingTool counter = new(); - var registry = await ToolRegistryBuilder.BuildAsync( - [new StubSource(new ToolRegistration("lookup", "d", () => counter.Function))], - new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup", CacheSeconds = 60 })) { Cache = NewCache() }, - Token); - - var tool = Assert.IsType(registry.Resolve("lookup")); - await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); - - Assert.Equal(1, counter.Calls); - } - - [Fact] - public async Task ADeclarationWithCacheSeconds_ButAHostWithNoCache_ResolvesToTheToolItself() - { - var inner = new CountingTool().Function; - var registry = await ToolRegistryBuilder.BuildAsync( - [new StubSource(new ToolRegistration("lookup", "d", () => inner))], - new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup", CacheSeconds = 60 })), - Token); - - Assert.Same(inner, registry.Resolve("lookup")); - } - - [Fact] - public async Task ADeclarationWithNoCacheSeconds_ResolvesToTheToolItself() - { - var inner = new CountingTool().Function; - var registry = await ToolRegistryBuilder.BuildAsync( - [new StubSource(new ToolRegistration("lookup", "d", () => inner))], - new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup" })) { Cache = NewCache() }, - Token); - - Assert.Same(inner, registry.Resolve("lookup")); - } - - private static AIFunctionArguments WithContext(AIFunctionArguments arguments, IDictionary context) - { - arguments.Context = context; - return arguments; - } - - /// A tool that answers with the arguments it saw, and counts how often it ran. - private sealed class CountingTool - { - public int Calls { get; private set; } - - public AIFunction Function { get; } - - public CountingTool() - => Function = AIFunctionFactory.Create( - (string order, string? region = null) => - { - Calls++; - return new JsonObject { ["order"] = order, ["region"] = region, ["call"] = Calls }; - }, + private static CancellationToken Token => TestContext.Current.CancellationToken; + + private static HybridCache NewCache() + { + ServiceCollection services = new(); + _ = services.AddHybridCache(); + return services.BuildServiceProvider().GetRequiredService(); + } + + [Fact] + public async Task ARepeatOfTheSameArguments_SkipsTheTool_AndReadsTheSameAnswer() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + object? first = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + object? second = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + + Assert.Equal(1, counter.Calls); + Assert.Equal(ToolResultJson.ToNode(first)!.ToJsonString(), ToolResultJson.ToNode(second)!.ToJsonString()); + } + + [Fact] + public async Task DifferentArguments_ReachTheTool() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + _ = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + _ = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "B2" }, Token); + + Assert.Equal(2, counter.Calls); + } + + [Fact] + public async Task TheOrderTheModelWroteTheArgumentsIn_DoesNotChangeTheKey() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + _ = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1", ["region"] = "us" }, Token); + _ = await tool.InvokeAsync(new AIFunctionArguments { ["region"] = "us", ["order"] = "A1" }, Token); + + Assert.Equal(1, counter.Calls); + } + + [Fact] + public async Task TheSideChannel_IsNotPartOfTheKey() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromMinutes(5)); + + _ = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + _ = await tool.InvokeAsync( + WithContext(new AIFunctionArguments { ["order"] = "A1" }, new Dictionary { ["turn"] = 2 }), + Token); + + Assert.Equal(1, counter.Calls); + } + + [Fact] + public async Task AFailure_IsNotServedTwice() + { + int calls = 0; + AIFunction flaky = AIFunctionFactory.Create( + (string order) => ++calls == 1 ? ToolErrorResult.Create("lookup", "down") : new JsonObject { ["status"] = "shipped" }, "lookup", "Looks up an order."); - } - - private sealed class StubSource(params ToolRegistration[] registrations) : Application.Ports.IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>(registrations); - } - - private static class Documents - { - public static AgentCoreConfiguration With(params ToolConfiguration[] tools) - => new() { ApiVersion = "agentcore/v1", Tools = tools, Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary() }; + CachedTool tool = new(flaky, NewCache(), TimeSpan.FromMinutes(5)); + + object? first = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + object? second = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + + Assert.True(ToolErrorResult.IsError(ToolResultJson.ToNode(first))); + Assert.Equal("shipped", ToolResultJson.ToNode(second)!["status"]!.GetValue()); + Assert.Equal(2, calls); + } + + [Fact] + public void TheWrapperShowsTheSameToolToTheModel() + { + CountingTool counter = new(); + CachedTool tool = new(counter.Function, NewCache(), TimeSpan.FromSeconds(1)); + + Assert.Equal(counter.Function.Name, tool.Name); + Assert.Equal(counter.Function.Description, tool.Description); + Assert.Equal(counter.Function.JsonSchema.GetRawText(), tool.JsonSchema.GetRawText()); + } + + [Fact] + public void ALifetimeOfNothing_IsRefused() + { + _ = Assert.Throws( + () => new CachedTool(new CountingTool().Function, NewCache(), TimeSpan.Zero)); + } + + // --------------------------------------------------------------------------------------------- + // The registry is what applies the cache, from the declaration and the host's cache. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ADeclarationWithCacheSeconds_ResolvesToACachedTool() + { + CountingTool counter = new(); + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("lookup", "d", () => counter.Function))], + new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup", CacheSeconds = 60 })) { Cache = NewCache() }, + Token); + + CachedTool tool = Assert.IsType(registry.Resolve("lookup")); + _ = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + _ = await tool.InvokeAsync(new AIFunctionArguments { ["order"] = "A1" }, Token); + + Assert.Equal(1, counter.Calls); + } + + [Fact] + public async Task ADeclarationWithCacheSeconds_ButAHostWithNoCache_ResolvesToTheToolItself() + { + AIFunction inner = new CountingTool().Function; + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("lookup", "d", () => inner))], + new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup", CacheSeconds = 60 })), + Token); + + Assert.Same(inner, registry.Resolve("lookup")); + } + + [Fact] + public async Task ADeclarationWithNoCacheSeconds_ResolvesToTheToolItself() + { + AIFunction inner = new CountingTool().Function; + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("lookup", "d", () => inner))], + new ToolSourceContext(Documents.With(new ToolConfiguration { Id = "lookup", Kind = ToolKind.Binding, Binds = "host.lookup" })) { Cache = NewCache() }, + Token); + + Assert.Same(inner, registry.Resolve("lookup")); + } + + private static AIFunctionArguments WithContext(AIFunctionArguments arguments, IDictionary context) + { + arguments.Context = context; + return arguments; + } + + /// A tool that answers with the arguments it saw, and counts how often it ran. + private sealed class CountingTool + { + public int Calls { get; private set; } + + public AIFunction Function { get; } + + public CountingTool() + { + Function = AIFunctionFactory.Create( + (string order, string? region = null) => + { + Calls++; + return new JsonObject { ["order"] = order, ["region"] = region, ["call"] = Calls }; + }, + "lookup", + "Looks up an order."); + } + } + + private sealed class StubSource(params ToolRegistration[] registrations) : Application.Ports.IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>(registrations); + } + } + + private static class Documents + { + public static AgentCoreConfiguration With(params ToolConfiguration[] tools) + { + return new() { ApiVersion = "agentcore/v1", Tools = tools, Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary() }; + } + } } } diff --git a/tests/AgentCore.Application.Tests/Tools/DeclaredToolTests.cs b/tests/AgentCore.Application.Tests/Tools/DeclaredToolTests.cs index 6e8d8105..4d5a29d3 100644 --- a/tests/AgentCore.Application.Tests/Tools/DeclaredToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/DeclaredToolTests.cs @@ -4,138 +4,141 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// no longer applies an error policy at all: it runs -/// and returns or throws exactly what that returned or threw. -/// -/// -/// -/// Task 7a moved the split between a fault the model can answer and a fault beyond it out of this -/// base class and into AuditingFunctionInvokingChatClient.InvokeFunctionAsync, the framework's -/// single choke point for every tool call — see -/// AgentCore.Application.Tests.Runtime.AuditingFunctionInvokingChatClientErrorPolicyTests for -/// the classification itself and the behaviour it pins. -/// -/// -/// What these tests pin instead is narrower and still real: a body may -/// still answer a fault itself by returning directly without throwing — -/// a builtin tool definition does exactly that for an argument it already validated — and everything -/// this base class does NOT catch keeps its original stack, cancellation included, all the way out to -/// whatever calls . -/// -/// -public sealed class DeclaredToolTests +namespace AgentCore.Application.Tests.Tools { - private static readonly ToolConfiguration LookupOrder = new() - { - Id = "lookup_order", - Kind = ToolKind.Binding, - Binds = "LookupOrder", - Description = "Read one order by its identifier.", - }; - /// - /// A representative fault of each kind the old split once told apart. Both propagate identically - /// now, because no longer classifies anything. + /// no longer applies an error policy at all: it runs + /// and returns or throws exactly what that returned or threw. /// - public static TheoryData RepresentativeFaults => - [ - new InvalidOperationException("the order is already closed."), - new ArgumentException("orderId is not a number."), - new FormatException("the date is not a date."), - new KeyNotFoundException("no such order."), - new NotSupportedException("this endpoint does not take a range."), - new HttpRequestException("no such host"), - new SocketException(), - new IOException("the disk went away."), - new TimeoutException("the endpoint did not answer."), - new UnauthorizedAccessException("the token was rejected."), - new TaskCanceledException("The request timed out.", new TimeoutException()), - ]; - - [Theory] - [MemberData(nameof(RepresentativeFaults), DisableDiscoveryEnumeration = true)] - public async Task AnyFaultTheBodyThrows_PropagatesUnfiltered(Exception failure) - { - var thrown = await Assert.ThrowsAnyAsync( - async () => await new ThrowingTool(failure).InvokeAsync( - [], - TestContext.Current.CancellationToken)); - - // The very exception, and not a copy: InvokeCoreAsync no longer catches, so this is a plain - // await of CallAsync and nothing rewraps the fault. Whether the model could have answered it - // is now decided one layer up, by AuditingFunctionInvokingChatClient. - Assert.Same(failure, thrown); - } - - [Fact] - public async Task ACallerThatHungUp_StillPassesTheCancellationThrough() + /// + /// + /// Task 7a moved the split between a fault the model can answer and a fault beyond it out of this + /// base class and into AuditingFunctionInvokingChatClient.InvokeFunctionAsync, the framework's + /// single choke point for every tool call — see + /// AgentCore.Application.Tests.Runtime.AuditingFunctionInvokingChatClientErrorPolicyTests for + /// the classification itself and the behaviour it pins. + /// + /// + /// What these tests pin instead is narrower and still real: a body may + /// still answer a fault itself by returning directly without throwing — + /// a builtin tool definition does exactly that for an argument it already validated — and everything + /// this base class does NOT catch keeps its original stack, cancellation included, all the way out to + /// whatever calls . + /// + /// + public sealed class DeclaredToolTests { - using CancellationTokenSource source = new(); - await source.CancelAsync(); + private static readonly ToolConfiguration LookupOrder = new() + { + Id = "lookup_order", + Kind = ToolKind.Binding, + Binds = "LookupOrder", + Description = "Read one order by its identifier.", + }; + + /// + /// A representative fault of each kind the old split once told apart. Both propagate identically + /// now, because no longer classifies anything. + /// + public static TheoryData RepresentativeFaults => + [ + new InvalidOperationException("the order is already closed."), + new ArgumentException("orderId is not a number."), + new FormatException("the date is not a date."), + new KeyNotFoundException("no such order."), + new NotSupportedException("this endpoint does not take a range."), + new HttpRequestException("no such host"), + new SocketException(), + new IOException("the disk went away."), + new TimeoutException("the endpoint did not answer."), + new UnauthorizedAccessException("the token was rejected."), + new TaskCanceledException("The request timed out.", new TimeoutException()), + ]; + + [Theory] + [MemberData(nameof(RepresentativeFaults), DisableDiscoveryEnumeration = true)] + public async Task AnyFaultTheBodyThrows_PropagatesUnfiltered(Exception failure) + { + Exception thrown = await Assert.ThrowsAnyAsync( + async () => await new ThrowingTool(failure).InvokeAsync( + [], + TestContext.Current.CancellationToken)); + + // The very exception, and not a copy: InvokeCoreAsync no longer catches, so this is a plain + // await of CallAsync and nothing rewraps the fault. Whether the model could have answered it + // is now decided one layer up, by AuditingFunctionInvokingChatClient. + Assert.Same(failure, thrown); + } - // Nobody reads this result, and swallowing it would keep a dead conversation running. - await Assert.ThrowsAnyAsync( - async () => await new ThrowingTool(new OperationCanceledException()).InvokeAsync( - [], - source.Token)); - } + [Fact] + public async Task ACallerThatHungUp_StillPassesTheCancellationThrough() + { + using CancellationTokenSource source = new(); + await source.CancelAsync(); + + // Nobody reads this result, and swallowing it would keep a dead conversation running. + _ = await Assert.ThrowsAnyAsync( + async () => await new ThrowingTool(new OperationCanceledException()).InvokeAsync( + [], + source.Token)); + } - [Fact] - public async Task ATimeoutThatIsNotTheCallersCancellation_IsRethrownAndNotSwallowed() - { - // HttpClient reports its own deadline as a TaskCanceledException with a TimeoutException - // inside it, on a token the caller never cancelled. It reads like a cancellation and it is a - // dead endpoint. Nothing here tests the token any more, but the result is the same: it is - // never swallowed. - TaskCanceledException timeout = new("The request timed out.", new TimeoutException()); + [Fact] + public async Task ATimeoutThatIsNotTheCallersCancellation_IsRethrownAndNotSwallowed() + { + // HttpClient reports its own deadline as a TaskCanceledException with a TimeoutException + // inside it, on a token the caller never cancelled. It reads like a cancellation and it is a + // dead endpoint. Nothing here tests the token any more, but the result is the same: it is + // never swallowed. + TaskCanceledException timeout = new("The request timed out.", new TimeoutException()); + + Exception thrown = await Assert.ThrowsAnyAsync( + async () => await new ThrowingTool(timeout).InvokeAsync( + [], + TestContext.Current.CancellationToken)); + + Assert.Same(timeout, thrown); + } - var thrown = await Assert.ThrowsAnyAsync( - async () => await new ThrowingTool(timeout).InvokeAsync( + [Fact] + public async Task ABodyThatAnswersItself_StillReturnsTheErrorResultDirectly() + { + // The one half of the old rule that still lives here: a tool body may choose to answer a + // fault itself, without throwing at all, exactly as a builtin tool definition does today. + object? result = await new SelfAnsweringTool().InvokeAsync( [], - TestContext.Current.CancellationToken)); - - Assert.Same(timeout, thrown); - } - - [Fact] - public async Task ABodyThatAnswersItself_StillReturnsTheErrorResultDirectly() - { - // The one half of the old rule that still lives here: a tool body may choose to answer a - // fault itself, without throwing at all, exactly as a builtin tool definition does today. - var result = await new SelfAnsweringTool().InvokeAsync( - [], - TestContext.Current.CancellationToken); - - Assert.True(ToolErrorResult.IsError(result as System.Text.Json.Nodes.JsonNode)); - } + TestContext.Current.CancellationToken); - /// A tool whose body throws whatever the test hands it. - private sealed class ThrowingTool : DeclaredTool - { - private readonly Exception _failure; - - public ThrowingTool(Exception failure) - : base(LookupOrder) => _failure = failure; - - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) => throw _failure; - } + Assert.True(ToolErrorResult.IsError(result as System.Text.Json.Nodes.JsonNode)); + } - /// A tool whose body returns its own error result rather than throwing. - private sealed class SelfAnsweringTool : DeclaredTool - { - public SelfAnsweringTool() - : base(LookupOrder) + /// A tool whose body throws whatever the test hands it. + private sealed class ThrowingTool(Exception failure) : DeclaredTool(LookupOrder) { + private readonly Exception _failure = failure; + + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + throw _failure; + } } - protected override ValueTask CallAsync( - AIFunctionArguments arguments, - CancellationToken cancellationToken) - => ValueTask.FromResult(Failed("the order is already closed.")); + /// A tool whose body returns its own error result rather than throwing. + private sealed class SelfAnsweringTool : DeclaredTool + { + public SelfAnsweringTool() + : base(LookupOrder) + { + } + + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + { + return ValueTask.FromResult(Failed("the order is already closed.")); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Tools/FilePublishBackgroundChildTests.cs b/tests/AgentCore.Application.Tests/Tools/FilePublishBackgroundChildTests.cs index b2b8673a..ffaaddf8 100644 --- a/tests/AgentCore.Application.Tests/Tools/FilePublishBackgroundChildTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/FilePublishBackgroundChildTests.cs @@ -8,67 +8,74 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// A background child runs with no turn, so file.publish finds the owning conversation on the stamp -/// its session carries and stores the file under the parent conversation. -/// -/// -/// The child session is created inside the parent's run, the way BackgroundAgentsProvider -/// creates it, so stamps it. The child then runs on that session -/// with null run options, which is what the provider passes it. -/// -public sealed class FilePublishBackgroundChildTests : IDisposable +namespace AgentCore.Application.Tests.Tools { - private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-publish-child-" + Guid.NewGuid().ToString("N")); - - public FilePublishBackgroundChildTests() => Directory.CreateDirectory(Path.Combine(_root, "conversation-9")); + /// + /// A background child runs with no turn, so file.publish finds the owning conversation on the stamp + /// its session carries and stores the file under the parent conversation. + /// + /// + /// The child session is created inside the parent's run, the way BackgroundAgentsProvider + /// creates it, so stamps it. The child then runs on that session + /// with null run options, which is what the provider passes it. + /// + public sealed class FilePublishBackgroundChildTests : IDisposable + { + private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-publish-child-" + Guid.NewGuid().ToString("N")); - public void Dispose() => Directory.Delete(_root, recursive: true); + public FilePublishBackgroundChildTests() + { + _ = Directory.CreateDirectory(Path.Combine(_root, "conversation-9")); + } - [Fact] - public async Task AChildThatPublishes_StoresTheFileUnderTheParentConversation() - { - // Arrange - var token = TestContext.Current.CancellationToken; - File.WriteAllText(Path.Combine(_root, "conversation-9", "rows.csv"), "a,b"); - RecordingBlobStore blobs = new(); + public void Dispose() + { + Directory.Delete(_root, recursive: true); + } - var publish = new FilePublishToolDefinition().Build( - new ToolConfiguration { Id = "publish", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.FilePublish }, - new BuiltinToolPorts(ChatClients: null, Blobs: blobs, WorkspaceRoot: _root)); + [Fact] + public async Task AChildThatPublishes_StoresTheFileUnderTheParentConversation() + { + // Arrange + CancellationToken token = TestContext.Current.CancellationToken; + File.WriteAllText(Path.Combine(_root, "conversation-9", "rows.csv"), "a,b"); + RecordingBlobStore blobs = new(); - ToolCallingChatClient childModel = new( - "published", - new Dictionary(StringComparer.Ordinal) { ["path"] = "rows.csv" }); + AITool publish = new FilePublishToolDefinition().Build( + new ToolConfiguration { Id = "publish", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.FilePublish }, + new BuiltinToolPorts(ChatClients: null, Blobs: blobs, WorkspaceRoot: _root)); - BackgroundChildAgent child = new(new ChatClientAgent(childModel, new ChatClientAgentOptions { ChatOptions = new ChatOptions { Tools = [publish] } })); - SessionCreatingProvider creating = new(child); - ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); - var turn = new TurnInvocation { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s", Workspace = Path.Combine(_root, "conversation-9") }; + ToolCallingChatClient childModel = new( + "published", + new Dictionary(StringComparer.Ordinal) { ["path"] = "rows.csv" }); - await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); + BackgroundChildAgent child = new(new ChatClientAgent(childModel, new ChatClientAgentOptions { ChatOptions = new ChatOptions { Tools = [publish] } })); + SessionCreatingProvider creating = new(child); + ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); + TurnInvocation turn = new() { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s", Workspace = Path.Combine(_root, "conversation-9") }; - // Act: the child runs on its stamped session with no run options, as the provider runs it. - await child.RunAsync("publish the rows", creating.Created!, options: null, token); + _ = await parent.RunAsync("go", await parent.CreateSessionAsync(token), turn.RunOptions(), token); - // Assert - Assert.Equal(["publish"], childModel.Called); - var result = Assert.Single(childModel.ToolResults); - Assert.Contains("https://blobs.test/conversation-9/rows.csv", result, StringComparison.Ordinal); - Assert.DoesNotContain(ToolErrorResult.ErrorProperty + "\":true", result, StringComparison.Ordinal); - Assert.Single(blobs.Blobs.Keys, key => key == ("conversation-9", "rows.csv")); - } + // Act: the child runs on its stamped session with no run options, as the provider runs it. + _ = await child.RunAsync("publish the rows", creating.Created!, options: null, token); - private sealed class SessionCreatingProvider(AIAgent child) : AIContextProvider - { - public AgentSession? Created { get; private set; } + // Assert + Assert.Equal(["publish"], childModel.Called); + string result = Assert.Single(childModel.ToolResults); + Assert.Contains("https://blobs.test/conversation-9/rows.csv", result, StringComparison.Ordinal); + Assert.DoesNotContain(ToolErrorResult.ErrorProperty + "\":true", result, StringComparison.Ordinal); + _ = Assert.Single(blobs.Blobs.Keys, key => key == ("conversation-9", "rows.csv")); + } - protected override async ValueTask InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default) + private sealed class SessionCreatingProvider(AIAgent child) : AIContextProvider { - Created = await child.CreateSessionAsync(cancellationToken); - return new AIContext(); + public AgentSession? Created { get; private set; } + + protected override async ValueTask InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default) + { + Created = await child.CreateSessionAsync(cancellationToken); + return new AIContext(); + } } } } diff --git a/tests/AgentCore.Application.Tests/Tools/FilePublishToolDefinitionTests.cs b/tests/AgentCore.Application.Tests/Tools/FilePublishToolDefinitionTests.cs index e225595e..e23f68b7 100644 --- a/tests/AgentCore.Application.Tests/Tools/FilePublishToolDefinitionTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/FilePublishToolDefinitionTests.cs @@ -12,191 +12,200 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// The uses: file.publish builtin: what it refuses, and what it stores, links, and files on -/// the turn when it accepts. -/// -public sealed class FilePublishToolDefinitionTests : IDisposable +namespace AgentCore.Application.Tests.Tools { - private static readonly ToolConfiguration Declared = - new() { Id = "publish", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.FilePublish, Description = "Publish a file." }; + /// + /// The uses: file.publish builtin: what it refuses, and what it stores, links, and files on + /// the turn when it accepts. + /// + public sealed class FilePublishToolDefinitionTests : IDisposable + { + private static readonly ToolConfiguration Declared = + new() { Id = "publish", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.FilePublish, Description = "Publish a file." }; - private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-publish-" + Guid.NewGuid().ToString("N")); + private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-publish-" + Guid.NewGuid().ToString("N")); - private readonly RecordingBlobStore _blobs = new(); + private readonly RecordingBlobStore _blobs = new(); - public FilePublishToolDefinitionTests() => Directory.CreateDirectory(Path.Combine(_root, "conversation-1")); + public FilePublishToolDefinitionTests() + { + _ = Directory.CreateDirectory(Path.Combine(_root, "conversation-1")); + } - public void Dispose() => Directory.Delete(_root, recursive: true); + public void Dispose() + { + Directory.Delete(_root, recursive: true); + } - [Fact] - public void Name_IsTheDocumentedUsesValue() - { - Assert.Equal("file.publish", BuiltinToolNames.FilePublish); - } + [Fact] + public void Name_IsTheDocumentedUsesValue() + { + Assert.Equal("file.publish", BuiltinToolNames.FilePublish); + } - [Fact] - public void Build_NoBlobStore_FailsTheLoadNamingTheToolAndThePort() - { - var failure = Assert.Throws(() => new FilePublishToolDefinition().Build( - Declared, new BuiltinToolPorts(ChatClients: null, Blobs: null, WorkspaceRoot: _root))); + [Fact] + public void Build_NoBlobStore_FailsTheLoadNamingTheToolAndThePort() + { + ConfigurationLoadException failure = Assert.Throws(() => new FilePublishToolDefinition().Build( + Declared, new BuiltinToolPorts(ChatClients: null, Blobs: null, WorkspaceRoot: _root))); - Assert.Contains("'publish'", failure.Message, StringComparison.Ordinal); - Assert.Contains("providers.blobs", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("'publish'", failure.Message, StringComparison.Ordinal); + Assert.Contains("providers.blobs", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Build_NoWorkspaceRoot_FailsTheLoadNamingUseWorkspace() - { - var failure = Assert.Throws(() => new FilePublishToolDefinition().Build( - Declared, new BuiltinToolPorts(ChatClients: null, Blobs: _blobs, WorkspaceRoot: null))); + [Fact] + public void Build_NoWorkspaceRoot_FailsTheLoadNamingUseWorkspace() + { + ConfigurationLoadException failure = Assert.Throws(() => new FilePublishToolDefinition().Build( + Declared, new BuiltinToolPorts(ChatClients: null, Blobs: _blobs, WorkspaceRoot: null))); - Assert.Contains("'publish'", failure.Message, StringComparison.Ordinal); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("'publish'", failure.Message, StringComparison.Ordinal); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Build_NamesTheFunctionAfterTheDeclaredIdAndHidesTheTurnFromTheModel() - { - var function = Assert.IsType(Build(), exactMatch: false); + [Fact] + public void Build_NamesTheFunctionAfterTheDeclaredIdAndHidesTheTurnFromTheModel() + { + AIFunction function = Assert.IsType(Build(), exactMatch: false); - Assert.Equal("publish", function.Name); - Assert.Equal("Publish a file.", function.Description); + Assert.Equal("publish", function.Name); + Assert.Equal("Publish a file.", function.Description); - var properties = function.JsonSchema.GetProperty("properties"); - Assert.True(properties.TryGetProperty("path", out _)); - Assert.True(properties.TryGetProperty("title", out _)); - Assert.False(properties.TryGetProperty("turn", out _)); - Assert.Contains("path", function.JsonSchema.GetProperty("required").EnumerateArray().Select(e => e.GetString())); - } + JsonElement properties = function.JsonSchema.GetProperty("properties"); + Assert.True(properties.TryGetProperty("path", out _)); + Assert.True(properties.TryGetProperty("title", out _)); + Assert.False(properties.TryGetProperty("turn", out _)); + Assert.Contains("path", function.JsonSchema.GetProperty("required").EnumerateArray().Select(e => e.GetString())); + } - [Theory] - [InlineData("../secret.csv")] - [InlineData("out/../../secret.csv")] - [InlineData("/etc/passwd")] - public async Task Publish_APathOutsideTheWorkspace_IsRefusedWithAToolError(string path) - { - File.WriteAllText(Path.Combine(_root, "secret.csv"), "a,b"); + [Theory] + [InlineData("../secret.csv")] + [InlineData("out/../../secret.csv")] + [InlineData("/etc/passwd")] + public async Task Publish_APathOutsideTheWorkspace_IsRefusedWithAToolError(string path) + { + File.WriteAllText(Path.Combine(_root, "secret.csv"), "a,b"); - var result = await PublishAsync(path); + JsonObject result = await PublishAsync(path); - Assert.True(ToolErrorResult.IsError(result)); - Assert.Equal("publish", result["tool"]!.GetValue()); - Assert.Contains("inside the workspace", result["message"]!.GetValue(), StringComparison.Ordinal); - Assert.Empty(_blobs.Blobs); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Equal("publish", result["tool"]!.GetValue()); + Assert.Contains("inside the workspace", result["message"]!.GetValue(), StringComparison.Ordinal); + Assert.Empty(_blobs.Blobs); + } - [Fact] - public async Task Publish_AFileThatIsNotThere_IsRefusedWithAToolError() - { - var result = await PublishAsync("missing.csv"); + [Fact] + public async Task Publish_AFileThatIsNotThere_IsRefusedWithAToolError() + { + JsonObject result = await PublishAsync("missing.csv"); - Assert.True(ToolErrorResult.IsError(result)); - Assert.Contains("missing.csv", result["message"]!.GetValue(), StringComparison.Ordinal); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Contains("missing.csv", result["message"]!.GetValue(), StringComparison.Ordinal); + } - [Fact] - public async Task Publish_AnExtensionThePolicyRefuses_IsRefusedWithTheReason() - { - File.WriteAllText(Path.Combine(_root, "conversation-1", "notes.exe"), "x"); + [Fact] + public async Task Publish_AnExtensionThePolicyRefuses_IsRefusedWithTheReason() + { + File.WriteAllText(Path.Combine(_root, "conversation-1", "notes.exe"), "x"); - var result = await PublishAsync("notes.exe"); + JsonObject result = await PublishAsync("notes.exe"); - Assert.True(ToolErrorResult.IsError(result)); - Assert.Contains("extension 'exe' is not allowed", result["message"]!.GetValue(), StringComparison.Ordinal); - Assert.Empty(_blobs.Blobs); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Contains("extension 'exe' is not allowed", result["message"]!.GetValue(), StringComparison.Ordinal); + Assert.Empty(_blobs.Blobs); + } - [Fact] - public async Task Publish_AFileOverTheCap_IsRefusedWithTheReason() - { - File.WriteAllBytes(Path.Combine(_root, "conversation-1", "big.csv"), new byte[64]); + [Fact] + public async Task Publish_AFileOverTheCap_IsRefusedWithTheReason() + { + File.WriteAllBytes(Path.Combine(_root, "conversation-1", "big.csv"), new byte[64]); - var result = await PublishAsync("big.csv", policy: new BlobPolicy(32, ["csv"])); + JsonObject result = await PublishAsync("big.csv", policy: new BlobPolicy(32, ["csv"])); - Assert.True(ToolErrorResult.IsError(result)); - Assert.Contains("size 64 is outside 0..32 bytes", result["message"]!.GetValue(), StringComparison.Ordinal); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Contains("size 64 is outside 0..32 bytes", result["message"]!.GetValue(), StringComparison.Ordinal); + } - [Fact] - public async Task Publish_AGoodFile_StoresItUnderTheConversationLinksItAndFilesTheCardOnTheTurn() - { - File.WriteAllText(Path.Combine(_root, "conversation-1", "rows.csv"), "a,b\n1,2\n"); - TurnFiles files = new(); - using var outer = files.BeginOuterCall("tc_1"); - - var result = await PublishAsync("rows.csv", title: "Sales by month", files: files); - - Assert.False(ToolErrorResult.IsError(result)); - Assert.Equal("rows.csv", result["name"]!.GetValue()); - Assert.Equal("text/csv", result["mediaType"]!.GetValue()); - Assert.Equal(8, result["length"]!.GetValue()); - Assert.Equal("https://blobs.test/conversation-1/rows.csv?ttl=900", result["url"]!.GetValue()); - - var (mediaType, bytes) = _blobs.Blobs[("conversation-1", "rows.csv")]; - Assert.Equal("text/csv", mediaType); - Assert.Equal("a,b\n1,2\n", System.Text.Encoding.UTF8.GetString(bytes)); - - var card = Assert.Single(files.TakeFor("tc_1")); - Assert.Equal("rows.csv", card.Name); - Assert.Equal("rows.csv", card.FileId); - Assert.Equal("Sales by month", card.Title); - Assert.Equal("text/csv", card.MediaType); - Assert.Equal(8, card.Length); - Assert.True(card.Kept); - } + [Fact] + public async Task Publish_AGoodFile_StoresItUnderTheConversationLinksItAndFilesTheCardOnTheTurn() + { + File.WriteAllText(Path.Combine(_root, "conversation-1", "rows.csv"), "a,b\n1,2\n"); + TurnFiles files = new(); + using IDisposable outer = files.BeginOuterCall("tc_1"); + + JsonObject result = await PublishAsync("rows.csv", title: "Sales by month", files: files); + + Assert.False(ToolErrorResult.IsError(result)); + Assert.Equal("rows.csv", result["name"]!.GetValue()); + Assert.Equal("text/csv", result["mediaType"]!.GetValue()); + Assert.Equal(8, result["length"]!.GetValue()); + Assert.Equal("https://blobs.test/conversation-1/rows.csv?ttl=900", result["url"]!.GetValue()); + + (string? mediaType, byte[]? bytes) = _blobs.Blobs[("conversation-1", "rows.csv")]; + Assert.Equal("text/csv", mediaType); + Assert.Equal("a,b\n1,2\n", System.Text.Encoding.UTF8.GetString(bytes)); + + FileContent card = Assert.Single(files.TakeFor("tc_1")); + Assert.Equal("rows.csv", card.Name); + Assert.Equal("rows.csv", card.FileId); + Assert.Equal("Sales by month", card.Title); + Assert.Equal("text/csv", card.MediaType); + Assert.Equal(8, card.Length); + Assert.True(card.Kept); + } - [Fact] - public async Task Publish_AFileInASubfolder_IsStoredUnderItsOwnName() - { - Directory.CreateDirectory(Path.Combine(_root, "conversation-1", "out")); - File.WriteAllBytes(Path.Combine(_root, "conversation-1", "out", "chart.png"), [1, 2, 3]); + [Fact] + public async Task Publish_AFileInASubfolder_IsStoredUnderItsOwnName() + { + _ = Directory.CreateDirectory(Path.Combine(_root, "conversation-1", "out")); + File.WriteAllBytes(Path.Combine(_root, "conversation-1", "out", "chart.png"), [1, 2, 3]); - var result = await PublishAsync("out/chart.png"); + JsonObject result = await PublishAsync("out/chart.png"); - Assert.Equal("chart.png", result["name"]!.GetValue()); - Assert.Equal("image/png", result["mediaType"]!.GetValue()); - Assert.True(_blobs.Blobs.ContainsKey(("conversation-1", "chart.png"))); - } + Assert.Equal("chart.png", result["name"]!.GetValue()); + Assert.Equal("image/png", result["mediaType"]!.GetValue()); + Assert.True(_blobs.Blobs.ContainsKey(("conversation-1", "chart.png"))); + } - [Fact] - public async Task Publish_OutsideAnyTurn_IsRefusedWithAToolError() - { - File.WriteAllText(Path.Combine(_root, "conversation-1", "rows.csv"), "a"); + [Fact] + public async Task Publish_OutsideAnyTurn_IsRefusedWithAToolError() + { + File.WriteAllText(Path.Combine(_root, "conversation-1", "rows.csv"), "a"); - var result = await PublishAsync("rows.csv", turn: false); + JsonObject result = await PublishAsync("rows.csv", turn: false); - Assert.True(ToolErrorResult.IsError(result)); - Assert.Contains("no conversation is running", result["message"]!.GetValue(), StringComparison.Ordinal); - } + Assert.True(ToolErrorResult.IsError(result)); + Assert.Contains("no conversation is running", result["message"]!.GetValue(), StringComparison.Ordinal); + } - private AITool Build(BlobPolicy? policy = null) - => new FilePublishToolDefinition().Build( - Declared, new BuiltinToolPorts(ChatClients: null, Blobs: _blobs, BlobPolicy: policy, WorkspaceRoot: _root)); + private AITool Build(BlobPolicy? policy = null) + { + return new FilePublishToolDefinition().Build( + Declared, new BuiltinToolPorts(ChatClients: null, Blobs: _blobs, BlobPolicy: policy, WorkspaceRoot: _root)); + } - private async Task PublishAsync( - string path, string? title = null, BlobPolicy? policy = null, TurnFiles? files = null, bool turn = true) - { - var function = (AIFunction)Build(policy); + private async Task PublishAsync( + string path, string? title = null, BlobPolicy? policy = null, TurnFiles? files = null, bool turn = true) + { + AIFunction function = (AIFunction)Build(policy); - AIFunctionArguments arguments = new(new Dictionary(StringComparer.Ordinal) { ["path"] = path, ["title"] = title }); + AIFunctionArguments arguments = new(new Dictionary(StringComparer.Ordinal) { ["path"] = path, ["title"] = title }); - if (turn) - { - new TurnInvocation + if (turn) { - ConversationId = "conversation-1", - TurnIndex = 0, - Stage = string.Empty, - Workspace = Path.Combine(_root, "conversation-1"), - Files = files, - }.FileIn(arguments); + _ = new TurnInvocation + { + ConversationId = "conversation-1", + TurnIndex = 0, + Stage = string.Empty, + Workspace = Path.Combine(_root, "conversation-1"), + Files = files, + }.FileIn(arguments); + } + + object? result = await function.InvokeAsync(arguments, TestContext.Current.CancellationToken); + + return Assert.IsType(ToolResultJson.ToNode(result)); } - - var result = await function.InvokeAsync(arguments, TestContext.Current.CancellationToken); - - return Assert.IsType(ToolResultJson.ToNode(result)); } } diff --git a/tests/AgentCore.Application.Tests/Tools/TimeLimitedToolTests.cs b/tests/AgentCore.Application.Tests/Tools/TimeLimitedToolTests.cs index a1af802d..10bc5a4c 100644 --- a/tests/AgentCore.Application.Tests/Tools/TimeLimitedToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/TimeLimitedToolTests.cs @@ -6,131 +6,140 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// The deadline any tool kind can carry. -/// -/// -/// A tool the model calls on a live telephone conversation can otherwise take as long as the far side feels -/// like taking. The deadline wraps a tool rather than living inside one, so one implementation and -/// one message cover every kind rather than each kind growing its own. -/// -public sealed class TimeLimitedToolTests +namespace AgentCore.Application.Tests.Tools { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task AToolThatAnswersInTime_IsUntouched() - { - TimeLimitedTool tool = new(Answering("done"), TimeSpan.FromSeconds(30)); - - var result = await tool.InvokeAsync([], Token); - - Assert.Equal("done", Assert.IsType(result).GetString()); - } - - [Fact] - public async Task AToolThatRunsLong_ReturnsAnErrorResult_AndDoesNotThrow() - { - TimeLimitedTool tool = new(Hanging(), TimeSpan.FromMilliseconds(50)); - - var result = await tool.InvokeAsync([], Token); - - // Section 8.7: the model reads the result and decides what to say next. An exception would - // end the turn while a caller is on the line. - var error = Assert.IsType(result); - Assert.True(ToolErrorResult.IsError(error)); - Assert.Equal("slow", error[ToolErrorResult.ToolProperty]!.GetValue()); - Assert.Contains("0.05s", error[ToolErrorResult.MessageProperty]!.GetValue(), StringComparison.Ordinal); - } - - /// - /// The turn being cancelled is the caller's own token and belongs to the caller. Only this - /// wrapper's own deadline becomes a result. - /// - [Fact] - public async Task TheTurnBeingCancelled_StillThrows_AndIsNotReportedAsATimeout() - { - TimeLimitedTool tool = new(Hanging(), TimeSpan.FromMinutes(5)); - using CancellationTokenSource turn = new(); - await turn.CancelAsync(); - - await Assert.ThrowsAnyAsync( - async () => await tool.InvokeAsync([], turn.Token)); - } - - [Fact] - public void TheWrapperShowsTheSameToolToTheModel() - { - var inner = Answering("x"); - TimeLimitedTool tool = new(inner, TimeSpan.FromSeconds(1)); - - Assert.Equal(inner.Name, tool.Name); - Assert.Equal(inner.Description, tool.Description); - Assert.Equal(inner.JsonSchema.GetRawText(), tool.JsonSchema.GetRawText()); - } - - [Fact] - public void ADeadlineOfNothing_IsRefused() - => Assert.Throws( - () => new TimeLimitedTool(Answering("x"), TimeSpan.Zero)); - - // --------------------------------------------------------------------------------------------- - // The registry is what applies the deadline, so every kind gets the same one. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ARegistrationThatNamesATimeout_ResolvesToALimitedTool() - { - var registry = await ToolRegistryBuilder.BuildAsync( - [new StubSource(new ToolRegistration("slow", "d", Hanging, TimeSpan.FromMilliseconds(50)))], - new ToolSourceContext(Documents.Empty), - Token); - - var result = await ((AIFunction)registry.Resolve("slow")).InvokeAsync([], Token); - - Assert.True(ToolErrorResult.IsError(Assert.IsType(result))); - } - /// - /// A source that names no timeout gets no wrapper: a kind: agent tool runs a whole inner - /// agent loop, and a default deadline over that would cut off work that is going fine. + /// The deadline any tool kind can carry. /// - [Fact] - public async Task ARegistrationThatNamesNoTimeout_ResolvesToTheToolItself() + /// + /// A tool the model calls on a live telephone conversation can otherwise take as long as the far side feels + /// like taking. The deadline wraps a tool rather than living inside one, so one implementation and + /// one message cover every kind rather than each kind growing its own. + /// + public sealed class TimeLimitedToolTests { - var inner = Answering("plain"); - var registry = await ToolRegistryBuilder.BuildAsync( - [new StubSource(new ToolRegistration("plain", "d", () => inner))], - new ToolSourceContext(Documents.Empty), - Token); - - Assert.Same(inner, registry.Resolve("plain")); - } - - private static AIFunction Answering(string answer) - => AIFunctionFactory.Create(() => answer, "quick", "Answers at once."); - - private static AIFunction Hanging() - => AIFunctionFactory.Create( - async (CancellationToken ct) => + private static CancellationToken Token => TestContext.Current.CancellationToken; + + [Fact] + public async Task AToolThatAnswersInTime_IsUntouched() + { + TimeLimitedTool tool = new(Answering("done"), TimeSpan.FromSeconds(30)); + + object? result = await tool.InvokeAsync([], Token); + + Assert.Equal("done", Assert.IsType(result).GetString()); + } + + [Fact] + public async Task AToolThatRunsLong_ReturnsAnErrorResult_AndDoesNotThrow() + { + TimeLimitedTool tool = new(Hanging(), TimeSpan.FromMilliseconds(50)); + + object? result = await tool.InvokeAsync([], Token); + + // Section 8.7: the model reads the result and decides what to say next. An exception would + // end the turn while a caller is on the line. + JsonObject error = Assert.IsType(result); + Assert.True(ToolErrorResult.IsError(error)); + Assert.Equal("slow", error[ToolErrorResult.ToolProperty]!.GetValue()); + Assert.Contains("0.05s", error[ToolErrorResult.MessageProperty]!.GetValue(), StringComparison.Ordinal); + } + + /// + /// The turn being cancelled is the caller's own token and belongs to the caller. Only this + /// wrapper's own deadline becomes a result. + /// + [Fact] + public async Task TheTurnBeingCancelled_StillThrows_AndIsNotReportedAsATimeout() + { + TimeLimitedTool tool = new(Hanging(), TimeSpan.FromMinutes(5)); + using CancellationTokenSource turn = new(); + await turn.CancelAsync(); + + _ = await Assert.ThrowsAnyAsync( + async () => await tool.InvokeAsync([], turn.Token)); + } + + [Fact] + public void TheWrapperShowsTheSameToolToTheModel() + { + AIFunction inner = Answering("x"); + TimeLimitedTool tool = new(inner, TimeSpan.FromSeconds(1)); + + Assert.Equal(inner.Name, tool.Name); + Assert.Equal(inner.Description, tool.Description); + Assert.Equal(inner.JsonSchema.GetRawText(), tool.JsonSchema.GetRawText()); + } + + [Fact] + public void ADeadlineOfNothing_IsRefused() + { + _ = Assert.Throws( + () => new TimeLimitedTool(Answering("x"), TimeSpan.Zero)); + } + + // --------------------------------------------------------------------------------------------- + // The registry is what applies the deadline, so every kind gets the same one. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ARegistrationThatNamesATimeout_ResolvesToALimitedTool() + { + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("slow", "d", Hanging, TimeSpan.FromMilliseconds(50)))], + new ToolSourceContext(Documents.Empty), + Token); + + object? result = await ((AIFunction)registry.Resolve("slow")).InvokeAsync([], Token); + + Assert.True(ToolErrorResult.IsError(Assert.IsType(result))); + } + + /// + /// A source that names no timeout gets no wrapper: a kind: agent tool runs a whole inner + /// agent loop, and a default deadline over that would cut off work that is going fine. + /// + [Fact] + public async Task ARegistrationThatNamesNoTimeout_ResolvesToTheToolItself() + { + AIFunction inner = Answering("plain"); + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [new StubSource(new ToolRegistration("plain", "d", () => inner))], + new ToolSourceContext(Documents.Empty), + Token); + + Assert.Same(inner, registry.Resolve("plain")); + } + + private static AIFunction Answering(string answer) + { + return AIFunctionFactory.Create(() => answer, "quick", "Answers at once."); + } + + private static AIFunction Hanging() + { + return AIFunctionFactory.Create( + async (CancellationToken ct) => + { + await Task.Delay(Timeout.InfiniteTimeSpan, ct); + return "never"; + }, + "slow", + "Never answers."); + } + + private sealed class StubSource(params ToolRegistration[] registrations) : Application.Ports.IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) { - await Task.Delay(Timeout.InfiniteTimeSpan, ct); - return "never"; - }, - "slow", - "Never answers."); - - private sealed class StubSource(params ToolRegistration[] registrations) : Application.Ports.IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>(registrations); - } - - private static class Documents - { - public static Application.Configuration.Schema.AgentCoreConfiguration Empty { get; } - = new() { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary() }; + return ValueTask.FromResult>(registrations); + } + } + + private static class Documents + { + public static AgentCoreConfiguration Empty { get; } + = new() { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary() }; + } } } diff --git a/tests/AgentCore.Application.Tests/Tools/ToolCallScopeTests.cs b/tests/AgentCore.Application.Tests/Tools/ToolCallScopeTests.cs index 8a401251..355e922c 100644 --- a/tests/AgentCore.Application.Tests/Tools/ToolCallScopeTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/ToolCallScopeTests.cs @@ -1,6 +1,7 @@ using System.Runtime.CompilerServices; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; @@ -10,15 +11,15 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// Drives a real turn end to end through , with a bound tool that declares -/// a parameter, and reads what the runtime actually filled it with. -/// -public sealed class ToolCallScopeTests +namespace AgentCore.Application.Tests.Tools { - private const string Yaml = """ + /// + /// Drives a real turn end to end through , with a bound tool that declares + /// a parameter, and reads what the runtime actually filled it with. + /// + public sealed class ToolCallScopeTests + { + private const string Yaml = """ apiVersion: agentcore/v1 tools: - { id: request_human, kind: binding, binds: RequestHuman, description: "Ask a human to take the conversation." } @@ -34,119 +35,121 @@ public sealed class ToolCallScopeTests - { id: waiting, agent: only, to: [ { stage: handling } ] } """; - [Fact] - public async Task ABoundTool_ReceivesTheRunningConversationsScope() - { - List captured = []; - ToolBindingRegistry bindings = new(); - bindings.Register("RequestHuman", (string reason, ToolCallScope scope) => captured.Add(scope)); - - var document = ConfigurationLoader.LoadYaml(Yaml); - var chatClients = new FakeChatClientFactory(new PerTurnToolCallingChatClient("connecting you now.")); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - Tools = await ToolRegistryBuilder.BuildAsync( - [new BindingToolSource(bindings)], - new ToolSourceContext(document), - TestContext.Current.CancellationToken), - })["main"]; - - var factory = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards)); - var session = factory.Create("conversation-scope-1"); - - await session.RunTurnAsync("I need a person", TestContext.Current.CancellationToken); - - var first = Assert.Single(captured); - Assert.Equal(session.ConversationId, first.ConversationId); - Assert.Equal(0, first.TurnIndex); - Assert.Equal("handling", first.Stage); - - captured.Clear(); - await session.RunTurnAsync("still need a person", TestContext.Current.CancellationToken); - - var second = Assert.Single(captured); - Assert.Equal(session.ConversationId, second.ConversationId); - Assert.Equal(1, second.TurnIndex); - } - - /// - /// Calls the one offered tool once per turn, rather than once per conversation: it looks only at what - /// came after the caller's latest message, so a tool call answered in an earlier turn does not - /// stop this one from calling the tool again. - /// - private sealed class PerTurnToolCallingChatClient : IChatClient - { - private readonly string _reply; - private int _nextCallId; - - public PerTurnToolCallingChatClient(string reply) => _reply = reply; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); - - var transcript = messages.ToList(); - var lastUserIndex = transcript.FindLastIndex(message => message.Role == ChatRole.User); - var answeredThisTurn = transcript - .Skip(lastUserIndex + 1) - .Any(message => message.Contents.OfType().Any()); - - var responseId = Guid.NewGuid().ToString("N"); - - if (!answeredThisTurn && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [ - new FunctionCallContent( - $"conversation_{_nextCallId++}", - tool.Name, - new Dictionary(StringComparer.Ordinal) - { - ["reason"] = "the caller wants a person", - }), - ]) - { - ResponseId = responseId, - MessageId = responseId, - }; - - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - }; - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - } - } + [Fact] + public async Task ABoundTool_ReceivesTheRunningConversationsScope() + { + List captured = []; + ToolBindingRegistry bindings = new(); + _ = bindings.Register("RequestHuman", (string reason, ToolCallScope scope) => captured.Add(scope)); + + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); + FakeChatClientFactory chatClients = new(new PerTurnToolCallingChatClient("connecting you now.")); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + Tools = await ToolRegistryBuilder.BuildAsync( + [new BindingToolSource(bindings)], + new ToolSourceContext(document), + TestContext.Current.CancellationToken), + })["main"]; + + ConversationSessionFactory factory = new( + compiled, new GuardEvaluator(compiled.Configuration.Guards)); + ConversationSession session = factory.Create("conversation-scope-1"); + + _ = await session.RunTurnAsync("I need a person", TestContext.Current.CancellationToken); + + ToolCallScope first = Assert.Single(captured); + Assert.Equal(session.ConversationId, first.ConversationId); + Assert.Equal(0, first.TurnIndex); + Assert.Equal("handling", first.Stage); + + captured.Clear(); + _ = await session.RunTurnAsync("still need a person", TestContext.Current.CancellationToken); + + ToolCallScope second = Assert.Single(captured); + Assert.Equal(session.ConversationId, second.ConversationId); + Assert.Equal(1, second.TurnIndex); + } + + /// + /// Calls the one offered tool once per turn, rather than once per conversation: it looks only at what + /// came after the caller's latest message, so a tool call answered in an earlier turn does not + /// stop this one from calling the tool again. + /// + private sealed class PerTurnToolCallingChatClient(string reply) : IChatClient + { + private readonly string _reply = reply; + private int _nextCallId; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); + + List transcript = [.. messages]; + int lastUserIndex = transcript.FindLastIndex(message => message.Role == ChatRole.User); + bool answeredThisTurn = transcript + .Skip(lastUserIndex + 1) + .Any(message => message.Contents.OfType().Any()); + + string responseId = Guid.NewGuid().ToString("N"); + + if (!answeredThisTurn && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [ + new FunctionCallContent( + $"conversation_{_nextCallId++}", + tool.Name, + new Dictionary(StringComparer.Ordinal) + { + ["reason"] = "the caller wants a person", + }), + ]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Tools/ToolRegistryTests.cs b/tests/AgentCore.Application.Tests/Tools/ToolRegistryTests.cs index 341ff8e5..60c810ca 100644 --- a/tests/AgentCore.Application.Tests/Tools/ToolRegistryTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/ToolRegistryTests.cs @@ -1,151 +1,159 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; -using AgentCore.Application.Tools; using AgentCore.Application.Tools.Registry; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// The map from a tool id to the tool, and the rules the boot enforces on it. -/// -/// -/// Sources push their tools in at startup. The id and the description are known then, so the boot -/// can reject them. The tool itself is built on the first resolve, which is what lets a kind: agent -/// tool be registered before the agent it delegates to has compiled. -/// -public sealed class ToolRegistryTests +namespace AgentCore.Application.Tests.Tools { - private const string ToolId = "search_chunks"; - private const string OtherId = "create_case"; - private const string Description = "Find a passage."; - - [Fact] - public async Task ARegisteredTool_ResolvesByItsId() + /// + /// The map from a tool id to the tool, and the rules the boot enforces on it. + /// + /// + /// Sources push their tools in at startup. The id and the description are known then, so the boot + /// can reject them. The tool itself is built on the first resolve, which is what lets a kind: agent + /// tool be registered before the agent it delegates to has compiled. + /// + public sealed class ToolRegistryTests { - var context = ContextFor(ToolId); + private const string ToolId = "search_chunks"; + private const string OtherId = "create_case"; + private const string Description = "Find a passage."; - var registry = await ToolRegistryBuilder.BuildAsync([SourceOf(ToolId)], context, TestContext.Current.CancellationToken); + [Fact] + public async Task ARegisteredTool_ResolvesByItsId() + { + ToolSourceContext context = ContextFor(ToolId); - Assert.Equal(ToolId, registry.Resolve(ToolId).Name); - } + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync([SourceOf(ToolId)], context, TestContext.Current.CancellationToken); - [Fact] - public async Task ATool_IsNotBuiltUntilItIsResolved() - { - var built = 0; - FakeToolSource source = new([new ToolRegistration(ToolId, Description, () => { built++; return Stub(ToolId); })]); + Assert.Equal(ToolId, registry.Resolve(ToolId).Name); + } - var registry = await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken); + [Fact] + public async Task ATool_IsNotBuiltUntilItIsResolved() + { + int built = 0; + FakeToolSource source = new([new ToolRegistration(ToolId, Description, () => { built++; return Stub(ToolId); })]); - Assert.Equal(0, built); - registry.Resolve(ToolId); - Assert.Equal(1, built); - } + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken); - [Fact] - public async Task AResolvedTool_IsBuiltOnlyOnce() - { - var built = 0; - FakeToolSource source = new([new ToolRegistration(ToolId, Description, () => { built++; return Stub(ToolId); })]); - var registry = await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken); + Assert.Equal(0, built); + _ = registry.Resolve(ToolId); + Assert.Equal(1, built); + } - registry.Resolve(ToolId); - registry.Resolve(ToolId); + [Fact] + public async Task AResolvedTool_IsBuiltOnlyOnce() + { + int built = 0; + FakeToolSource source = new([new ToolRegistration(ToolId, Description, () => { built++; return Stub(ToolId); })]); + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken); - Assert.Equal(1, built); - } + _ = registry.Resolve(ToolId); + _ = registry.Resolve(ToolId); - [Fact] - public async Task TwoSourcesClaimingOneId_FailTheBoot() - { - var context = ContextFor(ToolId); + Assert.Equal(1, built); + } - var failure = await Assert.ThrowsAsync(async () => - await ToolRegistryBuilder.BuildAsync( - [SourceOf(ToolId), SourceOf(ToolId)], context, TestContext.Current.CancellationToken)); + [Fact] + public async Task TwoSourcesClaimingOneId_FailTheBoot() + { + ToolSourceContext context = ContextFor(ToolId); - Assert.Contains(ToolId, failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await ToolRegistryBuilder.BuildAsync( + [SourceOf(ToolId), SourceOf(ToolId)], context, TestContext.Current.CancellationToken)); - [Fact] - public async Task ADeclaredToolNoSourceClaims_FailsTheBoot() - { - var context = ContextFor(ToolId, OtherId); + Assert.Contains(ToolId, failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync(async () => - await ToolRegistryBuilder.BuildAsync([SourceOf(ToolId)], context, TestContext.Current.CancellationToken)); + [Fact] + public async Task ADeclaredToolNoSourceClaims_FailsTheBoot() + { + ToolSourceContext context = ContextFor(ToolId, OtherId); - Assert.Contains(OtherId, failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await ToolRegistryBuilder.BuildAsync([SourceOf(ToolId)], context, TestContext.Current.CancellationToken)); - [Fact] - public async Task AnUnknownId_ThrowsOnResolve() - { - var registry = await ToolRegistryBuilder.BuildAsync( - [SourceOf(ToolId)], ContextFor(ToolId), TestContext.Current.CancellationToken); + Assert.Contains(OtherId, failure.Message, StringComparison.Ordinal); + } - Assert.Throws(() => registry.Resolve(OtherId)); - } + [Fact] + public async Task AnUnknownId_ThrowsOnResolve() + { + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [SourceOf(ToolId)], ContextFor(ToolId), TestContext.Current.CancellationToken); - [Fact] - public async Task ADeclaredAgentTool_BuildsWithNoSourceServingIt() - { - var context = ContextFor(ToolKind.Agent, "delegate"); + _ = Assert.Throws(() => registry.Resolve(OtherId)); + } - var registry = await ToolRegistryBuilder.BuildAsync([], context, TestContext.Current.CancellationToken); + [Fact] + public async Task ADeclaredAgentTool_BuildsWithNoSourceServingIt() + { + ToolSourceContext context = ContextFor(ToolKind.Agent, "delegate"); - Assert.False(registry.Contains("delegate")); - } + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync([], context, TestContext.Current.CancellationToken); - [Fact] - public async Task AToolWithNoDescription_FailsTheBoot() - { - FakeToolSource source = new([new ToolRegistration(ToolId, string.Empty, () => Stub(ToolId))]); + Assert.False(registry.Contains("delegate")); + } - var failure = await Assert.ThrowsAsync(async () => - await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken)); + [Fact] + public async Task AToolWithNoDescription_FailsTheBoot() + { + FakeToolSource source = new([new ToolRegistration(ToolId, string.Empty, () => Stub(ToolId))]); - Assert.Contains(ToolId, failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken)); - [Fact] - public async Task AToolWithAWhitespaceDescription_FailsTheBoot() - { - FakeToolSource source = new([new ToolRegistration(ToolId, " ", () => Stub(ToolId))]); + Assert.Contains(ToolId, failure.Message, StringComparison.Ordinal); + } - await Assert.ThrowsAsync(async () => - await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken)); - } + [Fact] + public async Task AToolWithAWhitespaceDescription_FailsTheBoot() + { + FakeToolSource source = new([new ToolRegistration(ToolId, " ", () => Stub(ToolId))]); - private static ToolSourceContext ContextFor(params string[] ids) - => ContextFor(ToolKind.Binding, ids); + _ = await Assert.ThrowsAsync(async () => + await ToolRegistryBuilder.BuildAsync([source], ContextFor(ToolId), TestContext.Current.CancellationToken)); + } - private static ToolSourceContext ContextFor(ToolKind kind, params string[] ids) - { - List tools = []; - foreach (var id in ids) + private static ToolSourceContext ContextFor(params string[] ids) { - tools.Add(kind == ToolKind.Agent - ? new ToolConfiguration { Id = id, Kind = ToolKind.Agent, Agent = "inner" } - : new ToolConfiguration { Id = id, Kind = ToolKind.Binding, Binds = id }); + return ContextFor(ToolKind.Binding, ids); } - return new ToolSourceContext(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Tools = tools }); - } + private static ToolSourceContext ContextFor(ToolKind kind, params string[] ids) + { + List tools = []; + foreach (string id in ids) + { + tools.Add(kind == ToolKind.Agent + ? new ToolConfiguration { Id = id, Kind = ToolKind.Agent, Agent = "inner" } + : new ToolConfiguration { Id = id, Kind = ToolKind.Binding, Binds = id }); + } + + return new ToolSourceContext(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Tools = tools }); + } - private static FakeToolSource SourceOf(string id) - => new([new ToolRegistration(id, Description, () => Stub(id))]); + private static FakeToolSource SourceOf(string id) + { + return new([new ToolRegistration(id, Description, () => Stub(id))]); + } - private static AIFunction Stub(string id) - => AIFunctionFactory.Create(() => "ok", new AIFunctionFactoryOptions { Name = id, Description = Description }); + private static AIFunction Stub(string id) + { + return AIFunctionFactory.Create(() => "ok", new AIFunctionFactoryOptions { Name = id, Description = Description }); + } - private sealed class FakeToolSource(IReadOnlyList registrations) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken) - => ValueTask.FromResult(registrations); + private sealed class FakeToolSource(IReadOnlyList registrations) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken) + { + return ValueTask.FromResult(registrations); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs b/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs index 1c94d601..76af6556 100644 --- a/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs @@ -10,287 +10,290 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// -/// The typed half of kind: binding: the host registers a method, and its signature is the -/// argument schema the model reads. -/// -/// -/// The document writes binds: CreateCase and no parameters:. Everything the model -/// needs to fill the conversation comes off the method, so the two can never drift apart. -/// -public sealed class TypedBindingToolTests +namespace AgentCore.Application.Tests.Tools { - private static readonly ToolConfiguration OpenCase = new() - { - Id = "open_case", - Kind = ToolKind.Binding, - Binds = "CreateCase", - Description = "Open a service case for a human agent.", - }; - - // --------------------------------------------------------------------------------------------- - // The registry. - // --------------------------------------------------------------------------------------------- - [Fact] - public void ATypedMethodAndAJsonDelegate_AreReadBackApart() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (string summary) => summary); - registry.Register("CloseCase", (_, _) => ValueTask.FromResult(null)); - - Assert.True(registry.TryGetMethod("CreateCase", out var method)); - Assert.NotNull(method); - Assert.False(registry.TryGetBinding("CreateCase", out var absentBinding)); - Assert.Null(absentBinding); - - Assert.True(registry.TryGetBinding("CloseCase", out var binding)); - Assert.NotNull(binding); - Assert.False(registry.TryGetMethod("CloseCase", out var absentMethod)); - Assert.Null(absentMethod); - } - - [Fact] - public void ATypedMethod_CountsAgainstTheSameNames() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (string summary) => summary); - - Assert.Equal(1, registry.Count); - Assert.True(registry.Contains("CreateCase")); - Assert.Contains("CreateCase", registry.Names); - } - - [Fact] - public void TheSameNameTypedThenJson_FailsAtStartup() - { - ToolBindingRegistry registry = new(); - registry.Register("CreateCase", (string summary) => summary); - - Assert.Throws( - () => registry.Register("CreateCase", (_, _) => ValueTask.FromResult(null))); - } - - // --------------------------------------------------------------------------------------------- - // The schema the model reads. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheSchemaComesOffTheMethodSignature() + /// + /// The typed half of kind: binding: the host registers a method, and its signature is the + /// argument schema the model reads. + /// + /// + /// The document writes binds: CreateCase and no parameters:. Everything the model + /// needs to fill the conversation comes off the method, so the two can never drift apart. + /// + public sealed class TypedBindingToolTests { - var tool = await CreateAsync( - ([Description("What the customer wants.")] string summary, int priority = 3) => $"{summary}/{priority}"); - - var properties = tool.JsonSchema.GetProperty("properties"); - Assert.True(properties.TryGetProperty("summary", out var summaryProperty)); - Assert.True(properties.TryGetProperty("priority", out _)); - Assert.Equal("What the customer wants.", summaryProperty.GetProperty("description").GetString()); - } + private static readonly ToolConfiguration OpenCase = new() + { + Id = "open_case", + Kind = ToolKind.Binding, + Binds = "CreateCase", + Description = "Open a service case for a human agent.", + }; - [Fact] - public async Task AParameterWithADefault_IsNotRequired() - { - var tool = await CreateAsync((string summary, int priority = 3) => $"{summary}/{priority}"); + // --------------------------------------------------------------------------------------------- + // The registry. + // --------------------------------------------------------------------------------------------- + [Fact] + public void ATypedMethodAndAJsonDelegate_AreReadBackApart() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (string summary) => summary); + _ = registry.Register("CloseCase", (_, _) => ValueTask.FromResult(null)); + + Assert.True(registry.TryGetMethod("CreateCase", out Delegate? method)); + Assert.NotNull(method); + Assert.False(registry.TryGetBinding("CreateCase", out ToolBinding? absentBinding)); + Assert.Null(absentBinding); + + Assert.True(registry.TryGetBinding("CloseCase", out ToolBinding? binding)); + Assert.NotNull(binding); + Assert.False(registry.TryGetMethod("CloseCase", out Delegate? absentMethod)); + Assert.Null(absentMethod); + } + + [Fact] + public void ATypedMethod_CountsAgainstTheSameNames() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (string summary) => summary); - var required = tool.JsonSchema.GetProperty("required").EnumerateArray().Select(e => e.GetString()).ToList(); + Assert.Equal(1, registry.Count); + Assert.True(registry.Contains("CreateCase")); + Assert.Contains("CreateCase", registry.Names); + } - Assert.Contains("summary", required); - Assert.DoesNotContain("priority", required); - } + [Fact] + public void TheSameNameTypedThenJson_FailsAtStartup() + { + ToolBindingRegistry registry = new(); + _ = registry.Register("CreateCase", (string summary) => summary); + + _ = Assert.Throws( + () => registry.Register("CreateCase", (_, _) => ValueTask.FromResult(null))); + } + + // --------------------------------------------------------------------------------------------- + // The schema the model reads. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheSchemaComesOffTheMethodSignature() + { + AIFunction tool = await CreateAsync( + ([Description("What the customer wants.")] string summary, int priority = 3) => $"{summary}/{priority}"); - [Fact] - public async Task TheNameAndDescription_StillComeFromTheDocument() - { - var tool = await CreateAsync((string summary) => summary); + JsonElement properties = tool.JsonSchema.GetProperty("properties"); + Assert.True(properties.TryGetProperty("summary", out JsonElement summaryProperty)); + Assert.True(properties.TryGetProperty("priority", out _)); + Assert.Equal("What the customer wants.", summaryProperty.GetProperty("description").GetString()); + } - Assert.Equal("open_case", tool.Name); - Assert.Equal("Open a service case for a human agent.", tool.Description); - } + [Fact] + public async Task AParameterWithADefault_IsNotRequired() + { + AIFunction tool = await CreateAsync((string summary, int priority = 3) => $"{summary}/{priority}"); - /// The model never sees the scope parameter: it names the running conversation, not an argument the model fills. - [Fact] - public async Task AToolCallScopeParameter_IsLeftOutOfTheSchema() - { - var tool = await CreateAsync((string reason, ToolCallScope scope, CancellationToken ct) => reason); + List required = [.. tool.JsonSchema.GetProperty("required").EnumerateArray().Select(e => e.GetString())]; - var properties = tool.JsonSchema.GetProperty("properties"); - Assert.True(properties.TryGetProperty("reason", out _)); - Assert.False(properties.TryGetProperty("scope", out _)); - Assert.DoesNotContain("ConversationId", tool.JsonSchema.GetRawText(), StringComparison.Ordinal); - } + Assert.Contains("summary", required); + Assert.DoesNotContain("priority", required); + } - // --------------------------------------------------------------------------------------------- - // Calling. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheModelArgumentsReachTheMethodParameters() - { - string? seenSummary = null; - int seenPriority = 0; - var tool = await CreateAsync((string summary, int priority) => + [Fact] + public async Task TheNameAndDescription_StillComeFromTheDocument() { - seenSummary = summary; - seenPriority = priority; - return "C-1"; - }); - - var result = await tool.InvokeAsync( - new AIFunctionArguments { ["summary"] = "broken belt", ["priority"] = 1 }, - TestContext.Current.CancellationToken); - - Assert.Equal("broken belt", seenSummary); - Assert.Equal(1, seenPriority); - Assert.Equal("C-1", $"{result}"); - } + AIFunction tool = await CreateAsync((string summary) => summary); - /// Arguments arrive off the wire as , not as CLR values. - [Fact] - public async Task ArgumentsThatArriveAsJsonElements_BindToo() - { - var tool = await CreateAsync((string summary, int priority) => $"{summary}/{priority}"); - using var document = JsonDocument.Parse("""{"summary":"loose bolt","priority":7}"""); + Assert.Equal("open_case", tool.Name); + Assert.Equal("Open a service case for a human agent.", tool.Description); + } - var result = await tool.InvokeAsync( - new AIFunctionArguments + /// The model never sees the scope parameter: it names the running conversation, not an argument the model fills. + [Fact] + public async Task AToolCallScopeParameter_IsLeftOutOfTheSchema() + { + AIFunction tool = await CreateAsync((string reason, ToolCallScope scope, CancellationToken ct) => reason); + + JsonElement properties = tool.JsonSchema.GetProperty("properties"); + Assert.True(properties.TryGetProperty("reason", out _)); + Assert.False(properties.TryGetProperty("scope", out _)); + Assert.DoesNotContain("ConversationId", tool.JsonSchema.GetRawText(), StringComparison.Ordinal); + } + + // --------------------------------------------------------------------------------------------- + // Calling. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheModelArgumentsReachTheMethodParameters() + { + string? seenSummary = null; + int seenPriority = 0; + AIFunction tool = await CreateAsync((string summary, int priority) => { - ["summary"] = document.RootElement.GetProperty("summary"), - ["priority"] = document.RootElement.GetProperty("priority"), - }, - TestContext.Current.CancellationToken); - - Assert.Equal("loose bolt/7", $"{result}"); - } - - [Fact] - public async Task AnArgumentTheModelLeftOut_TakesTheMethodDefault() - { - var tool = await CreateAsync((string summary, int priority = 3) => $"{summary}/{priority}"); - - var result = await tool.InvokeAsync( - new AIFunctionArguments { ["summary"] = "no power" }, TestContext.Current.CancellationToken); - - Assert.Equal("no power/3", $"{result}"); - } - - [Fact] - public async Task TheCancellationTokenReachesTheMethod() - { - var tool = await CreateAsync((string summary, CancellationToken cancellationToken) => + seenSummary = summary; + seenPriority = priority; + return "C-1"; + }); + + object? result = await tool.InvokeAsync( + new AIFunctionArguments { ["summary"] = "broken belt", ["priority"] = 1 }, + TestContext.Current.CancellationToken); + + Assert.Equal("broken belt", seenSummary); + Assert.Equal(1, seenPriority); + Assert.Equal("C-1", $"{result}"); + } + + /// Arguments arrive off the wire as , not as CLR values. + [Fact] + public async Task ArgumentsThatArriveAsJsonElements_BindToo() { - cancellationToken.ThrowIfCancellationRequested(); - return summary; - }); + AIFunction tool = await CreateAsync((string summary, int priority) => $"{summary}/{priority}"); + using JsonDocument document = JsonDocument.Parse("""{"summary":"loose bolt","priority":7}"""); + + object? result = await tool.InvokeAsync( + new AIFunctionArguments + { + ["summary"] = document.RootElement.GetProperty("summary"), + ["priority"] = document.RootElement.GetProperty("priority"), + }, + TestContext.Current.CancellationToken); + + Assert.Equal("loose bolt/7", $"{result}"); + } + + [Fact] + public async Task AnArgumentTheModelLeftOut_TakesTheMethodDefault() + { + AIFunction tool = await CreateAsync((string summary, int priority = 3) => $"{summary}/{priority}"); - using CancellationTokenSource cancelled = new(); - await cancelled.CancelAsync(); + object? result = await tool.InvokeAsync( + new AIFunctionArguments { ["summary"] = "no power" }, TestContext.Current.CancellationToken); - await Assert.ThrowsAnyAsync(async () => - await tool.InvokeAsync(new AIFunctionArguments { ["summary"] = "anything" }, cancelled.Token)); - } + Assert.Equal("no power/3", $"{result}"); + } - /// - /// A binding declares a parameter to read the conversation it runs in, but a - /// call to the tool with no turn open on this flow has no call to report. - /// - [Fact] - public async Task AToolCallScopeParameterWithNoTurnOpen_Throws() - { - var tool = await CreateAsync((string reason, ToolCallScope scope) => reason); + [Fact] + public async Task TheCancellationTokenReachesTheMethod() + { + AIFunction tool = await CreateAsync((string summary, CancellationToken cancellationToken) => + { + cancellationToken.ThrowIfCancellationRequested(); + return summary; + }); + + using CancellationTokenSource cancelled = new(); + await cancelled.CancelAsync(); + + _ = await Assert.ThrowsAnyAsync(async () => + await tool.InvokeAsync(new AIFunctionArguments { ["summary"] = "anything" }, cancelled.Token)); + } + + /// + /// A binding declares a parameter to read the conversation it runs in, but a + /// call to the tool with no turn open on this flow has no call to report. + /// + [Fact] + public async Task AToolCallScopeParameterWithNoTurnOpen_Throws() + { + AIFunction tool = await CreateAsync((string reason, ToolCallScope scope) => reason); - var thrown = await Assert.ThrowsAsync(async () => - await tool.InvokeAsync( - new AIFunctionArguments { ["reason"] = "the caller wants a person" }, - TestContext.Current.CancellationToken)); + InvalidOperationException thrown = await Assert.ThrowsAsync(async () => + await tool.InvokeAsync( + new AIFunctionArguments { ["reason"] = "the caller wants a person" }, + TestContext.Current.CancellationToken)); - Assert.Contains("ToolCallScope", thrown.Message, StringComparison.Ordinal); - Assert.Equal(ToolCallScopes.NoTurnMessage, thrown.Message); - } + Assert.Contains("ToolCallScope", thrown.Message, StringComparison.Ordinal); + Assert.Equal(ToolCallScopes.NoTurnMessage, thrown.Message); + } - /// A tool call carrying the turn in its arguments binds the scope off no flow at all. - [Fact] - public async Task AToolCallScopeParameterWithTheTurnFiled_BindsWithoutAFlow() - { - ToolCallScope? captured = null; - var tool = await CreateAsync((string reason, ToolCallScope scope) => + /// A tool call carrying the turn in its arguments binds the scope off no flow at all. + [Fact] + public async Task AToolCallScopeParameterWithTheTurnFiled_BindsWithoutAFlow() { - captured = scope; - return reason; - }); + ToolCallScope? captured = null; + AIFunction tool = await CreateAsync((string reason, ToolCallScope scope) => + { + captured = scope; + return reason; + }); - TurnInvocation turn = new() + TurnInvocation turn = new() + { + ConversationId = "conversation-9", + TurnIndex = 4, + Stage = "handling", + Workspace = "ws", + }; + + object? result = await tool.InvokeAsync( + turn.FileIn(new AIFunctionArguments { ["reason"] = "the caller wants a person" }), + TestContext.Current.CancellationToken); + + Assert.Equal("the caller wants a person", $"{result}"); + Assert.Equal("conversation-9", captured!.ConversationId); + Assert.Equal(4, captured.TurnIndex); + Assert.Equal("handling", captured.Stage); + Assert.Equal("ws", captured.Workspace); + } + + /// The error policy of section 8.7 keys off , not off the delegate. + [Fact] + public async Task ATypedBinding_IsStillADeclaredTool() { - ConversationId = "conversation-9", - TurnIndex = 4, - Stage = "handling", - Workspace = "ws", - }; + AIFunction tool = await CreateAsync((string summary) => summary); - var result = await tool.InvokeAsync( - turn.FileIn(new AIFunctionArguments { ["reason"] = "the caller wants a person" }), - TestContext.Current.CancellationToken); + _ = Assert.IsType(tool, exactMatch: false); + } - Assert.Equal("the caller wants a person", $"{result}"); - Assert.Equal("conversation-9", captured!.ConversationId); - Assert.Equal(4, captured.TurnIndex); - Assert.Equal("handling", captured.Stage); - Assert.Equal("ws", captured.Workspace); - } + // --------------------------------------------------------------------------------------------- + // The boot rules. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ATypedBindingThatAlsoDeclaresParameters_FailsTheBoot() + { + ToolBindingRegistry bindings = new(); + _ = bindings.Register("CreateCase", (string summary) => summary); - /// The error policy of section 8.7 keys off , not off the delegate. - [Fact] - public async Task ATypedBinding_IsStillADeclaredTool() - { - var tool = await CreateAsync((string summary) => summary); + ToolConfiguration declared = OpenCase with + { + Parameters = JsonNode.Parse("""{"type":"object","properties":{"summary":{"type":"string"}}}"""), + }; - Assert.IsType(tool, exactMatch: false); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await new BindingToolSource(bindings).ProvideAsync( + ContextFor(declared), TestContext.Current.CancellationToken)); - // --------------------------------------------------------------------------------------------- - // The boot rules. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ATypedBindingThatAlsoDeclaresParameters_FailsTheBoot() - { - ToolBindingRegistry bindings = new(); - bindings.Register("CreateCase", (string summary) => summary); + Assert.Contains("parameters:", failure.Message, StringComparison.Ordinal); + Assert.Contains("open_case", failure.Message, StringComparison.Ordinal); + } - var declared = OpenCase with + [Fact] + public async Task ATypedBinding_BecomesOneRegistration() { - Parameters = JsonNode.Parse("""{"type":"object","properties":{"summary":{"type":"string"}}}"""), - }; + ToolBindingRegistry bindings = new(); + _ = bindings.Register("CreateCase", (string summary) => summary); - var failure = await Assert.ThrowsAsync(async () => - await new BindingToolSource(bindings).ProvideAsync( - ContextFor(declared), TestContext.Current.CancellationToken)); + IReadOnlyList registrations = await new BindingToolSource(bindings).ProvideAsync( + ContextFor(OpenCase), TestContext.Current.CancellationToken); - Assert.Contains("parameters:", failure.Message, StringComparison.Ordinal); - Assert.Contains("open_case", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task ATypedBinding_BecomesOneRegistration() - { - ToolBindingRegistry bindings = new(); - bindings.Register("CreateCase", (string summary) => summary); + Assert.Equal("open_case", Assert.Single(registrations).Id); + } - var registrations = await new BindingToolSource(bindings).ProvideAsync( - ContextFor(OpenCase), TestContext.Current.CancellationToken); - - Assert.Equal("open_case", Assert.Single(registrations).Id); - } - - private static ToolSourceContext ContextFor(ToolConfiguration tool) - => new(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Tools = [tool] }); + private static ToolSourceContext ContextFor(ToolConfiguration tool) + { + return new(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Tools = [tool] }); + } - /// Builds the tool the way the boot does: through the source, off the document. - private static async Task CreateAsync(Delegate method) - { - ToolBindingRegistry bindings = new(); - bindings.Register("CreateCase", method); + /// Builds the tool the way the boot does: through the source, off the document. + private static async Task CreateAsync(Delegate method) + { + ToolBindingRegistry bindings = new(); + _ = bindings.Register("CreateCase", method); - var registrations = await new BindingToolSource(bindings).ProvideAsync( - ContextFor(OpenCase), TestContext.Current.CancellationToken); + IReadOnlyList registrations = await new BindingToolSource(bindings).ProvideAsync( + ContextFor(OpenCase), TestContext.Current.CancellationToken); - return Assert.IsType(Assert.Single(registrations).Materialise(), exactMatch: false); + return Assert.IsType(Assert.Single(registrations).Materialise(), exactMatch: false); + } } } diff --git a/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs b/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs index f2fa362e..18751c6c 100644 --- a/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs @@ -3,35 +3,36 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Tools; - -/// The uses: web.search builtin, which builds a marker and nothing else. -public sealed class WebSearchToolDefinitionTests +namespace AgentCore.Application.Tests.Tools { - [Fact] - public void Name_IsTheDocumentedUsesValue() + /// The uses: web.search builtin, which builds a marker and nothing else. + public sealed class WebSearchToolDefinitionTests { - Assert.Equal("web.search", BuiltinToolNames.WebSearch); - } + [Fact] + public void Name_IsTheDocumentedUsesValue() + { + Assert.Equal("web.search", BuiltinToolNames.WebSearch); + } - [Fact] - public void Build_ProducesAHostedWebSearchTool() - { - var tool = new WebSearchToolDefinition().Build( - new ToolConfiguration { Id = "search", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }, - new BuiltinToolPorts(ChatClients: null)); + [Fact] + public void Build_ProducesAHostedWebSearchTool() + { + AITool tool = new WebSearchToolDefinition().Build( + new ToolConfiguration { Id = "search", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }, + new BuiltinToolPorts(ChatClients: null)); - Assert.IsType(tool); - } + _ = Assert.IsType(tool); + } - [Fact] - public void Build_NeedsNoPorts() - { - // The marker carries no behaviour, so an unbound chat client factory is not a failure here. - var exception = Record.Exception(() => new WebSearchToolDefinition().Build( - new ToolConfiguration { Id = "search", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }, - new BuiltinToolPorts(ChatClients: null))); + [Fact] + public void Build_NeedsNoPorts() + { + // The marker carries no behaviour, so an unbound chat client factory is not a failure here. + Exception? exception = Record.Exception(() => new WebSearchToolDefinition().Build( + new ToolConfiguration { Id = "search", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }, + new BuiltinToolPorts(ChatClients: null))); - Assert.Null(exception); + Assert.Null(exception); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTestSupport.cs b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTestSupport.cs index a24807a9..991bdfca 100644 --- a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTestSupport.cs +++ b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTestSupport.cs @@ -8,133 +8,152 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// What both halves of the provider's test suite share: the conversation id, the session state -/// key, and the plumbing to open a conversation and read its history back. -internal static class AgentCoreChatHistoryProviderTestSupport +namespace AgentCore.Application.Tests.Transcript { - internal const string ConversationId = "conversation-1"; - - /// - /// The provider's MAF-default state key: its own type name. The transcript no longer files - /// under it — or anywhere in the bag — and a change still renames what the collision checks - /// compare, so it stays pinned here rather than inlined. - /// - internal const string StateKey = "AgentCoreChatHistoryProvider"; - - /// - /// Opens one conversation on a fresh session, the way ConversationSession does at conversation start: the row is - /// made before any turn can append against it, exactly as ConversationSession.OpenSessionAsync - /// makes it before it ever reaches this provider. - /// - internal static async Task<(AgentCoreChatHistoryProvider Provider, RecordingConversationStore Store, StubSession Session)> NewConversation() + /// What both halves of the provider's test suite share: the conversation id, the session state + /// key, and the plumbing to open a conversation and read its history back. + internal static class AgentCoreChatHistoryProviderTestSupport { - var store = new RecordingConversationStore(); - await store.CreateAsync(ConversationId, TestContext.Current.CancellationToken); - var provider = new AgentCoreChatHistoryProvider(store); - var session = new StubSession(); - provider.BeginConversation(session, ConversationId, []); - return (provider, store, session); - } + internal const string ConversationId = "conversation-1"; + + /// + /// The provider's MAF-default state key: its own type name. The transcript no longer files + /// under it — or anywhere in the bag — and a change still renames what the collision checks + /// compare, so it stays pinned here rather than inlined. + /// + internal const string StateKey = "AgentCoreChatHistoryProvider"; + + /// + /// Opens one conversation on a fresh session, the way ConversationSession does at conversation start: the row is + /// made before any turn can append against it, exactly as ConversationSession.OpenSessionAsync + /// makes it before it ever reaches this provider. + /// + internal static async Task<(AgentCoreChatHistoryProvider Provider, RecordingConversationStore Store, StubSession Session)> NewConversation() + { + RecordingConversationStore store = new(); + _ = await store.CreateAsync(ConversationId, TestContext.Current.CancellationToken); + AgentCoreChatHistoryProvider provider = new(store); + StubSession session = new(); + _ = provider.BeginConversation(session, ConversationId, []); + return (provider, store, session); + } - /// Writes one turn the way ConversationSession does: name the turn, then append it. - internal static void AppendTurn( - AgentCoreChatHistoryProvider provider, - AgentSession session, - int turnIndex, - string said, - string replied) - { - provider.BeginTurn(session, turnIndex); - provider.AppendTurn( - session, - [new ChatMessage(ChatRole.User, said), new ChatMessage(ChatRole.Assistant, replied)]); - } + /// Writes one turn the way ConversationSession does: name the turn, then append it. + internal static void AppendTurn( + AgentCoreChatHistoryProvider provider, + AgentSession session, + int turnIndex, + string said, + string replied) + { + provider.BeginTurn(session, turnIndex); + _ = provider.AppendTurn( + session, + [new ChatMessage(ChatRole.User, said), new ChatMessage(ChatRole.Assistant, replied)]); + } - internal static async Task> ProvideAsync( - AgentCoreChatHistoryProvider provider, AgentSession session) - { + internal static async Task> ProvideAsync( + AgentCoreChatHistoryProvider provider, AgentSession session) + { #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - var context = new ChatHistoryProvider.InvokingContext(StubAgent.Instance, session, []); + ChatHistoryProvider.InvokingContext context = new(StubAgent.Instance, session, []); #pragma warning restore MAAI001 - var messages = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - return [.. messages]; + IEnumerable messages = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + return [.. messages]; + } } -} -/// -/// Holds one append open, so a barge-in can arrive while a turn is still writing. It keeps the -/// real store's ordering rule: a rewrite of a row that is not there yet changes nothing. -/// -internal sealed class BlockingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) -{ - private readonly TaskCompletionSource _entered = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); - private bool _block; + /// + /// Holds one append open, so a barge-in can arrive while a turn is still writing. It keeps the + /// real store's ordering rule: a rewrite of a row that is not there yet changes nothing. + /// + internal sealed class BlockingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) + { + private readonly TaskCompletionSource _entered = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); + private bool _block; - public Task Entered => _entered.Task; + public Task Entered => _entered.Task; - public void BlockNextAppend() => _block = true; + public void BlockNextAppend() + { + _block = true; + } - public void Release() => _release.TrySetResult(); + public void Release() + { + _ = _release.TrySetResult(); + } - public override async ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - { - if (_block) + public override async ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) { - _block = false; - _entered.TrySetResult(); - await _release.Task.WaitAsync(cancellationToken); + if (_block) + { + _block = false; + _ = _entered.TrySetResult(); + await _release.Task.WaitAsync(cancellationToken); + } + + return await Inner.AppendAsync(conversationId, messages, state, cancellationToken); } - return await Inner.AppendAsync(conversationId, messages, state, cancellationToken); + public override ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + return Inner.RewriteAsync(conversationId, messageId, content, cancellationToken); + } } - public override ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - => Inner.RewriteAsync(conversationId, messageId, content, cancellationToken); -} + internal sealed class StubSession : AgentSession; -internal sealed class StubSession : AgentSession; + /// Stands in for the agent the framework names on a context. Nothing here runs it. + internal sealed class StubAgent : AIAgent + { + public static StubAgent Instance { get; } = new(); -/// Stands in for the agent the framework names on a context. Nothing here runs it. -internal sealed class StubAgent : AIAgent -{ - public static StubAgent Instance { get; } = new(); - - protected override ValueTask CreateSessionCoreAsync( - CancellationToken cancellationToken = default) - => new(new StubSession()); - - protected override ValueTask SerializeSessionCoreAsync( - AgentSession session, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override ValueTask DeserializeSessionCoreAsync( - JsonElement serializedState, - JsonSerializerOptions? jsonSerializerOptions = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override Task RunCoreAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - protected override IAsyncEnumerable RunCoreStreamingAsync( - IEnumerable messages, - AgentSession? session = null, - AgentRunOptions? options = null, - CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + protected override ValueTask CreateSessionCoreAsync( + CancellationToken cancellationToken = default) + { + return new(new StubSession()); + } + + protected override ValueTask SerializeSessionCoreAsync( + AgentSession session, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override ValueTask DeserializeSessionCoreAsync( + JsonElement serializedState, + JsonSerializerOptions? jsonSerializerOptions = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override Task RunCoreAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + protected override IAsyncEnumerable RunCoreStreamingAsync( + IEnumerable messages, + AgentSession? session = null, + AgentRunOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } diff --git a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTests.cs b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTests.cs index 0050db59..f5701c68 100644 --- a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTests.cs @@ -5,244 +5,244 @@ using Xunit; using static AgentCore.Application.Tests.Transcript.AgentCoreChatHistoryProviderTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins what the provider adds to : the lock, the write chain, and the -/// rule that a store failure never reaches the turn. -/// -public sealed class AgentCoreChatHistoryProviderTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task ProvideChatHistory_AfterAppend_ReturnsMessagesInOrder() - { - // Arrange - var (provider, _, session) = await NewConversation(); - AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); - AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday"); - - // Act - var history = await ProvideAsync(provider, session); - - // Assert - Assert.Equal( - ["hello", "hi there", "order 41?", "it ships Friday"], - history.Select(message => message.Text)); - } - - [Fact] - public async Task AppendTurn_MultipleTurns_OrdinalsAreDenseAndUnique() - { - // Arrange - var (provider, store, session) = await NewConversation(); - AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); - - // Act - AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday"); - - // Assert - await provider.DrainAsync(session); - Assert.Equal([0, 1, 2, 3], store.Rows.Select(row => row.Ordinal)); - Assert.Equal([0, 0, 1, 1], store.Rows.Select(row => row.TurnIndex)); - Assert.All(store.Rows, row => Assert.Equal(ConversationId, row.ConversationId)); - } - - [Fact] - public async Task AppendTurn_RefusedTurn_IsStored() - { - // Arrange - var (provider, store, session) = await NewConversation(); - - // Act - AppendTurn(provider, session, turnIndex: 0, "something flagged", "I can't help with that."); - - // Assert - await provider.DrainAsync(session); - Assert.Equal( - ["something flagged", "I can't help with that."], - store.Rows.Select(row => row.Content.Text)); - } - - [Fact] - public async Task AppendTurn_FailedTurn_IsStored() - { - // Arrange - var (provider, store, session) = await NewConversation(); - - // Act - AppendTurn(provider, session, turnIndex: 0, "check my order", "Sorry, I had trouble with that."); - - // Assert - await provider.DrainAsync(session); - Assert.Equal( - ["check my order", "Sorry, I had trouble with that."], - store.Rows.Select(row => row.Content.Text)); - } - /// - /// The framework offers to store a finished run, and this provider declines. Measured on - /// Microsoft.Agents.AI 1.17.0, that hook stores the request verbatim — reminder and all — and is - /// never called at all for a run the caller cut short, which is every barge-in. ConversationSession - /// writes the turn it shaped instead. + /// Pins what the provider adds to : the lock, the write chain, and the + /// rule that a store failure never reaches the turn. /// - [Fact] - public async Task StoreChatHistory_FinishedRun_StoresNothing() + public sealed class AgentCoreChatHistoryProviderTests { - // Arrange - var (provider, store, session) = await NewConversation(); - provider.BeginTurn(session, turnIndex: 0); - - // Act + [Fact] + public async Task ProvideChatHistory_AfterAppend_ReturnsMessagesInOrder() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore _, StubSession? session) = await NewConversation(); + AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); + AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday"); + + // Act + IReadOnlyList history = await ProvideAsync(provider, session); + + // Assert + Assert.Equal( + ["hello", "hi there", "order 41?", "it ships Friday"], + history.Select(message => message.Text)); + } + + [Fact] + public async Task AppendTurn_MultipleTurns_OrdinalsAreDenseAndUnique() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore? store, StubSession? session) = await NewConversation(); + AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); + + // Act + AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday"); + + // Assert + await provider.DrainAsync(session); + Assert.Equal([0, 1, 2, 3], store.Rows.Select(row => row.Ordinal)); + Assert.Equal([0, 0, 1, 1], store.Rows.Select(row => row.TurnIndex)); + Assert.All(store.Rows, row => Assert.Equal(ConversationId, row.ConversationId)); + } + + [Fact] + public async Task AppendTurn_RefusedTurn_IsStored() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore? store, StubSession? session) = await NewConversation(); + + // Act + AppendTurn(provider, session, turnIndex: 0, "something flagged", "I can't help with that."); + + // Assert + await provider.DrainAsync(session); + Assert.Equal( + ["something flagged", "I can't help with that."], + store.Rows.Select(row => row.Content.Text)); + } + + [Fact] + public async Task AppendTurn_FailedTurn_IsStored() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore? store, StubSession? session) = await NewConversation(); + + // Act + AppendTurn(provider, session, turnIndex: 0, "check my order", "Sorry, I had trouble with that."); + + // Assert + await provider.DrainAsync(session); + Assert.Equal( + ["check my order", "Sorry, I had trouble with that."], + store.Rows.Select(row => row.Content.Text)); + } + + /// + /// The framework offers to store a finished run, and this provider declines. Measured on + /// Microsoft.Agents.AI 1.17.0, that hook stores the request verbatim — reminder and all — and is + /// never called at all for a run the caller cut short, which is every barge-in. ConversationSession + /// writes the turn it shaped instead. + /// + [Fact] + public async Task StoreChatHistory_FinishedRun_StoresNothing() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore? store, StubSession? session) = await NewConversation(); + provider.BeginTurn(session, turnIndex: 0); + + // Act #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - await provider.InvokedAsync( - new ChatHistoryProvider.InvokedContext( - StubAgent.Instance, - session, - [new ChatMessage(ChatRole.User, "ask for the id\norder 41?")], - [new ChatMessage(ChatRole.Assistant, "it ships Friday")]), - TestContext.Current.CancellationToken); + await provider.InvokedAsync( + new ChatHistoryProvider.InvokedContext( + StubAgent.Instance, + session, + [new ChatMessage(ChatRole.User, "ask for the id\norder 41?")], + [new ChatMessage(ChatRole.Assistant, "it ships Friday")]), + TestContext.Current.CancellationToken); #pragma warning restore MAAI001 - // Assert - await provider.DrainAsync(session); - Assert.Empty(store.Rows); - Assert.Empty(await ProvideAsync(provider, session)); - } - - [Fact] - public async Task AppendTurn_ConcurrentAppends_LosesNoMessage() - { - // Arrange - var (provider, store, session) = await NewConversation(); - provider.BeginTurn(session, turnIndex: 0); - var start = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); - var turns = Enumerable.Range(0, 20) - .Select(index => Task.Run( - async () => - { - await start.Task; - provider.AppendTurn( - session, - [ - new ChatMessage(ChatRole.User, $"said {index}"), - new ChatMessage(ChatRole.Assistant, $"replied {index}"), - ]); - }, - TestContext.Current.CancellationToken)) - .ToArray(); - - // Act - start.SetResult(); - await Task.WhenAll(turns); - - // Assert - await provider.DrainAsync(session); - Assert.Equal(40, store.Rows.Count); - Assert.Equal(Enumerable.Range(0, 40), store.Rows.Select(row => row.Ordinal).Order()); - } - - [Fact] - public async Task ProvideChatHistory_TwoConcurrentSessions_DoNotMix() - { - // Arrange - var provider = new AgentCoreChatHistoryProvider(new RecordingConversationStore()); - var first = new StubSession(); - var second = new StubSession(); - provider.BeginConversation(first, "conversation-a", []); - provider.BeginConversation(second, "conversation-b", []); - AppendTurn(provider, first, turnIndex: 0, "a said", "a heard"); - - // Act - AppendTurn(provider, second, turnIndex: 0, "b said", "b heard"); - - // Assert - Assert.Equal(["a said", "a heard"], (await ProvideAsync(provider, first)).Select(message => message.Text)); - Assert.Equal(["b said", "b heard"], (await ProvideAsync(provider, second)).Select(message => message.Text)); - } - - /// - /// The framework validates this set at agent construction and again on every run, and refuses a - /// collision. The value is MAF's default — the provider's own type name — and nothing files - /// under it anymore, but a change still renames what the collision checks compare, so it stays - /// pinned rather than inlined. - /// - [Fact] - public void StateKeys_IsTheSingleProviderTypeNameKey() - { - // Arrange - var provider = new AgentCoreChatHistoryProvider(); - - // Assert - Assert.Equal([StateKey], provider.StateKeys); - } - - [Fact] - public async Task AppendTurn_LeavesTheSessionStateBagEmpty() - { - // Arrange - var (provider, _, session) = await NewConversation(); - - // Act - AppendTurn(provider, session, turnIndex: 0, "order 41?", "it ships Friday"); - - // Assert - Assert.Equal(0, session.StateBag.Count); - Assert.Equal(["order 41?", "it ships Friday"], provider.Read(session).Select(message => message.Text)); - } - - /// - /// The provider is one object shared by every conversation, so two sessions must still reach two - /// transcripts. State held against the provider rather than the session would merge them. - /// - [Fact] - public void AppendTurn_TwoSessions_EachHoldsItsOwnTranscript() - { - // Arrange - var provider = new AgentCoreChatHistoryProvider(new RecordingConversationStore()); - var first = new StubSession(); - var second = new StubSession(); - provider.BeginConversation(first, "conversation-a", []); - provider.BeginConversation(second, "conversation-b", []); - - // Act - AppendTurn(provider, first, turnIndex: 0, "a said", "a heard"); - AppendTurn(provider, second, turnIndex: 0, "b said", "b heard"); - - // Assert - Assert.Equal(["a said", "a heard"], provider.Read(first).Select(message => message.Text)); - Assert.Equal(["b said", "b heard"], provider.Read(second).Select(message => message.Text)); - } - - [Fact] - public async Task AppendTurn_BackingStoreThrows_DoesNotFailTheTurn() - { - // Arrange - var provider = new AgentCoreChatHistoryProvider(new ThrowingConversationStore()); - var session = new StubSession(); - provider.BeginConversation(session, ConversationId, []); - - // Act - AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); - - // Assert - await provider.DrainAsync(session); - Assert.Equal(["hello", "hi there"], (await ProvideAsync(provider, session)).Select(message => message.Text)); - } - - [Fact] - public async Task BeginConversation_BackingStoreThrows_TellsTheReporterWhichTurnWasLost() - { - // Arrange - var provider = new AgentCoreChatHistoryProvider(new ThrowingConversationStore()); - var session = new StubSession(); - List dropped = []; - provider.BeginConversation(session, ConversationId, [], (turnIndex, _) => dropped.Add(turnIndex)); - - // Act - AppendTurn(provider, session, turnIndex: 3, "hello", "hi there"); - - // Assert - await provider.DrainAsync(session); - Assert.Equal([3], dropped); + // Assert + await provider.DrainAsync(session); + Assert.Empty(store.Rows); + Assert.Empty(await ProvideAsync(provider, session)); + } + + [Fact] + public async Task AppendTurn_ConcurrentAppends_LosesNoMessage() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore? store, StubSession? session) = await NewConversation(); + provider.BeginTurn(session, turnIndex: 0); + TaskCompletionSource start = new(TaskCreationOptions.RunContinuationsAsynchronously); + Task[] turns = [.. Enumerable.Range(0, 20) + .Select(index => Task.Run( + async () => + { + await start.Task; + _ = provider.AppendTurn( + session, + [ + new ChatMessage(ChatRole.User, $"said {index}"), + new ChatMessage(ChatRole.Assistant, $"replied {index}"), + ]); + }, + TestContext.Current.CancellationToken))]; + + // Act + start.SetResult(); + await Task.WhenAll(turns); + + // Assert + await provider.DrainAsync(session); + Assert.Equal(40, store.Rows.Count); + Assert.Equal(Enumerable.Range(0, 40), store.Rows.Select(row => row.Ordinal).Order()); + } + + [Fact] + public async Task ProvideChatHistory_TwoConcurrentSessions_DoNotMix() + { + // Arrange + AgentCoreChatHistoryProvider provider = new(new RecordingConversationStore()); + StubSession first = new(); + StubSession second = new(); + _ = provider.BeginConversation(first, "conversation-a", []); + _ = provider.BeginConversation(second, "conversation-b", []); + AppendTurn(provider, first, turnIndex: 0, "a said", "a heard"); + + // Act + AppendTurn(provider, second, turnIndex: 0, "b said", "b heard"); + + // Assert + Assert.Equal(["a said", "a heard"], (await ProvideAsync(provider, first)).Select(message => message.Text)); + Assert.Equal(["b said", "b heard"], (await ProvideAsync(provider, second)).Select(message => message.Text)); + } + + /// + /// The framework validates this set at agent construction and again on every run, and refuses a + /// collision. The value is MAF's default — the provider's own type name — and nothing files + /// under it anymore, but a change still renames what the collision checks compare, so it stays + /// pinned rather than inlined. + /// + [Fact] + public void StateKeys_IsTheSingleProviderTypeNameKey() + { + // Arrange + AgentCoreChatHistoryProvider provider = new(); + + // Assert + Assert.Equal([StateKey], provider.StateKeys); + } + + [Fact] + public async Task AppendTurn_LeavesTheSessionStateBagEmpty() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, RecordingConversationStore _, StubSession? session) = await NewConversation(); + + // Act + AppendTurn(provider, session, turnIndex: 0, "order 41?", "it ships Friday"); + + // Assert + Assert.Equal(0, session.StateBag.Count); + Assert.Equal(["order 41?", "it ships Friday"], provider.Read(session).Select(message => message.Text)); + } + + /// + /// The provider is one object shared by every conversation, so two sessions must still reach two + /// transcripts. State held against the provider rather than the session would merge them. + /// + [Fact] + public void AppendTurn_TwoSessions_EachHoldsItsOwnTranscript() + { + // Arrange + AgentCoreChatHistoryProvider provider = new(new RecordingConversationStore()); + StubSession first = new(); + StubSession second = new(); + _ = provider.BeginConversation(first, "conversation-a", []); + _ = provider.BeginConversation(second, "conversation-b", []); + + // Act + AppendTurn(provider, first, turnIndex: 0, "a said", "a heard"); + AppendTurn(provider, second, turnIndex: 0, "b said", "b heard"); + + // Assert + Assert.Equal(["a said", "a heard"], provider.Read(first).Select(message => message.Text)); + Assert.Equal(["b said", "b heard"], provider.Read(second).Select(message => message.Text)); + } + + [Fact] + public async Task AppendTurn_BackingStoreThrows_DoesNotFailTheTurn() + { + // Arrange + AgentCoreChatHistoryProvider provider = new(new ThrowingConversationStore()); + StubSession session = new(); + _ = provider.BeginConversation(session, ConversationId, []); + + // Act + AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); + + // Assert + await provider.DrainAsync(session); + Assert.Equal(["hello", "hi there"], (await ProvideAsync(provider, session)).Select(message => message.Text)); + } + + [Fact] + public async Task BeginConversation_BackingStoreThrows_TellsTheReporterWhichTurnWasLost() + { + // Arrange + AgentCoreChatHistoryProvider provider = new(new ThrowingConversationStore()); + StubSession session = new(); + List dropped = []; + _ = provider.BeginConversation(session, ConversationId, [], (turnIndex, _) => dropped.Add(turnIndex)); + + // Act + AppendTurn(provider, session, turnIndex: 3, "hello", "hi there"); + + // Assert + await provider.DrainAsync(session); + Assert.Equal([3], dropped); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs index 7a0dc07f..3f50dc62 100644 --- a/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/AgentCoreChatHistoryProviderTruncateTests.cs @@ -5,178 +5,179 @@ using Xunit; using static AgentCore.Application.Tests.Transcript.AgentCoreChatHistoryProviderTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins what a barge-in does to the words the provider already wrote: which row it rewrites, and -/// when the rewrite is guaranteed to land after the append it corrects. -/// -public sealed class AgentCoreChatHistoryProviderTruncateTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task TruncateLastReply_LastAssistantMessage_RewritesOnlyThatMessage() - { - // Arrange - var (provider, store, session) = await NewConversation(); - AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); - AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday from the depot"); - - // Act - var cut = provider.TruncateLastReply(session, "it ships", TimeSpan.FromMilliseconds(420)); - - // Assert - Assert.True(cut); - var history = await ProvideAsync(provider, session); - Assert.Equal( - ["hello", "hi there", "order 41?", "it ships"], - history.Select(message => message.Text)); - await provider.DrainAsync(session); - Assert.Equal([3], store.Rewrites.Select(rewrite => rewrite.Ordinal)); - } - - [Fact] - public async Task ProvideChatHistory_AfterTruncate_ReturnsHeardTextNotProducedText() - { - // Arrange - var (provider, _, session) = await NewConversation(); - AppendTurn(provider, session, turnIndex: 0, "order 41?", "it ships Friday from the depot"); - - // Act - _ = provider.TruncateLastReply(session, "it ships Fri", TimeSpan.FromMilliseconds(300)); - - // Assert - var history = await ProvideAsync(provider, session); - Assert.Equal(["order 41?", "it ships Fri"], history.Select(message => message.Text)); - } - - /// - /// The barge-in lands while the turn it belongs to is still inside its own write. The write - /// chain is what orders the two: a rewrite that overtook the insert it targets would find no row - /// and leave the record holding words the caller never heard. - /// - [Fact] - public async Task TruncateLastReply_WhileTheAppendIsStillWriting_ReachesTheStoreAfterIt() - { - // Arrange - var store = new BlockingConversationStore(); - await store.CreateAsync(ConversationId, TestContext.Current.CancellationToken); - var provider = new AgentCoreChatHistoryProvider(store); - var session = new StubSession(); - provider.BeginConversation(session, ConversationId, []); - AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); - await provider.DrainAsync(session); - store.BlockNextAppend(); - AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday from the depot"); - await store.Entered; - - // Act - var cut = provider.TruncateLastReply(session, "it ships", TimeSpan.FromMilliseconds(90)); - store.Release(); - await provider.DrainAsync(session); - - // Assert - Assert.True(cut); - Assert.Equal( - ["hello", "hi there", "order 41?", "it ships"], - (await store.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); - } - /// - /// The held prompt of item 6a: the vendor is still speaking turn 0 when turn 1 begins, so the - /// reply the caller was hearing belongs to the turn before the one now open. ConversationSession decides - /// that a barge-in reaches it; the provider must not refuse because the turn moved on. + /// Pins what a barge-in does to the words the provider already wrote: which row it rewrites, and + /// when the rewrite is guaranteed to land after the append it corrects. /// - [Fact] - public async Task TruncateLastReply_AfterTheNextTurnOpened_CutsTheReplyTheCallerWasHearing() - { - // Arrange - var (provider, _, session) = await NewConversation(); - AppendTurn(provider, session, turnIndex: 0, "hello", "hi there caller"); - provider.BeginTurn(session, turnIndex: 1); - - // Act - var cut = provider.TruncateLastReply(session, "hi there", TimeSpan.FromMilliseconds(300)); - - // Assert - Assert.True(cut); - var history = await ProvideAsync(provider, session); - Assert.Equal(["hello", "hi there"], history.Select(message => message.Text)); - } - - /// - /// A model routinely writes a line and puts the tool call it announces on the same message, and a - /// graph row writes one reply for each node. The caller heard as much of the turn as the vendor - /// played and nothing else, so no earlier word of that turn may survive the cut as text the - /// caller is recorded as having heard. - /// - [Fact] - public async Task TruncateLastReply_TurnWithProseBesideAToolCall_DropsEveryWordButTheHeardOnes() - { - // Arrange - var (provider, store, session) = await NewConversation(); - provider.BeginTurn(session, turnIndex: 0); - ChatMessage announced = new( - ChatRole.Assistant, - [new TextContent("Let me check that for you"), new FunctionCallContent("conversation-1", "lookup")]); - provider.AppendTurn( - session, - [ - new ChatMessage(ChatRole.User, "how much?"), - announced, - new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", "50")]), - new ChatMessage(ChatRole.Assistant, "the price is fifty"), - ]); - - // Act - var cut = provider.TruncateLastReply(session, "the price", TimeSpan.FromMilliseconds(400)); - - // Assert - Assert.True(cut); - var history = await ProvideAsync(provider, session); - Assert.Equal(["how much?", string.Empty, string.Empty, "the price"], history.Select(m => m.Text)); - - // The side effect ran, so the pair stays. That is the rule the cut must not break. - Assert.Contains(history, m => m.Contents.OfType().Any()); - Assert.Contains(history, m => m.Contents.OfType().Any()); - - await provider.DrainAsync(session); - Assert.Equal([1, 3], store.Rewrites.Select(rewrite => rewrite.Ordinal)); - } - - [Fact] - public async Task TruncateLastReply_BeforeAnyReplyExists_NoOps() - { - // Arrange - var (provider, store, session) = await NewConversation(); - provider.BeginTurn(session, turnIndex: 0); - - // Act - var cut = provider.TruncateLastReply(session, "nothing was said", TimeSpan.Zero); - - // Assert - Assert.False(cut); - Assert.Empty(store.Rewrites); - Assert.Empty(await ProvideAsync(provider, session)); - } - - [Fact] - public async Task InMemoryStore_AfterTurnAndBargeIn_HoldsTheHeardTextInOrder() + public sealed class AgentCoreChatHistoryProviderTruncateTests { - // Arrange - var store = new InMemoryConversationStore(); - await store.CreateAsync(ConversationId, TestContext.Current.CancellationToken); - var provider = new AgentCoreChatHistoryProvider(store); - var session = new StubSession(); - provider.BeginConversation(session, ConversationId, []); - AppendTurn(provider, session, turnIndex: 0, "order 41?", "it ships Friday from the depot"); - - // Act - _ = provider.TruncateLastReply(session, "it ships", TimeSpan.FromMilliseconds(200)); - - // Assert - await provider.DrainAsync(session); - Assert.Equal( - ["order 41?", "it ships"], - (await store.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + [Fact] + public async Task TruncateLastReply_LastAssistantMessage_RewritesOnlyThatMessage() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, Fakes.RecordingConversationStore? store, StubSession? session) = await NewConversation(); + AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); + AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday from the depot"); + + // Act + bool cut = provider.TruncateLastReply(session, "it ships", TimeSpan.FromMilliseconds(420)); + + // Assert + Assert.True(cut); + IReadOnlyList history = await ProvideAsync(provider, session); + Assert.Equal( + ["hello", "hi there", "order 41?", "it ships"], + history.Select(message => message.Text)); + await provider.DrainAsync(session); + Assert.Equal([3], store.Rewrites.Select(rewrite => rewrite.Ordinal)); + } + + [Fact] + public async Task ProvideChatHistory_AfterTruncate_ReturnsHeardTextNotProducedText() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, Fakes.RecordingConversationStore _, StubSession? session) = await NewConversation(); + AppendTurn(provider, session, turnIndex: 0, "order 41?", "it ships Friday from the depot"); + + // Act + _ = provider.TruncateLastReply(session, "it ships Fri", TimeSpan.FromMilliseconds(300)); + + // Assert + IReadOnlyList history = await ProvideAsync(provider, session); + Assert.Equal(["order 41?", "it ships Fri"], history.Select(message => message.Text)); + } + + /// + /// The barge-in lands while the turn it belongs to is still inside its own write. The write + /// chain is what orders the two: a rewrite that overtook the insert it targets would find no row + /// and leave the record holding words the caller never heard. + /// + [Fact] + public async Task TruncateLastReply_WhileTheAppendIsStillWriting_ReachesTheStoreAfterIt() + { + // Arrange + BlockingConversationStore store = new(); + _ = await store.CreateAsync(ConversationId, TestContext.Current.CancellationToken); + AgentCoreChatHistoryProvider provider = new(store); + StubSession session = new(); + _ = provider.BeginConversation(session, ConversationId, []); + AppendTurn(provider, session, turnIndex: 0, "hello", "hi there"); + await provider.DrainAsync(session); + store.BlockNextAppend(); + AppendTurn(provider, session, turnIndex: 1, "order 41?", "it ships Friday from the depot"); + await store.Entered; + + // Act + bool cut = provider.TruncateLastReply(session, "it ships", TimeSpan.FromMilliseconds(90)); + store.Release(); + await provider.DrainAsync(session); + + // Assert + Assert.True(cut); + Assert.Equal( + ["hello", "hi there", "order 41?", "it ships"], + (await store.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + } + + /// + /// The held prompt of item 6a: the vendor is still speaking turn 0 when turn 1 begins, so the + /// reply the caller was hearing belongs to the turn before the one now open. ConversationSession decides + /// that a barge-in reaches it; the provider must not refuse because the turn moved on. + /// + [Fact] + public async Task TruncateLastReply_AfterTheNextTurnOpened_CutsTheReplyTheCallerWasHearing() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, Fakes.RecordingConversationStore _, StubSession? session) = await NewConversation(); + AppendTurn(provider, session, turnIndex: 0, "hello", "hi there caller"); + provider.BeginTurn(session, turnIndex: 1); + + // Act + bool cut = provider.TruncateLastReply(session, "hi there", TimeSpan.FromMilliseconds(300)); + + // Assert + Assert.True(cut); + IReadOnlyList history = await ProvideAsync(provider, session); + Assert.Equal(["hello", "hi there"], history.Select(message => message.Text)); + } + + /// + /// A model routinely writes a line and puts the tool call it announces on the same message, and a + /// graph row writes one reply for each node. The caller heard as much of the turn as the vendor + /// played and nothing else, so no earlier word of that turn may survive the cut as text the + /// caller is recorded as having heard. + /// + [Fact] + public async Task TruncateLastReply_TurnWithProseBesideAToolCall_DropsEveryWordButTheHeardOnes() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, Fakes.RecordingConversationStore? store, StubSession? session) = await NewConversation(); + provider.BeginTurn(session, turnIndex: 0); + ChatMessage announced = new( + ChatRole.Assistant, + [new TextContent("Let me check that for you"), new FunctionCallContent("conversation-1", "lookup")]); + _ = provider.AppendTurn( + session, + [ + new ChatMessage(ChatRole.User, "how much?"), + announced, + new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", "50")]), + new ChatMessage(ChatRole.Assistant, "the price is fifty"), + ]); + + // Act + bool cut = provider.TruncateLastReply(session, "the price", TimeSpan.FromMilliseconds(400)); + + // Assert + Assert.True(cut); + IReadOnlyList history = await ProvideAsync(provider, session); + Assert.Equal(["how much?", string.Empty, string.Empty, "the price"], history.Select(m => m.Text)); + + // The side effect ran, so the pair stays. That is the rule the cut must not break. + Assert.Contains(history, m => m.Contents.OfType().Any()); + Assert.Contains(history, m => m.Contents.OfType().Any()); + + await provider.DrainAsync(session); + Assert.Equal([1, 3], store.Rewrites.Select(rewrite => rewrite.Ordinal)); + } + + [Fact] + public async Task TruncateLastReply_BeforeAnyReplyExists_NoOps() + { + // Arrange + (AgentCoreChatHistoryProvider? provider, Fakes.RecordingConversationStore? store, StubSession? session) = await NewConversation(); + provider.BeginTurn(session, turnIndex: 0); + + // Act + bool cut = provider.TruncateLastReply(session, "nothing was said", TimeSpan.Zero); + + // Assert + Assert.False(cut); + Assert.Empty(store.Rewrites); + Assert.Empty(await ProvideAsync(provider, session)); + } + + [Fact] + public async Task InMemoryStore_AfterTurnAndBargeIn_HoldsTheHeardTextInOrder() + { + // Arrange + InMemoryConversationStore store = new(); + _ = await store.CreateAsync(ConversationId, TestContext.Current.CancellationToken); + AgentCoreChatHistoryProvider provider = new(store); + StubSession session = new(); + _ = provider.BeginConversation(session, ConversationId, []); + AppendTurn(provider, session, turnIndex: 0, "order 41?", "it ships Friday from the depot"); + + // Act + _ = provider.TruncateLastReply(session, "it ships", TimeSpan.FromMilliseconds(200)); + + // Assert + await provider.DrainAsync(session); + Assert.Equal( + ["order 41?", "it ships"], + (await store.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs b/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs index 67774023..77a8346a 100644 --- a/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs +++ b/tests/AgentCore.Application.Tests/Transcript/CapturingChatClient.cs @@ -1,66 +1,53 @@ -using System.Runtime.CompilerServices; -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Conversation; -using AgentCore.Application.Conversation.Memory; -using AgentCore.Application.Ports; -using AgentCore.Application.Runtime; -using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; -using AgentCore.Application.Transcript; -using AgentCore.TestSupport; -using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; -using Microsoft.Extensions.Logging; -using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// Answers each request in turn, keeps what it was asked, and runs a hook before answering. -/// Buffered path only, like . -internal sealed class CapturingChatClient : IChatClient +namespace AgentCore.Application.Tests.Transcript { - private readonly Func _beforeReply; - - private readonly string[] _replies; + /// Answers each request in turn, keeps what it was asked, and runs a hook before answering. + /// Buffered path only, like . + internal sealed class CapturingChatClient(Func beforeReply, params string[] replies) : IChatClient + { + private readonly Func _beforeReply = beforeReply; - private int _calls; + private readonly string[] _replies = replies; - public CapturingChatClient(Func beforeReply, params string[] replies) - { - _beforeReply = beforeReply; - _replies = replies; - } + private int _calls; - /// Gets every request this client answered, one role-prefixed line per message: its text, or its tool results. - public List> Requests { get; } = []; + /// Gets every request this client answered, one role-prefixed line per message: its text, or its tool results. + public List> Requests { get; } = []; - public async Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - var callIndex = _calls++; - Requests.Add([.. messages.Select(message => $"{message.Role}:{Words(message)}")]); + public async Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + int callIndex = _calls++; + Requests.Add([.. messages.Select(message => $"{message.Role}:{Words(message)}")]); - await _beforeReply(callIndex).ConfigureAwait(false); + await _beforeReply(callIndex).ConfigureAwait(false); - return new ChatResponse(new ChatMessage(ChatRole.Assistant, _replies[callIndex])); - } + return new ChatResponse(new ChatMessage(ChatRole.Assistant, _replies[callIndex])); + } - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - => throw new NotSupportedException("These facts drive the buffered path only."); + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException("These facts drive the buffered path only."); + } - private static string Words(ChatMessage message) - => message.Text.Length > 0 - ? message.Text - : string.Join("|", message.Contents.OfType().Select(result => result.Result?.ToString())); + private static string Words(ChatMessage message) + { + return message.Text.Length > 0 + ? message.Text + : string.Join("|", message.Contents.OfType().Select(result => result.Result?.ToString())); + } - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - public void Dispose() - { + public void Dispose() + { + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/CompiledHistoryProviderTests.cs b/tests/AgentCore.Application.Tests/Transcript/CompiledHistoryProviderTests.cs index eb0cdb25..753182c4 100644 --- a/tests/AgentCore.Application.Tests/Transcript/CompiledHistoryProviderTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/CompiledHistoryProviderTests.cs @@ -5,35 +5,34 @@ using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Where store 1 is bound: on the compiled agent of rows 1 and 2, and on nothing else. -/// -/// -/// -/// The provider is bound once, at compile time, so no run has to name a conversation to keep it — -/// which is what lets ThrowOnChatHistoryProviderConflict stay at the framework default. -/// -/// -/// Rows 3 and 4 must stay unbound. A node is handed the conversation in the request messages the turn loop -/// renders, and it runs on a session the workflow made rather than the conversation's, so store 1 on a node -/// is a second history source keyed on a session it does not know. -/// -/// -/// Every test here runs offline: no network conversation and no API key. -/// -/// -public sealed class CompiledHistoryProviderTests +namespace AgentCore.Application.Tests.Transcript { - private const string SingleAgentYaml = - """ + /// + /// Where store 1 is bound: on the compiled agent of rows 1 and 2, and on nothing else. + /// + /// + /// + /// The provider is bound once, at compile time, so no run has to name a conversation to keep it — + /// which is what lets ThrowOnChatHistoryProviderConflict stay at the framework default. + /// + /// + /// Rows 3 and 4 must stay unbound. A node is handed the conversation in the request messages the turn loop + /// renders, and it runs on a session the workflow made rather than the conversation's, so store 1 on a node + /// is a second history source keyed on a session it does not know. + /// + /// + /// Every test here runs offline: no network conversation and no API key. + /// + /// + public sealed class CompiledHistoryProviderTests + { + private const string SingleAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -43,8 +42,8 @@ public sealed class CompiledHistoryProviderTests agent: solo """; - private const string PolicyYaml = - """ + private const string PolicyYaml = + """ apiVersion: agentcore/v1 state: orderId: { type: string, writer: extractor, description: the order the caller asks about } @@ -65,8 +64,8 @@ public sealed class CompiledHistoryProviderTests - { id: done, agent: front, terminal: true } """; - private const string PatternGraphYaml = - """ + private const string PatternGraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -79,8 +78,8 @@ public sealed class CompiledHistoryProviderTests agents: [ researcher, responder ] """; - private const string ExplicitGraphYaml = - """ + private const string ExplicitGraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -96,322 +95,332 @@ public sealed class CompiledHistoryProviderTests - { from: route, to: answer } """; - /// What the caller says on the first turn of every multi-turn fact here. - private const string FirstUtterance = "where is my order"; - - /// What the caller says on the second turn. - private const string SecondUtterance = "and the second one?"; - - /// What the delegating agent asks the sub-agent, on both turns. - private const string DelegatedQuestion = "check the order system"; - - /// What the delegating agent tells the caller once the sub-agent has answered. - private const string FrontReply = "your order is on its way"; - - // --------------------------------------------------------------------------------------------- - // Hazard 3 and 4: which agents hold the provider, and that every row still constructs. - // --------------------------------------------------------------------------------------------- - [Theory] - [InlineData(SingleAgentYaml)] - [InlineData(PolicyYaml)] - public void ARowThatCarriesHistoryOnItsSession_BindsStoreOneToEveryCompiledAgent(string yaml) - { - using ToolCallingChatClient client = new("hello"); - - var compiled = Compile(yaml, client); - - Assert.NotEmpty(compiled.Agents); - Assert.All( - compiled.Agents.Values, - agent => Assert.Same(compiled.History, ChatClientAgentOf(agent).ChatHistoryProvider)); - } - - [Theory] - [InlineData(PatternGraphYaml)] - [InlineData(ExplicitGraphYaml)] - public void AGraphRow_BindsStoreOneToNoNodeAgent(string yaml) - { - using ToolCallingChatClient client = new("hello"); - - var compiled = Compile(yaml, client); - - // A ChatClientAgent that is handed no provider builds the framework's own in-memory one, which - // opens empty on each node session and never sees store 1. The fact is that store 1 is not - // there, not that nothing is. - Assert.NotEmpty(compiled.Agents); - Assert.All( - compiled.Agents.Values, - agent => Assert.IsNotType(ChatClientAgentOf(agent).ChatHistoryProvider)); - } - - // --------------------------------------------------------------------------------------------- - // The safety check the workaround switched off. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AModelThatKeepsTheHistoryItself_ConflictsWithStoreOne() - { - // A response that carries a conversation id is how a service says it keeps the history itself. - // That and store 1 are two answers to one question, and the framework refuses both at once. - // Switching this check off to buy something else — a telemetry attribute, say — leaves a conversation - // whose model silently sees one message and no history. - ServerSideHistoryChatClient client = new("hello"); - var compiled = Compile(SingleAgentYaml, client); - var agent = compiled.Agents["solo"]; - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - - var conflict = await Assert.ThrowsAsync( - () => agent.RunAsync("hi", session, options: null, TestContext.Current.CancellationToken)); - - Assert.Contains("ChatHistoryProvider", conflict.Message, StringComparison.Ordinal); - } - - // --------------------------------------------------------------------------------------------- - // Hazard 1: a workflow node reads the call once. - // --------------------------------------------------------------------------------------------- - [Theory] - [InlineData(PatternGraphYaml)] - [InlineData(ExplicitGraphYaml)] - public async Task AGraphRow_ReplaysTheConversationToItsNodesExactlyOnce(string yaml) - { - RecordingChatClient researcher = new("looking into it"); - RecordingChatClient responder = new("it ships Friday"); - var session = CreateSession(yaml, researcher, responder); - - _ = await session.RunTurnAsync(FirstUtterance, TestContext.Current.CancellationToken); - _ = await session.RunTurnAsync(SecondUtterance, TestContext.Current.CancellationToken); - - // One system message carries the whole call to a graph row, and it is the only way the conversation - // reaches a node. Two copies of the caller's words in one request is what a second history - // source on that node would look like. - Assert.Equal(1, Mentions(researcher.Requests[1], FirstUtterance)); - Assert.Equal(1, Mentions(responder.Requests[1], FirstUtterance)); - } - - // --------------------------------------------------------------------------------------------- - // Hazard 2: a delegated agent starts empty. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ADelegatedAgent_NeverReadsTheCallersTranscript() - { - DelegatingChatClient front = new(FrontReply); - RecordingChatClient specialist = new("the specialist answer"); - var session = CreateSession(PolicyYaml, front, specialist); - - _ = await session.RunTurnAsync(FirstUtterance, TestContext.Current.CancellationToken); - _ = await session.RunTurnAsync(SecondUtterance, TestContext.Current.CancellationToken); - - // Agent-as-tool is call and return: the inner run gets a fresh AgentSession, and store 1 keys - // on the session, so the second delegation opens on an empty history exactly like the first. - Assert.Equal(2, specialist.Requests.Count); - Assert.All( - specialist.Requests, - request => - { - Assert.Equal(1, Mentions(request, DelegatedQuestion)); - Assert.Equal(0, Mentions(request, FirstUtterance)); - Assert.Equal(0, Mentions(request, FrontReply)); - }); - } - - /// Counts the messages of one recorded request that carry a piece of text. - private static int Mentions(IEnumerable request, string text) - => request.Count(message => message.Contains(text, StringComparison.Ordinal)); - - /// Reads the under whatever the compiler wrapped it in. - private static ChatClientAgent ChatClientAgentOf(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner; - } - - private static CompiledAgent Compile(string yaml, IChatClient client) - => ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; - - /// Compiles one document over two named models and opens a conversation on it. - private static ConversationSession CreateSession(string yaml, IChatClient first, IChatClient second) - { - RoutingChatClientFactory chatClients = new(first); - chatClients.Route("researcher", first); - chatClients.Route("front", first); - chatClients.Route("responder", second); - chatClients.Route("specialist", second); - - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(chatClients))["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null).Create(); - } - - /// Answers with a conversation id, the way a service that keeps the history does. - private sealed class ServerSideHistoryChatClient : IChatClient - { - private readonly string _reply; - - public ServerSideHistoryChatClient(string reply) => _reply = reply; - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => Task.FromResult( - new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply)) { ConversationId = "server-side" }); - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - var responseId = Guid.NewGuid().ToString("N"); - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - ConversationId = "server-side", - }; - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - } - - /// Answers with one fixed line, and keeps every request it was handed. - private sealed class RecordingChatClient : IChatClient - { - private readonly string _reply; - - public RecordingChatClient(string reply) => _reply = reply; - - /// Gets each request, one role-prefixed line per message, in the order they arrived. - public List> Requests { get; } = []; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Record(messages); - await Task.Yield(); - - var responseId = Guid.NewGuid().ToString("N"); - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - }; - } - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Record(messages); - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - - private void Record(IEnumerable messages) - { - lock (Requests) - { - Requests.Add([.. messages.Select(message => $"{message.Role}:{message.Text}")]); - } - } - } - - /// - /// Calls the one tool it is offered on every turn, then answers. - /// - /// - /// delegates once per call, because it stops as soon as the - /// request carries any tool result. Store 1 of rows 1 and 2 keeps the finished tool pair, so on a - /// second turn that client would never delegate again — and a fact about the SECOND delegation - /// needs one that does. The rule here reads the last message instead: a request that ends on the - /// caller delegates, and a request that ends on the tool result answers. - /// - private sealed class DelegatingChatClient : IChatClient - { - private const string ConversationId = "conversation_1"; - - /// The one argument AsAIFunction() generates for an agent that declares no schema. - private static readonly Dictionary Arguments = - new(StringComparer.Ordinal) { ["query"] = DelegatedQuestion }; - - private readonly string _reply; - - public DelegatingChatClient(string reply) => _reply = reply; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); - - var responseId = Guid.NewGuid().ToString("N"); - // The turn's context provider appends a system message below the caller's words, so the - // caller's utterance is no longer the last message. Skip what the framework injected. - var last = messages.LastOrDefault(message => message.Role != ChatRole.System); - var tool = options?.Tools?.OfType().FirstOrDefault(); - - if (tool is not null && last?.Role == ChatRole.User) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent(ConversationId, tool.Name, Arguments)]) - { - ResponseId = responseId, - MessageId = responseId, - }; - - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - }; - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - } - } + /// What the caller says on the first turn of every multi-turn fact here. + private const string FirstUtterance = "where is my order"; + + /// What the caller says on the second turn. + private const string SecondUtterance = "and the second one?"; + + /// What the delegating agent asks the sub-agent, on both turns. + private const string DelegatedQuestion = "check the order system"; + + /// What the delegating agent tells the caller once the sub-agent has answered. + private const string FrontReply = "your order is on its way"; + + // --------------------------------------------------------------------------------------------- + // Hazard 3 and 4: which agents hold the provider, and that every row still constructs. + // --------------------------------------------------------------------------------------------- + [Theory] + [InlineData(SingleAgentYaml)] + [InlineData(PolicyYaml)] + public void ARowThatCarriesHistoryOnItsSession_BindsStoreOneToEveryCompiledAgent(string yaml) + { + using ToolCallingChatClient client = new("hello"); + + CompiledAgent compiled = Compile(yaml, client); + + Assert.NotEmpty(compiled.Agents); + Assert.All( + compiled.Agents.Values, + agent => Assert.Same(compiled.History, ChatClientAgentOf(agent).ChatHistoryProvider)); + } + + [Theory] + [InlineData(PatternGraphYaml)] + [InlineData(ExplicitGraphYaml)] + public void AGraphRow_BindsStoreOneToNoNodeAgent(string yaml) + { + using ToolCallingChatClient client = new("hello"); + + CompiledAgent compiled = Compile(yaml, client); + + // A ChatClientAgent that is handed no provider builds the framework's own in-memory one, which + // opens empty on each node session and never sees store 1. The fact is that store 1 is not + // there, not that nothing is. + Assert.NotEmpty(compiled.Agents); + Assert.All( + compiled.Agents.Values, + agent => Assert.IsNotType(ChatClientAgentOf(agent).ChatHistoryProvider)); + } + + // --------------------------------------------------------------------------------------------- + // The safety check the workaround switched off. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AModelThatKeepsTheHistoryItself_ConflictsWithStoreOne() + { + // A response that carries a conversation id is how a service says it keeps the history itself. + // That and store 1 are two answers to one question, and the framework refuses both at once. + // Switching this check off to buy something else — a telemetry attribute, say — leaves a conversation + // whose model silently sees one message and no history. + ServerSideHistoryChatClient client = new("hello"); + CompiledAgent compiled = Compile(SingleAgentYaml, client); + AIAgent agent = compiled.Agents["solo"]; + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + + InvalidOperationException conflict = await Assert.ThrowsAsync( + () => agent.RunAsync("hi", session, options: null, TestContext.Current.CancellationToken)); + + Assert.Contains("ChatHistoryProvider", conflict.Message, StringComparison.Ordinal); + } + + // --------------------------------------------------------------------------------------------- + // Hazard 1: a workflow node reads the call once. + // --------------------------------------------------------------------------------------------- + [Theory] + [InlineData(PatternGraphYaml)] + [InlineData(ExplicitGraphYaml)] + public async Task AGraphRow_ReplaysTheConversationToItsNodesExactlyOnce(string yaml) + { + RecordingChatClient researcher = new("looking into it"); + RecordingChatClient responder = new("it ships Friday"); + ConversationSession session = CreateSession(yaml, researcher, responder); + + _ = await session.RunTurnAsync(FirstUtterance, TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync(SecondUtterance, TestContext.Current.CancellationToken); + + // One system message carries the whole call to a graph row, and it is the only way the conversation + // reaches a node. Two copies of the caller's words in one request is what a second history + // source on that node would look like. + Assert.Equal(1, Mentions(researcher.Requests[1], FirstUtterance)); + Assert.Equal(1, Mentions(responder.Requests[1], FirstUtterance)); + } + + // --------------------------------------------------------------------------------------------- + // Hazard 2: a delegated agent starts empty. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ADelegatedAgent_NeverReadsTheCallersTranscript() + { + DelegatingChatClient front = new(FrontReply); + RecordingChatClient specialist = new("the specialist answer"); + ConversationSession session = CreateSession(PolicyYaml, front, specialist); + + _ = await session.RunTurnAsync(FirstUtterance, TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync(SecondUtterance, TestContext.Current.CancellationToken); + + // Agent-as-tool is call and return: the inner run gets a fresh AgentSession, and store 1 keys + // on the session, so the second delegation opens on an empty history exactly like the first. + Assert.Equal(2, specialist.Requests.Count); + Assert.All( + specialist.Requests, + request => + { + Assert.Equal(1, Mentions(request, DelegatedQuestion)); + Assert.Equal(0, Mentions(request, FirstUtterance)); + Assert.Equal(0, Mentions(request, FrontReply)); + }); + } + + /// Counts the messages of one recorded request that carry a piece of text. + private static int Mentions(IEnumerable request, string text) + { + return request.Count(message => message.Contains(text, StringComparison.Ordinal)); + } + + /// Reads the under whatever the compiler wrapped it in. + private static ChatClientAgent ChatClientAgentOf(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner; + } + + private static CompiledAgent Compile(string yaml, IChatClient client) + { + return ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory(client)))["main"]; + } + + /// Compiles one document over two named models and opens a conversation on it. + private static ConversationSession CreateSession(string yaml, IChatClient first, IChatClient second) + { + RoutingChatClientFactory chatClients = new(first); + _ = chatClients.Route("researcher", first); + _ = chatClients.Route("front", first); + _ = chatClients.Route("responder", second); + _ = chatClients.Route("specialist", second); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(chatClients))["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null).Create(); + } + + /// Answers with a conversation id, the way a service that keeps the history does. + private sealed class ServerSideHistoryChatClient(string reply) : IChatClient + { + private readonly string _reply = reply; + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + return Task.FromResult( + new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply)) { ConversationId = "server-side" }); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + + string responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + ConversationId = "server-side", + }; + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + } + + /// Answers with one fixed line, and keeps every request it was handed. + private sealed class RecordingChatClient(string reply) : IChatClient + { + private readonly string _reply = reply; + + /// Gets each request, one role-prefixed line per message, in the order they arrived. + public List> Requests { get; } = []; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + Record(messages); + await Task.Yield(); + + string responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + Record(messages); + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + + private void Record(IEnumerable messages) + { + lock (Requests) + { + Requests.Add([.. messages.Select(message => $"{message.Role}:{message.Text}")]); + } + } + } + + /// + /// Calls the one tool it is offered on every turn, then answers. + /// + /// + /// delegates once per call, because it stops as soon as the + /// request carries any tool result. Store 1 of rows 1 and 2 keeps the finished tool pair, so on a + /// second turn that client would never delegate again — and a fact about the SECOND delegation + /// needs one that does. The rule here reads the last message instead: a request that ends on the + /// caller delegates, and a request that ends on the tool result answers. + /// + private sealed class DelegatingChatClient(string reply) : IChatClient + { + private const string ConversationId = "conversation_1"; + + /// The one argument AsAIFunction() generates for an agent that declares no schema. + private static readonly Dictionary Arguments = + new(StringComparer.Ordinal) { ["query"] = DelegatedQuestion }; + + private readonly string _reply = reply; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); + + string responseId = Guid.NewGuid().ToString("N"); + // The turn's context provider appends a system message below the caller's words, so the + // caller's utterance is no longer the last message. Skip what the framework injected. + ChatMessage? last = messages.LastOrDefault(message => message.Role != ChatRole.System); + AIFunction? tool = options?.Tools?.OfType().FirstOrDefault(); + + if (tool is not null && last?.Role == ChatRole.User) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent(ConversationId, tool.Name, Arguments)]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs index 5bf01529..df15ff38 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionEditTests.cs @@ -1,153 +1,146 @@ -using System.Runtime.CompilerServices; -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; -using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; using AgentCore.Domain.Audit; using AgentCore.TestSupport; -using Microsoft.Agents.AI.Compaction; -using Microsoft.Extensions.AI; -using Microsoft.Extensions.Logging; using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// An edit against a conversation that carries a summary: cut above what the summary covers, -/// or reach under it and take the summary with the tail. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class ConversationSessionCompactionEditTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task ATurn_EditingAMessageUnderTheSummary_CutsTheStoreFirst_AndReadsBackOnlyWhatSurvived() - { - var store = new CountingReads(new InMemoryConversationStore()); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a0, rewritten reply"); - RecordingObserver observer = new(); - var session = CreateSession( - reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), observer: observer); - - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // Turns 0 and 1 (q0/a0, q1/a1) are under the summary (D11: turn 2 stayed live as the newest - // existing turn). "m-0-a" — turn 0's reply — sits inside that span. - Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo == 3); - store.RowsRead.Clear(); - - await session.RunTurnAtOriginAsync( - "q0, rewritten", - new ConversationTurnOrigin("caller-2", "m-0-a") { NamesParent = true }, - TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // The session's view is the raw rows again: the cut row's parent and the rewritten turn, - // nothing from the dropped summary and nothing that was cut. - var view = session.Compiled.History.Read(session.AgentSession!).Select(message => message.Text).ToList(); - Assert.Equal(["q0", "a0", "q0, rewritten", "a0, rewritten reply"], view); - Assert.Equal(view, (await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); - Assert.Null(session.Compiled.History.Summary(session.AgentSession!)); - - // The store handed the session the two rows the cut kept, not the eight it held before the - // cut; the last read is this test's own. - Assert.Equal([2, 4], store.RowsRead); - - // Turns 1 through 3 (q1/a1, q2/a2, q3/a3) went, and the trail says so even though the session - // never held turn 1's rows. - var superseded = Assert.Single(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); - Assert.Equal("1", superseded.Payload![AuditPayloadKeys.WithdrewFromTurnIndex]); - Assert.Equal("3", superseded.Payload[AuditPayloadKeys.WithdrewThroughTurnIndex]); - } - - [Fact] - public async Task ATurn_EditingAMessageTheStoreDoesNotHold_CutsNothing_AndKeepsTheSummary() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a4"); - RecordingObserver observer = new(); - var session = CreateSession( - reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), observer: observer); - - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - await session.RunTurnAtOriginAsync( - "q4", - new ConversationTurnOrigin("caller-2", "nobody") { NamesParent = true }, - TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // Nothing went: the summary stands, and the turn compacts again over it (D11: q3/a3 was the - // newest existing turn, so it stays live and the summary now covers everything before it). - Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q3", "assistant:a3", "user:q4"], reply.Requests[1]); - Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo == 5); - Assert.Equal(10, (await store.ReadAllAsync("c1", TestContext.Current.CancellationToken)).Count); - Assert.DoesNotContain(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); - } - - [Fact] - public async Task ATurn_EditingAMessageAboveTheSummary_CutsTheTailAndKeepsTheSummary() + /// + /// An edit against a conversation that carries a summary: cut above what the summary covers, + /// or reach under it and take the summary with the tail. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class ConversationSessionCompactionEditTests { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a3, rewritten reply"); - var session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0)); - - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // The edit hangs off a2 (ordinal 5), above what the summary covers (3) and below the summary's - // own ordinal (6). The cut takes q3/a3 (7, 8) and leaves the summary standing. - await session.RunTurnAtOriginAsync( - "q3, rewritten", - new ConversationTurnOrigin("caller-2", "m-2-a") { NamesParent = true }, - TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - Assert.Equal( - ["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3, rewritten"], - reply.Requests[1]); - var forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); - Assert.Single(forSession, row => row.CoversUpTo == 3); - Assert.Equal([4, 5, 6, 9, 10], forSession.Select(row => row.Ordinal)); - } + [Fact] + public async Task ATurn_EditingAMessageUnderTheSummary_CutsTheStoreFirst_AndReadsBackOnlyWhatSurvived() + { + CountingReads store = new(new InMemoryConversationStore()); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + CapturingChatClient reply = new(_ => Task.CompletedTask, "a3", "a0, rewritten reply"); + RecordingObserver observer = new(); + ConversationSession session = CreateSession( + reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), observer: observer); + + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // Turns 0 and 1 (q0/a0, q1/a1) are under the summary (D11: turn 2 stayed live as the newest + // existing turn). "m-0-a" — turn 0's reply — sits inside that span. + _ = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo == 3); + store.RowsRead.Clear(); + + _ = await session.RunTurnAtOriginAsync( + "q0, rewritten", + new ConversationTurnOrigin("caller-2", "m-0-a") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The session's view is the raw rows again: the cut row's parent and the rewritten turn, + // nothing from the dropped summary and nothing that was cut. + List view = [.. session.Compiled.History.Read(session.AgentSession!).Select(message => message.Text)]; + Assert.Equal(["q0", "a0", "q0, rewritten", "a0, rewritten reply"], view); + Assert.Equal(view, (await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken)).Select(row => row.Content.Text)); + Assert.Null(session.Compiled.History.Summary(session.AgentSession!)); + + // The store handed the session the two rows the cut kept, not the eight it held before the + // cut; the last read is this test's own. + Assert.Equal([2, 4], store.RowsRead); + + // Turns 1 through 3 (q1/a1, q2/a2, q3/a3) went, and the trail says so even though the session + // never held turn 1's rows. + ConversationEvent superseded = Assert.Single(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); + Assert.Equal("1", superseded.Payload![AuditPayloadKeys.WithdrewFromTurnIndex]); + Assert.Equal("3", superseded.Payload[AuditPayloadKeys.WithdrewThroughTurnIndex]); + } - /// Notes how many rows each read handed back. - private sealed class CountingReads(IConversationStore inner) : DelegatingConversationStore(inner) - { - public List RowsRead { get; } = []; + [Fact] + public async Task ATurn_EditingAMessageTheStoreDoesNotHold_CutsNothing_AndKeepsTheSummary() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + CapturingChatClient reply = new(_ => Task.CompletedTask, "a3", "a4"); + RecordingObserver observer = new(); + ConversationSession session = CreateSession( + reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), observer: observer); + + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + _ = await session.RunTurnAtOriginAsync( + "q4", + new ConversationTurnOrigin("caller-2", "nobody") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // Nothing went: the summary stands, and the turn compacts again over it (D11: q3/a3 was the + // newest existing turn, so it stays live and the summary now covers everything before it). + Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q3", "assistant:a3", "user:q4"], reply.Requests[1]); + _ = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo == 5); + Assert.Equal(10, (await store.ReadAllAsync("c1", TestContext.Current.CancellationToken)).Count); + Assert.DoesNotContain(observer.Events, raised => raised.Kind == ConversationEventKind.TurnSuperseded); + } - public override async ValueTask> ReadForSessionAsync(string conversationId, CancellationToken cancellationToken = default) - => Note(await base.ReadForSessionAsync(conversationId, cancellationToken)); + [Fact] + public async Task ATurn_EditingAMessageAboveTheSummary_CutsTheTailAndKeepsTheSummary() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + CapturingChatClient reply = new(_ => Task.CompletedTask, "a3", "a3, rewritten reply"); + ConversationSession session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0)); + + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The edit hangs off a2 (ordinal 5), above what the summary covers (3) and below the summary's + // own ordinal (6). The cut takes q3/a3 (7, 8) and leaves the summary standing. + _ = await session.RunTurnAtOriginAsync( + "q3, rewritten", + new ConversationTurnOrigin("caller-2", "m-2-a") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal( + ["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3, rewritten"], + reply.Requests[1]); + IReadOnlyList forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); + _ = Assert.Single(forSession, row => row.CoversUpTo == 3); + Assert.Equal([4, 5, 6, 9, 10], forSession.Select(row => row.Ordinal)); + } - private IReadOnlyList Note(IReadOnlyList rows) + /// Notes how many rows each read handed back. + private sealed class CountingReads(IConversationStore inner) : DelegatingConversationStore(inner) { - RowsRead.Add(rows.Count); - return rows; + public List RowsRead { get; } = []; + + public override async ValueTask> ReadForSessionAsync(string conversationId, CancellationToken cancellationToken = default) + { + return Note(await base.ReadForSessionAsync(conversationId, cancellationToken)); + } + + private IReadOnlyList Note(IReadOnlyList rows) + { + RowsRead.Add(rows.Count); + return rows; + } } } -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs index d1ff04c5..8a109bd3 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionFailureTests.cs @@ -1,15 +1,10 @@ -using System.Runtime.CompilerServices; -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; -using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; +using AgentCore.Domain; using AgentCore.TestSupport; using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; @@ -17,146 +12,151 @@ using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Compaction that goes wrong costs the conversation nothing: a strategy that throws, one whose -/// output is not one summary, a refused row write, and words that move under the summariser. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class ConversationSessionCompactionFailureTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task CompactAsync_AStrategyThatThrows_LeavesTheTurnAndTheStoreUntouched_AndLogsEvent26() + /// + /// Compaction that goes wrong costs the conversation nothing: a strategy that throws, one whose + /// output is not one summary, a refused row write, and words that move under the summariser. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class ConversationSessionCompactionFailureTests { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - - var loggerFactory = new RecordingLoggerFactory(); - var session = CreateSession( - new ScriptedChatClient("a2"), store, conversationId: "c1", logger: loggerFactory.CreateLogger("test"), - compaction: SummaryOnly(new ThrowingCompactionStrategy())); - - var result = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - Assert.Null(result.Failure); - Assert.Equal("a2", result.ReplyText); - Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - Assert.Single(loggerFactory.Of(26)); - } + [Fact] + public async Task CompactAsync_AStrategyThatThrows_LeavesTheTurnAndTheStoreUntouched_AndLogsEvent26() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + + RecordingLoggerFactory loggerFactory = new(); + ConversationSession session = CreateSession( + new ScriptedChatClient("a2"), store, conversationId: "c1", logger: loggerFactory.CreateLogger("test"), + compaction: SummaryOnly(new ThrowingCompactionStrategy())); + + TurnResult result = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Null(result.Failure); + Assert.Equal("a2", result.ReplyText); + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + _ = Assert.Single(loggerFactory.Of(26)); + } - [Fact] - public async Task CompactAsync_AStrategyWhoseOutputIsNotOneSummary_KeepsTheView_AndLogsEvent27() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - - var loggerFactory = new RecordingLoggerFactory(); - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a2"); - var session = CreateSession( - reply, store, conversationId: "c1", logger: loggerFactory.CreateLogger("test"), - compaction: SummaryOnly(new TruncatingCompactionStrategy())); - - await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - Assert.Equal(["user:q0", "assistant:a0", "user:q1", "assistant:a1", "user:q2"], Assert.Single(reply.Requests)); - Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - Assert.Single(loggerFactory.Of(27)); - } + [Fact] + public async Task CompactAsync_AStrategyWhoseOutputIsNotOneSummary_KeepsTheView_AndLogsEvent27() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + + RecordingLoggerFactory loggerFactory = new(); + CapturingChatClient reply = new(_ => Task.CompletedTask, "a2"); + ConversationSession session = CreateSession( + reply, store, conversationId: "c1", logger: loggerFactory.CreateLogger("test"), + compaction: SummaryOnly(new TruncatingCompactionStrategy())); + + _ = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal(["user:q0", "assistant:a0", "user:q1", "assistant:a1", "user:q2"], Assert.Single(reply.Requests)); + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + _ = Assert.Single(loggerFactory.Of(27)); + } - [Fact] - public async Task CompactAsync_TheRowWriteFails_IsReportedAsADroppedWriteAndTheTurnStands() - { - var store = new RefusingSummaryWrite(new InMemoryConversationStore()); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - RecordingObserver observer = new(); - var session = CreateSession( - new ScriptedChatClient("a3"), store, conversationId: "c1", - compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), - observer: observer); - - var result = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - Assert.Equal("a3", result.ReplyText); - var dropped = Assert.Single(observer.Events, conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptWriteFailed); - Assert.Null(dropped.EventId); - Assert.Contains("summary row refused", dropped.Payload![ConversationEventPayloadKeys.Reason], StringComparison.Ordinal); - - // The words landed; only the summary did not. - Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - Assert.Equal(8, (await store.ReadAllAsync("c1", TestContext.Current.CancellationToken)).Count); - } + [Fact] + public async Task CompactAsync_TheRowWriteFails_IsReportedAsADroppedWriteAndTheTurnStands() + { + RefusingSummaryWrite store = new(new InMemoryConversationStore()); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + RecordingObserver observer = new(); + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), store, conversationId: "c1", + compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0), + observer: observer); + + TurnResult result = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal("a3", result.ReplyText); + ConversationEvent dropped = Assert.Single(observer.Events, conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptWriteFailed); + Assert.Null(dropped.EventId); + Assert.Contains("summary row refused", dropped.Payload![ConversationEventPayloadKeys.Reason], StringComparison.Ordinal); + + // The words landed; only the summary did not. + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Equal(8, (await store.ReadAllAsync("c1", TestContext.Current.CancellationToken)).Count); + } - [Fact] - public async Task CompactAsync_WordsMoveWhileTheSummariserRuns_TheSummaryIsRefused() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - ConversationSession? session = null; - var strategy = new BargingCompactionStrategy( - new SummarizationCompactionStrategy(new ScriptedChatClient("the gist of it"), CompactionTriggers.Always, minimumPreservedGroups: 0), - () => session!.Compiled.History.AppendTurn(session.AgentSession!, [new ChatMessage(ChatRole.User, "barged in")])); - session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: SummaryOnly(strategy)); - - var result = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - Assert.Equal("a3", result.ReplyText); - Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - Assert.Null(session.Compiled.History.Summary(session.AgentSession!)); - Assert.Contains(await store.ReadAllAsync("c1", TestContext.Current.CancellationToken), row => row.Content.Text == "barged in"); - } + [Fact] + public async Task CompactAsync_WordsMoveWhileTheSummariserRuns_TheSummaryIsRefused() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + ConversationSession? session = null; + BargingCompactionStrategy strategy = new( + new SummarizationCompactionStrategy(new ScriptedChatClient("the gist of it"), CompactionTriggers.Always, minimumPreservedGroups: 0), + () => session!.Compiled.History.AppendTurn(session.AgentSession!, [new ChatMessage(ChatRole.User, "barged in")])); + session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: SummaryOnly(strategy)); + + TurnResult result = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + Assert.Equal("a3", result.ReplyText); + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Null(session.Compiled.History.Summary(session.AgentSession!)); + Assert.Contains(await store.ReadAllAsync("c1", TestContext.Current.CancellationToken), row => row.Content.Text == "barged in"); + } - /// A store that refuses to write a summary row and takes every other row. - private sealed class RefusingSummaryWrite(IConversationStore inner) : DelegatingConversationStore(inner) - { - public override ValueTask> AppendAsync( - string conversationId, IReadOnlyList messages, ConversationSessionState? state = null, CancellationToken cancellationToken = default) - => messages.Any(draft => draft.CoversUpTo is not null) - ? throw new InvalidOperationException("summary row refused") - : base.AppendAsync(conversationId, messages, state, cancellationToken); - } + /// A store that refuses to write a summary row and takes every other row. + private sealed class RefusingSummaryWrite(IConversationStore inner) : DelegatingConversationStore(inner) + { + public override ValueTask> AppendAsync( + string conversationId, IReadOnlyList messages, ConversationSessionState? state = null, CancellationToken cancellationToken = default) + { + return messages.Any(draft => draft.CoversUpTo is not null) + ? throw new InvalidOperationException("summary row refused") + : base.AppendAsync(conversationId, messages, state, cancellationToken); + } + } - /// A strategy that always fires and always throws, to prove a failed compaction costs the turn nothing. - private sealed class ThrowingCompactionStrategy() : CompactionStrategy(CompactionTriggers.Always) - { - protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) - => throw new InvalidOperationException("the summariser is down"); - } + /// A strategy that always fires and always throws, to prove a failed compaction costs the turn nothing. + private sealed class ThrowingCompactionStrategy() : CompactionStrategy(CompactionTriggers.Always) + { + protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + { + throw new InvalidOperationException("the summariser is down"); + } + } - /// Drops the oldest group and inserts nothing: a shape no summary row can stand for. - private sealed class TruncatingCompactionStrategy() : CompactionStrategy(CompactionTriggers.Always) - { - protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + /// Drops the oldest group and inserts nothing: a shape no summary row can stand for. + private sealed class TruncatingCompactionStrategy() : CompactionStrategy(CompactionTriggers.Always) { - index.Groups[0].IsExcluded = true; - return new(true); + protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + { + index.Groups[0].IsExcluded = true; + return new(true); + } } - } - /// Moves the words before forwarding to , as a writer racing the compaction would. - private sealed class BargingCompactionStrategy(CompactionStrategy inner, Action bargeIn) : CompactionStrategy(CompactionTriggers.Always) - { - protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + /// Moves the words before forwarding to , as a writer racing the compaction would. + private sealed class BargingCompactionStrategy(CompactionStrategy inner, Action bargeIn) : CompactionStrategy(CompactionTriggers.Always) { - bargeIn(); - return inner.CompactAsync(index, logger, cancellationToken); + protected override ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + { + bargeIn(); + return inner.CompactAsync(index, logger, cancellationToken); + } } } -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs index 0cd8e023..1dfb3209 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs @@ -1,6 +1,6 @@ -using System.Runtime.CompilerServices; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; @@ -8,7 +8,6 @@ using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; using AgentCore.TestSupport; using Microsoft.Agents.AI.Compaction; @@ -16,79 +15,84 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// Builds the session and seeds the store the compaction facts run against. -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -internal static class ConversationSessionCompactionTestSupport +namespace AgentCore.Application.Tests.Transcript { - /// - /// The stages the agent runs in place of the window-derived ones: sized to fire on a handful of - /// fixture messages. - /// - /// The reply model's window, in tokens. The fixed stages fire at 75% of it (D7). - internal static ConversationSession CreateSession( - IChatClient reply, IConversationStore store, string? conversationId = null, ILogger? logger = null, CompactionStages? compaction = null, int contextWindow = 128_000, IConversationObserver? observer = null) + /// Builds the session and seeds the store the compaction facts run against. +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + internal static class ConversationSessionCompactionTestSupport { - var document = ConfigurationLoader.LoadYaml(ConversationSessionResumeTestSupport.OneAgentYaml); - var chatClients = new FakeChatClientFactory(reply, contextWindow); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - ConversationStore = store, - Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), - Compaction = compaction, - })["main"]; + /// + /// The stages the agent runs in place of the window-derived ones: sized to fire on a handful of + /// fixture messages. + /// + /// The reply model's window, in tokens. The fixed stages fire at 75% of it (D7). + internal static ConversationSession CreateSession( + IChatClient reply, IConversationStore store, string? conversationId = null, ILogger? logger = null, CompactionStages? compaction = null, int contextWindow = 128_000, IConversationObserver? observer = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(ConversationSessionResumeTestSupport.OneAgentYaml); + FakeChatClientFactory chatClients = new(reply, contextWindow); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + ConversationStore = store, + Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), + Compaction = compaction, + })["main"]; - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null, - logger: logger, - observers: observer is null ? [] : [observer]); + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null, + logger: logger, + observers: observer is null ? [] : [observer]); - return factory.Create(conversationId); - } + return factory.Create(conversationId); + } - /// Stages whose cap never fires and whose summary always does. - internal static CompactionStages Summary(IChatClient summariser, int minimumPreservedGroups) - => SummaryOnly(new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups)); + /// Stages whose cap never fires and whose summary always does. + internal static CompactionStages Summary(IChatClient summariser, int minimumPreservedGroups) + { + return SummaryOnly(new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups)); + } - /// Stages whose cap never fires. - internal static CompactionStages SummaryOnly(CompactionStrategy summary) - => new(new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 1), summary); + /// Stages whose cap never fires. + internal static CompactionStages SummaryOnly(CompactionStrategy summary) + { + return new(new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 1), summary); + } - /// Seeds one turn of a plain question and reply, two rows. - internal static async Task SeedPlainTurnAsync(IConversationStore store, int turnIndex, string question, string reply) - { - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, question), $"m-{turnIndex}-q"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, reply), $"m-{turnIndex}-a"), - ], - new ConversationSessionState { NextTurnIndex = turnIndex + 1 }, - TestContext.Current.CancellationToken); - } + /// Seeds one turn of a plain question and reply, two rows. + internal static async Task SeedPlainTurnAsync(IConversationStore store, int turnIndex, string question, string reply) + { + _ = await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, question), $"m-{turnIndex}-q"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, reply), $"m-{turnIndex}-a"), + ], + new ConversationSessionState { NextTurnIndex = turnIndex + 1 }, + TestContext.Current.CancellationToken); + } - /// Seeds one turn of a question, a tool call and its result, and a reply — four rows. - internal static async Task SeedToolTurnAsync( - InMemoryConversationStore store, int turnIndex, string question, string toolName, string callId, string result, string reply) - { - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, question), $"m-{turnIndex}-q"), - new ConversationMessageDraft( - turnIndex, - new ChatMessage(ChatRole.Assistant, [new FunctionCallContent(callId, toolName, new Dictionary(StringComparer.Ordinal))]), - $"m-{turnIndex}-call"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Tool, [new FunctionResultContent(callId, result)]), $"m-{turnIndex}-result"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, reply), $"m-{turnIndex}-a"), - ], - new ConversationSessionState { NextTurnIndex = turnIndex + 1 }, - TestContext.Current.CancellationToken); + /// Seeds one turn of a question, a tool call and its result, and a reply — four rows. + internal static async Task SeedToolTurnAsync( + InMemoryConversationStore store, int turnIndex, string question, string toolName, string callId, string result, string reply) + { + _ = await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, question), $"m-{turnIndex}-q"), + new ConversationMessageDraft( + turnIndex, + new ChatMessage(ChatRole.Assistant, [new FunctionCallContent(callId, toolName, new Dictionary(StringComparer.Ordinal))]), + $"m-{turnIndex}-call"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Tool, [new FunctionResultContent(callId, result)]), $"m-{turnIndex}-result"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, reply), $"m-{turnIndex}-a"), + ], + new ConversationSessionState { NextTurnIndex = turnIndex + 1 }, + TestContext.Current.CancellationToken); + } } -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs index 3e23e1a5..bce9e062 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs @@ -1,192 +1,186 @@ -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; -using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Runtime.Compaction; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.Application.Transcript; using AgentCore.TestSupport; using Microsoft.Agents.AI.Compaction; using Microsoft.Extensions.AI; -using Microsoft.Extensions.Logging; using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Compaction driven end to end through a real session: the summary a real MAF strategy produces -/// lands as one row before the firing turn's own model call, is read back by the next session, -/// survives a barge-in, and a strategy that throws costs the conversation nothing. -/// -#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. -public sealed class ConversationSessionCompactionTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task TheFiringTurn_CallsTheSummariserOnce_AndSendsTheSummaryInItsOwnRequest() + /// + /// Compaction driven end to end through a real session: the summary a real MAF strategy produces + /// lands as one row before the firing turn's own model call, is read back by the next session, + /// survives a barge-in, and a strategy that throws costs the conversation nothing. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class ConversationSessionCompactionTests { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - var summariser = new CapturingChatClient(_ => Task.CompletedTask, "the gist of it"); - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3"); - var session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(summariser, minimumPreservedGroups: 0)); - - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - Assert.Single(summariser.Requests); - - // Turn 2 (q2/a2) is the newest existing turn and stays live (D11); turns 0 and 1 go under the summary. - Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3"], Assert.Single(reply.Requests)); - - var forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); - var summary = Assert.Single(forSession, row => row.CoversUpTo is not null); - Assert.Equal((6, 3, 3), (summary.Ordinal, summary.CoversUpTo, summary.TurnIndex)); - Assert.Equal([4, 5, 6, 7, 8], forSession.Select(row => row.Ordinal)); - } + [Fact] + public async Task TheFiringTurn_CallsTheSummariserOnce_AndSendsTheSummaryInItsOwnRequest() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - [Fact] - public async Task ASecondSummary_FoldsTheFirstIntoItself_AndOneRowStands() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - var summariser = new CapturingChatClient(_ => Task.CompletedTask, "SUMMARY-ONE", "SUMMARY-TWO"); - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a3", "a4"); - var session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(summariser, minimumPreservedGroups: 0)); - - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.RunTurnAsync("q4", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // The second summariser call read the first summary, and the rows above it that came under the floor. - Assert.Equal(2, summariser.Requests.Count); - Assert.Equal(["assistant:[Summary]\nSUMMARY-ONE", "user:q2", "assistant:a2"], summariser.Requests[1].Skip(1)); - Assert.Equal(["assistant:[Summary]\nSUMMARY-TWO", "user:q3", "assistant:a3", "user:q4"], reply.Requests[1]); - - var forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); - var summary = Assert.Single(forSession, row => row.CoversUpTo is not null); - Assert.Equal((9, 5), (summary.Ordinal, summary.CoversUpTo)); - Assert.Contains("SUMMARY-TWO", summary.Content.Text, StringComparison.Ordinal); - Assert.DoesNotContain(forSession, row => row.Content.Text.Contains("SUMMARY-ONE", StringComparison.Ordinal)); - } + CapturingChatClient summariser = new(_ => Task.CompletedTask, "the gist of it"); + CapturingChatClient reply = new(_ => Task.CompletedTask, "a3"); + ConversationSession session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(summariser, minimumPreservedGroups: 0)); - [Fact] - public async Task TheSummary_ReadsTheCappedResults_AndCoversTheirRows() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedToolTurnAsync(store, turnIndex: 0, "q0", "toolA", "call-0", "result-A", "a0"); - await SeedToolTurnAsync(store, turnIndex: 1, "q1", "toolB", "call-1", "result-B", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - // Cap every result to 3 characters; summarise all but the newest four groups, which are - // q1 (call-1 + result-1) a1: the summary takes q0, its tool group and a0, rows 0-3. - var summariser = new CapturingChatClient(_ => Task.CompletedTask, "the gist of it"); - var stages = new CompactionStages( - new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), - new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups: 3)); - var session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: stages); - - await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - var request = Assert.Single(summariser.Requests); - Assert.Contains("tool:res…", request); - Assert.DoesNotContain("tool:result-A", request); - - var summary = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - Assert.Equal(3, summary.CoversUpTo); - } + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); - [Fact] - public async Task ACapOnlyStage_WritesNoRow_AndTheRequestCarriesTheCappedResults() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedToolTurnAsync(store, turnIndex: 0, "q0", "toolA", "call-0", "result-A", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a2"); - var stages = new CompactionStages( - new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), - new SummarizationCompactionStrategy(new ScriptedChatClient("never"), CompactionTriggers.Never)); - var session = CreateSession(reply, store, conversationId: "c1", compaction: stages); - - await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - var request = Assert.Single(reply.Requests); - Assert.Contains("tool:res…", request); - Assert.DoesNotContain("tool:result-A", request); - - Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - var stored = await store.ReadAllAsync("c1", TestContext.Current.CancellationToken); - Assert.Equal(8, stored.Count); - Assert.Contains(stored, row => row.Content.Contents.OfType().Any(result => result.Result?.ToString() == "result-A")); - } + _ = Assert.Single(summariser.Requests); - [Fact] - public async Task ATurn_WhoseViewCrossesThreeQuartersOfTheWindow_FiresTheRealPipeline() - { - // A 400-token window fires at 300 and stops at 200 (D7). One short turn stays well under; - // twelve turns of ~80 characters each land well over. - const int Window = 400; - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + // Turn 2 (q2/a2) is the newest existing turn and stays live (D11); turns 0 and 1 go under the summary. + Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3"], Assert.Single(reply.Requests)); - var quiet = CreateSession(new ScriptedChatClient("a1"), store, conversationId: "c1", contextWindow: Window); - await quiet.RunTurnAsync("q1", TestContext.Current.CancellationToken); - await quiet.FlushTranscriptAsync(); + IReadOnlyList forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); + ConversationMessage summary = Assert.Single(forSession, row => row.CoversUpTo is not null); + Assert.Equal((6, 3, 3), (summary.Ordinal, summary.CoversUpTo, summary.TurnIndex)); + Assert.Equal([4, 5, 6, 7, 8], forSession.Select(row => row.Ordinal)); + } - Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + [Fact] + public async Task ASecondSummary_FoldsTheFirstIntoItself_AndOneRowStands() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + CapturingChatClient summariser = new(_ => Task.CompletedTask, "SUMMARY-ONE", "SUMMARY-TWO"); + CapturingChatClient reply = new(_ => Task.CompletedTask, "a3", "a4"); + ConversationSession session = CreateSession(reply, store, conversationId: "c1", compaction: Summary(summariser, minimumPreservedGroups: 0)); + + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("q4", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The second summariser call read the first summary, and the rows above it that came under the floor. + Assert.Equal(2, summariser.Requests.Count); + Assert.Equal(["assistant:[Summary]\nSUMMARY-ONE", "user:q2", "assistant:a2"], summariser.Requests[1].Skip(1)); + Assert.Equal(["assistant:[Summary]\nSUMMARY-TWO", "user:q3", "assistant:a3", "user:q4"], reply.Requests[1]); + + IReadOnlyList forSession = await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken); + ConversationMessage summary = Assert.Single(forSession, row => row.CoversUpTo is not null); + Assert.Equal((9, 5), (summary.Ordinal, summary.CoversUpTo)); + Assert.Contains("SUMMARY-TWO", summary.Content.Text, StringComparison.Ordinal); + Assert.DoesNotContain(forSession, row => row.Content.Text.Contains("SUMMARY-ONE", StringComparison.Ordinal)); + } - var padding = new string('w', 80); - for (var turn = 2; turn < 14; turn++) + [Fact] + public async Task TheSummary_ReadsTheCappedResults_AndCoversTheirRows() { - await SeedPlainTurnAsync(store, turn, $"q{turn} {padding}", $"a{turn} {padding}"); + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedToolTurnAsync(store, turnIndex: 0, "q0", "toolA", "call-0", "result-A", "a0"); + await SeedToolTurnAsync(store, turnIndex: 1, "q1", "toolB", "call-1", "result-B", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + // Cap every result to 3 characters; summarise all but the newest four groups, which are + // q1 (call-1 + result-1) a1: the summary takes q0, its tool group and a0, rows 0-3. + CapturingChatClient summariser = new(_ => Task.CompletedTask, "the gist of it"); + CompactionStages stages = new( + new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), + new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups: 3)); + ConversationSession session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: stages); + + _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + List request = Assert.Single(summariser.Requests); + Assert.Contains("tool:res…", request); + Assert.DoesNotContain("tool:result-A", request); + + ConversationMessage summary = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Equal(3, summary.CoversUpTo); } - var loud = CreateSession(new ScriptedChatClient("the gist of it"), store, conversationId: "c1", contextWindow: Window); - await loud.RunTurnAsync("q14", TestContext.Current.CancellationToken); - await loud.FlushTranscriptAsync(); + [Fact] + public async Task ACapOnlyStage_WritesNoRow_AndTheRequestCarriesTheCappedResults() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedToolTurnAsync(store, turnIndex: 0, "q0", "toolA", "call-0", "result-A", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + + CapturingChatClient reply = new(_ => Task.CompletedTask, "a2"); + CompactionStages stages = new( + new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), + new SummarizationCompactionStrategy(new ScriptedChatClient("never"), CompactionTriggers.Never)); + ConversationSession session = CreateSession(reply, store, conversationId: "c1", compaction: stages); + + _ = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + List request = Assert.Single(reply.Requests); + Assert.Contains("tool:res…", request); + Assert.DoesNotContain("tool:result-A", request); + + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + IReadOnlyList stored = await store.ReadAllAsync("c1", TestContext.Current.CancellationToken); + Assert.Equal(8, stored.Count); + Assert.Contains(stored, row => row.Content.Contents.OfType().Any(result => result.Result?.ToString() == "result-A")); + } - var summary = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - Assert.Contains("the gist of it", summary.Content.Text, StringComparison.Ordinal); - Assert.DoesNotContain(await store.ReadAllAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); - } + [Fact] + public async Task ATurn_WhoseViewCrossesThreeQuartersOfTheWindow_FiresTheRealPipeline() + { + // A 400-token window fires at 300 and stops at 200 (D7). One short turn stays well under; + // twelve turns of ~80 characters each land well over. + const int Window = 400; + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + + ConversationSession quiet = CreateSession(new ScriptedChatClient("a1"), store, conversationId: "c1", contextWindow: Window); + _ = await quiet.RunTurnAsync("q1", TestContext.Current.CancellationToken); + await quiet.FlushTranscriptAsync(); + + Assert.DoesNotContain(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + + string padding = new('w', 80); + for (int turn = 2; turn < 14; turn++) + { + await SeedPlainTurnAsync(store, turn, $"q{turn} {padding}", $"a{turn} {padding}"); + } + + ConversationSession loud = CreateSession(new ScriptedChatClient("the gist of it"), store, conversationId: "c1", contextWindow: Window); + _ = await loud.RunTurnAsync("q14", TestContext.Current.CancellationToken); + await loud.FlushTranscriptAsync(); + + ConversationMessage summary = Assert.Single(await store.ReadForSessionAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + Assert.Contains("the gist of it", summary.Content.Text, StringComparison.Ordinal); + Assert.DoesNotContain(await store.ReadAllAsync("c1", TestContext.Current.CancellationToken), row => row.CoversUpTo is not null); + } - [Fact] - public async Task ANewSession_OfAConversationWithASummary_OpensOnTheSummarisedView() - { - var store = new InMemoryConversationStore(); - await store.CreateAsync("c1", TestContext.Current.CancellationToken); - await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); - await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); - await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); - - var first = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0)); - await first.RunTurnAsync("q3", TestContext.Current.CancellationToken); - await first.FlushTranscriptAsync(); - - var reply = new CapturingChatClient(_ => Task.CompletedTask, "a4"); - var resumed = CreateSession(reply, store, conversationId: "c1"); - await resumed.RunTurnAsync("q4", TestContext.Current.CancellationToken); - - Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3", "assistant:a3", "user:q4"], Assert.Single(reply.Requests)); - Assert.NotNull(resumed.Compiled.History.Summary(resumed.AgentSession!)); + [Fact] + public async Task ANewSession_OfAConversationWithASummary_OpensOnTheSummarisedView() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, turnIndex: 0, "q0", "a0"); + await SeedPlainTurnAsync(store, turnIndex: 1, "q1", "a1"); + await SeedPlainTurnAsync(store, turnIndex: 2, "q2", "a2"); + + ConversationSession first = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: Summary(new ScriptedChatClient("the gist of it"), minimumPreservedGroups: 0)); + _ = await first.RunTurnAsync("q3", TestContext.Current.CancellationToken); + await first.FlushTranscriptAsync(); + + CapturingChatClient reply = new(_ => Task.CompletedTask, "a4"); + ConversationSession resumed = CreateSession(reply, store, conversationId: "c1"); + _ = await resumed.RunTurnAsync("q4", TestContext.Current.CancellationToken); + + Assert.Equal(["assistant:[Summary]\nthe gist of it", "user:q2", "assistant:a2", "user:q3", "assistant:a3", "user:q4"], Assert.Single(reply.Requests)); + Assert.NotNull(resumed.Compiled.History.Summary(resumed.AgentSession!)); + } } -} #pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs index acefdf62..66112797 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionConversationRowTests.cs @@ -6,17 +6,17 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Transcript; - -/// A conversation's row exists before its first word does. -public sealed class ConversationSessionConversationRowTests +namespace AgentCore.Application.Tests.Transcript { - private const string OneAgentYaml = """ + /// A conversation's row exists before its first word does. + public sealed class ConversationSessionConversationRowTests + { + private const string OneAgentYaml = """ apiVersion: agentcore/v1 agents: items: @@ -26,66 +26,69 @@ public sealed class ConversationSessionConversationRowTests agent: only """; - /// A store 0 that is down: it takes no row, so no word may follow. - private sealed class RefusingCreate(IConversationStore inner) : DelegatingConversationStore(inner) - { - public override ValueTask CreateAsync( - string conversationId, CancellationToken cancellationToken = default) - => throw new InvalidOperationException("store 0 is down."); - } + /// A store 0 that is down: it takes no row, so no word may follow. + private sealed class RefusingCreate(IConversationStore inner) : DelegatingConversationStore(inner) + { + public override ValueTask CreateAsync( + string conversationId, CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("store 0 is down."); + } + } - [Fact] - public async Task ATurn_CreatesTheConversationRow_BeforeItWritesAnyWord() - { - // Arrange - InMemoryConversationStore store = new(); - using ScriptedChatClient reply = new("hello"); - var session = CreateSession(OneAgentYaml, reply, store); + [Fact] + public async Task ATurn_CreatesTheConversationRow_BeforeItWritesAnyWord() + { + // Arrange + InMemoryConversationStore store = new(); + using ScriptedChatClient reply = new("hello"); + ConversationSession session = CreateSession(OneAgentYaml, reply, store); - // Act - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + // Act + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - // Assert - await session.FlushTranscriptAsync(); - Assert.NotNull(await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken)); - Assert.NotEmpty(await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken)); - } + // Assert + await session.FlushTranscriptAsync(); + Assert.NotNull(await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken)); + Assert.NotEmpty(await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken)); + } - [Fact] - public async Task ATurn_WhenStoreZeroRefusesTheRow_FailsAndWritesNoWords() - { - // Arrange - InMemoryConversationStore inner = new(); - RefusingCreate store = new(inner); - using ScriptedChatClient reply = new("hello"); - var session = CreateSession(OneAgentYaml, reply, store); + [Fact] + public async Task ATurn_WhenStoreZeroRefusesTheRow_FailsAndWritesNoWords() + { + // Arrange + InMemoryConversationStore inner = new(); + RefusingCreate store = new(inner); + using ScriptedChatClient reply = new("hello"); + ConversationSession session = CreateSession(OneAgentYaml, reply, store); - // Act - var fault = await Assert.ThrowsAsync( - () => session.RunTurnAsync("hi", TestContext.Current.CancellationToken)); + // Act + InvalidOperationException fault = await Assert.ThrowsAsync( + () => session.RunTurnAsync("hi", TestContext.Current.CancellationToken)); - // Assert - Assert.Equal("store 0 is down.", fault.Message); - Assert.Empty(await inner.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken)); - } + // Assert + Assert.Equal("store 0 is down.", fault.Message); + Assert.Empty(await inner.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken)); + } - private static ConversationSession CreateSession(string yaml, IChatClient reply, IConversationStore store) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new FakeChatClientFactory(reply); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - ConversationStore = store, - Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), - })["main"]; + private static ConversationSession CreateSession(string yaml, IChatClient reply, IConversationStore store) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + FakeChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + ConversationStore = store, + Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), + })["main"]; - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null); + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null); - return factory.Create(); + return factory.Create(); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionGraphTranscriptTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionGraphTranscriptTests.cs index b6f82e5b..df99372c 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionGraphTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionGraphTranscriptTests.cs @@ -9,26 +9,28 @@ using AgentCore.Application.Tests.Fakes; using Microsoft.Extensions.AI; using Xunit; +using AgentCore.Domain; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins what a graph row keeps and what it sends: the caller-facing turn, and nothing else. -/// -/// -/// A workflow takes no chat history provider and no session of ours, so the turn loop carries the -/// conversation itself. Every test here runs offline, with no network conversation and no API key. -/// -public sealed class ConversationSessionGraphTranscriptTests +namespace AgentCore.Application.Tests.Transcript { - /// What the first node says while it works. The caller never hears it. - private const string Thinking = "Let me check the order system."; - - /// What the answering node says. This is the whole spoken reply. - private const string Spoken = "Order 41 ships Friday."; - - private const string GraphYaml = - """ + /// + /// Pins what a graph row keeps and what it sends: the caller-facing turn, and nothing else. + /// + /// + /// A workflow takes no chat history provider and no session of ours, so the turn loop carries the + /// conversation itself. Every test here runs offline, with no network conversation and no API key. + /// + public sealed class ConversationSessionGraphTranscriptTests + { + /// What the first node says while it works. The caller never hears it. + private const string Thinking = "Let me check the order system."; + + /// What the answering node says. This is the whole spoken reply. + private const string Spoken = "Order 41 ships Friday."; + + private const string GraphYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -41,229 +43,231 @@ public sealed class ConversationSessionGraphTranscriptTests agents: [ researcher, responder ] """; - /// - /// Store 1 holds what the caller said and what the caller heard. The graph's node-to-node - /// chatter is neither, so it never enters the record. - /// - [Fact] - public async Task Run_GraphRow_StoresOnlyCallerFacingMessages() - { - // Arrange - RecordingConversationStore store = new(); - RecordingNodeClient researcher = new(Thinking); - RecordingNodeClient responder = new(Spoken); - var session = CreateSession(researcher, responder, store); - - // Act - _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert - await session.FlushTranscriptAsync(); - Assert.Equal( - ["where is my order", Spoken], - store.Live(session.ConversationId).Select(row => row.Content.Text)); - } - - /// - /// The next turn sends the caller-facing history and never the deliberation that produced the - /// answer, so a node reads only what the caller heard. - /// - [Fact] - public async Task Run_GraphRow_SecondTurn_ModelSeesNoIntermediateNodeReply() - { - // Arrange - RecordingNodeClient researcher = new(Thinking); - RecordingNodeClient responder = new(Spoken); - var session = CreateSession(researcher, responder, new RecordingConversationStore()); - _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Act - _ = await session.RunTurnAsync("and the second one?", TestContext.Current.CancellationToken); - - // Assert. The demotion of an assistant message to user is why the conversation rides one system - // message: the node reads who said what off the line, not off the role. - var second = researcher.Requests[1]; - Assert.Contains( - second, - message => message.Role == ChatRole.System - && message.Text.Contains( - TurnMessages.HistoryPreamble + TurnMessages.CallerLinePrefix + "where is my order", - StringComparison.Ordinal) - && message.Text.Contains(TurnMessages.AgentLinePrefix + Spoken, StringComparison.Ordinal)); - Assert.DoesNotContain(second, message => message.Text.Contains(Thinking, StringComparison.Ordinal)); - Assert.Contains(second, message => message.Role == ChatRole.User && message.Text == "and the second one?"); - } - - /// - /// AgentResponse.Text concatenates every node's reply, so the spoken words are the last - /// message and never the whole response. - /// - [Fact] - public async Task Run_GraphRow_ReplyIsFinalNodeOnly() - { - // Arrange - RecordingConversationStore store = new(); - RecordingNodeClient researcher = new(Thinking); - RecordingNodeClient responder = new(Spoken); - var session = CreateSession(researcher, responder, store); - - // Act - var turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); - - // Assert - Assert.Equal(Spoken, turn.ReplyText); - Assert.DoesNotContain(Thinking, turn.ReplyText, StringComparison.Ordinal); - } - - /// - /// R4 on a graph row: the record holds the words the caller heard, and never the tail the - /// answering node went on to produce. - /// - [Fact] - public async Task Interrupt_MidGraphReply_StoresTheHeardWordsOnly() - { - // Arrange - RecordingConversationStore store = new(); - RecordingNodeClient researcher = new(Thinking); - using ScriptedChatClient responder = new("Order 41 ", "ships Friday.") { GateAfterFirstFragment = true }; - var session = CreateSession(researcher, responder, store); - var (turn, spoke) = StartGatedTurn(session, "where is my order"); - await spoke; - - // Act - var recorded = session.Interrupt("Order 41", TimeSpan.FromMilliseconds(300)); - - // Assert - Assert.True(recorded); - responder.OpenGate(); - await turn; - await session.FlushTranscriptAsync(); - Assert.Equal( - ["where is my order", "Order 41"], - store.Live(session.ConversationId).Select(row => row.Content.Text)); - } - - /// - /// A cut inside the first 100 ms leaves no heard words, and an empty assistant message teaches - /// the next turn nothing. The utterance still enters the record alone. - /// - [Fact] - public async Task Interrupt_BeforeAnyGraphWordLanded_StoresTheCallerUtteranceAlone() - { - // Arrange - RecordingConversationStore store = new(); - RecordingNodeClient researcher = new(Thinking); - using ScriptedChatClient responder = new("Order 41 ", "ships Friday.") { GateAfterFirstFragment = true }; - var session = CreateSession(researcher, responder, store); - var (turn, spoke) = StartGatedTurn(session, "where is my order"); - await spoke; - - // Act - var recorded = session.Interrupt(string.Empty, TimeSpan.FromMilliseconds(40)); - - // Assert - Assert.True(recorded); - responder.OpenGate(); - await turn; - await session.FlushTranscriptAsync(); - Assert.Equal(["where is my order"], store.Live(session.ConversationId).Select(row => row.Content.Text)); - } - - /// Starts a streaming turn on a background task and says when the caller can hear it. - /// The conversation to run the turn on. - /// What the caller said. - /// The running turn, and a task that completes at its first spoken update. - /// - /// A run that has handed the host nothing is not the turn the caller is hearing, so a barge-in - /// before the first update takes the amendment path instead and records nothing against this - /// turn. Waiting for that update is what makes the cut land in the reply. - /// - private static (Task Turn, Task Spoke) StartGatedTurn(ConversationSession session, string userInput) - { - TaskCompletionSource spoke = new(TaskCreationOptions.RunContinuationsAsynchronously); - var turn = Task.Run( - async () => - { - await foreach (var _ in session - .RunTurnStreamingAsync(userInput, TestContext.Current.CancellationToken) - .ConfigureAwait(false)) - { - spoke.TrySetResult(); - } - }, - CancellationToken.None); - - return (turn, spoke.Task.WaitAsync(TimeSpan.FromSeconds(10))); - } - - private static ConversationSession CreateSession( - IChatClient researcher, IChatClient responder, IConversationStore store) - { - var document = ConfigurationLoader.LoadYaml(GraphYaml); - RoutingChatClientFactory chatClients = new(researcher); - chatClients.Route("responder", responder); - - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { ConversationStore = store })["main"]; - - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null); - - return factory.Create(); - } - - /// Answers with one fixed line, and keeps every request it was handed. - private sealed class RecordingNodeClient : IChatClient - { - private readonly string _reply; - - public RecordingNodeClient(string reply) => _reply = reply; - - /// Gets what this node's model was sent, one entry per run. - public List> Requests { get; } = []; - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Record(messages); - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); - } - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - Record(messages); - await Task.Yield(); - - var responseId = Guid.NewGuid().ToString("N"); - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - }; - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - - private void Record(IEnumerable messages) - { - lock (Requests) - { - Requests.Add([.. messages]); - } - } - } - } + /// + /// Store 1 holds what the caller said and what the caller heard. The graph's node-to-node + /// chatter is neither, so it never enters the record. + /// + [Fact] + public async Task Run_GraphRow_StoresOnlyCallerFacingMessages() + { + // Arrange + RecordingConversationStore store = new(); + RecordingNodeClient researcher = new(Thinking); + RecordingNodeClient responder = new(Spoken); + ConversationSession session = CreateSession(researcher, responder, store); + + // Act + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert + await session.FlushTranscriptAsync(); + Assert.Equal( + ["where is my order", Spoken], + store.Live(session.ConversationId).Select(row => row.Content.Text)); + } + + /// + /// The next turn sends the caller-facing history and never the deliberation that produced the + /// answer, so a node reads only what the caller heard. + /// + [Fact] + public async Task Run_GraphRow_SecondTurn_ModelSeesNoIntermediateNodeReply() + { + // Arrange + RecordingNodeClient researcher = new(Thinking); + RecordingNodeClient responder = new(Spoken); + ConversationSession session = CreateSession(researcher, responder, new RecordingConversationStore()); + _ = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Act + _ = await session.RunTurnAsync("and the second one?", TestContext.Current.CancellationToken); + + // Assert. The demotion of an assistant message to user is why the conversation rides one system + // message: the node reads who said what off the line, not off the role. + List second = researcher.Requests[1]; + Assert.Contains( + second, + message => message.Role == ChatRole.System + && message.Text.Contains( + TurnMessages.HistoryPreamble + TurnMessages.CallerLinePrefix + "where is my order", + StringComparison.Ordinal) + && message.Text.Contains(TurnMessages.AgentLinePrefix + Spoken, StringComparison.Ordinal)); + Assert.DoesNotContain(second, message => message.Text.Contains(Thinking, StringComparison.Ordinal)); + Assert.Contains(second, message => message.Role == ChatRole.User && message.Text == "and the second one?"); + } + + /// + /// AgentResponse.Text concatenates every node's reply, so the spoken words are the last + /// message and never the whole response. + /// + [Fact] + public async Task Run_GraphRow_ReplyIsFinalNodeOnly() + { + // Arrange + RecordingConversationStore store = new(); + RecordingNodeClient researcher = new(Thinking); + RecordingNodeClient responder = new(Spoken); + ConversationSession session = CreateSession(researcher, responder, store); + + // Act + TurnResult turn = await session.RunTurnAsync("where is my order", TestContext.Current.CancellationToken); + + // Assert + Assert.Equal(Spoken, turn.ReplyText); + Assert.DoesNotContain(Thinking, turn.ReplyText, StringComparison.Ordinal); + } + + /// + /// R4 on a graph row: the record holds the words the caller heard, and never the tail the + /// answering node went on to produce. + /// + [Fact] + public async Task Interrupt_MidGraphReply_StoresTheHeardWordsOnly() + { + // Arrange + RecordingConversationStore store = new(); + RecordingNodeClient researcher = new(Thinking); + using ScriptedChatClient responder = new("Order 41 ", "ships Friday.") { GateAfterFirstFragment = true }; + ConversationSession session = CreateSession(researcher, responder, store); + (Task? turn, Task? spoke) = StartGatedTurn(session, "where is my order"); + await spoke; + + // Act + bool recorded = session.Interrupt("Order 41", TimeSpan.FromMilliseconds(300)); + + // Assert + Assert.True(recorded); + responder.OpenGate(); + await turn; + await session.FlushTranscriptAsync(); + Assert.Equal( + ["where is my order", "Order 41"], + store.Live(session.ConversationId).Select(row => row.Content.Text)); + } + + /// + /// A cut inside the first 100 ms leaves no heard words, and an empty assistant message teaches + /// the next turn nothing. The utterance still enters the record alone. + /// + [Fact] + public async Task Interrupt_BeforeAnyGraphWordLanded_StoresTheCallerUtteranceAlone() + { + // Arrange + RecordingConversationStore store = new(); + RecordingNodeClient researcher = new(Thinking); + using ScriptedChatClient responder = new("Order 41 ", "ships Friday.") { GateAfterFirstFragment = true }; + ConversationSession session = CreateSession(researcher, responder, store); + (Task? turn, Task? spoke) = StartGatedTurn(session, "where is my order"); + await spoke; + + // Act + bool recorded = session.Interrupt(string.Empty, TimeSpan.FromMilliseconds(40)); + + // Assert + Assert.True(recorded); + responder.OpenGate(); + await turn; + await session.FlushTranscriptAsync(); + Assert.Equal(["where is my order"], store.Live(session.ConversationId).Select(row => row.Content.Text)); + } + + /// Starts a streaming turn on a background task and says when the caller can hear it. + /// The conversation to run the turn on. + /// What the caller said. + /// The running turn, and a task that completes at its first spoken update. + /// + /// A run that has handed the host nothing is not the turn the caller is hearing, so a barge-in + /// before the first update takes the amendment path instead and records nothing against this + /// turn. Waiting for that update is what makes the cut land in the reply. + /// + private static (Task Turn, Task Spoke) StartGatedTurn(ConversationSession session, string userInput) + { + TaskCompletionSource spoke = new(TaskCreationOptions.RunContinuationsAsynchronously); + Task turn = Task.Run( + async () => + { + await foreach (ChatResponseUpdate? update in session + .RunTurnStreamingAsync(userInput, TestContext.Current.CancellationToken) + .ConfigureAwait(false)) + { + _ = spoke.TrySetResult(); + } + }, + CancellationToken.None); + + return (turn, spoke.Task.WaitAsync(TimeSpan.FromSeconds(10))); + } + + private static ConversationSession CreateSession( + IChatClient researcher, IChatClient responder, IConversationStore store) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(GraphYaml); + RoutingChatClientFactory chatClients = new(researcher); + _ = chatClients.Route("responder", responder); + + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { ConversationStore = store })["main"]; + + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null); + + return factory.Create(); + } + + /// Answers with one fixed line, and keeps every request it was handed. + private sealed class RecordingNodeClient(string reply) : IChatClient + { + private readonly string _reply = reply; + + /// Gets what this node's model was sent, one entry per run. + public List> Requests { get; } = []; + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + Record(messages); + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + Record(messages); + await Task.Yield(); + + string responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + + private void Record(IEnumerable messages) + { + lock (Requests) + { + Requests.Add([.. messages]); + } + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs index 7a9ba43c..63a3e7aa 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionOutsideAppendTests.cs @@ -1,208 +1,211 @@ +using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Transcript; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionResumeTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// A turn sees a row a host appended from outside any turn — after a human handoff ends, say, -/// possibly from another machine — and its own new rows still continue from store 0's counter. -/// -#pragma warning disable CA1859 // store is typed as IConversationStore throughout: AppendMessageAsync(conversationId, message, ct) - // is a default interface method, and only resolves through the interface type. -public sealed class ConversationSessionOutsideAppendTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task SecondTurn_SeesTheOutsideMessagesBetweenTheTurns_AndKeepsTheirProperties() + /// + /// A turn sees a row a host appended from outside any turn — after a human handoff ends, say, + /// possibly from another machine — and its own new rows still continue from store 0's counter. + /// +#pragma warning disable CA1859 // store is typed as IConversationStore throughout: AppendMessageAsync(conversationId, message, ct) + // is a default interface method, and only resolves through the interface type. + public sealed class ConversationSessionOutsideAppendTests { - IConversationStore store = new InMemoryConversationStore(); - var (_, client) = await RunTwoTurnsWithAnOutsideHandoffAsync(store); - - var secondRequest = client.Requests[1]; + [Fact] + public async Task SecondTurn_SeesTheOutsideMessagesBetweenTheTurns_AndKeepsTheirProperties() + { + IConversationStore store = new InMemoryConversationStore(); + (ConversationSession _, SequencedChatClient? client) = await RunTwoTurnsWithAnOutsideHandoffAsync(store); - // Both outside rows land between turn 1's words and turn 2's own question, in the order the - // host wrote them. - Assert.Equal( - ["my name is Dana", "hi Dana", "Dana joined", "human phase", "are you still there?"], - secondRequest.Select(message => message.Text)); + List secondRequest = client.Requests[1]; - var joined = Assert.Single(secondRequest, message => message.Text == "Dana joined"); - Assert.Equal("human-agent", joined.AdditionalProperties?["speaker"]?.ToString()); - } + // Both outside rows land between turn 1's words and turn 2's own question, in the order the + // host wrote them. + Assert.Equal( + ["my name is Dana", "hi Dana", "Dana joined", "human phase", "are you still there?"], + secondRequest.Select(message => message.Text)); - [Fact] - public async Task AfterTheSecondTurn_TheStoresOrdinalsAreDenseAndUnique() - { - IConversationStore store = new InMemoryConversationStore(); - var (session, _) = await RunTwoTurnsWithAnOutsideHandoffAsync(store); - - var rows = await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken); - var ordinals = rows.Select(row => row.Ordinal).ToArray(); + ChatMessage joined = Assert.Single(secondRequest, message => message.Text == "Dana joined"); + Assert.Equal("human-agent", joined.AdditionalProperties?["speaker"]?.ToString()); + } - for (var index = 1; index < ordinals.Length; index++) + [Fact] + public async Task AfterTheSecondTurn_TheStoresOrdinalsAreDenseAndUnique() { - Assert.True(ordinals[index] > ordinals[index - 1]); - } + IConversationStore store = new InMemoryConversationStore(); + (ConversationSession? session, SequencedChatClient _) = await RunTwoTurnsWithAnOutsideHandoffAsync(store); - // No truncate ran in this scenario, so the counter and the row count agree exactly. - var record = await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken); - Assert.Equal(rows.Count, record?.NextOrdinal); - } + IReadOnlyList rows = await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken); + int[] ordinals = [.. rows.Select(row => row.Ordinal)]; - [Fact] - public async Task ASecondSessionOverTheSameStore_SeesTheOutsideMessageAndContinuesTheCounter() - { - // Two ConversationSession instances of one conversation, standing in for two machines: nothing but the store - // passes between them. - IConversationStore store = new InMemoryConversationStore(); - - SequencedChatClient clientA = new("hi Dana"); - var sessionA = CreateSession(OneAgentYaml, clientA, store); - await sessionA.RunTurnAsync("my name is Dana", TestContext.Current.CancellationToken); - await sessionA.FlushTranscriptAsync(); - - await store.AppendMessageAsync( - sessionA.ConversationId, - new ChatMessage(ChatRole.Assistant, "Dana joined") + for (int index = 1; index < ordinals.Length; index++) { - AdditionalProperties = new() { ["speaker"] = "human-agent" }, - }, - TestContext.Current.CancellationToken); - - SequencedChatClient clientB = new("welcome back"); - var sessionB = CreateSession(OneAgentYaml, clientB, store, sessionA.ConversationId); - - await sessionB.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - await sessionB.FlushTranscriptAsync(); + Assert.True(ordinals[index] > ordinals[index - 1]); + } - Assert.Equal( - ["my name is Dana", "hi Dana", "Dana joined", "still there?"], - clientB.Requests[0].Select(message => message.Text)); - - var rows = await store.ReadAllAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); - Assert.Equal([0, 1, 2, 3, 4], rows.Select(row => row.Ordinal)); - - var record = await store.GetAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); - Assert.Equal(rows.Count, record?.NextOrdinal); - } - - [Fact] - public async Task AnEditAfterAnOutsideAppend_CutsTheOutsideRowWithTheReplyItReplaces() - { - IConversationStore store = new InMemoryConversationStore(); - SequencedChatClient client = new("first reply", "second reply"); - var session = CreateSession(OneAgentYaml, client, store); - - await session.RunTurnAtOriginAsync( - "first question", - new ConversationTurnOrigin("m1", null) { NamesParent = true }, - TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - await store.AppendMessageAsync( - session.ConversationId, - new ChatMessage(ChatRole.Assistant, "Dana joined") - { - AdditionalProperties = new() { ["speaker"] = "human-agent" }, - }, - TestContext.Current.CancellationToken); - - // Names m1 as the parent, so the edit must see the outside row that now sits after it in - // order to cut it along with the reply it replaces. - await session.RunTurnAtOriginAsync( - "first question, rewritten", - new ConversationTurnOrigin("m2", "m1") { NamesParent = true }, - TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - var rows = await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken); - - Assert.Equal(3, rows.Count); - Assert.Equal("m1", rows[0].MessageId); - Assert.Equal("m2", rows[1].MessageId); - Assert.Equal( - ["first question", "first question, rewritten", "second reply"], - rows.Select(row => row.Content.Text)); - } + // No truncate ran in this scenario, so the counter and the row count agree exactly. + ConversationRecord? record = await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken); + Assert.Equal(rows.Count, record?.NextOrdinal); + } - [Fact] - public async Task AfterOneTurn_TheStoredBlobCarriesTheTurnIndexAndTheCounterLivesOnTheRecord() - { - IConversationStore store = new InMemoryConversationStore(); - SequencedChatClient client = new("hi there"); - var session = CreateSession(OneAgentYaml, client, store); + [Fact] + public async Task ASecondSessionOverTheSameStore_SeesTheOutsideMessageAndContinuesTheCounter() + { + // Two ConversationSession instances of one conversation, standing in for two machines: nothing but the store + // passes between them. + IConversationStore store = new InMemoryConversationStore(); + + SequencedChatClient clientA = new("hi Dana"); + ConversationSession sessionA = CreateSession(OneAgentYaml, clientA, store); + _ = await sessionA.RunTurnAsync("my name is Dana", TestContext.Current.CancellationToken); + await sessionA.FlushTranscriptAsync(); + + _ = await store.AppendMessageAsync( + sessionA.ConversationId, + new ChatMessage(ChatRole.Assistant, "Dana joined") + { + AdditionalProperties = new() { ["speaker"] = "human-agent" }, + }, + TestContext.Current.CancellationToken); + + SequencedChatClient clientB = new("welcome back"); + ConversationSession sessionB = CreateSession(OneAgentYaml, clientB, store, sessionA.ConversationId); + + _ = await sessionB.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + await sessionB.FlushTranscriptAsync(); + + Assert.Equal( + ["my name is Dana", "hi Dana", "Dana joined", "still there?"], + clientB.Requests[0].Select(message => message.Text)); + + IReadOnlyList rows = await store.ReadAllAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); + Assert.Equal([0, 1, 2, 3, 4], rows.Select(row => row.Ordinal)); + + ConversationRecord? record = await store.GetAsync(sessionA.ConversationId, TestContext.Current.CancellationToken); + Assert.Equal(rows.Count, record?.NextOrdinal); + } - await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); + [Fact] + public async Task AnEditAfterAnOutsideAppend_CutsTheOutsideRowWithTheReplyItReplaces() + { + IConversationStore store = new InMemoryConversationStore(); + SequencedChatClient client = new("first reply", "second reply"); + ConversationSession session = CreateSession(OneAgentYaml, client, store); + + _ = await session.RunTurnAtOriginAsync( + "first question", + new ConversationTurnOrigin("m1", null) { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + _ = await store.AppendMessageAsync( + session.ConversationId, + new ChatMessage(ChatRole.Assistant, "Dana joined") + { + AdditionalProperties = new() { ["speaker"] = "human-agent" }, + }, + TestContext.Current.CancellationToken); + + // Names m1 as the parent, so the edit must see the outside row that now sits after it in + // order to cut it along with the reply it replaces. + _ = await session.RunTurnAtOriginAsync( + "first question, rewritten", + new ConversationTurnOrigin("m2", "m1") { NamesParent = true }, + TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + IReadOnlyList rows = await store.ReadAllAsync(session.ConversationId, TestContext.Current.CancellationToken); + + Assert.Equal(3, rows.Count); + Assert.Equal("m1", rows[0].MessageId); + Assert.Equal("m2", rows[1].MessageId); + Assert.Equal( + ["first question", "first question, rewritten", "second reply"], + rows.Select(row => row.Content.Text)); + } - var record = await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken); + [Fact] + public async Task AfterOneTurn_TheStoredBlobCarriesTheTurnIndexAndTheCounterLivesOnTheRecord() + { + IConversationStore store = new InMemoryConversationStore(); + SequencedChatClient client = new("hi there"); + ConversationSession session = CreateSession(OneAgentYaml, client, store); - // One turn writes two rows (what the caller said, what it heard) and leaves the next turn at - // index 1 — the mark the blob carries now that the ordinal has its own column on the record. - Assert.Equal(1, record?.State?.NextTurnIndex); - Assert.Equal(2, record?.NextOrdinal); - } + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); - [Fact] - public async Task SecondTurn_WithNoOutsideAppend_DoesNotReadTheWordsBack() - { - RecordingConversationStore store = new(); - SequencedChatClient client = new("hi Dana", "welcome back"); - var session = CreateSession(OneAgentYaml, client, store); - - await session.RunTurnAsync("my name is Dana", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - await session.RunTurnAsync("are you still there?", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // The counter store 0 hands back matches the one the session holds, so nobody wrote from - // outside and there is nothing to read. - Assert.Equal(0, store.Reads); - Assert.Equal( - ["my name is Dana", "hi Dana", "are you still there?"], - client.Requests[1].Select(message => message.Text)); - } + ConversationRecord? record = await store.GetAsync(session.ConversationId, TestContext.Current.CancellationToken); - [Fact] - public async Task SecondTurn_AfterAnOutsideAppend_ReadsTheWordsBackOnce() - { - RecordingConversationStore store = new(); - await RunTwoTurnsWithAnOutsideHandoffAsync(store); + // One turn writes two rows (what the caller said, what it heard) and leaves the next turn at + // index 1 — the mark the blob carries now that the ordinal has its own column on the record. + Assert.Equal(1, record?.State?.NextTurnIndex); + Assert.Equal(2, record?.NextOrdinal); + } - Assert.Equal(1, store.Reads); - } + [Fact] + public async Task SecondTurn_WithNoOutsideAppend_DoesNotReadTheWordsBack() + { + RecordingConversationStore store = new(); + SequencedChatClient client = new("hi Dana", "welcome back"); + ConversationSession session = CreateSession(OneAgentYaml, client, store); + + _ = await session.RunTurnAsync("my name is Dana", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + _ = await session.RunTurnAsync("are you still there?", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The counter store 0 hands back matches the one the session holds, so nobody wrote from + // outside and there is nothing to read. + Assert.Equal(0, store.Reads); + Assert.Equal( + ["my name is Dana", "hi Dana", "are you still there?"], + client.Requests[1].Select(message => message.Text)); + } - private static async Task<(ConversationSession Session, SequencedChatClient Client)> RunTwoTurnsWithAnOutsideHandoffAsync( - IConversationStore store) - { - SequencedChatClient client = new("hi Dana", "welcome back"); - var session = CreateSession(OneAgentYaml, client, store); + [Fact] + public async Task SecondTurn_AfterAnOutsideAppend_ReadsTheWordsBackOnce() + { + RecordingConversationStore store = new(); + _ = await RunTwoTurnsWithAnOutsideHandoffAsync(store); - await session.RunTurnAsync("my name is Dana", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); + Assert.Equal(1, store.Reads); + } - await store.AppendMessageAsync( - session.ConversationId, - new ChatMessage(ChatRole.Assistant, "Dana joined") - { - AdditionalProperties = new() { ["speaker"] = "human-agent" }, - }, - TestContext.Current.CancellationToken); - await store.AppendMessageAsync( - session.ConversationId, - new ChatMessage(ChatRole.User, "human phase"), - TestContext.Current.CancellationToken); - - await session.RunTurnAsync("are you still there?", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - return (session, client); + private static async Task<(ConversationSession Session, SequencedChatClient Client)> RunTwoTurnsWithAnOutsideHandoffAsync( + IConversationStore store) + { + SequencedChatClient client = new("hi Dana", "welcome back"); + ConversationSession session = CreateSession(OneAgentYaml, client, store); + + _ = await session.RunTurnAsync("my name is Dana", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + _ = await store.AppendMessageAsync( + session.ConversationId, + new ChatMessage(ChatRole.Assistant, "Dana joined") + { + AdditionalProperties = new() { ["speaker"] = "human-agent" }, + }, + TestContext.Current.CancellationToken); + _ = await store.AppendMessageAsync( + session.ConversationId, + new ChatMessage(ChatRole.User, "human phase"), + TestContext.Current.CancellationToken); + + _ = await session.RunTurnAsync("are you still there?", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + return (session, client); + } } -} #pragma warning restore CA1859 +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTestSupport.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTestSupport.cs index 7a0aadd4..fe701d3c 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTestSupport.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTestSupport.cs @@ -1,20 +1,20 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tests.Runtime; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// The documents and session-building helpers a conversation's resume tests share. -internal static class ConversationSessionResumeTestSupport +namespace AgentCore.Application.Tests.Transcript { - internal const string OneAgentYaml = """ + /// The documents and session-building helpers a conversation's resume tests share. + internal static class ConversationSessionResumeTestSupport + { + internal const string OneAgentYaml = """ apiVersion: agentcore/v1 agents: # These tests read the exact messages the model sees; the clock line would be one more. @@ -26,10 +26,10 @@ internal static class ConversationSessionResumeTestSupport agent: only """; - /// - /// A document with something to forget: one slot a writer fills, and a stage that moves. - /// - internal const string StagedYaml = """ + /// + /// A document with something to forget: one slot a writer fills, and a stage that moves. + /// + internal const string StagedYaml = """ apiVersion: agentcore/v1 state: turnsTaken: @@ -52,10 +52,10 @@ internal static class ConversationSessionResumeTestSupport - { id: help, agent: help } """; - /// - /// A document whose stages run three deep, so a machine left in the first one is visible. - /// - internal const string ThreeStageYaml = """ + /// + /// A document whose stages run three deep, so a machine left in the first one is visible. + /// + internal const string ThreeStageYaml = """ apiVersion: agentcore/v1 guards: always: { ">=": [ { var: turnIndex }, 0 ] } @@ -74,80 +74,81 @@ internal static class ConversationSessionResumeTestSupport - { id: three, agent: third } """; - internal static async Task FirstTurnAsync( - IConversationStore store, string said, string heard) - { - using ScriptedChatClient reply = new(heard); - var session = CreateSession(OneAgentYaml, reply, store); - - await session.RunTurnAsync(said, TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - return session.ConversationId; - } - - internal static async Task SecondTurnAsync( - IConversationStore store, string conversationId, string said, string heard) - { - using ScriptedChatClient reply = new(heard); - var session = CreateSession(OneAgentYaml, reply, store, conversationId); - - await session.RunTurnAsync(said, TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - } - - internal static ConversationSession CreateSession( - string yaml, - IChatClient reply, - IConversationStore store, - string? conversationId = null, - IConversationObserver? observer = null) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new FakeChatClientFactory(reply); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - ConversationStore = store, - Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), - })["main"]; - - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null, - observers: observer is null ? null : [observer]); - - return factory.Create(conversationId); - } - } - - /// Keeps every fact of the conversation, in the order the turn loop raised them. - internal sealed class RecordingObserver : IConversationObserver - { - private readonly Lock _gate = new(); - private readonly List _events = []; - - /// Gets what the conversation raised, oldest first. - public IReadOnlyList Events - { - get - { - lock (_gate) - { - return [.. _events]; - } - } - } - - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - { - lock (_gate) - { - _events.Add(conversationEvent); - } - - return ValueTask.CompletedTask; - } - } + internal static async Task FirstTurnAsync( + IConversationStore store, string said, string heard) + { + using ScriptedChatClient reply = new(heard); + ConversationSession session = CreateSession(OneAgentYaml, reply, store); + + _ = await session.RunTurnAsync(said, TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + return session.ConversationId; + } + + internal static async Task SecondTurnAsync( + IConversationStore store, string conversationId, string said, string heard) + { + using ScriptedChatClient reply = new(heard); + ConversationSession session = CreateSession(OneAgentYaml, reply, store, conversationId); + + _ = await session.RunTurnAsync(said, TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + } + + internal static ConversationSession CreateSession( + string yaml, + IChatClient reply, + IConversationStore store, + string? conversationId = null, + IConversationObserver? observer = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + FakeChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + ConversationStore = store, + Tools = TestToolRegistry.From(document, null, TestContext.Current.CancellationToken), + })["main"]; + + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null, + observers: observer is null ? null : [observer]); + + return factory.Create(conversationId); + } + } + + /// Keeps every fact of the conversation, in the order the turn loop raised them. + internal sealed class RecordingObserver : IConversationObserver + { + private readonly Lock _gate = new(); + private readonly List _events = []; + + /// Gets what the conversation raised, oldest first. + public IReadOnlyList Events + { + get + { + lock (_gate) + { + return [.. _events]; + } + } + } + + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + { + lock (_gate) + { + _events.Add(conversationEvent); + } + + return ValueTask.CompletedTask; + } + } +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs index c7ba917d..e2a854e0 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionResumeTests.cs @@ -1,103 +1,106 @@ using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Transcript; using AgentCore.TestSupport; -using Microsoft.Extensions.AI; using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionResumeTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// A conversation outlives the session that started it. -/// -public sealed class ConversationSessionResumeTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task ASecondSessionOfOneConversation_SendsTheFirstTurnToTheModel() - { - InMemoryConversationStore store = new(); - var conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); - - using ScriptedChatClient reply = new("Dana"); - using RequestCapturingChatClient capture = new(reply); - var resumed = CreateSession(OneAgentYaml, capture, store, conversationId); - - await resumed.RunTurnAsync("what is my name?", TestContext.Current.CancellationToken); - - Assert.NotEmpty(capture.Requests); - Assert.Contains( - capture.Requests[^1], - message => message.Text.Contains("my name is Dana", StringComparison.Ordinal)); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_KeepsEveryWordTheFirstOneWrote() - { - InMemoryConversationStore store = new(); - var conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); - - await SecondTurnAsync(store, conversationId, "what is my name?", "Dana"); - - var rows = await store.ReadAllAsync(conversationId, TestContext.Current.CancellationToken); - - // Two turns, each writing what the caller said and what it heard. A resumed session that - // restarted its ordinals would overwrite the first pair rather than follow them. - Assert.Equal(4, rows.Count); - Assert.Equal([0, 1, 2, 3], rows.Select(row => row.Ordinal)); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_CountsItsTurnAsTheNextOne() - { - InMemoryConversationStore store = new(); - var conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); - - await SecondTurnAsync(store, conversationId, "what is my name?", "Dana"); - - var rows = await store.ReadAllAsync(conversationId, TestContext.Current.CancellationToken); - - // The turn index is the join to the audit chain, so a second turn numbered 0 would claim the - // first turn's events as its own. - Assert.Equal([0, 0, 1, 1], rows.Select(row => row.TurnIndex)); - } - - [Fact] - public async Task ASessionOfAConversationWithNoWords_StartsAtTheBeginning() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("empty-conversation", TestContext.Current.CancellationToken); - - await SecondTurnAsync(store, "empty-conversation", "hello", "hi there"); - - var rows = await store.ReadAllAsync("empty-conversation", TestContext.Current.CancellationToken); - - Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); - Assert.Equal([0, 0], rows.Select(row => row.TurnIndex)); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_WhoseWordsCannotBeRead_RefusesTheTurn() - { - InMemoryConversationStore backing = new(); - UnreadableConversationStore store = new(backing); - var conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); - - using ScriptedChatClient reply = new("Dana"); - var resumed = CreateSession(OneAgentYaml, reply, store, conversationId); - - // A read that answered empty would run the turn with no memory of the caller. Meeting a - // stranger is worse than meeting an error, so the turn does not run at all. - await Assert.ThrowsAsync( - () => resumed.RunTurnAsync("what is my name?", TestContext.Current.CancellationToken)); - } - - /// A store 1 that takes words and will not give them back. - private sealed class UnreadableConversationStore(IConversationStore inner) : DelegatingConversationStore(inner) + /// + /// A conversation outlives the session that started it. + /// + public sealed class ConversationSessionResumeTests { - public override ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - => throw new InvalidOperationException("store 1 will not answer a read."); + [Fact] + public async Task ASecondSessionOfOneConversation_SendsTheFirstTurnToTheModel() + { + InMemoryConversationStore store = new(); + string conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); + + using ScriptedChatClient reply = new("Dana"); + using RequestCapturingChatClient capture = new(reply); + ConversationSession resumed = CreateSession(OneAgentYaml, capture, store, conversationId); + + _ = await resumed.RunTurnAsync("what is my name?", TestContext.Current.CancellationToken); + + Assert.NotEmpty(capture.Requests); + Assert.Contains( + capture.Requests[^1], + message => message.Text.Contains("my name is Dana", StringComparison.Ordinal)); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_KeepsEveryWordTheFirstOneWrote() + { + InMemoryConversationStore store = new(); + string conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); + + await SecondTurnAsync(store, conversationId, "what is my name?", "Dana"); + + IReadOnlyList rows = await store.ReadAllAsync(conversationId, TestContext.Current.CancellationToken); + + // Two turns, each writing what the caller said and what it heard. A resumed session that + // restarted its ordinals would overwrite the first pair rather than follow them. + Assert.Equal(4, rows.Count); + Assert.Equal([0, 1, 2, 3], rows.Select(row => row.Ordinal)); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_CountsItsTurnAsTheNextOne() + { + InMemoryConversationStore store = new(); + string conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); + + await SecondTurnAsync(store, conversationId, "what is my name?", "Dana"); + + IReadOnlyList rows = await store.ReadAllAsync(conversationId, TestContext.Current.CancellationToken); + + // The turn index is the join to the audit chain, so a second turn numbered 0 would claim the + // first turn's events as its own. + Assert.Equal([0, 0, 1, 1], rows.Select(row => row.TurnIndex)); + } + + [Fact] + public async Task ASessionOfAConversationWithNoWords_StartsAtTheBeginning() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("empty-conversation", TestContext.Current.CancellationToken); + + await SecondTurnAsync(store, "empty-conversation", "hello", "hi there"); + + IReadOnlyList rows = await store.ReadAllAsync("empty-conversation", TestContext.Current.CancellationToken); + + Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); + Assert.Equal([0, 0], rows.Select(row => row.TurnIndex)); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_WhoseWordsCannotBeRead_RefusesTheTurn() + { + InMemoryConversationStore backing = new(); + UnreadableConversationStore store = new(backing); + string conversationId = await FirstTurnAsync(store, "my name is Dana", "Hello Dana"); + + using ScriptedChatClient reply = new("Dana"); + ConversationSession resumed = CreateSession(OneAgentYaml, reply, store, conversationId); + + // A read that answered empty would run the turn with no memory of the caller. Meeting a + // stranger is worse than meeting an error, so the turn does not run at all. + _ = await Assert.ThrowsAsync( + () => resumed.RunTurnAsync("what is my name?", TestContext.Current.CancellationToken)); + } + + /// A store 1 that takes words and will not give them back. + private sealed class UnreadableConversationStore(IConversationStore inner) : DelegatingConversationStore(inner) + { + public override ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("store 1 will not answer a read."); + } + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStateRestoreTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStateRestoreTests.cs index 40c7a9fa..1dfa2dd9 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStateRestoreTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStateRestoreTests.cs @@ -8,327 +8,328 @@ using Xunit; using static AgentCore.Application.Tests.Transcript.ConversationSessionResumeTestSupport; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// What a second session of one conversation restores from the state a first one left behind. -/// -public sealed class ConversationSessionStateRestoreTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public async Task ASecondSessionOfOneConversation_KeepsTheStageTheFirstOneReached() - { - InMemoryConversationStore store = new(); - - using ScriptedChatClient first = new("what model is it?"); - var opened = CreateSession(StagedYaml, first, store); - await opened.RunTurnAsync("hello", TestContext.Current.CancellationToken); - await opened.FlushTranscriptAsync(); - - Assert.Equal("help", opened.Stage); - - using ScriptedChatClient second = new("sure"); - var resumed = CreateSession(StagedYaml, second, store, opened.ConversationId); - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // StageBefore, and not Stage. The stage is restored when the session OPENS and the session - // opens on the first turn, so the restored stage is the one that turn spoke in, and 'intake' - // is what a session that forgot would report. Reading Stage after the turn would prove - // nothing: this document's only guard reads the reserved turnIndex slot, which store 1 - // restores off the words on its own, so even a session that remembered nothing would land in - // 'help' by the end of the turn. - Assert.Equal("help", resumed.LastTurn!.StageBefore); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_MovesTheStageMachineAndNotOnlyItsLabel() + /// + /// What a second session of one conversation restores from the state a first one left behind. + /// + public sealed class ConversationSessionStateRestoreTests { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-machine", TestContext.Current.CancellationToken); - - await store.AppendAsync( - "C-machine", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { Stage = "two" }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - var resumed = CreateSession(ThreeStageYaml, reply, store, "C-machine"); - - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // 'three', because the turn ran in 'two' and moved on from there. A session that restored - // the reserved stage slot and left the machine where the document starts would report 'two' - // twice over: 'two' as the stage the turn spoke in, because the slot says so, and 'two' - // again afterwards, because the machine only just walked to it — while the turn itself was - // answered by the agent of 'one'. - Assert.Equal("two", resumed.LastTurn!.StageBefore); - Assert.Equal("three", resumed.Stage); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_KeepsTheSlotsTheFirstOneFilled() - { - InMemoryConversationStore store = new(); - - using ScriptedChatClient first = new("what model is it?"); - var opened = CreateSession(StagedYaml, first, store); - await opened.RunTurnAsync("hello", TestContext.Current.CancellationToken); - await opened.FlushTranscriptAsync(); - - Assert.Equal(1L, opened.State.Read("turnsTaken")!.GetValue()); - - using ScriptedChatClient second = new("sure"); - var resumed = CreateSession(StagedYaml, second, store, opened.ConversationId); - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // Two, not one. A session that forgot would count its own turn from zero. - Assert.Equal(2L, resumed.State.Read("turnsTaken")!.GetValue()); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_DropsASlotTheDocumentNoLongerDeclares() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-drift", TestContext.Current.CancellationToken); - - // Written as though a build that declared 'retired' had run this conversation. - await store.AppendAsync( - "C-drift", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState - { - Stage = "intake", - Slots = new Dictionary(StringComparer.Ordinal) + [Fact] + public async Task ASecondSessionOfOneConversation_KeepsTheStageTheFirstOneReached() + { + InMemoryConversationStore store = new(); + + using ScriptedChatClient first = new("what model is it?"); + ConversationSession opened = CreateSession(StagedYaml, first, store); + _ = await opened.RunTurnAsync("hello", TestContext.Current.CancellationToken); + await opened.FlushTranscriptAsync(); + + Assert.Equal("help", opened.Stage); + + using ScriptedChatClient second = new("sure"); + ConversationSession resumed = CreateSession(StagedYaml, second, store, opened.ConversationId); + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // StageBefore, and not Stage. The stage is restored when the session OPENS and the session + // opens on the first turn, so the restored stage is the one that turn spoke in, and 'intake' + // is what a session that forgot would report. Reading Stage after the turn would prove + // nothing: this document's only guard reads the reserved turnIndex slot, which store 1 + // restores off the words on its own, so even a session that remembered nothing would land in + // 'help' by the end of the turn. + Assert.Equal("help", resumed.LastTurn!.StageBefore); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_MovesTheStageMachineAndNotOnlyItsLabel() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-machine", TestContext.Current.CancellationToken); + + _ = await store.AppendAsync( + "C-machine", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { Stage = "two" }, + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + ConversationSession resumed = CreateSession(ThreeStageYaml, reply, store, "C-machine"); + + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // 'three', because the turn ran in 'two' and moved on from there. A session that restored + // the reserved stage slot and left the machine where the document starts would report 'two' + // twice over: 'two' as the stage the turn spoke in, because the slot says so, and 'two' + // again afterwards, because the machine only just walked to it — while the turn itself was + // answered by the agent of 'one'. + Assert.Equal("two", resumed.LastTurn!.StageBefore); + Assert.Equal("three", resumed.Stage); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_KeepsTheSlotsTheFirstOneFilled() + { + InMemoryConversationStore store = new(); + + using ScriptedChatClient first = new("what model is it?"); + ConversationSession opened = CreateSession(StagedYaml, first, store); + _ = await opened.RunTurnAsync("hello", TestContext.Current.CancellationToken); + await opened.FlushTranscriptAsync(); + + Assert.Equal(1L, opened.State.Read("turnsTaken")!.GetValue()); + + using ScriptedChatClient second = new("sure"); + ConversationSession resumed = CreateSession(StagedYaml, second, store, opened.ConversationId); + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // Two, not one. A session that forgot would count its own turn from zero. + Assert.Equal(2L, resumed.State.Read("turnsTaken")!.GetValue()); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_DropsASlotTheDocumentNoLongerDeclares() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-drift", TestContext.Current.CancellationToken); + + // Written as though a build that declared 'retired' had run this conversation. + _ = await store.AppendAsync( + "C-drift", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { - ["turnsTaken"] = JsonValue.Create(4L), - ["retired"] = JsonValue.Create("gone"), + Stage = "intake", + Slots = new Dictionary(StringComparer.Ordinal) + { + ["turnsTaken"] = JsonValue.Create(4L), + ["retired"] = JsonValue.Create("gone"), + }, }, - }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - RecordingObserver observer = new(); - var resumed = CreateSession(StagedYaml, reply, store, "C-drift", observer); - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - Assert.Equal(5L, resumed.State.Read("turnsTaken")!.GetValue()); - Assert.Null(resumed.State.Read("retired")); - - // Dropped, and said so. A document change that quietly costs a conversation one slot is a change - // nobody can price afterwards, so the slot that went is named in the fact. - var dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); - Assert.Equal( - "the document no longer declares the slot 'retired'.", - dropped.Payload[ConversationEventPayloadKeys.Reason]); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_DropsASlotWhoseDeclaredTypeNoLongerTakesTheStoredValue() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-retyped", TestContext.Current.CancellationToken); - - // Written as though 'turnsTaken' had been declared a string when this conversation ran. - await store.AppendAsync( - "C-retyped", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState - { - Stage = "intake", - Slots = new Dictionary(StringComparer.Ordinal) + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + RecordingObserver observer = new(); + ConversationSession resumed = CreateSession(StagedYaml, reply, store, "C-drift", observer); + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + Assert.Equal(5L, resumed.State.Read("turnsTaken")!.GetValue()); + Assert.Null(resumed.State.Read("retired")); + + // Dropped, and said so. A document change that quietly costs a conversation one slot is a change + // nobody can price afterwards, so the slot that went is named in the fact. + ConversationEvent dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); + Assert.Equal( + "the document no longer declares the slot 'retired'.", + dropped.Payload[ConversationEventPayloadKeys.Reason]); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_DropsASlotWhoseDeclaredTypeNoLongerTakesTheStoredValue() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-retyped", TestContext.Current.CancellationToken); + + // Written as though 'turnsTaken' had been declared a string when this conversation ran. + _ = await store.AppendAsync( + "C-retyped", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { - ["turnsTaken"] = JsonValue.Create("four"), + Stage = "intake", + Slots = new Dictionary(StringComparer.Ordinal) + { + ["turnsTaken"] = JsonValue.Create("four"), + }, }, - }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - RecordingObserver observer = new(); - var resumed = CreateSession(StagedYaml, reply, store, "C-retyped", observer); - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // Back to the declared default, and then this turn's own increment. - Assert.Equal(1L, resumed.State.Read("turnsTaken")!.GetValue()); - - // The other half of what TryWrite answers false for. An operator fixes a retyped slot and a - // deleted slot differently, so the two reasons have to read differently. - var dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); - Assert.Equal( - "the slot 'turnsTaken' no longer takes the value it was stored with.", - dropped.Payload[ConversationEventPayloadKeys.Reason]); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_DropsAReservedSlotRatherThanRefusingTheConversation() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-reserved", TestContext.Current.CancellationToken); - - // No writer produces this, but the blob is arbitrary JSON out of store 0 and a host can hand - // one in directly. StateDocument.TryWrite THROWS on a reserved slot rather than answering - // false, so a Restore that just asked it would take the conversation down on its first turn. - await store.AppendAsync( - "C-reserved", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState - { - Stage = "intake", - Slots = new Dictionary(StringComparer.Ordinal) + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + RecordingObserver observer = new(); + ConversationSession resumed = CreateSession(StagedYaml, reply, store, "C-retyped", observer); + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // Back to the declared default, and then this turn's own increment. + Assert.Equal(1L, resumed.State.Read("turnsTaken")!.GetValue()); + + // The other half of what TryWrite answers false for. An operator fixes a retyped slot and a + // deleted slot differently, so the two reasons have to read differently. + ConversationEvent dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); + Assert.Equal( + "the slot 'turnsTaken' no longer takes the value it was stored with.", + dropped.Payload[ConversationEventPayloadKeys.Reason]); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_DropsAReservedSlotRatherThanRefusingTheConversation() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-reserved", TestContext.Current.CancellationToken); + + // No writer produces this, but the blob is arbitrary JSON out of store 0 and a host can hand + // one in directly. StateDocument.TryWrite THROWS on a reserved slot rather than answering + // false, so a Restore that just asked it would take the conversation down on its first turn. + _ = await store.AppendAsync( + "C-reserved", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { - ["turnsTaken"] = JsonValue.Create(4L), - ["stage"] = JsonValue.Create("help"), + Stage = "intake", + Slots = new Dictionary(StringComparer.Ordinal) + { + ["turnsTaken"] = JsonValue.Create(4L), + ["stage"] = JsonValue.Create("help"), + }, }, - }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - RecordingObserver observer = new(); - var resumed = CreateSession(StagedYaml, reply, store, "C-reserved", observer); - - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // It ran, and the declared slot beside the reserved one still landed. - Assert.NotNull(resumed.LastTurn); - Assert.Equal(5L, resumed.State.Read("turnsTaken")!.GetValue()); - - var dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); - Assert.Equal( - "the slot 'stage' is reserved, and a reserved slot is never restored.", - dropped.Payload[ConversationEventPayloadKeys.Reason]); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_IgnoresAStateBlobWrittenInAShapeThisBuildDoesNotKnow() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-future", TestContext.Current.CancellationToken); - - await store.AppendAsync( - "C-future", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState - { - Version = ConversationSessionState.CurrentVersion + 1, - Stage = "help", - Slots = new Dictionary(StringComparer.Ordinal) + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + RecordingObserver observer = new(); + ConversationSession resumed = CreateSession(StagedYaml, reply, store, "C-reserved", observer); + + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // It ran, and the declared slot beside the reserved one still landed. + Assert.NotNull(resumed.LastTurn); + Assert.Equal(5L, resumed.State.Read("turnsTaken")!.GetValue()); + + ConversationEvent dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); + Assert.Equal( + "the slot 'stage' is reserved, and a reserved slot is never restored.", + dropped.Payload[ConversationEventPayloadKeys.Reason]); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_IgnoresAStateBlobWrittenInAShapeThisBuildDoesNotKnow() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-future", TestContext.Current.CancellationToken); + + _ = await store.AppendAsync( + "C-future", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { - ["turnsTaken"] = JsonValue.Create(4L), + Version = ConversationSessionState.CurrentVersion + 1, + Stage = "help", + Slots = new Dictionary(StringComparer.Ordinal) + { + ["turnsTaken"] = JsonValue.Create(4L), + }, }, - }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - RecordingObserver observer = new(); - var resumed = CreateSession(StagedYaml, reply, store, "C-future", observer); - - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // Nothing of it is taken, not the stage and not the slot. A conversation that forgets answers the - // caller; a conversation that guesses at a shape it does not know answers them wrongly. - Assert.Equal("intake", resumed.LastTurn!.StageBefore); - Assert.Equal(1L, resumed.State.Read("turnsTaken")!.GetValue()); - - var dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); - Assert.Equal( - $"the stored state is version {ConversationSessionState.CurrentVersion + 1} " - + $"and this build writes {ConversationSessionState.CurrentVersion}.", - dropped.Payload[ConversationEventPayloadKeys.Reason]); - } - - [Fact] - public async Task ASecondSessionOfAConversationWhoseDocumentLostItsPolicy_DropsTheStoredStage() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-nopolicy", TestContext.Current.CancellationToken); - - await store.AppendAsync( - "C-nopolicy", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { Stage = "intake" }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - RecordingObserver observer = new(); - - // OneAgentYaml declares no policy: at all, which is the shape a document takes when its - // policy section is removed between one session of a conversation and the next. - var resumed = CreateSession(OneAgentYaml, reply, store, "C-nopolicy", observer); - - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // Empty, not 'intake'. There is no machine to hold that stage, and writing it into the - // reserved slot anyway would hand the guards and the audit chain a stage nothing is in. - Assert.Equal(string.Empty, resumed.Stage); - - var dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); - Assert.Equal( - "the entry declares no policy, so the stage 'intake' has nowhere to go.", - dropped.Payload[ConversationEventPayloadKeys.Reason]); - } - - [Fact] - public async Task ASecondSessionOfAConversationThatAlreadyFinished_RefusesTheTurn() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-finished", TestContext.Current.CancellationToken); - - await store.AppendAsync( - "C-finished", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { Stage = "help", IsComplete = true }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - var resumed = CreateSession(StagedYaml, reply, store, "C-finished"); - - // The restore happens in OpenSessionAsync, which RunTurnAsync awaits before it reads - // IsComplete — so a conversation that reached a terminal stage stays finished across sessions and - // turns the caller away rather than starting again. Worth pinning rather than inferring: it - // is what a chat page reload on a finished conversation now does. - await Assert.ThrowsAsync( - () => resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken)); - } - - [Fact] - public async Task ASecondSessionOfOneConversation_FallsBackWhenTheStageIsGone() - { - InMemoryConversationStore store = new(); - await store.CreateAsync("C-nostage", TestContext.Current.CancellationToken); - - await store.AppendAsync( - "C-nostage", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { Stage = "a-stage-nobody-declares" }, - TestContext.Current.CancellationToken); - - using ScriptedChatClient reply = new("sure"); - RecordingObserver observer = new(); - var resumed = CreateSession(StagedYaml, reply, store, "C-nostage", observer); - - await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); - - // It ran. Falling back beats refusing: a conversation that comes back knowing less is worth more than - // one that will not come back. - Assert.NotNull(resumed.LastTurn); - Assert.Equal("intake", resumed.LastTurn!.StageBefore); - - var dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); - Assert.Contains( - "a-stage-nobody-declares", dropped.Payload[ConversationEventPayloadKeys.Reason], StringComparison.Ordinal); - } - - [Fact] - public async Task AConversationWithNoStoredState_StartsWhereTheDocumentSays() - { - InMemoryConversationStore store = new(); - - using ScriptedChatClient reply = new("what model is it?"); - var session = CreateSession(StagedYaml, reply, store); - - await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.NotNull(session.LastTurn); - Assert.Equal("intake", session.LastTurn!.StageBefore); + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + RecordingObserver observer = new(); + ConversationSession resumed = CreateSession(StagedYaml, reply, store, "C-future", observer); + + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // Nothing of it is taken, not the stage and not the slot. A conversation that forgets answers the + // caller; a conversation that guesses at a shape it does not know answers them wrongly. + Assert.Equal("intake", resumed.LastTurn!.StageBefore); + Assert.Equal(1L, resumed.State.Read("turnsTaken")!.GetValue()); + + ConversationEvent dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); + Assert.Equal( + $"the stored state is version {ConversationSessionState.CurrentVersion + 1} " + + $"and this build writes {ConversationSessionState.CurrentVersion}.", + dropped.Payload[ConversationEventPayloadKeys.Reason]); + } + + [Fact] + public async Task ASecondSessionOfAConversationWhoseDocumentLostItsPolicy_DropsTheStoredStage() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-nopolicy", TestContext.Current.CancellationToken); + + _ = await store.AppendAsync( + "C-nopolicy", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { Stage = "intake" }, + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + RecordingObserver observer = new(); + + // OneAgentYaml declares no policy: at all, which is the shape a document takes when its + // policy section is removed between one session of a conversation and the next. + ConversationSession resumed = CreateSession(OneAgentYaml, reply, store, "C-nopolicy", observer); + + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // Empty, not 'intake'. There is no machine to hold that stage, and writing it into the + // reserved slot anyway would hand the guards and the audit chain a stage nothing is in. + Assert.Equal(string.Empty, resumed.Stage); + + ConversationEvent dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); + Assert.Equal( + "the entry declares no policy, so the stage 'intake' has nowhere to go.", + dropped.Payload[ConversationEventPayloadKeys.Reason]); + } + + [Fact] + public async Task ASecondSessionOfAConversationThatAlreadyFinished_RefusesTheTurn() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-finished", TestContext.Current.CancellationToken); + + _ = await store.AppendAsync( + "C-finished", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { Stage = "help", IsComplete = true }, + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + ConversationSession resumed = CreateSession(StagedYaml, reply, store, "C-finished"); + + // The restore happens in OpenSessionAsync, which RunTurnAsync awaits before it reads + // IsComplete — so a conversation that reached a terminal stage stays finished across sessions and + // turns the caller away rather than starting again. Worth pinning rather than inferring: it + // is what a chat page reload on a finished conversation now does. + _ = await Assert.ThrowsAsync( + () => resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken)); + } + + [Fact] + public async Task ASecondSessionOfOneConversation_FallsBackWhenTheStageIsGone() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("C-nostage", TestContext.Current.CancellationToken); + + _ = await store.AppendAsync( + "C-nostage", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { Stage = "a-stage-nobody-declares" }, + TestContext.Current.CancellationToken); + + using ScriptedChatClient reply = new("sure"); + RecordingObserver observer = new(); + ConversationSession resumed = CreateSession(StagedYaml, reply, store, "C-nostage", observer); + + _ = await resumed.RunTurnAsync("still there?", TestContext.Current.CancellationToken); + + // It ran. Falling back beats refusing: a conversation that comes back knowing less is worth more than + // one that will not come back. + Assert.NotNull(resumed.LastTurn); + Assert.Equal("intake", resumed.LastTurn!.StageBefore); + + ConversationEvent dropped = Assert.Single(observer.Events, fact => fact.Kind == ConversationEventKind.StateRestorePartial); + Assert.Contains( + "a-stage-nobody-declares", dropped.Payload[ConversationEventPayloadKeys.Reason], StringComparison.Ordinal); + } + + [Fact] + public async Task AConversationWithNoStoredState_StartsWhereTheDocumentSays() + { + InMemoryConversationStore store = new(); + + using ScriptedChatClient reply = new("what model is it?"); + ConversationSession session = CreateSession(StagedYaml, reply, store); + + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + Assert.NotNull(session.LastTurn); + Assert.Equal("intake", session.LastTurn!.StageBefore); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStoreFailureTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStoreFailureTests.cs index 32bd7c04..811798cb 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStoreFailureTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionStoreFailureTests.cs @@ -1,26 +1,27 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; -using AgentCore.Domain.Audit; +using AgentCore.Domain; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// What store 1 owes the chain: the words first, and a dropped write that costs the conversation nothing. -/// -/// -/// The chain stores a hash of the spoken text and store 1 stores the text. That split only works in -/// one order — the words have to be there before the row that names their digest — and it only works -/// if a store that refuses a write cannot end the conversation it is recording. -/// -public sealed class ConversationSessionStoreFailureTests +namespace AgentCore.Application.Tests.Transcript { - private const string OneAgentYaml = """ + /// + /// What store 1 owes the chain: the words first, and a dropped write that costs the conversation nothing. + /// + /// + /// The chain stores a hash of the spoken text and store 1 stores the text. That split only works in + /// one order — the words have to be there before the row that names their digest — and it only works + /// if a store that refuses a write cannot end the conversation it is recording. + /// + public sealed class ConversationSessionStoreFailureTests + { + private const string OneAgentYaml = """ apiVersion: agentcore/v1 agents: # These tests read the exact messages the model sees; the clock line would be one more. @@ -32,199 +33,194 @@ public sealed class ConversationSessionStoreFailureTests agent: only """; - /// - /// The reply.interrupted row names a hash of the words the caller heard. Raised before - /// store 1 holds them, it names a hash of words nothing holds. - /// - [Fact] - public async Task Interrupt_MidReply_StoreOneHoldsTheWordsBeforeTheInterruptedFactIsRaised() - { - // Arrange - RecordingConversationStore store = new(); - using ScriptedChatClient reply = new("Hello", " there", " caller") { GateAfterFirstFragment = true }; - List whenTheFactWasRaised = []; - WatchingObserver observer = new( - ConversationEventKind.ReplyInterrupted, - conversationEvent => whenTheFactWasRaised.AddRange( - store.Live(conversationEvent.ConversationId).Select(row => row.Content.Text))); - var session = CreateSession(OneAgentYaml, reply, store, observer); - var (turn, spoke) = StartGatedTurn(session, "hi"); - await spoke; - - // Act - var recorded = session.Interrupt("Hello", TimeSpan.FromMilliseconds(300)); - - // Assert - reply.OpenGate(); - await turn; - Assert.True(recorded); - Assert.Equal(["hi", "Hello"], whenTheFactWasRaised); - } + /// + /// The reply.interrupted row names a hash of the words the caller heard. Raised before + /// store 1 holds them, it names a hash of words nothing holds. + /// + [Fact] + public async Task Interrupt_MidReply_StoreOneHoldsTheWordsBeforeTheInterruptedFactIsRaised() + { + // Arrange + RecordingConversationStore store = new(); + using ScriptedChatClient reply = new("Hello", " there", " caller") { GateAfterFirstFragment = true }; + List whenTheFactWasRaised = []; + WatchingObserver observer = new( + ConversationEventKind.ReplyInterrupted, + conversationEvent => whenTheFactWasRaised.AddRange( + store.Live(conversationEvent.ConversationId).Select(row => row.Content.Text))); + ConversationSession session = CreateSession(OneAgentYaml, reply, store, observer); + (Task? turn, Task? spoke) = StartGatedTurn(session, "hi"); + await spoke; + + // Act + bool recorded = session.Interrupt("Hello", TimeSpan.FromMilliseconds(300)); + + // Assert + reply.OpenGate(); + await turn; + Assert.True(recorded); + Assert.Equal(["hi", "Hello"], whenTheFactWasRaised); + } - /// A store 1 write failure never ends a conversation. - [Fact] - public async Task Append_StoreThrows_ConversationContinues() - { - // Arrange - using RequestRecordingChatClient reply = new("hi there", "it ships Friday"); - var session = CreateSession(OneAgentYaml, reply, new ThrowingConversationStore()); - _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Act - var second = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); - - // Assert. The live history is the session's, so the turn after a dropped write still has the - // whole conversation. Only the durable copy was lost. - Assert.Equal("it ships Friday", second.ReplyText); - Assert.Equal( - ["user:hello", "assistant:hi there", "user:order 41?"], - reply.Requests[1]); - } + /// A store 1 write failure never ends a conversation. + [Fact] + public async Task Append_StoreThrows_ConversationContinues() + { + // Arrange + using RequestRecordingChatClient reply = new("hi there", "it ships Friday"); + ConversationSession session = CreateSession(OneAgentYaml, reply, new ThrowingConversationStore()); + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Act + TurnResult second = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); + + // Assert. The live history is the session's, so the turn after a dropped write still has the + // whole conversation. Only the durable copy was lost. + Assert.Equal("it ships Friday", second.ReplyText); + Assert.Equal( + ["user:hello", "assistant:hi there", "user:order 41?"], + reply.Requests[1]); + } - /// - /// A turn that cannot re-read store 1 as it opens says so, and runs on the words it holds. - /// - [Fact] - public async Task Resync_StoreThrows_RaisesDiagnosticAndTheTurnRuns() - { - // Arrange - using RequestRecordingChatClient reply = new("hi there", "it ships Friday"); - RecordingObserver observer = new(); - var session = CreateSession(OneAgentYaml, reply, new ThrowingConversationStore(), observer); - _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Act - var second = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); - - // Assert - Assert.Equal("it ships Friday", second.ReplyText); - var failed = Assert.Single( - observer.Events, - conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptResyncFailed); - Assert.Null(failed.EventId); - Assert.Equal(1, failed.TurnIndex); - } + /// + /// A turn that cannot re-read store 1 as it opens says so, and runs on the words it holds. + /// + [Fact] + public async Task Resync_StoreThrows_RaisesDiagnosticAndTheTurnRuns() + { + // Arrange + using RequestRecordingChatClient reply = new("hi there", "it ships Friday"); + RecordingObserver observer = new(); + ConversationSession session = CreateSession(OneAgentYaml, reply, new ThrowingConversationStore(), observer); + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Act + TurnResult second = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); + + // Assert + Assert.Equal("it ships Friday", second.ReplyText); + ConversationEvent failed = Assert.Single( + observer.Events, + conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptResyncFailed); + Assert.Null(failed.EventId); + Assert.Equal(1, failed.TurnIndex); + } - /// - /// A dropped write is a fact about the system and never about the conversation, so it is counted and - /// logged and stored nowhere. - /// - [Fact] - public async Task Append_StoreThrows_RaisesDiagnosticWithNoEventId() - { - // Arrange - using RequestRecordingChatClient reply = new("hi there"); - RecordingObserver observer = new(); - var session = CreateSession(OneAgentYaml, reply, new ThrowingConversationStore(), observer); - - // Act - _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Assert - await session.FlushTranscriptAsync(); - var dropped = Assert.Single( - observer.Events, - conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptWriteFailed); - Assert.Null(dropped.EventId); - Assert.Equal(0, dropped.TurnIndex); - - // The facts that did take an identity are the ones the chain would have written with no - // failure at all: only the dropped write itself takes no row. - var stored = observer.Events.Where(item => item.EventId is not null).ToArray(); - Assert.Equal( - [ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted], - stored.Select(item => item.Kind).ToArray()); - Assert.Equal(stored.Length, stored.Select(item => item.EventId).Distinct().Count()); - } + /// + /// A dropped write is a fact about the system and never about the conversation, so it is counted and + /// logged and stored nowhere. + /// + [Fact] + public async Task Append_StoreThrows_RaisesDiagnosticWithNoEventId() + { + // Arrange + using RequestRecordingChatClient reply = new("hi there"); + RecordingObserver observer = new(); + ConversationSession session = CreateSession(OneAgentYaml, reply, new ThrowingConversationStore(), observer); + + // Act + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Assert + await session.FlushTranscriptAsync(); + ConversationEvent dropped = Assert.Single( + observer.Events, + conversationEvent => conversationEvent.Kind == ConversationEventKind.TranscriptWriteFailed); + Assert.Null(dropped.EventId); + Assert.Equal(0, dropped.TurnIndex); + + // The facts that did take an identity are the ones the chain would have written with no + // failure at all: only the dropped write itself takes no row. + ConversationEvent[] stored = [.. observer.Events.Where(item => item.EventId is not null)]; + Assert.Equal( + [ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted], + stored.Select(item => item.Kind).ToArray()); + Assert.Equal(stored.Length, stored.Select(item => item.EventId).Distinct().Count()); + } - private static ConversationSession CreateSession( - string yaml, IChatClient reply, IConversationStore store, params IConversationObserver[] observers) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new FakeChatClientFactory(reply)) { ConversationStore = store })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null, - observers: observers).Create(); - } + private static ConversationSession CreateSession( + string yaml, IChatClient reply, IConversationStore store, params IConversationObserver[] observers) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new FakeChatClientFactory(reply)) { ConversationStore = store })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null, + observers: observers).Create(); + } - /// Starts a streaming turn on a background task and says when the caller can hear it. - private static (Task Turn, Task Spoke) StartGatedTurn(ConversationSession session, string userInput) - { - TaskCompletionSource spoke = new(TaskCreationOptions.RunContinuationsAsynchronously); - var turn = Task.Run( - async () => - { - await foreach (var _ in session - .RunTurnStreamingAsync(userInput, TestContext.Current.CancellationToken) - .ConfigureAwait(false)) + /// Starts a streaming turn on a background task and says when the caller can hear it. + private static (Task Turn, Task Spoke) StartGatedTurn(ConversationSession session, string userInput) + { + TaskCompletionSource spoke = new(TaskCreationOptions.RunContinuationsAsynchronously); + Task turn = Task.Run( + async () => { - spoke.TrySetResult(); - } - }, - CancellationToken.None); - - return (turn, spoke.Task.WaitAsync(TimeSpan.FromSeconds(10))); - } - - /// Keeps every fact of the conversation, in the order the turn loop raised them. - private sealed class RecordingObserver : IConversationObserver - { - private readonly Lock _gate = new(); - private readonly List _events = []; + await foreach (ChatResponseUpdate? update in session + .RunTurnStreamingAsync(userInput, TestContext.Current.CancellationToken) + .ConfigureAwait(false)) + { + _ = spoke.TrySetResult(); + } + }, + CancellationToken.None); + + return (turn, spoke.Task.WaitAsync(TimeSpan.FromSeconds(10))); + } - public IReadOnlyList Events + /// Keeps every fact of the conversation, in the order the turn loop raised them. + private sealed class RecordingObserver : IConversationObserver { - get + private readonly Lock _gate = new(); + private readonly List _events = []; + + public IReadOnlyList Events { - lock (_gate) + get { - return [.. _events]; + lock (_gate) + { + return [.. _events]; + } } } - } - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - { - lock (_gate) + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - _events.Add(conversationEvent); - } + lock (_gate) + { + _events.Add(conversationEvent); + } - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } - } - /// - /// Reads the world at the moment one kind of fact is raised. - /// - /// - /// The dispatcher runs an observer that completes at once on the caller's thread, so what this - /// reads is what was true when the turn loop raised the fact, and not what became true later. - /// - private sealed class WatchingObserver : IConversationObserver - { - private readonly ConversationEventKind _kind; - private readonly Action _look; - - public WatchingObserver(ConversationEventKind kind, Action look) + /// + /// Reads the world at the moment one kind of fact is raised. + /// + /// + /// The dispatcher runs an observer that completes at once on the caller's thread, so what this + /// reads is what was true when the turn loop raised the fact, and not what became true later. + /// + private sealed class WatchingObserver(ConversationEventKind kind, Action look) : IConversationObserver { - _kind = kind; - _look = look; - } + private readonly ConversationEventKind _kind = kind; + private readonly Action _look = look; - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - { - if (conversationEvent.Kind == _kind) + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - _look(conversationEvent); - } + if (conversationEvent.Kind == _kind) + { + _look(conversationEvent); + } - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs index f4f9717f..92f73efa 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs @@ -13,14 +13,14 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins the conversation's move onto one AgentSession: what the run is sent, and what store 1 keeps. -/// -public sealed class ConversationSessionTranscriptTests +namespace AgentCore.Application.Tests.Transcript { - private const string OneAgentYaml = """ + /// + /// Pins the conversation's move onto one AgentSession: what the run is sent, and what store 1 keeps. + /// + public sealed class ConversationSessionTranscriptTests + { + private const string OneAgentYaml = """ apiVersion: agentcore/v1 agents: # These tests read the exact messages the model sees; the clock line would be one more. @@ -32,7 +32,7 @@ public sealed class ConversationSessionTranscriptTests agent: only """; - private const string ToolYaml = """ + private const string ToolYaml = """ apiVersion: agentcore/v1 tools: - { id: price_lookup, kind: builtin, uses: orders.read, description: "Look up the price of an item." } @@ -44,7 +44,7 @@ public sealed class ConversationSessionTranscriptTests agent: only """; - private const string SlotYaml = """ + private const string SlotYaml = """ apiVersion: agentcore/v1 state: orderId: @@ -69,331 +69,335 @@ public sealed class ConversationSessionTranscriptTests terminal: true """; - private const string ToolResult = """{ "price": 50 }"""; - - /// - /// Item 6a and R4: the record holds the words the caller heard, and never the tail the model - /// produced. It is store 1 that must hold them, not only the live history. - /// - [Fact] - public async Task Interrupt_MidReply_StoredTranscriptHoldsHeardTextOnly() - { - // Arrange - RecordingConversationStore store = new(); - using ScriptedChatClient reply = new("Hello", " there", " caller") { GateAfterFirstFragment = true }; - var session = CreateSession(OneAgentYaml, reply, store); - var (turn, spoke) = StartGatedTurn(session, "hi"); - await spoke; - - // Act - var recorded = session.Interrupt("Hello", TimeSpan.FromMilliseconds(300)); - - // Assert - reply.OpenGate(); - await turn; - Assert.True(recorded); - await session.FlushTranscriptAsync(); - Assert.Equal(["hi", "Hello"], store.Live(session.ConversationId).Select(row => row.Content.Text)); - } - - /// - /// The vendor paces the audio, so the model finishes streaming long before the caller finishes - /// hearing, and the frame lands after the turn ended. The turn is then corrected in place — every - /// word of it, not only its last message. A line the model wrote beside the tool call it - /// announced is a line the caller may never have heard. - /// - [Fact] - public async Task InterruptAfterTheTurnEnded_ToolTurnWithProse_StoresTheHeardWordsOnce() - { - // Arrange - RecordingConversationStore store = new(); - using ProseThenReplyChatClient reply = new("the price is fifty"); - var session = CreateSession(ToolYaml, reply, store, new StubToolBuilder(ToolResult).Create); - await DrainAsync(session.RunTurnStreamingAsync("how much?", TestContext.Current.CancellationToken)); - - // Act - var recorded = session.Interrupt("the price", TimeSpan.FromMilliseconds(400)); - - // Assert - Assert.True(recorded); - await session.FlushTranscriptAsync(); - var rows = store.Live(session.ConversationId); - Assert.DoesNotContain( - rows.SelectMany(row => row.Content.Contents).OfType(), - text => text.Text.Contains(ProseThenReplyChatClient.Prose, StringComparison.Ordinal)); - - // The side effect ran, so the pair stays visible to the next turn. - Assert.Contains(rows, row => row.Content.Contents.OfType().Any()); - Assert.Contains(rows, row => row.Content.Contents.OfType().Any()); - Assert.Equal( - ["how much?", "the price"], - rows.Select(row => row.Content.Text).Where(text => text.Length > 0)); - } - - /// - /// A barge-in rewrites the assistant reply in place, but a render rides the tool-result - /// message from earlier in the same turn — a different row entirely. Correcting the reply must - /// leave that row, and what it carries, alone. - /// - [Fact] - public async Task InterruptAfterTheTurnEnded_ToolTurnThatRendered_LeavesTheRenderContentOnTheToolResultRow() - { - // Arrange - RecordingConversationStore store = new(); - using ProseThenReplyChatClient reply = new("the price is fifty"); - var session = CreateSession(ToolYaml, reply, store, RenderTool); - session.SetHasScreen(true); - await DrainAsync(session.RunTurnStreamingAsync("how much?", TestContext.Current.CancellationToken)); - - // Act - var recorded = session.Interrupt("the price", TimeSpan.FromMilliseconds(400)); - - // Assert - Assert.True(recorded); - await session.FlushTranscriptAsync(); - var rows = store.Live(session.ConversationId); - Assert.Equal( - ["how much?", "the price"], - rows.Select(row => row.Content.Text).Where(text => text.Length > 0)); - - var toolResultRow = Assert.Single(rows, row => row.Content.Contents.OfType().Any()); - var render = Assert.Single(toolResultRow.Content.Contents.OfType()); - Assert.Equal("chart-1", render.RenderId); - } - - /// - /// Drives a real turn end to end through , with a screen bound and a - /// real tool that publishes through it, and reads what store 1 actually kept. Every other render - /// test in this suite hand-rolls collectors, so none of them would notice a broken wire between - /// the turn's invocation and its renders — this is the one test that goes through that wire - /// itself. - /// - [Fact] - public async Task ATurnThatRendersWithAScreenBound_StoresTheRenderContentOnTheToolResultRow() - { - // Arrange - RecordingConversationStore store = new(); - ToolCallingChatClient reply = new("drew it."); - var session = CreateSession(ToolYaml, reply, store, RenderTool); - session.SetHasScreen(true); - - // Act - await session.RunTurnAsync("how much?", TestContext.Current.CancellationToken); - - // Assert - await session.FlushTranscriptAsync(); - var rows = store.Live(session.ConversationId); - Assert.Contains(rows.SelectMany(row => row.Content.Contents), content => content is RenderContent); - } - - /// Builds a real tool that publishes through the turn's screen, for . - private static AITool? RenderTool(ToolConfiguration tool) - => AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - turn!.Screen!.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); - return "drew it."; - }, - new AIFunctionFactoryOptions - { - Name = tool.Id, - Description = tool.Description ?? tool.Id, - ConfigureParameterBinding = ToolParameterBindings.For, - }); - - /// - /// Step 1's second failure mode: a cut that reached back a turn would replace a sentence the - /// caller heard in full, and nothing would detect it. The guard is ConversationSession's, so this - /// drives it through rather than through the provider. - /// - [Fact] - public async Task Interrupt_AfterASecondTurn_LeavesTheFirstTurnsReplyWhole() - { - // Arrange - RecordingConversationStore store = new(); - RequestRecordingChatClient reply = new("hi there caller", "it ships Friday from the depot"); - var session = CreateSession(OneAgentYaml, reply, store); - _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - _ = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); - - // Act - var recorded = session.Interrupt("it ships", TimeSpan.FromMilliseconds(500)); - - // Assert - Assert.True(recorded); - await session.FlushTranscriptAsync(); - Assert.Equal( - ["hello", "hi there caller", "order 41?", "it ships"], - store.Live(session.ConversationId).Select(row => row.Content.Text)); - } - - [Fact] - public async Task RunTurn_SecondTurn_SendsTheNewCallerMessageAloneAndTheModelStillSeesTheConversation() - { - // Arrange - RequestRecordingChatClient reply = new("hi there", "it ships Friday"); - var session = CreateSession(OneAgentYaml, reply, new RecordingConversationStore()); - _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Act - _ = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); - - // Assert - Assert.Equal( - ["user:hello", "assistant:hi there", "user:order 41?"], - reply.Requests[1]); - } - - /// - /// The reminder rides exactly one invocation, as instructions the framework merges and stores - /// nowhere. Nothing of it reaches the caller's own message, so store 1 keeps what was said. - /// - [Fact] - public async Task RunTurn_WithAnUnfilledSlot_KeepsTheReminderOutOfTheStoredTranscript() - { - // Arrange - RecordingConversationStore store = new(); - RequestRecordingChatClient reply = new("which order?"); - var session = CreateSession(SlotYaml, reply, store); - - // Act - _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - // Assert - // The reminder rides a message of its own, below the transcript, so the instructions block - // stays byte-identical across turns and the vendor's cacheable prefix covers the transcript. - Assert.DoesNotContain("", reply.Instructions[0] ?? string.Empty, StringComparison.Ordinal); - Assert.Contains(reply.Requests[0], message => message.Contains("", StringComparison.Ordinal)); - await session.FlushTranscriptAsync(); - Assert.Equal(["hello", "which order?"], store.Live(session.ConversationId).Select(row => row.Content.Text)); - } - - private static ConversationSession CreateSession( - string yaml, IChatClient reply, IConversationStore store, Func? tools = null) - { - var document = ConfigurationLoader.LoadYaml(yaml); - var chatClients = new FakeChatClientFactory(reply); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) - { - ConversationStore = store, - Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), - })["main"]; - - var factory = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null); - - return factory.Create(); - } - - /// Starts a streaming turn on a background task and says when the caller can hear it. - /// The conversation to run the turn on. - /// What the caller said. - /// The running turn, and a task that completes at its first spoken update. - /// - /// A run that has handed the host nothing is not the turn the caller is hearing, so a barge-in - /// before the first update takes the amendment path instead and records nothing. Waiting for that - /// update is what makes the cut land in the reply rather than after it. - /// - private static (Task Turn, Task Spoke) StartGatedTurn(ConversationSession session, string userInput) - { - TaskCompletionSource spoke = new(TaskCreationOptions.RunContinuationsAsynchronously); - var turn = Task.Run( - async () => - { - await foreach (var _ in session - .RunTurnStreamingAsync(userInput, TestContext.Current.CancellationToken) - .ConfigureAwait(false)) - { - spoke.TrySetResult(); - } - }, - CancellationToken.None); - - return (turn, spoke.Task.WaitAsync(TimeSpan.FromSeconds(10))); - } - - /// Runs a streaming turn to its end. No fact here reads an update. - private static async Task DrainAsync(IAsyncEnumerable updates) - { - await foreach (var _ in updates.ConfigureAwait(false)) - { - } - } - - /// Writes a line beside the tool call it announces, then answers once the result lands. - /// - /// This is what a real model produces, and it is the shape a cut has to survive: the prose and - /// the conversation ride one message, so the words and the side effect cannot be dropped together. - /// - private sealed class ProseThenReplyChatClient : IChatClient - { - /// The line the model speaks before it calls the tool. - public const string Prose = "Let me check that for you"; - - private const string ToolCallId = "conversation_1"; - - private readonly string _reply; - - public ProseThenReplyChatClient(string reply) => _reply = reply; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); - - var answered = messages.Any(message => message.Contents.OfType().Any()); - var responseId = Guid.NewGuid().ToString("N"); - - if (!answered && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [ - new TextContent(Prose), - new FunctionCallContent( - ToolCallId, tool.Name, new Dictionary(StringComparer.Ordinal)), - ]) - { - ResponseId = responseId, - MessageId = responseId, - }; - - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) - { - ResponseId = responseId, - MessageId = responseId, - }; - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - } - } + private const string ToolResult = /*lang=json,strict*/ """{ "price": 50 }"""; + + /// + /// Item 6a and R4: the record holds the words the caller heard, and never the tail the model + /// produced. It is store 1 that must hold them, not only the live history. + /// + [Fact] + public async Task Interrupt_MidReply_StoredTranscriptHoldsHeardTextOnly() + { + // Arrange + RecordingConversationStore store = new(); + using ScriptedChatClient reply = new("Hello", " there", " caller") { GateAfterFirstFragment = true }; + ConversationSession session = CreateSession(OneAgentYaml, reply, store); + (Task? turn, Task? spoke) = StartGatedTurn(session, "hi"); + await spoke; + + // Act + bool recorded = session.Interrupt("Hello", TimeSpan.FromMilliseconds(300)); + + // Assert + reply.OpenGate(); + await turn; + Assert.True(recorded); + await session.FlushTranscriptAsync(); + Assert.Equal(["hi", "Hello"], store.Live(session.ConversationId).Select(row => row.Content.Text)); + } + + /// + /// The vendor paces the audio, so the model finishes streaming long before the caller finishes + /// hearing, and the frame lands after the turn ended. The turn is then corrected in place — every + /// word of it, not only its last message. A line the model wrote beside the tool call it + /// announced is a line the caller may never have heard. + /// + [Fact] + public async Task InterruptAfterTheTurnEnded_ToolTurnWithProse_StoresTheHeardWordsOnce() + { + // Arrange + RecordingConversationStore store = new(); + using ProseThenReplyChatClient reply = new("the price is fifty"); + ConversationSession session = CreateSession(ToolYaml, reply, store, new StubToolBuilder(ToolResult).Create); + await DrainAsync(session.RunTurnStreamingAsync("how much?", TestContext.Current.CancellationToken)); + + // Act + bool recorded = session.Interrupt("the price", TimeSpan.FromMilliseconds(400)); + + // Assert + Assert.True(recorded); + await session.FlushTranscriptAsync(); + IReadOnlyList rows = store.Live(session.ConversationId); + Assert.DoesNotContain( + rows.SelectMany(row => row.Content.Contents).OfType(), + text => text.Text.Contains(ProseThenReplyChatClient.Prose, StringComparison.Ordinal)); + + // The side effect ran, so the pair stays visible to the next turn. + Assert.Contains(rows, row => row.Content.Contents.OfType().Any()); + Assert.Contains(rows, row => row.Content.Contents.OfType().Any()); + Assert.Equal( + ["how much?", "the price"], + rows.Select(row => row.Content.Text).Where(text => text.Length > 0)); + } + + /// + /// A barge-in rewrites the assistant reply in place, but a render rides the tool-result + /// message from earlier in the same turn — a different row entirely. Correcting the reply must + /// leave that row, and what it carries, alone. + /// + [Fact] + public async Task InterruptAfterTheTurnEnded_ToolTurnThatRendered_LeavesTheRenderContentOnTheToolResultRow() + { + // Arrange + RecordingConversationStore store = new(); + using ProseThenReplyChatClient reply = new("the price is fifty"); + ConversationSession session = CreateSession(ToolYaml, reply, store, RenderTool); + session.SetHasScreen(true); + await DrainAsync(session.RunTurnStreamingAsync("how much?", TestContext.Current.CancellationToken)); + + // Act + bool recorded = session.Interrupt("the price", TimeSpan.FromMilliseconds(400)); + + // Assert + Assert.True(recorded); + await session.FlushTranscriptAsync(); + IReadOnlyList rows = store.Live(session.ConversationId); + Assert.Equal( + ["how much?", "the price"], + rows.Select(row => row.Content.Text).Where(text => text.Length > 0)); + + ConversationMessage toolResultRow = Assert.Single(rows, row => row.Content.Contents.OfType().Any()); + RenderContent render = Assert.Single(toolResultRow.Content.Contents.OfType()); + Assert.Equal("chart-1", render.RenderId); + } + + /// + /// Drives a real turn end to end through , with a screen bound and a + /// real tool that publishes through it, and reads what store 1 actually kept. Every other render + /// test in this suite hand-rolls collectors, so none of them would notice a broken wire between + /// the turn's invocation and its renders — this is the one test that goes through that wire + /// itself. + /// + [Fact] + public async Task ATurnThatRendersWithAScreenBound_StoresTheRenderContentOnTheToolResultRow() + { + // Arrange + RecordingConversationStore store = new(); + ToolCallingChatClient reply = new("drew it."); + ConversationSession session = CreateSession(ToolYaml, reply, store, RenderTool); + session.SetHasScreen(true); + + // Act + _ = await session.RunTurnAsync("how much?", TestContext.Current.CancellationToken); + + // Assert + await session.FlushTranscriptAsync(); + IReadOnlyList rows = store.Live(session.ConversationId); + Assert.Contains(rows.SelectMany(row => row.Content.Contents), content => content is RenderContent); + } + + /// Builds a real tool that publishes through the turn's screen, for . + private static AITool? RenderTool(ToolConfiguration tool) + { + return AIFunctionFactory.Create( + (TurnInvocation? turn) => + { + turn!.Screen!.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); + return "drew it."; + }, + new AIFunctionFactoryOptions + { + Name = tool.Id, + Description = tool.Description ?? tool.Id, + ConfigureParameterBinding = ToolParameterBindings.For, + }); + } + + /// + /// Step 1's second failure mode: a cut that reached back a turn would replace a sentence the + /// caller heard in full, and nothing would detect it. The guard is ConversationSession's, so this + /// drives it through rather than through the provider. + /// + [Fact] + public async Task Interrupt_AfterASecondTurn_LeavesTheFirstTurnsReplyWhole() + { + // Arrange + RecordingConversationStore store = new(); + RequestRecordingChatClient reply = new("hi there caller", "it ships Friday from the depot"); + ConversationSession session = CreateSession(OneAgentYaml, reply, store); + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + _ = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); + + // Act + bool recorded = session.Interrupt("it ships", TimeSpan.FromMilliseconds(500)); + + // Assert + Assert.True(recorded); + await session.FlushTranscriptAsync(); + Assert.Equal( + ["hello", "hi there caller", "order 41?", "it ships"], + store.Live(session.ConversationId).Select(row => row.Content.Text)); + } + + [Fact] + public async Task RunTurn_SecondTurn_SendsTheNewCallerMessageAloneAndTheModelStillSeesTheConversation() + { + // Arrange + RequestRecordingChatClient reply = new("hi there", "it ships Friday"); + ConversationSession session = CreateSession(OneAgentYaml, reply, new RecordingConversationStore()); + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Act + _ = await session.RunTurnAsync("order 41?", TestContext.Current.CancellationToken); + + // Assert + Assert.Equal( + ["user:hello", "assistant:hi there", "user:order 41?"], + reply.Requests[1]); + } + + /// + /// The reminder rides exactly one invocation, as instructions the framework merges and stores + /// nowhere. Nothing of it reaches the caller's own message, so store 1 keeps what was said. + /// + [Fact] + public async Task RunTurn_WithAnUnfilledSlot_KeepsTheReminderOutOfTheStoredTranscript() + { + // Arrange + RecordingConversationStore store = new(); + RequestRecordingChatClient reply = new("which order?"); + ConversationSession session = CreateSession(SlotYaml, reply, store); + + // Act + _ = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + // Assert + // The reminder rides a message of its own, below the transcript, so the instructions block + // stays byte-identical across turns and the vendor's cacheable prefix covers the transcript. + Assert.DoesNotContain("", reply.Instructions[0] ?? string.Empty, StringComparison.Ordinal); + Assert.Contains(reply.Requests[0], message => message.Contains("", StringComparison.Ordinal)); + await session.FlushTranscriptAsync(); + Assert.Equal(["hello", "which order?"], store.Live(session.ConversationId).Select(row => row.Content.Text)); + } + + private static ConversationSession CreateSession( + string yaml, IChatClient reply, IConversationStore store, Func? tools = null) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + FakeChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) + { + ConversationStore = store, + Tools = TestToolRegistry.From(document, tools, TestContext.Current.CancellationToken), + })["main"]; + + ConversationSessionFactory factory = new( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + extractor: null); + + return factory.Create(); + } + + /// Starts a streaming turn on a background task and says when the caller can hear it. + /// The conversation to run the turn on. + /// What the caller said. + /// The running turn, and a task that completes at its first spoken update. + /// + /// A run that has handed the host nothing is not the turn the caller is hearing, so a barge-in + /// before the first update takes the amendment path instead and records nothing. Waiting for that + /// update is what makes the cut land in the reply rather than after it. + /// + private static (Task Turn, Task Spoke) StartGatedTurn(ConversationSession session, string userInput) + { + TaskCompletionSource spoke = new(TaskCreationOptions.RunContinuationsAsynchronously); + Task turn = Task.Run( + async () => + { + await foreach (ChatResponseUpdate? update in session + .RunTurnStreamingAsync(userInput, TestContext.Current.CancellationToken) + .ConfigureAwait(false)) + { + _ = spoke.TrySetResult(); + } + }, + CancellationToken.None); + + return (turn, spoke.Task.WaitAsync(TimeSpan.FromSeconds(10))); + } + + /// Runs a streaming turn to its end. No fact here reads an update. + private static async Task DrainAsync(IAsyncEnumerable updates) + { + await foreach (ChatResponseUpdate? _ in updates.ConfigureAwait(false)) + { + } + } + + /// Writes a line beside the tool call it announces, then answers once the result lands. + /// + /// This is what a real model produces, and it is the shape a cut has to survive: the prose and + /// the conversation ride one message, so the words and the side effect cannot be dropped together. + /// + private sealed class ProseThenReplyChatClient(string reply) : IChatClient + { + /// The line the model speaks before it calls the tool. + public const string Prose = "Let me check that for you"; + + private const string ToolCallId = "conversation_1"; + + private readonly string _reply = reply; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); + + bool answered = messages.Any(message => message.Contents.OfType().Any()); + string responseId = Guid.NewGuid().ToString("N"); + + if (!answered && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [ + new TextContent(Prose), + new FunctionCallContent( + ToolCallId, tool.Name, new Dictionary(StringComparer.Ordinal)), + ]) + { + ResponseId = responseId, + MessageId = responseId, + }; + + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + } + } +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs index 86ae3984..658ae538 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptCompactionTests.cs @@ -2,197 +2,208 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// The summary row inside one transcript: the view it and the live rows build together, what a -/// compaction may cover, when one is refused, and which cuts must not reach under it. -/// -public sealed class ConversationTranscriptCompactionTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public void Read_WithASummary_EmitsItFirstThenTheLiveRowsAboveWhatItCovers() + /// + /// The summary row inside one transcript: the view it and the live rows build together, what a + /// compaction may cover, when one is refused, and which cuts must not reach under it. + /// + public sealed class ConversationTranscriptCompactionTests { - var transcript = FiveTurns(); + [Fact] + public void Read_WithASummary_EmitsItFirstThenTheLiveRowsAboveWhatItCovers() + { + ConversationTranscript transcript = FiveTurns(); - var row = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + ConversationMessage? row = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - Assert.NotNull(row); - Assert.Equal(10, row.Ordinal); - Assert.Equal(3, row.CoversUpTo); - Assert.Equal(["past", "q2", "a2", "q3", "a3", "q4", "a4"], transcript.Read().Select(message => message.Text)); - } + Assert.NotNull(row); + Assert.Equal(10, row.Ordinal); + Assert.Equal(3, row.CoversUpTo); + Assert.Equal(["past", "q2", "a2", "q3", "a3", "q4", "a4"], transcript.Read().Select(message => message.Text)); + } - [Fact] - public void Compact_ASecondSummary_ReplacesTheFirstAndCoversMore() - { - var transcript = FiveTurns(); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + [Fact] + public void Compact_ASecondSummary_ReplacesTheFirstAndCoversMore() + { + ConversationTranscript transcript = FiveTurns(); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - var row = transcript.Compact(Assistant("more past"), coversUpTo: 5, transcript.Revision); + ConversationMessage? row = transcript.Compact(Assistant("more past"), coversUpTo: 5, transcript.Revision); - Assert.NotNull(row); - Assert.Equal(11, row.Ordinal); - Assert.Equal(["more past", "q3", "a3", "q4", "a4"], transcript.Read().Select(message => message.Text)); - Assert.Single(transcript.Messages, stored => stored.CoversUpTo is not null); - } + Assert.NotNull(row); + Assert.Equal(11, row.Ordinal); + Assert.Equal(["more past", "q3", "a3", "q4", "a4"], transcript.Read().Select(message => message.Text)); + _ = Assert.Single(transcript.Messages, stored => stored.CoversUpTo is not null); + } - [Fact] - public void Compact_ASummaryThatCoversLessThanTheStandingOne_Throws() - { - var transcript = FiveTurns(); - transcript.Compact(Assistant("past"), coversUpTo: 5, transcript.Revision); + [Fact] + public void Compact_ASummaryThatCoversLessThanTheStandingOne_Throws() + { + ConversationTranscript transcript = FiveTurns(); + _ = transcript.Compact(Assistant("past"), coversUpTo: 5, transcript.Revision); - Assert.Throws(() => transcript.Compact(Assistant("less"), coversUpTo: 3, transcript.Revision)); - } + _ = Assert.Throws(() => transcript.Compact(Assistant("less"), coversUpTo: 3, transcript.Revision)); + } - [Fact] - public void Compact_RefusesACompactionReadBeforeTheWordsMoved() - { - var transcript = FiveTurns(); - var revision = transcript.Revision; - transcript.BeginTurn(5); - transcript.Append([User("q5")]); + [Fact] + public void Compact_RefusesACompactionReadBeforeTheWordsMoved() + { + ConversationTranscript transcript = FiveTurns(); + int revision = transcript.Revision; + transcript.BeginTurn(5); + _ = transcript.Append([User("q5")]); - Assert.Null(transcript.Compact(Assistant("past"), coversUpTo: 3, revision)); - Assert.Null(transcript.Summary); - } + Assert.Null(transcript.Compact(Assistant("past"), coversUpTo: 3, revision)); + Assert.Null(transcript.Summary); + } - [Fact] - public void Floor_ALiveRowReportsItsOwnOrdinal_AndTheSummaryReportsWhatItCovers() - { - var transcript = FiveTurns(); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + [Fact] + public void Floor_ALiveRowReportsItsOwnOrdinal_AndTheSummaryReportsWhatItCovers() + { + ConversationTranscript transcript = FiveTurns(); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - var floor = transcript.Floor(); + TranscriptFloor? floor = transcript.Floor(); - Assert.NotNull(floor); - Assert.Equal(3, floor.Value.CoversUpTo); - Assert.Equal( - [("past", 3), ("q2", 4), ("a2", 5), ("q3", 6), ("a3", 7)], - floor.Value.Messages.Select(view => (view.Message.Text, view.LastOrdinal))); - } + _ = Assert.NotNull(floor); + Assert.Equal(3, floor.Value.CoversUpTo); + Assert.Equal( + [("past", 3), ("q2", 4), ("a2", 5), ("q3", 6), ("a3", 7)], + floor.Value.Messages.Select(view => (view.Message.Text, view.LastOrdinal))); + } - [Fact] - public void Floor_IsNothing_WhenOneTurnIsAllThatIsLive() - { - var transcript = new ConversationTranscript { ConversationId = "c1" }; - transcript.BeginTurn(0); - transcript.Append([User("q0"), Assistant("a0")]); + [Fact] + public void Floor_IsNothing_WhenOneTurnIsAllThatIsLive() + { + ConversationTranscript transcript = new() { ConversationId = "c1" }; + transcript.BeginTurn(0); + _ = transcript.Append([User("q0"), Assistant("a0")]); - Assert.Null(transcript.Floor()); + Assert.Null(transcript.Floor()); - // A summary that covers everything but the newest turn: nothing lies before that turn either. - var five = FiveTurns(); - five.Compact(Assistant("past"), coversUpTo: 7, five.Revision); - Assert.Null(five.Floor()); - } + // A summary that covers everything but the newest turn: nothing lies before that turn either. + ConversationTranscript five = FiveTurns(); + _ = five.Compact(Assistant("past"), coversUpTo: 7, five.Revision); + Assert.Null(five.Floor()); + } - [Fact] - public void Floor_LeavesTheSummaryOutOfTheNewestTurn_WhenTheTurnThatWroteItNeverLanded() - { - // The summary carries turn 5, but turn 5's own rows never landed. Turn 4 is still the newest - // live turn, so it stays out of the floor. - var transcript = FiveTurns(); - transcript.BeginTurn(5); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + [Fact] + public void Floor_LeavesTheSummaryOutOfTheNewestTurn_WhenTheTurnThatWroteItNeverLanded() + { + // The summary carries turn 5, but turn 5's own rows never landed. Turn 4 is still the newest + // live turn, so it stays out of the floor. + ConversationTranscript transcript = FiveTurns(); + transcript.BeginTurn(5); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - var floor = transcript.Floor(); + TranscriptFloor? floor = transcript.Floor(); - Assert.NotNull(floor); - Assert.Equal(["past", "q2", "a2", "q3", "a3"], floor.Value.Messages.Select(view => view.Message.Text)); - } + _ = Assert.NotNull(floor); + Assert.Equal(["past", "q2", "a2", "q3", "a3"], floor.Value.Messages.Select(view => view.Message.Text)); + } - [Fact] - public void CanTruncateFrom_UnderASummary_OnlyARowAboveWhatItCoversWillDo() - { - var transcript = FiveTurns(); - Assert.True(transcript.CanTruncateFrom(null)); - Assert.True(transcript.CanTruncateFrom("nobody")); + [Fact] + public void CanTruncateFrom_UnderASummary_OnlyARowAboveWhatItCoversWillDo() + { + ConversationTranscript transcript = FiveTurns(); + Assert.True(transcript.CanTruncateFrom(null)); + Assert.True(transcript.CanTruncateFrom("nobody")); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - Assert.False(transcript.CanTruncateFrom(null)); - Assert.False(transcript.CanTruncateFrom("nobody")); - Assert.True(transcript.CanTruncateFrom(transcript.Messages.Single(stored => stored.Ordinal == 4).MessageId)); - } + Assert.False(transcript.CanTruncateFrom(null)); + Assert.False(transcript.CanTruncateFrom("nobody")); + Assert.True(transcript.CanTruncateFrom(transcript.Messages.Single(stored => stored.Ordinal == 4).MessageId)); + } - [Fact] - public void TruncateFrom_UnderWhatTheSummaryCovers_Refuses() - { - var transcript = FiveTurns(); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + [Fact] + public void TruncateFrom_UnderWhatTheSummaryCovers_Refuses() + { + ConversationTranscript transcript = FiveTurns(); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - Assert.Throws(() => transcript.TruncateFrom(3)); - } + _ = Assert.Throws(() => transcript.TruncateFrom(3)); + } - [Fact] - public void TruncateFrom_AboveWhatTheSummaryCovers_CutsTheLiveRowsAndKeepsTheSummary() - { - // The summary sits at ordinal 10, above the cut, and stays: it was written after the rows it - // does not cover, so its ordinal says nothing about where the cut falls. - var transcript = FiveTurns(); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + [Fact] + public void TruncateFrom_AboveWhatTheSummaryCovers_CutsTheLiveRowsAndKeepsTheSummary() + { + // The summary sits at ordinal 10, above the cut, and stays: it was written after the rows it + // does not cover, so its ordinal says nothing about where the cut falls. + ConversationTranscript transcript = FiveTurns(); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - var withdrawn = transcript.TruncateFrom(6); + WithdrawnTurns? withdrawn = transcript.TruncateFrom(6); - Assert.Equal(new WithdrawnTurns(3, 4), withdrawn); - Assert.Equal(["past", "q2", "a2"], transcript.Read().Select(message => message.Text)); - Assert.NotNull(transcript.Summary); - Assert.Equal(5, transcript.LastAssistantOrdinal); - } + Assert.Equal(new WithdrawnTurns(3, 4), withdrawn); + Assert.Equal(["past", "q2", "a2"], transcript.Read().Select(message => message.Text)); + Assert.NotNull(transcript.Summary); + Assert.Equal(5, transcript.LastAssistantOrdinal); + } - [Fact] - public void Resync_WithTheSummaryAndTheRowsAboveIt_BuildsTheSameView() - { - var transcript = new ConversationTranscript { ConversationId = "c1" }; + [Fact] + public void Resync_WithTheSummaryAndTheRowsAboveIt_BuildsTheSameView() + { + ConversationTranscript transcript = new() { ConversationId = "c1" }; - transcript.Resync( - [Row(4, 2, "q2", "m4"), Row(5, 2, "a2", "m5"), Summary(6, 3, "past", coversUpTo: 3), Row(7, 3, "q3", "m7")], - nextOrdinal: 8); + transcript.Resync( + [Row(4, 2, "q2", "m4"), Row(5, 2, "a2", "m5"), Summary(6, 3, "past", coversUpTo: 3), Row(7, 3, "q3", "m7")], + nextOrdinal: 8); - Assert.Equal(["past", "q2", "a2", "q3"], transcript.Read().Select(message => message.Text)); - Assert.Equal(3, transcript.Summary?.CoversUpTo); - Assert.Equal(5, transcript.LastAssistantOrdinal); - } + Assert.Equal(["past", "q2", "a2", "q3"], transcript.Read().Select(message => message.Text)); + Assert.Equal(3, transcript.Summary?.CoversUpTo); + Assert.Equal(5, transcript.LastAssistantOrdinal); + } - [Fact] - public void TruncateLastReply_NeverRewritesTheSummary() - { - // The summary is an assistant message with text, in the same turn as the reply. A barge-in - // must cut the reply and leave the summary whole. - var transcript = FiveTurns(); - transcript.BeginTurn(5); - transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); - transcript.Append([User("q5"), Assistant("a5 in full")]); + [Fact] + public void TruncateLastReply_NeverRewritesTheSummary() + { + // The summary is an assistant message with text, in the same turn as the reply. A barge-in + // must cut the reply and leave the summary whole. + ConversationTranscript transcript = FiveTurns(); + transcript.BeginTurn(5); + _ = transcript.Compact(Assistant("past"), coversUpTo: 3, transcript.Revision); + _ = transcript.Append([User("q5"), Assistant("a5 in full")]); - var rows = transcript.TruncateLastReply("a5"); + IReadOnlyList rows = transcript.TruncateLastReply("a5"); - Assert.Equal("a5", Assert.Single(rows).Content.Text); - Assert.Equal("past", transcript.Summary?.Message.Text); - } + Assert.Equal("a5", Assert.Single(rows).Content.Text); + Assert.Equal("past", transcript.Summary?.Message.Text); + } - /// Turns 0-4, ordinals 0-9: q0/a0 .. q4/a4. - private static ConversationTranscript FiveTurns() - { - var transcript = new ConversationTranscript { ConversationId = "c1" }; - for (var turn = 0; turn < 5; turn++) + /// Turns 0-4, ordinals 0-9: q0/a0 .. q4/a4. + private static ConversationTranscript FiveTurns() { - transcript.BeginTurn(turn); - transcript.Append([User($"q{turn}"), Assistant($"a{turn}")]); + ConversationTranscript transcript = new() { ConversationId = "c1" }; + for (int turn = 0; turn < 5; turn++) + { + transcript.BeginTurn(turn); + _ = transcript.Append([User($"q{turn}"), Assistant($"a{turn}")]); + } + + return transcript; } - return transcript; - } - - /// A row whose role follows its text: a question is the user's, anything else the assistant's. - private static ConversationMessage Row(int ordinal, int turnIndex, string text, string messageId) - => new("c1", ordinal, turnIndex, new ChatMessage(text.StartsWith('q') ? ChatRole.User : ChatRole.Assistant, text), messageId); + /// A row whose role follows its text: a question is the user's, anything else the assistant's. + private static ConversationMessage Row(int ordinal, int turnIndex, string text, string messageId) + { + return new("c1", ordinal, turnIndex, new ChatMessage(text.StartsWith('q') ? ChatRole.User : ChatRole.Assistant, text), messageId); + } - private static ConversationMessage Summary(int ordinal, int turnIndex, string text, int coversUpTo) - => new("c1", ordinal, turnIndex, Assistant(text), $"s{ordinal}") { CoversUpTo = coversUpTo }; + private static ConversationMessage Summary(int ordinal, int turnIndex, string text, int coversUpTo) + { + return new("c1", ordinal, turnIndex, Assistant(text), $"s{ordinal}") { CoversUpTo = coversUpTo }; + } - private static ChatMessage User(string text) => new(ChatRole.User, text); + private static ChatMessage User(string text) + { + return new(ChatRole.User, text); + } - private static ChatMessage Assistant(string text) => new(ChatRole.Assistant, text); + private static ChatMessage Assistant(string text) + { + return new(ChatRole.Assistant, text); + } + } } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptEditTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptEditTests.cs index 16af0fde..a446982e 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptEditTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptEditTests.cs @@ -2,132 +2,139 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins what happens when a caller sends an earlier message again: what is withdrawn, what is kept, -/// and which numbers refuse to be wound back with it. -/// -public sealed class ConversationTranscriptEditTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public void Append_NamesEveryRow_AndKeepsTheNameTheCallerGaveTheFirst() + /// + /// Pins what happens when a caller sends an earlier message again: what is withdrawn, what is kept, + /// and which numbers refuse to be wound back with it. + /// + public sealed class ConversationTranscriptEditTests { - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - - var rows = transcript.Append([User("hello"), Assistant("hi")], firstMessageId: "caller-1"); - - Assert.Equal("caller-1", rows[0].MessageId); - - // The reply is named too. It has to be: the message an edit hangs off is usually a reply, and - // no caller can have named one in advance. - Assert.NotNull(rows[1].MessageId); - Assert.NotEqual(rows[0].MessageId, rows[1].MessageId); + [Fact] + public void Append_NamesEveryRow_AndKeepsTheNameTheCallerGaveTheFirst() + { + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + + IReadOnlyList rows = transcript.Append([User("hello"), Assistant("hi")], firstMessageId: "caller-1"); + + Assert.Equal("caller-1", rows[0].MessageId); + + // The reply is named too. It has to be: the message an edit hangs off is usually a reply, and + // no caller can have named one in advance. + Assert.NotNull(rows[1].MessageId); + Assert.NotEqual(rows[0].MessageId, rows[1].MessageId); + } + + [Fact] + public void TruncateFrom_DropsTheTailAndLeavesTheMarksWhereTheyAre() + { + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + transcript.BeginTurn(0); + IReadOnlyList first = transcript.Append([User("q1"), Assistant("a1")], "caller-1"); + transcript.BeginTurn(1); + _ = transcript.Append([User("q2"), Assistant("a2")], "caller-2"); + + WithdrawnTurns? went = transcript.TruncateFrom(transcript.OrdinalOf(first[1].MessageId!)!.Value + 1); + + Assert.Equal(new WithdrawnTurns(1, 1), went); + Assert.Equal(["q1", "a1"], transcript.Read().Select(message => message.Text)); + + // The withdrawn places stay spent. Store 3 is append-only and still holds rows against the + // turns that stood in them, so reissuing either number would put two turns in one place. + Assert.Equal(4, transcript.NextOrdinal); + Assert.Equal(1, transcript.TurnIndex); + } + + [Fact] + public void TruncateFrom_AimsTheNextBargeInAtTheReplyThatSurvived() + { + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + transcript.BeginTurn(0); + IReadOnlyList first = transcript.Append([User("q1"), Assistant("a1")], "caller-1"); + transcript.BeginTurn(1); + _ = transcript.Append([User("q2"), Assistant("a2")], "caller-2"); + + _ = transcript.TruncateFrom(transcript.OrdinalOf(first[1].MessageId!)!.Value + 1); + + // Without this a barge-in after an edit would aim at an ordinal no row holds any more, and + // the cut would be a silent no-op. + Assert.Equal(first[1].Ordinal, transcript.LastAssistantOrdinal); + } + + [Fact] + public void OrdinalOf_AMessageTheConversationDoesNotHold_IsNull() + { + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + _ = transcript.Append([User("hello")], "caller-1"); + + Assert.Null(transcript.OrdinalOf("never-stored")); + } + + [Fact] + public void Resume_PrefersTheStoredMarksOverTheRowsThatSurvived() + { + // A conversation that was edited: the rows of turns 1 and 2 are gone, so the rows alone would say the + // next turn is 1 and the next ordinal 2 — both of which a deleted row already used. + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + + int next = transcript.Resume( + [ + new ConversationMessage("conversation-1", 0, 0, User("q1"), "m0"), + new ConversationMessage("conversation-1", 1, 0, Assistant("a1"), "m1"), + ], + new TranscriptMarks(NextOrdinal: 6, NextTurnIndex: 3)); + + Assert.Equal(3, next); + Assert.Equal(6, transcript.NextOrdinal); + } + + [Fact] + public void Resume_SetsTheReplyABargeInWouldCut() + { + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + + _ = transcript.Resume( + [ + new ConversationMessage("conversation-1", 0, 0, User("q1"), "m0"), + new ConversationMessage("conversation-1", 1, 0, Assistant("a1"), "m1"), + + // A tool-calling turn's textless assistant message is not a reply anybody can be cut + // off in the middle of, so it must not be what the next barge-in aims at. + new ConversationMessage("conversation-1", 2, 0, new ChatMessage(ChatRole.Assistant, []), "m2"), + ], + new TranscriptMarks(NextOrdinal: 3, NextTurnIndex: 1)); + + Assert.Equal(1, transcript.LastAssistantOrdinal); + } + + [Fact] + public void Resume_ThenTruncateLastReply_ActuallyCuts() + { + // A resumed conversation has to know which reply a barge-in aims at. With no ordinal to aim at, + // TruncateLastReply returns an empty list, which the provider reports as a write it declined + // rather than as a cut it lost — so the caller is silently not heard. + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + _ = transcript.Resume( + [ + new ConversationMessage("conversation-1", 0, 0, User("q1"), "m0"), + new ConversationMessage("conversation-1", 1, 0, Assistant("it ships on Friday"), "m1"), + ], + new TranscriptMarks(NextOrdinal: 2, NextTurnIndex: 1)); + + IReadOnlyList rows = transcript.TruncateLastReply("it ships"); + + _ = Assert.Single(rows); + Assert.Equal("it ships", rows[0].Content.Text); + } + + private static ChatMessage User(string text) + { + return new(ChatRole.User, text); + } + + private static ChatMessage Assistant(string text) + { + return new(ChatRole.Assistant, text); + } } - - [Fact] - public void TruncateFrom_DropsTheTailAndLeavesTheMarksWhereTheyAre() - { - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - transcript.BeginTurn(0); - var first = transcript.Append([User("q1"), Assistant("a1")], "caller-1"); - transcript.BeginTurn(1); - transcript.Append([User("q2"), Assistant("a2")], "caller-2"); - - var went = transcript.TruncateFrom(transcript.OrdinalOf(first[1].MessageId!)!.Value + 1); - - Assert.Equal(new WithdrawnTurns(1, 1), went); - Assert.Equal(["q1", "a1"], transcript.Read().Select(message => message.Text)); - - // The withdrawn places stay spent. Store 3 is append-only and still holds rows against the - // turns that stood in them, so reissuing either number would put two turns in one place. - Assert.Equal(4, transcript.NextOrdinal); - Assert.Equal(1, transcript.TurnIndex); - } - - [Fact] - public void TruncateFrom_AimsTheNextBargeInAtTheReplyThatSurvived() - { - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - transcript.BeginTurn(0); - var first = transcript.Append([User("q1"), Assistant("a1")], "caller-1"); - transcript.BeginTurn(1); - transcript.Append([User("q2"), Assistant("a2")], "caller-2"); - - transcript.TruncateFrom(transcript.OrdinalOf(first[1].MessageId!)!.Value + 1); - - // Without this a barge-in after an edit would aim at an ordinal no row holds any more, and - // the cut would be a silent no-op. - Assert.Equal(first[1].Ordinal, transcript.LastAssistantOrdinal); - } - - [Fact] - public void OrdinalOf_AMessageTheConversationDoesNotHold_IsNull() - { - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - transcript.Append([User("hello")], "caller-1"); - - Assert.Null(transcript.OrdinalOf("never-stored")); - } - - [Fact] - public void Resume_PrefersTheStoredMarksOverTheRowsThatSurvived() - { - // A conversation that was edited: the rows of turns 1 and 2 are gone, so the rows alone would say the - // next turn is 1 and the next ordinal 2 — both of which a deleted row already used. - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - - var next = transcript.Resume( - [ - new ConversationMessage("conversation-1", 0, 0, User("q1"), "m0"), - new ConversationMessage("conversation-1", 1, 0, Assistant("a1"), "m1"), - ], - new TranscriptMarks(NextOrdinal: 6, NextTurnIndex: 3)); - - Assert.Equal(3, next); - Assert.Equal(6, transcript.NextOrdinal); - } - - [Fact] - public void Resume_SetsTheReplyABargeInWouldCut() - { - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - - transcript.Resume( - [ - new ConversationMessage("conversation-1", 0, 0, User("q1"), "m0"), - new ConversationMessage("conversation-1", 1, 0, Assistant("a1"), "m1"), - - // A tool-calling turn's textless assistant message is not a reply anybody can be cut - // off in the middle of, so it must not be what the next barge-in aims at. - new ConversationMessage("conversation-1", 2, 0, new ChatMessage(ChatRole.Assistant, []), "m2"), - ], - new TranscriptMarks(NextOrdinal: 3, NextTurnIndex: 1)); - - Assert.Equal(1, transcript.LastAssistantOrdinal); - } - - [Fact] - public void Resume_ThenTruncateLastReply_ActuallyCuts() - { - // A resumed conversation has to know which reply a barge-in aims at. With no ordinal to aim at, - // TruncateLastReply returns an empty list, which the provider reports as a write it declined - // rather than as a cut it lost — so the caller is silently not heard. - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - transcript.Resume( - [ - new ConversationMessage("conversation-1", 0, 0, User("q1"), "m0"), - new ConversationMessage("conversation-1", 1, 0, Assistant("it ships on Friday"), "m1"), - ], - new TranscriptMarks(NextOrdinal: 2, NextTurnIndex: 1)); - - var rows = transcript.TruncateLastReply("it ships"); - - Assert.Single(rows); - Assert.Equal("it ships", rows[0].Content.Text); - } - - private static ChatMessage User(string text) => new(ChatRole.User, text); - - private static ChatMessage Assistant(string text) => new(ChatRole.Assistant, text); } diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs index 7f00e532..a6cd558d 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs @@ -1,180 +1,186 @@ using System.Text.Json; -using AgentCore.Application.Runtime; using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// Pins the rules of store 1: ordinals, which reply a barge-in cuts, and what a cut keeps. -public sealed class ConversationTranscriptTests +namespace AgentCore.Application.Tests.Transcript { - private static readonly JsonElement Payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); - - [Fact] - public void Append_ToolResultCarriesARender_RowKeepsItAndMessagesStripsIt() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - var render = new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }; - var toolResult = new ChatMessage( - ChatRole.Tool, - [new FunctionResultContent("conversation-1", "50"), render]); - var plain = Assistant("the price is fifty"); - - // Act - var rows = transcript.Append([toolResult, plain]); - - // Assert - var storedToolResult = transcript.Messages[0].Message; - - // The row is untouched: Append never rebuilds the message it hands to the store, so the - // row is the exact original object, drawing and tool result both. - Assert.Same(toolResult, rows[0].Content); - Assert.Contains(render, rows[0].Content.Contents); - Assert.Single(rows[0].Content.Contents.OfType()); - - Assert.DoesNotContain(storedToolResult.Contents, content => content is RenderContent); - Assert.Single(storedToolResult.Contents.OfType()); - Assert.Equal(rows[0].Content.Role, storedToolResult.Role); - Assert.Equal(rows[0].Ordinal, transcript.Messages[0].Ordinal); - Assert.Equal(rows[0].TurnIndex, transcript.Messages[0].TurnIndex); - - Assert.Same(plain, rows[1].Content); - Assert.Same(plain, transcript.Messages[1].Message); - } - - [Fact] - public void Append_TwoTurns_AllocatesDenseUniqueOrdinals() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - transcript.BeginTurn(0); - _ = transcript.Append([User("hello"), Assistant("hi there")]); - transcript.BeginTurn(1); - - // Act - var rows = transcript.Append([User("order 41?"), Assistant("it ships Friday")]); - - // Assert - Assert.Equal([2, 3], rows.Select(row => row.Ordinal)); - Assert.Equal([1, 1], rows.Select(row => row.TurnIndex)); - } - - [Fact] - public void Append_ToolCallingTurn_AimsTheCutAtTheSpokenReply() + /// Pins the rules of store 1: ordinals, which reply a barge-in cuts, and what a cut keeps. + public sealed class ConversationTranscriptTests { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - var toolCall = new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("id", "lookup")]); - - // Act - _ = transcript.Append([User("order 41?"), toolCall, Assistant("it ships Friday")]); - - // Assert - Assert.Equal(2, transcript.LastAssistantOrdinal); - } - - [Fact] - public void TruncateLastReply_ReplyCarryingUsage_KeepsEverythingButTheWords() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - var reply = new ChatMessage( - ChatRole.Assistant, - [new TextContent("it ships Friday from the depot"), new UsageContent(new UsageDetails { OutputTokenCount = 7 })]); - _ = transcript.Append([User("order 41?"), reply]); - - // Act - var rows = transcript.TruncateLastReply("it ships"); - - // Assert - var row = Assert.Single(rows); - Assert.Equal("it ships", row.Content.Text); - Assert.Equal(7, row.Content.Contents.OfType().Single().Details.OutputTokenCount); + private static readonly JsonElement Payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); + + [Fact] + public void Append_ToolResultCarriesARender_RowKeepsItAndMessagesStripsIt() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + RenderContent render = new() { Name = "order-card", RenderId = "order-41", Data = Payload }; + ChatMessage toolResult = new( + ChatRole.Tool, + [new FunctionResultContent("conversation-1", "50"), render]); + ChatMessage plain = Assistant("the price is fifty"); + + // Act + IReadOnlyList rows = transcript.Append([toolResult, plain]); + + // Assert + ChatMessage storedToolResult = transcript.Messages[0].Message; + + // The row is untouched: Append never rebuilds the message it hands to the store, so the + // row is the exact original object, drawing and tool result both. + Assert.Same(toolResult, rows[0].Content); + Assert.Contains(render, rows[0].Content.Contents); + _ = Assert.Single(rows[0].Content.Contents.OfType()); + + Assert.DoesNotContain(storedToolResult.Contents, content => content is RenderContent); + _ = Assert.Single(storedToolResult.Contents.OfType()); + Assert.Equal(rows[0].Content.Role, storedToolResult.Role); + Assert.Equal(rows[0].Ordinal, transcript.Messages[0].Ordinal); + Assert.Equal(rows[0].TurnIndex, transcript.Messages[0].TurnIndex); + + Assert.Same(plain, rows[1].Content); + Assert.Same(plain, transcript.Messages[1].Message); + } + + [Fact] + public void Append_TwoTurns_AllocatesDenseUniqueOrdinals() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + transcript.BeginTurn(0); + _ = transcript.Append([User("hello"), Assistant("hi there")]); + transcript.BeginTurn(1); + + // Act + IReadOnlyList rows = transcript.Append([User("order 41?"), Assistant("it ships Friday")]); + + // Assert + Assert.Equal([2, 3], rows.Select(row => row.Ordinal)); + Assert.Equal([1, 1], rows.Select(row => row.TurnIndex)); + } + + [Fact] + public void Append_ToolCallingTurn_AimsTheCutAtTheSpokenReply() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + ChatMessage toolCall = new(ChatRole.Assistant, [new FunctionCallContent("id", "lookup")]); + + // Act + _ = transcript.Append([User("order 41?"), toolCall, Assistant("it ships Friday")]); + + // Assert + Assert.Equal(2, transcript.LastAssistantOrdinal); + } + + [Fact] + public void TruncateLastReply_ReplyCarryingUsage_KeepsEverythingButTheWords() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + ChatMessage reply = new( + ChatRole.Assistant, + [new TextContent("it ships Friday from the depot"), new UsageContent(new UsageDetails { OutputTokenCount = 7 })]); + _ = transcript.Append([User("order 41?"), reply]); + + // Act + IReadOnlyList rows = transcript.TruncateLastReply("it ships"); + + // Assert + ConversationMessage row = Assert.Single(rows); + Assert.Equal("it ships", row.Content.Text); + Assert.Equal(7, row.Content.Contents.OfType().Single().Details.OutputTokenCount); + } + + [Fact] + public void TruncateLastReply_TheConversationSpokeNothing_RewritesNoRow() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + _ = transcript.Append([User("hello")]); + + // Act + IReadOnlyList rows = transcript.TruncateLastReply("nothing was said"); + + // Assert + Assert.Empty(rows); + } + + /// + /// A model routinely writes a line and puts the tool call it announces on the same message. The + /// caller heard as much of the turn as the vendor played and nothing else, so the announcement + /// must not survive the cut as words the caller is recorded as having heard. + /// + [Fact] + public void TruncateLastReply_ProseBesideAToolCall_KeepsTheConversationAndDropsTheWords() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + ChatMessage announced = new( + ChatRole.Assistant, + [new TextContent("Let me check that for you"), new FunctionCallContent("conversation-1", "lookup")]); + _ = transcript.Append( + [ + User("how much?"), + announced, + new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", "50")]), + Assistant("the price is fifty"), + ]); + + // Act + IReadOnlyList rows = transcript.TruncateLastReply("the price"); + + // Assert + Assert.Equal([1, 3], rows.Select(row => row.Ordinal)); + Assert.Equal([string.Empty, "the price"], rows.Select(row => row.Content.Text)); + _ = Assert.Single(rows[0].Content.Contents.OfType()); + } + + /// + /// The held prompt of item 6a opens turn 1 while the vendor is still speaking turn 0, so the + /// reply a barge-in cuts is the one before the turn now open. Whether that turn may still be + /// corrected is ConversationSession's decision, and this class does not take it away. + /// + [Fact] + public void BeginTurn_NextTurnOpens_LeavesThePreviousReplyOpenToACut() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + transcript.BeginTurn(0); + _ = transcript.Append([User("hello"), Assistant("hi there")]); + + // Act + transcript.BeginTurn(1); + + // Assert + Assert.Equal(1, transcript.LastAssistantOrdinal); + ConversationMessage row = Assert.Single(transcript.TruncateLastReply("hi")); + Assert.Equal(0, row.TurnIndex); + } + + [Fact] + public void Read_AfterTruncate_ReturnsHeardTextNotProducedText() + { + // Arrange + ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; + _ = transcript.Append([User("order 41?"), Assistant("it ships Friday from the depot")]); + + // Act + _ = transcript.TruncateLastReply("it ships Fri"); + + // Assert + Assert.Equal(["order 41?", "it ships Fri"], transcript.Read().Select(message => message.Text)); + } + + private static ChatMessage User(string text) + { + return new(ChatRole.User, text); + } + + private static ChatMessage Assistant(string text) + { + return new(ChatRole.Assistant, text); + } } - - [Fact] - public void TruncateLastReply_TheConversationSpokeNothing_RewritesNoRow() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - _ = transcript.Append([User("hello")]); - - // Act - var rows = transcript.TruncateLastReply("nothing was said"); - - // Assert - Assert.Empty(rows); - } - - /// - /// A model routinely writes a line and puts the tool call it announces on the same message. The - /// caller heard as much of the turn as the vendor played and nothing else, so the announcement - /// must not survive the cut as words the caller is recorded as having heard. - /// - [Fact] - public void TruncateLastReply_ProseBesideAToolCall_KeepsTheConversationAndDropsTheWords() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - var announced = new ChatMessage( - ChatRole.Assistant, - [new TextContent("Let me check that for you"), new FunctionCallContent("conversation-1", "lookup")]); - _ = transcript.Append( - [ - User("how much?"), - announced, - new ChatMessage(ChatRole.Tool, [new FunctionResultContent("conversation-1", "50")]), - Assistant("the price is fifty"), - ]); - - // Act - var rows = transcript.TruncateLastReply("the price"); - - // Assert - Assert.Equal([1, 3], rows.Select(row => row.Ordinal)); - Assert.Equal([string.Empty, "the price"], rows.Select(row => row.Content.Text)); - Assert.Single(rows[0].Content.Contents.OfType()); - } - - /// - /// The held prompt of item 6a opens turn 1 while the vendor is still speaking turn 0, so the - /// reply a barge-in cuts is the one before the turn now open. Whether that turn may still be - /// corrected is ConversationSession's decision, and this class does not take it away. - /// - [Fact] - public void BeginTurn_NextTurnOpens_LeavesThePreviousReplyOpenToACut() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - transcript.BeginTurn(0); - _ = transcript.Append([User("hello"), Assistant("hi there")]); - - // Act - transcript.BeginTurn(1); - - // Assert - Assert.Equal(1, transcript.LastAssistantOrdinal); - var row = Assert.Single(transcript.TruncateLastReply("hi")); - Assert.Equal(0, row.TurnIndex); - } - - [Fact] - public void Read_AfterTruncate_ReturnsHeardTextNotProducedText() - { - // Arrange - var transcript = new ConversationTranscript { ConversationId = "conversation-1" }; - _ = transcript.Append([User("order 41?"), Assistant("it ships Friday from the depot")]); - - // Act - _ = transcript.TruncateLastReply("it ships Fri"); - - // Assert - Assert.Equal(["order 41?", "it ships Fri"], transcript.Read().Select(message => message.Text)); - } - - private static ChatMessage User(string text) => new(ChatRole.User, text); - - private static ChatMessage Assistant(string text) => new(ChatRole.Assistant, text); } diff --git a/tests/AgentCore.Application.Tests/Transcript/FileContentTests.cs b/tests/AgentCore.Application.Tests/Transcript/FileContentTests.cs index 39fd6538..525f891a 100644 --- a/tests/AgentCore.Application.Tests/Transcript/FileContentTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/FileContentTests.cs @@ -1,36 +1,36 @@ using System.Text.Json; -using AgentCore.Application.Blobs; using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// A kept file survives the trip through the transcript store. -public sealed class FileContentTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public void Kept_SurvivesTheTranscriptEncoder() + /// A kept file survives the trip through the transcript store. + public sealed class FileContentTests { - // Arrange: what the publish tool wrote, stored, read back. - FileContent file = new() + [Fact] + public void Kept_SurvivesTheTranscriptEncoder() { - Name = "chart.png", - FileId = "out/chart.png", - Title = "Sales by month", - MediaType = "image/png", - Length = 48213, - Kept = true, - }; - ChatMessage reply = new(ChatRole.Assistant, [new TextContent("see"), file]); + // Arrange: what the publish tool wrote, stored, read back. + FileContent file = new() + { + Name = "chart.png", + FileId = "out/chart.png", + Title = "Sales by month", + MediaType = "image/png", + Length = 48213, + Kept = true, + }; + ChatMessage reply = new(ChatRole.Assistant, [new TextContent("see"), file]); - // Act - var json = JsonSerializer.Serialize(reply, TranscriptJson.Options); - var restored = JsonSerializer.Deserialize(json, TranscriptJson.Options)!; + // Act + string json = JsonSerializer.Serialize(reply, TranscriptJson.Options); + ChatMessage restored = JsonSerializer.Deserialize(json, TranscriptJson.Options)!; - // Assert - var read = Assert.Single(restored.Contents.OfType()); - Assert.Equal(("chart.png", "out/chart.png", "Sales by month", "image/png", 48213L, true), (read.Name, read.FileId, read.Title, read.MediaType, read.Length, read.Kept)); - Assert.Contains("\"agentcore.file\"", json, StringComparison.Ordinal); + // Assert + FileContent read = Assert.Single(restored.Contents.OfType()); + Assert.Equal(("chart.png", "out/chart.png", "Sales by month", "image/png", 48213L, true), (read.Name, read.FileId, read.Title, read.MediaType, read.Length, read.Kept)); + Assert.Contains("\"agentcore.file\"", json, StringComparison.Ordinal); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/InnerAgentTranscriptTests.cs b/tests/AgentCore.Application.Tests/Transcript/InnerAgentTranscriptTests.cs index e191eb25..2aa4e3d9 100644 --- a/tests/AgentCore.Application.Tests/Transcript/InnerAgentTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/InnerAgentTranscriptTests.cs @@ -3,17 +3,18 @@ using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Runtime; using AgentCore.Application.Tests.Fakes; +using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins the isolation a kind: agent tool sells: the outer agent buys the inner agent's -/// answer, never its working-out. -/// -public sealed class InnerAgentTranscriptTests +namespace AgentCore.Application.Tests.Transcript { - private const string DelegatingYaml = """ + /// + /// Pins the isolation a kind: agent tool sells: the outer agent buys the inner agent's + /// answer, never its working-out. + /// + public sealed class InnerAgentTranscriptTests + { + private const string DelegatingYaml = """ apiVersion: agentcore/v1 tools: - { id: call_helper, kind: agent, agent: helper, description: "ask the helper" } @@ -31,37 +32,38 @@ public sealed class InnerAgentTranscriptTests terminal: true """; - /// - /// The inner agent runs on a session of its own, which no BeginConversation ever named, so store 1 - /// never sees its rounds. Keeping them would cost tokens on every later turn and would put the - /// inner agent's working-out into the audit record, which no consumer asked for. - /// - [Fact] - public async Task ADelegatingTurn_WritesTheOuterRoundsOnly() - { - RecordingConversationStore store = new(); - using ToolCallingChatClient model = new("done"); - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(DelegatingYaml), - new AgentCompilationContext(new FakeChatClientFactory(model)) { ConversationStore = store })["main"]; + /// + /// The inner agent runs on a session of its own, which no BeginConversation ever named, so store 1 + /// never sees its rounds. Keeping them would cost tokens on every later turn and would put the + /// inner agent's working-out into the audit record, which no consumer asked for. + /// + [Fact] + public async Task ADelegatingTurn_WritesTheOuterRoundsOnly() + { + RecordingConversationStore store = new(); + using ToolCallingChatClient model = new("done"); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(DelegatingYaml), + new AgentCompilationContext(new FakeChatClientFactory(model)) { ConversationStore = store })["main"]; - var session = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor: null).Create(); + ConversationSession session = new ConversationSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor: null).Create(); - await foreach (var _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) - { - } + await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) + { + } - await session.FlushTranscriptAsync(); + await session.FlushTranscriptAsync(); - // Outer tool call, inner answer, outer reply. The old count was two: the inner run - // never reached its own model, so a kind: agent tool never heard its agent. Three is - // the delegation actually working — and the rows below still hold, so its working-out - // stays off store 1 all the same. - Assert.Equal(3, model.Calls); - Assert.Equal( - ["user", "assistant", "tool", "assistant"], - store.Rows.Select(row => row.Content.Role.Value)); - Assert.All(store.Rows, row => Assert.Equal(session.ConversationId, row.ConversationId)); - } - } + // Outer tool call, inner answer, outer reply. The old count was two: the inner run + // never reached its own model, so a kind: agent tool never heard its agent. Three is + // the delegation actually working — and the rows below still hold, so its working-out + // stays off store 1 all the same. + Assert.Equal(3, model.Calls); + Assert.Equal( + ["user", "assistant", "tool", "assistant"], + store.Rows.Select(row => row.Content.Role.Value)); + Assert.All(store.Rows, row => Assert.Equal(session.ConversationId, row.ConversationId)); + } + } +} diff --git a/tests/AgentCore.Application.Tests/Transcript/ReaderContentTests.cs b/tests/AgentCore.Application.Tests/Transcript/ReaderContentTests.cs index 281e347c..f81e1750 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ReaderContentTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ReaderContentTests.cs @@ -2,37 +2,38 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -public sealed class ReaderContentTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public void Strip_MessageWithoutReaderContent_ReturnsTheSameInstance() + public sealed class ReaderContentTests { - ChatMessage plain = new(ChatRole.User, "hello"); + [Fact] + public void Strip_MessageWithoutReaderContent_ReturnsTheSameInstance() + { + ChatMessage plain = new(ChatRole.User, "hello"); - var stripped = Assert.Single(ReaderContent.Strip([plain])); + ChatMessage stripped = Assert.Single(ReaderContent.Strip([plain])); - Assert.Same(plain, stripped); - } + Assert.Same(plain, stripped); + } - [Fact] - public void Strip_MessageWithReaderContent_CopiesItWithoutThatContentAndLeavesTheOriginalWhole() - { - ChatMessage published = new(ChatRole.Tool, [new FunctionResultContent("call-1", "published")]) + [Fact] + public void Strip_MessageWithReaderContent_CopiesItWithoutThatContentAndLeavesTheOriginalWhole() { - MessageId = "m-7", - AuthorName = "tool", - }; - published.Contents.Add(new FileContent { Name = "report.md", FileId = "out/report.md", Kept = true }); + ChatMessage published = new(ChatRole.Tool, [new FunctionResultContent("call-1", "published")]) + { + MessageId = "m-7", + AuthorName = "tool", + }; + published.Contents.Add(new FileContent { Name = "report.md", FileId = "out/report.md", Kept = true }); - var stripped = Assert.Single(ReaderContent.Strip([published])); + ChatMessage stripped = Assert.Single(ReaderContent.Strip([published])); - Assert.NotSame(published, stripped); - Assert.Equal("m-7", stripped.MessageId); - Assert.Equal("tool", stripped.AuthorName); - Assert.Equal(ChatRole.Tool, stripped.Role); - Assert.IsType(Assert.Single(stripped.Contents)); - Assert.Equal(2, published.Contents.Count); + Assert.NotSame(published, stripped); + Assert.Equal("m-7", stripped.MessageId); + Assert.Equal("tool", stripped.AuthorName); + Assert.Equal(ChatRole.Tool, stripped.Role); + _ = Assert.IsType(Assert.Single(stripped.Contents)); + Assert.Equal(2, published.Contents.Count); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/SourceContentTests.cs b/tests/AgentCore.Application.Tests/Transcript/SourceContentTests.cs index cabfd547..d69eca2e 100644 --- a/tests/AgentCore.Application.Tests/Transcript/SourceContentTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/SourceContentTests.cs @@ -4,60 +4,61 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// A source is host-produced content that rides a message, exactly as a drawing does. It has to -/// survive the same serialiser, because the same message goes through the same store. -/// -public sealed class SourceContentTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public void SourceContent_RoundTripsThroughTranscriptJson() + /// + /// A source is host-produced content that rides a message, exactly as a drawing does. It has to + /// survive the same serialiser, because the same message goes through the same store. + /// + public sealed class SourceContentTests { - ChatMessage message = new(ChatRole.Assistant, [ - new SourceContent - { - Source = new SourceReference + [Fact] + public void SourceContent_RoundTripsThroughTranscriptJson() + { + ChatMessage message = new(ChatRole.Assistant, [ + new SourceContent { - SourceId = "card-42", - Kind = SourceKind.Document, - Title = "Spirit CT900 owner's manual", - Origin = "knowledge", - Locator = "p.27", + Source = new SourceReference + { + SourceId = "card-42", + Kind = SourceKind.Document, + Title = "Spirit CT900 owner's manual", + Origin = "knowledge", + Locator = "p.27", + }, + CallId = "call-1", }, - CallId = "call-1", - }, - ]); + ]); - var json = JsonSerializer.Serialize(message, TranscriptJson.Options); - var read = JsonSerializer.Deserialize(json, TranscriptJson.Options); + string json = JsonSerializer.Serialize(message, TranscriptJson.Options); + ChatMessage? read = JsonSerializer.Deserialize(json, TranscriptJson.Options); - var content = Assert.IsType(Assert.Single(read!.Contents)); - Assert.Equal("call-1", content.CallId); - Assert.Equal("card-42", content.Source.SourceId); - Assert.Equal(SourceKind.Document, content.Source.Kind); - Assert.Equal("Spirit CT900 owner's manual", content.Source.Title); - Assert.Equal("knowledge", content.Source.Origin); - Assert.Equal("p.27", content.Source.Locator); - Assert.Null(content.Source.Url); - Assert.Equal("text/plain", content.Source.MediaType); - } + SourceContent content = Assert.IsType(Assert.Single(read!.Contents)); + Assert.Equal("call-1", content.CallId); + Assert.Equal("card-42", content.Source.SourceId); + Assert.Equal(SourceKind.Document, content.Source.Kind); + Assert.Equal("Spirit CT900 owner's manual", content.Source.Title); + Assert.Equal("knowledge", content.Source.Origin); + Assert.Equal("p.27", content.Source.Locator); + Assert.Null(content.Source.Url); + Assert.Equal("text/plain", content.Source.MediaType); + } - [Fact] - public void SourceReference_UrlKind_KeepsItsLink() - { - SourceReference source = new() + [Fact] + public void SourceReference_UrlKind_KeepsItsLink() { - SourceId = "hit-1", - Kind = SourceKind.Url, - Title = "Spirit Fitness support", - Origin = "web-search", - Url = "https://example.com/support", - }; + SourceReference source = new() + { + SourceId = "hit-1", + Kind = SourceKind.Url, + Title = "Spirit Fitness support", + Origin = "web-search", + Url = "https://example.com/support", + }; - Assert.Equal(SourceKind.Url, source.Kind); - Assert.Equal("https://example.com/support", source.Url); - Assert.Equal(string.Empty, source.Locator); + Assert.Equal(SourceKind.Url, source.Kind); + Assert.Equal("https://example.com/support", source.Url); + Assert.Equal(string.Empty, source.Locator); + } } } diff --git a/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs b/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs index d66b8e15..3c458d4d 100644 --- a/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs @@ -4,77 +4,78 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Application.Tests.Transcript; - -/// -/// Pins against the one failure mode that matters: a column type -/// that gives back an object's keys in a different order than they were written. -/// -public sealed class TranscriptJsonTests +namespace AgentCore.Application.Tests.Transcript { - [Fact] - public void Options_RoundTripsAMessageWithOutOfOrderTypeDiscriminators() + /// + /// Pins against the one failure mode that matters: a column type + /// that gives back an object's keys in a different order than they were written. + /// + public sealed class TranscriptJsonTests { - // Arrange - var data = JsonSerializer.SerializeToElement(new + [Fact] + public void Options_RoundTripsAMessageWithOutOfOrderTypeDiscriminators() { - orderId = "41", - widget = new Dictionary { ["$type"] = "custom-widget", ["label"] = "Order #41" }, - }); + // Arrange + JsonElement data = JsonSerializer.SerializeToElement(new + { + orderId = "41", + widget = new Dictionary { ["$type"] = "custom-widget", ["label"] = "Order #41" }, + }); - var message = new ChatMessage(ChatRole.Assistant, - [ - new TextContent("here's your order"), - new FunctionCallContent("conversation-1", "lookup_order", new Dictionary { ["orderId"] = "41" }), - new FunctionResultContent("conversation-1", new { status = "shipped" }), - new UsageContent(new UsageDetails { InputTokenCount = 10, OutputTokenCount = 5 }), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = data }, - ]); + ChatMessage message = new(ChatRole.Assistant, + [ + new TextContent("here's your order"), + new FunctionCallContent("conversation-1", "lookup_order", new Dictionary { ["orderId"] = "41" }), + new FunctionResultContent("conversation-1", new { status = "shipped" }), + new UsageContent(new UsageDetails { InputTokenCount = 10, OutputTokenCount = 5 }), + new RenderContent { Name = "order-card", RenderId = "order-41", Data = data }, + ]); - var json = JsonSerializer.Serialize(message, TranscriptJson.Options); - var shuffled = MoveTypeDiscriminatorsLast(JsonNode.Parse(json)!).ToJsonString(); + string json = JsonSerializer.Serialize(message, TranscriptJson.Options); + string shuffled = MoveTypeDiscriminatorsLast(JsonNode.Parse(json)!).ToJsonString(); - // Act - var result = JsonSerializer.Deserialize(shuffled, TranscriptJson.Options)!; + // Act + ChatMessage result = JsonSerializer.Deserialize(shuffled, TranscriptJson.Options)!; - // Assert - Assert.Equal(5, result.Contents.Count); + // Assert + Assert.Equal(5, result.Contents.Count); - var render = Assert.Single(result.Contents.OfType()); - Assert.Equal("order-card", render.Name); - Assert.Equal("order-41", render.RenderId); - Assert.True(JsonNode.DeepEquals(JsonNode.Parse(data.GetRawText()), JsonNode.Parse(render.Data.GetRawText()))); - } + RenderContent render = Assert.Single(result.Contents.OfType()); + Assert.Equal("order-card", render.Name); + Assert.Equal("order-41", render.RenderId); + Assert.True(JsonNode.DeepEquals(JsonNode.Parse(data.GetRawText()), JsonNode.Parse(render.Data.GetRawText()))); + } - /// Rewrites every object in the tree so a $type key, if present, comes back last. - /// - /// jsonb sorts an object's keys, so a stored message's $type discriminator can come - /// back anywhere. This is what a read out of that column actually looks like. - /// - private static JsonNode MoveTypeDiscriminatorsLast(JsonNode node) - { - switch (node) + /// Rewrites every object in the tree so a $type key, if present, comes back last. + /// + /// jsonb sorts an object's keys, so a stored message's $type discriminator can come + /// back anywhere. This is what a read out of that column actually looks like. + /// + private static JsonNode MoveTypeDiscriminatorsLast(JsonNode node) { - case JsonObject obj: - var reordered = new JsonObject(); - foreach (var property in obj.Where(property => property.Key != "$type")) - { - reordered[property.Key] = property.Value is null ? null : MoveTypeDiscriminatorsLast(property.Value.DeepClone()); - } + switch (node) + { + case JsonObject obj: + JsonObject reordered = []; + foreach (KeyValuePair property in obj.Where(property => property.Key != "$type")) + { + reordered[property.Key] = property.Value is null ? null : MoveTypeDiscriminatorsLast(property.Value.DeepClone()); + } - if (obj.TryGetPropertyValue("$type", out var typeValue)) - { - reordered["$type"] = typeValue?.DeepClone(); - } + if (obj.TryGetPropertyValue("$type", out JsonNode? typeValue)) + { + reordered["$type"] = typeValue?.DeepClone(); + } - return reordered; + return reordered; - case JsonArray array: - var items = array.Select(item => item is null ? null : MoveTypeDiscriminatorsLast(item.DeepClone())); - return new JsonArray([.. items]); + case JsonArray array: + IEnumerable items = array.Select(item => item is null ? null : MoveTypeDiscriminatorsLast(item.DeepClone())); + return new JsonArray([.. items]); - default: - return node.DeepClone(); + default: + return node.DeepClone(); + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationChannelShapeTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationChannelShapeTests.cs index dad8944a..3a0aa316 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationChannelShapeTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationChannelShapeTests.cs @@ -3,46 +3,47 @@ using AgentCore.AspNetCore.Tests.Fakes; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// The arbiter serves a split channel exactly as it serves a bundled one. -/// -/// -/// If this file ever needs a Telnyx type to compile, D8 has failed and the seam is in the wrong -/// place. That is the whole assertion. -/// -public sealed class ConversationChannelShapeTests +namespace AgentCore.AspNetCore.Tests.Conversation { - [Fact(Timeout = 30_000)] - public async Task ASplitChannelOfTwoObjects_RunsAScriptedConversationThroughTheSameArbiter() + /// + /// The arbiter serves a split channel exactly as it serves a bundled one. + /// + /// + /// If this file ever needs a Telnyx type to compile, D8 has failed and the seam is in the wrong + /// place. That is the whole assertion. + /// + public sealed class ConversationChannelShapeTests { - var session = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var input = new FakeConversationInput(); - var channel = new ConversationChannel(input, output); + [Fact(Timeout = 30_000)] + public async Task ASplitChannelOfTwoObjects_RunsAScriptedConversationThroughTheSameArbiter() + { + ScriptedConversationPort session = new(); + FakeConversationOutput output = new(); + FakeConversationInput input = new(); + ConversationChannel channel = new(input, output); - var arbiter = new ConversationTurnArbiter( - session, - channel.Output, - new ConnectionTaskObserver(() => session.ConversationId, (_, _) => { }, (_, _, _) => { }, (_, _, _) => false), - _ => { }, - _ => { }, - TestContext.Current.CancellationToken); + ConversationTurnArbiter arbiter = new( + session, + channel.Output, + new ConnectionTaskObserver(() => session.ConversationId, (_, _) => { }, (_, _, _) => { }, (_, _, _) => false), + _ => { }, + _ => { }, + TestContext.Current.CancellationToken); - // The scripted conversation holds every turn on a gate until a test opens it, so this turn is let - // through before it starts: this test is about the shape of the channel, and never about - // the held-prompt window the arbiter's own tests use that gate for. - session.ReleaseTurn(); + // The scripted conversation holds every turn on a gate until a test opens it, so this turn is let + // through before it starts: this test is about the shape of the channel, and never about + // the held-prompt window the arbiter's own tests use that gate for. + session.ReleaseTurn(); - await arbiter.StartTurnAsync("hello"); - await arbiter.CurrentTurn; + await arbiter.StartTurnAsync("hello"); + await arbiter.CurrentTurn; - Assert.NotEmpty(output.Spoken); - Assert.Equal(1, output.Completions); + Assert.NotEmpty(output.Spoken); + Assert.Equal(1, output.Completions); - await channel.DisposeAsync(); - Assert.Equal(1, input.Disposals); - Assert.Equal(1, output.Disposals); + await channel.DisposeAsync(); + Assert.Equal(1, input.Disposals); + Assert.Equal(1, output.Disposals); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationInputPortTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationInputPortTests.cs index a515e4a5..af7dad14 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationInputPortTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationInputPortTests.cs @@ -3,65 +3,66 @@ using AgentCore.AspNetCore.Tests.Fakes; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// The two promises makes that a signature cannot: one consumer for -/// the life of the port, and a cancelled read that throws rather than passing for the end of a conversation. -/// -/// -/// Pinned on the test double, which is the only implementation reachable without a live socket. The -/// relay connection's own guard is the same three lines over the same -/// flag, but its constructor is private and RunAsync — the one way in — needs an accepted -/// WebSocket and a request's service provider, so nothing here can hold one. What keeps the two -/// honest is that both quote the same rule from the port's own doc. -/// -public sealed class ConversationInputPortTests +namespace AgentCore.AspNetCore.Tests.Conversation { - [Fact(Timeout = 30_000)] - public async Task ASecondListenAsync_ThrowsRatherThanGivingEachReaderHalfTheConversation() + /// + /// The two promises makes that a signature cannot: one consumer for + /// the life of the port, and a cancelled read that throws rather than passing for the end of a conversation. + /// + /// + /// Pinned on the test double, which is the only implementation reachable without a live socket. The + /// relay connection's own guard is the same three lines over the same + /// flag, but its constructor is private and RunAsync — the one way in — needs an accepted + /// WebSocket and a request's service provider, so nothing here can hold one. What keeps the two + /// honest is that both quote the same rule from the port's own doc. + /// + public sealed class ConversationInputPortTests { - var input = new FakeConversationInput( - new ConversationInput.Utterance("hello", "en", IsFinal: true), - new ConversationInput.Keypress("1"), - new ConversationInput.Barge("hel", TimeSpan.FromMilliseconds(240))); - - var heard = new List(); - await foreach (var item in input.ListenAsync(TestContext.Current.CancellationToken)) + [Fact(Timeout = 30_000)] + public async Task ASecondListenAsync_ThrowsRatherThanGivingEachReaderHalfTheConversation() { - heard.Add(item); - } + FakeConversationInput input = new( + new ConversationInput.Utterance("hello", "en", IsFinal: true), + new ConversationInput.Keypress("1"), + new ConversationInput.Barge("hel", TimeSpan.FromMilliseconds(240))); - // One ordered stream carries every kind, and the reader takes them in the order they - // happened rather than one stream per kind. - Assert.Equal(3, heard.Count); - Assert.Equal(new ConversationInput.Utterance("hello", "en", IsFinal: true), heard[0]); - Assert.Equal(new ConversationInput.Keypress("1"), heard[1]); - Assert.Equal(new ConversationInput.Barge("hel", TimeSpan.FromMilliseconds(240)), heard[2]); + List heard = []; + await foreach (ConversationInput item in input.ListenAsync(TestContext.Current.CancellationToken)) + { + heard.Add(item); + } - // Thrown by the conversation itself, and not by enumerating what it returns: an iterator's body - // does not run until something reads it, so a guard that waited for the first MoveNext - // would let a second reader walk away holding a stream that never says no. - Assert.Throws( - () => input.ListenAsync(TestContext.Current.CancellationToken)); - } + // One ordered stream carries every kind, and the reader takes them in the order they + // happened rather than one stream per kind. + Assert.Equal(3, heard.Count); + Assert.Equal(new ConversationInput.Utterance("hello", "en", IsFinal: true), heard[0]); + Assert.Equal(new ConversationInput.Keypress("1"), heard[1]); + Assert.Equal(new ConversationInput.Barge("hel", TimeSpan.FromMilliseconds(240)), heard[2]); - [Fact(Timeout = 30_000)] - public async Task ACancelledRead_ThrowsRatherThanPassingForTheEndOfTheConversation() - { - // The difference a consumer cannot see for itself: an await foreach that simply ends means - // the conversation is over, so a port that swallowed its own consumer's cancellation would report a - // conversation that ended when the conversation is still up. - var input = new FakeConversationInput(new ConversationInput.Keypress("1")); - using var cancellation = new CancellationTokenSource(); - await cancellation.CancelAsync(); + // Thrown by the conversation itself, and not by enumerating what it returns: an iterator's body + // does not run until something reads it, so a guard that waited for the first MoveNext + // would let a second reader walk away holding a stream that never says no. + _ = Assert.Throws( + () => input.ListenAsync(TestContext.Current.CancellationToken)); + } - await Assert.ThrowsAnyAsync(async () => + [Fact(Timeout = 30_000)] + public async Task ACancelledRead_ThrowsRatherThanPassingForTheEndOfTheConversation() { - await foreach (var item in input.ListenAsync(cancellation.Token)) + // The difference a consumer cannot see for itself: an await foreach that simply ends means + // the conversation is over, so a port that swallowed its own consumer's cancellation would report a + // conversation that ended when the conversation is still up. + FakeConversationInput input = new(new ConversationInput.Keypress("1")); + using CancellationTokenSource cancellation = new(); + await cancellation.CancelAsync(); + + _ = await Assert.ThrowsAnyAsync(async () => { - Assert.Fail($"a cancelled read yielded {item}."); - } - }); + await foreach (ConversationInput item in input.ListenAsync(cancellation.Token)) + { + Assert.Fail($"a cancelled read yielded {item}."); + } + }); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationOptionsFromDocumentTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationOptionsFromDocumentTests.cs index f7ae4854..424d64bf 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationOptionsFromDocumentTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationOptionsFromDocumentTests.cs @@ -3,108 +3,111 @@ using AgentCore.AspNetCore.Vendors.TelnyxRelay; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// The three socket limits come out of providers.conversation, and a bad one stops the start. -/// -/// -/// These replace the three map-time ArgumentOutOfRangeException facts that used to live in -/// TelnyxRelayEndpointTests. The values no longer come from a C# caller, so the failure is a -/// carrying the JSON pointer of the offending field rather -/// than an exception naming a property: a reader needs the line of the document to fix. Spec §12. -/// -public sealed class ConversationOptionsFromDocumentTests +namespace AgentCore.AspNetCore.Tests.Conversation { - private static ConversationProviderConfiguration Entry( - int? idle = null, int? close = null, int? frame = null) - => new() - { - Kind = "telnyx-relay", - IdleTimeoutSeconds = idle, - CloseTimeoutSeconds = close, - MaxFrameBytes = frame, - }; - - [Fact] - public void TheThreeKnobsReachTheOptions() + /// + /// The three socket limits come out of providers.conversation, and a bad one stops the start. + /// + /// + /// These replace the three map-time ArgumentOutOfRangeException facts that used to live in + /// TelnyxRelayEndpointTests. The values no longer come from a C# caller, so the failure is a + /// carrying the JSON pointer of the offending field rather + /// than an exception naming a property: a reader needs the line of the document to fix. Spec §12. + /// + public sealed class ConversationOptionsFromDocumentTests { - var options = TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: 30, close: 5, frame: 4096)); + private static ConversationProviderConfiguration Entry( + int? idle = null, int? close = null, int? frame = null) + { + return new() + { + Kind = "telnyx-relay", + IdleTimeoutSeconds = idle, + CloseTimeoutSeconds = close, + MaxFrameBytes = frame, + }; + } + + [Fact] + public void TheThreeKnobsReachTheOptions() + { + TelnyxRelayOptions options = TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: 30, close: 5, frame: 4096)); - Assert.Equal(TimeSpan.FromSeconds(30), options.IdleTimeout); - Assert.Equal(TimeSpan.FromSeconds(5), options.CloseTimeout); - Assert.Equal(4096, options.MaxFrameBytes); - } + Assert.Equal(TimeSpan.FromSeconds(30), options.IdleTimeout); + Assert.Equal(TimeSpan.FromSeconds(5), options.CloseTimeout); + Assert.Equal(4096, options.MaxFrameBytes); + } - [Fact] - public void AnAbsentKnobKeepsTheShippedDefault() - { - var shipped = new TelnyxRelayOptions(); + [Fact] + public void AnAbsentKnobKeepsTheShippedDefault() + { + TelnyxRelayOptions shipped = new(); - var options = TelnyxRelayConversationAdapter.BuildOptions(Entry()); + TelnyxRelayOptions options = TelnyxRelayConversationAdapter.BuildOptions(Entry()); - Assert.Equal(shipped.IdleTimeout, options.IdleTimeout); - Assert.Equal(shipped.CloseTimeout, options.CloseTimeout); - Assert.Equal(shipped.MaxFrameBytes, options.MaxFrameBytes); - } + Assert.Equal(shipped.IdleTimeout, options.IdleTimeout); + Assert.Equal(shipped.CloseTimeout, options.CloseTimeout); + Assert.Equal(shipped.MaxFrameBytes, options.MaxFrameBytes); + } - [Fact] - public void MinusOneMeansInfinite() - { - var options = TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: -1)); + [Fact] + public void MinusOneMeansInfinite() + { + TelnyxRelayOptions options = TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: -1)); - Assert.Equal(Timeout.InfiniteTimeSpan, options.IdleTimeout); - } + Assert.Equal(Timeout.InfiniteTimeSpan, options.IdleTimeout); + } - [Fact] - public void MinusOneMeansInfiniteOnTheCloseTimeoutToo() - { - // The two timeouts read the same field of the same document block, and nothing but this - // pins that they read it the same way. A close timeout that quietly turned -1 into a - // negative TimeSpan would be refused by CancelAfter on the first teardown that used it. - var options = TelnyxRelayConversationAdapter.BuildOptions(Entry(close: -1)); + [Fact] + public void MinusOneMeansInfiniteOnTheCloseTimeoutToo() + { + // The two timeouts read the same field of the same document block, and nothing but this + // pins that they read it the same way. A close timeout that quietly turned -1 into a + // negative TimeSpan would be refused by CancelAfter on the first teardown that used it. + TelnyxRelayOptions options = TelnyxRelayConversationAdapter.BuildOptions(Entry(close: -1)); - Assert.Equal(Timeout.InfiniteTimeSpan, options.CloseTimeout); - } + Assert.Equal(Timeout.InfiniteTimeSpan, options.CloseTimeout); + } - [Fact] - public void ANegativeSecondsThatIsNotMinusOneFailsTheStartWithAPointer() - { - // -1 is the one negative the document is allowed to write, and it means never. Every other - // negative is a typo, and it must be caught here rather than handed to CancelAfter, which - // refuses any negative span but -1 milliseconds at the moment teardown needs it. - var failure = Assert.Throws( - () => TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: -2))); + [Fact] + public void ANegativeSecondsThatIsNotMinusOneFailsTheStartWithAPointer() + { + // -1 is the one negative the document is allowed to write, and it means never. Every other + // negative is a typo, and it must be caught here rather than handed to CancelAfter, which + // refuses any negative span but -1 milliseconds at the moment teardown needs it. + ConfigurationLoadException failure = Assert.Throws( + () => TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: -2))); - Assert.Equal("/providers/conversation/idleTimeoutSeconds", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/conversation/idleTimeoutSeconds", failure.Errors[0].Pointer); + } - [Fact] - public void AZeroFrameCapFailsTheStartWithAPointer() - { - var failure = Assert.Throws( - () => TelnyxRelayConversationAdapter.BuildOptions(Entry(frame: 0))); + [Fact] + public void AZeroFrameCapFailsTheStartWithAPointer() + { + ConfigurationLoadException failure = Assert.Throws( + () => TelnyxRelayConversationAdapter.BuildOptions(Entry(frame: 0))); - Assert.Equal("/providers/conversation/maxFrameBytes", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/conversation/maxFrameBytes", failure.Errors[0].Pointer); + } - [Fact] - public void ATimeoutPastTheTimerCeilingFailsTheStartWithAPointer() - { - var failure = Assert.Throws( - () => TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: 5_000_000))); + [Fact] + public void ATimeoutPastTheTimerCeilingFailsTheStartWithAPointer() + { + ConfigurationLoadException failure = Assert.Throws( + () => TelnyxRelayConversationAdapter.BuildOptions(Entry(idle: 5_000_000))); - Assert.Equal("/providers/conversation/idleTimeoutSeconds", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/conversation/idleTimeoutSeconds", failure.Errors[0].Pointer); + } - [Fact] - public void ACloseTimeoutPastTheTimerCeilingFailsTheStartWithItsOwnPointer() - { - // The pointer must name the field the document actually wrote. A shared checker that - // reported idleTimeoutSeconds for both would send a reader to the wrong line. - var failure = Assert.Throws( - () => TelnyxRelayConversationAdapter.BuildOptions(Entry(close: 5_000_000))); + [Fact] + public void ACloseTimeoutPastTheTimerCeilingFailsTheStartWithItsOwnPointer() + { + // The pointer must name the field the document actually wrote. A shared checker that + // reported idleTimeoutSeconds for both would send a reader to the wrong line. + ConfigurationLoadException failure = Assert.Throws( + () => TelnyxRelayConversationAdapter.BuildOptions(Entry(close: 5_000_000))); - Assert.Equal("/providers/conversation/closeTimeoutSeconds", failure.Errors[0].Pointer); + Assert.Equal("/providers/conversation/closeTimeoutSeconds", failure.Errors[0].Pointer); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRegistrationTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRegistrationTests.cs index b3b6107d..ca58a70a 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRegistrationTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRegistrationTests.cs @@ -9,133 +9,134 @@ using Microsoft.Extensions.Hosting; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// providers.conversation is selected while the host starts, and the pairing rule runs there too. -/// -/// -/// -/// Registering a vendor is what turns this seam on, exactly as it is for telemetry, knowledge, -/// moderation, and speech. Every test here starts a host alone, with no route -/// mapped anywhere, because agreement between two document entries is a document fact and is true -/// or false whether or not anything is ever routed. -/// -/// -/// Every test runs offline against a fake model. There is no Telnyx account, no network conversation, and -/// no API key anywhere in this file. -/// -/// -public sealed class ConversationRegistrationTests +namespace AgentCore.AspNetCore.Tests.Conversation { - /// A conversation transport that is a name and a wire fact, which is all the port asks for. - private sealed class FakeConversationAdapter(string kind, bool carriesText) : IConversationAdapter + /// + /// providers.conversation is selected while the host starts, and the pairing rule runs there too. + /// + /// + /// + /// Registering a vendor is what turns this seam on, exactly as it is for telemetry, knowledge, + /// moderation, and speech. Every test here starts a host alone, with no route + /// mapped anywhere, because agreement between two document entries is a document fact and is true + /// or false whether or not anything is ever routed. + /// + /// + /// Every test runs offline against a fake model. There is no Telnyx account, no network conversation, and + /// no API key anywhere in this file. + /// + /// + public sealed class ConversationRegistrationTests { - public string Kind { get; } = kind; + /// A conversation transport that is a name and a wire fact, which is all the port asks for. + private sealed class FakeConversationAdapter(string kind, bool carriesText) : IConversationAdapter + { + public string Kind { get; } = kind; - public bool CarriesText { get; } = carriesText; - } + public bool CarriesText { get; } = carriesText; + } - [Fact] - public async Task AMatchingPairStarts() - { - using var provider = await BuildAsync( - conversationKind: "telnyx-relay", - speechKind: "telnyx-relay", - new FakeConversationAdapter("telnyx-relay", carriesText: true)); + [Fact] + public async Task AMatchingPairStarts() + { + using IHost provider = await BuildAsync( + conversationKind: "telnyx-relay", + speechKind: "telnyx-relay", + new FakeConversationAdapter("telnyx-relay", carriesText: true)); - Assert.NotNull(provider.Services.GetService>()); - } + Assert.NotNull(provider.Services.GetService>()); + } - [Fact] - public async Task AMismatchedPairFailsTheStartEvenWithNoRouteMapped() - { - var failure = await Assert.ThrowsAsync( - async () => await BuildAsync( - conversationKind: "telnyx-relay", - speechKind: "deepgram", - new FakeConversationAdapter("telnyx-relay", carriesText: true))); + [Fact] + public async Task AMismatchedPairFailsTheStartEvenWithNoRouteMapped() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await BuildAsync( + conversationKind: "telnyx-relay", + speechKind: "deepgram", + new FakeConversationAdapter("telnyx-relay", carriesText: true))); - Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/speech/stt/kind", failure.Errors[0].Pointer); + } - [Fact] - public async Task AHostThatRegistersNoConversationAdapterIsNotAskedAnything() - { - // The seam is off, exactly as telemetry, knowledge, and moderation are when nothing is - // registered for them. A contradictory document is not read, and the start succeeds. - using var provider = await BuildAsync(conversationKind: "telnyx-relay", speechKind: "deepgram"); + [Fact] + public async Task AHostThatRegistersNoConversationAdapterIsNotAskedAnything() + { + // The seam is off, exactly as telemetry, knowledge, and moderation are when nothing is + // registered for them. A contradictory document is not read, and the start succeeds. + using IHost provider = await BuildAsync(conversationKind: "telnyx-relay", speechKind: "deepgram"); - Assert.Null(provider.Services.GetService>()); - } + Assert.Null(provider.Services.GetService>()); + } - [Fact] - public async Task ADocumentNamingAnUnregisteredConversationKindFailsTheStart() - { - var failure = await Assert.ThrowsAsync( - async () => await BuildAsync( - conversationKind: "sip", - speechKind: "sip", - new FakeConversationAdapter("telnyx-relay", carriesText: true))); + [Fact] + public async Task ADocumentNamingAnUnregisteredConversationKindFailsTheStart() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await BuildAsync( + conversationKind: "sip", + speechKind: "sip", + new FakeConversationAdapter("telnyx-relay", carriesText: true))); - Assert.Equal("/providers/conversation/kind", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/conversation/kind", failure.Errors[0].Pointer); + } - // --------------------------------------------------------------------------------------------- - // The two blocks are required by the schema, so a loaded document that writes a providers - // section carries both. A configuration a host built in code passes through no schema at all, - // and so does a loaded document that writes no providers section: the root requires only - // apiVersion and name. Both routes reach the guard with a block missing, and both are refused - // by a message that names the block rather than by a NullReferenceException. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AConfigurationBuiltInCodeWithNoConversationBlockFailsTheStart() - { - var failure = await Assert.ThrowsAsync( - async () => await BuildFromAsync( - InCode(new ProvidersConfiguration - { - Llm = OneModel, - Speech = new SpeechProviderConfiguration + // --------------------------------------------------------------------------------------------- + // The two blocks are required by the schema, so a loaded document that writes a providers + // section carries both. A configuration a host built in code passes through no schema at all, + // and so does a loaded document that writes no providers section: the root requires only + // apiVersion and name. Both routes reach the guard with a block missing, and both are refused + // by a message that names the block rather than by a NullReferenceException. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AConfigurationBuiltInCodeWithNoConversationBlockFailsTheStart() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await BuildFromAsync( + InCode(new ProvidersConfiguration { - Stt = new VendorProviderConfiguration { Kind = "telnyx-relay" }, - Tts = new VendorProviderConfiguration { Kind = "telnyx-relay" }, - }, - }), - new FakeConversationAdapter("telnyx-relay", carriesText: true))); - - Assert.Equal("/providers/conversation", failure.Errors[0].Pointer); - } + Llm = OneModel, + Speech = new SpeechProviderConfiguration + { + Stt = new VendorProviderConfiguration { Kind = "telnyx-relay" }, + Tts = new VendorProviderConfiguration { Kind = "telnyx-relay" }, + }, + }), + new FakeConversationAdapter("telnyx-relay", carriesText: true))); + + Assert.Equal("/providers/conversation", failure.Errors[0].Pointer); + } - [Fact] - public async Task AConfigurationBuiltInCodeWithNoSpeechBlockFailsTheStart() - { - var failure = await Assert.ThrowsAsync( - async () => await BuildFromAsync( - InCode(new ProvidersConfiguration - { - Llm = OneModel, - Conversation = new ConversationProviderConfiguration { Kind = "telnyx-relay" }, - }), - new FakeConversationAdapter("telnyx-relay", carriesText: true))); + [Fact] + public async Task AConfigurationBuiltInCodeWithNoSpeechBlockFailsTheStart() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await BuildFromAsync( + InCode(new ProvidersConfiguration + { + Llm = OneModel, + Conversation = new ConversationProviderConfiguration { Kind = "telnyx-relay" }, + }), + new FakeConversationAdapter("telnyx-relay", carriesText: true))); - Assert.Equal("/providers/speech", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/speech", failure.Errors[0].Pointer); + } - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- - /// The one model every document here names, so the compile has something to resolve. - private static IReadOnlyList OneModel { get; } = - [new LlmProviderConfiguration { Kind = "openai", Model = "gpt-4.1-mini", As = "reply" }]; + /// The one model every document here names, so the compile has something to resolve. + private static IReadOnlyList OneModel { get; } = + [new LlmProviderConfiguration { Kind = "openai", Model = "gpt-4.1-mini", As = "reply" }]; - /// Writes one document that names both required blocks. - /// The value providers.conversation.kind carries. - /// The value both speech roles carry, stt and tts alike. - /// The document text. - private static string Document(string conversationKind, string speechKind) - => $$""" + /// Writes one document that names both required blocks. + /// The value providers.conversation.kind carries. + /// The value both speech roles carry, stt and tts alike. + /// The document text. + private static string Document(string conversationKind, string speechKind) + { + return $$""" apiVersion: agentcore/v1 providers: conversation: { kind: {{conversationKind}} } @@ -151,75 +152,81 @@ private static string Document(string conversationKind, string speechKind) main: agent: dummy """; + } - /// Builds a configuration the way a host that loads no document does. - /// The providers block, with one of the two required entries left out. - /// The configuration. - private static AgentCoreConfiguration InCode(ProvidersConfiguration providers) - => new() + /// Builds a configuration the way a host that loads no document does. + /// The providers block, with one of the two required entries left out. + /// The configuration. + private static AgentCoreConfiguration InCode(ProvidersConfiguration providers) { - ApiVersion = AgentCoreConfiguration.SupportedApiVersion, - Agents = new AgentsConfiguration - { - Items = [new AgentConfiguration { Id = "only", Instructions = "I answer everything" }], - }, - Entries = new Dictionary + return new() { - ["main"] = new EntryConfiguration { Agent = "only" }, - }, - Providers = providers, - }; - - /// Starts a host on a document that names both kinds. - /// The value providers.conversation.kind carries. - /// The value both speech roles carry, stt and tts alike. - /// The conversation transports this host registers, if any. - /// The composed container. - private static Task BuildAsync( - string conversationKind, - string speechKind, - params IConversationAdapter[] adapters) - => BuildFromAsync(ConfigurationLoader.LoadYaml(Document(conversationKind, speechKind)), adapters); - - /// Starts a host on one configuration, however that configuration was made. - /// The document, loaded or built in code. - /// The conversation transports this host registers, if any. - /// The composed container. - /// - /// UseConversation is called only when this host has something to register. Calling it with an - /// empty list would turn the seam on for a host that registered no vendor, which is the one - /// thing these tests prove does not happen. - /// - private static async Task BuildFromAsync( - AgentCoreConfiguration configuration, - params IConversationAdapter[] adapters) - { - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only", Instructions = "I answer everything" }], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "only" }, + }, + Providers = providers, + }; + } + + /// Starts a host on a document that names both kinds. + /// The value providers.conversation.kind carries. + /// The value both speech roles carry, stt and tts alike. + /// The conversation transports this host registers, if any. + /// The composed container. + private static Task BuildAsync( + string conversationKind, + string speechKind, + params IConversationAdapter[] adapters) + { + return BuildFromAsync(ConfigurationLoader.LoadYaml(Document(conversationKind, speechKind)), adapters); + } - builder.Services.AddAgentCore(options => + /// Starts a host on one configuration, however that configuration was made. + /// The document, loaded or built in code. + /// The conversation transports this host registers, if any. + /// The composed container. + /// + /// UseConversation is called only when this host has something to register. Calling it with an + /// empty list would turn the seam on for a host that registered no vendor, which is the one + /// thing these tests prove does not happen. + /// + private static async Task BuildFromAsync( + AgentCoreConfiguration configuration, + params IConversationAdapter[] adapters) { - options.Configuration = configuration; - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - options.UseSpeech(new TelnyxRelaySpeechAdapter()); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + + _ = builder.Services.AddAgentCore(options => + { + options.Configuration = configuration; + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + _ = options.UseSpeech(new TelnyxRelaySpeechAdapter()); + + if (adapters.Length > 0) + { + _ = options.UseConversation(adapters); + } + }); - if (adapters.Length > 0) + IHost host = builder.Build(); + try + { + await host.StartAsync(TestContext.Current.CancellationToken); + } + catch { - options.UseConversation(adapters); + // A failed start never stops what started, so disposal is the only cleanup path. + host.Dispose(); + throw; } - }); - var host = builder.Build(); - try - { - await host.StartAsync(TestContext.Current.CancellationToken); + return host; } - catch - { - // A failed start never stops what started, so disposal is the only cleanup path. - host.Dispose(); - throw; - } - - return host; } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRouteSelectionTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRouteSelectionTests.cs index 4f88664d..af4aeb2a 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRouteSelectionTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationRouteSelectionTests.cs @@ -13,162 +13,165 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// providers.conversation decides which transport answers the one conversation route, and whether a conversation -/// routes here at all. -/// -/// -/// -/// No fake here names Telnyx, and this file references no vendor type. That is the point of -/// the seam — spec §12. If this file ever needs a vendor type to prove the route, the selection has -/// leaked back into the vendor. -/// -/// -/// The selection happens while the host starts and not while the route is mapped, so these read -/// rather than MapCall. A host maps its routes on a built -/// application, which is after the document has been read; deciding there would mean a document -/// edit could silently leave the path a 404. -/// -/// -/// Every test runs offline. There is no account, no network conversation, and no API key anywhere in this -/// file. -/// -/// -public sealed class ConversationRouteSelectionTests +namespace AgentCore.AspNetCore.Tests.Conversation { - [Fact] - public void TheTransportTheDocumentNamesIsAskedForItsHandler() + /// + /// providers.conversation decides which transport answers the one conversation route, and whether a conversation + /// routes here at all. + /// + /// + /// + /// No fake here names Telnyx, and this file references no vendor type. That is the point of + /// the seam — spec §12. If this file ever needs a vendor type to prove the route, the selection has + /// leaked back into the vendor. + /// + /// + /// The selection happens while the host starts and not while the route is mapped, so these read + /// rather than MapCall. A host maps its routes on a built + /// application, which is after the document has been read; deciding there would mean a document + /// edit could silently leave the path a 404. + /// + /// + /// Every test runs offline. There is no account, no network conversation, and no API key anywhere in this + /// file. + /// + /// + public sealed class ConversationRouteSelectionTests { - var transport = new FakeTransport("bundled-fake"); + [Fact] + public void TheTransportTheDocumentNamesIsAskedForItsHandler() + { + FakeTransport transport = new("bundled-fake"); - var seams = Build(conversationKind: "bundled-fake", transport); + ConversationSeamAdapters seams = Build(conversationKind: "bundled-fake", transport); - Assert.NotNull(seams.Handler); + Assert.NotNull(seams.Handler); - // The block handed over is the providers.conversation entry of this document, not null and not some - // empty stand-in. The kind is what proves which entry it is. - Assert.NotNull(transport.Configuration); - Assert.Equal("bundled-fake", transport.Configuration.Kind); + // The block handed over is the providers.conversation entry of this document, not null and not some + // empty stand-in. The kind is what proves which entry it is. + Assert.NotNull(transport.Configuration); + Assert.Equal("bundled-fake", transport.Configuration.Kind); - // And nothing reports the route as unroutable when one does route. - Assert.Null(seams.Unroutable); - } + // And nothing reports the route as unroutable when one does route. + Assert.Null(seams.Unroutable); + } - [Fact] - public void AKindNoRegisteredAdapterServesFailsTheStartWithAPointer() - { - // The host registers a transport, and the document names a different vendor. That is a - // deployment that would otherwise start with no inbound conversation route and no reason given, so - // the boot must refuse it, with the pointer of the field the reader has to fix. - var failure = Assert.Throws( - () => Build(conversationKind: "no-such-vendor", new FakeTransport("bundled-fake"))); + [Fact] + public void AKindNoRegisteredAdapterServesFailsTheStartWithAPointer() + { + // The host registers a transport, and the document names a different vendor. That is a + // deployment that would otherwise start with no inbound conversation route and no reason given, so + // the boot must refuse it, with the pointer of the field the reader has to fix. + ConfigurationLoadException failure = Assert.Throws( + () => Build(conversationKind: "no-such-vendor", new FakeTransport("bundled-fake"))); - Assert.Equal("/providers/conversation/kind", failure.Errors[0].Pointer); - } + Assert.Equal("/providers/conversation/kind", failure.Errors[0].Pointer); + } - [Fact] - public void ADialOutVendorRoutesNothingAndSaysWhy() - { - var seams = Build(conversationKind: "dial-out-fake", new FakeDialOut("dial-out-fake")); + [Fact] + public void ADialOutVendorRoutesNothingAndSaysWhy() + { + ConversationSeamAdapters seams = Build(conversationKind: "dial-out-fake", new FakeDialOut("dial-out-fake")); - // Section 12 asks this case to route nothing AND say so. A route that vanishes in silence is - // how a deployment loses every call to a 404 with nothing to read. - Assert.Null(seams.Handler); - Assert.NotNull(seams.Unroutable); - Assert.Contains("dial-out-fake", seams.Unroutable, StringComparison.Ordinal); - } + // Section 12 asks this case to route nothing AND say so. A route that vanishes in silence is + // how a deployment loses every call to a 404 with nothing to read. + Assert.Null(seams.Handler); + Assert.NotNull(seams.Unroutable); + Assert.Contains("dial-out-fake", seams.Unroutable, StringComparison.Ordinal); + } - [Fact] - public void AHostThatRegisteredNoTransportRoutesNothingAndSaysWhy() - { - var seams = ConversationSeamStartup.Build( - ConfigurationLoader.LoadYaml(Document("bundled-fake")), new AgentCoreOptions()); + [Fact] + public void AHostThatRegisteredNoTransportRoutesNothingAndSaysWhy() + { + ConversationSeamAdapters seams = ConversationSeamStartup.Build( + ConfigurationLoader.LoadYaml(Document("bundled-fake")), new AgentCoreOptions()); - Assert.Null(seams.Handler); - Assert.NotNull(seams.Unroutable); - Assert.Contains("no conversation adapter", seams.Unroutable, StringComparison.Ordinal); - } + Assert.Null(seams.Handler); + Assert.NotNull(seams.Unroutable); + Assert.Contains("no conversation adapter", seams.Unroutable, StringComparison.Ordinal); + } - [Fact] - public async Task AHostWithNoAgentCoreRegistrationAnswersTheRouteWithAReason() - { - var builder = WebApplication.CreateSlimBuilder(); - builder.Logging.ClearProviders(); - builder.WebHost.UseUrls("http://127.0.0.1:0"); - - await using var app = builder.Build(); - app.MapCall(); - await app.StartAsync(TestContext.Current.CancellationToken); - - using HttpClient client = new() { BaseAddress = new Uri(Address(app)) }; - var response = await client.GetAsync("/v1/main/call", TestContext.Current.CancellationToken); - - // A readable refusal, and not the 404 a route that mapped nothing would have produced. - Assert.Equal(System.Net.HttpStatusCode.ServiceUnavailable, response.StatusCode); - Assert.Contains( - "registered no AgentCore services", - await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken), - StringComparison.Ordinal); - } + [Fact] + public async Task AHostWithNoAgentCoreRegistrationAnswersTheRouteWithAReason() + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + _ = builder.Logging.ClearProviders(); + _ = builder.WebHost.UseUrls("http://127.0.0.1:0"); + + await using WebApplication app = builder.Build(); + _ = app.MapCall(); + await app.StartAsync(TestContext.Current.CancellationToken); + + using HttpClient client = new() { BaseAddress = new Uri(Address(app)) }; + HttpResponseMessage response = await client.GetAsync("/v1/main/call", TestContext.Current.CancellationToken); + + // A readable refusal, and not the 404 a route that mapped nothing would have produced. + Assert.Equal(System.Net.HttpStatusCode.ServiceUnavailable, response.StatusCode); + Assert.Contains( + "registered no AgentCore services", + await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken), + StringComparison.Ordinal); + } - [Fact] - public void TheDefaultPatternIsVendorNeutral() - { - Assert.Equal("/v1/{entry}/call", ConversationEndpointRouteBuilderExtensions.DefaultPattern); - } + [Fact] + public void TheDefaultPatternIsVendorNeutral() + { + Assert.Equal("/v1/{entry}/call", ConversationEndpointRouteBuilderExtensions.DefaultPattern); + } - [Fact] - public void ARouteWithNoEntryParameterIsRefused() - { - var builder = WebApplication.CreateSlimBuilder(); - using var app = builder.Build(); + [Fact] + public void ARouteWithNoEntryParameterIsRefused() + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + using WebApplication app = builder.Build(); - var failure = Assert.Throws(() => app.MapCall("/v1/conversation")); + ArgumentException failure = Assert.Throws(() => app.MapCall("/v1/conversation")); - Assert.Contains("{entry}", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("{entry}", failure.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- - /// Runs the conversation seam over one document and the adapters a host registered. - /// The value providers.conversation.kind carries. - /// The conversation vendors this host registers. - /// What the seam produced. - private static ConversationSeamAdapters Build(string conversationKind, params IConversationAdapter[] adapters) - { - AgentCoreOptions options = new(); - options.UseConversation(adapters); - options.UseSpeech(new FakeSpeech(conversationKind)); + /// Runs the conversation seam over one document and the adapters a host registered. + /// The value providers.conversation.kind carries. + /// The conversation vendors this host registers. + /// What the seam produced. + private static ConversationSeamAdapters Build(string conversationKind, params IConversationAdapter[] adapters) + { + AgentCoreOptions options = new(); + _ = options.UseConversation(adapters); + _ = options.UseSpeech(new FakeSpeech(conversationKind)); - return ConversationSeamStartup.Build(ConfigurationLoader.LoadYaml(Document(conversationKind)), options); - } + return ConversationSeamStartup.Build(ConfigurationLoader.LoadYaml(Document(conversationKind)), options); + } - /// Reads back the port the server bound, since the test asked for any free one. - /// The started application. - /// The base address to send to. - private static string Address(WebApplication app) - => app.Services - .GetRequiredService() - .Features - .Get()! - .Addresses - .First(); - - /// Writes one document that names both blocks section 8.2 requires of one another. - /// The value providers.conversation.kind carries. - /// The document text. - /// - /// Written line by line here rather than at each call site, because the block sits under - /// providers: and YAML indentation written by hand at a conversation site is how test documents - /// go wrong. speech names the same kind as conversation because the schema requires the - /// block to exist; nothing in this file selects a speech vendor. - /// - private static string Document(string conversationKind) - => $$""" + /// Reads back the port the server bound, since the test asked for any free one. + /// The started application. + /// The base address to send to. + private static string Address(WebApplication app) + { + return app.Services + .GetRequiredService() + .Features + .Get()! + .Addresses + .First(); + } + + /// Writes one document that names both blocks section 8.2 requires of one another. + /// The value providers.conversation.kind carries. + /// The document text. + /// + /// Written line by line here rather than at each call site, because the block sits under + /// providers: and YAML indentation written by hand at a conversation site is how test documents + /// go wrong. speech names the same kind as conversation because the schema requires the + /// block to exist; nothing in this file selects a speech vendor. + /// + private static string Document(string conversationKind) + { + return $$""" apiVersion: agentcore/v1 providers: conversation: { kind: {{conversationKind}} } @@ -184,39 +187,41 @@ private static string Document(string conversationKind) main: agent: dummy """; + } - /// A transport that answers a conversation and names no vendor. - /// - /// It records the block the seam is supposed to hand it. Recording only that - /// CreateHandler ran would let a seam that resolved the document block to something other - /// than the one the reader wrote still pass. - /// - private sealed class FakeTransport(string kind) : IConversationTransportAdapter - { - public string Kind { get; } = kind; + /// A transport that answers a conversation and names no vendor. + /// + /// It records the block the seam is supposed to hand it. Recording only that + /// CreateHandler ran would let a seam that resolved the document block to something other + /// than the one the reader wrote still pass. + /// + private sealed class FakeTransport(string kind) : IConversationTransportAdapter + { + public string Kind { get; } = kind; - public bool CarriesText => true; + public bool CarriesText => true; - public ConversationProviderConfiguration? Configuration { get; private set; } + public ConversationProviderConfiguration? Configuration { get; private set; } - public RequestDelegate CreateHandler(ConversationProviderConfiguration configuration) - { - Configuration = configuration; - return _ => Task.CompletedTask; + public RequestDelegate CreateHandler(ConversationProviderConfiguration configuration) + { + Configuration = configuration; + return _ => Task.CompletedTask; + } } - } - /// A vendor this process dials out to. It has no route to answer. - private sealed class FakeDialOut(string kind) : IConversationAdapter - { - public string Kind { get; } = kind; + /// A vendor this process dials out to. It has no route to answer. + private sealed class FakeDialOut(string kind) : IConversationAdapter + { + public string Kind { get; } = kind; - public bool CarriesText => false; - } + public bool CarriesText => false; + } - /// The speech vendor the pairing rule reads, which builds nothing. - private sealed class FakeSpeech(string kind) : ISpeechAdapter - { - public string Kind { get; } = kind; + /// The speech vendor the pairing rule reads, which builds nothing. + private sealed class FakeSpeech(string kind) : ISpeechAdapter + { + public string Kind { get; } = kind; + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationTurnArbiterTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationTurnArbiterTests.cs index 22e384d6..70776cca 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationTurnArbiterTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/ConversationTurnArbiterTests.cs @@ -8,304 +8,314 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// The three questions the arbiter answers, with no socket and no vendor frame in sight. -/// -public sealed class ConversationTurnArbiterTests +namespace AgentCore.AspNetCore.Tests.Conversation { - [Fact(Timeout = 30_000)] - public async Task ASecondUtteranceDuringATurn_IsHeldAndRunsWhenTheTurnEnds() + /// + /// The three questions the arbiter answers, with no socket and no vendor frame in sight. + /// + public sealed class ConversationTurnArbiterTests { - // One is held. The turn in flight finishes, and the held one runs inside its own ending. - var session = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var arbiter = NewArbiter(session, output); + [Fact(Timeout = 30_000)] + public async Task ASecondUtteranceDuringATurn_IsHeldAndRunsWhenTheTurnEnds() + { + // One is held. The turn in flight finishes, and the held one runs inside its own ending. + ScriptedConversationPort session = new(); + FakeConversationOutput output = new(); + ConversationTurnArbiter arbiter = NewArbiter(session, output); - var first = arbiter.StartTurnAsync("one"); - await arbiter.StartTurnAsync("two"); + Task first = arbiter.StartTurnAsync("one"); + await arbiter.StartTurnAsync("two"); - session.ReleaseTurn(); - await first; - await arbiter.CurrentTurn; + session.ReleaseTurn(); + await first; + await arbiter.CurrentTurn; - Assert.Equal(["one", "two"], session.TurnsRun); - } + Assert.Equal(["one", "two"], session.TurnsRun); + } - [Fact(Timeout = 30_000)] - public async Task APendingApprovalTurn_SpeaksTheNoticeInsteadOfHangingInSilence() - { - // A voice conversation has no surface to answer an approval on, so the pending turn speaks - // nothing. The arbiter says so instead of closing the reply in silence. - var session = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var arbiter = NewArbiter(session, output); - session.ReleaseTurn(); - - using var empty = JsonDocument.Parse("{}"); - session.LastTurn = new TurnResult("conversation-scripted", 0, string.Empty, string.Empty, string.Empty, false, null) + [Fact(Timeout = 30_000)] + public async Task APendingApprovalTurn_SpeaksTheNoticeInsteadOfHangingInSilence() { - Approvals = [new PendingApproval("req-1", "send_email", empty.RootElement.Clone())], - }; + // A voice conversation has no surface to answer an approval on, so the pending turn speaks + // nothing. The arbiter says so instead of closing the reply in silence. + ScriptedConversationPort session = new(); + FakeConversationOutput output = new(); + ConversationTurnArbiter arbiter = NewArbiter(session, output); + session.ReleaseTurn(); + + using JsonDocument empty = JsonDocument.Parse("{}"); + session.LastTurn = new TurnResult("conversation-scripted", 0, string.Empty, string.Empty, string.Empty, false, null) + { + Approvals = [new PendingApproval("req-1", "send_email", empty.RootElement.Clone())], + }; - await arbiter.StartTurnAsync("one"); - await arbiter.CurrentTurn; + await arbiter.StartTurnAsync("one"); + await arbiter.CurrentTurn; - Assert.Contains(ConversationTurnArbiter.PendingApprovalNotice, output.Spoken); - } + Assert.Contains(ConversationTurnArbiter.PendingApprovalNotice, output.Spoken); + } - [Fact(Timeout = 30_000)] - public async Task AThirdUtteranceDuringATurn_IsDroppedRatherThanQueued() - { - // A queue of held prompts would answer questions the caller has already moved past. - var session = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var arbiter = NewArbiter(session, output); + [Fact(Timeout = 30_000)] + public async Task AThirdUtteranceDuringATurn_IsDroppedRatherThanQueued() + { + // A queue of held prompts would answer questions the caller has already moved past. + ScriptedConversationPort session = new(); + FakeConversationOutput output = new(); + ConversationTurnArbiter arbiter = NewArbiter(session, output); - var first = arbiter.StartTurnAsync("one"); - await arbiter.StartTurnAsync("two"); - await arbiter.StartTurnAsync("three"); + Task first = arbiter.StartTurnAsync("one"); + await arbiter.StartTurnAsync("two"); + await arbiter.StartTurnAsync("three"); - session.ReleaseTurn(); - await first; - await arbiter.CurrentTurn; + session.ReleaseTurn(); + await first; + await arbiter.CurrentTurn; - Assert.Equal(["one", "two"], session.TurnsRun); - } + Assert.Equal(["one", "two"], session.TurnsRun); + } - [Fact(Timeout = 30_000)] - public async Task ABargeInDuringTheHeldPromptWindow_CutsTheTurnTheCallerWasHearing() - { - // Turn one finished streaming and turn two started inside its ending, but the caller is - // still hearing turn one. The record belongs to turn one, and turn two must keep speaking. - var session = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var arbiter = NewArbiter(session, output); - - // Opened before the first turn, not during it: this test needs turn one to finish streaming - // on its own, and nothing here ever comes back to open a gate the two tests above open while - // a turn is deliberately held in flight. - session.ReleaseTurn(); - - await arbiter.StartTurnAsync("one"); - await arbiter.CurrentTurn; - - var recorded = arbiter.Interrupt("half a reply", TimeSpan.FromMilliseconds(600)); - - Assert.True(recorded); - Assert.Equal("half a reply", session.LastHeardText); - Assert.Equal(1, output.Stops); - - // The turn the caller heard is the turn running now, so the barge-in cuts it. The other - // half of that comparison — the held-prompt window this test's name describes, where the - // two are different turns — is pinned by the test below. - Assert.True(session.LastCutRunningTurn); - } + [Fact(Timeout = 30_000)] + public async Task ABargeInDuringTheHeldPromptWindow_CutsTheTurnTheCallerWasHearing() + { + // Turn one finished streaming and turn two started inside its ending, but the caller is + // still hearing turn one. The record belongs to turn one, and turn two must keep speaking. + ScriptedConversationPort session = new(); + FakeConversationOutput output = new(); + ConversationTurnArbiter arbiter = NewArbiter(session, output); + + // Opened before the first turn, not during it: this test needs turn one to finish streaming + // on its own, and nothing here ever comes back to open a gate the two tests above open while + // a turn is deliberately held in flight. + session.ReleaseTurn(); + + await arbiter.StartTurnAsync("one"); + await arbiter.CurrentTurn; + + bool recorded = arbiter.Interrupt("half a reply", TimeSpan.FromMilliseconds(600)); + + Assert.True(recorded); + Assert.Equal("half a reply", session.LastHeardText); + Assert.Equal(1, output.Stops); + + // The turn the caller heard is the turn running now, so the barge-in cuts it. The other + // half of that comparison — the held-prompt window this test's name describes, where the + // two are different turns — is pinned by the test below. + Assert.True(session.LastCutRunningTurn); + } - [Fact(Timeout = 30_000)] - public async Task ABargeInWhileTheHeldTurnHasSaidNothing_BelongsToTheTurnTheCallerWasHearing() - { - // The rule the arbiter is hardest to get right. Turn one finished streaming and turn two - // started inside its ending, but turn two has not produced one word, so the caller is still - // hearing turn one. cutsRunningTurn must answer false there — turn two is not the turn to - // cut, and it must keep speaking — and true once turn two is itself what the caller heard. - var session = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var arbiter = NewArbiter(session, output); - - var first = arbiter.StartTurnAsync("one"); - await arbiter.StartTurnAsync("two"); - - // Turn one only. Turn two starts inside turn one's own ending and stops at its own gate, - // having said nothing, which is the window this test exists for. - session.ReleaseTurn(1); - await first; - - Assert.True(arbiter.Interrupt("first", TimeSpan.FromMilliseconds(640))); - Assert.False(session.LastCutRunningTurn); - - // Turn two kept speaking, and closed its own reply: the barge-in belonged to turn one, so - // nothing silenced a turn the caller had not heard. - session.ReleaseTurn(2); - await arbiter.CurrentTurn; - - Assert.Contains("two", output.Spoken); - Assert.Equal(2, output.Completions); - - // And now the turn the caller has heard is the turn running now, so the same comparison - // answers the other way. - Assert.True(arbiter.Interrupt("second", TimeSpan.FromMilliseconds(120))); - Assert.True(session.LastCutRunningTurn); - } + [Fact(Timeout = 30_000)] + public async Task ABargeInWhileTheHeldTurnHasSaidNothing_BelongsToTheTurnTheCallerWasHearing() + { + // The rule the arbiter is hardest to get right. Turn one finished streaming and turn two + // started inside its ending, but turn two has not produced one word, so the caller is still + // hearing turn one. cutsRunningTurn must answer false there — turn two is not the turn to + // cut, and it must keep speaking — and true once turn two is itself what the caller heard. + ScriptedConversationPort session = new(); + FakeConversationOutput output = new(); + ConversationTurnArbiter arbiter = NewArbiter(session, output); + + Task first = arbiter.StartTurnAsync("one"); + await arbiter.StartTurnAsync("two"); + + // Turn one only. Turn two starts inside turn one's own ending and stops at its own gate, + // having said nothing, which is the window this test exists for. + session.ReleaseTurn(1); + await first; + + Assert.True(arbiter.Interrupt("first", TimeSpan.FromMilliseconds(640))); + Assert.False(session.LastCutRunningTurn); + + // Turn two kept speaking, and closed its own reply: the barge-in belonged to turn one, so + // nothing silenced a turn the caller had not heard. + session.ReleaseTurn(2); + await arbiter.CurrentTurn; + + Assert.Contains("two", output.Spoken); + Assert.Equal(2, output.Completions); + + // And now the turn the caller has heard is the turn running now, so the same comparison + // answers the other way. + Assert.True(arbiter.Interrupt("second", TimeSpan.FromMilliseconds(120))); + Assert.True(session.LastCutRunningTurn); + } - [Fact(Timeout = 30_000)] - public async Task ASecondConversationNamedMidTurn_StillHoldsTheNextUtteranceBehindTheTurnInFlight() - { - // One transport runs one turn at a time, and a vendor that names the conversation a second time - // does not get to start a second reply alongside the first. The prompt that arrives after - // the rename is held, and it runs against the conversation named last. - var replaced = new ScriptedConversationPort(); - var named = new ScriptedConversationPort(); - var output = new FakeConversationOutput(); - var arbiter = NewArbiter(replaced, output); + [Fact(Timeout = 30_000)] + public async Task ASecondConversationNamedMidTurn_StillHoldsTheNextUtteranceBehindTheTurnInFlight() + { + // One transport runs one turn at a time, and a vendor that names the conversation a second time + // does not get to start a second reply alongside the first. The prompt that arrives after + // the rename is held, and it runs against the conversation named last. + ScriptedConversationPort replaced = new(); + ScriptedConversationPort named = new(); + FakeConversationOutput output = new(); + ConversationTurnArbiter arbiter = NewArbiter(replaced, output); - var running = arbiter.StartTurnAsync("one"); + Task running = arbiter.StartTurnAsync("one"); - arbiter.Rebind(named); - await arbiter.StartTurnAsync("two"); + arbiter.Rebind(named); + await arbiter.StartTurnAsync("two"); - Assert.Empty(named.TurnsRun); + Assert.Empty(named.TurnsRun); - replaced.ReleaseTurn(); - named.ReleaseTurn(); - await running; - await arbiter.CurrentTurn; + replaced.ReleaseTurn(); + named.ReleaseTurn(); + await running; + await arbiter.CurrentTurn; + + Assert.Equal(["one"], replaced.TurnsRun); + Assert.Equal(["two"], named.TurnsRun); + } - Assert.Equal(["one"], replaced.TurnsRun); - Assert.Equal(["two"], named.TurnsRun); + private static ConversationTurnArbiter NewArbiter(ScriptedConversationPort session, FakeConversationOutput output) + { + return new( + session, + output, + new ConnectionTaskObserver(() => session.ConversationId, (_, _) => { }, (_, _, _) => { }, (_, _, _) => false), + _ => { }, + _ => { }, + CancellationToken.None); + } } - private static ConversationTurnArbiter NewArbiter(ScriptedConversationPort session, FakeConversationOutput output) - => new( - session, - output, - new ConnectionTaskObserver(() => session.ConversationId, (_, _) => { }, (_, _, _) => { }, (_, _, _) => false), - _ => { }, - _ => { }, - CancellationToken.None); -} + /// + /// One call the test drives by hand: it records the turns it was asked to run, holds each of them + /// on one gate the test opens, and remembers what a barge-in told it. + /// + /// + /// The gate is what makes the two holding tests deterministic. Without it a turn would run to its + /// end inside StartTurnAsync itself, and a second utterance would find no turn in flight to + /// be held behind — which is the one condition those tests exist to create. + /// + internal sealed class ScriptedConversationPort : IConversationPort + { + private readonly Dictionary _gates = []; + private readonly List _turnsRun = []; + private readonly Lock _lock = new(); + private bool _allReleased; + private int _turnsStarted; -/// -/// One call the test drives by hand: it records the turns it was asked to run, holds each of them -/// on one gate the test opens, and remembers what a barge-in told it. -/// -/// -/// The gate is what makes the two holding tests deterministic. Without it a turn would run to its -/// end inside StartTurnAsync itself, and a second utterance would find no turn in flight to -/// be held behind — which is the one condition those tests exist to create. -/// -internal sealed class ScriptedConversationPort : IConversationPort -{ - private readonly Dictionary _gates = []; - private readonly List _turnsRun = []; - private readonly Lock _lock = new(); - private bool _allReleased; - private int _turnsStarted; + /// + public string ConversationId => "conversation-scripted"; - /// - public string ConversationId => "conversation-scripted"; + /// + public string Stage => string.Empty; - /// - public string Stage => string.Empty; + /// + public bool IsComplete => false; - /// - public bool IsComplete => false; + /// + public TurnResult? LastTurn { get; set; } - /// - public TurnResult? LastTurn { get; set; } + /// + public KnowledgeScope? Scope { get; set; } - /// - public KnowledgeScope? Scope { get; set; } + /// Gets what the caller was told it heard, or null before a barge-in. + public string? LastHeardText { get; private set; } - /// Gets what the caller was told it heard, or null before a barge-in. - public string? LastHeardText { get; private set; } + /// Gets how much of the reply the caller was told had played, or null before a barge-in. + public TimeSpan? LastPlayedDuration { get; private set; } - /// Gets how much of the reply the caller was told had played, or null before a barge-in. - public TimeSpan? LastPlayedDuration { get; private set; } + /// Gets whether the last barge-in said it cut the turn running now. + public bool? LastCutRunningTurn { get; private set; } - /// Gets whether the last barge-in said it cut the turn running now. - public bool? LastCutRunningTurn { get; private set; } + /// Gets the text of every turn this port was asked to run, in order. + public IReadOnlyList TurnsRun + { + get { lock (_lock) { return [.. _turnsRun]; } } + } - /// Gets the text of every turn this port was asked to run, in order. - public IReadOnlyList TurnsRun - { - get { lock (_lock) { return [.. _turnsRun]; } } - } + /// Opens the gate of every turn, the ones already waiting and every later one. + public void ReleaseTurn() + { + lock (_lock) + { + _allReleased = true; + foreach (TaskCompletionSource gate in _gates.Values) + { + _ = gate.TrySetResult(); + } + } + } - /// Opens the gate of every turn, the ones already waiting and every later one. - public void ReleaseTurn() - { - lock (_lock) + /// Opens the gate of one turn only, named by the order it started in, from one. + /// The turn to release: 1 is the first turn this port was asked to run. + /// + /// One turn at a time is what the arbiter promises, so releasing turn one alone is how a test + /// reaches the window the arbiter's hardest rule lives in: turn one finished and turn two + /// started inside its ending, still holding its own gate and still having said nothing. + /// + public void ReleaseTurn(int ordinal) { - _allReleased = true; - foreach (var gate in _gates.Values) + lock (_lock) { - gate.TrySetResult(); + _ = GateFor(ordinal).TrySetResult(); } } - } - /// Opens the gate of one turn only, named by the order it started in, from one. - /// The turn to release: 1 is the first turn this port was asked to run. - /// - /// One turn at a time is what the arbiter promises, so releasing turn one alone is how a test - /// reaches the window the arbiter's hardest rule lives in: turn one finished and turn two - /// started inside its ending, still holding its own gate and still having said nothing. - /// - public void ReleaseTurn(int ordinal) - { - lock (_lock) + /// + public Task RunTurnAsync(string userInput, CancellationToken cancellationToken = default) { - GateFor(ordinal).TrySetResult(); + throw new NotSupportedException("the arbiter only ever streams a turn."); } - } - /// - public Task RunTurnAsync(string userInput, CancellationToken cancellationToken = default) - => throw new NotSupportedException("the arbiter only ever streams a turn."); - /// - public Task RunTurnMessageAsync(ChatMessage userInput, CancellationToken cancellationToken) - => throw new NotSupportedException("the arbiter only ever streams a turn."); - - /// - public async IAsyncEnumerable RunTurnStreamingAsync( - string userInput, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - Task gate; - lock (_lock) + /// + public Task RunTurnMessageAsync(ChatMessage userInput, CancellationToken cancellationToken) { - _turnsRun.Add(userInput); - gate = _allReleased ? Task.CompletedTask : GateFor(++_turnsStarted).Task; + throw new NotSupportedException("the arbiter only ever streams a turn."); } - await gate.WaitAsync(cancellationToken).ConfigureAwait(false); + /// + public async IAsyncEnumerable RunTurnStreamingAsync( + string userInput, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + Task gate; + lock (_lock) + { + _turnsRun.Add(userInput); + gate = _allReleased ? Task.CompletedTask : GateFor(++_turnsStarted).Task; + } - yield return new ChatResponseUpdate(ChatRole.Assistant, userInput); - yield return new ChatResponseUpdate(ChatRole.Assistant, " done"); - } + await gate.WaitAsync(cancellationToken).ConfigureAwait(false); - /// - public IAsyncEnumerable RunTurnMessageStreamingAsync( - ChatMessage userInput, - CancellationToken cancellationToken) - => RunTurnStreamingAsync(userInput.Text ?? string.Empty, cancellationToken); - - /// - public bool Interrupt( - string utteranceUntilInterrupt, - TimeSpan durationUntilInterrupt, - bool cutsRunningTurn = true) - { - LastHeardText = utteranceUntilInterrupt; - LastPlayedDuration = durationUntilInterrupt; - LastCutRunningTurn = cutsRunningTurn; - return true; - } + yield return new ChatResponseUpdate(ChatRole.Assistant, userInput); + yield return new ChatResponseUpdate(ChatRole.Assistant, " done"); + } - /// Finds one turn's gate, creating it if the turn has not reached it yet. - /// The turn, in the order this port was asked to run them, from one. - /// The gate that turn waits on. - /// Callers hold _lock. - private TaskCompletionSource GateFor(int ordinal) - { - if (!_gates.TryGetValue(ordinal, out var gate)) + /// + public IAsyncEnumerable RunTurnMessageStreamingAsync( + ChatMessage userInput, + CancellationToken cancellationToken) { - gate = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); - _gates[ordinal] = gate; + return RunTurnStreamingAsync(userInput.Text ?? string.Empty, cancellationToken); } - return gate; + /// + public bool Interrupt( + string utteranceUntilInterrupt, + TimeSpan durationUntilInterrupt, + bool cutsRunningTurn = true) + { + LastHeardText = utteranceUntilInterrupt; + LastPlayedDuration = durationUntilInterrupt; + LastCutRunningTurn = cutsRunningTurn; + return true; + } + + /// Finds one turn's gate, creating it if the turn has not reached it yet. + /// The turn, in the order this port was asked to run them, from one. + /// The gate that turn waits on. + /// Callers hold _lock. + private TaskCompletionSource GateFor(int ordinal) + { + if (!_gates.TryGetValue(ordinal, out TaskCompletionSource? gate)) + { + gate = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + _gates[ordinal] = gate; + } + + return gate; + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Conversation/TelnyxRelayThroughTheConversationSeamTests.cs b/tests/AgentCore.AspNetCore.Tests/Conversation/TelnyxRelayThroughTheConversationSeamTests.cs index 08438310..a1d0b50b 100644 --- a/tests/AgentCore.AspNetCore.Tests/Conversation/TelnyxRelayThroughTheConversationSeamTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Conversation/TelnyxRelayThroughTheConversationSeamTests.cs @@ -1,54 +1,53 @@ -using AgentCore.TestSupport; using System.Net; -using AgentCore.AspNetCore.Conversation; using AgentCore.AspNetCore.Tests.Fakes; using AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; using AgentCore.AspNetCore.Vendors.TelnyxRelay; using Xunit; -namespace AgentCore.AspNetCore.Tests.Conversation; - -/// -/// The one place the shipped vendor and the vendor-neutral route meet in a running host. -/// -/// -/// -/// ConversationRouteSelectionTests proves the selection over fakes and names no vendor, which is -/// spec §12. ConversationOptionsFromDocumentTests proves -/// TelnyxRelayConversationAdapter.BuildOptions over a document. Neither of them runs -/// TelnyxRelayConversationAdapter.Map, and that method is the single executable line joining the -/// shipped vendor to the seam. This file is where it runs. -/// -/// -/// This file may name Telnyx freely: joining the real vendor to the real route is precisely what it -/// exists to prove, and a version of it written over a fake would prove nothing new. -/// -/// -/// It runs offline against a fake model. There is no Telnyx account, no network conversation, and no API -/// key here. -/// -/// -public sealed class TelnyxRelayThroughTheConversationSeamTests +namespace AgentCore.AspNetCore.Tests.Conversation { - [Fact(Timeout = 30_000)] - public async Task APlainGetToTheVendorNeutralRoute_ReachesTheRelayHandler() + /// + /// The one place the shipped vendor and the vendor-neutral route meet in a running host. + /// + /// + /// + /// ConversationRouteSelectionTests proves the selection over fakes and names no vendor, which is + /// spec §12. ConversationOptionsFromDocumentTests proves + /// TelnyxRelayConversationAdapter.BuildOptions over a document. Neither of them runs + /// TelnyxRelayConversationAdapter.Map, and that method is the single executable line joining the + /// shipped vendor to the seam. This file is where it runs. + /// + /// + /// This file may name Telnyx freely: joining the real vendor to the real route is precisely what it + /// exists to prove, and a version of it written over a fake would prove nothing new. + /// + /// + /// It runs offline against a fake model. There is no Telnyx account, no network conversation, and no API + /// key here. + /// + /// + public sealed class TelnyxRelayThroughTheConversationSeamTests { - using FragmentingChatClient reply = new("hello"); + [Fact(Timeout = 30_000)] + public async Task APlainGetToTheVendorNeutralRoute_ReachesTheRelayHandler() + { + using FragmentingChatClient reply = new("hello"); - // The host names no vendor at the route. providers.conversation: { kind: telnyx-relay } is what - // picks this adapter, and app.MapCall() is what asks. - await using var host = await TelnyxRelayHost.StartThroughConversationSeamAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - options => options.UseConversation(new TelnyxRelayConversationAdapter())); + // The host names no vendor at the route. providers.conversation: { kind: telnyx-relay } is what + // picks this adapter, and app.MapCall() is what asks. + await using TelnyxRelayHost host = await TelnyxRelayHost.StartThroughConversationSeamAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + options => options.UseConversation(new TelnyxRelayConversationAdapter())); - var answer = await host.GetAsync(TelnyxRelayHost.MainConversation); + HttpResponseMessage answer = await host.GetAsync(TelnyxRelayHost.MainConversation); - // 404 would mean MapCall mapped nothing, and every call to this deployment would be lost - // with nothing to read. 400 is the relay's own HandleAsync refusing a request that is not a - // WebSocket upgrade, so it proves both halves at once: the route exists, and the handler - // behind it is the Telnyx one. - Assert.NotEqual(HttpStatusCode.NotFound, answer.StatusCode); - Assert.Equal(HttpStatusCode.BadRequest, answer.StatusCode); + // 404 would mean MapCall mapped nothing, and every call to this deployment would be lost + // with nothing to read. 400 is the relay's own HandleAsync refusing a request that is not a + // WebSocket upgrade, so it proves both halves at once: the route exists, and the handler + // behind it is the Telnyx one. + Assert.NotEqual(HttpStatusCode.NotFound, answer.StatusCode); + Assert.Equal(HttpStatusCode.BadRequest, answer.StatusCode); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs index c952c0ed..1a28e8cb 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs @@ -13,7 +13,6 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Secrets; -using AgentCore.Application.Tools; using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Transcript; @@ -33,21 +32,22 @@ using AgentCore.AspNetCore.DependencyInjection.Startup; using Microsoft.Agents.AI; using static AgentCore.AspNetCore.Tests.DependencyInjection.StartedHostFixture; +using AgentCore.Domain; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// The composition root. It loads, validates, resolves, compiles, and registers, in that order. -/// -/// -/// A configuration defect stops the host at start and never on the first conversation. Every test proves -/// that by starting a host and nothing else, with no request anywhere. -/// -public sealed class AddAgentCoreTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - /// The conversation and speech providers every document below shares. - private const string SpeechAndConversation = - """ + /// + /// The composition root. It loads, validates, resolves, compiles, and registers, in that order. + /// + /// + /// A configuration defect stops the host at start and never on the first conversation. Every test proves + /// that by starting a host and nothing else, with no request anywhere. + /// + public sealed class AddAgentCoreTests + { + /// The conversation and speech providers every document below shares. + private const string SpeechAndConversation = + """ providers: conversation: { kind: telnyx-relay } speech: @@ -55,17 +55,17 @@ public sealed class AddAgentCoreTests tts: { kind: telnyx-relay } """; - /// plus the single reply model most documents declare. - private const string MinimalProviders = - $$""" + /// plus the single reply model most documents declare. + private const string MinimalProviders = + $$""" {{SpeechAndConversation}} llm: - { kind: openai, model: gpt-4.1-mini, as: reply } """; - // The same agent, reachable on two entries. - private const string TwoEntryYaml = - $$""" + // The same agent, reachable on two entries. + private const string TwoEntryYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -78,9 +78,9 @@ public sealed class AddAgentCoreTests agent: only """; - // The same agent, and a document that names a telemetry vendor. - private const string TelemetryYaml = - $$""" + // The same agent, and a document that names a telemetry vendor. + private const string TelemetryYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -92,9 +92,9 @@ public sealed class AddAgentCoreTests agent: only """; - // The same agent, and a document that names a moderation vendor. - private const string ModeratedYaml = - $$""" + // The same agent, and a document that names a moderation vendor. + private const string ModeratedYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -106,9 +106,9 @@ public sealed class AddAgentCoreTests agent: only """; - // The same agent, served by a vendor this host's fake adapter does not answer to. - private const string OtherVendorYaml = - $$""" + // The same agent, served by a vendor this host's fake adapter does not answer to. + private const string OtherVendorYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -121,9 +121,9 @@ public sealed class AddAgentCoreTests agent: only """; - // The same agent, with both tunable keys of the document set away from their default. - private const string TunedYaml = - $$""" + // The same agent, with both tunable keys of the document set away from their default. + private const string TunedYaml = + $$""" apiVersion: agentcore/v1 fallbackReply: "One moment please. I will try that again." evaluation: @@ -137,8 +137,8 @@ public sealed class AddAgentCoreTests agent: only """; - private const string BindingYaml = - $$""" + private const string BindingYaml = + $$""" apiVersion: agentcore/v1 tools: - id: create_case @@ -158,8 +158,8 @@ public sealed class AddAgentCoreTests agent: only """; - private const string SecretYaml = - $$""" + private const string SecretYaml = + $$""" apiVersion: agentcore/v1 tools: - id: lookup_order @@ -182,10 +182,10 @@ public sealed class AddAgentCoreTests agent: only """; - // Row 4 of the section 8.2 compile table, with a guarded edge on each exit of the start node. - // Check 5 proves the two guards exclusive, so exactly one edge fires for each conversation. - private const string GuardedGraphYaml = - $$""" + // Row 4 of the section 8.2 compile table, with a guarded edge on each exit of the start node. + // Check 5 proves the two guards exclusive, so exactly one edge fires for each conversation. + private const string GuardedGraphYaml = + $$""" apiVersion: agentcore/v1 state: escalate: { type: boolean, writer: extractor, default: false } @@ -218,9 +218,9 @@ public sealed class AddAgentCoreTests - { kind: openai, model: gpt-4.1-mini, as: bot } """; - // A stage names a target that policy.stages does not declare, so check 2 fails the load. - private const string BrokenYaml = - $$""" + // A stage names a target that policy.stages does not declare, so check 2 fails the load. + private const string BrokenYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -234,10 +234,10 @@ public sealed class AddAgentCoreTests - { id: start, agent: only, to: [ { stage: nowhere } ] } """; - // A state slot's from: names a tool no tools: entry declares, and no mcp: server offers it - // either, so nothing in the served set ever resolves it. - private const string UndeclaredToolYaml = - $$""" + // A state slot's from: names a tool no tools: entry declares, and no mcp: server offers it + // either, so nothing in the served set ever resolves it. + private const string UndeclaredToolYaml = + $$""" apiVersion: agentcore/v1 state: orderStatus: { type: string, writer: tool, from: lookup_order.status } @@ -250,11 +250,11 @@ public sealed class AddAgentCoreTests agent: only """; - // An agent's tools: names an id nothing serves. Unlike UndeclaredToolYaml, the fault sits in - // agents.items[].tools rather than state:, so the pointer must name the agent and not a bare - // /tools. - private const string UndeclaredAgentToolYaml = - $$""" + // An agent's tools: names an id nothing serves. Unlike UndeclaredToolYaml, the fault sits in + // agents.items[].tools rather than state:, so the pointer must name the agent and not a bare + // /tools. + private const string UndeclaredAgentToolYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -265,11 +265,11 @@ public sealed class AddAgentCoreTests agent: only """; - // Declares no tools: at all. 'discovered_only' is served only by a fake IToolSource the test - // registers, never named anywhere in the document itself, so the only way this boots is if the - // reference pass resolves against what got discovered rather than what got declared. - private const string DiscoveredOnlyToolYaml = - $$""" + // Declares no tools: at all. 'discovered_only' is served only by a fake IToolSource the test + // registers, never named anywhere in the document itself, so the only way this boots is if the + // reference pass resolves against what got discovered rather than what got declared. + private const string DiscoveredOnlyToolYaml = + $$""" apiVersion: agentcore/v1 agents: items: @@ -280,13 +280,13 @@ public sealed class AddAgentCoreTests agent: only """; - // A kind: agent tool reaches no source at all: the compiler builds it once the agent it names - // has compiled, so the registry never holds it. The reference pass must still let front's - // tools: [ ask_specialist ] through, or every delegating document fails to boot. - // A declared kind: agent tool whose id a registered source also discovers. The collision is only - // found after every source has answered, so by then the source is open. - private const string CollidingAgentToolYaml = - $$""" + // A kind: agent tool reaches no source at all: the compiler builds it once the agent it names + // has compiled, so the registry never holds it. The reference pass must still let front's + // tools: [ ask_specialist ] through, or every delegating document fails to boot. + // A declared kind: agent tool whose id a registered source also discovers. The collision is only + // found after every source has answered, so by then the source is open. + private const string CollidingAgentToolYaml = + $$""" apiVersion: agentcore/v1 tools: - id: shared_id @@ -310,8 +310,8 @@ public sealed class AddAgentCoreTests - { id: talk, agent: front, terminal: true } """; - private const string DelegatingAgentToolYaml = - $$""" + private const string DelegatingAgentToolYaml = + $$""" apiVersion: agentcore/v1 tools: - id: ask_specialist @@ -335,13 +335,13 @@ public sealed class AddAgentCoreTests - { id: talk, agent: front, terminal: true } """; - // BrokenYaml's structural defect (an unreachable policy transition), plus an mcp: server whose - // command names a binary that does not exist. Decision 15's whole point is that the structural - // error below must surface without AgentCore ever trying to reach that server: a missing - // executable fails Process.Start synchronously, so if discovery ran first this would instead - // report the MCP failure. See AddAgentCore_TheStructuralFaultSurfaces_BeforeMcpIsEverAsked. - private const string StructuralFaultPlusUnreachableMcpYaml = - $$""" + // BrokenYaml's structural defect (an unreachable policy transition), plus an mcp: server whose + // command names a binary that does not exist. Decision 15's whole point is that the structural + // error below must surface without AgentCore ever trying to reach that server: a missing + // executable fails Process.Start synchronously, so if discovery ran first this would instead + // report the MCP failure. See AddAgentCore_TheStructuralFaultSurfaces_BeforeMcpIsEverAsked. + private const string StructuralFaultPlusUnreachableMcpYaml = + $$""" apiVersion: agentcore/v1 mcp: - id: bogus-server @@ -360,1450 +360,1469 @@ public sealed class AddAgentCoreTests - { id: start, agent: only, to: [ { stage: nowhere } ] } """; - // ------------------------------------------------------------------------------------------- - // What it registers. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AddAgentCore_RegistersTheCompiledAgentAsAProcessSingleton() - { - using var provider = await BuildAsync(OneAgentYaml); - - var first = provider.GetRequiredService>()["main"]; - var second = provider.GetRequiredService>()["main"]; - - Assert.Same(first, second); - Assert.Equal("main", first.Name); - - // The registry compiled once, and every conversation shares that one result. - Assert.Equal(1, provider.GetRequiredService().CompileCount); - } - - [Fact] - public async Task AddAgentCore_RegistersOneSessionFactoryThatBuildsANewSessionForEachConversation() - { - using var provider = await BuildAsync(OneAgentYaml); - var factory = provider.GetRequiredService().ForFactory("main"); - - Assert.Same(factory, provider.GetRequiredService().ForFactory("main")); - - // A ConversationSession belongs to one conversation, so it is not a singleton and the container holds none. - var first = factory.Create(); - var second = factory.Create(); - Assert.NotSame(first, second); - Assert.NotEqual(first.ConversationId, second.ConversationId); - } - - [Fact] - public async Task AddAgentCore_RegistersTheKnowledgePortTheHostBound() - { - FacetCapablePort port = new(); - - using var provider = await BuildAsync( - OneAgentYaml, options => options.UseKnowledgeRetrieval(_ => port)); - - Assert.Same(port, provider.GetRequiredService()); - } - - [Fact] - public async Task AddAgentCore_TheResolvedPortAnswersWhatElseItServes() - { - // What a consumer actually does with it: resolve the one port, then ask that port for the - // capability it needs. Registering each capability separately would hand out a second - // object for the same store, and a store that serves none would have to be registered as - // null anyway. - FacetCapablePort port = new(); - - using var provider = await BuildAsync( - OneAgentYaml, options => options.UseKnowledgeRetrieval(_ => port)); - - var knowledge = provider.GetRequiredService(); - - Assert.Same(port, knowledge.GetService()); - } - - [Fact] - public async Task AddAgentCore_ADocumentThatReadsNoKnowledge_ResolvesNoPort() - { - using var provider = await BuildAsync(OneAgentYaml); - - Assert.Null(provider.GetService()); - } - - [Fact] - public async Task AddAgentCore_RegistersTheAgentShimAsAProcessSingleton() - { - using var provider = await BuildAsync(OneAgentYaml); - - var agent = provider.GetRequiredService().ForAgent("main"); - - Assert.Same(agent, provider.GetRequiredService().ForAgent("main")); - Assert.Equal("main", agent.Name); - - // One session of the shim is one conversation, drawn from the same factory the rest of the host - // uses, so the two seams describe the same conversations. - var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); - Assert.NotNull(session.GetService()); - } - - [Fact] - public async Task AddAgentCore_RegistersTheInMemorySessionsByDefault() - { - using var provider = await BuildAsync(OneAgentYaml); - - var sessions = provider.GetRequiredService().ForSessions("main"); - - Assert.IsType(sessions); - Assert.Same(sessions, provider.GetRequiredService().ForSessions("main")); - } - - [Fact] - public async Task AddAgentCore_RunsTheIdleSweepForTheDefaultSessions() - { - // Expiry needs something to drive it. Without this the idle timeout never fires and the - // text path holds every conversation a caller walked away from for the life of the process. - using var provider = await BuildAsync(OneAgentYaml); - - Assert.Contains( - provider.GetServices(), - service => service is ConversationSessionSweeper); - } - - /// - /// The one thing deferring the boot to host start has to guarantee: a service the document - /// produced cannot be read before the document has been read. A provider nobody started answers - /// with a refusal that names the fix, and never with a half-built graph or a null. - /// - [Fact] - public void AServiceReadFromAProviderNobodyStarted_RefusesAndSaysWhatToDo() - { - ServiceCollection services = new(); - ConfigureServices(services, OneAgentYaml, null); - - using var provider = services.BuildServiceProvider(); - - var failure = Assert.Throws( - provider.GetRequiredService>); - - Assert.Contains("has not booted", failure.Message, StringComparison.Ordinal); - Assert.Contains("StartAsync", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task AddAgentCore_UsesTheSessionsTheHostBound() - { - CountingConversationSessions mine = new(); - - using var provider = await BuildAsync( - OneAgentYaml, options => options.UseConversationSessions((_, _) => mine)); - - // A distributed store replaces the default one, and the default steps aside. - Assert.Same(mine, provider.GetRequiredService().ForSessions("main")); - } - - [Fact] - public async Task AddAgentCore_OpensOneStorePerEntry() - { - // A vendor call id arriving on two entries opens two isolated conversations. That holds only when - // each entry has its own store, so the host's opener runs once per entry and is told which. - List opened = []; - - using var provider = await BuildAsync(TwoEntryYaml, options => options.UseConversationSessions( - (entry, factory) => - { - opened.Add(entry); - return new InMemoryConversationSessions( - factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); - })); - - var registry = provider.GetRequiredService(); - - Assert.Equal(["main", "other"], opened.Order(StringComparer.Ordinal)); - Assert.NotSame(registry.ForSessions("main"), registry.ForSessions("other")); - } - - [Fact] - public async Task AddAgentCore_RegistersTheSessionRegistryAsAPublicPort() - { - // A consumer reaches an entry's store through the port, never through the internal - // registry, and never through a bare IConversationSessions: no store spans the whole host. - using var provider = await BuildAsync(OneAgentYaml); - - var registry = provider.GetRequiredService(); - - Assert.Equal(["main"], registry.Entries); - Assert.Same( - provider.GetRequiredService().ForSessions("main"), - registry.ForSessions("main")); - Assert.Null(provider.GetService()); - - var failure = Assert.Throws(() => registry.ForSessions("missing")); - Assert.Contains("main", failure.Message, StringComparison.Ordinal); - } - - // ------------------------------------------------------------------------------------------- - // Telemetry shuts down with the host. The container owns the session, so its disposal is the - // flush — which is the one path a start that failed also reaches. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AddAgentCore_RegistersTheTelemetrySessionTheDocumentNames() - { - var (host, adapter) = await BuildTelemetryHostAsync(); - - using (host) - { - await host.StartAsync(TestContext.Current.CancellationToken); - - // A host that reads its own spans and metrics resolves this. Nothing in this library - // does, so only a test holds it to being there at all. - Assert.Same(adapter.Session, host.Services.GetRequiredService()); - } - } - - [Fact] - public async Task AddAgentCore_RegistersNoTelemetrySessionWhenTheHostBindsNoVendor() - { - using var provider = await BuildAsync(OneAgentYaml); - - Assert.Null(provider.GetService()); - } - - [Fact] - public async Task AddAgentCore_FlushesTheTelemetrySessionWhenTheHostShutsDown() - { - var (host, adapter) = await BuildTelemetryHostAsync(); - - await host.StartAsync(TestContext.Current.CancellationToken); - - Assert.Equal(0, adapter.Session.Flushes); - - await host.StopAsync(TestContext.Current.CancellationToken); - host.Dispose(); - - Assert.Equal(1, adapter.Session.Flushes); - } - - [Fact] - public async Task AddAgentCore_FlushesTheTelemetrySessionOnceWhenTheHostIsDisposedTwice() - { - var (host, adapter) = await BuildTelemetryHostAsync(); - - await host.StartAsync(TestContext.Current.CancellationToken); - await host.StopAsync(TestContext.Current.CancellationToken); - - // An adapter's session is not required to survive being drained twice, so the second call - // has to be a no-op. - host.Dispose(); - host.Dispose(); - - Assert.Equal(1, adapter.Session.Flushes); - } - - // ------------------------------------------------------------------------------------------- - // The audit chain shuts down with the host. An event is ACCEPTED when AppendAsync returns, so a - // stop that does not drain the queue loses every row still in it. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AddAgentCore_DrainsTheAuditQueueWhenTheHostShutsDown() - { - var (host, store) = await BuildAuditHostAsync(); - - await host.StartAsync(TestContext.Current.CancellationToken); - - await host.Services - .GetRequiredService() - .AppendAsync(AuditRow(1), TestContext.Current.CancellationToken); - - await host.StopAsync(TestContext.Current.CancellationToken); - host.Dispose(); - - Assert.Equal(1, store.Written); - } - - [Fact] - public async Task AddAgentCore_ClosesTheAuditStoreOnlyAfterTheQueueHasDrained() - { - var (host, store) = await BuildAuditHostAsync(); - - await host.StartAsync(TestContext.Current.CancellationToken); - - await host.Services - .GetRequiredService() - .AppendAsync(AuditRow(1), TestContext.Current.CancellationToken); - - await host.StopAsync(TestContext.Current.CancellationToken); - - // The container closes what it resolved before it closes the boot that still owns the store - // behind the queue. Closing that store first would hand the drain a store which can no - // longer accept the rows it already promised to keep. - host.Dispose(); - - Assert.True(store.Closed); - Assert.Equal(1, store.WrittenWhenClosed); - } - - [Fact] - public async Task AddAgentCore_ClosesTheConversationStoreWhenTheHostShutsDown() - { - RecordingConversationStore store = new(); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - ConfigureServices( - builder.Services, - VendorTranscriptYaml, - options => options.UseConversationStores(new TestConversationStoreAdapter(store))); - - IHost host = builder.Build(); - await host.StartAsync(TestContext.Current.CancellationToken); - await host.StopAsync(TestContext.Current.CancellationToken); - host.Dispose(); - - Assert.True(store.Closed); - } - - [Fact] - public async Task AddAgentCore_ClosesTheKnowledgePortWhenTheHostShutsDown() - { - // KnowledgeStartup.OpenAsync's result used to be discarded with `_ = await ...`, so a - // successful open -- a QdrantClient in production -- was never tracked against the boot and - // outlived host shutdown. This proves the port the adapter built is closed the same way the - // conversation store above is. - DisposeTrackingKnowledgeAdapter adapter = new(); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - ConfigureServices( - builder.Services, - VendorKnowledgeYaml, - options => options.UseKnowledgeStores(adapter)); - - IHost host = builder.Build(); - await host.StartAsync(TestContext.Current.CancellationToken); - - Assert.NotNull(adapter.Built); - Assert.False(adapter.Built.Closed); - - await host.StopAsync(TestContext.Current.CancellationToken); - host.Dispose(); - - Assert.True(adapter.Built.Closed); - } - - [Fact] - public async Task AHostRegisteredDisposableToolSource_IsClosedWhenTheHostShutsDown() - { - // Disposal happens once, when the container closes the boot that owns the source — the same - // route McpToolSource is closed through, proved here with no MCP server involved. The - // reference kept below is exactly the case that makes the risk small rather than zero: - // AddToolSource's factory could be called more than once by a host that keeps its own - // reference to what it returns, and closing it anyway costs little because the host was - // about to lose it either way. - DisposeTrackingToolSource source = new(); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - ConfigureServices( - builder.Services, - OneAgentYaml, - options => options.AddToolSource(_ => source)); - - IHost host = builder.Build(); - await host.StartAsync(TestContext.Current.CancellationToken); - - Assert.False(source.Disposed); - - await host.StopAsync(TestContext.Current.CancellationToken); - host.Dispose(); - - Assert.True(source.Disposed); - } - - // ------------------------------------------------------------------------------------------- - // The document picks the vendor, and no code names one: the point of the adapter seam. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task TheAdapterOverload_LetsTheDocumentPickTheVendorByItsKind() - { - // 'kind: openai' selects the adapter registered under that kind. The host lists what it - // supports, once, and the document decides which entry runs. - using var provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients( - new FakeChatClientAdapter("openai", () => new FragmentingChatClient("routed")), - new FakeChatClientAdapter("anthropic", () => new FragmentingChatClient("wrong vendor")))); - - var session = provider.GetRequiredService().ForFactory("main").Create(); - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Equal("routed", turn.ReplyText); - } - - [Fact] - public async Task AKindNoRegisteredAdapterServes_FailsTheStartAndNamesBothSides() - { - var failure = await Assert.ThrowsAsync(() => BuildAsync( - OtherVendorYaml, - options => options.UseChatClients( - new FakeChatClientAdapter("openai", () => new FragmentingChatClient("hello"))))); - - // The message names the kind the document wrote and the kinds the host registers, so the - // reader knows which side to change. - Assert.Contains("anthropic", failure.Message, StringComparison.Ordinal); - Assert.Contains("'openai'", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task AnAsyncSeam_BuildsItsFactoryWithNoBlockedThread() - { - using var provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients( - async (startup, cancellationToken) => - { - await Task.Yield(); - return new RoutingChatClientFactory(new FragmentingChatClient("awaited")); - })); - - var session = provider.GetRequiredService().ForFactory("main").Create(); - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Equal("awaited", turn.ReplyText); - } - - [Fact] - public async Task AToolSource_SeesTheChatClientFactoryAlreadyBuilt() - { - // The seam that builds the factory only runs once, so a null capture here means the tools - // were built before it ran — exactly the ordering builtin tools depend on. - IChatClientFactory? builtFactory = null; - IChatClientFactory? seenWhenToolsWereBuilt = null; - - using var provider = await BuildAsync(OneAgentYaml, options => - { - options.UseChatClients((_, _) => - { - builtFactory = new RoutingChatClientFactory(new FragmentingChatClient("hello")); - return ValueTask.FromResult(builtFactory); - }); - - options.AddToolSource(_ => new SpyToolSource(() => seenWhenToolsWereBuilt = builtFactory)); - }); - - Assert.NotNull(provider.GetRequiredService>()["main"]); - Assert.NotNull(seenWhenToolsWereBuilt); - Assert.Same(builtFactory, seenWhenToolsWereBuilt); - } - - // ------------------------------------------------------------------------------------------- - // The seams the host binds. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ABindingTool_ReachesTheDelegateTheHostRegistered() - { - using var provider = await BuildAsync( - BindingYaml, - options => options.Bind("CreateCase", (_, _) => ValueTask.FromResult(new JsonObject()))); - - var bindings = provider.GetRequiredService(); - - Assert.True(bindings.Contains("CreateCase")); - Assert.Equal(1, bindings.Count); - } - - [Fact] - public async Task ABindingToolWithNoDelegate_FailsTheStartAndNamesTheBinding() - { - var failure = await Assert.ThrowsAsync(() => BuildAsync(BindingYaml)); - - Assert.Contains("CreateCase", failure.Message, StringComparison.Ordinal); - Assert.Contains("did not register", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task ASecretReference_ResolvesOnceAtStartup() - { - using HttpClient client = new(); - MapSecretResolver resolver = new(); - resolver.With("orders-api-key", "a-value-no-message-repeats"); - - using var provider = await BuildAsync( - SecretYaml, - options => - { - options.SecretResolver = resolver; - options.AddToolSource(startup => new HttpToolSource(client, startup.Secrets)); - }); - - var secrets = provider.GetRequiredService(); - - Assert.True(secrets.Contains("orders-api-key")); - - // A resolved set lands in a log line sooner or later, so it reports the count and never a value. - Assert.DoesNotContain("a-value-no-message-repeats", secrets.ToString(), StringComparison.Ordinal); - } - - [Fact] - public async Task ASecretReferenceWithNoResolver_FailsTheStartAndNamesTheSecret() - { - using HttpClient client = new(); - - var failure = await Assert.ThrowsAsync(() => BuildAsync( - SecretYaml, - options => options.AddToolSource(startup => new HttpToolSource(client, startup.Secrets)))); - - Assert.Equal("orders-api-key", failure.SecretName); - } - - // ------------------------------------------------------------------------------------------- - // Row 4 of the compile table, through the only supported composition root. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AGuardedGraph_Starts() - { - using var provider = await BuildGuardedGraphAsync(); - - var compiled = provider.GetRequiredService>()["main"]; - - // The document passes all eight checks and now compiles too. AddAgentCore binds the guard - // evaluator, so a guarded edge is reachable from here. - Assert.Equal(CompiledAgentShape.ExplicitGraph, compiled.Shape); - Assert.Equal("main", compiled.Name); - } - - [Theory] - [InlineData(true, "ESCALATED", "HANDLED")] - [InlineData(false, "HANDLED", "ESCALATED")] - public async Task AGuardedGraph_TakesTheEdgeTheStateOfTheConversationNames(bool escalate, string taken, string refused) - { - using var provider = await BuildGuardedGraphAsync(); - var session = provider.GetRequiredService().ForFactory("main").Create(); - session.State.TryWrite("escalate", escalate); - - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Contains(taken, turn.ReplyText, StringComparison.Ordinal); - Assert.DoesNotContain(refused, turn.ReplyText, StringComparison.Ordinal); - } - - [Fact] - public async Task AGuardedGraph_KeepsTwoConversationsApartWhenTheyRunAtTheSameTime() - { - using var provider = await BuildGuardedGraphAsync(); - var sessions = provider.GetRequiredService().ForFactory("main"); - var token = TestContext.Current.CancellationToken; - - var escalated = sessions.Create(); - escalated.State.TryWrite("escalate", true); - var handled = sessions.Create(); - handled.State.TryWrite("escalate", false); - - // One compiled graph, two conversations, two edges. Neither conversation reads the state of the other. - var turns = await Task.WhenAll( - escalated.RunTurnAsync("hello", token), - handled.RunTurnAsync("hello", token)); - - Assert.Contains("ESCALATED", turns[0].ReplyText, StringComparison.Ordinal); - Assert.Contains("HANDLED", turns[1].ReplyText, StringComparison.Ordinal); - Assert.Equal(1, provider.GetRequiredService().CompileCount); - } - - // ------------------------------------------------------------------------------------------- - // The evaluation seam of D13. Triage row T18 defers the online path, so the rate is 0. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AddAgentCore_RegistersTheEvaluationSeamWithTheOnlinePathClosed() - { - using var provider = await BuildAsync(OneAgentYaml); - - var registry = provider.GetRequiredService(); - var sampler = provider.GetRequiredService(); - - // D13 names fault_code, and it calls no model, so it is the one evaluator that is safe by - // default. - Assert.True(registry.Contains("fault_code")); - - // T18: a judge must never block a turn, and the offline gate has not proved the evaluators - // yet. A rate of 0 draws no number and conversations nothing. - Assert.Equal(0, sampler.Rate); - Assert.False(sampler.ShouldSample()); - - Assert.IsType(provider.GetRequiredService()); - } - - [Fact] - public async Task AddAgentCore_RegistersNoModeratorWhenTheHostBindsNoVendor() - { - using var provider = await BuildAsync(OneAgentYaml); - - var registry = provider.GetRequiredService(); - - // A host that registers no moderation vendor moderates nothing, and every turn reaches the - // model. Moderation needs a vendor account, and a library that refused to start without one - // could not be used in a test. - Assert.False(registry.Contains(PromptModerator.ModerationEvaluatorName)); - Assert.Null(PromptModerator.FromRegistry(registry)); - } - - [Fact] - public async Task AddAgentCore_BuildsNoModeratorWhenTheDocumentNamesNoProvider() - { - var adapter = new FakeModerationAdapter("test", new AlwaysFlagsEvaluator()); - - // The vendor is registered and the document names none, so the adapter is never asked to - // build anything. Registering a vendor costs nothing until a document names it. - using var provider = await BuildAsync(OneAgentYaml, options => options.UseModeration(adapter)); - - Assert.False(provider.GetRequiredService() - .Contains(PromptModerator.ModerationEvaluatorName)); - Assert.Equal(0, adapter.Builds); - } - - [Fact] - public async Task AddAgentCore_BuildsTheModerationVendorTheDocumentNames() - { - var adapter = new FakeModerationAdapter("test", new AlwaysFlagsEvaluator()); - - using var provider = await BuildAsync(ModeratedYaml, options => options.UseModeration(adapter)); - - var registry = provider.GetRequiredService(); - - // The same object serves the turn loop and the offline golden set, which is what D13 means - // by an evaluator written once and used twice. - Assert.Equal(1, adapter.Builds); - Assert.True(registry.Contains(PromptModerator.ModerationEvaluatorName)); - Assert.True(registry.Contains("fault_code")); - } - - [Fact] - public async Task AddAgentCore_MatchesTheModerationKindWithoutRegardToCase() - { - // A vendor name is written by a human, exactly as the knowledge kinds are matched. - var adapter = new FakeModerationAdapter("TEST", new AlwaysFlagsEvaluator()); - - using var provider = await BuildAsync(ModeratedYaml, options => options.UseModeration(adapter)); - - Assert.Equal(1, adapter.Builds); - } - - [Fact] - public async Task AddAgentCore_FailsWhenTheDocumentNamesAModerationKindThisHostDoesNotRegister() - { - var error = await Assert.ThrowsAsync( - async () => await BuildAsync( - ModeratedYaml, - options => options.UseModeration(new FakeModerationAdapter("other", new AlwaysFlagsEvaluator())))); - - // The message names what this host does register, so the fix is obvious from the failure. - Assert.Contains("test", error.Message, StringComparison.Ordinal); - Assert.Contains("'other'", error.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task AddAgentCore_FailsWhenTwoModerationAdaptersAnswerToOneKind() - { - var error = await Assert.ThrowsAsync( - async () => await BuildAsync( - ModeratedYaml, - options => options.UseModeration( - new FakeModerationAdapter("test", new AlwaysFlagsEvaluator()), - new FakeModerationAdapter("test", new AlwaysFlagsEvaluator())))); - - // Two adapters for one kind means the document silently picked whichever was registered - // first, and every seam refuses that. - Assert.Contains("two adapters", error.Message, StringComparison.Ordinal); - - // And the noun is this seam's own. VendorSeam.Plural exists to keep four seams' wording - // through one shared selector, so moderation's "endpoints" is pinned here — without this, - // the argument could be dropped and nothing would fail. - Assert.Contains("endpoints", error.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task AddAgentCore_RefusesATurnTheDocumentsModerationVendorFlags() - { - using var provider = await BuildAsync( - ModeratedYaml, - options => options.UseModeration(new FakeModerationAdapter("test", new AlwaysFlagsEvaluator()))); - - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - var result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); - - // The wiring reaches the turn loop, and not only the registry. - Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, result.ReplyText); - } - - [Fact] - public async Task AddAgentCore_TakesTheSampleRateTheDocumentSets() - { - using var provider = await BuildAsync(TunedYaml); - - var sampler = provider.GetRequiredService(); - - // T18: the rate comes from evaluation.sampleRate, and the composition root reads it. - Assert.Equal(1, sampler.Rate); - Assert.True(sampler.ShouldSample()); - } - - // ------------------------------------------------------------------------------------------- - // The spoken fallback of section 8.7, from the document to the caller. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AQuietTurn_SpeaksTheFallbackTheDocumentNames() - { - using var provider = await BuildAsync(TunedYaml, options => options.UseChatClients( - _ => new RoutingChatClientFactory(new FragmentingChatClient(string.Empty)))); - var session = provider.GetRequiredService().ForFactory("main").Create(); - - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Equal("One moment please. I will try that again.", turn.ReplyText); - Assert.NotEqual(ConversationSession.FallbackReply, turn.ReplyText); - } - - [Fact] - public async Task AQuietTurn_SpeaksTheDefaultFallbackWhenTheDocumentNamesNone() - { - using var provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients( - _ => new RoutingChatClientFactory(new FragmentingChatClient(string.Empty)))); - var session = provider.GetRequiredService().ForFactory("main").Create(); - - var turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - - Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); - } - - [Fact] - public async Task AddAgentCore_KeepsAnEvaluationServiceTheHostRegisteredFirst() - { - EvaluationSampler mine = new(rate: 1); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - builder.Services.AddSingleton(mine); - ConfigureServices(builder.Services, OneAgentYaml, null); - - using var provider = await StartAsync(builder.Build()); - - // The in-memory publisher grows without a bound, and a long-running host replaces it. Every - // registration therefore steps aside, exactly as the session store does. - Assert.Same(mine, provider.GetRequiredService()); - } - - // ------------------------------------------------------------------------------------------- - // The conversation titler: one model, named by the document like every other model. - // ------------------------------------------------------------------------------------------- - - // The same agent, and a document that gives the titler a model of its own. - private const string TitlerYaml = - $$""" - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - titler: - model: { ref: titles } - {{MinimalProviders}} - - { kind: openai, model: gpt-4.1-nano, as: titles } - entries: - main: - agent: only - """; - - [Fact] - public async Task AddAgentCore_GivesTheTitlerTheModelTheDocumentNames() - { - RecordingChatClientFactory factory = new(); - using var provider = await BuildAsync(TitlerYaml, options => options.UseChatClients(_ => factory)); + // ------------------------------------------------------------------------------------------- + // What it registers. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AddAgentCore_RegistersTheCompiledAgentAsAProcessSingleton() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - var titler = provider.GetRequiredService(); + CompiledAgent first = provider.GetRequiredService>()["main"]; + CompiledAgent second = provider.GetRequiredService>()["main"]; - Assert.IsType(titler); - Assert.Equal("titles", factory.Asked?.Ref); - } + Assert.Same(first, second); + Assert.Equal("main", first.Name); - [Fact] - public async Task AddAgentCore_GivesTheTitlerTheDefaultModelWhenTheDocumentNamesNone() - { - RecordingChatClientFactory factory = new(); - using var provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients(_ => factory)); + // The registry compiled once, and every conversation shares that one result. + Assert.Equal(1, provider.GetRequiredService().CompileCount); + } - provider.GetRequiredService(); + [Fact] + public async Task AddAgentCore_RegistersOneSessionFactoryThatBuildsANewSessionForEachConversation() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); + IConversationSessionFactory factory = provider.GetRequiredService().ForFactory("main"); - // A null reference is how the factory is asked for the first declared entry. - Assert.Null(factory.Asked); - } + Assert.Same(factory, provider.GetRequiredService().ForFactory("main")); - [Fact] - public async Task AddAgentCore_KeepsATitlerTheHostRegisteredFirst() - { - SilentConversationTitler mine = new(); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - builder.Services.AddSingleton(mine); - ConfigureServices(builder.Services, TitlerYaml, null); + // A ConversationSession belongs to one conversation, so it is not a singleton and the container holds none. + ConversationSession first = factory.Create(); + ConversationSession second = factory.Create(); + Assert.NotSame(first, second); + Assert.NotEqual(first.ConversationId, second.ConversationId); + } - using var provider = await StartAsync(builder.Build()); + [Fact] + public async Task AddAgentCore_RegistersTheKnowledgePortTheHostBound() + { + FacetCapablePort port = new(); - Assert.Same(mine, provider.GetRequiredService()); - } + using StartedHost provider = await BuildAsync( + OneAgentYaml, options => options.UseKnowledgeRetrieval(_ => port)); - /// A titler that names nothing, for the test that only asks who won the registration. - private sealed class SilentConversationTitler : IConversationTitler - { - public async IAsyncEnumerable GenerateAsync( - string conversationId, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.CompletedTask; - yield break; + Assert.Same(port, provider.GetRequiredService()); } - public async IAsyncEnumerable GenerateFromAsync( - string conversationId, - IReadOnlyList messages, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + [Fact] + public async Task AddAgentCore_TheResolvedPortAnswersWhatElseItServes() { - await Task.CompletedTask; - yield break; - } - } - - // ------------------------------------------------------------------------------------------- - // The audit sink: named by providers.audit, and never absent. - // ------------------------------------------------------------------------------------------- - - // The same agent, and a document that names the built-in memory kind on purpose. - private const string MemoryAuditYaml = - $$""" - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - {{MinimalProviders}} - audit: { kind: memory } - entries: - main: - agent: only - """; + // What a consumer actually does with it: resolve the one port, then ask that port for the + // capability it needs. Registering each capability separately would hand out a second + // object for the same store, and a store that serves none would have to be registered as + // null anyway. + FacetCapablePort port = new(); - // The same agent, served by an audit vendor the host registers itself. - private const string VendorAuditYaml = - $$""" - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - {{MinimalProviders}} - audit: { kind: test } - entries: - main: - agent: only - """; + using StartedHost provider = await BuildAsync( + OneAgentYaml, options => options.UseKnowledgeRetrieval(_ => port)); - [Fact] - public async Task TheDefaultAuditSink_ReachesTheTurnLoopAndTheChainVerifies() - { - using var provider = await BuildAsync(OneAgentYaml); + IKnowledgeRetrievalPort knowledge = provider.GetRequiredService(); - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + Assert.Same(port, knowledge.GetService()); + } - // The queue is what keeps the append off the turn, so the rows land on a thread of their own - // and a reader that wants them now asks for them now. - await Queue(provider).FlushAsync(TestContext.Current.CancellationToken); + [Fact] + public async Task AddAgentCore_ADocumentThatReadsNoKnowledge_ResolvesNoPort() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - var events = Sink(provider).EventsOf("conversation-1"); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], - events.Select(item => item.Kind).ToArray()); - Assert.All(events, AuditEventVocabulary.Validate); - } + Assert.Null(provider.GetService()); + } - [Fact] - public async Task ADocumentThatNamesNoAuditProvider_StillOpensTheMemorySink() - { - using var provider = await BuildAsync(OneAgentYaml); + [Fact] + public async Task AddAgentCore_RegistersTheAgentShimAsAProcessSingleton() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - // The turn loop produces the events of D23 whatever a document says, so the seam that receives - // them has a working default rather than a null. That is what lets every reading of a conversation be - // unconditional, and what lets a first run and a test work with no database. - Assert.NotNull(provider.GetService()); - Assert.IsType(provider.GetRequiredService().Store); - } + AgentCoreAgent agent = provider.GetRequiredService().ForAgent("main"); - [Fact] - public async Task ADocumentThatNamesTheMemoryKind_OpensTheSameSinkAsNamingNothing() - { - using var provider = await BuildAsync(MemoryAuditYaml); + Assert.Same(agent, provider.GetRequiredService().ForAgent("main")); + Assert.Equal("main", agent.Name); - // memory is this library's own name and it needs no registered vendor, so writing it says out - // loud what leaving the block out does quietly. The startup warning is the difference. - Assert.IsType(provider.GetRequiredService().Store); - } + // One session of the shim is one conversation, drawn from the same factory the rest of the host + // uses, so the two seams describe the same conversations. + AgentSession session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken); + Assert.NotNull(session.GetService()); + } - [Fact] - public async Task AnAuditVendorTheDocumentNames_IsTheStoreBehindTheQueue() - { - RecordingAuditSink store = new(); - using var provider = await BuildAsync( - VendorAuditYaml, - options => options.UseAuditSinks(new TestAuditSinkAdapter(store))); - - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - await Queue(provider).FlushAsync(TestContext.Current.CancellationToken); - - // The host lists its vendors once and providers.audit.kind picks one, exactly as the five - // seams beside it. Nothing but the document decides which store the chain lands in. - Assert.Same(store, provider.GetRequiredService().Store); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], - store.Events.Select(item => item.Kind).ToArray()); - } + [Fact] + public async Task AddAgentCore_RegistersTheInMemorySessionsByDefault() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - [Fact] - public async Task AnAuditKindThisHostDoesNotRegister_FailsTheStart() - { - // A document that asked for something this host cannot give fails while the host starts, and - // never on a conversation. The message names the kind, exactly as every other vendor seam. - var failure = await Assert.ThrowsAsync( - () => BuildAsync(VendorAuditYaml)); + IConversationSessions sessions = provider.GetRequiredService().ForSessions("main"); - Assert.Contains("test", failure.Message, StringComparison.Ordinal); - } + _ = Assert.IsType(sessions); + Assert.Same(sessions, provider.GetRequiredService().ForSessions("main")); + } - [Fact] - public async Task TheAuditSink_IsWrappedInTheQueueThatKeepsItOffTheTurn() - { - using var provider = await BuildAsync(OneAgentYaml); + [Fact] + public async Task AddAgentCore_RunsTheIdleSweepForTheDefaultSessions() + { + // Expiry needs something to drive it. Without this the idle timeout never fires and the + // text path holds every conversation a caller walked away from for the life of the process. + using StartedHost provider = await BuildAsync(OneAgentYaml); - // Section 7 puts a durable insert at 13 ms p50 against 91 nanoseconds to enqueue, and the rule - // that follows is applied once, here, to whatever the document opened. So an adapter that - // blocks on its database is a correct adapter, and no adapter carries a queue of its own. - Assert.IsType(provider.GetRequiredService()); - } + Assert.Contains( + provider.GetServices(), + service => service is ConversationSessionSweeper); + } - /// Reads back the queue the composition root put in front of the document's store. - private static QueuedAuditSink Queue(IServiceProvider provider) - => Assert.IsType(provider.GetRequiredService()); + /// + /// The one thing deferring the boot to host start has to guarantee: a service the document + /// produced cannot be read before the document has been read. A provider nobody started answers + /// with a refusal that names the fix, and never with a half-built graph or a null. + /// + [Fact] + public void AServiceReadFromAProviderNobodyStarted_RefusesAndSaysWhatToDo() + { + ServiceCollection services = new(); + ConfigureServices(services, OneAgentYaml, null); - /// Reads back the store itself, which is registered under its own concrete type. - /// - /// The document builds the store now, not the host, so this is how a test that wants the events - /// of one conversation reaches the thing that holds them. Resolving gives the - /// queue instead, because that is the only registration that honours the port's contract. - /// - private static InMemoryAuditSink Sink(IServiceProvider provider) - => Assert.IsType(provider.GetRequiredService().Store); + using ServiceProvider provider = services.BuildServiceProvider(); - // ------------------------------------------------------------------------------------------- - // The transcript store: named by providers.conversations, and never absent. - // ------------------------------------------------------------------------------------------- + InvalidOperationException failure = Assert.Throws( + provider.GetRequiredService>); - // The same agent, served by a conversation-store vendor the host registers itself. - private const string VendorTranscriptYaml = - $$""" - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - {{MinimalProviders}} - conversations: { kind: test } - entries: - main: - agent: only - """; + Assert.Contains("has not booted", failure.Message, StringComparison.Ordinal); + Assert.Contains("StartAsync", failure.Message, StringComparison.Ordinal); + } - // The same agent, served by a knowledge vendor the host registers itself. - private const string VendorKnowledgeYaml = - $$""" - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - {{MinimalProviders}} - knowledge: { kind: test, collection: manuals, fields: { body: body } } - entries: - main: - agent: only - """; + [Fact] + public async Task AddAgentCore_UsesTheSessionsTheHostBound() + { + CountingConversationSessions mine = new(); - // The conversation store opens at step 4c and the moderation vendor is built at step 4c, so a - // document that names both puts a failure strictly after an open. Nothing else in the boot has - // that shape. - private const string ConversationStoreThenModerationFailureYaml = - $$""" - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - {{MinimalProviders}} - conversations: { kind: test } - moderation: { kind: test } - entries: - main: - agent: only - """; + using StartedHost provider = await BuildAsync( + OneAgentYaml, options => options.UseConversationSessions((_, _) => mine)); - [Fact] - public async Task ADocumentThatNamesNoConversationStoreProvider_StillOpensTheMemoryStore() - { - using var provider = await BuildAsync(OneAgentYaml); + // A distributed store replaces the default one, and the default steps aside. + Assert.Same(mine, provider.GetRequiredService().ForSessions("main")); + } - // The turn loop writes the words of every conversation whatever a document says, so this seam has a - // working default rather than a null, and a first run needs no database. - Assert.NotNull(provider.GetService()); - Assert.IsType(provider.GetRequiredService().Store); - } + [Fact] + public async Task AddAgentCore_OpensOneStorePerEntry() + { + // A vendor call id arriving on two entries opens two isolated conversations. That holds only when + // each entry has its own store, so the host's opener runs once per entry and is told which. + List opened = []; - [Fact] - public async Task AConversationStoreVendorTheDocumentNames_IsTheStoreTheTurnWritesTo() - { - RecordingConversationStore store = new(); - using var provider = await BuildAsync( - VendorTranscriptYaml, - options => options.UseConversationStores(new TestConversationStoreAdapter(store))); - - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - await session.FlushTranscriptAsync(); - - // The host lists its vendors once and providers.conversations.kind picks one. Nothing but the - // document decides where the words of a conversation land. - Assert.Same(store, provider.GetRequiredService().Store); - Assert.Equal(["user", "assistant"], store.Roles); - } + using StartedHost provider = await BuildAsync(TwoEntryYaml, options => options.UseConversationSessions( + (entry, factory) => + { + opened.Add(entry); + return new InMemoryConversationSessions( + factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); + })); - [Fact] - public async Task AConversationStoreKindThisHostDoesNotRegister_FailsTheStart() - { - // A document that asked for something this host cannot give fails while the host starts, and - // never on a conversation. - var failure = await Assert.ThrowsAsync( - () => BuildAsync(VendorTranscriptYaml)); + IConversationSessionRegistry registry = provider.GetRequiredService(); - Assert.Contains("test", failure.Message, StringComparison.Ordinal); - } + Assert.Equal(["main", "other"], opened.Order(StringComparer.Ordinal)); + Assert.NotSame(registry.ForSessions("main"), registry.ForSessions("other")); + } - /// A conversation-store vendor that hands over the store the test holds. - private sealed class TestConversationStoreAdapter(RecordingConversationStore store) : IConversationStoreAdapter - { - public string Kind => "test"; + [Fact] + public async Task AddAgentCore_RegistersTheSessionRegistryAsAPublicPort() + { + // A consumer reaches an entry's store through the port, never through the internal + // registry, and never through a bare IConversationSessions: no store spans the whole host. + using StartedHost provider = await BuildAsync(OneAgentYaml); - public ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(store); - } + IConversationSessionRegistry registry = provider.GetRequiredService(); - /// A store 1 backing that keeps the role of every row it accepted. - /// - /// Keeps only , with no conversationId or ordinal, so it cannot rebuild a - /// to answer a read or an erase truthfully. and - /// report empty and 0 even after has recorded - /// rows — a test that needs either should use a different double. - /// - private sealed class RecordingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()), IAsyncDisposable - { - private readonly Lock _gate = new(); - private readonly List _roles = []; + Assert.Equal(["main"], registry.Entries); + Assert.Same( + provider.GetRequiredService().ForSessions("main"), + registry.ForSessions("main")); + Assert.Null(provider.GetService()); - /// Gets whether this store was closed. - public bool Closed { get; private set; } + InvalidOperationException failure = Assert.Throws(() => registry.ForSessions("missing")); + Assert.Contains("main", failure.Message, StringComparison.Ordinal); + } - /// Gets the role of each row this store accepted, in the order it arrived. - public IReadOnlyList Roles + // ------------------------------------------------------------------------------------------- + // Telemetry shuts down with the host. The container owns the session, so its disposal is the + // flush — which is the one path a start that failed also reaches. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AddAgentCore_RegistersTheTelemetrySessionTheDocumentNames() { - get + (IHost? host, FlushRecordingTelemetryAdapter? adapter) = await BuildTelemetryHostAsync(); + + using (host) { - lock (_gate) - { - return [.. _roles]; - } + await host.StartAsync(TestContext.Current.CancellationToken); + + // A host that reads its own spans and metrics resolves this. Nothing in this library + // does, so only a test holds it to being there at all. + Assert.Same(adapter.Session, host.Services.GetRequiredService()); } } - public override ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) + [Fact] + public async Task AddAgentCore_RegistersNoTelemetrySessionWhenTheHostBindsNoVendor() { - lock (_gate) - { - _roles.AddRange(messages.Select(message => message.Content.Role.Value)); - } + using StartedHost provider = await BuildAsync(OneAgentYaml); - IReadOnlyList rows = [.. messages.Select( - (message, index) => new ConversationMessage(conversationId, index, message.TurnIndex ?? 0, message.Content, message.MessageId))]; - return ValueTask.FromResult(rows); + Assert.Null(provider.GetService()); } - public override ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - => ValueTask.CompletedTask; + [Fact] + public async Task AddAgentCore_FlushesTheTelemetrySessionWhenTheHostShutsDown() + { + (IHost? host, FlushRecordingTelemetryAdapter? adapter) = await BuildTelemetryHostAsync(); - public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) => - ValueTask.FromResult(0); + await host.StartAsync(TestContext.Current.CancellationToken); - public ValueTask DisposeAsync() - { - Closed = true; - return ValueTask.CompletedTask; + Assert.Equal(0, adapter.Session.Flushes); + + await host.StopAsync(TestContext.Current.CancellationToken); + host.Dispose(); + + Assert.Equal(1, adapter.Session.Flushes); } - } - /// A knowledge vendor that hands back one port and keeps a reference to it. - private sealed class DisposeTrackingKnowledgeAdapter : IKnowledgeStoreAdapter - { - public string Kind => "test"; + [Fact] + public async Task AddAgentCore_FlushesTheTelemetrySessionOnceWhenTheHostIsDisposedTwice() + { + (IHost? host, FlushRecordingTelemetryAdapter? adapter) = await BuildTelemetryHostAsync(); - public bool CanServeSearch => true; + await host.StartAsync(TestContext.Current.CancellationToken); + await host.StopAsync(TestContext.Current.CancellationToken); - public bool CanScope => true; + // An adapter's session is not required to survive being drained twice, so the second call + // has to be a no-op. + host.Dispose(); + host.Dispose(); - /// Gets the port the last build returned, or before one built. - public DisposeTrackingKnowledgePort? Built { get; private set; } + Assert.Equal(1, adapter.Session.Flushes); + } - public ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default) + // ------------------------------------------------------------------------------------------- + // The audit chain shuts down with the host. An event is ACCEPTED when AppendAsync returns, so a + // stop that does not drain the queue loses every row still in it. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AddAgentCore_DrainsTheAuditQueueWhenTheHostShutsDown() { - Built = new DisposeTrackingKnowledgePort(); - return ValueTask.FromResult(Built); - } - } + (IHost? host, ClosingAuditSink? store) = await BuildAuditHostAsync(); - /// A knowledge port that answers with nothing and tracks whether it was closed. - /// A knowledge port that also reads whole cards by an exact facet value. - private sealed class FacetCapablePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort - { - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + await host.StartAsync(TestContext.Current.CancellationToken); - public ValueTask> ReadByFacetAsync( - string path, string value, int limit, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); - } + await host.Services + .GetRequiredService() + .AppendAsync(AuditRow(1), TestContext.Current.CancellationToken); - private sealed class DisposeTrackingKnowledgePort : IKnowledgeRetrievalPort, IDisposable - { - /// Gets whether this port was closed. - public bool Closed { get; private set; } + await host.StopAsync(TestContext.Current.CancellationToken); + host.Dispose(); - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + Assert.Equal(1, store.Written); + } - public void Dispose() => Closed = true; - } + [Fact] + public async Task AddAgentCore_ClosesTheAuditStoreOnlyAfterTheQueueHasDrained() + { + (IHost? host, ClosingAuditSink? store) = await BuildAuditHostAsync(); - [Fact] - public async Task NoLoggerAndNoAuditVendor_StillRunsATurn() - { - using var provider = await BuildAsync(OneAgentYaml); + await host.StartAsync(TestContext.Current.CancellationToken); - var session = provider.GetRequiredService().ForFactory("main").Create(); - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + await host.Services + .GetRequiredService() + .AppendAsync(AuditRow(1), TestContext.Current.CancellationToken); - Assert.Equal("hello", turn.ReplyText); - } + await host.StopAsync(TestContext.Current.CancellationToken); - // ------------------------------------------------------------------------------------------- - // The host's own observers: the socket behind IConversationObserver. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AHostObserver_ReadsTheFactsOfATurn() - { - RecordingConversationObserver first = new(); - RecordingConversationObserver second = new(); - using var provider = await BuildAsync(OneAgentYaml, options => options.UseObservers(first, second)); + // The container closes what it resolved before it closes the boot that still owns the store + // behind the queue. Closing that store first would hand the drain a store which can no + // longer accept the rows it already promised to keep. + host.Dispose(); - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + Assert.True(store.Closed); + Assert.Equal(1, store.WrittenWhenClosed); + } - // The port is public, so a host writes one of these and binds it. Every observer of a conversation - // reads the same facts, and the library's own three are neither replaced nor bypassed. - Assert.Equal([ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted], first.Seen); - Assert.Equal([ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted], second.Seen); - } + [Fact] + public async Task AddAgentCore_ClosesTheConversationStoreWhenTheHostShutsDown() + { + RecordingConversationStore store = new(); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ConfigureServices( + builder.Services, + VendorTranscriptYaml, + options => options.UseConversationStores(new TestConversationStoreAdapter(store))); + + IHost host = builder.Build(); + await host.StartAsync(TestContext.Current.CancellationToken); + await host.StopAsync(TestContext.Current.CancellationToken); + host.Dispose(); + + Assert.True(store.Closed); + } - [Fact] - public async Task AHostObserverThatThrows_CostsNeitherTheTurnNorTheChain() - { - using var provider = await BuildAsync( - OneAgentYaml, - options => options.UseObservers(new ThrowingConversationObserver())); + [Fact] + public async Task AddAgentCore_ClosesTheKnowledgePortWhenTheHostShutsDown() + { + // KnowledgeStartup.OpenAsync's result used to be discarded with `_ = await ...`, so a + // successful open -- a QdrantClient in production -- was never tracked against the boot and + // outlived host shutdown. This proves the port the adapter built is closed the same way the + // conversation store above is. + DisposeTrackingKnowledgeAdapter adapter = new(); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ConfigureServices( + builder.Services, + VendorKnowledgeYaml, + options => options.UseKnowledgeStores(adapter)); + + IHost host = builder.Build(); + await host.StartAsync(TestContext.Current.CancellationToken); + + Assert.NotNull(adapter.Built); + Assert.False(adapter.Built.Closed); + + await host.StopAsync(TestContext.Current.CancellationToken); + host.Dispose(); + + Assert.True(adapter.Built.Closed); + } - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - var turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + [Fact] + public async Task AHostRegisteredDisposableToolSource_IsClosedWhenTheHostShutsDown() + { + // Disposal happens once, when the container closes the boot that owns the source — the same + // route McpToolSource is closed through, proved here with no MCP server involved. The + // reference kept below is exactly the case that makes the risk small rather than zero: + // AddToolSource's factory could be called more than once by a host that keeps its own + // reference to what it returns, and closing it anyway costs little because the host was + // about to lose it either way. + DisposeTrackingToolSource source = new(); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ConfigureServices( + builder.Services, + OneAgentYaml, + options => options.AddToolSource(_ => source)); + + IHost host = builder.Build(); + await host.StartAsync(TestContext.Current.CancellationToken); + + Assert.False(source.Disposed); + + await host.StopAsync(TestContext.Current.CancellationToken); + host.Dispose(); + + Assert.True(source.Disposed); + } - // An observer records the conversation and is never a part of it. That holds for the host's own, and - // it holds for the readings registered beside it: a broken host observer does not cost the - // chain of D23 a single row. - Assert.Equal("hello", turn.ReplyText); + // ------------------------------------------------------------------------------------------- + // The document picks the vendor, and no code names one: the point of the adapter seam. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task TheAdapterOverload_LetsTheDocumentPickTheVendorByItsKind() + { + // 'kind: openai' selects the adapter registered under that kind. The host lists what it + // supports, once, and the document decides which entry runs. + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients( + new FakeChatClientAdapter("openai", () => new FragmentingChatClient("routed")), + new FakeChatClientAdapter("anthropic", () => new FragmentingChatClient("wrong vendor")))); - await Queue(provider).FlushAsync(TestContext.Current.CancellationToken); + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create(); + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - var events = Sink(provider).EventsOf("conversation-1"); - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], - events.Select(item => item.Kind).ToArray()); - Assert.All(events, AuditEventVocabulary.Validate); - } + Assert.Equal("routed", turn.ReplyText); + } - [Fact] - public async Task UseObserversTwice_KeepsBothRegistrations() - { - RecordingConversationObserver first = new(); - RecordingConversationObserver second = new(); - using var provider = await BuildAsync( - OneAgentYaml, - options => options.UseObservers(first).UseObservers(second)); - - var session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); - await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // The seam adds rather than replaces, so a host composes its readings across whatever code - // configures the container. - Assert.NotEmpty(first.Seen); - Assert.NotEmpty(second.Seen); - } + [Fact] + public async Task AKindNoRegisteredAdapterServes_FailsTheStartAndNamesBothSides() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => BuildAsync( + OtherVendorYaml, + options => options.UseChatClients( + new FakeChatClientAdapter("openai", () => new FragmentingChatClient("hello"))))); + + // The message names the kind the document wrote and the kinds the host registers, so the + // reader knows which side to change. + Assert.Contains("anthropic", failure.Message, StringComparison.Ordinal); + Assert.Contains("'openai'", failure.Message, StringComparison.Ordinal); + } - // ------------------------------------------------------------------------------------------- - // What it refuses. - // ------------------------------------------------------------------------------------------- - [Fact] - public async Task ABadDocument_FailsTheStartAndNamesTheFault() - { - var failure = await Assert.ThrowsAsync(() => BuildAsync(BrokenYaml)); + [Fact] + public async Task AnAsyncSeam_BuildsItsFactoryWithNoBlockedThread() + { + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients( + async (startup, cancellationToken) => + { + await Task.Yield(); + return new RoutingChatClientFactory(new FragmentingChatClient("awaited")); + })); - var error = Assert.Single(failure.Errors); - Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); - Assert.Equal("/entries/main/policy/stages/0/to/0/stage", error.Pointer); - Assert.Contains("'nowhere' is not declared", error.Message, StringComparison.Ordinal); - } + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create(); + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - /// - /// The reference pass runs after discovery, against what the tool registry actually serves. A - /// state slot's from: naming a tool nothing serves — not declared, and no mcp: - /// server offers it either — still stops the boot rather than leaving the slot silently unfilled. - /// - [Fact] - public async Task AnUndeclaredToolInAStateSlot_FailsTheStartAndNamesTheTool() - { - var failure = await Assert.ThrowsAsync(() => BuildAsync(UndeclaredToolYaml)); + Assert.Equal("awaited", turn.ReplyText); + } - var error = Assert.Single(failure.Errors); - Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); - Assert.Equal("/state/orderStatus/from", error.Pointer); - Assert.Contains("lookup_order", error.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AToolSource_SeesTheChatClientFactoryAlreadyBuilt() + { + // The seam that builds the factory only runs once, so a null capture here means the tools + // were built before it ran — exactly the ordering builtin tools depend on. + IChatClientFactory? builtFactory = null; + IChatClientFactory? seenWhenToolsWereBuilt = null; - [Fact] - public async Task AnAgentToolReferencingAnIdNothingServes_FailsTheStartNamingTheAgent() - { - var failure = await Assert.ThrowsAsync(() => BuildAsync(UndeclaredAgentToolYaml)); + using StartedHost provider = await BuildAsync(OneAgentYaml, options => + { + _ = options.UseChatClients((_, _) => + { + builtFactory = new RoutingChatClientFactory(new FragmentingChatClient("hello")); + return ValueTask.FromResult(builtFactory); + }); - var error = Assert.Single(failure.Errors); - Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); - Assert.Equal("/agents/items/0/tools/0", error.Pointer); - Assert.Contains("no_such_tool", error.Message, StringComparison.Ordinal); - } + _ = options.AddToolSource(_ => new SpyToolSource(() => seenWhenToolsWereBuilt = builtFactory)); + }); - /// - /// A source's own discovery can succeed while the boot still fails later: here, an agent's - /// tools: names an id nothing serves, so ValidateToolReferences throws after - /// already returned. AgentCoreBoot tracked - /// the source as it was built, before any discovery ran, so the failed start closes it however - /// far the boot had got. - /// - [Fact] - public async Task AToolReferenceFailureAfterDiscoverySucceeds_StillDisposesTheSource() - { - var source = new DisposeTrackingToolSource(); + Assert.NotNull(provider.GetRequiredService>()["main"]); + Assert.NotNull(seenWhenToolsWereBuilt); + Assert.Same(builtFactory, seenWhenToolsWereBuilt); + } - await Assert.ThrowsAsync(() => BuildAsync( - UndeclaredAgentToolYaml, - options => options.AddToolSource(_ => source))); + // ------------------------------------------------------------------------------------------- + // The seams the host binds. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task ABindingTool_ReachesTheDelegateTheHostRegistered() + { + using StartedHost provider = await BuildAsync( + BindingYaml, + options => options.Bind("CreateCase", (_, _) => ValueTask.FromResult(new JsonObject()))); - Assert.True(source.Disposed); - } + ToolBindingRegistry bindings = provider.GetRequiredService(); - /// - /// The conversation store is opened at step 4c, and the moderation vendor is built after it. A - /// document that names a moderation kind this host does not register therefore fails with the - /// store already open, and nothing between the two steps has taken ownership of it. - /// - [Fact] - public async Task AFailureAfterTheConversationStoreOpens_StillClosesTheStore() - { - RecordingConversationStore store = new(); + Assert.True(bindings.Contains("CreateCase")); + Assert.Equal(1, bindings.Count); + } - await Assert.ThrowsAsync(() => BuildAsync( - ConversationStoreThenModerationFailureYaml, - options => options - .UseConversationStores(new TestConversationStoreAdapter(store)) - .UseModeration(new FakeModerationAdapter("other", new AlwaysFlagsEvaluator())))); + [Fact] + public async Task ABindingToolWithNoDelegate_FailsTheStartAndNamesTheBinding() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => BuildAsync(BindingYaml)); - Assert.True(store.Closed); - } + Assert.Contains("CreateCase", failure.Message, StringComparison.Ordinal); + Assert.Contains("did not register", failure.Message, StringComparison.Ordinal); + } - /// - /// The id collision between a discovered tool and a declared kind: agent tool is only - /// found once every source has answered, so the source that served the colliding id is open by - /// then. It must not be left running. - /// - [Fact] - public async Task AnIdCollisionFoundAfterDiscovery_StillClosesTheSource() - { - DisposeTrackingToolSource source = new("shared_id"); + [Fact] + public async Task ASecretReference_ResolvesOnceAtStartup() + { + using HttpClient client = new(); + MapSecretResolver resolver = new(); + _ = resolver.With("orders-api-key", "a-value-no-message-repeats"); - await Assert.ThrowsAsync(() => BuildAsync( - CollidingAgentToolYaml, - options => options.AddToolSource(_ => source))); + using StartedHost provider = await BuildAsync( + SecretYaml, + options => + { + options.SecretResolver = resolver; + _ = options.AddToolSource(startup => new HttpToolSource(client, startup.Secrets)); + }); - Assert.True(source.Disposed); - } + ResolvedSecrets secrets = provider.GetRequiredService(); - /// - /// An id no tools: entry names, served only by a discovering source, still satisfies an - /// agent's reference through - /// end to end, public API only. An mcp: server's tools work exactly this way: decision 15 - /// requires the reference pass to resolve against what got discovered, not just what got declared. - /// - [Fact] - public async Task ADiscoveredOnlyTool_SatisfiesAnAgentsReferenceThroughTheRealBoot() - { - using var provider = await BuildAsync( - DiscoveredOnlyToolYaml, - options => options.AddToolSource(_ => new DiscoveredOnlyToolSource("discovered_only"))); + Assert.True(secrets.Contains("orders-api-key")); - Assert.NotNull(provider.GetRequiredService>()["main"]); - Assert.True(provider.GetRequiredService().Contains("discovered_only")); - } + // A resolved set lands in a log line sooner or later, so it reports the count and never a value. + Assert.DoesNotContain("a-value-no-message-repeats", secrets.ToString(), StringComparison.Ordinal); + } - /// - /// carves - /// out of its own "every declaration is served" rule, because that kind reaches no source — the - /// compile table builds it once the agent it names has compiled. The reference pass in the - /// composition root has to carve the same kind out of its own served-ids set for the same reason, - /// or a document exactly like this one — the shape section 8.1 calls agent-as-tool — fails to - /// boot even though it declares nothing wrong. - /// - [Fact] - public async Task ADelegatingAgentTool_BootsBecauseKindAgentReachesNoSource() - { - using var provider = await BuildAsync(DelegatingAgentToolYaml); + [Fact] + public async Task ASecretReferenceWithNoResolver_FailsTheStartAndNamesTheSecret() + { + using HttpClient client = new(); - Assert.NotNull(provider.GetRequiredService>()["main"]); - } + SecretResolutionException failure = await Assert.ThrowsAsync(() => BuildAsync( + SecretYaml, + options => options.AddToolSource(startup => new HttpToolSource(client, startup.Secrets)))); - /// - /// Decision 15's whole justification: a YAML typo must never cost a round trip to an MCP server. - /// This document carries both a structural defect and an mcp: server whose command does - /// not exist, so the two possible orderings are observably different: structure-first reports - /// the policy fault and never touches the server; discovery-first would instead report that the - /// server could not be reached, because Process.Start on a missing executable fails - /// synchronously, well before any structural error would ever be found. The error alone only - /// infers the order; observes it directly by recording whether - /// ProvideAsync was ever called on any source at all — structure-first means - /// never runs, so nothing - /// is ever asked, not even a source that serves nothing. - /// - [Fact] - public async Task AddAgentCore_TheStructuralFaultSurfaces_BeforeMcpIsEverAsked() - { - var asked = false; + Assert.Equal("orders-api-key", failure.SecretName); + } - var failure = await Assert.ThrowsAsync(() => BuildAsync( - StructuralFaultPlusUnreachableMcpYaml, - options => - { - // Registered before McpToolSource, so this is asked first if discovery runs at all — - // a true observer of whether ToolRegistryBuilder.BuildAsync began, not just of - // whether the MCP source in particular got asked. - options.AddToolSource(_ => new SpyToolSource(() => asked = true)); - options.AddToolSource(startup => new McpToolSource(startup.Secrets)); - })); - - var error = Assert.Single(failure.Errors); - Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); - Assert.Equal("/entries/main/policy/stages/0/to/0/stage", error.Pointer); - Assert.Contains("'nowhere' is not declared", error.Message, StringComparison.Ordinal); - - // Distinguishes the orders directly: an MCP connection failure would name the server id. - Assert.DoesNotContain("bogus-server", failure.Message, StringComparison.Ordinal); - - Assert.False(asked); - } + // ------------------------------------------------------------------------------------------- + // Row 4 of the compile table, through the only supported composition root. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AGuardedGraph_Starts() + { + using StartedHost provider = await BuildGuardedGraphAsync(); - [Fact] - public async Task ADocumentThatDoesNotParse_FailsTheStart() - { - var failure = await Assert.ThrowsAsync( - () => StartBareAsync(options => - { - options.ConfigurationPath = "no-such-extension.txt"; - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - })); + CompiledAgent compiled = provider.GetRequiredService>()["main"]; - Assert.Equal(ConfigurationCheck.Syntax, failure.Check); - } + // The document passes all eight checks and now compiles too. AddAgentCore binds the guard + // evaluator, so a guarded edge is reachable from here. + Assert.Equal(CompiledAgentShape.ExplicitGraph, compiled.Shape); + Assert.Equal("main", compiled.Name); + } - [Fact] - public async Task NoDocumentAtAll_FailsTheStartAndSaysWhatToSet() - { - var failure = await Assert.ThrowsAsync( - () => StartBareAsync( - options => options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))))); + [Theory] + [InlineData(true, "ESCALATED", "HANDLED")] + [InlineData(false, "HANDLED", "ESCALATED")] + public async Task AGuardedGraph_TakesTheEdgeTheStateOfTheConversationNames(bool escalate, string taken, string refused) + { + using StartedHost provider = await BuildGuardedGraphAsync(); + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create(); + _ = session.State.TryWrite("escalate", escalate); - Assert.Contains("names no document", failure.Message, StringComparison.Ordinal); - } + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); - [Fact] - public async Task TwoDocuments_FailTheStart() - { - var failure = await Assert.ThrowsAsync( - () => StartBareAsync(options => - { - options.Configuration = ConfigurationLoader.LoadYaml(OneAgentYaml); - options.ConfigurationPath = "config/example.yaml"; - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - })); + Assert.Contains(taken, turn.ReplyText, StringComparison.Ordinal); + Assert.DoesNotContain(refused, turn.ReplyText, StringComparison.Ordinal); + } - Assert.Contains("names two documents", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AGuardedGraph_KeepsTwoConversationsApartWhenTheyRunAtTheSameTime() + { + using StartedHost provider = await BuildGuardedGraphAsync(); + IConversationSessionFactory sessions = provider.GetRequiredService().ForFactory("main"); + CancellationToken token = TestContext.Current.CancellationToken; + + ConversationSession escalated = sessions.Create(); + _ = escalated.State.TryWrite("escalate", true); + ConversationSession handled = sessions.Create(); + _ = handled.State.TryWrite("escalate", false); + + // One compiled graph, two conversations, two edges. Neither conversation reads the state of the other. + TurnResult[] turns = await Task.WhenAll( + escalated.RunTurnAsync("hello", token), + handled.RunTurnAsync("hello", token)); + + Assert.Contains("ESCALATED", turns[0].ReplyText, StringComparison.Ordinal); + Assert.Contains("HANDLED", turns[1].ReplyText, StringComparison.Ordinal); + Assert.Equal(1, provider.GetRequiredService().CompileCount); + } - [Fact] - public async Task NoChatClientAdapter_FailsTheStart() - { - var failure = await Assert.ThrowsAsync( - () => StartBareAsync(options => options.Configuration = ConfigurationLoader.LoadYaml(OneAgentYaml))); + // ------------------------------------------------------------------------------------------- + // The evaluation seam of D13. Triage row T18 defers the online path, so the rate is 0. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AddAgentCore_RegistersTheEvaluationSeamWithTheOnlinePathClosed() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - Assert.Contains("UseChatClients", failure.Message, StringComparison.Ordinal); - } + EvaluatorRegistry registry = provider.GetRequiredService(); + EvaluationSampler sampler = provider.GetRequiredService(); - [Fact] - public async Task AddAgentCore_AnAgentWithSkills_Boots() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); + // D13 names fault_code, and it calls no model, so it is the one evaluator that is safe by + // default. + Assert.True(registry.Contains("fault_code")); - const string yaml = """ - apiVersion: agentcore/v1 - agents: - items: - - { id: only, instructions: "I answer everything" } - entries: - main: - agent: only - """; + // T18: a judge must never block a turn, and the offline gate has not proved the evaluators + // yet. A rate of 0 draws no number and conversations nothing. + Assert.Equal(0, sampler.Rate); + Assert.False(sampler.ShouldSample()); - using var host = await BuildAsync(yaml, options => options.UseSkills(folder.Root)); + _ = Assert.IsType(provider.GetRequiredService()); + } - Assert.NotNull(host); - } + [Fact] + public async Task AddAgentCore_RegistersNoModeratorWhenTheHostBindsNoVendor() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - [Fact] - public async Task AddAgentCore_AnAgentNamingASkillTheFolderDoesNotServe_FailsAtBoot() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); + EvaluatorRegistry registry = provider.GetRequiredService(); - const string yaml = """ - apiVersion: agentcore/v1 - agents: + // A host that registers no moderation vendor moderates nothing, and every turn reaches the + // model. Moderation needs a vendor account, and a library that refused to start without one + // could not be used in a test. + Assert.False(registry.Contains(PromptModerator.ModerationEvaluatorName)); + Assert.Null(PromptModerator.FromRegistry(registry)); + } + + [Fact] + public async Task AddAgentCore_BuildsNoModeratorWhenTheDocumentNamesNoProvider() + { + FakeModerationAdapter adapter = new("test", new AlwaysFlagsEvaluator()); + + // The vendor is registered and the document names none, so the adapter is never asked to + // build anything. Registering a vendor costs nothing until a document names it. + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseModeration(adapter)); + + Assert.False(provider.GetRequiredService() + .Contains(PromptModerator.ModerationEvaluatorName)); + Assert.Equal(0, adapter.Builds); + } + + [Fact] + public async Task AddAgentCore_BuildsTheModerationVendorTheDocumentNames() + { + FakeModerationAdapter adapter = new("test", new AlwaysFlagsEvaluator()); + + using StartedHost provider = await BuildAsync(ModeratedYaml, options => options.UseModeration(adapter)); + + EvaluatorRegistry registry = provider.GetRequiredService(); + + // The same object serves the turn loop and the offline golden set, which is what D13 means + // by an evaluator written once and used twice. + Assert.Equal(1, adapter.Builds); + Assert.True(registry.Contains(PromptModerator.ModerationEvaluatorName)); + Assert.True(registry.Contains("fault_code")); + } + + [Fact] + public async Task AddAgentCore_MatchesTheModerationKindWithoutRegardToCase() + { + // A vendor name is written by a human, exactly as the knowledge kinds are matched. + FakeModerationAdapter adapter = new("TEST", new AlwaysFlagsEvaluator()); + + using StartedHost provider = await BuildAsync(ModeratedYaml, options => options.UseModeration(adapter)); + + Assert.Equal(1, adapter.Builds); + } + + [Fact] + public async Task AddAgentCore_FailsWhenTheDocumentNamesAModerationKindThisHostDoesNotRegister() + { + ConfigurationLoadException error = await Assert.ThrowsAsync( + async () => await BuildAsync( + ModeratedYaml, + options => options.UseModeration(new FakeModerationAdapter("other", new AlwaysFlagsEvaluator())))); + + // The message names what this host does register, so the fix is obvious from the failure. + Assert.Contains("test", error.Message, StringComparison.Ordinal); + Assert.Contains("'other'", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task AddAgentCore_FailsWhenTwoModerationAdaptersAnswerToOneKind() + { + ConfigurationLoadException error = await Assert.ThrowsAsync( + async () => await BuildAsync( + ModeratedYaml, + options => options.UseModeration( + new FakeModerationAdapter("test", new AlwaysFlagsEvaluator()), + new FakeModerationAdapter("test", new AlwaysFlagsEvaluator())))); + + // Two adapters for one kind means the document silently picked whichever was registered + // first, and every seam refuses that. + Assert.Contains("two adapters", error.Message, StringComparison.Ordinal); + + // And the noun is this seam's own. VendorSeam.Plural exists to keep four seams' wording + // through one shared selector, so moderation's "endpoints" is pinned here — without this, + // the argument could be dropped and nothing would fail. + Assert.Contains("endpoints", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task AddAgentCore_RefusesATurnTheDocumentsModerationVendorFlags() + { + using StartedHost provider = await BuildAsync( + ModeratedYaml, + options => options.UseModeration(new FakeModerationAdapter("test", new AlwaysFlagsEvaluator()))); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + TurnResult result = await session.RunTurnAsync("...", TestContext.Current.CancellationToken); + + // The wiring reaches the turn loop, and not only the registry. + Assert.Equal(AgentCoreConfiguration.DefaultRefusalReply, result.ReplyText); + } + + [Fact] + public async Task AddAgentCore_TakesTheSampleRateTheDocumentSets() + { + using StartedHost provider = await BuildAsync(TunedYaml); + + EvaluationSampler sampler = provider.GetRequiredService(); + + // T18: the rate comes from evaluation.sampleRate, and the composition root reads it. + Assert.Equal(1, sampler.Rate); + Assert.True(sampler.ShouldSample()); + } + + // ------------------------------------------------------------------------------------------- + // The spoken fallback of section 8.7, from the document to the caller. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AQuietTurn_SpeaksTheFallbackTheDocumentNames() + { + using StartedHost provider = await BuildAsync(TunedYaml, options => options.UseChatClients( + _ => new RoutingChatClientFactory(new FragmentingChatClient(string.Empty)))); + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create(); + + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + Assert.Equal("One moment please. I will try that again.", turn.ReplyText); + Assert.NotEqual(ConversationSession.FallbackReply, turn.ReplyText); + } + + [Fact] + public async Task AQuietTurn_SpeaksTheDefaultFallbackWhenTheDocumentNamesNone() + { + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients( + _ => new RoutingChatClientFactory(new FragmentingChatClient(string.Empty)))); + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create(); + + TurnResult turn = await session.RunTurnAsync("hello", TestContext.Current.CancellationToken); + + Assert.Equal(ConversationSession.FallbackReply, turn.ReplyText); + } + + [Fact] + public async Task AddAgentCore_KeepsAnEvaluationServiceTheHostRegisteredFirst() + { + EvaluationSampler mine = new(rate: 1); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + _ = builder.Services.AddSingleton(mine); + ConfigureServices(builder.Services, OneAgentYaml, null); + + using StartedHost provider = await StartAsync(builder.Build()); + + // The in-memory publisher grows without a bound, and a long-running host replaces it. Every + // registration therefore steps aside, exactly as the session store does. + Assert.Same(mine, provider.GetRequiredService()); + } + + // ------------------------------------------------------------------------------------------- + // The conversation titler: one model, named by the document like every other model. + // ------------------------------------------------------------------------------------------- + + // The same agent, and a document that gives the titler a model of its own. + private const string TitlerYaml = + $$""" + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + titler: + model: { ref: titles } + {{MinimalProviders}} + - { kind: openai, model: gpt-4.1-nano, as: titles } + entries: + main: + agent: only + """; + + [Fact] + public async Task AddAgentCore_GivesTheTitlerTheModelTheDocumentNames() + { + RecordingChatClientFactory factory = new(); + using StartedHost provider = await BuildAsync(TitlerYaml, options => options.UseChatClients(_ => factory)); + + IConversationTitler titler = provider.GetRequiredService(); + + _ = Assert.IsType(titler); + Assert.Equal("titles", factory.Asked?.Ref); + } + + [Fact] + public async Task AddAgentCore_GivesTheTitlerTheDefaultModelWhenTheDocumentNamesNone() + { + RecordingChatClientFactory factory = new(); + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseChatClients(_ => factory)); + + _ = provider.GetRequiredService(); + + // A null reference is how the factory is asked for the first declared entry. + Assert.Null(factory.Asked); + } + + [Fact] + public async Task AddAgentCore_KeepsATitlerTheHostRegisteredFirst() + { + SilentConversationTitler mine = new(); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + _ = builder.Services.AddSingleton(mine); + ConfigureServices(builder.Services, TitlerYaml, null); + + using StartedHost provider = await StartAsync(builder.Build()); + + Assert.Same(mine, provider.GetRequiredService()); + } + + /// A titler that names nothing, for the test that only asks who won the registration. + private sealed class SilentConversationTitler : IConversationTitler + { + public async IAsyncEnumerable GenerateAsync( + string conversationId, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.CompletedTask; + yield break; + } + + public async IAsyncEnumerable GenerateFromAsync( + string conversationId, + IReadOnlyList messages, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.CompletedTask; + yield break; + } + } + + // ------------------------------------------------------------------------------------------- + // The audit sink: named by providers.audit, and never absent. + // ------------------------------------------------------------------------------------------- + + // The same agent, and a document that names the built-in memory kind on purpose. + private const string MemoryAuditYaml = + $$""" + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + {{MinimalProviders}} + audit: { kind: memory } + entries: + main: + agent: only + """; + + // The same agent, served by an audit vendor the host registers itself. + private const string VendorAuditYaml = + $$""" + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + {{MinimalProviders}} + audit: { kind: test } + entries: + main: + agent: only + """; + + [Fact] + public async Task TheDefaultAuditSink_ReachesTheTurnLoopAndTheChainVerifies() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // The queue is what keeps the append off the turn, so the rows land on a thread of their own + // and a reader that wants them now asks for them now. + await Queue(provider).FlushAsync(TestContext.Current.CancellationToken); + + IReadOnlyList events = Sink(provider).EventsOf("conversation-1"); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], + events.Select(item => item.Kind).ToArray()); + Assert.All(events, AuditEventVocabulary.Validate); + } + + [Fact] + public async Task ADocumentThatNamesNoAuditProvider_StillOpensTheMemorySink() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); + + // The turn loop produces the events of D23 whatever a document says, so the seam that receives + // them has a working default rather than a null. That is what lets every reading of a conversation be + // unconditional, and what lets a first run and a test work with no database. + Assert.NotNull(provider.GetService()); + _ = Assert.IsType(provider.GetRequiredService().Store); + } + + [Fact] + public async Task ADocumentThatNamesTheMemoryKind_OpensTheSameSinkAsNamingNothing() + { + using StartedHost provider = await BuildAsync(MemoryAuditYaml); + + // memory is this library's own name and it needs no registered vendor, so writing it says out + // loud what leaving the block out does quietly. The startup warning is the difference. + _ = Assert.IsType(provider.GetRequiredService().Store); + } + + [Fact] + public async Task AnAuditVendorTheDocumentNames_IsTheStoreBehindTheQueue() + { + RecordingAuditSink store = new(); + using StartedHost provider = await BuildAsync( + VendorAuditYaml, + options => options.UseAuditSinks(new TestAuditSinkAdapter(store))); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + await Queue(provider).FlushAsync(TestContext.Current.CancellationToken); + + // The host lists its vendors once and providers.audit.kind picks one, exactly as the five + // seams beside it. Nothing but the document decides which store the chain lands in. + Assert.Same(store, provider.GetRequiredService().Store); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], + store.Events.Select(item => item.Kind).ToArray()); + } + + [Fact] + public async Task AnAuditKindThisHostDoesNotRegister_FailsTheStart() + { + // A document that asked for something this host cannot give fails while the host starts, and + // never on a conversation. The message names the kind, exactly as every other vendor seam. + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(VendorAuditYaml)); + + Assert.Contains("test", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task TheAuditSink_IsWrappedInTheQueueThatKeepsItOffTheTurn() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); + + // Section 7 puts a durable insert at 13 ms p50 against 91 nanoseconds to enqueue, and the rule + // that follows is applied once, here, to whatever the document opened. So an adapter that + // blocks on its database is a correct adapter, and no adapter carries a queue of its own. + _ = Assert.IsType(provider.GetRequiredService()); + } + + /// Reads back the queue the composition root put in front of the document's store. + private static QueuedAuditSink Queue(IServiceProvider provider) + { + return Assert.IsType(provider.GetRequiredService()); + } + + /// Reads back the store itself, which is registered under its own concrete type. + /// + /// The document builds the store now, not the host, so this is how a test that wants the events + /// of one conversation reaches the thing that holds them. Resolving gives the + /// queue instead, because that is the only registration that honours the port's contract. + /// + private static InMemoryAuditSink Sink(IServiceProvider provider) + { + return Assert.IsType(provider.GetRequiredService().Store); + } + + // ------------------------------------------------------------------------------------------- + // The transcript store: named by providers.conversations, and never absent. + // ------------------------------------------------------------------------------------------- + + // The same agent, served by a conversation-store vendor the host registers itself. + private const string VendorTranscriptYaml = + $$""" + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + {{MinimalProviders}} + conversations: { kind: test } + entries: + main: + agent: only + """; + + // The same agent, served by a knowledge vendor the host registers itself. + private const string VendorKnowledgeYaml = + $$""" + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + {{MinimalProviders}} + knowledge: { kind: test, collection: manuals, fields: { body: body } } + entries: + main: + agent: only + """; + + // The conversation store opens at step 4c and the moderation vendor is built at step 4c, so a + // document that names both puts a failure strictly after an open. Nothing else in the boot has + // that shape. + private const string ConversationStoreThenModerationFailureYaml = + $$""" + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + {{MinimalProviders}} + conversations: { kind: test } + moderation: { kind: test } + entries: + main: + agent: only + """; + + [Fact] + public async Task ADocumentThatNamesNoConversationStoreProvider_StillOpensTheMemoryStore() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); + + // The turn loop writes the words of every conversation whatever a document says, so this seam has a + // working default rather than a null, and a first run needs no database. + Assert.NotNull(provider.GetService()); + _ = Assert.IsType(provider.GetRequiredService().Store); + } + + [Fact] + public async Task AConversationStoreVendorTheDocumentNames_IsTheStoreTheTurnWritesTo() + { + RecordingConversationStore store = new(); + using StartedHost provider = await BuildAsync( + VendorTranscriptYaml, + options => options.UseConversationStores(new TestConversationStoreAdapter(store))); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + await session.FlushTranscriptAsync(); + + // The host lists its vendors once and providers.conversations.kind picks one. Nothing but the + // document decides where the words of a conversation land. + Assert.Same(store, provider.GetRequiredService().Store); + Assert.Equal(["user", "assistant"], store.Roles); + } + + [Fact] + public async Task AConversationStoreKindThisHostDoesNotRegister_FailsTheStart() + { + // A document that asked for something this host cannot give fails while the host starts, and + // never on a conversation. + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(VendorTranscriptYaml)); + + Assert.Contains("test", failure.Message, StringComparison.Ordinal); + } + + /// A conversation-store vendor that hands over the store the test holds. + private sealed class TestConversationStoreAdapter(RecordingConversationStore store) : IConversationStoreAdapter + { + public string Kind => "test"; + + public ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(store); + } + } + + /// A store 1 backing that keeps the role of every row it accepted. + /// + /// Keeps only , with no conversationId or ordinal, so it cannot rebuild a + /// to answer a read or an erase truthfully. and + /// report empty and 0 even after has recorded + /// rows — a test that needs either should use a different double. + /// + private sealed class RecordingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()), IAsyncDisposable + { + private readonly Lock _gate = new(); + private readonly List _roles = []; + + /// Gets whether this store was closed. + public bool Closed { get; private set; } + + /// Gets the role of each row this store accepted, in the order it arrived. + public IReadOnlyList Roles + { + get + { + lock (_gate) + { + return [.. _roles]; + } + } + } + + public override ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + lock (_gate) + { + _roles.AddRange(messages.Select(message => message.Content.Role.Value)); + } + + IReadOnlyList rows = [.. messages.Select( + (message, index) => new ConversationMessage(conversationId, index, message.TurnIndex ?? 0, message.Content, message.MessageId))]; + return ValueTask.FromResult(rows); + } + + public override ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + return ValueTask.CompletedTask; + } + + public override ValueTask EraseAsync(string conversationId, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(0); + } + + public ValueTask DisposeAsync() + { + Closed = true; + return ValueTask.CompletedTask; + } + } + + /// A knowledge vendor that hands back one port and keeps a reference to it. + private sealed class DisposeTrackingKnowledgeAdapter : IKnowledgeStoreAdapter + { + public string Kind => "test"; + + public bool CanServeSearch => true; + + public bool CanScope => true; + + /// Gets the port the last build returned, or before one built. + public DisposeTrackingKnowledgePort? Built { get; private set; } + + public ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) + { + Built = new DisposeTrackingKnowledgePort(); + return ValueTask.FromResult(Built); + } + } + + /// A knowledge port that answers with nothing and tracks whether it was closed. + /// A knowledge port that also reads whole cards by an exact facet value. + private sealed class FacetCapablePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + + public ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + } + + private sealed class DisposeTrackingKnowledgePort : IKnowledgeRetrievalPort, IDisposable + { + /// Gets whether this port was closed. + public bool Closed { get; private set; } + + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + + public void Dispose() + { + Closed = true; + } + } + + [Fact] + public async Task NoLoggerAndNoAuditVendor_StillRunsATurn() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create(); + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + Assert.Equal("hello", turn.ReplyText); + } + + // ------------------------------------------------------------------------------------------- + // The host's own observers: the socket behind IConversationObserver. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task AHostObserver_ReadsTheFactsOfATurn() + { + RecordingConversationObserver first = new(); + RecordingConversationObserver second = new(); + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseObservers(first, second)); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // The port is public, so a host writes one of these and binds it. Every observer of a conversation + // reads the same facts, and the library's own three are neither replaced nor bypassed. + Assert.Equal([ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted], first.Seen); + Assert.Equal([ConversationEventKind.ConversationStarted, ConversationEventKind.TurnCompleted], second.Seen); + } + + [Fact] + public async Task AHostObserverThatThrows_CostsNeitherTheTurnNorTheChain() + { + using StartedHost provider = await BuildAsync( + OneAgentYaml, + options => options.UseObservers(new ThrowingConversationObserver())); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + TurnResult turn = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // An observer records the conversation and is never a part of it. That holds for the host's own, and + // it holds for the readings registered beside it: a broken host observer does not cost the + // chain of D23 a single row. + Assert.Equal("hello", turn.ReplyText); + + await Queue(provider).FlushAsync(TestContext.Current.CancellationToken); + + IReadOnlyList events = Sink(provider).EventsOf("conversation-1"); + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.TurnCompleted], + events.Select(item => item.Kind).ToArray()); + Assert.All(events, AuditEventVocabulary.Validate); + } + + [Fact] + public async Task UseObserversTwice_KeepsBothRegistrations() + { + RecordingConversationObserver first = new(); + RecordingConversationObserver second = new(); + using StartedHost provider = await BuildAsync( + OneAgentYaml, + options => options.UseObservers(first).UseObservers(second)); + + ConversationSession session = provider.GetRequiredService().ForFactory("main").Create("conversation-1"); + _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); + + // The seam adds rather than replaces, so a host composes its readings across whatever code + // configures the container. + Assert.NotEmpty(first.Seen); + Assert.NotEmpty(second.Seen); + } + + // ------------------------------------------------------------------------------------------- + // What it refuses. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task ABadDocument_FailsTheStartAndNamesTheFault() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => BuildAsync(BrokenYaml)); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); + Assert.Equal("/entries/main/policy/stages/0/to/0/stage", error.Pointer); + Assert.Contains("'nowhere' is not declared", error.Message, StringComparison.Ordinal); + } + + /// + /// The reference pass runs after discovery, against what the tool registry actually serves. A + /// state slot's from: naming a tool nothing serves — not declared, and no mcp: + /// server offers it either — still stops the boot rather than leaving the slot silently unfilled. + /// + [Fact] + public async Task AnUndeclaredToolInAStateSlot_FailsTheStartAndNamesTheTool() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => BuildAsync(UndeclaredToolYaml)); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); + Assert.Equal("/state/orderStatus/from", error.Pointer); + Assert.Contains("lookup_order", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task AnAgentToolReferencingAnIdNothingServes_FailsTheStartNamingTheAgent() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => BuildAsync(UndeclaredAgentToolYaml)); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); + Assert.Equal("/agents/items/0/tools/0", error.Pointer); + Assert.Contains("no_such_tool", error.Message, StringComparison.Ordinal); + } + + /// + /// A source's own discovery can succeed while the boot still fails later: here, an agent's + /// tools: names an id nothing serves, so ValidateToolReferences throws after + /// already returned. AgentCoreBoot tracked + /// the source as it was built, before any discovery ran, so the failed start closes it however + /// far the boot had got. + /// + [Fact] + public async Task AToolReferenceFailureAfterDiscoverySucceeds_StillDisposesTheSource() + { + DisposeTrackingToolSource source = new(); + + _ = await Assert.ThrowsAsync(() => BuildAsync( + UndeclaredAgentToolYaml, + options => options.AddToolSource(_ => source))); + + Assert.True(source.Disposed); + } + + /// + /// The conversation store is opened at step 4c, and the moderation vendor is built after it. A + /// document that names a moderation kind this host does not register therefore fails with the + /// store already open, and nothing between the two steps has taken ownership of it. + /// + [Fact] + public async Task AFailureAfterTheConversationStoreOpens_StillClosesTheStore() + { + RecordingConversationStore store = new(); + + _ = await Assert.ThrowsAsync(() => BuildAsync( + ConversationStoreThenModerationFailureYaml, + options => options + .UseConversationStores(new TestConversationStoreAdapter(store)) + .UseModeration(new FakeModerationAdapter("other", new AlwaysFlagsEvaluator())))); + + Assert.True(store.Closed); + } + + /// + /// The id collision between a discovered tool and a declared kind: agent tool is only + /// found once every source has answered, so the source that served the colliding id is open by + /// then. It must not be left running. + /// + [Fact] + public async Task AnIdCollisionFoundAfterDiscovery_StillClosesTheSource() + { + DisposeTrackingToolSource source = new("shared_id"); + + _ = await Assert.ThrowsAsync(() => BuildAsync( + CollidingAgentToolYaml, + options => options.AddToolSource(_ => source))); + + Assert.True(source.Disposed); + } + + /// + /// An id no tools: entry names, served only by a discovering source, still satisfies an + /// agent's reference through + /// end to end, public API only. An mcp: server's tools work exactly this way: decision 15 + /// requires the reference pass to resolve against what got discovered, not just what got declared. + /// + [Fact] + public async Task ADiscoveredOnlyTool_SatisfiesAnAgentsReferenceThroughTheRealBoot() + { + using StartedHost provider = await BuildAsync( + DiscoveredOnlyToolYaml, + options => options.AddToolSource(_ => new DiscoveredOnlyToolSource("discovered_only"))); + + Assert.NotNull(provider.GetRequiredService>()["main"]); + Assert.True(provider.GetRequiredService().Contains("discovered_only")); + } + + /// + /// carves + /// out of its own "every declaration is served" rule, because that kind reaches no source — the + /// compile table builds it once the agent it names has compiled. The reference pass in the + /// composition root has to carve the same kind out of its own served-ids set for the same reason, + /// or a document exactly like this one — the shape section 8.1 calls agent-as-tool — fails to + /// boot even though it declares nothing wrong. + /// + [Fact] + public async Task ADelegatingAgentTool_BootsBecauseKindAgentReachesNoSource() + { + using StartedHost provider = await BuildAsync(DelegatingAgentToolYaml); + + Assert.NotNull(provider.GetRequiredService>()["main"]); + } + + /// + /// Decision 15's whole justification: a YAML typo must never cost a round trip to an MCP server. + /// This document carries both a structural defect and an mcp: server whose command does + /// not exist, so the two possible orderings are observably different: structure-first reports + /// the policy fault and never touches the server; discovery-first would instead report that the + /// server could not be reached, because Process.Start on a missing executable fails + /// synchronously, well before any structural error would ever be found. The error alone only + /// infers the order; observes it directly by recording whether + /// ProvideAsync was ever called on any source at all — structure-first means + /// never runs, so nothing + /// is ever asked, not even a source that serves nothing. + /// + [Fact] + public async Task AddAgentCore_TheStructuralFaultSurfaces_BeforeMcpIsEverAsked() + { + bool asked = false; + + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => BuildAsync( + StructuralFaultPlusUnreachableMcpYaml, + options => + { + // Registered before McpToolSource, so this is asked first if discovery runs at all — + // a true observer of whether ToolRegistryBuilder.BuildAsync began, not just of + // whether the MCP source in particular got asked. + _ = options.AddToolSource(_ => new SpyToolSource(() => asked = true)); + _ = options.AddToolSource(startup => new McpToolSource(startup.Secrets)); + })); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); + Assert.Equal("/entries/main/policy/stages/0/to/0/stage", error.Pointer); + Assert.Contains("'nowhere' is not declared", error.Message, StringComparison.Ordinal); + + // Distinguishes the orders directly: an MCP connection failure would name the server id. + Assert.DoesNotContain("bogus-server", failure.Message, StringComparison.Ordinal); + + Assert.False(asked); + } + + [Fact] + public async Task ADocumentThatDoesNotParse_FailsTheStart() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => StartBareAsync(options => + { + options.ConfigurationPath = "no-such-extension.txt"; + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + })); + + Assert.Equal(ConfigurationCheck.Syntax, failure.Check); + } + + [Fact] + public async Task NoDocumentAtAll_FailsTheStartAndSaysWhatToSet() + { + InvalidOperationException failure = await Assert.ThrowsAsync( + () => StartBareAsync( + options => options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))))); + + Assert.Contains("names no document", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task TwoDocuments_FailTheStart() + { + InvalidOperationException failure = await Assert.ThrowsAsync( + () => StartBareAsync(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(OneAgentYaml); + options.ConfigurationPath = "config/example.yaml"; + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + })); + + Assert.Contains("names two documents", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task NoChatClientAdapter_FailsTheStart() + { + InvalidOperationException failure = await Assert.ThrowsAsync( + () => StartBareAsync(options => options.Configuration = ConfigurationLoader.LoadYaml(OneAgentYaml))); + + Assert.Contains("UseChatClients", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task AddAgentCore_AnAgentWithSkills_Boots() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + + const string yaml = """ + apiVersion: agentcore/v1 + agents: + items: + - { id: only, instructions: "I answer everything" } + entries: + main: + agent: only + """; + + using StartedHost host = await BuildAsync(yaml, options => options.UseSkills(folder.Root)); + + Assert.NotNull(host); + } + + [Fact] + public async Task AddAgentCore_AnAgentNamingASkillTheFolderDoesNotServe_FailsAtBoot() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + + const string yaml = """ + apiVersion: agentcore/v1 + agents: items: - { id: support, skills: [warranty-return] } entries: @@ -1811,18 +1830,18 @@ public async Task AddAgentCore_AnAgentNamingASkillTheFolderDoesNotServe_FailsAtB agent: support """; - var failure = await Assert.ThrowsAsync( - () => BuildAsync(yaml, options => options.UseSkills(folder.Root))); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(yaml, options => options.UseSkills(folder.Root))); - Assert.Contains("warranty-return", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("warranty-return", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task AddAgentCore_ClosesTheSkillsSourceWhenTheHostShutsDown() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); + [Fact] + public async Task AddAgentCore_ClosesTheSkillsSourceWhenTheHostShutsDown() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); - const string yaml = """ + const string yaml = """ apiVersion: agentcore/v1 agents: items: @@ -1832,25 +1851,25 @@ public async Task AddAgentCore_ClosesTheSkillsSourceWhenTheHostShutsDown() agent: support """; - TrackingSkillsSource tracked = new(folder.Root); + TrackingSkillsSource tracked = new(folder.Root); - var host = await BuildAsync(yaml, options => options.UseSkills(tracked)); - host.Dispose(); + StartedHost host = await BuildAsync(yaml, options => options.UseSkills(tracked)); + host.Dispose(); - Assert.True(tracked.Disposed); - } + Assert.True(tracked.Disposed); + } - /// - /// The source has to be open for the document to be checked against the names it serves, so a - /// skills: entry nothing serves fails with it open. AgentCoreBoot takes ownership - /// before running that check, and this is what holds the two lines in that order. - /// - [Fact] - public async Task ASkillReferenceFailure_StillClosesTheSkillsSource() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); + /// + /// The source has to be open for the document to be checked against the names it serves, so a + /// skills: entry nothing serves fails with it open. AgentCoreBoot takes ownership + /// before running that check, and this is what holds the two lines in that order. + /// + [Fact] + public async Task ASkillReferenceFailure_StillClosesTheSkillsSource() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); - const string yaml = """ + const string yaml = """ apiVersion: agentcore/v1 agents: items: @@ -1860,25 +1879,25 @@ public async Task ASkillReferenceFailure_StillClosesTheSkillsSource() agent: support """; - TrackingSkillsSource tracked = new(folder.Root); + TrackingSkillsSource tracked = new(folder.Root); - await Assert.ThrowsAsync( - () => BuildAsync(yaml, options => options.UseSkills(tracked))); + _ = await Assert.ThrowsAsync( + () => BuildAsync(yaml, options => options.UseSkills(tracked))); - Assert.True(tracked.Disposed); - } + Assert.True(tracked.Disposed); + } - /// - /// The reserved-tool-id check reads only the document, so it runs outside the null check and - /// would sit happily above Track — where its refusal would strand an open source. This - /// is what holds it below. - /// - [Fact] - public async Task AReservedSkillToolIdFailure_StillClosesTheSkillsSource() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); + /// + /// The reserved-tool-id check reads only the document, so it runs outside the null check and + /// would sit happily above Track — where its refusal would strand an open source. This + /// is what holds it below. + /// + [Fact] + public async Task AReservedSkillToolIdFailure_StillClosesTheSkillsSource() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); - const string yaml = """ + const string yaml = """ apiVersion: agentcore/v1 tools: - id: load_skill @@ -1897,329 +1916,351 @@ public async Task AReservedSkillToolIdFailure_StillClosesTheSkillsSource() agent: support """; - TrackingSkillsSource tracked = new(folder.Root); - - var failure = await Assert.ThrowsAsync( - () => BuildAsync( - yaml, - options => - { - options.UseSkills(tracked); - options.Bind("CreateCase", (_, _) => ValueTask.FromResult(new JsonObject())); - })); + TrackingSkillsSource tracked = new(folder.Root); - Assert.Contains("reserved", failure.Message, StringComparison.Ordinal); - Assert.True(tracked.Disposed); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync( + yaml, + options => + { + _ = options.UseSkills(tracked); + _ = options.Bind("CreateCase", (_, _) => ValueTask.FromResult(new JsonObject())); + })); - // ------------------------------------------------------------------------------------------- - // Helpers. - // ------------------------------------------------------------------------------------------- - /// Composes the guarded graph over one offline model for each node. - /// The provider a test resolves from. - private static Task BuildGuardedGraphAsync() - { - RoutingChatClientFactory models = new(new FragmentingChatClient("ROUTED")); - models.Route("human", new FragmentingChatClient("ESCALATED")); - models.Route("bot", new FragmentingChatClient("HANDLED")); + Assert.Contains("reserved", failure.Message, StringComparison.Ordinal); + Assert.True(tracked.Disposed); + } - return BuildAsync(GuardedGraphYaml, options => options.UseChatClients(_ => models)); - } + // ------------------------------------------------------------------------------------------- + // Helpers. + // ------------------------------------------------------------------------------------------- + /// Composes the guarded graph over one offline model for each node. + /// The provider a test resolves from. + private static Task BuildGuardedGraphAsync() + { + RoutingChatClientFactory models = new(new FragmentingChatClient("ROUTED")); + _ = models.Route("human", new FragmentingChatClient("ESCALATED")); + _ = models.Route("bot", new FragmentingChatClient("HANDLED")); - private static async Task<(IHost Host, FlushRecordingTelemetryAdapter Adapter)> BuildTelemetryHostAsync() - { - FlushRecordingTelemetryAdapter adapter = new("test"); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - ConfigureServices( - builder.Services, - TelemetryYaml, - options => options.UseTelemetry(adapter)); - - return (builder.Build(), adapter); - } + return BuildAsync(GuardedGraphYaml, options => options.UseChatClients(_ => models)); + } - private static async Task<(IHost Host, ClosingAuditSink Store)> BuildAuditHostAsync() - { - ClosingAuditSink store = new(); - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - ConfigureServices( - builder.Services, - VendorAuditYaml, - options => options.UseAuditSinks(new TestAuditSinkAdapter(store))); - - return (builder.Build(), store); - } + private static async Task<(IHost Host, FlushRecordingTelemetryAdapter Adapter)> BuildTelemetryHostAsync() + { + FlushRecordingTelemetryAdapter adapter = new("test"); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ConfigureServices( + builder.Services, + TelemetryYaml, + options => options.UseTelemetry(adapter)); + + return (builder.Build(), adapter); + } - /// One well-formed event, which is all a drain has to carry. - /// Seconds past the epoch the event occurred at, so callers can order rows. - /// The event. - private static AuditEvent AuditRow(long secondsPastEpoch) => new() - { - ConversationId = "conversation-1", - EventId = Guid.CreateVersion7(), - Kind = AuditEventKind.TurnCompleted, - OccurredAt = DateTimeOffset.UnixEpoch.AddSeconds(secondsPastEpoch), - }; - - /// An adapter that starts nothing and hands back a session that records its flush. - private sealed class FlushRecordingTelemetryAdapter(string kind) : ITelemetryAdapter - { - public string Kind => kind; + private static async Task<(IHost Host, ClosingAuditSink Store)> BuildAuditHostAsync() + { + ClosingAuditSink store = new(); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ConfigureServices( + builder.Services, + VendorAuditYaml, + options => options.UseAuditSinks(new TestAuditSinkAdapter(store))); + + return (builder.Build(), store); + } - public FlushRecordingSession Session { get; } = new(); + /// One well-formed event, which is all a drain has to carry. + /// Seconds past the epoch the event occurred at, so callers can order rows. + /// The event. + private static AuditEvent AuditRow(long secondsPastEpoch) + { + return new() + { + ConversationId = "conversation-1", + EventId = Guid.CreateVersion7(), + Kind = AuditEventKind.TurnCompleted, + OccurredAt = DateTimeOffset.UnixEpoch.AddSeconds(secondsPastEpoch), + }; + } - public ValueTask StartAsync( - TelemetryProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(Session); - } + /// An adapter that starts nothing and hands back a session that records its flush. + private sealed class FlushRecordingTelemetryAdapter(string kind) : ITelemetryAdapter + { + public string Kind => kind; - /// A session that exports nowhere and counts how many times it was drained. - private sealed class FlushRecordingSession : ITelemetrySession - { - public ILoggerProvider? Logs => null; + public FlushRecordingSession Session { get; } = new(); - public int Flushes { get; private set; } + public ValueTask StartAsync( + TelemetryProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(Session); + } + } - public ValueTask DisposeAsync() + /// A session that exports nowhere and counts how many times it was drained. + private sealed class FlushRecordingSession : ITelemetrySession { - Flushes++; - return ValueTask.CompletedTask; - } - } + public ILoggerProvider? Logs => null; - /// An observer a host binds, which keeps every fact it was offered, in order. - private sealed class RecordingConversationObserver : IConversationObserver - { - private readonly Lock _gate = new(); - private readonly List _seen = []; + public int Flushes { get; private set; } - /// Gets what this observer read, in the order the conversation produced it. - public IReadOnlyList Seen + public ValueTask DisposeAsync() + { + Flushes++; + return ValueTask.CompletedTask; + } + } + + /// An observer a host binds, which keeps every fact it was offered, in order. + private sealed class RecordingConversationObserver : IConversationObserver { - get + private readonly Lock _gate = new(); + private readonly List _seen = []; + + /// Gets what this observer read, in the order the conversation produced it. + public IReadOnlyList Seen + { + get + { + // A delivery may land on a thread of its own, so the reading is taken under the gate. + lock (_gate) + { + return [.. _seen]; + } + } + } + + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - // A delivery may land on a thread of its own, so the reading is taken under the gate. lock (_gate) { - return [.. _seen]; + _seen.Add(conversationEvent.Kind); } + + return ValueTask.CompletedTask; } } - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) + /// An observer that refuses every fact, so the isolation of the seam is observable. + private sealed class ThrowingConversationObserver : IConversationObserver { - lock (_gate) + public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) { - _seen.Add(conversationEvent.Kind); + throw new InvalidOperationException("the host's observer is broken"); } - - return ValueTask.CompletedTask; } - } - /// An observer that refuses every fact, so the isolation of the seam is observable. - private sealed class ThrowingConversationObserver : IConversationObserver - { - public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken) - => throw new InvalidOperationException("the host's observer is broken"); - } + /// A moderation vendor a test registers, which counts the times it was asked to build. + private sealed class FakeModerationAdapter(string kind, IEvaluator evaluator) : IModerationAdapter + { + public string Kind => kind; - /// A moderation vendor a test registers, which counts the times it was asked to build. - private sealed class FakeModerationAdapter(string kind, IEvaluator evaluator) : IModerationAdapter - { - public string Kind => kind; + /// Gets the number of times the composition root asked this vendor to build. + public int Builds { get; private set; } - /// Gets the number of times the composition root asked this vendor to build. - public int Builds { get; private set; } + public ValueTask CreateAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + Builds++; + return ValueTask.FromResult(evaluator); + } + } - public ValueTask CreateAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) + /// An audit vendor a test registers, which opens one store the test already holds. + private sealed class TestAuditSinkAdapter(IAuditSinkPort store) : IAuditSinkAdapter { - Builds++; - return ValueTask.FromResult(evaluator); - } - } + public string Kind => "test"; - /// An audit vendor a test registers, which opens one store the test already holds. - private sealed class TestAuditSinkAdapter(IAuditSinkPort store) : IAuditSinkAdapter - { - public string Kind => "test"; + public ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(store); + } + } - public ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(store); - } + /// An audit store that is slow to write and records what it held when it was closed. + /// + /// The delay is the whole test: a shutdown that does not wait for the queue returns long before + /// this store has been handed anything, so a lost row is a failed assertion rather than a race. + /// + private sealed class ClosingAuditSink : IAuditSinkPort, IAsyncDisposable + { + private static readonly TimeSpan WriteDelay = TimeSpan.FromMilliseconds(200); - /// An audit store that is slow to write and records what it held when it was closed. - /// - /// The delay is the whole test: a shutdown that does not wait for the queue returns long before - /// this store has been handed anything, so a lost row is a failed assertion rather than a race. - /// - private sealed class ClosingAuditSink : IAuditSinkPort, IAsyncDisposable - { - private static readonly TimeSpan WriteDelay = TimeSpan.FromMilliseconds(200); + private int _written; - private int _written; + /// Gets the number of events this store has written. + public int Written => Volatile.Read(ref _written); - /// Gets the number of events this store has written. - public int Written => Volatile.Read(ref _written); + /// Gets whether this store was closed. + public bool Closed { get; private set; } - /// Gets whether this store was closed. - public bool Closed { get; private set; } + /// Gets how many events this store had written by the time it was closed. + public int WrittenWhenClosed { get; private set; } - /// Gets how many events this store had written by the time it was closed. - public int WrittenWhenClosed { get; private set; } + public async ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) + { + await Task.Delay(WriteDelay, CancellationToken.None); + _ = Interlocked.Increment(ref _written); + } - public async ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) - { - await Task.Delay(WriteDelay, CancellationToken.None); - Interlocked.Increment(ref _written); + public ValueTask DisposeAsync() + { + Closed = true; + WrittenWhenClosed = Written; + return ValueTask.CompletedTask; + } } - public ValueTask DisposeAsync() + /// An audit store that keeps what it accepted, so what the document opened is observable. + /// + /// It is not , on purpose: the test has to tell the vendor the + /// document named apart from the built-in the document would have fallen back to. + /// + private sealed class RecordingAuditSink : IAuditSinkPort { - Closed = true; - WrittenWhenClosed = Written; - return ValueTask.CompletedTask; - } - } + private readonly Lock _gate = new(); + private readonly List _events = []; - /// An audit store that keeps what it accepted, so what the document opened is observable. - /// - /// It is not , on purpose: the test has to tell the vendor the - /// document named apart from the built-in the document would have fallen back to. - /// - private sealed class RecordingAuditSink : IAuditSinkPort - { - private readonly Lock _gate = new(); - private readonly List _events = []; + /// Gets the events this store accepted, in the order they arrived. + public IReadOnlyList Events + { + get + { + lock (_gate) + { + return [.. _events]; + } + } + } - /// Gets the events this store accepted, in the order they arrived. - public IReadOnlyList Events - { - get + public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) { lock (_gate) { - return [.. _events]; + _events.Add(auditEvent); } + + return ValueTask.CompletedTask; } } - public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default) + /// A moderation evaluator that flags every text, so the wiring is observable. + private sealed class AlwaysFlagsEvaluator : IEvaluator { - lock (_gate) + public IReadOnlyCollection EvaluationMetricNames => ["Content Safety"]; + + public ValueTask EvaluateAsync( + IEnumerable messages, + ChatResponse modelResponse, + ChatConfiguration? chatConfiguration = null, + IEnumerable? additionalContext = null, + CancellationToken cancellationToken = default) { - _events.Add(auditEvent); + BooleanMetric metric = new("Content Safety", value: false); + metric.AddOrUpdateContext(new ModerationVerdict(flagged: true, ["harassment"])); + return ValueTask.FromResult(new EvaluationResult(metric)); } - - return ValueTask.CompletedTask; } - } - /// A moderation evaluator that flags every text, so the wiring is observable. - private sealed class AlwaysFlagsEvaluator : IEvaluator - { - public IReadOnlyCollection EvaluationMetricNames => ["Content Safety"]; - - public ValueTask EvaluateAsync( - IEnumerable messages, - ChatResponse modelResponse, - ChatConfiguration? chatConfiguration = null, - IEnumerable? additionalContext = null, - CancellationToken cancellationToken = default) + /// Sessions a host registers in place of the default ones. + private sealed class CountingConversationSessions : IConversationSessions { - BooleanMetric metric = new("Content Safety", value: false); - metric.AddOrUpdateContext(new ModerationVerdict(flagged: true, ["harassment"])); - return ValueTask.FromResult(new EvaluationResult(metric)); - } - } - - /// Sessions a host registers in place of the default ones. - private sealed class CountingConversationSessions : IConversationSessions - { - public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } - public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) - => ValueTask.FromResult(null); + public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(null); + } - public ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) - => ValueTask.CompletedTask; - } + public ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) + { + return ValueTask.CompletedTask; + } + } - /// - /// A tool source that serves one id no document ever declares in tools:, standing in for - /// what an MCP server's discovery would supply. imposes no rule - /// that a served id be declared, so this alone is enough to prove the reference pass runs against - /// what got discovered. - /// - private sealed class DiscoveredOnlyToolSource(string id) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - [new ToolRegistration(id, "A tool discovered but never declared.", () => AIFunctionFactory.Create(() => "ok", id))]); - } + /// + /// A tool source that serves one id no document ever declares in tools:, standing in for + /// what an MCP server's discovery would supply. imposes no rule + /// that a served id be declared, so this alone is enough to prove the reference pass runs against + /// what got discovered. + /// + private sealed class DiscoveredOnlyToolSource(string id) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>( + [new ToolRegistration(id, "A tool discovered but never declared.", () => AIFunctionFactory.Create(() => "ok", id))]); + } + } - /// A tool source that serves nothing, and tells a test when it was asked to. - private sealed class SpyToolSource(Action onProvide) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) + /// A tool source that serves nothing, and tells a test when it was asked to. + private sealed class SpyToolSource(Action onProvide) : IToolSource { - onProvide(); - return ValueTask.FromResult>([]); + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + onProvide(); + return ValueTask.FromResult>([]); + } } - } - /// A tool source a host registers, which records whether it was ever closed. - /// One id to serve, or to serve nothing. - private sealed class DisposeTrackingToolSource(string? servedId = null) : IToolSource, IAsyncDisposable - { - /// Gets whether this source was disposed. - public bool Disposed { get; private set; } + /// A tool source a host registers, which records whether it was ever closed. + /// One id to serve, or to serve nothing. + private sealed class DisposeTrackingToolSource(string? servedId = null) : IToolSource, IAsyncDisposable + { + /// Gets whether this source was disposed. + public bool Disposed { get; private set; } - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - servedId is null - ? [] - : [new ToolRegistration(servedId, "A tool discovered under a claimed id.", () => AIFunctionFactory.Create(() => "ok", servedId))]); + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>( + servedId is null + ? [] + : [new ToolRegistration(servedId, "A tool discovered under a claimed id.", () => AIFunctionFactory.Create(() => "ok", servedId))]); + } - public ValueTask DisposeAsync() - { - Disposed = true; - return ValueTask.CompletedTask; + public ValueTask DisposeAsync() + { + Disposed = true; + return ValueTask.CompletedTask; + } } } -} - -/// A file source that records whether the boot tracker closed it. -internal sealed class TrackingSkillsSource(string path) : AgentSkillsSource -{ - private readonly AgentFileSkillsSource _inner = new(path); - public bool Disposed { get; private set; } + /// A file source that records whether the boot tracker closed it. + internal sealed class TrackingSkillsSource(string path) : AgentSkillsSource + { + private readonly AgentFileSkillsSource _inner = new(path); - public override Task> GetSkillsAsync( - AgentSkillsSourceContext context, CancellationToken cancellationToken = default) - => _inner.GetSkillsAsync(context, cancellationToken); + public bool Disposed { get; private set; } - protected override void Dispose(bool disposing) - { - if (disposing) + public override Task> GetSkillsAsync( + AgentSkillsSourceContext context, CancellationToken cancellationToken = default) { - Disposed = true; - _inner.Dispose(); + return _inner.GetSkillsAsync(context, cancellationToken); } - base.Dispose(disposing); + protected override void Dispose(bool disposing) + { + if (disposing) + { + Disposed = true; + _inner.Dispose(); + } + + base.Dispose(disposing); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AgentCoreHttpClientsTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AgentCoreHttpClientsTests.cs index a59026ac..fb2386b1 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AgentCoreHttpClientsTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AgentCoreHttpClientsTests.cs @@ -3,170 +3,171 @@ using AgentCore.AspNetCore.Tests.Fakes; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// The one outbound HTTP pipeline every adapter of this host sends on. -/// -/// -/// The pipeline owns what no vendor should repeat: the connection lifetime, the deadline, and the -/// retry. A vendor adapter owns its base address, its credential, and its wire format, and nothing -/// else. -/// -public sealed class AgentCoreHttpClientsTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - private const string Name = "agentcore.test"; - - private static CancellationToken Token => TestContext.Current.CancellationToken; - - private static Uri Endpoint => new("https://endpoint.test/answer", UriKind.Absolute); - - [Fact] - public async Task ItRetriesAServerFailureAndAnswersFromTheRetry() + /// + /// The one outbound HTTP pipeline every adapter of this host sends on. + /// + /// + /// The pipeline owns what no vendor should repeat: the connection lifetime, the deadline, and the + /// retry. A vendor adapter owns its base address, its credential, and its wire format, and nothing + /// else. + /// + public sealed class AgentCoreHttpClientsTests { - using ScriptedHttpMessageHandler endpoint = new( - HttpStatusCode.ServiceUnavailable, - HttpStatusCode.ServiceUnavailable, - HttpStatusCode.OK); - using AgentCoreHttpClients clients = new(endpoint); + private const string Name = "agentcore.test"; - using var response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); + private static CancellationToken Token => TestContext.Current.CancellationToken; - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - Assert.Equal(3, endpoint.Attempts); - } + private static Uri Endpoint => new("https://endpoint.test/answer", UriKind.Absolute); - [Fact] - public async Task ItRetriesARateLimitAnswer() - { - using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.TooManyRequests, HttpStatusCode.OK); - using AgentCoreHttpClients clients = new(endpoint); + [Fact] + public async Task ItRetriesAServerFailureAndAnswersFromTheRetry() + { + using ScriptedHttpMessageHandler endpoint = new( + HttpStatusCode.ServiceUnavailable, + HttpStatusCode.ServiceUnavailable, + HttpStatusCode.OK); + using AgentCoreHttpClients clients = new(endpoint); - using var response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); + using HttpResponseMessage response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - Assert.Equal(2, endpoint.Attempts); - } + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + Assert.Equal(3, endpoint.Attempts); + } - /// - /// A POST that fails is not retried, because a kind: http tool that POSTs may have already - /// fired its side effect, and repeating the attempt would fire it again. - /// - [Fact] - public async Task AFailedPostIsSentOnlyOnce() - { - using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.ServiceUnavailable); - using AgentCoreHttpClients clients = new(endpoint); + [Fact] + public async Task ItRetriesARateLimitAnswer() + { + using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.TooManyRequests, HttpStatusCode.OK); + using AgentCoreHttpClients clients = new(endpoint); - using var response = await clients.CreateClient(Name).PostAsync(Endpoint, content: null, Token); + using HttpResponseMessage response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); - Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode); - Assert.Equal(1, endpoint.Attempts); - } + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + Assert.Equal(2, endpoint.Attempts); + } - /// A GET is idempotent, so a server failure still gets retried. - [Fact] - public async Task AFailedGetIsStillRetried() - { - using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.ServiceUnavailable, HttpStatusCode.OK); - using AgentCoreHttpClients clients = new(endpoint); + /// + /// A POST that fails is not retried, because a kind: http tool that POSTs may have already + /// fired its side effect, and repeating the attempt would fire it again. + /// + [Fact] + public async Task AFailedPostIsSentOnlyOnce() + { + using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.ServiceUnavailable); + using AgentCoreHttpClients clients = new(endpoint); - using var response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); + using HttpResponseMessage response = await clients.CreateClient(Name).PostAsync(Endpoint, content: null, Token); - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - Assert.Equal(2, endpoint.Attempts); - } + Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode); + Assert.Equal(1, endpoint.Attempts); + } - [Fact] - public async Task ItSendsAnAnswerTheEndpointMeantStraightBack() - { - using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.BadRequest); - using AgentCoreHttpClients clients = new(endpoint); + /// A GET is idempotent, so a server failure still gets retried. + [Fact] + public async Task AFailedGetIsStillRetried() + { + using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.ServiceUnavailable, HttpStatusCode.OK); + using AgentCoreHttpClients clients = new(endpoint); - using var response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); + using HttpResponseMessage response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); - // A refusal is the answer. Repeating it costs a turn and changes nothing. - Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); - Assert.Equal(1, endpoint.Attempts); - } + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + Assert.Equal(2, endpoint.Attempts); + } - [Fact] - public void EveryClientCarriesTheDeadlineOfThisPipeline() - { - using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.OK); - using AgentCoreHttpClients clients = new(endpoint); + [Fact] + public async Task ItSendsAnAnswerTheEndpointMeantStraightBack() + { + using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.BadRequest); + using AgentCoreHttpClients clients = new(endpoint); - // Any name is served without being registered first, so a vendor that names a new client - // must still get the deadline rather than whatever the factory would hand out. - Assert.Equal(AgentCoreHttpClients.RequestDeadline, clients.CreateClient(Name).Timeout); - Assert.NotEqual(Timeout.InfiniteTimeSpan, AgentCoreHttpClients.RequestDeadline); - } + using HttpResponseMessage response = await clients.CreateClient(Name).GetAsync(Endpoint, Token); - /// - /// A rate limit that names its own wait wins over the backoff of this pipeline. - /// - /// - /// Guessing shorter than the endpoint asked for gets the next attempt refused as well, and - /// guessing longer holds the conversation for no reason. - /// - [Fact] - public void ItWaitsTheRetryAfterAnEndpointAsksFor() - { - using HttpResponseMessage asking = new(HttpStatusCode.TooManyRequests); - asking.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue(TimeSpan.FromSeconds(7)); + // A refusal is the answer. Repeating it costs a turn and changes nothing. + Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); + Assert.Equal(1, endpoint.Attempts); + } - Assert.Equal(TimeSpan.FromSeconds(7), AgentCoreHttpClients.RetryAfter(asking)); - } + [Fact] + public void EveryClientCarriesTheDeadlineOfThisPipeline() + { + using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.OK); + using AgentCoreHttpClients clients = new(endpoint); - [Fact] - public void ItReadsARetryAfterWrittenAsADate() - { - using HttpResponseMessage asking = new(HttpStatusCode.ServiceUnavailable); - asking.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue( - DateTimeOffset.UtcNow.AddMinutes(1)); + // Any name is served without being registered first, so a vendor that names a new client + // must still get the deadline rather than whatever the factory would hand out. + Assert.Equal(AgentCoreHttpClients.RequestDeadline, clients.CreateClient(Name).Timeout); + Assert.NotEqual(Timeout.InfiniteTimeSpan, AgentCoreHttpClients.RequestDeadline); + } - var wait = AgentCoreHttpClients.RetryAfter(asking); + /// + /// A rate limit that names its own wait wins over the backoff of this pipeline. + /// + /// + /// Guessing shorter than the endpoint asked for gets the next attempt refused as well, and + /// guessing longer holds the conversation for no reason. + /// + [Fact] + public void ItWaitsTheRetryAfterAnEndpointAsksFor() + { + using HttpResponseMessage asking = new(HttpStatusCode.TooManyRequests); + asking.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue(TimeSpan.FromSeconds(7)); - Assert.NotNull(wait); - Assert.InRange(wait.Value, TimeSpan.FromSeconds(50), TimeSpan.FromSeconds(60)); - } + Assert.Equal(TimeSpan.FromSeconds(7), AgentCoreHttpClients.RetryAfter(asking)); + } - [Fact] - public void AnAnswerThatAsksForNoWaitLeavesTheBackoffOfThisPipelineInPlace() - { - using HttpResponseMessage silent = new(HttpStatusCode.ServiceUnavailable); + [Fact] + public void ItReadsARetryAfterWrittenAsADate() + { + using HttpResponseMessage asking = new(HttpStatusCode.ServiceUnavailable); + asking.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue( + DateTimeOffset.UtcNow.AddMinutes(1)); - // Null is how a delay generator says "use the strategy delay". - Assert.Null(AgentCoreHttpClients.RetryAfter(silent)); - Assert.Null(AgentCoreHttpClients.RetryAfter(null)); - } + TimeSpan? wait = AgentCoreHttpClients.RetryAfter(asking); - [Fact] - public void ADateThatHasAlreadyPassedWaitsNothingExtra() - { - using HttpResponseMessage stale = new(HttpStatusCode.ServiceUnavailable); - stale.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue( - DateTimeOffset.UtcNow.AddMinutes(-1)); + _ = Assert.NotNull(wait); + Assert.InRange(wait.Value, TimeSpan.FromSeconds(50), TimeSpan.FromSeconds(60)); + } - Assert.Null(AgentCoreHttpClients.RetryAfter(stale)); - } + [Fact] + public void AnAnswerThatAsksForNoWaitLeavesTheBackoffOfThisPipelineInPlace() + { + using HttpResponseMessage silent = new(HttpStatusCode.ServiceUnavailable); - [Fact] - public async Task TheHandlerTheHostOwnsIsNotDisposedWithThePipeline() - { - using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.OK); + // Null is how a delay generator says "use the strategy delay". + Assert.Null(AgentCoreHttpClients.RetryAfter(silent)); + Assert.Null(AgentCoreHttpClients.RetryAfter(null)); + } - using (AgentCoreHttpClients clients = new(endpoint)) + [Fact] + public void ADateThatHasAlreadyPassedWaitsNothingExtra() { - using var first = await clients.CreateClient(Name).GetAsync(Endpoint, Token); - Assert.Equal(HttpStatusCode.OK, first.StatusCode); + using HttpResponseMessage stale = new(HttpStatusCode.ServiceUnavailable); + stale.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue( + DateTimeOffset.UtcNow.AddMinutes(-1)); + + Assert.Null(AgentCoreHttpClients.RetryAfter(stale)); } - // The pipeline is closed, and the handler the host passed in still answers. - using HttpClient direct = new(endpoint, disposeHandler: false); - using var second = await direct.GetAsync(Endpoint, Token); + [Fact] + public async Task TheHandlerTheHostOwnsIsNotDisposedWithThePipeline() + { + using ScriptedHttpMessageHandler endpoint = new(HttpStatusCode.OK); - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - Assert.Equal(2, endpoint.Attempts); + using (AgentCoreHttpClients clients = new(endpoint)) + { + using HttpResponseMessage first = await clients.CreateClient(Name).GetAsync(Endpoint, Token); + Assert.Equal(HttpStatusCode.OK, first.StatusCode); + } + + // The pipeline is closed, and the handler the host passed in still answers. + using HttpClient direct = new(endpoint, disposeHandler: false); + using HttpResponseMessage second = await direct.GetAsync(Endpoint, Token); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.Equal(2, endpoint.Attempts); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AmbiguityStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AmbiguityStartupTests.cs index a5f4e3db..0f6ec737 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AmbiguityStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AmbiguityStartupTests.cs @@ -10,119 +10,125 @@ using Microsoft.Extensions.Options; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// The ambiguity: warning the validator raises, exercised through -/// so the plumbing that carries it to the log is what is -/// under test. -/// -public sealed class AmbiguityStartupTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - [Fact] - public async Task BootAsync_ASingleFacetAmbiguityDocument_LogsTheConfigurationWarningBelowTelemetry() + /// + /// The ambiguity: warning the validator raises, exercised through + /// so the plumbing that carries it to the log is what is + /// under test. + /// + public sealed class AmbiguityStartupTests { - // A warning EvaluateStructure raised (K33 here) must reach the log, through - // ConfigurationStartup.Load's returned Warnings and AgentCoreBoot's own logger. - RecordingLoggerFactory loggers = new(); - - AgentCoreOptions options = new() + [Fact] + public async Task BootAsync_ASingleFacetAmbiguityDocument_LogsTheConfigurationWarningBelowTelemetry() { - Configuration = SingleFacetDocument(), - LoggerFactory = loggers, - }; - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - options.UseKnowledgeStores(new TestKnowledgeAdapter()); + // A warning EvaluateStructure raised (K33 here) must reach the log, through + // ConfigurationStartup.Load's returned Warnings and AgentCoreBoot's own logger. + RecordingLoggerFactory loggers = new(); + + AgentCoreOptions options = new() + { + Configuration = SingleFacetDocument(), + LoggerFactory = loggers, + }; + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + _ = options.UseKnowledgeStores(new TestKnowledgeAdapter()); - await using var boot = new AgentCoreBoot(Options.Create(options), loggers); - await boot.BootAsync(TestContext.Current.CancellationToken); + await using AgentCoreBoot boot = new(Options.Create(options), loggers); + await boot.BootAsync(TestContext.Current.CancellationToken); - var warnings = loggers.Lines.Where(line => - line.Level == LogLevel.Warning - && line.Message.Contains("/providers/knowledge/ambiguity", StringComparison.Ordinal)) - .ToList(); + List warnings = [.. loggers.Lines.Where(line => + line.Level == LogLevel.Warning + && line.Message.Contains("/providers/knowledge/ambiguity", StringComparison.Ordinal))]; - Assert.Contains(warnings, line => line.Message.Contains("at most one", StringComparison.Ordinal)); - } + Assert.Contains(warnings, line => line.Message.Contains("at most one", StringComparison.Ordinal)); + } - private static AgentCoreConfiguration SingleFacetDocument() - => new() + private static AgentCoreConfiguration SingleFacetDocument() { - ApiVersion = "agentcore/v1", - Extractor = new ExtractorConfiguration { Model = new ModelReference { Ref = "fill" } }, - State = new Dictionary(StringComparer.Ordinal) + return new() { - ["machine"] = new StateSlotConfiguration + ApiVersion = "agentcore/v1", + Extractor = new ExtractorConfiguration { Model = new ModelReference { Ref = "fill" } }, + State = new Dictionary(StringComparer.Ordinal) { - Type = StateSlotType.String, - Writer = StateWriter.Extractor, - EnumValues = [JsonValue.Create("ct900")!, JsonValue.Create("ct1200")!], - }, - }, - Providers = new ProvidersConfiguration - { - Llm = [new LlmProviderConfiguration { Kind = "test", Model = "test", As = "fill" }], - Knowledge = new KnowledgeProviderConfiguration - { - Kind = "test", - Collection = "kb", - Fields = new KnowledgeFieldsConfiguration { Body = "body" }, - Scope = new KnowledgeScopeConfiguration + ["machine"] = new StateSlotConfiguration { - Template = "facets.{key}", - FromState = ["machine"], - Wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["machine"] }, + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [JsonValue.Create("ct900")!, JsonValue.Create("ct1200")!], }, - Ambiguity = new KnowledgeAmbiguityConfiguration(), }, - }, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration + Providers = new ProvidersConfiguration + { + Llm = [new LlmProviderConfiguration { Kind = "test", Model = "test", As = "fill" }], + Knowledge = new KnowledgeProviderConfiguration { - Id = "resolver", - Instructions = "I answer about one machine", - Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, + Kind = "test", + Collection = "kb", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + Scope = new KnowledgeScopeConfiguration + { + Template = "facets.{key}", + FromState = ["machine"], + Wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["machine"] }, + }, + Ambiguity = new KnowledgeAmbiguityConfiguration(), }, - ], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration + }, + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration + { + Id = "resolver", + Instructions = "I answer about one machine", + Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, + }, + ], + }, + Entries = new Dictionary { - Policy = new PolicyConfiguration + ["main"] = new EntryConfiguration { - Initial = "answering", - Stages = [new StageConfiguration { Id = "answering", Agent = "resolver", Terminal = true }], + Policy = new PolicyConfiguration + { + Initial = "answering", + Stages = [new StageConfiguration { Id = "answering", Agent = "resolver", Terminal = true }], + }, }, }, - }, - }; + }; + } - /// Answers providers.knowledge.kind: test with a port that finds nothing. - private sealed class TestKnowledgeAdapter : IKnowledgeStoreAdapter - { - public string Kind => "test"; + /// Answers providers.knowledge.kind: test with a port that finds nothing. + private sealed class TestKnowledgeAdapter : IKnowledgeStoreAdapter + { + public string Kind => "test"; - public bool CanServeSearch => true; + public bool CanServeSearch => true; - public bool CanScope => true; + public bool CanScope => true; - public ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(new EmptyPort()); - } + public ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(new EmptyPort()); + } + } - private sealed class EmptyPort : IKnowledgeRetrievalPort - { - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + private sealed class EmptyPort : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeLoggingThroughBootTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeLoggingThroughBootTests.cs index e9c97e12..1df81d49 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeLoggingThroughBootTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeLoggingThroughBootTests.cs @@ -10,106 +10,111 @@ using Microsoft.Extensions.Options; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// That the composition root's own logger factory reaches the provider a shipped host compiles. -/// -/// -/// -/// The knowledge provider's own facts hand a recording factory straight into -/// KnowledgeProviderFactory.Create, and every compile-table fact builds an -/// AgentCompilationContext without a Loggers at all. So one line — -/// CompilationStartup's Loggers = loggers — is what makes the whole observability fix -/// live in a real host, and deleting it left the entire suite green while a store outage went silent -/// again. That is the original defect restated, so it gets a fact of its own, taken through -/// AgentCoreBoot rather than through the compiler. -/// -/// -/// The assertion is on the ERROR row and not the debug one: it is the row that exists for an outage, -/// and it is the row a default production configuration is listening to. -/// -/// -public sealed class KnowledgeLoggingThroughBootTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - [Fact] - public async Task BootAsync_TheStoreIsDown_TheCompiledProviderWritesThroughTheHostsLoggerFactory() + /// + /// That the composition root's own logger factory reaches the provider a shipped host compiles. + /// + /// + /// + /// The knowledge provider's own facts hand a recording factory straight into + /// KnowledgeProviderFactory.Create, and every compile-table fact builds an + /// AgentCompilationContext without a Loggers at all. So one line — + /// CompilationStartup's Loggers = loggers — is what makes the whole observability fix + /// live in a real host, and deleting it left the entire suite green while a store outage went silent + /// again. That is the original defect restated, so it gets a fact of its own, taken through + /// AgentCoreBoot rather than through the compiler. + /// + /// + /// The assertion is on the ERROR row and not the debug one: it is the row that exists for an outage, + /// and it is the row a default production configuration is listening to. + /// + /// + public sealed class KnowledgeLoggingThroughBootTests { - RecordingLoggerFactory loggers = new(); - InvalidOperationException down = new("qdrant is down"); + [Fact] + public async Task BootAsync_TheStoreIsDown_TheCompiledProviderWritesThroughTheHostsLoggerFactory() + { + RecordingLoggerFactory loggers = new(); + InvalidOperationException down = new("qdrant is down"); - await using var boot = Boot(new ThrowingPort(down), loggers); - await boot.BootAsync(TestContext.Current.CancellationToken); + await using AgentCoreBoot boot = Boot(new ThrowingPort(down), loggers); + await boot.BootAsync(TestContext.Current.CancellationToken); - var provider = Assert.Single(Providers(boot.CompiledEntries["main"].Agents["resolver"]).OfType()); + KnowledgePrefetchProvider provider = Assert.Single(Providers(boot.CompiledEntries["main"].Agents["resolver"]).OfType()); #pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. - AIContextProvider.InvokingContext context = new( - boot.CompiledEntries["main"].Agents["resolver"], null, new AIContext()); + AIContextProvider.InvokingContext context = new( + boot.CompiledEntries["main"].Agents["resolver"], null, new AIContext()); #pragma warning restore MAAI001 - await provider.InvokingAsync(context, TestContext.Current.CancellationToken); + _ = await provider.InvokingAsync(context, TestContext.Current.CancellationToken); - var line = Assert.Single(loggers.Of(12)); - Assert.Equal("resolver", line.Field("Agent")); - Assert.Same(down, line.Exception); - } + CapturedLine line = Assert.Single(loggers.Of(12)); + Assert.Equal("resolver", line.Field("Agent")); + Assert.Same(down, line.Exception); + } - /// The document: one agent, one knowledge block, nothing else the boot must resolve. - private static AgentCoreConfiguration OneScopelessReader() - => new() + /// The document: one agent, one knowledge block, nothing else the boot must resolve. + private static AgentCoreConfiguration OneScopelessReader() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration + return new() { - Items = - [ - new AgentConfiguration - { - Id = "resolver", - Instructions = "I answer from the knowledge base", - Knowledge = new AgentKnowledgeConfiguration + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration { - Mode = KnowledgeMode.Prefetch, - Scoped = false, + Id = "resolver", + Instructions = "I answer from the knowledge base", + Knowledge = new AgentKnowledgeConfiguration + { + Mode = KnowledgeMode.Prefetch, + Scoped = false, + }, }, - }, - ], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration { Agent = "resolver" }, - }, - }; + ], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { Agent = "resolver" }, + }, + }; + } - private static AgentCoreBoot Boot(IKnowledgeRetrievalPort port, RecordingLoggerFactory loggers) - { - AgentCoreOptions options = new() + private static AgentCoreBoot Boot(IKnowledgeRetrievalPort port, RecordingLoggerFactory loggers) { - Configuration = OneScopelessReader(), + AgentCoreOptions options = new() + { + Configuration = OneScopelessReader(), - // The seam the boot's own constructor prefers over the container's factory. Setting it - // here is what makes "the host's factory" a thing this test can read back. - LoggerFactory = loggers, - }; + // The seam the boot's own constructor prefers over the container's factory. Setting it + // here is what makes "the host's factory" a thing this test can read back. + LoggerFactory = loggers, + }; - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - options.UseKnowledgeRetrieval(_ => port); + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + _ = options.UseKnowledgeRetrieval(_ => port); - return new AgentCoreBoot(Options.Create(options), NullLoggerFactory.Instance); - } + return new AgentCoreBoot(Options.Create(options), NullLoggerFactory.Instance); + } - private static IEnumerable Providers(AIAgent agent) - { - var inner = agent.GetService(); - Assert.NotNull(inner); - return inner.AIContextProviders ?? []; - } + private static IEnumerable Providers(AIAgent agent) + { + ChatClientAgent? inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } - /// A store that is down, the way Qdrant is down. - private sealed class ThrowingPort(Exception failure) : IKnowledgeRetrievalPort - { - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => throw failure; + /// A store that is down, the way Qdrant is down. + private sealed class ThrowingPort(Exception failure) : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + throw failure; + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeScopeArgumentOrderTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeScopeArgumentOrderTests.cs index 66befd3e..2ad95ce3 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeScopeArgumentOrderTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeScopeArgumentOrderTests.cs @@ -10,165 +10,170 @@ using Microsoft.Extensions.Options; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// Which of the two scoping questions reaches which parameter, asserted from the composition root. -/// -/// -/// -/// AgentCoreBoot passes AnyScoped and then AllScoped into two adjacent -/// parameters of a security-adjacent pair. Swap them and the compiler is -/// silent, every other test in the tree stays green, and the deployment is wrong in both directions -/// at once: a mixed document makes the shared store strict, so every turn of its unscoped agent -/// throws, and a fully scoped document makes it permissive, so the store's own fail-closed guard -/// quietly disappears. -/// -/// -/// A MIXED document is the only one that can tell them apart — it is the one shape where the two -/// questions have different answers. So both facts here run on the same mixed document: one reads -/// what the adapter was handed, the other reads what the capability check did with the other value. -/// -/// -public sealed class KnowledgeScopeArgumentOrderTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - [Fact] - public async Task BootAsync_MixedScoping_LeavesTheSharedStorePermissive() + /// + /// Which of the two scoping questions reaches which parameter, asserted from the composition root. + /// + /// + /// + /// AgentCoreBoot passes AnyScoped and then AllScoped into two adjacent + /// parameters of a security-adjacent pair. Swap them and the compiler is + /// silent, every other test in the tree stays green, and the deployment is wrong in both directions + /// at once: a mixed document makes the shared store strict, so every turn of its unscoped agent + /// throws, and a fully scoped document makes it permissive, so the store's own fail-closed guard + /// quietly disappears. + /// + /// + /// A MIXED document is the only one that can tell them apart — it is the one shape where the two + /// questions have different answers. So both facts here run on the same mixed document: one reads + /// what the adapter was handed, the other reads what the capability check did with the other value. + /// + /// + public sealed class KnowledgeScopeArgumentOrderTests { - // requireScope is AllScoped, the SECOND argument. False here, because one agent is unscoped - // and the store is shared: a strict store would throw on every turn that agent takes. - ScopeRecordingAdapter adapter = new(canScope: true); + [Fact] + public async Task BootAsync_MixedScoping_LeavesTheSharedStorePermissive() + { + // requireScope is AllScoped, the SECOND argument. False here, because one agent is unscoped + // and the store is shared: a strict store would throw on every turn that agent takes. + ScopeRecordingAdapter adapter = new(canScope: true); - await using var boot = Boot(adapter); - await boot.BootAsync(TestContext.Current.CancellationToken); + await using AgentCoreBoot boot = Boot(adapter); + await boot.BootAsync(TestContext.Current.CancellationToken); - Assert.True(adapter.Built); - Assert.False(adapter.RequireScope); - } + Assert.True(adapter.Built); + Assert.False(adapter.RequireScope); + } - [Fact] - public async Task BootAsync_MixedScopingOverAnAdapterThatCannotScope_FailsTheStart() - { - // scopeDeclared is AnyScoped, the FIRST argument. True here, because one agent IS scoped, so - // an adapter that cannot filter must refuse the start rather than serve that agent every - // customer's cards. Under a swap this value would be AllScoped -- false -- and the start would - // succeed with the leak in it. - ScopeRecordingAdapter adapter = new(canScope: false); + [Fact] + public async Task BootAsync_MixedScopingOverAnAdapterThatCannotScope_FailsTheStart() + { + // scopeDeclared is AnyScoped, the FIRST argument. True here, because one agent IS scoped, so + // an adapter that cannot filter must refuse the start rather than serve that agent every + // customer's cards. Under a swap this value would be AllScoped -- false -- and the start would + // succeed with the leak in it. + ScopeRecordingAdapter adapter = new(canScope: false); - await using var boot = Boot(adapter); + await using AgentCoreBoot boot = Boot(adapter); - var failure = await Assert.ThrowsAsync( - async () => await boot.BootAsync(TestContext.Current.CancellationToken)); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await boot.BootAsync(TestContext.Current.CancellationToken)); - Assert.Contains("scoped: true", failure.Message, StringComparison.Ordinal); - Assert.False(adapter.Built); - } + Assert.Contains("scoped: true", failure.Message, StringComparison.Ordinal); + Assert.False(adapter.Built); + } - /// - /// The one document shape that can tell the two questions apart: one scoped agent, one not. - /// - /// - /// Built as an object rather than parsed from YAML, so it needs no providers.conversation and no - /// providers.speech — the schema requires both once a providers: block exists, and a - /// boot that had to register a conversation vendor and a speech vendor would be testing those instead. - /// - private static AgentCoreConfiguration MixedScoping() - => new() + /// + /// The one document shape that can tell the two questions apart: one scoped agent, one not. + /// + /// + /// Built as an object rather than parsed from YAML, so it needs no providers.conversation and no + /// providers.speech — the schema requires both once a providers: block exists, and a + /// boot that had to register a conversation vendor and a speech vendor would be testing those instead. + /// + private static AgentCoreConfiguration MixedScoping() { - ApiVersion = "agentcore/v1", - Providers = new ProvidersConfiguration + return new() { - Knowledge = new KnowledgeProviderConfiguration + ApiVersion = "agentcore/v1", + Providers = new ProvidersConfiguration { - Kind = "test", - Collection = "kb", - Fields = new KnowledgeFieldsConfiguration { Body = "body" }, - Scope = new KnowledgeScopeConfiguration { Template = "facets.{key}" }, - }, - }, - Agents = new AgentsConfiguration - { - Items = - [ - new AgentConfiguration - { - Id = "resolver", - Instructions = "I answer about one machine", - Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, - }, - new AgentConfiguration + Knowledge = new KnowledgeProviderConfiguration { - Id = "analyst", - Instructions = "I search every product on purpose", - Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = false }, + Kind = "test", + Collection = "kb", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + Scope = new KnowledgeScopeConfiguration { Template = "facets.{key}" }, }, - ], - }, - Entries = new Dictionary - { - ["main"] = new EntryConfiguration + }, + Agents = new AgentsConfiguration { - Policy = new PolicyConfiguration + Items = + [ + new AgentConfiguration + { + Id = "resolver", + Instructions = "I answer about one machine", + Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, + }, + new AgentConfiguration + { + Id = "analyst", + Instructions = "I search every product on purpose", + Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = false }, + }, + ], + }, + Entries = new Dictionary + { + ["main"] = new EntryConfiguration { - Initial = "answering", - Stages = - [ - new StageConfiguration - { - Id = "answering", - Agent = "resolver", - To = [new StageTransition { Stage = "reviewing" }], - }, - new StageConfiguration { Id = "reviewing", Agent = "analyst", Terminal = true }, - ], + Policy = new PolicyConfiguration + { + Initial = "answering", + Stages = + [ + new StageConfiguration + { + Id = "answering", + Agent = "resolver", + To = [new StageTransition { Stage = "reviewing" }], + }, + new StageConfiguration { Id = "reviewing", Agent = "analyst", Terminal = true }, + ], + }, }, }, - }, - }; + }; + } - private static AgentCoreBoot Boot(IKnowledgeStoreAdapter adapter) - { - AgentCoreOptions options = new() { Configuration = MixedScoping() }; + private static AgentCoreBoot Boot(IKnowledgeStoreAdapter adapter) + { + AgentCoreOptions options = new() { Configuration = MixedScoping() }; - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - options.UseKnowledgeStores(adapter); + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + _ = options.UseKnowledgeStores(adapter); - return new AgentCoreBoot(Options.Create(options), NullLoggerFactory.Instance); - } + return new AgentCoreBoot(Options.Create(options), NullLoggerFactory.Instance); + } - /// A knowledge vendor that records the scoping question it was handed. - private sealed class ScopeRecordingAdapter(bool canScope) : IKnowledgeStoreAdapter - { - public string Kind => "test"; + /// A knowledge vendor that records the scoping question it was handed. + private sealed class ScopeRecordingAdapter(bool canScope) : IKnowledgeStoreAdapter + { + public string Kind => "test"; - public bool CanServeSearch => true; + public bool CanServeSearch => true; - public bool CanScope { get; } = canScope; + public bool CanScope { get; } = canScope; - /// Gets whether the composition root ever asked this adapter to build. - public bool Built { get; private set; } + /// Gets whether the composition root ever asked this adapter to build. + public bool Built { get; private set; } - /// Gets the value of the second scoping argument, as it arrived. - public bool RequireScope { get; private set; } + /// Gets the value of the second scoping argument, as it arrived. + public bool RequireScope { get; private set; } - public ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default) - { - Built = true; - RequireScope = requireScope; - return ValueTask.FromResult(new SilentPort()); + public ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) + { + Built = true; + RequireScope = requireScope; + return ValueTask.FromResult(new SilentPort()); + } } - } - /// A port that answers with nothing. Nothing here searches. - private sealed class SilentPort : IKnowledgeRetrievalPort - { - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + /// A port that answers with nothing. Nothing here searches. + private sealed class SilentPort : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs index 6c65d1d7..220a364d 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/KnowledgeStartupTests.cs @@ -5,217 +5,225 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; using AgentCore.AspNetCore.DependencyInjection; +using AgentCore.AspNetCore.DependencyInjection.Startup; using AgentCore.Application.Secrets; using AgentCore.Domain.Knowledge; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// Step 3b of the composition root: open the knowledge port the document names, before any tool is -/// built. -/// -/// -/// Task 1 deleted the four knowledge tools, and with them every host-DI test that used to observe -/// this wiring by calling a tool. This file proves the two seams directly, with no tool involved. -/// -public sealed class KnowledgeStartupTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - [Fact] - public async Task OpenAsync_UseKnowledgeStoresWithAMatchingProvidersKnowledgeBlock_ReturnsALivePort() + /// + /// Step 3b of the composition root: open the knowledge port the document names, before any tool is + /// built. + /// + /// + /// Task 1 deleted the four knowledge tools, and with them every host-DI test that used to observe + /// this wiring by calling a tool. This file proves the two seams directly, with no tool involved. + /// + public sealed class KnowledgeStartupTests { - RecordingAdapter adapter = new("test"); - AgentCoreOptions options = new(); - options.UseKnowledgeStores(adapter); - - var configuration = Configuration(new KnowledgeProviderConfiguration + [Fact] + public async Task OpenAsync_UseKnowledgeStoresWithAMatchingProvidersKnowledgeBlock_ReturnsALivePort() { - Kind = "test", - Collection = "manuals", - Fields = new KnowledgeFieldsConfiguration { Body = "body" }, - }); - AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - - var port = await KnowledgeStartup.OpenAsync( - configuration, - options, - startup, - embeddings: null, - scopeDeclared: false, - requireScope: false, - TestContext.Current.CancellationToken); - - Assert.NotNull(port); - Assert.Same(adapter.LastBuilt, port); - Assert.True(adapter.CreateSearchCalled); - } + RecordingAdapter adapter = new("test"); + AgentCoreOptions options = new(); + _ = options.UseKnowledgeStores(adapter); - [Fact] - public async Task OpenAsync_UseKnowledgeRetrievalRegistered_InvokesItWithTheStartup() - { - FakePort fake = new(); - AgentCoreStartup? seen = null; - AgentCoreOptions options = new(); - options.UseKnowledgeRetrieval(startup => - { - seen = startup; - return fake; - }); - - var configuration = Configuration(knowledge: null); - AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - - var port = await KnowledgeStartup.OpenAsync( - configuration, - options, - startup, - embeddings: null, - scopeDeclared: false, - requireScope: false, - TestContext.Current.CancellationToken); - - Assert.Same(fake, port); - Assert.Same(startup, seen); - } + AgentCoreConfiguration configuration = Configuration(new KnowledgeProviderConfiguration + { + Kind = "test", + Collection = "manuals", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + }); + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - [Fact] - public async Task OpenAsync_CacheSet_WrapsTheStoreAndStillReachesIt() - { - RecordingAdapter adapter = new("test"); - AgentCoreOptions options = new() { Cache = PassThroughHybridCache.Instance }; - options.UseKnowledgeStores(adapter); + IKnowledgeRetrievalPort? port = await KnowledgeStartup.OpenAsync( + configuration, + options, + startup, + embeddings: null, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken); + + Assert.NotNull(port); + Assert.Same(adapter.LastBuilt, port); + Assert.True(adapter.CreateSearchCalled); + } - var configuration = Configuration(new KnowledgeProviderConfiguration + [Fact] + public async Task OpenAsync_UseKnowledgeRetrievalRegistered_InvokesItWithTheStartup() { - Kind = "test", - Collection = "manuals", - Fields = new KnowledgeFieldsConfiguration { Body = "body" }, - }); - AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - - var port = await KnowledgeStartup.OpenAsync( - configuration, - options, - startup, - embeddings: null, - scopeDeclared: false, - requireScope: false, - TestContext.Current.CancellationToken); - - Assert.IsType(port); - Assert.Same(adapter.LastBuilt, port.GetService()); - } + FakePort fake = new(); + AgentCoreStartup? seen = null; + AgentCoreOptions options = new(); + _ = options.UseKnowledgeRetrieval(startup => + { + seen = startup; + return fake; + }); - [Fact] - public async Task OpenAsync_NoKnowledgeBlockAndNoAgentKnowledge_OpensNothingAndAsksNoAdapter() - { - // The hosting layer registers a knowledge adapter by default, so a document that never - // mentions knowledge must not pay for a store — or fail over one it never asked for. - RecordingAdapter adapter = new("test"); - AgentCoreOptions options = new(); - options.UseKnowledgeStores(adapter); - - var configuration = Configuration(knowledge: null); - AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - - var port = await KnowledgeStartup.OpenAsync( - configuration, - options, - startup, - embeddings: null, - scopeDeclared: false, - requireScope: false, - TestContext.Current.CancellationToken); - - Assert.Null(port); - Assert.False(adapter.CreateSearchCalled); - } + AgentCoreConfiguration configuration = Configuration(knowledge: null); + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - [Fact] - public async Task OpenAsync_AnAgentDeclaresKnowledgeButNoProvidersBlock_FailsTheStart() - { - // The agent's own knowledge: block is the other opt-in, so the registry IS reached -- and - // then there is nothing to reach it with. AgentCore has no default vendor, collection or - // payload shape, so the only honest answer is a refusal that names the missing block. - RecordingAdapter adapter = new("qdrant"); - AgentCoreOptions options = new(); - options.UseKnowledgeStores(adapter); - - var configuration = Configuration(knowledge: null) with + IKnowledgeRetrievalPort? port = await KnowledgeStartup.OpenAsync( + configuration, + options, + startup, + embeddings: null, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken); + + Assert.Same(fake, port); + Assert.Same(startup, seen); + } + + [Fact] + public async Task OpenAsync_CacheSet_WrapsTheStoreAndStillReachesIt() { - Agents = new AgentsConfiguration + RecordingAdapter adapter = new("test"); + AgentCoreOptions options = new() { Cache = PassThroughHybridCache.Instance }; + _ = options.UseKnowledgeStores(adapter); + + AgentCoreConfiguration configuration = Configuration(new KnowledgeProviderConfiguration { - Items = - [ - new AgentConfiguration - { - Id = "only", - Instructions = "I answer everything", - Knowledge = new AgentKnowledgeConfiguration(), - }, - ], - }, - }; - AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - - var failure = await Assert.ThrowsAsync( - async () => await KnowledgeStartup.OpenAsync( + Kind = "test", + Collection = "manuals", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + }); + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); + + IKnowledgeRetrievalPort? port = await KnowledgeStartup.OpenAsync( configuration, options, startup, embeddings: null, scopeDeclared: false, requireScope: false, - TestContext.Current.CancellationToken)); + TestContext.Current.CancellationToken); - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/knowledge"); - Assert.False(adapter.CreateSearchCalled); - } + _ = Assert.IsType(port); + Assert.Same(adapter.LastBuilt, port.GetService()); + } - private static AgentCoreConfiguration Configuration(KnowledgeProviderConfiguration? knowledge) - => new() + [Fact] + public async Task OpenAsync_NoKnowledgeBlockAndNoAgentKnowledge_OpensNothingAndAsksNoAdapter() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Providers = new ProvidersConfiguration { Knowledge = knowledge }, - }; - - /// An offline knowledge vendor that records what it was asked to build. - private sealed class RecordingAdapter(string kind) : IKnowledgeStoreAdapter - { - public string Kind { get; } = kind; + // The hosting layer registers a knowledge adapter by default, so a document that never + // mentions knowledge must not pay for a store — or fail over one it never asked for. + RecordingAdapter adapter = new("test"); + AgentCoreOptions options = new(); + _ = options.UseKnowledgeStores(adapter); - public bool CanServeSearch => true; + AgentCoreConfiguration configuration = Configuration(knowledge: null); + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - public bool CanScope => true; + IKnowledgeRetrievalPort? port = await KnowledgeStartup.OpenAsync( + configuration, + options, + startup, + embeddings: null, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken); + + Assert.Null(port); + Assert.False(adapter.CreateSearchCalled); + } - public bool CreateSearchCalled { get; private set; } + [Fact] + public async Task OpenAsync_AnAgentDeclaresKnowledgeButNoProvidersBlock_FailsTheStart() + { + // The agent's own knowledge: block is the other opt-in, so the registry IS reached -- and + // then there is nothing to reach it with. AgentCore has no default vendor, collection or + // payload shape, so the only honest answer is a refusal that names the missing block. + RecordingAdapter adapter = new("qdrant"); + AgentCoreOptions options = new(); + _ = options.UseKnowledgeStores(adapter); + + AgentCoreConfiguration configuration = Configuration(knowledge: null) with + { + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration + { + Id = "only", + Instructions = "I answer everything", + Knowledge = new AgentKnowledgeConfiguration(), + }, + ], + }, + }; + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await KnowledgeStartup.OpenAsync( + configuration, + options, + startup, + embeddings: null, + scopeDeclared: false, + requireScope: false, + TestContext.Current.CancellationToken)); + + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/knowledge"); + Assert.False(adapter.CreateSearchCalled); + } - public IKnowledgeRetrievalPort? LastBuilt { get; private set; } + private static AgentCoreConfiguration Configuration(KnowledgeProviderConfiguration? knowledge) + { + return new() + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Providers = new ProvidersConfiguration { Knowledge = knowledge }, + }; + } - public ValueTask CreateSearchAsync( - KnowledgeProviderConfiguration entry, - ISecretResolverPort? secrets, - IEmbeddingGenerator>? embeddings, - bool requireScope, - CancellationToken cancellationToken = default) + /// An offline knowledge vendor that records what it was asked to build. + private sealed class RecordingAdapter(string kind) : IKnowledgeStoreAdapter { - CreateSearchCalled = true; - LastBuilt = new FakePort(); - return ValueTask.FromResult(LastBuilt); + public string Kind { get; } = kind; + + public bool CanServeSearch => true; + + public bool CanScope => true; + + public bool CreateSearchCalled { get; private set; } + + public IKnowledgeRetrievalPort? LastBuilt { get; private set; } + + public ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) + { + CreateSearchCalled = true; + LastBuilt = new FakePort(); + return ValueTask.FromResult(LastBuilt); + } } - } - /// A port that answers with nothing. Its identity, and one extra capability, are asserted against. - private sealed class FakePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort - { - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + /// A port that answers with nothing. Its identity, and one extra capability, are asserted against. + private sealed class FakePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort + { + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } - public ValueTask> ReadByFacetAsync( - string path, string value, int limit, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + public ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/SkillsStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/SkillsStartupTests.cs index fb0adcb7..45aaf3b9 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/SkillsStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/SkillsStartupTests.cs @@ -1,308 +1,314 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Skills; using AgentCore.AspNetCore.DependencyInjection; +using AgentCore.AspNetCore.DependencyInjection.Startup; using AgentCore.TestSupport; using Microsoft.Agents.AI; using Microsoft.Extensions.Logging.Abstractions; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// MAF says nothing when a skills folder is wrong: a missing folder, a dropped skill and a -/// duplicate name all enumerate cleanly and serve the wrong answers later. Every one of them must -/// stop the boot instead. -/// -public sealed class SkillsStartupTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - [Fact] - public async Task OpenAsync_NoHostBinding_ReturnsNull() - { - var catalog = await SkillsStartup.OpenAsync( - new AgentCoreOptions(), NullLoggerFactory.Instance, TestContext.Current.CancellationToken); - - Assert.Null(catalog); - } - - [Fact] - public async Task OpenAsync_AGoodFolder_CarriesEveryName() - { - using var folder = SkillFolder.Create() - .WithSkill("warranty-returns") - .WithSkill("shipping-claims"); - - var catalog = await OpenAsync(folder.Root); - - Assert.NotNull(catalog); - Assert.Equal( - ["shipping-claims", "warranty-returns"], - catalog.Names.Order(StringComparer.Ordinal)); - } - - [Fact] - public async Task OpenAsync_AMissingFolder_FailsNamingThePath() - { - var missing = Path.Combine(Path.GetTempPath(), "agentcore-skills-does-not-exist"); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(missing).AsTask()); - - Assert.Contains(missing, failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_APathThatIsAFile_SaysSoRatherThanCallingItMissing() - { - // Directory.Exists is false for a file, so a deployment that hands over an archive or a - // single SKILL.md would otherwise be sent hunting for a folder that is right there. - using var folder = SkillFolder.Create(); - var file = Path.Combine(folder.Root, "skills.zip"); - await File.WriteAllTextAsync(file, "not a folder", TestContext.Current.CancellationToken); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(file).AsTask()); - - Assert.Contains($"the skills path '{file}' is a file, not a folder", failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain("does not exist", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_AnEmptyFolder_Fails() - { - using var folder = SkillFolder.Create(); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(folder.Root).AsTask()); - - Assert.Contains("serves no skill", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_ANameThatDoesNotMatchItsDirectory_FailsNamingTheDirectory() - { - using var folder = SkillFolder.Create().WithSkill("folder-name", frontmatterName: "other-name"); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(folder.Root).AsTask()); - - Assert.Contains("folder-name", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_TwoDirectoriesServingOneName_FailsNamingBoth() - { - using var folder = SkillFolder.Create() - .WithSkill("team-a/warranty-returns") - .WithSkill("team-b/warranty-returns"); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(folder.Root).AsTask()); - - Assert.Contains("team-a", failure.Message, StringComparison.Ordinal); - Assert.Contains("team-b", failure.Message, StringComparison.Ordinal); - - // Both names would also appear if MAF dropped both skills and the dropped-directory check - // fired instead, so the wording is what tells the two checks apart. - Assert.Contains("serves one name from more than one directory", failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain("did not load:", failure.Message, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_ASkillDirectoryInsideASkillDirectory_LoadsTheOuterOneAndDoesNotFail() - { - // MAF stops descending at the first SKILL.md, so the inner directory is never a candidate. - // A glob-based check would call it a dropped skill and fail this legal folder. - using var folder = SkillFolder.Create() - .WithSkill("outer") - .WithSkill("outer/inner"); - - var catalog = await OpenAsync(folder.Root); - - Assert.NotNull(catalog); - Assert.Equal(["outer"], catalog.Names); - } - - [Fact] - public async Task OpenAsync_ASkillWithAScript_HidesItFromLoadSkill() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns").WithScript("warranty-returns"); - - var catalog = await OpenAsync(folder.Root); - - var body = await SkillFolder.LoadBodyAsync(catalog!.Source, "warranty-returns", TestContext.Current.CancellationToken); - - Assert.Contains("", body, StringComparison.Ordinal); - Assert.DoesNotContain("hello.py", body, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_ASkillWithAReference_StillListsIt() - { - // The script filter must not take resources down with it. - using var folder = SkillFolder.Create().WithSkill("warranty-returns").WithReference("warranty-returns"); - - var catalog = await OpenAsync(folder.Root); - - var body = await SkillFolder.LoadBodyAsync(catalog!.Source, "warranty-returns", TestContext.Current.CancellationToken); - - Assert.Contains("references/notes.md", body, StringComparison.Ordinal); - } - - [Fact] - public async Task OpenAsync_APathBinding_HandsBackTheCachingWrapper() - { - // The boot tracker disposes whatever this returns as Source. It must be the caching wrapper, - // because disposing that is what cascades into the file source underneath it. - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - - var catalog = await OpenAsync(folder.Root); - - Assert.IsType(catalog!.Source); - } - - [Fact] - public async Task OpenAsync_ABoundSource_CarriesEveryNameAndHandsTheSourceBackUnwrapped() - { - using AgentInMemorySkillsSource source = new([Skill("warranty-returns"), Skill("shipping-claims")]); - - var catalog = await OpenAsync(source); - - Assert.NotNull(catalog); - Assert.Equal( - ["shipping-claims", "warranty-returns"], - catalog.Names.Order(StringComparer.Ordinal)); - - // UseSkills(AgentSkillsSource) documents that it transfers ownership, and the boot tracker - // disposes exactly what it finds here. Wrapping would hand back something else to dispose. - Assert.Same(source, catalog.Source); - } - - [Fact] - public async Task OpenAsync_ABoundSourceServingNothing_FailsWithoutNamingAFolder() - { - using AgentInMemorySkillsSource source = new([]); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(source).AsTask()); - - Assert.Equal( - "The configuration document did not load. the skills source bound by " - + "options.UseSkills(...) serves no skill.", - failure.Message); - } - - [Fact] - public async Task OpenAsync_ABoundSourceServingOneNameTwice_FailsWithoutNamingAFolder() - { - // AgentInMemorySkillsSource keeps the list it was given, so a host reaches the duplicate - // check with no file skill in the group and nothing but a name to be told about. - using AgentInMemorySkillsSource source = new([Skill("warranty-returns"), Skill("warranty-returns")]); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(source).AsTask()); - - Assert.Equal( - "The configuration document did not load. the skills source bound by options.UseSkills(...) " - + "serves one name more than once: 'warranty-returns' is served by 2 skills, of type " - + "AgentInlineSkill. Which copy loads is decided by the order the source returned them, so " - + "the answer can change between runs. Serve each name once.", - failure.Message); - } - - [Fact] - public async Task OpenAsync_ABoundSourceThatFailsACheck_DisposesIt() - { - // UseSkills(AgentSkillsSource) documents that it takes ownership, and OpenAsync is the only - // owner until it returns: the boot tracker never sees a source a check threw over. - using var folder = SkillFolder.Create(); - TrackingSkillsSource tracked = new(folder.Root); - - await Assert.ThrowsAsync(() => OpenAsync(tracked).AsTask()); - - Assert.True(tracked.Disposed); - } - - [Fact] - public async Task OpenAsync_ABoundSourceThatOpensCleanly_IsNotDisposed() - { - using var folder = SkillFolder.Create().WithSkill("warranty-returns"); - TrackingSkillsSource tracked = new(folder.Root); - - var catalog = await OpenAsync(tracked); - - Assert.NotNull(catalog); - Assert.False(tracked.Disposed); - } - - [Fact] - public async Task OpenAsync_ABoundSourceThatCannotBeRead_FailsWithoutNamingAFolder() - { - using UnreadableSkillsSource source = new(); - - var failure = await Assert.ThrowsAsync(() => OpenAsync(source).AsTask()); - - Assert.StartsWith( - "The configuration document did not load. the skills source bound by " - + "options.UseSkills(...) could not be read:", - failure.Message, - StringComparison.Ordinal); - Assert.DoesNotContain("the skills folder", failure.Message, StringComparison.Ordinal); - Assert.IsType(failure.InnerException); - } - - [Fact] - public async Task UseSkills_ASourceAfterAPath_ReadsTheSource() - { - using var folder = SkillFolder.Create().WithSkill("from-the-folder"); - using AgentInMemorySkillsSource source = new([Skill("from-the-source")]); - - AgentCoreOptions options = new(); - options.UseSkills(folder.Root).UseSkills(source); - - var catalog = await SkillsStartup.OpenAsync( - options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); - - Assert.Equal(["from-the-source"], catalog!.Names); - } - - [Fact] - public async Task UseSkills_APathAfterASource_ReadsThePath() + /// + /// MAF says nothing when a skills folder is wrong: a missing folder, a dropped skill and a + /// duplicate name all enumerate cleanly and serve the wrong answers later. Every one of them must + /// stop the boot instead. + /// + public sealed class SkillsStartupTests { - // OpenAsync prefers a bound source, so only clearing the slot keeps this binding from being - // silently discarded. - using var folder = SkillFolder.Create().WithSkill("from-the-folder"); - using AgentInMemorySkillsSource source = new([Skill("from-the-source")]); + [Fact] + public async Task OpenAsync_NoHostBinding_ReturnsNull() + { + SkillCatalog? catalog = await SkillsStartup.OpenAsync( + new AgentCoreOptions(), NullLoggerFactory.Instance, TestContext.Current.CancellationToken); + + Assert.Null(catalog); + } + + [Fact] + public async Task OpenAsync_AGoodFolder_CarriesEveryName() + { + using SkillFolder folder = SkillFolder.Create() + .WithSkill("warranty-returns") + .WithSkill("shipping-claims"); + + SkillCatalog? catalog = await OpenAsync(folder.Root); + + Assert.NotNull(catalog); + Assert.Equal( + ["shipping-claims", "warranty-returns"], + catalog.Names.Order(StringComparer.Ordinal)); + } + + [Fact] + public async Task OpenAsync_AMissingFolder_FailsNamingThePath() + { + string missing = Path.Combine(Path.GetTempPath(), "agentcore-skills-does-not-exist"); - AgentCoreOptions options = new(); - options.UseSkills(source).UseSkills(folder.Root); + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(missing).AsTask()); - var catalog = await SkillsStartup.OpenAsync( - options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); + Assert.Contains(missing, failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task OpenAsync_APathThatIsAFile_SaysSoRatherThanCallingItMissing() + { + // Directory.Exists is false for a file, so a deployment that hands over an archive or a + // single SKILL.md would otherwise be sent hunting for a folder that is right there. + using SkillFolder folder = SkillFolder.Create(); + string file = Path.Combine(folder.Root, "skills.zip"); + await File.WriteAllTextAsync(file, "not a folder", TestContext.Current.CancellationToken); - Assert.Equal(["from-the-folder"], catalog!.Names); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(file).AsTask()); - private static AgentInlineSkill Skill(string name) - => new(new AgentSkillFrontmatter(name, "A skill used by a test."), "Do the thing."); + Assert.Contains($"the skills path '{file}' is a file, not a folder", failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain("does not exist", failure.Message, StringComparison.Ordinal); + } - private static ValueTask OpenAsync(string path) - { - AgentCoreOptions options = new(); - options.UseSkills(path); + [Fact] + public async Task OpenAsync_AnEmptyFolder_Fails() + { + using SkillFolder folder = SkillFolder.Create(); - return SkillsStartup.OpenAsync(options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(folder.Root).AsTask()); + + Assert.Contains("serves no skill", failure.Message, StringComparison.Ordinal); + } - private static ValueTask OpenAsync(AgentSkillsSource source) - { - AgentCoreOptions options = new(); - options.UseSkills(source); + [Fact] + public async Task OpenAsync_ANameThatDoesNotMatchItsDirectory_FailsNamingTheDirectory() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("folder-name", frontmatterName: "other-name"); - return SkillsStartup.OpenAsync(options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(folder.Root).AsTask()); - /// - /// MAF ships no source that fails this way, and the handler exists for a host that binds its own - /// source over a filesystem it cannot read. - /// - private sealed class UnreadableSkillsSource : AgentSkillsSource - { - public override Task> GetSkillsAsync( - AgentSkillsSourceContext context, - CancellationToken cancellationToken = default) - => throw new UnauthorizedAccessException("Access to the path '/srv/skills' is denied."); + Assert.Contains("folder-name", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task OpenAsync_TwoDirectoriesServingOneName_FailsNamingBoth() + { + using SkillFolder folder = SkillFolder.Create() + .WithSkill("team-a/warranty-returns") + .WithSkill("team-b/warranty-returns"); + + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(folder.Root).AsTask()); + + Assert.Contains("team-a", failure.Message, StringComparison.Ordinal); + Assert.Contains("team-b", failure.Message, StringComparison.Ordinal); + + // Both names would also appear if MAF dropped both skills and the dropped-directory check + // fired instead, so the wording is what tells the two checks apart. + Assert.Contains("serves one name from more than one directory", failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain("did not load:", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task OpenAsync_ASkillDirectoryInsideASkillDirectory_LoadsTheOuterOneAndDoesNotFail() + { + // MAF stops descending at the first SKILL.md, so the inner directory is never a candidate. + // A glob-based check would call it a dropped skill and fail this legal folder. + using SkillFolder folder = SkillFolder.Create() + .WithSkill("outer") + .WithSkill("outer/inner"); + + SkillCatalog? catalog = await OpenAsync(folder.Root); + + Assert.NotNull(catalog); + Assert.Equal(["outer"], catalog.Names); + } + + [Fact] + public async Task OpenAsync_ASkillWithAScript_HidesItFromLoadSkill() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns").WithScript("warranty-returns"); + + SkillCatalog? catalog = await OpenAsync(folder.Root); + + string body = await SkillFolder.LoadBodyAsync(catalog!.Source, "warranty-returns", TestContext.Current.CancellationToken); + + Assert.Contains("", body, StringComparison.Ordinal); + Assert.DoesNotContain("hello.py", body, StringComparison.Ordinal); + } + + [Fact] + public async Task OpenAsync_ASkillWithAReference_StillListsIt() + { + // The script filter must not take resources down with it. + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns").WithReference("warranty-returns"); + + SkillCatalog? catalog = await OpenAsync(folder.Root); + + string body = await SkillFolder.LoadBodyAsync(catalog!.Source, "warranty-returns", TestContext.Current.CancellationToken); + + Assert.Contains("references/notes.md", body, StringComparison.Ordinal); + } + + [Fact] + public async Task OpenAsync_APathBinding_HandsBackTheCachingWrapper() + { + // The boot tracker disposes whatever this returns as Source. It must be the caching wrapper, + // because disposing that is what cascades into the file source underneath it. + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + + SkillCatalog? catalog = await OpenAsync(folder.Root); + + _ = Assert.IsType(catalog!.Source); + } + + [Fact] + public async Task OpenAsync_ABoundSource_CarriesEveryNameAndHandsTheSourceBackUnwrapped() + { + using AgentInMemorySkillsSource source = new([Skill("warranty-returns"), Skill("shipping-claims")]); + + SkillCatalog? catalog = await OpenAsync(source); + + Assert.NotNull(catalog); + Assert.Equal( + ["shipping-claims", "warranty-returns"], + catalog.Names.Order(StringComparer.Ordinal)); + + // UseSkills(AgentSkillsSource) documents that it transfers ownership, and the boot tracker + // disposes exactly what it finds here. Wrapping would hand back something else to dispose. + Assert.Same(source, catalog.Source); + } + + [Fact] + public async Task OpenAsync_ABoundSourceServingNothing_FailsWithoutNamingAFolder() + { + using AgentInMemorySkillsSource source = new([]); + + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(source).AsTask()); + + Assert.Equal( + "The configuration document did not load. the skills source bound by " + + "options.UseSkills(...) serves no skill.", + failure.Message); + } + + [Fact] + public async Task OpenAsync_ABoundSourceServingOneNameTwice_FailsWithoutNamingAFolder() + { + // AgentInMemorySkillsSource keeps the list it was given, so a host reaches the duplicate + // check with no file skill in the group and nothing but a name to be told about. + using AgentInMemorySkillsSource source = new([Skill("warranty-returns"), Skill("warranty-returns")]); + + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(source).AsTask()); + + Assert.Equal( + "The configuration document did not load. the skills source bound by options.UseSkills(...) " + + "serves one name more than once: 'warranty-returns' is served by 2 skills, of type " + + "AgentInlineSkill. Which copy loads is decided by the order the source returned them, so " + + "the answer can change between runs. Serve each name once.", + failure.Message); + } + + [Fact] + public async Task OpenAsync_ABoundSourceThatFailsACheck_DisposesIt() + { + // UseSkills(AgentSkillsSource) documents that it takes ownership, and OpenAsync is the only + // owner until it returns: the boot tracker never sees a source a check threw over. + using SkillFolder folder = SkillFolder.Create(); + TrackingSkillsSource tracked = new(folder.Root); + + _ = await Assert.ThrowsAsync(() => OpenAsync(tracked).AsTask()); + + Assert.True(tracked.Disposed); + } + + [Fact] + public async Task OpenAsync_ABoundSourceThatOpensCleanly_IsNotDisposed() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("warranty-returns"); + TrackingSkillsSource tracked = new(folder.Root); + + SkillCatalog? catalog = await OpenAsync(tracked); + + Assert.NotNull(catalog); + Assert.False(tracked.Disposed); + } + + [Fact] + public async Task OpenAsync_ABoundSourceThatCannotBeRead_FailsWithoutNamingAFolder() + { + using UnreadableSkillsSource source = new(); + + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => OpenAsync(source).AsTask()); + + Assert.StartsWith( + "The configuration document did not load. the skills source bound by " + + "options.UseSkills(...) could not be read:", + failure.Message, + StringComparison.Ordinal); + Assert.DoesNotContain("the skills folder", failure.Message, StringComparison.Ordinal); + _ = Assert.IsType(failure.InnerException); + } + + [Fact] + public async Task UseSkills_ASourceAfterAPath_ReadsTheSource() + { + using SkillFolder folder = SkillFolder.Create().WithSkill("from-the-folder"); + using AgentInMemorySkillsSource source = new([Skill("from-the-source")]); + + AgentCoreOptions options = new(); + _ = options.UseSkills(folder.Root).UseSkills(source); + + SkillCatalog? catalog = await SkillsStartup.OpenAsync( + options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); + + Assert.Equal(["from-the-source"], catalog!.Names); + } + + [Fact] + public async Task UseSkills_APathAfterASource_ReadsThePath() + { + // OpenAsync prefers a bound source, so only clearing the slot keeps this binding from being + // silently discarded. + using SkillFolder folder = SkillFolder.Create().WithSkill("from-the-folder"); + using AgentInMemorySkillsSource source = new([Skill("from-the-source")]); + + AgentCoreOptions options = new(); + _ = options.UseSkills(source).UseSkills(folder.Root); + + SkillCatalog? catalog = await SkillsStartup.OpenAsync( + options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); + + Assert.Equal(["from-the-folder"], catalog!.Names); + } + + private static AgentInlineSkill Skill(string name) + { + return new(new AgentSkillFrontmatter(name, "A skill used by a test."), "Do the thing."); + } + + private static ValueTask OpenAsync(string path) + { + AgentCoreOptions options = new(); + _ = options.UseSkills(path); + + return SkillsStartup.OpenAsync(options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); + } + + private static ValueTask OpenAsync(AgentSkillsSource source) + { + AgentCoreOptions options = new(); + _ = options.UseSkills(source); + + return SkillsStartup.OpenAsync(options, NullLoggerFactory.Instance, TestContext.Current.CancellationToken); + } + + /// + /// MAF ships no source that fails this way, and the handler exists for a host that binds its own + /// source over a filesystem it cannot read. + /// + private sealed class UnreadableSkillsSource : AgentSkillsSource + { + public override Task> GetSkillsAsync( + AgentSkillsSourceContext context, + CancellationToken cancellationToken = default) + { + throw new UnauthorizedAccessException("Access to the path '/srv/skills' is denied."); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHost.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHost.cs index 5be7fd8e..81a968a8 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHost.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHost.cs @@ -1,16 +1,23 @@ using Microsoft.Extensions.Hosting; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// A started host, read as the container it is. -/// The host to read services from, and to close on the way out. -/// -/// Disposing this disposes the host, which disposes the container. That is the whole shutdown -/// path: nothing here calls StopAsync, because a host that failed to start never gets one. -/// -internal sealed class StartedHost(IHost host) : IServiceProvider, IDisposable +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - public object? GetService(Type serviceType) => host.Services.GetService(serviceType); + /// A started host, read as the container it is. + /// The host to read services from, and to close on the way out. + /// + /// Disposing this disposes the host, which disposes the container. That is the whole shutdown + /// path: nothing here calls StopAsync, because a host that failed to start never gets one. + /// + internal sealed class StartedHost(IHost host) : IServiceProvider, IDisposable + { + public object? GetService(Type serviceType) + { + return host.Services.GetService(serviceType); + } - public void Dispose() => host.Dispose(); + public void Dispose() + { + host.Dispose(); + } + } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHostFixture.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHostFixture.cs index f7ea8d2f..ee0e0cad 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHostFixture.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/StartedHostFixture.cs @@ -6,19 +6,19 @@ using Microsoft.Extensions.Hosting; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// Builds a host over one document, which is where the whole boot happens. -/// -/// Shared by every DI test that only needs a booted host and nothing document-specific — the -/// tests that need their own document still write their own YAML and conversation -/// or directly. -/// -internal static class StartedHostFixture +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - /// The one-agent document every test that needs no more than that boots on. - internal const string OneAgentYaml = - """ + /// Builds a host over one document, which is where the whole boot happens. + /// + /// Shared by every DI test that only needs a booted host and nothing document-specific — the + /// tests that need their own document still write their own YAML and conversation + /// or directly. + /// + internal static class StartedHostFixture + { + /// The one-agent document every test that needs no more than that boots on. + internal const string OneAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -35,59 +35,62 @@ internal static class StartedHostFixture agent: only """; - /// Starts a host on one document. - /// The document to boot. - /// The host's own word on the options. - /// The started host, read as the container it is. - internal static async Task BuildAsync(string yaml, Action? configure = null) - { - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - ConfigureServices(builder.Services, yaml, configure); - - return await StartAsync(builder.Build()); - } - - /// Starts one host, and closes it itself when the start fails. - /// The host to start. - /// The started host. - /// - /// A failed start never stops what already started, so disposal is the only cleanup path — and - /// it is the one a real host takes too, inside RunAsync's own finally. StopAsync is - /// deliberately not called here: on net10 a host that failed to start throws - /// out of StopAsync when the failure was a constructor. - /// - internal static async Task StartAsync(IHost host) - { - try + /// Starts a host on one document. + /// The document to boot. + /// The host's own word on the options. + /// The started host, read as the container it is. + internal static async Task BuildAsync(string yaml, Action? configure = null) { - await host.StartAsync(TestContext.Current.CancellationToken); + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + ConfigureServices(builder.Services, yaml, configure); + + return await StartAsync(builder.Build()); } - catch + + /// Starts one host, and closes it itself when the start fails. + /// The host to start. + /// The started host. + /// + /// A failed start never stops what already started, so disposal is the only cleanup path — and + /// it is the one a real host takes too, inside RunAsync's own finally. StopAsync is + /// deliberately not called here: on net10 a host that failed to start throws + /// out of StopAsync when the failure was a constructor. + /// + internal static async Task StartAsync(IHost host) { - host.Dispose(); - throw; - } + try + { + await host.StartAsync(TestContext.Current.CancellationToken); + } + catch + { + host.Dispose(); + throw; + } - return new StartedHost(host); - } + return new StartedHost(host); + } - /// Starts a host on nothing but the options a test writes, with no document default. - /// The only word on the options. - /// The started host, for the tests that expect it never to get one. - internal static async Task StartBareAsync(Action configure) - { - HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); - builder.Services.AddAgentCore(configure); + /// Starts a host on nothing but the options a test writes, with no document default. + /// The only word on the options. + /// The started host, for the tests that expect it never to get one. + internal static async Task StartBareAsync(Action configure) + { + HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(new()); + _ = builder.Services.AddAgentCore(configure); - return await StartAsync(builder.Build()); - } + return await StartAsync(builder.Build()); + } - internal static void ConfigureServices( - IServiceCollection services, string yaml, Action? configure) - => services.AddAgentCore(options => + internal static void ConfigureServices( + IServiceCollection services, string yaml, Action? configure) { - options.Configuration = ConfigurationLoader.LoadYaml(yaml); - options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); - configure?.Invoke(options); - }); + _ = services.AddAgentCore(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(yaml); + _ = options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + configure?.Invoke(options); + }); + } + } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/ToolRegistryStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/ToolRegistryStartupTests.cs index 01267c9b..00997852 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/ToolRegistryStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/ToolRegistryStartupTests.cs @@ -4,7 +4,6 @@ using AgentCore.Application.Secrets; using AgentCore.Application.Tools.Builtin; using AgentCore.Application.Tools.Registry; -using AgentCore.Application.Tools; using AgentCore.AspNetCore.DependencyInjection; using AgentCore.AspNetCore.DependencyInjection.Startup; using AgentCore.AspNetCore.Tests.Fakes; @@ -14,174 +13,189 @@ using Microsoft.Extensions.Options; using Xunit; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// Step 4 of the composition root: build every tool source's registrations into one registry, with -/// every source tracked against the boot that must close it. -/// -public sealed class ToolRegistryStartupTests +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - [Fact] - public async Task BuildAsync_ADocumentWithNoMcpBlockAndNoHostSource_ServesOnlyTheBuiltInIds() - { - var built = await BuildAsync(NoMcpConfiguration(), new AgentCoreOptions()); - - Assert.NotNull(built.Registry); - } - /// - /// A source's own ProvideAsync can succeed — it has already opened whatever it opens — - /// and the overall build still fail later, here on an undeclared tool - /// VerifyEveryDeclarationIsServed only catches once every source has answered. The source - /// is tracked against the boot as it is built, before any of that, so a failed start closes it. + /// Step 4 of the composition root: build every tool source's registrations into one registry, with + /// every source tracked against the boot that must close it. /// - [Fact] - public async Task BuildAsync_TheBuilderThrowsAfterASourceAlreadyOpened_LeavesTheSourceWithTheBootToClose() + public sealed class ToolRegistryStartupTests { - OpenTrackingToolSource source = new(); - AgentCoreOptions options = new(); - options.AddToolSource(_ => source); + [Fact] + public async Task BuildAsync_ADocumentWithNoMcpBlockAndNoHostSource_ServesOnlyTheBuiltInIds() + { + ToolRegistryBuildResult built = await BuildAsync(NoMcpConfiguration(), new AgentCoreOptions()); - var boot = Boot(); + Assert.NotNull(built.Registry); + } - await Assert.ThrowsAsync( - () => BuildAsync(UndeclaredToolConfiguration(), options, boot).AsTask()); + /// + /// A source's own ProvideAsync can succeed — it has already opened whatever it opens — + /// and the overall build still fail later, here on an undeclared tool + /// VerifyEveryDeclarationIsServed only catches once every source has answered. The source + /// is tracked against the boot as it is built, before any of that, so a failed start closes it. + /// + [Fact] + public async Task BuildAsync_TheBuilderThrowsAfterASourceAlreadyOpened_LeavesTheSourceWithTheBootToClose() + { + OpenTrackingToolSource source = new(); + AgentCoreOptions options = new(); + _ = options.AddToolSource(_ => source); - await boot.DisposeAsync(); + AgentCoreBoot boot = Boot(); - Assert.True(source.Disposed); - } + _ = await Assert.ThrowsAsync( + () => BuildAsync(UndeclaredToolConfiguration(), options, boot).AsTask()); - /// - /// A kind: agent tool reaches no source ( carves it out of - /// its own collision check), so without this guard a discovered id and a declared agent tool could - /// claim the same served id: the registry would never notice, ServedIds would just union - /// the two, and ConfigurationCompiler would find the declared entry first and silently hand - /// the agent the delegation tool instead of the discovered one. - /// - [Fact] - public async Task BuildAsync_ADiscoveredIdCollidesWithADeclaredAgentTool_FailsNamingTheId() - { - AgentCoreOptions options = new(); - options.AddToolSource(_ => new DiscoveringToolSource("shared_id")); - - var failure = await Assert.ThrowsAsync( - () => BuildAsync(CollidingAgentToolConfiguration(), options).AsTask()); + await boot.DisposeAsync(); - var error = Assert.Single(failure.Errors); - Assert.Contains("shared_id", error.Message, StringComparison.Ordinal); - } + Assert.True(source.Disposed); + } - /// - /// AgentCore.Hosting registers McpToolSource into options.ToolSources; a host that - /// calls AddAgentCore directly never does. Without this guard, a document with an - /// mcp: block and no registered source at all would boot clean and just serve fewer tools - /// than it declares, with no error anywhere — the silent no-op this codebase rejects everywhere - /// else. This deliberately checks a plain count, never McpToolSource by type: this project - /// must not reference AgentCore.Infrastructure, where that type lives. - /// - [Fact] - public async Task BuildAsync_AnMcpBlockWithNoRegisteredToolSource_FailsNamingHowToFixIt() - { - AgentCoreOptions options = new(); + /// + /// A kind: agent tool reaches no source ( carves it out of + /// its own collision check), so without this guard a discovered id and a declared agent tool could + /// claim the same served id: the registry would never notice, ServedIds would just union + /// the two, and ConfigurationCompiler would find the declared entry first and silently hand + /// the agent the delegation tool instead of the discovered one. + /// + [Fact] + public async Task BuildAsync_ADiscoveredIdCollidesWithADeclaredAgentTool_FailsNamingTheId() + { + AgentCoreOptions options = new(); + _ = options.AddToolSource(_ => new DiscoveringToolSource("shared_id")); - var failure = await Assert.ThrowsAsync( - () => BuildAsync(McpWithNoSourceConfiguration(), options).AsTask()); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(CollidingAgentToolConfiguration(), options).AsTask()); - var error = Assert.Single(failure.Errors); - Assert.Contains("AddAgentCoreHost", error.Message, StringComparison.Ordinal); - Assert.Contains("AddToolSource", error.Message, StringComparison.Ordinal); - } + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Contains("shared_id", error.Message, StringComparison.Ordinal); + } - private static AgentCoreConfiguration McpWithNoSourceConfiguration() - => new() + /// + /// AgentCore.Hosting registers McpToolSource into options.ToolSources; a host that + /// calls AddAgentCore directly never does. Without this guard, a document with an + /// mcp: block and no registered source at all would boot clean and just serve fewer tools + /// than it declares, with no error anywhere — the silent no-op this codebase rejects everywhere + /// else. This deliberately checks a plain count, never McpToolSource by type: this project + /// must not reference AgentCore.Infrastructure, where that type lives. + /// + [Fact] + public async Task BuildAsync_AnMcpBlockWithNoRegisteredToolSource_FailsNamingHowToFixIt() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Mcp = - [ - new McpServerConfiguration - { - Id = "jira", - Transport = McpTransport.Stdio, - Command = ["npx"], - Allow = [new McpAllowEntry { Name = "*" }], - }, - ], - }; - - private static AgentCoreConfiguration NoMcpConfiguration() - => new() + AgentCoreOptions options = new(); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(McpWithNoSourceConfiguration(), options).AsTask()); + + ConfigurationError error = Assert.Single(failure.Errors); + Assert.Contains("AddAgentCoreHost", error.Message, StringComparison.Ordinal); + Assert.Contains("AddToolSource", error.Message, StringComparison.Ordinal); + } + + private static AgentCoreConfiguration McpWithNoSourceConfiguration() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - }; + return new() + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Mcp = + [ + new McpServerConfiguration + { + Id = "jira", + Transport = McpTransport.Stdio, + Command = ["npx"], + Allow = [new McpAllowEntry { Name = "*" }], + }, + ], + }; + } - private static AgentCoreConfiguration UndeclaredToolConfiguration() - => new() + private static AgentCoreConfiguration NoMcpConfiguration() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Tools = [new ToolConfiguration { Id = "no_such_tool", Kind = ToolKind.Binding }], - }; - - private static AgentCoreConfiguration CollidingAgentToolConfiguration() - => new() + return new() + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + }; + } + + private static AgentCoreConfiguration UndeclaredToolConfiguration() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Tools = [new ToolConfiguration { Id = "shared_id", Kind = ToolKind.Agent, Agent = "specialist" }], - }; - - private static ValueTask BuildAsync( - AgentCoreConfiguration configuration, AgentCoreOptions options, AgentCoreBoot? boot = null) - { - AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); - - return ToolRegistryStartup.BuildAsync( - boot ?? Boot(), - options, - startup, - new BuiltinToolPorts( - new RoutingChatClientFactory(new FragmentingChatClient("hello")), - Blobs: null, - Loggers: NullLoggerFactory.Instance), - TestContext.Current.CancellationToken); - } + return new() + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [new ToolConfiguration { Id = "no_such_tool", Kind = ToolKind.Binding }], + }; + } - /// The owner every source this step builds is tracked against. - /// A boot that has run nothing, which is all this step needs of it. - private static AgentCoreBoot Boot() - => new(Options.Create(new AgentCoreOptions()), NullLoggerFactory.Instance); + private static AgentCoreConfiguration CollidingAgentToolConfiguration() + { + return new() + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [new ToolConfiguration { Id = "shared_id", Kind = ToolKind.Agent, Agent = "specialist" }], + }; + } - /// A tool source that tracks whether it was disposed, and serves nothing. - private sealed class OpenTrackingToolSource : IToolSource, IAsyncDisposable - { - /// Gets whether this source was disposed. - public bool Disposed { get; private set; } + private static ValueTask BuildAsync( + AgentCoreConfiguration configuration, AgentCoreOptions options, AgentCoreBoot? boot = null) + { + AgentCoreStartup startup = new(configuration, ResolvedSecrets.Empty); + + return ToolRegistryStartup.BuildAsync( + boot ?? Boot(), + options, + startup, + new BuiltinToolPorts( + new RoutingChatClientFactory(new FragmentingChatClient("hello")), + Blobs: null, + Loggers: NullLoggerFactory.Instance), + TestContext.Current.CancellationToken); + } - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([]); + /// The owner every source this step builds is tracked against. + /// A boot that has run nothing, which is all this step needs of it. + private static AgentCoreBoot Boot() + { + return new(Options.Create(new AgentCoreOptions()), NullLoggerFactory.Instance); + } - public ValueTask DisposeAsync() + /// A tool source that tracks whether it was disposed, and serves nothing. + private sealed class OpenTrackingToolSource : IToolSource, IAsyncDisposable { - Disposed = true; - return ValueTask.CompletedTask; + /// Gets whether this source was disposed. + public bool Disposed { get; private set; } + + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([]); + } + + public ValueTask DisposeAsync() + { + Disposed = true; + return ValueTask.CompletedTask; + } } - } - /// A tool source that serves one id, standing in for what an MCP server's discovery would supply. - private sealed class DiscoveringToolSource(string id) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - [new ToolRegistration(id, "A tool discovered under the same id a declared tool claims.", () => AIFunctionFactory.Create(() => "ok", id))]); + /// A tool source that serves one id, standing in for what an MCP server's discovery would supply. + private sealed class DiscoveringToolSource(string id) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>( + [new ToolRegistration(id, "A tool discovered under the same id a declared tool claims.", () => AIFunctionFactory.Create(() => "ok", id))]); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/WorkspaceStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/WorkspaceStartupTests.cs index a26a0521..28d695d9 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/WorkspaceStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/WorkspaceStartupTests.cs @@ -7,128 +7,128 @@ using Xunit; using static AgentCore.AspNetCore.Tests.DependencyInjection.StartedHostFixture; -namespace AgentCore.AspNetCore.Tests.DependencyInjection; - -/// -/// and the folder it binds a conversation's -/// to. -/// -public sealed class WorkspaceStartupTests : IDisposable +namespace AgentCore.AspNetCore.Tests.DependencyInjection { - private readonly string _tempRoot = - Path.Combine(Path.GetTempPath(), "agentcore-ws-" + Guid.NewGuid().ToString("N")); - - [Fact] - public void UseWorkspace_AnEmptyPath_ThrowsArgumentException() + /// + /// and the folder it binds a conversation's + /// to. + /// + public sealed class WorkspaceStartupTests : IDisposable { - AgentCoreOptions options = new(); + private readonly string _tempRoot = + Path.Combine(Path.GetTempPath(), "agentcore-ws-" + Guid.NewGuid().ToString("N")); - Assert.Throws(() => options.UseWorkspace("")); - } + [Fact] + public void UseWorkspace_AnEmptyPath_ThrowsArgumentException() + { + AgentCoreOptions options = new(); - [Fact] - public async Task AHostBoundToAWorkspaceRoot_CreatesTheConversationsFolderWhenAConversationOpens() - { - using var provider = await BuildAsync(OneAgentYaml, options => options.UseWorkspace(_tempRoot)); + _ = Assert.Throws(() => options.UseWorkspace("")); + } - var sessions = provider.GetRequiredService().ForSessions("main"); - var session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); + [Fact] + public async Task AHostBoundToAWorkspaceRoot_CreatesTheConversationsFolderWhenAConversationOpens() + { + using StartedHost provider = await BuildAsync(OneAgentYaml, options => options.UseWorkspace(_tempRoot)); - Assert.Equal(Path.Combine(_tempRoot, "conversation-1"), session.Workspace); - Assert.True(Directory.Exists(Path.Combine(_tempRoot, "conversation-1"))); - } + IConversationSessions sessions = provider.GetRequiredService().ForSessions("main"); + ConversationSession session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); - [Fact] - public async Task AHostWithNoWorkspaceBound_CreatesNothingAndLeavesWorkspaceNull() - { - using var provider = await BuildAsync(OneAgentYaml); + Assert.Equal(Path.Combine(_tempRoot, "conversation-1"), session.Workspace); + Assert.True(Directory.Exists(Path.Combine(_tempRoot, "conversation-1"))); + } - var sessions = provider.GetRequiredService().ForSessions("main"); - var session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); + [Fact] + public async Task AHostWithNoWorkspaceBound_CreatesNothingAndLeavesWorkspaceNull() + { + using StartedHost provider = await BuildAsync(OneAgentYaml); - Assert.Null(session.Workspace); - } + IConversationSessions sessions = provider.GetRequiredService().ForSessions("main"); + ConversationSession session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); - [Fact] - public async Task ARootThatCannotBeCreated_FailsStartupWithThePathAndTheOption() - { - var blockingFile = Path.Combine(_tempRoot, "blocks-the-root"); - Directory.CreateDirectory(_tempRoot); - await File.WriteAllTextAsync(blockingFile, "not a directory", TestContext.Current.CancellationToken); - var unusableRoot = Path.Combine(blockingFile, "x"); + Assert.Null(session.Workspace); + } - var failure = await Assert.ThrowsAsync( - () => BuildAsync(OneAgentYaml, options => options.UseWorkspace(unusableRoot))); + [Fact] + public async Task ARootThatCannotBeCreated_FailsStartupWithThePathAndTheOption() + { + string blockingFile = Path.Combine(_tempRoot, "blocks-the-root"); + _ = Directory.CreateDirectory(_tempRoot); + await File.WriteAllTextAsync(blockingFile, "not a directory", TestContext.Current.CancellationToken); + string unusableRoot = Path.Combine(blockingFile, "x"); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - Assert.Contains(unusableRoot, failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(OneAgentYaml, options => options.UseWorkspace(unusableRoot))); - [Fact] - public async Task AMemoryAgent_WithAWorkspaceRootBound_Starts() - { - using var provider = await BuildAsync(MemoryAgentYaml, options => options.UseWorkspace(_tempRoot)); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + Assert.Contains(unusableRoot, failure.Message, StringComparison.Ordinal); + } - var sessions = provider.GetRequiredService().ForSessions("main"); - var session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); + [Fact] + public async Task AMemoryAgent_WithAWorkspaceRootBound_Starts() + { + using StartedHost provider = await BuildAsync(MemoryAgentYaml, options => options.UseWorkspace(_tempRoot)); - Assert.StartsWith(_tempRoot, session.Workspace, StringComparison.Ordinal); - } + IConversationSessions sessions = provider.GetRequiredService().ForSessions("main"); + ConversationSession session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); - [Fact] - public async Task AMemoryAgent_WithNoWorkspaceRootBound_FailsStartupNamingUseWorkspace() - { - var failure = await Assert.ThrowsAsync( - () => BuildAsync(MemoryAgentYaml)); + Assert.StartsWith(_tempRoot, session.Workspace, StringComparison.Ordinal); + } - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AMemoryAgent_WithNoWorkspaceRootBound_FailsStartupNamingUseWorkspace() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(MemoryAgentYaml)); - [Fact] - public async Task AMemoryAgent_WithARootThatCannotBeCreated_FailsStartupWithThePathAndTheOption() - { - var blockingFile = Path.Combine(_tempRoot, "blocks-the-root"); - Directory.CreateDirectory(_tempRoot); - await File.WriteAllTextAsync(blockingFile, "not a directory", TestContext.Current.CancellationToken); - var unusableRoot = Path.Combine(blockingFile, "x"); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - () => BuildAsync(MemoryAgentYaml, options => options.UseWorkspace(unusableRoot))); + [Fact] + public async Task AMemoryAgent_WithARootThatCannotBeCreated_FailsStartupWithThePathAndTheOption() + { + string blockingFile = Path.Combine(_tempRoot, "blocks-the-root"); + _ = Directory.CreateDirectory(_tempRoot); + await File.WriteAllTextAsync(blockingFile, "not a directory", TestContext.Current.CancellationToken); + string unusableRoot = Path.Combine(blockingFile, "x"); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - Assert.Contains(unusableRoot, failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(MemoryAgentYaml, options => options.UseWorkspace(unusableRoot))); - [Fact] - public async Task AFilesAgent_WithAWorkspaceRootBound_Starts() - { - using var provider = await BuildAsync(FilesAgentYaml, options => options.UseWorkspace(_tempRoot)); + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + Assert.Contains(unusableRoot, failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task AFilesAgent_WithAWorkspaceRootBound_Starts() + { + using StartedHost provider = await BuildAsync(FilesAgentYaml, options => options.UseWorkspace(_tempRoot)); - var sessions = provider.GetRequiredService().ForSessions("main"); - var session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); + IConversationSessions sessions = provider.GetRequiredService().ForSessions("main"); + ConversationSession session = await sessions.OpenAsync("conversation-1", TestContext.Current.CancellationToken); - Assert.StartsWith(_tempRoot, session.Workspace, StringComparison.Ordinal); - } + Assert.StartsWith(_tempRoot, session.Workspace, StringComparison.Ordinal); + } - [Fact] - public async Task AFilesAgent_WithNoWorkspaceRootBound_FailsStartupNamingUseWorkspace() - { - var failure = await Assert.ThrowsAsync( - () => BuildAsync(FilesAgentYaml)); + [Fact] + public async Task AFilesAgent_WithNoWorkspaceRootBound_FailsStartupNamingUseWorkspace() + { + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => BuildAsync(FilesAgentYaml)); - Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("options.UseWorkspace(", failure.Message, StringComparison.Ordinal); + } - public void Dispose() - { - if (Directory.Exists(_tempRoot)) + public void Dispose() { - Directory.Delete(_tempRoot, recursive: true); + if (Directory.Exists(_tempRoot)) + { + Directory.Delete(_tempRoot, recursive: true); + } } - } - private const string MemoryAgentYaml = - """ + private const string MemoryAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -145,8 +145,8 @@ public void Dispose() agent: only """; - private const string FilesAgentYaml = - """ + private const string FilesAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -162,4 +162,5 @@ public void Dispose() main: agent: only """; + } } diff --git a/tests/AgentCore.AspNetCore.Tests/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapterTests.cs b/tests/AgentCore.AspNetCore.Tests/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapterTests.cs index 0b8b204b..399f6c61 100644 --- a/tests/AgentCore.AspNetCore.Tests/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapterTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Embeddings/OpenAI/OpenAiEmbeddingGeneratorAdapterTests.cs @@ -7,21 +7,21 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Embeddings.OpenAI; - -/// -/// The OpenAI embedding adapter. It owns the vendor only: the SDK client, the key, the model name. -/// -/// -/// Building a generator opens no socket, so every test here runs offline. The key is a fake string, -/// and no test sends a request. -/// -public sealed class OpenAiEmbeddingGeneratorAdapterTests +namespace AgentCore.AspNetCore.Tests.Embeddings.OpenAI { - private const string FakeKey = "sk-test-not-a-real-key"; + /// + /// The OpenAI embedding adapter. It owns the vendor only: the SDK client, the key, the model name. + /// + /// + /// Building a generator opens no socket, so every test here runs offline. The key is a fake string, + /// and no test sends a request. + /// + public sealed class OpenAiEmbeddingGeneratorAdapterTests + { + private const string FakeKey = "sk-test-not-a-real-key"; - private const string OneGeneratorYaml = - """ + private const string OneGeneratorYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -37,86 +37,93 @@ public sealed class OpenAiEmbeddingGeneratorAdapterTests agent: only """; - [Fact] - public void TheAdapter_ServesTheOpenAiKind() - { - Assert.Equal("openai", new OpenAiEmbeddingGeneratorAdapter().Kind); - } - - [Fact] - public async Task TheApiKey_ComesFromTheResolverChain() - { - MapSecretResolver resolver = new(); - resolver.With(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, FakeKey); + [Fact] + public void TheAdapter_ServesTheOpenAiKind() + { + Assert.Equal("openai", new OpenAiEmbeddingGeneratorAdapter().Kind); + } - var generator = await new OpenAiEmbeddingGeneratorAdapter().CreateGeneratorAsync( - Entry(), - resolver, - TestContext.Current.CancellationToken); + [Fact] + public async Task TheApiKey_ComesFromTheResolverChain() + { + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, FakeKey); - Assert.NotNull(generator); - } + IEmbeddingGenerator> generator = await new OpenAiEmbeddingGeneratorAdapter().CreateGeneratorAsync( + Entry(), + resolver, + TestContext.Current.CancellationToken); - [Fact] - public async Task TheGenerator_CarriesTheModelAndTheWidthTheDocumentWrote() - { - MapSecretResolver resolver = new(); - resolver.With(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, FakeKey); + Assert.NotNull(generator); + } - var generator = await new OpenAiEmbeddingGeneratorAdapter().CreateGeneratorAsync( - Entry(), - resolver, - TestContext.Current.CancellationToken); + [Fact] + public async Task TheGenerator_CarriesTheModelAndTheWidthTheDocumentWrote() + { + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, FakeKey); - var metadata = generator.GetService(typeof(EmbeddingGeneratorMetadata)) as EmbeddingGeneratorMetadata; + IEmbeddingGenerator> generator = await new OpenAiEmbeddingGeneratorAdapter().CreateGeneratorAsync( + Entry(), + resolver, + TestContext.Current.CancellationToken); - Assert.NotNull(metadata); - Assert.Equal("text-embedding-3-small", metadata.DefaultModelId); - Assert.Equal(512, metadata.DefaultModelDimensions); - } + EmbeddingGeneratorMetadata? metadata = generator.GetService(typeof(EmbeddingGeneratorMetadata)) as EmbeddingGeneratorMetadata; - [Fact] - public async Task NoApiKeyAnywhere_FailsAndSaysWhereToPutOne() - { - var saved = Environment.GetEnvironmentVariable(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName); - Environment.SetEnvironmentVariable(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName, null); - - try - { - var failure = await Assert.ThrowsAsync( - async () => await new OpenAiEmbeddingGeneratorAdapter().CreateGeneratorAsync( - Entry(), - new MapSecretResolver(), - TestContext.Current.CancellationToken)); - - Assert.Contains(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, failure.Message, StringComparison.Ordinal); - Assert.Contains(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName, failure.Message, StringComparison.Ordinal); + Assert.NotNull(metadata); + Assert.Equal("text-embedding-3-small", metadata.DefaultModelId); + Assert.Equal(512, metadata.DefaultModelDimensions); } - finally + + [Fact] + public async Task NoApiKeyAnywhere_FailsAndSaysWhereToPutOne() { - Environment.SetEnvironmentVariable(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName, saved); + string? saved = Environment.GetEnvironmentVariable(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName); + Environment.SetEnvironmentVariable(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName, null); + + try + { + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await new OpenAiEmbeddingGeneratorAdapter().CreateGeneratorAsync( + Entry(), + new MapSecretResolver(), + TestContext.Current.CancellationToken)); + + Assert.Contains(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, failure.Message, StringComparison.Ordinal); + Assert.Contains(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName, failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(OpenAiEmbeddingGeneratorAdapter.ApiKeyVariableName, saved); + } } - } - [Fact] - public async Task TheComposite_ServesAnOpenAiDocumentThroughThisAdapter() - { - MapSecretResolver resolver = new(); - resolver.With(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, FakeKey); + [Fact] + public async Task TheComposite_ServesAnOpenAiDocumentThroughThisAdapter() + { + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiEmbeddingGeneratorAdapter.ApiKeySecretName, FakeKey); - var generator = await CompositeEmbeddingGeneratorFactory.CreateAsync( - Document(), - resolver, - [new OpenAiEmbeddingGeneratorAdapter()], - TestContext.Current.CancellationToken); + IEmbeddingGenerator>? generator = await CompositeEmbeddingGeneratorFactory.CreateAsync( + Document(), + resolver, + [new OpenAiEmbeddingGeneratorAdapter()], + TestContext.Current.CancellationToken); - Assert.NotNull(generator); - } + Assert.NotNull(generator); + } - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private static AgentCoreConfiguration Document() => ConfigurationLoader.LoadYaml(OneGeneratorYaml); + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private static AgentCoreConfiguration Document() + { + return ConfigurationLoader.LoadYaml(OneGeneratorYaml); + } - private static EmbeddingProviderConfiguration Entry() => Document().Providers!.Embeddings!; + private static EmbeddingProviderConfiguration Entry() + { + return Document().Providers!.Embeddings!; + } + } } diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/ApprovalWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/ApprovalWireTests.cs index a96c2d0f..8a1656c8 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/ApprovalWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/ApprovalWireTests.cs @@ -1,32 +1,32 @@ using System.Net; using System.Text.Json; +using System.Text.Json.Nodes; using AgentCore.Application.Ports; -using AgentCore.Application.Tools; using AgentCore.Application.Tools.Registry; using AgentCore.AspNetCore.Tests.Fakes; using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// -/// The wire an approval travels: one SSE field that asks, and one request field that answers. -/// -/// -/// -/// Like the tool loop facts, an approval is host business the caller must see: the model asked to -/// run something it may not run alone, so the request rides its own agentcore_approval -/// field, and the answer comes back on agentcore.approval naming the same request id on the -/// same conversation. A client that does not speak the dialect reads text frames alone. -/// -/// -/// Every test here runs offline against a fake model, on a real socket. -/// -/// -public sealed class ApprovalWireTests +namespace AgentCore.AspNetCore.Tests.Endpoints { - private const string ApprovalYaml = - """ + /// + /// The wire an approval travels: one SSE field that asks, and one request field that answers. + /// + /// + /// + /// Like the tool loop facts, an approval is host business the caller must see: the model asked to + /// run something it may not run alone, so the request rides its own agentcore_approval + /// field, and the answer comes back on agentcore.approval naming the same request id on the + /// same conversation. A client that does not speak the dialect reads text frames alone. + /// + /// + /// Every test here runs offline against a fake model, on a real socket. + /// + /// + public sealed class ApprovalWireTests + { + private const string ApprovalYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -45,236 +45,247 @@ public sealed class ApprovalWireTests agent: greeter """; - [Fact] - public async Task AGatedToolCall_StreamsAnApprovalEventWithTheConversationFacts() - { - int sent = 0; - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); - - using var response = await PostStreamAsync(host, "send it"); - var events = await ResponsesHost.ReadEventsAsync(response); - - var approval = Assert.Single(ApprovalEventsOf(events)); - Assert.False(string.IsNullOrEmpty(approval.GetProperty("request_id").GetString())); - Assert.Equal("send_email", approval.GetProperty("tool").GetString()); - Assert.Equal("a@b.com", approval.GetProperty("arguments").GetProperty("to").GetString()); - - Assert.Empty(ResponsesHost.TextDeltas(events)); - Assert.Equal(0, sent); - } - - [Fact] - public async Task AGatedToolCall_AnswersWholeWithTheRequestOnTheTurn() - { - int sent = 0; - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); - - using var response = await PostTextAsync(host, "send it"); - var body = await ResponsesHost.ReadJsonAsync(response); - - Assert.Equal(string.Empty, body.OutputText()); - var approvals = JsonDocument.Parse(body["metadata"]!["approvals"]!.GetValue()).RootElement; - var approval = Assert.Single(approvals.EnumerateArray()); - Assert.Equal("send_email", approval.GetProperty("tool").GetString()); - Assert.Equal(0, sent); - } + [Fact] + public async Task AGatedToolCall_StreamsAnApprovalEventWithTheConversationFacts() + { + int sent = 0; + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); + + using HttpResponseMessage response = await PostStreamAsync(host, "send it"); + List events = await ResponsesHost.ReadEventsAsync(response); + + JsonElement approval = Assert.Single(ApprovalEventsOf(events)); + Assert.False(string.IsNullOrEmpty(approval.GetProperty("request_id").GetString())); + Assert.Equal("send_email", approval.GetProperty("tool").GetString()); + Assert.Equal("a@b.com", approval.GetProperty("arguments").GetProperty("to").GetString()); + + Assert.Empty(ResponsesHost.TextDeltas(events)); + Assert.Equal(0, sent); + } - [Fact] - public async Task AnApprovalAnswer_RunsTheToolAndReplies() - { - int sent = 0; - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); - - using var first = await PostTextAsync(host, "send it"); - var asked = await ResponsesHost.ReadJsonAsync(first); - var conversation = asked.ContinuationId(); - var requestId = JsonDocument.Parse( - asked["metadata"]!["approvals"]!.GetValue()) - .RootElement[0].GetProperty("request_id").GetString() ?? string.Empty; - - using var second = await PostApprovalAsync(host, conversation, requestId, approved: true); - var replied = await ResponsesHost.ReadJsonAsync(second); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - Assert.Equal(1, sent); - Assert.Equal("done.", replied.OutputText()); - } + [Fact] + public async Task AGatedToolCall_AnswersWholeWithTheRequestOnTheTurn() + { + int sent = 0; + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); + + using HttpResponseMessage response = await PostTextAsync(host, "send it"); + JsonNode body = await ResponsesHost.ReadJsonAsync(response); + + Assert.Equal(string.Empty, body.OutputText()); + JsonElement approvals = JsonDocument.Parse(body["metadata"]!["approvals"]!.GetValue()).RootElement; + JsonElement approval = Assert.Single(approvals.EnumerateArray()); + Assert.Equal("send_email", approval.GetProperty("tool").GetString()); + Assert.Equal(0, sent); + } - [Fact] - public async Task ARejection_LeavesTheToolUnrun() - { - int sent = 0; - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); - - using var first = await PostTextAsync(host, "send it"); - var asked = await ResponsesHost.ReadJsonAsync(first); - var conversation = asked.ContinuationId(); - var requestId = JsonDocument.Parse( - asked["metadata"]!["approvals"]!.GetValue()) - .RootElement[0].GetProperty("request_id").GetString() ?? string.Empty; - - using var second = await PostApprovalAsync(host, conversation, requestId, approved: false); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - Assert.Equal(0, sent); - } + [Fact] + public async Task AnApprovalAnswer_RunsTheToolAndReplies() + { + int sent = 0; + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); + + using HttpResponseMessage first = await PostTextAsync(host, "send it"); + JsonNode asked = await ResponsesHost.ReadJsonAsync(first); + string conversation = asked.ContinuationId(); + string requestId = JsonDocument.Parse( + asked["metadata"]!["approvals"]!.GetValue()) + .RootElement[0].GetProperty("request_id").GetString() ?? string.Empty; + + using HttpResponseMessage second = await PostApprovalAsync(host, conversation, requestId, approved: true); + JsonNode replied = await ResponsesHost.ReadJsonAsync(second); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.Equal(1, sent); + Assert.Equal("done.", replied.OutputText()); + } - [Fact] - public async Task AnApprovalAnswerForAnUnknownConversation_IsNotFound() - { - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); + [Fact] + public async Task ARejection_LeavesTheToolUnrun() + { + int sent = 0; + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); + + using HttpResponseMessage first = await PostTextAsync(host, "send it"); + JsonNode asked = await ResponsesHost.ReadJsonAsync(first); + string conversation = asked.ContinuationId(); + string requestId = JsonDocument.Parse( + asked["metadata"]!["approvals"]!.GetValue()) + .RootElement[0].GetProperty("request_id").GetString() ?? string.Empty; + + using HttpResponseMessage second = await PostApprovalAsync(host, conversation, requestId, approved: false); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.Equal(0, sent); + } - using var response = await PostApprovalAsync(host, "conv-that-never-existed", "req-1", approved: true); + [Fact] + public async Task AnApprovalAnswerForAnUnknownConversation_IsNotFound() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); - Assert.Equal(HttpStatusCode.NotFound, response.StatusCode); - } + using HttpResponseMessage response = await PostApprovalAsync(host, "conv-that-never-existed", "req-1", approved: true); - [Fact] - public async Task AnApprovalAnswerWithNoConversation_IsBadRequest() - { - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); + Assert.Equal(HttpStatusCode.NotFound, response.StatusCode); + } - using var response = await PostApprovalAsync(host, null, "req-1", approved: true); + [Fact] + public async Task AnApprovalAnswerWithNoConversation_IsBadRequest() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); - Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); - } + using HttpResponseMessage response = await PostApprovalAsync(host, null, "req-1", approved: true); - [Fact] - public async Task AnApprovalAnswerForARequestNothingAsked_IsConflict() - { - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); + Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); + } - using var first = await PostTextAsync(host, "send it"); - var asked = await ResponsesHost.ReadJsonAsync(first); - var conversation = asked.ContinuationId(); + [Fact] + public async Task AnApprovalAnswerForARequestNothingAsked_IsConflict() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); - using var second = await PostApprovalAsync(host, conversation, "req-nothing-asked", approved: true); + using HttpResponseMessage first = await PostTextAsync(host, "send it"); + JsonNode asked = await ResponsesHost.ReadJsonAsync(first); + string conversation = asked.ContinuationId(); - Assert.Equal(HttpStatusCode.Conflict, second.StatusCode); - } + using HttpResponseMessage second = await PostApprovalAsync(host, conversation, "req-nothing-asked", approved: true); - /// Sends one turn of words. - private static Task PostTextAsync(ResponsesHost host, string text, string? conversation = null) - => host.PostAsync(conversation is { Length: > 0 } - ? $$"""{ "stream": false, "conversation": "{{conversation}}", "input": "{{text}}" }""" - : $$"""{ "stream": false, "input": "{{text}}" }"""); + Assert.Equal(HttpStatusCode.Conflict, second.StatusCode); + } - /// Sends one turn of words and reads the answer as it arrives. - /// - /// The dialect member opts the stream into the browser parts: without it the frames carry - /// text alone and an approval ask would suspend the turn in silence. - /// - private static Task PostStreamAsync(ResponsesHost host, string text, string? conversation = null) - => host.PostAsync(conversation is { Length: > 0 } - ? $$"""{ "stream": true, "conversation": "{{conversation}}", "input": "{{text}}", "agentcore": { "message_id": "m1" } }""" - : $$"""{ "stream": true, "input": "{{text}}", "agentcore": { "message_id": "m1" } }"""); - - /// Answers one pending approval. - private static Task PostApprovalAsync( - ResponsesHost host, string? conversation, string requestId, bool approved) - { - var answer = $$"""{ "approval": { "request_id": "{{requestId}}", "approved": {{(approved ? "true" : "false")}} } }"""; - return host.PostAsync(conversation is { Length: > 0 } - ? $$"""{ "stream": false, "conversation": "{{conversation}}", "input": [], "agentcore": {{answer}} }""" - : $$"""{ "stream": false, "input": [], "agentcore": {{answer}} }"""); - } + /// Sends one turn of words. + private static Task PostTextAsync(ResponsesHost host, string text, string? conversation = null) + { + return host.PostAsync(conversation is { Length: > 0 } + ? $$"""{ "stream": false, "conversation": "{{conversation}}", "input": "{{text}}" }""" + : $$"""{ "stream": false, "input": "{{text}}" }"""); + } - private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) => new(AIFunctionFactory.Create( - (string to) => + /// Sends one turn of words and reads the answer as it arrives. + /// + /// The dialect member opts the stream into the browser parts: without it the frames carry + /// text alone and an approval ask would suspend the turn in silence. + /// + private static Task PostStreamAsync(ResponsesHost host, string text, string? conversation = null) { - onSend(); - return "sent"; - }, - "send_email", - "Send an email.")); - - /// Picks the agentcore_approval payloads out of events already read. - private static List ApprovalEventsOf(IEnumerable events) - { - return events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_approval", out var approval) - && approval.ValueKind != JsonValueKind.Null) - .Select(chunk => chunk.GetProperty("agentcore_approval")) - .ToList(); - } + return host.PostAsync(conversation is { Length: > 0 } + ? $$"""{ "stream": true, "conversation": "{{conversation}}", "input": "{{text}}", "agentcore": { "message_id": "m1" } }""" + : $$"""{ "stream": true, "input": "{{text}}", "agentcore": { "message_id": "m1" } }"""); + } - /// A tool source that serves one gated id, standing in for an approval-required host tool. - private sealed class GatedSource(Func build) : IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - [new ToolRegistration("send_email", "Send an email.", build)]); - } + /// Answers one pending approval. + private static Task PostApprovalAsync( + ResponsesHost host, string? conversation, string requestId, bool approved) + { + string answer = $$"""{ "approval": { "request_id": "{{requestId}}", "approved": {{(approved ? "true" : "false")}} } }"""; + return host.PostAsync(conversation is { Length: > 0 } + ? $$"""{ "stream": false, "conversation": "{{conversation}}", "input": [], "agentcore": {{answer}} }""" + : $$"""{ "stream": false, "input": [], "agentcore": {{answer}} }"""); + } - /// Calls the first tool it is offered, once, then answers in words. - private sealed class GatedToolCallingChatClient : IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) { - await Task.Yield(); + return new(AIFunctionFactory.Create( + (string to) => + { + onSend(); + return "sent"; + }, + "send_email", + "Send an email.")); + } - var alreadyCalled = messages.Any(message => message.Contents.OfType().Any()); + /// Picks the agentcore_approval payloads out of events already read. + private static List ApprovalEventsOf(IEnumerable events) + { + return [.. events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_approval", out JsonElement approval) + && approval.ValueKind != JsonValueKind.Null) + .Select(chunk => chunk.GetProperty("agentcore_approval"))]; + } - if (!alreadyCalled && options?.Tools?.OfType().FirstOrDefault() is { } tool) + /// A tool source that serves one gated id, standing in for an approval-required host tool. + private sealed class GatedSource(Func build) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" })]); - yield break; + return ValueTask.FromResult>( + [new ToolRegistration("send_email", "Send an email.", build)]); } - - yield return new ChatResponseUpdate(ChatRole.Assistant, "done."); } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) + /// Calls the first tool it is offered, once, then answers in words. + private sealed class GatedToolCallingChatClient : IChatClient { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) { - updates.Add(update); + await Task.Yield(); + + bool alreadyCalled = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyCalled && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_1", + tool.Name, + new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" })]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "done."); } - return updates.ToChatResponse(); - } + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs index 37769cdc..a01eaf9e 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/FileWireTests.cs @@ -1,26 +1,28 @@ using System.Runtime.CompilerServices; using System.Text.Json; +using AgentCore.Application.Blobs; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Conversation; +using AgentCore.Application.Transcript; using AgentCore.AspNetCore.Tests.Fakes; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// -/// The whole wire a published file travels: the model calls file.publish on a file in the -/// conversation's workspace, the blob store keeps it under the conversation, the browser gets one -/// agentcore_file part with the link, and the transcript links the same file on a later read. -/// -public sealed class FileWireTests : IDisposable +namespace AgentCore.AspNetCore.Tests.Endpoints { - private const string ConversationId = "conversation-pub-1"; + /// + /// The whole wire a published file travels: the model calls file.publish on a file in the + /// conversation's workspace, the blob store keeps it under the conversation, the browser gets one + /// agentcore_file part with the link, and the transcript links the same file on a later read. + /// + public sealed class FileWireTests : IDisposable + { + private const string ConversationId = "conversation-pub-1"; - private const string Yaml = - """ + private const string Yaml = + """ apiVersion: agentcore/v1 tools: - { id: publish, kind: builtin, uses: file.publish } @@ -42,161 +44,166 @@ public sealed class FileWireTests : IDisposable blobs: { kind: fake } """; - private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-filewire-" + Guid.NewGuid().ToString("N")); - - public FileWireTests() => Directory.CreateDirectory(Path.Combine(_root, ConversationId)); + private readonly string _root = Path.Combine(Path.GetTempPath(), "agentcore-filewire-" + Guid.NewGuid().ToString("N")); - public void Dispose() - { - if (Directory.Exists(_root)) + public FileWireTests() { - Directory.Delete(_root, recursive: true); + _ = Directory.CreateDirectory(Path.Combine(_root, ConversationId)); } - } - - [Fact] - public async Task AToolThatPublishes_ReachesTheBrowserAsAFilePartAndTheTranscriptLinksItLater() - { - File.WriteAllText(Path.Combine(_root, ConversationId, "report.csv"), "month,sales\njan,10\n"); - FakeBlobStoreAdapter blobs = new(); - - await using var host = await ResponsesHost.StartAsync( - Yaml, - new PublishingChatClient(), - configure: options => options.UseWorkspace(_root).UseBlobStores(blobs)); - - using var response = await host.PostAsync( - $$"""{ "stream": true, "conversation": "{{ConversationId}}", "input": "send me the report", "agentcore": { "message_id": "m1" } }"""); - var events = await ResponsesHost.ReadEventsAsync(response); - - var files = events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_file", out var file) && file.ValueKind != JsonValueKind.Null) - .Select(chunk => chunk.GetProperty("agentcore_file")) - .ToList(); - - var file = Assert.Single(files); - Assert.Equal("report.csv", file.GetProperty("name").GetString()); - Assert.Equal("Quarterly report", file.GetProperty("title").GetString()); - Assert.Equal("text/csv", file.GetProperty("media_type").GetString()); - Assert.Equal(19, file.GetProperty("length").GetInt64()); - Assert.Equal($"https://blobs.test/{ConversationId}/report.csv?ttl=900", file.GetProperty("url").GetString()); - - // The bytes are in the store, owned by the conversation. - var (mediaType, bytes) = blobs.Store.Blobs[(ConversationId, "report.csv")]; - Assert.Equal("text/csv", mediaType); - Assert.Equal("month,sales\njan,10\n", System.Text.Encoding.UTF8.GetString(bytes)); - - // The model read the link back in its tool result. - var toolResult = events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_tool", out var tool) - && tool.GetProperty("phase").GetString() == "result") - .Select(chunk => chunk.GetProperty("agentcore_tool")) - .Single(); - Assert.False(toolResult.GetProperty("failed").GetBoolean()); - Assert.Equal($"https://blobs.test/{ConversationId}/report.csv?ttl=900", toolResult.GetProperty("result").GetProperty("url").GetString()); - - // And a later read of the transcript links the same file again. - var conversations = host.Services.GetRequiredService(); - var stored = await conversations.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken); - var links = await conversations.LinkFilesAsync(ConversationId, stored.Select(row => row.Content), TestContext.Current.CancellationToken); - - var link = Assert.Single(links); - Assert.Equal((ConversationId, "report.csv", "text/csv", 19L), (link.Blob.OwnerId, link.Blob.Name, link.Blob.MediaType, link.Blob.Length)); - Assert.Equal($"https://blobs.test/{ConversationId}/report.csv?ttl=900", link.Url?.ToString()); - } - - [Fact] - public async Task AToolThatPublishesAMissingFile_TellsTheModelAndWritesNoFilePart() - { - FakeBlobStoreAdapter blobs = new(); - - await using var host = await ResponsesHost.StartAsync( - Yaml, - new PublishingChatClient(), - configure: options => options.UseWorkspace(_root).UseBlobStores(blobs)); - - using var response = await host.PostAsync( - $$"""{ "stream": true, "conversation": "{{ConversationId}}", "input": "send me the report", "agentcore": { "message_id": "m1" } }"""); - var events = await ResponsesHost.ReadEventsAsync(response); - - Assert.DoesNotContain(events, text => text.Contains("agentcore_file", StringComparison.Ordinal)); - - var toolResult = events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_tool", out var tool) - && tool.GetProperty("phase").GetString() == "result") - .Select(chunk => chunk.GetProperty("agentcore_tool")) - .Single(); - Assert.True(toolResult.GetProperty("failed").GetBoolean()); - Assert.Contains("report.csv", toolResult.GetProperty("result").GetProperty("message").GetString(), StringComparison.Ordinal); - Assert.Empty(blobs.Store.Blobs); - } - [Fact] - public async Task APublishToolWithNoBlobStore_FailsTheStartNamingTheToolAndThePort() - { - var yaml = Yaml.Replace("blobs: { kind: fake }", string.Empty, StringComparison.Ordinal); - - var failure = await Assert.ThrowsAsync(() => ResponsesHost.StartAsync( - yaml, - new PublishingChatClient(), - configure: options => options.UseWorkspace(_root))); + public void Dispose() + { + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } + } - Assert.Contains("'publish'", failure.Message, StringComparison.Ordinal); - Assert.Contains("providers.blobs", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AToolThatPublishes_ReachesTheBrowserAsAFilePartAndTheTranscriptLinksItLater() + { + File.WriteAllText(Path.Combine(_root, ConversationId, "report.csv"), "month,sales\njan,10\n"); + FakeBlobStoreAdapter blobs = new(); + + await using ResponsesHost host = await ResponsesHost.StartAsync( + Yaml, + new PublishingChatClient(), + configure: options => options.UseWorkspace(_root).UseBlobStores(blobs)); + + using HttpResponseMessage response = await host.PostAsync( + $$"""{ "stream": true, "conversation": "{{ConversationId}}", "input": "send me the report", "agentcore": { "message_id": "m1" } }"""); + List events = await ResponsesHost.ReadEventsAsync(response); + + List files = [.. events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_file", out JsonElement file) && file.ValueKind != JsonValueKind.Null) + .Select(chunk => chunk.GetProperty("agentcore_file"))]; + + JsonElement file = Assert.Single(files); + Assert.Equal("report.csv", file.GetProperty("name").GetString()); + Assert.Equal("Quarterly report", file.GetProperty("title").GetString()); + Assert.Equal("text/csv", file.GetProperty("media_type").GetString()); + Assert.Equal(19, file.GetProperty("length").GetInt64()); + Assert.Equal($"https://blobs.test/{ConversationId}/report.csv?ttl=900", file.GetProperty("url").GetString()); + + // The bytes are in the store, owned by the conversation. + (string? mediaType, byte[]? bytes) = blobs.Store.Blobs[(ConversationId, "report.csv")]; + Assert.Equal("text/csv", mediaType); + Assert.Equal("month,sales\njan,10\n", System.Text.Encoding.UTF8.GetString(bytes)); + + // The model read the link back in its tool result. + JsonElement toolResult = events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_tool", out JsonElement tool) + && tool.GetProperty("phase").GetString() == "result") + .Select(chunk => chunk.GetProperty("agentcore_tool")) + .Single(); + Assert.False(toolResult.GetProperty("failed").GetBoolean()); + Assert.Equal($"https://blobs.test/{ConversationId}/report.csv?ttl=900", toolResult.GetProperty("result").GetProperty("url").GetString()); + + // And a later read of the transcript links the same file again. + Conversations conversations = host.Services.GetRequiredService(); + IReadOnlyList stored = await conversations.ReadAllAsync(ConversationId, TestContext.Current.CancellationToken); + IReadOnlyList links = await conversations.LinkFilesAsync(ConversationId, stored.Select(row => row.Content), TestContext.Current.CancellationToken); + + FileLink link = Assert.Single(links); + Assert.Equal((ConversationId, "report.csv", "text/csv", 19L), (link.Blob.OwnerId, link.Blob.Name, link.Blob.MediaType, link.Blob.Length)); + Assert.Equal($"https://blobs.test/{ConversationId}/report.csv?ttl=900", link.Url?.ToString()); + } - /// Calls the publish tool it is offered, once, on the report, then answers in words. - private sealed class PublishingChatClient : IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + [Fact] + public async Task AToolThatPublishesAMissingFile_TellsTheModelAndWritesNoFilePart() { - await Task.Yield(); + FakeBlobStoreAdapter blobs = new(); + + await using ResponsesHost host = await ResponsesHost.StartAsync( + Yaml, + new PublishingChatClient(), + configure: options => options.UseWorkspace(_root).UseBlobStores(blobs)); + + using HttpResponseMessage response = await host.PostAsync( + $$"""{ "stream": true, "conversation": "{{ConversationId}}", "input": "send me the report", "agentcore": { "message_id": "m1" } }"""); + List events = await ResponsesHost.ReadEventsAsync(response); + + Assert.DoesNotContain(events, text => text.Contains("agentcore_file", StringComparison.Ordinal)); + + JsonElement toolResult = events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_tool", out JsonElement tool) + && tool.GetProperty("phase").GetString() == "result") + .Select(chunk => chunk.GetProperty("agentcore_tool")) + .Single(); + Assert.True(toolResult.GetProperty("failed").GetBoolean()); + Assert.Contains("report.csv", toolResult.GetProperty("result").GetProperty("message").GetString(), StringComparison.Ordinal); + Assert.Empty(blobs.Store.Blobs); + } - var alreadyPublished = messages.Any(message => message.Contents.OfType().Any()); + [Fact] + public async Task APublishToolWithNoBlobStore_FailsTheStartNamingTheToolAndThePort() + { + string yaml = Yaml.Replace("blobs: { kind: fake }", string.Empty, StringComparison.Ordinal); - if (!alreadyPublished && options?.Tools?.OfType().FirstOrDefault(tool => tool.Name == "publish") is { } publish) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_1", - publish.Name, - new Dictionary(StringComparer.Ordinal) - { - ["path"] = "report.csv", - ["title"] = "Quarterly report", - })]); - yield break; - } + ConfigurationLoadException failure = await Assert.ThrowsAsync(() => ResponsesHost.StartAsync( + yaml, + new PublishingChatClient(), + configure: options => options.UseWorkspace(_root))); - yield return new ChatResponseUpdate(ChatRole.Assistant, "here is the report."); + Assert.Contains("'publish'", failure.Message, StringComparison.Ordinal); + Assert.Contains("providers.blobs", failure.Message, StringComparison.Ordinal); } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) + /// Calls the publish tool it is offered, once, on the report, then answers in words. + private sealed class PublishingChatClient : IChatClient { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken).ConfigureAwait(false)) + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) { - updates.Add(update); + await Task.Yield(); + + bool alreadyPublished = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyPublished && options?.Tools?.OfType().FirstOrDefault(tool => tool.Name == "publish") is { } publish) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_1", + publish.Name, + new Dictionary(StringComparer.Ordinal) + { + ["path"] = "report.csv", + ["title"] = "Quarterly report", + })]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "here is the report."); } - return updates.ToChatResponse(); - } + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken).ConfigureAwait(false)) + { + updates.Add(update); + } - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + return updates.ToChatResponse(); + } - public void Dispose() - { + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs index 0c253de7..e9b4b1fe 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs @@ -5,20 +5,20 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// -/// The Responses path: one request runs one turn, and the continuation carries the conversation. -/// -/// -/// Every test here runs offline against a fake model. The two-stage document names the -/// stage in each reply, so the text proves which stage spoke: there is no subtler -/// assertion about continuity than the second turn answering with the second agent. -/// -public sealed class ResponsesTests +namespace AgentCore.AspNetCore.Tests.Endpoints { - private const string TwoStagesYaml = - """ + /// + /// The Responses path: one request runs one turn, and the continuation carries the conversation. + /// + /// + /// Every test here runs offline against a fake model. The two-stage document names the + /// stage in each reply, so the text proves which stage spoke: there is no subtler + /// assertion about continuity than the second turn answering with the second agent. + /// + public sealed class ResponsesTests + { + private const string TwoStagesYaml = + """ apiVersion: agentcore/v1 guards: second: { ">=": [ { var: turnIndex }, 1 ] } @@ -45,346 +45,348 @@ public sealed class ResponsesTests - { kind: openai, model: gpt-4.1-mini, as: reply } """; - [Fact] - public async Task FirstTurn_MintsConversationAndAnswersStageOne() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var response = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - var body = await ResponsesHost.ReadJsonAsync(response); - Assert.Contains("answer one", body.OutputText(), StringComparison.Ordinal); - Assert.StartsWith("conv_", body.ContinuationId(), StringComparison.Ordinal); - Assert.StartsWith("resp_", body["id"]?.GetValue(), StringComparison.Ordinal); - } - - [Fact] - public async Task SecondTurnOnConversation_ContinuesStageAndTranscript() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var first = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - var convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); - var firstRequest = reply.LastRequest; - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - var body = await ResponsesHost.ReadJsonAsync(second); - Assert.Contains("answer two", body.OutputText(), StringComparison.Ordinal); - - var secondRequest = reply.LastRequest; - Assert.NotNull(secondRequest); - Assert.Contains(secondRequest, m => m.Text.Contains("first question", StringComparison.Ordinal)); - Assert.Contains(secondRequest, m => m.Text.Contains("answer one", StringComparison.Ordinal)); - Assert.NotSame(firstRequest, secondRequest); - } - - [Fact] - public async Task SecondTurnOnResponseChain_ContinuesStage() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var first = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - var respId = (await ResponsesHost.ReadJsonAsync(first))["id"]?.GetValue(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "previous_response_id": "{{respId}}", "input": "chained question" }"""); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - var body = await ResponsesHost.ReadJsonAsync(second); - Assert.Contains("answer two", body.OutputText(), StringComparison.Ordinal); - } - - [Fact] - public async Task SecondTurnStreams_StillContinuesStage() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var first = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - var convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); - - using var second = await host.PostAsync( - $$"""{ "stream": true, "conversation": "{{convId}}", "input": "second question" }"""); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - Assert.Equal("text/event-stream", second.Content.Headers.ContentType?.MediaType); - var text = await ResponsesHost.ReadTextAsync(second); - Assert.Contains("answer two", text, StringComparison.Ordinal); - } - - [Fact] - public async Task UnknownConversation_StartsTheConversationUnderThatId() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var first = await host.PostAsync( - """{ "stream": false, "conversation": "thread-7", "input": "first question" }"""); - - Assert.Equal(HttpStatusCode.OK, first.StatusCode); - var firstBody = await ResponsesHost.ReadJsonAsync(first); - Assert.Equal("thread-7", firstBody.ContinuationId()); - Assert.Equal("thread-7", firstBody["metadata"]!["call_id"]!.GetValue()); - - using var second = await host.PostAsync( - """{ "stream": false, "conversation": "thread-7", "input": "second question" }"""); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - Assert.Contains("answer two", (await ResponsesHost.ReadJsonAsync(second)).OutputText(), StringComparison.Ordinal); - } - - [Fact] - public async Task UnknownResponseId_ReturnsNotFound() - { - using FragmentingChatClient reply = new("answer one"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var response = await host.PostAsync( - """{ "stream": false, "previous_response_id": "resp_doesnotexist", "input": "hello" }"""); - - Assert.Equal(HttpStatusCode.NotFound, response.StatusCode); - } - - [Fact] - public async Task MalformedBody_ReturnsBadRequest() - { - using FragmentingChatClient reply = new("answer one"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var response = await host.PostAsync("""{ "stream": false, "input": """); - - Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); - } - - [Fact] - public async Task MissingInput_ReturnsBadRequest() - { - using FragmentingChatClient reply = new("answer one"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var response = await host.PostAsync("""{ "stream": false }"""); - - Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); - } - [Fact] - public async Task FirstTurn_MetadataCarriesTurnFacts() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var response = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - var body = await ResponsesHost.ReadJsonAsync(response); - var metadata = body["metadata"]!.AsObject(); - Assert.Equal("0", metadata["turn_index"]!.GetValue()); - // The commit advances on the post-increment index, so the first turn already leaves talking. - Assert.Equal("talking", metadata["stage_before"]!.GetValue()); - Assert.Equal("followup", metadata["stage_after"]!.GetValue()); - Assert.Equal("false", metadata["is_terminal"]!.GetValue()); - Assert.False(string.IsNullOrEmpty(metadata["call_id"]!.GetValue())); - Assert.False(string.IsNullOrEmpty(metadata["message_id"]!.GetValue())); - Assert.Null(body["metadata"]!["approvals"]); - Assert.Equal("followup", Assert.Single(response.Headers.GetValues("X-AgentCore-Stage"))); - } - - [Fact] - public async Task SecondTurn_MetadataAdvancesWithTheStage() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var first = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - var convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); - - var metadata = (await ResponsesHost.ReadJsonAsync(second))["metadata"]!.AsObject(); - Assert.Equal("1", metadata["turn_index"]!.GetValue()); - // The second turn speaks in followup and its post-increment index trips the third guard back. - Assert.Equal("followup", metadata["stage_before"]!.GetValue()); - Assert.Equal("talking", metadata["stage_after"]!.GetValue()); - } - - [Fact] - public async Task TerminalTurn_SignalsTerminalAndRefusesTheNext() - { - using FragmentingChatClient reply = new("answer one"); - await using var host = await ResponsesHost.StartAsync(TerminalYaml, reply); - - using var first = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - var body = await ResponsesHost.ReadJsonAsync(first); - Assert.Equal("true", body["metadata"]!["is_terminal"]!.GetValue()); - var convId = body.ContinuationId(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); - - Assert.Equal(HttpStatusCode.Conflict, second.StatusCode); - } - - [Fact] - public async Task GatedToolCall_AnswersWholeWithTheRequestInMetadata() - { - int sent = 0; - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); - - using var response = await host.PostAsync("""{ "stream": false, "input": "send it" }"""); - var body = await ResponsesHost.ReadJsonAsync(response); - - Assert.Equal(string.Empty, body.OutputText()); - var approvals = body["metadata"]!["approvals"]!.GetValue(); - Assert.Contains("send_email", approvals, StringComparison.Ordinal); - Assert.Equal(0, sent); - } - - [Fact] - public async Task ApprovalAnswer_RunsTheToolAndReplies() - { - int sent = 0; - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); - - using var first = await host.PostAsync("""{ "stream": false, "input": "send it" }"""); - var asked = await ResponsesHost.ReadJsonAsync(first); - var convId = asked.ContinuationId(); - var requestId = System.Text.Json.JsonDocument.Parse( - asked["metadata"]!["approvals"]!.GetValue()) - .RootElement[0].GetProperty("request_id").GetString(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": [], "agentcore": { "approval": { "request_id": "{{requestId}}", "approved": true } } }"""); - var replied = await ResponsesHost.ReadJsonAsync(second); - - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - Assert.Equal(1, sent); - Assert.Contains("done.", replied.OutputText(), StringComparison.Ordinal); - } - - [Fact] - public async Task ApprovalAnswerForARequestNothingAsked_IsConflict() - { - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); - - using var first = await host.PostAsync("""{ "stream": false, "input": "send it" }"""); - var convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": [], "agentcore": { "approval": { "request_id": "req-nothing-asked", "approved": true } } }"""); - - Assert.Equal(HttpStatusCode.Conflict, second.StatusCode); - } - - [Fact] - public async Task ApprovalAnswerWithWords_IsBadRequest() - { - await using var host = await ResponsesHost.StartAsync( - ApprovalYaml, - new GatedToolCallingChatClient(), - configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); - - using var first = await host.PostAsync("""{ "stream": false, "input": "send it" }"""); - var convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": "send it", "agentcore": { "approval": { "request_id": "req-1", "approved": true } } }"""); - - Assert.Equal(HttpStatusCode.BadRequest, second.StatusCode); - } - - [Fact] - public async Task EditAtAnEarlierMessage_WithdrawsTheWordsAfterIt() - { - using FragmentingChatClient reply = new("answer one", "answer two"); - await using var host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); - - using var first = await host.PostAsync("""{ "stream": false, "input": "first question" }"""); - var firstBody = await ResponsesHost.ReadJsonAsync(first); - var convId = firstBody.ContinuationId(); - var anchor = firstBody["metadata"]!["message_id"]!.GetValue(); - - using var second = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); - Assert.Equal(HttpStatusCode.OK, second.StatusCode); - - // Hanging the third turn off the first reply takes back everything after it: the model - // sees the first exchange and the corrected words, but never the withdrawn question. - using var third = await host.PostAsync( - $$"""{ "stream": false, "conversation": "{{convId}}", "input": "corrected question", "agentcore": { "message_id": "q3", "parent_id": "{{anchor}}" } }"""); - Assert.Equal(HttpStatusCode.OK, third.StatusCode); - var thirdRequest = reply.LastRequest; - Assert.NotNull(thirdRequest); - Assert.Contains(thirdRequest, m => m.Text.Contains("first question", StringComparison.Ordinal)); - Assert.DoesNotContain(thirdRequest, m => m.Text.Contains("second question", StringComparison.Ordinal)); - Assert.Contains(thirdRequest, m => m.Text.Contains("corrected question", StringComparison.Ordinal)); - } - - [Fact] - public async Task DialectStream_WritesRendersAsTheirOwnEvents() - { - await using var host = await ResponsesHost.StartAsync( - RenderYaml, - new RenderChatClient(), - configure: options => options.Bind("DrawIt", (AgentCore.Application.Runtime.TurnInvocation? turn) => - { - turn?.Screen?.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); - return ValueTask.FromResult("drew a Card; buttons: none"); - })); - - using var response = await host.PostAsync( - """{ "stream": true, "input": "show me revenue", "agentcore": { "message_id": "m1" } }"""); - var events = await ResponsesHost.ReadEventsAsync(response); - - var chunks = events - .Select(text => System.Text.Json.JsonDocument.Parse(text).RootElement) - .ToList(); - var drawing = Assert.Single(chunks, static chunk => chunk.TryGetProperty("agentcore_data", out var data) - && data.ValueKind != System.Text.Json.JsonValueKind.Null); - Assert.Equal("generative-ui", drawing.GetProperty("agentcore_data").GetProperty("name").GetString()); - Assert.Equal( - "Q3 revenue", - drawing.GetProperty("agentcore_data").GetProperty("data").GetProperty("title").GetString()); - } - - [Fact] - public async Task PureStream_WritesNoDialectEvents() - { - await using var host = await ResponsesHost.StartAsync( - RenderYaml, - new RenderChatClient(), - configure: options => options.Bind("DrawIt", (AgentCore.Application.Runtime.TurnInvocation? turn) => - { - turn?.Screen?.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); - return ValueTask.FromResult("drew a Card; buttons: none"); - })); - - using var response = await host.PostAsync("""{ "stream": true, "input": "show me revenue" }"""); - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - var events = await ResponsesHost.ReadEventsAsync(response); - - Assert.DoesNotContain(events - .Select(text => System.Text.Json.JsonDocument.Parse(text).RootElement), - static chunk => chunk.TryGetProperty("agentcore_data", out var data) - && data.ValueKind != System.Text.Json.JsonValueKind.Null); - } - private const string TerminalYaml = - """ + [Fact] + public async Task FirstTurn_MintsConversationAndAnswersStageOne() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage response = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + JsonNode body = await ResponsesHost.ReadJsonAsync(response); + Assert.Contains("answer one", body.OutputText(), StringComparison.Ordinal); + Assert.StartsWith("conv_", body.ContinuationId(), StringComparison.Ordinal); + Assert.StartsWith("resp_", body["id"]?.GetValue(), StringComparison.Ordinal); + } + + [Fact] + public async Task SecondTurnOnConversation_ContinuesStageAndTranscript() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + string convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); + IReadOnlyList? firstRequest = reply.LastRequest; + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + JsonNode body = await ResponsesHost.ReadJsonAsync(second); + Assert.Contains("answer two", body.OutputText(), StringComparison.Ordinal); + + IReadOnlyList? secondRequest = reply.LastRequest; + Assert.NotNull(secondRequest); + Assert.Contains(secondRequest, m => m.Text.Contains("first question", StringComparison.Ordinal)); + Assert.Contains(secondRequest, m => m.Text.Contains("answer one", StringComparison.Ordinal)); + Assert.NotSame(firstRequest, secondRequest); + } + + [Fact] + public async Task SecondTurnOnResponseChain_ContinuesStage() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + string? respId = (await ResponsesHost.ReadJsonAsync(first))["id"]?.GetValue(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "previous_response_id": "{{respId}}", "input": "chained question" }"""); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + JsonNode body = await ResponsesHost.ReadJsonAsync(second); + Assert.Contains("answer two", body.OutputText(), StringComparison.Ordinal); + } + + [Fact] + public async Task SecondTurnStreams_StillContinuesStage() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + string convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": true, "conversation": "{{convId}}", "input": "second question" }"""); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.Equal("text/event-stream", second.Content.Headers.ContentType?.MediaType); + string text = await ResponsesHost.ReadTextAsync(second); + Assert.Contains("answer two", text, StringComparison.Ordinal); + } + + [Fact] + public async Task UnknownConversation_StartsTheConversationUnderThatId() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage first = await host.PostAsync( + /*lang=json,strict*/ + """{ "stream": false, "conversation": "thread-7", "input": "first question" }"""); + + Assert.Equal(HttpStatusCode.OK, first.StatusCode); + JsonNode firstBody = await ResponsesHost.ReadJsonAsync(first); + Assert.Equal("thread-7", firstBody.ContinuationId()); + Assert.Equal("thread-7", firstBody["metadata"]!["call_id"]!.GetValue()); + + using HttpResponseMessage second = await host.PostAsync( + /*lang=json,strict*/ + """{ "stream": false, "conversation": "thread-7", "input": "second question" }"""); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.Contains("answer two", (await ResponsesHost.ReadJsonAsync(second)).OutputText(), StringComparison.Ordinal); + } + + [Fact] + public async Task UnknownResponseId_ReturnsNotFound() + { + using FragmentingChatClient reply = new("answer one"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage response = await host.PostAsync( + /*lang=json,strict*/ + """{ "stream": false, "previous_response_id": "resp_doesnotexist", "input": "hello" }"""); + + Assert.Equal(HttpStatusCode.NotFound, response.StatusCode); + } + + [Fact] + public async Task MalformedBody_ReturnsBadRequest() + { + using FragmentingChatClient reply = new("answer one"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage response = await host.PostAsync("""{ "stream": false, "input": """); + + Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); + } + + [Fact] + public async Task MissingInput_ReturnsBadRequest() + { + using FragmentingChatClient reply = new("answer one"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage response = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false }"""); + + Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); + } + [Fact] + public async Task FirstTurn_MetadataCarriesTurnFacts() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage response = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + JsonNode body = await ResponsesHost.ReadJsonAsync(response); + JsonObject metadata = body["metadata"]!.AsObject(); + Assert.Equal("0", metadata["turn_index"]!.GetValue()); + // The commit advances on the post-increment index, so the first turn already leaves talking. + Assert.Equal("talking", metadata["stage_before"]!.GetValue()); + Assert.Equal("followup", metadata["stage_after"]!.GetValue()); + Assert.Equal("false", metadata["is_terminal"]!.GetValue()); + Assert.False(string.IsNullOrEmpty(metadata["call_id"]!.GetValue())); + Assert.False(string.IsNullOrEmpty(metadata["message_id"]!.GetValue())); + Assert.Null(body["metadata"]!["approvals"]); + Assert.Equal("followup", Assert.Single(response.Headers.GetValues("X-AgentCore-Stage"))); + } + + [Fact] + public async Task SecondTurn_MetadataAdvancesWithTheStage() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + string convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); + + JsonObject metadata = (await ResponsesHost.ReadJsonAsync(second))["metadata"]!.AsObject(); + Assert.Equal("1", metadata["turn_index"]!.GetValue()); + // The second turn speaks in followup and its post-increment index trips the third guard back. + Assert.Equal("followup", metadata["stage_before"]!.GetValue()); + Assert.Equal("talking", metadata["stage_after"]!.GetValue()); + } + + [Fact] + public async Task TerminalTurn_SignalsTerminalAndRefusesTheNext() + { + using FragmentingChatClient reply = new("answer one"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TerminalYaml, reply); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + JsonNode body = await ResponsesHost.ReadJsonAsync(first); + Assert.Equal("true", body["metadata"]!["is_terminal"]!.GetValue()); + string convId = body.ContinuationId(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); + + Assert.Equal(HttpStatusCode.Conflict, second.StatusCode); + } + + [Fact] + public async Task GatedToolCall_AnswersWholeWithTheRequestInMetadata() + { + int sent = 0; + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); + + using HttpResponseMessage response = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "send it" }"""); + JsonNode body = await ResponsesHost.ReadJsonAsync(response); + + Assert.Equal(string.Empty, body.OutputText()); + string approvals = body["metadata"]!["approvals"]!.GetValue(); + Assert.Contains("send_email", approvals, StringComparison.Ordinal); + Assert.Equal(0, sent); + } + + [Fact] + public async Task ApprovalAnswer_RunsTheToolAndReplies() + { + int sent = 0; + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => sent++)))); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "send it" }"""); + JsonNode asked = await ResponsesHost.ReadJsonAsync(first); + string convId = asked.ContinuationId(); + string? requestId = JsonDocument.Parse( + asked["metadata"]!["approvals"]!.GetValue()) + .RootElement[0].GetProperty("request_id").GetString(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": [], "agentcore": { "approval": { "request_id": "{{requestId}}", "approved": true } } }"""); + JsonNode replied = await ResponsesHost.ReadJsonAsync(second); + + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.Equal(1, sent); + Assert.Contains("done.", replied.OutputText(), StringComparison.Ordinal); + } + + [Fact] + public async Task ApprovalAnswerForARequestNothingAsked_IsConflict() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "send it" }"""); + string convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": [], "agentcore": { "approval": { "request_id": "req-nothing-asked", "approved": true } } }"""); + + Assert.Equal(HttpStatusCode.Conflict, second.StatusCode); + } + + [Fact] + public async Task ApprovalAnswerWithWords_IsBadRequest() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ApprovalYaml, + new GatedToolCallingChatClient(), + configure: options => options.AddToolSource(_ => new GatedSource(() => GatedSendEmail(() => { })))); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "send it" }"""); + string convId = (await ResponsesHost.ReadJsonAsync(first)).ContinuationId(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": "send it", "agentcore": { "approval": { "request_id": "req-1", "approved": true } } }"""); + + Assert.Equal(HttpStatusCode.BadRequest, second.StatusCode); + } + + [Fact] + public async Task EditAtAnEarlierMessage_WithdrawsTheWordsAfterIt() + { + using FragmentingChatClient reply = new("answer one", "answer two"); + await using ResponsesHost host = await ResponsesHost.StartAsync(TwoStagesYaml, reply); + + using HttpResponseMessage first = await host.PostAsync(/*lang=json,strict*/ """{ "stream": false, "input": "first question" }"""); + JsonNode firstBody = await ResponsesHost.ReadJsonAsync(first); + string convId = firstBody.ContinuationId(); + string anchor = firstBody["metadata"]!["message_id"]!.GetValue(); + + using HttpResponseMessage second = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": "second question" }"""); + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + + // Hanging the third turn off the first reply takes back everything after it: the model + // sees the first exchange and the corrected words, but never the withdrawn question. + using HttpResponseMessage third = await host.PostAsync( + $$"""{ "stream": false, "conversation": "{{convId}}", "input": "corrected question", "agentcore": { "message_id": "q3", "parent_id": "{{anchor}}" } }"""); + Assert.Equal(HttpStatusCode.OK, third.StatusCode); + IReadOnlyList? thirdRequest = reply.LastRequest; + Assert.NotNull(thirdRequest); + Assert.Contains(thirdRequest, m => m.Text.Contains("first question", StringComparison.Ordinal)); + Assert.DoesNotContain(thirdRequest, m => m.Text.Contains("second question", StringComparison.Ordinal)); + Assert.Contains(thirdRequest, m => m.Text.Contains("corrected question", StringComparison.Ordinal)); + } + + [Fact] + public async Task DialectStream_WritesRendersAsTheirOwnEvents() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + RenderYaml, + new RenderChatClient(), + configure: options => options.Bind("DrawIt", (Application.Runtime.TurnInvocation? turn) => + { + turn?.Screen?.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); + return ValueTask.FromResult("drew a Card; buttons: none"); + })); + + using HttpResponseMessage response = await host.PostAsync( + /*lang=json,strict*/ + """{ "stream": true, "input": "show me revenue", "agentcore": { "message_id": "m1" } }"""); + List events = await ResponsesHost.ReadEventsAsync(response); + + List chunks = [.. events.Select(text => JsonDocument.Parse(text).RootElement)]; + JsonElement drawing = Assert.Single(chunks, static chunk => chunk.TryGetProperty("agentcore_data", out JsonElement data) + && data.ValueKind != JsonValueKind.Null); + Assert.Equal("generative-ui", drawing.GetProperty("agentcore_data").GetProperty("name").GetString()); + Assert.Equal( + "Q3 revenue", + drawing.GetProperty("agentcore_data").GetProperty("data").GetProperty("title").GetString()); + } + + [Fact] + public async Task PureStream_WritesNoDialectEvents() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + RenderYaml, + new RenderChatClient(), + configure: options => options.Bind("DrawIt", (Application.Runtime.TurnInvocation? turn) => + { + turn?.Screen?.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); + return ValueTask.FromResult("drew a Card; buttons: none"); + })); + + using HttpResponseMessage response = await host.PostAsync(/*lang=json,strict*/ """{ "stream": true, "input": "show me revenue" }"""); + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + List events = await ResponsesHost.ReadEventsAsync(response); + + Assert.DoesNotContain(events + .Select(text => JsonDocument.Parse(text).RootElement), + static chunk => chunk.TryGetProperty("agentcore_data", out JsonElement data) + && data.ValueKind != JsonValueKind.Null); + } + private const string TerminalYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -406,8 +408,8 @@ public async Task PureStream_WritesNoDialectEvents() - { kind: openai, model: gpt-4.1-mini, as: reply } """; - private const string ApprovalYaml = - """ + private const string ApprovalYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -426,8 +428,8 @@ public async Task PureStream_WritesNoDialectEvents() agent: greeter """; - private const string RenderYaml = - """ + private const string RenderYaml = + """ apiVersion: agentcore/v1 tools: - id: draw_it @@ -456,148 +458,156 @@ public async Task PureStream_WritesNoDialectEvents() - { kind: openai, model: gpt-4.1-mini, as: reply } """; - private static Microsoft.Extensions.AI.ApprovalRequiredAIFunction GatedSendEmail(Action onSend) => - new(Microsoft.Extensions.AI.AIFunctionFactory.Create( - (string to) => - { - onSend(); - return "sent"; - }, - "send_email", - "Send an email.")); - - /// A tool source that serves one gated id, standing in for an approval-required host tool. - private sealed class GatedSource(Func build) - : AgentCore.Application.Ports.IToolSource - { - public ValueTask> ProvideAsync( - AgentCore.Application.Tools.Registry.ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>( - [new AgentCore.Application.Tools.Registry.ToolRegistration("send_email", "Send an email.", build)]); - } - - /// Calls the first tool it is offered, once, then answers in words. - private sealed class GatedToolCallingChatClient : Microsoft.Extensions.AI.IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - Microsoft.Extensions.AI.ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - var alreadyCalled = messages.Any(message => message.Contents.OfType().Any()); - - if (!alreadyCalled && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new Microsoft.Extensions.AI.ChatResponseUpdate( - Microsoft.Extensions.AI.ChatRole.Assistant, - [new Microsoft.Extensions.AI.FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" })]); - yield break; - } - - yield return new Microsoft.Extensions.AI.ChatResponseUpdate(Microsoft.Extensions.AI.ChatRole.Assistant, "done."); - } - - public async Task GetResponseAsync( - IEnumerable messages, - Microsoft.Extensions.AI.ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - - public void Dispose() - { - } - } - - /// Calls the first tool it is offered, once, then answers in words. - private sealed class RenderChatClient : Microsoft.Extensions.AI.IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - Microsoft.Extensions.AI.ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - var alreadyDrew = messages.Any(message => message.Contents.OfType().Any()); - - if (!alreadyDrew && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new Microsoft.Extensions.AI.ChatResponseUpdate( - Microsoft.Extensions.AI.ChatRole.Assistant, - [new Microsoft.Extensions.AI.FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["what"] = "a card" })]); - yield break; - } - - yield return new Microsoft.Extensions.AI.ChatResponseUpdate(Microsoft.Extensions.AI.ChatRole.Assistant, "here it is."); - } - - public async Task GetResponseAsync( - IEnumerable messages, - Microsoft.Extensions.AI.ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - - public void Dispose() - { - } - } - } - - /// Reads what one Responses answer carries. - internal static class ResponsesAnswer - { - /// Reads the assistant text of one answer. - /// The answer. - /// Every output text, joined. - internal static string OutputText(this JsonNode body) - => string.Join("", body["output"]?.AsArray() - .SelectMany(o => o?["content"]?.AsArray() ?? []) - .Select(c => c?["text"]?.GetValue() ?? "") ?? []); - - /// Reads the id a later turn hangs off: the conversation, or the response. - /// The answer. - /// The continuation id. - internal static string ContinuationId(this JsonNode body) - { - if (body["conversation"] is JsonObject conversation - && conversation["id"]?.GetValue() is { Length: > 0 } conversationId) - { - return conversationId; - } - - return body["id"]?.GetValue() - ?? throw new InvalidOperationException("Answer carries no continuation id."); - } - } + private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) + { + return new(AIFunctionFactory.Create( + (string to) => + { + onSend(); + return "sent"; + }, + "send_email", + "Send an email.")); + } + + /// A tool source that serves one gated id, standing in for an approval-required host tool. + private sealed class GatedSource(Func build) + : Application.Ports.IToolSource + { + public ValueTask> ProvideAsync( + Application.Tools.Registry.ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>( + [new Application.Tools.Registry.ToolRegistration("send_email", "Send an email.", build)]); + } + } + + /// Calls the first tool it is offered, once, then answers in words. + private sealed class GatedToolCallingChatClient : IChatClient + { + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + + bool alreadyCalled = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyCalled && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_1", + tool.Name, + new Dictionary(StringComparer.Ordinal) { ["to"] = "a@b.com" })]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "done."); + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } + } + + /// Calls the first tool it is offered, once, then answers in words. + private sealed class RenderChatClient : IChatClient + { + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + + bool alreadyDrew = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyDrew && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_1", + tool.Name, + new Dictionary(StringComparer.Ordinal) { ["what"] = "a card" })]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "here it is."); + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } + } + } + + /// Reads what one Responses answer carries. + internal static class ResponsesAnswer + { + /// Reads the assistant text of one answer. + /// The answer. + /// Every output text, joined. + internal static string OutputText(this JsonNode body) + { + return string.Join("", body["output"]?.AsArray() + .SelectMany(o => o?["content"]?.AsArray() ?? []) + .Select(c => c?["text"]?.GetValue() ?? "") ?? []); + } + + /// Reads the id a later turn hangs off: the conversation, or the response. + /// The answer. + /// The continuation id. + internal static string ContinuationId(this JsonNode body) + { + return body["conversation"] is JsonObject conversation + && conversation["id"]?.GetValue() is { Length: > 0 } conversationId + ? conversationId + : body["id"]?.GetValue() + ?? throw new InvalidOperationException("Answer carries no continuation id."); + } + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs index b853d9c6..eb083014 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs @@ -6,20 +6,20 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// -/// The whole wire a source travels: a producer, the conversation's sources, and one extra SSE field. -/// -/// -/// Retrieval is the first producer of a source and this test deliberately does not use it. The -/// channel belongs to anything that can name what it read, so what is proved here is that a plain -/// bound tool can cite one and have it reach the browser. -/// -public sealed class SourceWireTests +namespace AgentCore.AspNetCore.Tests.Endpoints { - private const string SourceYaml = - """ + /// + /// The whole wire a source travels: a producer, the conversation's sources, and one extra SSE field. + /// + /// + /// Retrieval is the first producer of a source and this test deliberately does not use it. The + /// channel belongs to anything that can name what it read, so what is proved here is that a plain + /// bound tool can cite one and have it reach the browser. + /// + public sealed class SourceWireTests + { + private const string SourceYaml = + """ apiVersion: agentcore/v1 tools: - id: look_it_up @@ -48,228 +48,233 @@ public sealed class SourceWireTests - { kind: openai, model: gpt-4.1-mini, as: reply } """; - [Fact] - public async Task AToolThatCites_ReachesTheBrowserOnItsOwnFieldAndNotInTheReply() - { - await using var host = await ResponsesHost.StartAsync( - SourceYaml, - new SourceCitingChatClient(), - configure: options => options.Bind("LookItUp", (TurnInvocation? turn) => - { - turn?.Sources?.Publish(new SourceReference - { - SourceId = "card-42", - Kind = SourceKind.Document, - Title = "Spirit CT900 owner's manual", - Origin = "knowledge", - Locator = "p.27", - }); - - return ValueTask.FromResult("E03 is an overcurrent trip."); - })); - - using var response = await PostStreamAsync(host, "what is E03"); - var events = await ResponsesHost.ReadEventsAsync(response); - - var cited = events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_source", out var source) - && source.ValueKind != JsonValueKind.Null) - .ToList(); - - var chunk = Assert.Single(cited).GetProperty("agentcore_source"); - - Assert.Equal("card-42", chunk.GetProperty("id").GetString()); - Assert.Equal("document", chunk.GetProperty("source_type").GetString()); - Assert.Equal("Spirit CT900 owner's manual", chunk.GetProperty("title").GetString()); - Assert.Equal("p.27", chunk.GetProperty("locator").GetString()); - Assert.Equal("knowledge", chunk.GetProperty("origin").GetString()); - Assert.False(string.IsNullOrEmpty(chunk.GetProperty("call_id").GetString())); - - // And it is not in what the caller is told. The spoken reply is what the transcript keeps. - var spoken = string.Concat(ResponsesHost.TextDeltas(events)); - - Assert.DoesNotContain("card-42", spoken, StringComparison.Ordinal); - } - - [Fact] - public async Task AToolThatCitesNothing_WritesNoSourceField() - { - await using var host = await ResponsesHost.StartAsync( - SourceYaml, - new SourceCitingChatClient(), - configure: options => options.Bind("LookItUp", (_, _) => - ValueTask.FromResult("nothing to cite"))); - - using var response = await PostStreamAsync(host, "what is E03"); - var events = await ResponsesHost.ReadEventsAsync(response); - - Assert.DoesNotContain(events, text => text.Contains("agentcore_source", StringComparison.Ordinal)); - } - - [Fact] - public async Task AToolThatCitesUnderTwoParallelCalls_StampsEachSourceWithItsOwnCallId() - { - // FunctionInvokingChatClient batches every parallel call's results of one round onto ONE - // message (and this endpoint turns that message into ONE update), so a fix that reads the - // call id off "the first FunctionResultContent on the update" rather than off the source - // itself would silently stamp the second source with the first conversation's id. This is the - // regression test for exactly that. - await using var host = await ResponsesHost.StartAsync( - SourceYaml, - new TwoParallelConversationsChatClient(), - configure: options => options.Bind("LookItUp", (string? what, TurnInvocation? turn) => - { - turn?.Sources?.Publish(new SourceReference - { - SourceId = what == "left" ? "card-left" : "card-right", - Kind = SourceKind.Document, - Title = what == "left" ? "Left manual" : "Right manual", - Origin = "knowledge", - }); - - return ValueTask.FromResult("looked up " + what); - })); - - using var response = await PostStreamAsync(host, "what is E03"); - var events = await ResponsesHost.ReadEventsAsync(response); - - var cited = events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_source", out var source) - && source.ValueKind != JsonValueKind.Null) - .Select(chunk => chunk.GetProperty("agentcore_source")) - .ToList(); - - Assert.Equal(2, cited.Count); - - var left = Assert.Single(cited, source => source.GetProperty("id").GetString() == "card-left"); - var right = Assert.Single(cited, source => source.GetProperty("id").GetString() == "card-right"); - - Assert.Equal("conversation_1", left.GetProperty("call_id").GetString()); - Assert.Equal("conversation_2", right.GetProperty("call_id").GetString()); - } - - /// Sends one turn of words and reads the answer as it arrives. - /// - /// The dialect member opts the stream into the browser parts: without it the frames carry - /// text alone and a citation would never reach the browser. - /// - private static Task PostStreamAsync(ResponsesHost host, string text, string? conversation = null) - => host.PostAsync(conversation is { Length: > 0 } - ? $$"""{ "stream": true, "conversation": "{{conversation}}", "input": "{{text}}", "agentcore": { "message_id": "m1" } }""" - : $$"""{ "stream": true, "input": "{{text}}", "agentcore": { "message_id": "m1" } }"""); - - /// Calls the first tool it is offered, once, then answers in words. - /// - /// Copied from the render chat client in ResponsesTests — that class is private to its own file, - /// so this test needs its own copy of the same shape rather than sharing the type. - /// - private sealed class SourceCitingChatClient : IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - var alreadyCited = messages.Any(message => message.Contents.OfType().Any()); - - if (!alreadyCited && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["what"] = "E03" })]); - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, "it is an overcurrent trip."); - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - - public void Dispose() - { - } - } - - /// Calls the tool it is offered twice in one round — two parallel calls — then answers in words. - /// - /// This is the shape a real model routinely produces and the single-conversation fakes above cannot - /// exercise: FunctionInvokingChatClient batches both tool results of one round onto ONE - /// message before this endpoint ever sees it. - /// - private sealed class TwoParallelConversationsChatClient : IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - var alreadyCited = messages.Any(message => message.Contents.OfType().Any()); - - if (!alreadyCited && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [ - new FunctionCallContent( + [Fact] + public async Task AToolThatCites_ReachesTheBrowserOnItsOwnFieldAndNotInTheReply() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + SourceYaml, + new SourceCitingChatClient(), + configure: options => options.Bind("LookItUp", (TurnInvocation? turn) => + { + turn?.Sources?.Publish(new SourceReference + { + SourceId = "card-42", + Kind = SourceKind.Document, + Title = "Spirit CT900 owner's manual", + Origin = "knowledge", + Locator = "p.27", + }); + + return ValueTask.FromResult("E03 is an overcurrent trip."); + })); + + using HttpResponseMessage response = await PostStreamAsync(host, "what is E03"); + List events = await ResponsesHost.ReadEventsAsync(response); + + List cited = [.. events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_source", out JsonElement source) + && source.ValueKind != JsonValueKind.Null)]; + + JsonElement chunk = Assert.Single(cited).GetProperty("agentcore_source"); + + Assert.Equal("card-42", chunk.GetProperty("id").GetString()); + Assert.Equal("document", chunk.GetProperty("source_type").GetString()); + Assert.Equal("Spirit CT900 owner's manual", chunk.GetProperty("title").GetString()); + Assert.Equal("p.27", chunk.GetProperty("locator").GetString()); + Assert.Equal("knowledge", chunk.GetProperty("origin").GetString()); + Assert.False(string.IsNullOrEmpty(chunk.GetProperty("call_id").GetString())); + + // And it is not in what the caller is told. The spoken reply is what the transcript keeps. + string spoken = string.Concat(ResponsesHost.TextDeltas(events)); + + Assert.DoesNotContain("card-42", spoken, StringComparison.Ordinal); + } + + [Fact] + public async Task AToolThatCitesNothing_WritesNoSourceField() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + SourceYaml, + new SourceCitingChatClient(), + configure: options => options.Bind("LookItUp", (_, _) => + ValueTask.FromResult("nothing to cite"))); + + using HttpResponseMessage response = await PostStreamAsync(host, "what is E03"); + List events = await ResponsesHost.ReadEventsAsync(response); + + Assert.DoesNotContain(events, text => text.Contains("agentcore_source", StringComparison.Ordinal)); + } + + [Fact] + public async Task AToolThatCitesUnderTwoParallelCalls_StampsEachSourceWithItsOwnCallId() + { + // FunctionInvokingChatClient batches every parallel call's results of one round onto ONE + // message (and this endpoint turns that message into ONE update), so a fix that reads the + // call id off "the first FunctionResultContent on the update" rather than off the source + // itself would silently stamp the second source with the first conversation's id. This is the + // regression test for exactly that. + await using ResponsesHost host = await ResponsesHost.StartAsync( + SourceYaml, + new TwoParallelConversationsChatClient(), + configure: options => options.Bind("LookItUp", (string? what, TurnInvocation? turn) => + { + turn?.Sources?.Publish(new SourceReference + { + SourceId = what == "left" ? "card-left" : "card-right", + Kind = SourceKind.Document, + Title = what == "left" ? "Left manual" : "Right manual", + Origin = "knowledge", + }); + + return ValueTask.FromResult("looked up " + what); + })); + + using HttpResponseMessage response = await PostStreamAsync(host, "what is E03"); + List events = await ResponsesHost.ReadEventsAsync(response); + + List cited = [.. events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_source", out JsonElement source) + && source.ValueKind != JsonValueKind.Null) + .Select(chunk => chunk.GetProperty("agentcore_source"))]; + + Assert.Equal(2, cited.Count); + + JsonElement left = Assert.Single(cited, source => source.GetProperty("id").GetString() == "card-left"); + JsonElement right = Assert.Single(cited, source => source.GetProperty("id").GetString() == "card-right"); + + Assert.Equal("conversation_1", left.GetProperty("call_id").GetString()); + Assert.Equal("conversation_2", right.GetProperty("call_id").GetString()); + } + + /// Sends one turn of words and reads the answer as it arrives. + /// + /// The dialect member opts the stream into the browser parts: without it the frames carry + /// text alone and a citation would never reach the browser. + /// + private static Task PostStreamAsync(ResponsesHost host, string text, string? conversation = null) + { + return host.PostAsync(conversation is { Length: > 0 } + ? $$"""{ "stream": true, "conversation": "{{conversation}}", "input": "{{text}}", "agentcore": { "message_id": "m1" } }""" + : $$"""{ "stream": true, "input": "{{text}}", "agentcore": { "message_id": "m1" } }"""); + } + + /// Calls the first tool it is offered, once, then answers in words. + /// + /// Copied from the render chat client in ResponsesTests — that class is private to its own file, + /// so this test needs its own copy of the same shape rather than sharing the type. + /// + private sealed class SourceCitingChatClient : IChatClient + { + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + + bool alreadyCited = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyCited && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( "conversation_1", tool.Name, - new Dictionary(StringComparer.Ordinal) { ["what"] = "left" }), - new FunctionCallContent( - "conversation_2", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["what"] = "right" }), - ]); - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, "looked up both."); - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - - public void Dispose() - { - } - } - } + new Dictionary(StringComparer.Ordinal) { ["what"] = "E03" })]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "it is an overcurrent trip."); + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } + } + + /// Calls the tool it is offered twice in one round — two parallel calls — then answers in words. + /// + /// This is the shape a real model routinely produces and the single-conversation fakes above cannot + /// exercise: FunctionInvokingChatClient batches both tool results of one round onto ONE + /// message before this endpoint ever sees it. + /// + private sealed class TwoParallelConversationsChatClient : IChatClient + { + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + + bool alreadyCited = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyCited && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [ + new FunctionCallContent( + "conversation_1", + tool.Name, + new Dictionary(StringComparer.Ordinal) { ["what"] = "left" }), + new FunctionCallContent( + "conversation_2", + tool.Name, + new Dictionary(StringComparer.Ordinal) { ["what"] = "right" }), + ]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "looked up both."); + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } + } + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/TimeZoneHeaderTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/TimeZoneHeaderTests.cs index 84409e3c..51c94430 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/TimeZoneHeaderTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/TimeZoneHeaderTests.cs @@ -6,16 +6,16 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// -/// The X-AgentCore-Time-Zone header: the browser's zone reaches the clock line the model -/// reads, and a missing or unknown zone leaves the server's own in place. -/// -public sealed class TimeZoneHeaderTests +namespace AgentCore.AspNetCore.Tests.Endpoints { - private const string OneAgentYaml = - """ + /// + /// The X-AgentCore-Time-Zone header: the browser's zone reaches the clock line the model + /// reads, and a missing or unknown zone leaves the server's own in place. + /// + public sealed class TimeZoneHeaderTests + { + private const string OneAgentYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -32,40 +32,43 @@ public sealed class TimeZoneHeaderTests - { kind: openai, model: gpt-4.1-mini, as: reply } """; - // 2026-09-17 23:30 UTC: still Thursday in Chicago, already Friday morning in Taipei. - private static readonly DateTimeOffset Instant = new(2026, 9, 17, 23, 30, 0, TimeSpan.Zero); + // 2026-09-17 23:30 UTC: still Thursday in Chicago, already Friday morning in Taipei. + private static readonly DateTimeOffset Instant = new(2026, 9, 17, 23, 30, 0, TimeSpan.Zero); - [Fact] - public async Task HeaderNamesAZone_TheClockLineReadsTheDateInIt() - { - using FragmentingChatClient reply = new("answer"); - FakeTimeProvider clock = new(Instant); - await using var host = await ResponsesHost.StartAsync(OneAgentYaml, reply, options => options.TimeProvider = clock); + [Fact] + public async Task HeaderNamesAZone_TheClockLineReadsTheDateInIt() + { + using FragmentingChatClient reply = new("answer"); + FakeTimeProvider clock = new(Instant); + await using ResponsesHost host = await ResponsesHost.StartAsync(OneAgentYaml, reply, options => options.TimeProvider = clock); - using var response = await host.PostAsync( - """{ "stream": false, "input": "what day is it" }""", - new Dictionary { [ResponsesEndpointRouteBuilderExtensions.TimeZoneHeaderName] = "Asia/Taipei" }); + using HttpResponseMessage response = await host.PostAsync( + /*lang=json,strict*/ + """{ "stream": false, "input": "what day is it" }""", + new Dictionary { [ResponsesEndpointRouteBuilderExtensions.TimeZoneHeaderName] = "Asia/Taipei" }); - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - Assert.Contains( - reply.LastRequest!, - message => message.Role == ChatRole.System - && message.Text == "Today is Friday, 2026-09-18. The local time is 07:30, Asia/Taipei (UTC+08:00)."); - } + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + Assert.Contains( + reply.LastRequest!, + message => message.Role == ChatRole.System + && message.Text == "Today is Friday, 2026-09-18. The local time is 07:30, Asia/Taipei (UTC+08:00)."); + } - [Fact] - public async Task HeaderNamesNoKnownZone_TheClockLineReadsTheServerZone() - { - using FragmentingChatClient reply = new("answer"); - FakeTimeProvider clock = new(Instant); - await using var host = await ResponsesHost.StartAsync(OneAgentYaml, reply, options => options.TimeProvider = clock); + [Fact] + public async Task HeaderNamesNoKnownZone_TheClockLineReadsTheServerZone() + { + using FragmentingChatClient reply = new("answer"); + FakeTimeProvider clock = new(Instant); + await using ResponsesHost host = await ResponsesHost.StartAsync(OneAgentYaml, reply, options => options.TimeProvider = clock); - using var response = await host.PostAsync( - """{ "stream": false, "input": "what day is it" }""", - new Dictionary { [ResponsesEndpointRouteBuilderExtensions.TimeZoneHeaderName] = "Mars/Olympus_Mons" }); + using HttpResponseMessage response = await host.PostAsync( + /*lang=json,strict*/ + """{ "stream": false, "input": "what day is it" }""", + new Dictionary { [ResponsesEndpointRouteBuilderExtensions.TimeZoneHeaderName] = "Mars/Olympus_Mons" }); - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - var expected = ClockContextProvider.Describe(clock, clock.LocalTimeZone); - Assert.Contains(reply.LastRequest!, message => message.Role == ChatRole.System && message.Text == expected); + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + string expected = ClockContextProvider.Describe(clock, clock.LocalTimeZone); + Assert.Contains(reply.LastRequest!, message => message.Role == ChatRole.System && message.Text == expected); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs index a41c1be9..4b7cf185 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs @@ -5,25 +5,25 @@ using AgentCore.AspNetCore.Tests.Fakes; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// -/// The wire a tool call travels: one SSE field that names the conversation, and a second that answers it. -/// -/// -/// -/// This endpoint owns the tool loop, so the caller never runs a tool and must never be asked to. -/// The facts of the loop ride their own agentcore_tool field, beside agentcore_data, -/// where a client that does not know the field ignores it and the browser that does can draw the loop. -/// -/// -/// Every test here runs offline against a fake model, on a real socket. -/// -/// -public sealed class ToolWireTests +namespace AgentCore.AspNetCore.Tests.Endpoints { - private const string ToolYaml = - """ + /// + /// The wire a tool call travels: one SSE field that names the conversation, and a second that answers it. + /// + /// + /// + /// This endpoint owns the tool loop, so the caller never runs a tool and must never be asked to. + /// The facts of the loop ride their own agentcore_tool field, beside agentcore_data, + /// where a client that does not know the field ignores it and the browser that does can draw the loop. + /// + /// + /// Every test here runs offline against a fake model, on a real socket. + /// + /// + public sealed class ToolWireTests + { + private const string ToolYaml = + """ apiVersion: agentcore/v1 tools: - id: look_it_up @@ -55,256 +55,262 @@ public sealed class ToolWireTests - { kind: openai, model: gpt-4.1-mini, as: reply } """; - [Fact] - public async Task AToolCall_ReachesTheBrowserOnItsOwnFieldWithTheNameAndTheArguments() - { - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); - - using var response = await PostStreamAsync(host, "look up revenue"); - var tools = await ReadToolEventsAsync(response); - - var call = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "call"); - - Assert.Equal("conversation_1", call.GetProperty("call_id").GetString()); - Assert.Equal("look_it_up", call.GetProperty("name").GetString()); - Assert.Equal("a card", call.GetProperty("arguments").GetProperty("what").GetString()); - } - - [Fact] - public async Task AToolResult_ReachesTheBrowserOnTheSameFieldAndNamesTheCallItAnswers() - { - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); - - using var response = await PostStreamAsync(host, "look up revenue"); - var tools = await ReadToolEventsAsync(response); - - var result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); - - // The id is what pairs the two halves in the browser, so the result carries the conversation's id - // and not one of its own. - Assert.Equal("conversation_1", result.GetProperty("call_id").GetString()); - Assert.Equal("look_it_up", result.GetProperty("name").GetString()); - Assert.False(result.GetProperty("failed").GetBoolean()); - Assert.Contains("42 rows", result.GetProperty("result").GetString(), StringComparison.Ordinal); - } - - [Fact] - public async Task AToolThatThrows_ReachesTheBrowserAsAFailedResultRatherThanAsSilence() - { - // The loop turns a fault the model can answer into an error result and carries on. The - // caller's screen must say so, or a tool that failed looks the same as one that worked. - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => throw new InvalidOperationException("the table is gone"))); - - using var response = await PostStreamAsync(host, "look up revenue"); - var tools = await ReadToolEventsAsync(response); - - var result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); - - Assert.True(result.GetProperty("failed").GetBoolean()); - Assert.Contains( - "the table is gone", - result.GetProperty("result").GetProperty(ToolErrorResult.MessageProperty).GetString(), - StringComparison.Ordinal); - } - - [Fact] - public async Task AToolThatAnswersWithAnErrorObjectAsText_IsStillMarkedFailed() - { - // Section 8.7 lets a tool answer with the error object rather than throw, and an MCP server - // or a host delegate hands that object over as text. Reading the result as a node only when - // it already is one would call this failure a success. - var failure = ToolErrorResult.Create("look_it_up", "the table is gone").ToJsonString(); - - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult(failure))); - - using var response = await PostStreamAsync(host, "look up revenue"); - var tools = await ReadToolEventsAsync(response); - - var result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); - - Assert.True(result.GetProperty("failed").GetBoolean()); - Assert.Equal( - "the table is gone", - result.GetProperty("result").GetProperty(ToolErrorResult.MessageProperty).GetString()); - } - - [Fact] - public async Task AToolThatAnswersWithAnObject_ReachesTheBrowserAsItsFieldsAndNotItsTypeName() - { - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult(new Lookup(7, "cards")))); - - using var response = await PostStreamAsync(host, "look up revenue"); - var tools = await ReadToolEventsAsync(response); - - var result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); - var answer = result.GetProperty("result"); - - Assert.False(result.GetProperty("failed").GetBoolean()); - Assert.Equal(7, answer.GetProperty("rows").GetInt32()); - Assert.Equal("cards", answer.GetProperty("of").GetString()); - } - - [Fact] - public async Task AnAnswerThatIsJson_RidesTheWireAsJsonRatherThanAsEscapedText() - { - // Writing the answer as text escapes every quote inside it as \u0022, and leaves the browser - // a string to print raw where it lays out an object. The answer travels as itself instead. - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult("""{ "entities": [ "it's" ] }"""))); - - using var response = await PostStreamAsync(host, "look up revenue"); - - // The quotes inside the answer were the whole complaint: an answer written as text has every - // one of them escaped. The apostrophe stays escaped, because the default JSON writer escapes - // it whatever the shape it sits in, and the browser turns it back on parse. - var events = await ResponsesHost.ReadEventsAsync(response); - - // The framework's own function-conversation frames carry the model's raw argument string with its - // quotes escaped — that is the protocol's shape for a conversation. The complaint was ever about - // the answer, so the assertion reads the result line alone: on our field it travels as - // itself, not as escaped text. - var line = Assert.Single(events, text => JsonDocument.Parse(text).RootElement - .TryGetProperty("agentcore_tool", out var carried) - && carried.GetProperty("phase").GetString() == "result"); - Assert.DoesNotContain("\\u0022", line, StringComparison.Ordinal); - - var result = Assert.Single( - ToolEventsOf(events), - tool => tool.GetProperty("phase").GetString() == "result"); - } - - [Fact] - public async Task ATurnThatCallsNoTool_WritesNoToolFieldAtAll() - { - // The tool is declared and bound, exactly as in every other test here. The model simply - // never reaches for it, which is what this test is about. - using FragmentingChatClient reply = new("hello there"); - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - reply, - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); - - using var response = await PostStreamAsync(host, "hi"); - - Assert.Empty(await ReadToolEventsAsync(response)); - } - - [Fact] - public async Task AToolCall_StaysOutOfTheWordsTheCallerIsTold() - { - // The voice path speaks this same turn, and a tool name read aloud is not an answer. - await using var host = await ResponsesHost.StartAsync( - ToolYaml, - new ToolCallingChatClient(), - configure: options => options.Bind( - "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); - - using var response = await PostStreamAsync(host, "look up revenue"); - var events = await ResponsesHost.ReadEventsAsync(response); - - var spoken = string.Concat(ResponsesHost.TextDeltas(events)); - - Assert.Equal("here it is.", spoken); - } - - /// What a tool answers with when it answers with an object of its own. - private sealed record Lookup(int Rows, string Of); - - /// Sends one turn of words and reads the answer as it arrives. - /// - /// The dialect member opts the stream into the browser parts: without it the frames carry - /// text alone and the tool halves would never reach the browser. - /// - private static Task PostStreamAsync(ResponsesHost host, string text, string? conversation = null) - => host.PostAsync(conversation is { Length: > 0 } - ? $$"""{ "stream": true, "conversation": "{{conversation}}", "input": "{{text}}", "agentcore": { "message_id": "m1" } }""" - : $$"""{ "stream": true, "input": "{{text}}", "agentcore": { "message_id": "m1" } }"""); - - /// Reads every agentcore_tool payload the stream carried, in arrival order. - private static async Task> ReadToolEventsAsync(HttpResponseMessage response) - => ToolEventsOf(await ResponsesHost.ReadEventsAsync(response)); - - /// Picks the agentcore_tool payloads out of events already read. - private static List ToolEventsOf(IEnumerable events) - { - return events - .Select(text => JsonDocument.Parse(text).RootElement) - .Where(chunk => chunk.TryGetProperty("agentcore_tool", out var tool) - && tool.ValueKind != JsonValueKind.Null) - .Select(chunk => chunk.GetProperty("agentcore_tool")) - .ToList(); - } - - /// Calls the first tool it is offered, once, then answers in words. - private sealed class ToolCallingChatClient : IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - var alreadyCalled = messages.Any(message => message.Contents.OfType().Any()); - - if (!alreadyCalled && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["what"] = "a card" })]); - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, "here it is."); - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - - public void Dispose() - { - } - } - } + [Fact] + public async Task AToolCall_ReachesTheBrowserOnItsOwnFieldWithTheNameAndTheArguments() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + List tools = await ReadToolEventsAsync(response); + + JsonElement call = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "call"); + + Assert.Equal("conversation_1", call.GetProperty("call_id").GetString()); + Assert.Equal("look_it_up", call.GetProperty("name").GetString()); + Assert.Equal("a card", call.GetProperty("arguments").GetProperty("what").GetString()); + } + + [Fact] + public async Task AToolResult_ReachesTheBrowserOnTheSameFieldAndNamesTheCallItAnswers() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + List tools = await ReadToolEventsAsync(response); + + JsonElement result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); + + // The id is what pairs the two halves in the browser, so the result carries the conversation's id + // and not one of its own. + Assert.Equal("conversation_1", result.GetProperty("call_id").GetString()); + Assert.Equal("look_it_up", result.GetProperty("name").GetString()); + Assert.False(result.GetProperty("failed").GetBoolean()); + Assert.Contains("42 rows", result.GetProperty("result").GetString(), StringComparison.Ordinal); + } + + [Fact] + public async Task AToolThatThrows_ReachesTheBrowserAsAFailedResultRatherThanAsSilence() + { + // The loop turns a fault the model can answer into an error result and carries on. The + // caller's screen must say so, or a tool that failed looks the same as one that worked. + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => throw new InvalidOperationException("the table is gone"))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + List tools = await ReadToolEventsAsync(response); + + JsonElement result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); + + Assert.True(result.GetProperty("failed").GetBoolean()); + Assert.Contains( + "the table is gone", + result.GetProperty("result").GetProperty(ToolErrorResult.MessageProperty).GetString(), + StringComparison.Ordinal); + } + + [Fact] + public async Task AToolThatAnswersWithAnErrorObjectAsText_IsStillMarkedFailed() + { + // Section 8.7 lets a tool answer with the error object rather than throw, and an MCP server + // or a host delegate hands that object over as text. Reading the result as a node only when + // it already is one would call this failure a success. + string failure = ToolErrorResult.Create("look_it_up", "the table is gone").ToJsonString(); + + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult(failure))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + List tools = await ReadToolEventsAsync(response); + + JsonElement result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); + + Assert.True(result.GetProperty("failed").GetBoolean()); + Assert.Equal( + "the table is gone", + result.GetProperty("result").GetProperty(ToolErrorResult.MessageProperty).GetString()); + } + + [Fact] + public async Task AToolThatAnswersWithAnObject_ReachesTheBrowserAsItsFieldsAndNotItsTypeName() + { + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult(new Lookup(7, "cards")))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + List tools = await ReadToolEventsAsync(response); + + JsonElement result = Assert.Single(tools, tool => tool.GetProperty("phase").GetString() == "result"); + JsonElement answer = result.GetProperty("result"); + + Assert.False(result.GetProperty("failed").GetBoolean()); + Assert.Equal(7, answer.GetProperty("rows").GetInt32()); + Assert.Equal("cards", answer.GetProperty("of").GetString()); + } + + [Fact] + public async Task AnAnswerThatIsJson_RidesTheWireAsJsonRatherThanAsEscapedText() + { + // Writing the answer as text escapes every quote inside it as \u0022, and leaves the browser + // a string to print raw where it lays out an object. The answer travels as itself instead. + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult(/*lang=json,strict*/ """{ "entities": [ "it's" ] }"""))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + + // The quotes inside the answer were the whole complaint: an answer written as text has every + // one of them escaped. The apostrophe stays escaped, because the default JSON writer escapes + // it whatever the shape it sits in, and the browser turns it back on parse. + List events = await ResponsesHost.ReadEventsAsync(response); + + // The framework's own function-conversation frames carry the model's raw argument string with its + // quotes escaped — that is the protocol's shape for a conversation. The complaint was ever about + // the answer, so the assertion reads the result line alone: on our field it travels as + // itself, not as escaped text. + string line = Assert.Single(events, text => JsonDocument.Parse(text).RootElement + .TryGetProperty("agentcore_tool", out JsonElement carried) + && carried.GetProperty("phase").GetString() == "result"); + Assert.DoesNotContain("\\u0022", line, StringComparison.Ordinal); + + JsonElement result = Assert.Single( + ToolEventsOf(events), + tool => tool.GetProperty("phase").GetString() == "result"); + } + + [Fact] + public async Task ATurnThatCallsNoTool_WritesNoToolFieldAtAll() + { + // The tool is declared and bound, exactly as in every other test here. The model simply + // never reaches for it, which is what this test is about. + using FragmentingChatClient reply = new("hello there"); + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + reply, + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); + + using HttpResponseMessage response = await PostStreamAsync(host, "hi"); + + Assert.Empty(await ReadToolEventsAsync(response)); + } + + [Fact] + public async Task AToolCall_StaysOutOfTheWordsTheCallerIsTold() + { + // The voice path speaks this same turn, and a tool name read aloud is not an answer. + await using ResponsesHost host = await ResponsesHost.StartAsync( + ToolYaml, + new ToolCallingChatClient(), + configure: options => options.Bind( + "LookItUp", (_, _) => ValueTask.FromResult("42 rows"))); + + using HttpResponseMessage response = await PostStreamAsync(host, "look up revenue"); + List events = await ResponsesHost.ReadEventsAsync(response); + + string spoken = string.Concat(ResponsesHost.TextDeltas(events)); + + Assert.Equal("here it is.", spoken); + } + + /// What a tool answers with when it answers with an object of its own. + private sealed record Lookup(int Rows, string Of); + + /// Sends one turn of words and reads the answer as it arrives. + /// + /// The dialect member opts the stream into the browser parts: without it the frames carry + /// text alone and the tool halves would never reach the browser. + /// + private static Task PostStreamAsync(ResponsesHost host, string text, string? conversation = null) + { + return host.PostAsync(conversation is { Length: > 0 } + ? $$"""{ "stream": true, "conversation": "{{conversation}}", "input": "{{text}}", "agentcore": { "message_id": "m1" } }""" + : $$"""{ "stream": true, "input": "{{text}}", "agentcore": { "message_id": "m1" } }"""); + } + + /// Reads every agentcore_tool payload the stream carried, in arrival order. + private static async Task> ReadToolEventsAsync(HttpResponseMessage response) + { + return ToolEventsOf(await ResponsesHost.ReadEventsAsync(response)); + } + + /// Picks the agentcore_tool payloads out of events already read. + private static List ToolEventsOf(IEnumerable events) + { + return [.. events + .Select(text => JsonDocument.Parse(text).RootElement) + .Where(chunk => chunk.TryGetProperty("agentcore_tool", out JsonElement tool) + && tool.ValueKind != JsonValueKind.Null) + .Select(chunk => chunk.GetProperty("agentcore_tool"))]; + } + + /// Calls the first tool it is offered, once, then answers in words. + private sealed class ToolCallingChatClient : IChatClient + { + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + + bool alreadyCalled = messages.Any(message => message.Contents.OfType().Any()); + + if (!alreadyCalled && options?.Tools?.OfType().FirstOrDefault() is { } tool) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + "conversation_1", + tool.Name, + new Dictionary(StringComparer.Ordinal) { ["what"] = "a card" })]); + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, "here it is."); + } + + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } + } + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs index 5262ff99..024f923f 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs @@ -7,86 +7,101 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.AspNetCore.Tests.Endpoints; - -/// Which published files reach the browser as a part, and with what link. -public sealed class TurnStreamFilesTests +namespace AgentCore.AspNetCore.Tests.Endpoints { - private static ChatResponseUpdate UpdateWith(params AIContent[] contents) - => new(ChatRole.Assistant, contents); - - /// A file the publish tool kept, as it files it on the turn before the stream ends. - private static FileContent Kept(string name, string mediaType, long length) - => new() { Name = name, FileId = "cfile_" + name, MediaType = mediaType, Length = length, Kept = true }; - - [Fact] - public async Task ResolveAsync_NotedFileTheCaptureKept_YieldsOnePartWithTheLink() - { - // Arrange: the same content passes twice, as a re-yielded update would; a refused one passes too. - Conversations conversations = new(new InMemoryConversationStore(), new StubBlobStore()); - TurnStreamFiles files = new(); - var chart = Kept("chart.png", "image/png", 48213); - FileContent refused = new() { Name = "refused.png", FileId = "cfile_2" }; - files.Note(UpdateWith(new TextContent("see"), chart)); - files.Note(UpdateWith(chart)); - files.Note(UpdateWith(refused)); - - // Act - var parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); - - // Assert: once, linked, and the refused file is not there. - var part = Assert.Single(parts); - Assert.Equal("chart.png", part.Payload.Name); - Assert.Equal("image/png", part.Payload.MediaType); - Assert.Equal(48213, part.Payload.Length); - Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", part.Payload.Url); - } - - [Fact] - public async Task ResolveAsync_StoreWithNoWebDoor_YieldsThePartWithoutAUrl() - { - // Arrange - Conversations conversations = new(new InMemoryConversationStore(), new StubBlobStore { Links = false }); - TurnStreamFiles files = new(); - files.Note(UpdateWith(Kept("rows.csv", "text/csv", 8))); - - // Act - var parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); - - // Assert - Assert.Null(Assert.Single(parts).Payload.Url); - } - - [Fact] - public async Task ResolveAsync_NothingNoted_YieldsNothing() + /// Which published files reach the browser as a part, and with what link. + public sealed class TurnStreamFilesTests { - // Arrange - Conversations conversations = new(new InMemoryConversationStore(), blobs: null); - - // Act - var parts = await new TurnStreamFiles().ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); - - // Assert - Assert.Empty(parts); - } - - private sealed class StubBlobStore : IBlobStore - { - public bool Links { get; init; } = true; - - public ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); - - public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => throw new NotSupportedException("The read path links from the content and never asks the store."); - - public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) - => ValueTask.FromResult(Links ? new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}") : null); - - public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + private static ChatResponseUpdate UpdateWith(params AIContent[] contents) + { + return new(ChatRole.Assistant, contents); + } + + /// A file the publish tool kept, as it files it on the turn before the stream ends. + private static FileContent Kept(string name, string mediaType, long length) + { + return new() { Name = name, FileId = "cfile_" + name, MediaType = mediaType, Length = length, Kept = true }; + } + + [Fact] + public async Task ResolveAsync_NotedFileTheCaptureKept_YieldsOnePartWithTheLink() + { + // Arrange: the same content passes twice, as a re-yielded update would; a refused one passes too. + Conversations conversations = new(new InMemoryConversationStore(), new StubBlobStore()); + TurnStreamFiles files = new(); + FileContent chart = Kept("chart.png", "image/png", 48213); + FileContent refused = new() { Name = "refused.png", FileId = "cfile_2" }; + files.Note(UpdateWith(new TextContent("see"), chart)); + files.Note(UpdateWith(chart)); + files.Note(UpdateWith(refused)); + + // Act + List parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); + + // Assert: once, linked, and the refused file is not there. + TurnStreamFile part = Assert.Single(parts); + Assert.Equal("chart.png", part.Payload.Name); + Assert.Equal("image/png", part.Payload.MediaType); + Assert.Equal(48213, part.Payload.Length); + Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", part.Payload.Url); + } + + [Fact] + public async Task ResolveAsync_StoreWithNoWebDoor_YieldsThePartWithoutAUrl() + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), new StubBlobStore { Links = false }); + TurnStreamFiles files = new(); + files.Note(UpdateWith(Kept("rows.csv", "text/csv", 8))); + + // Act + List parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); + + // Assert + Assert.Null(Assert.Single(parts).Payload.Url); + } + + [Fact] + public async Task ResolveAsync_NothingNoted_YieldsNothing() + { + // Arrange + Conversations conversations = new(new InMemoryConversationStore(), blobs: null); + + // Act + List parts = await new TurnStreamFiles().ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); + + // Assert + Assert.Empty(parts); + } + + private sealed class StubBlobStore : IBlobStore + { + public bool Links { get; init; } = true; + + public ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + throw new NotSupportedException("The read path links from the content and never asks the store."); + } + + public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(Links ? new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}") : null); + } + + public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/EventObservedLoggerProvider.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/EventObservedLoggerProvider.cs index 1f4b2ecc..ed2bf891 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/EventObservedLoggerProvider.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/EventObservedLoggerProvider.cs @@ -1,67 +1,89 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// Completes once the connection writes the log line named eventName, and counts how many -/// times it does. -/// -/// -/// A relay client's SendAsync completing only proves the bytes left the client, not that the -/// connection has read, dispatched, and finished handling them — the same gap -/// documents for a setup frame. A test that -/// released a gate on SendAsync alone would be timing delivery, not the connection's own -/// state, so several tests in this file wait for a named line first. Matched by -/// , the same way already is, -/// because none of the words a caller said ever reach a log line to match on instead. -/// -internal sealed class EventObservedLoggerProvider(string eventName) : ILoggerProvider +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly TaskCompletionSource _observed = new(TaskCreationOptions.RunContinuationsAsynchronously); - private int _count; - private LogLevel? _level; - private string? _message; + /// + /// Completes once the connection writes the log line named eventName, and counts how many + /// times it does. + /// + /// + /// A relay client's SendAsync completing only proves the bytes left the client, not that the + /// connection has read, dispatched, and finished handling them — the same gap + /// documents for a setup frame. A test that + /// released a gate on SendAsync alone would be timing delivery, not the connection's own + /// state, so several tests in this file wait for a named line first. Matched by + /// , the same way already is, + /// because none of the words a caller said ever reach a log line to match on instead. + /// + internal sealed class EventObservedLoggerProvider(string eventName) : ILoggerProvider + { + private readonly TaskCompletionSource _observed = new(TaskCreationOptions.RunContinuationsAsynchronously); - /// Gets a task that completes once the connection first logs the named line. - public Task Observed => _observed.Task; + /// Gets a task that completes once the connection first logs the named line. + public Task Observed => _observed.Task; - /// Gets how many times the connection has logged the named line so far. - public int Count => Volatile.Read(ref _count); + private readonly Lock _gate = new(); - /// Gets the level of the most recent match, or null before the first one. - public LogLevel? Level => _level; + public int Count + { + get + { + lock (_gate) + { + return field; + } + } - /// Gets the rendered text of the most recent match, or null before the first one. - public string? Message => _message; + private set; + } - public ILogger CreateLogger(string categoryName) => new Logger(this, eventName); + /// Gets the level of the most recent match, or null before the first one. + public LogLevel? Level { get; private set; } - public void Dispose() - { - // Nothing to release. - } + /// Gets the rendered text of the most recent match, or null before the first one. + public string? Message { get; private set; } - private sealed class Logger(EventObservedLoggerProvider owner, string eventName) : ILogger - { - public IDisposable? BeginScope(TState state) - where TState : notnull - => null; + public ILogger CreateLogger(string categoryName) + { + return new Logger(this, eventName); + } - public bool IsEnabled(LogLevel logLevel) => true; + public void Dispose() + { + // Nothing to release. + } - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + private sealed class Logger(EventObservedLoggerProvider owner, string eventName) : ILogger { - if (eventId.Name == eventName) + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } + + public bool IsEnabled(LogLevel logLevel) { - owner._level = logLevel; - owner._message = formatter(state, exception); - Interlocked.Increment(ref owner._count); - owner._observed.TrySetResult(); + return true; + } + + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + if (eventId.Name == eventName) + { + owner.Level = logLevel; + owner.Message = formatter(state, exception); + lock (owner._gate) + { + owner.Count++; + } + + _ = owner._observed.TrySetResult(); + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeBlobStoreAdapter.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeBlobStoreAdapter.cs index 13ca16c4..b239e085 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeBlobStoreAdapter.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeBlobStoreAdapter.cs @@ -2,64 +2,73 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// A providers.blobs vendor that opens one in-memory store, so a test reads what a turn published. -internal sealed class FakeBlobStoreAdapter(string kind = "fake") : IBlobStoreAdapter +namespace AgentCore.AspNetCore.Tests.Fakes { - public string Kind => kind; + /// A providers.blobs vendor that opens one in-memory store, so a test reads what a turn published. + internal sealed class FakeBlobStoreAdapter(string kind = "fake") : IBlobStoreAdapter + { + public string Kind => kind; - /// Gets the one store every open hands over. - public FakeBlobStore Store { get; } = new(); + /// Gets the one store every open hands over. + public FakeBlobStore Store { get; } = new(); - public ValueTask OpenAsync( - BlobProviderConfiguration entry, ISecretResolverPort? secrets, CancellationToken cancellationToken = default) - => ValueTask.FromResult(Store); -} + public ValueTask OpenAsync( + BlobProviderConfiguration entry, ISecretResolverPort? secrets, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(Store); + } + } -/// An in-memory whose links name the owner and the blob, so a test can read them off a URL. -internal sealed class FakeBlobStore : IBlobStore -{ - private readonly Dictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> _blobs = []; + /// An in-memory whose links name the owner and the blob, so a test can read them off a URL. + internal sealed class FakeBlobStore : IBlobStore + { + private readonly Dictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> _blobs = []; - /// Gets every blob stored, keyed by owner and name. - public IReadOnlyDictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> Blobs => _blobs; + /// Gets every blob stored, keyed by owner and name. + public IReadOnlyDictionary<(string Owner, string Name), (string MediaType, byte[] Bytes)> Blobs => _blobs; - public async ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) - { - using MemoryStream copy = new(); - await write.Content.CopyToAsync(copy, cancellationToken); - lock (_blobs) + public async ValueTask PutAsync(BlobWrite write, CancellationToken cancellationToken = default) { - _blobs[(write.OwnerId, write.Name)] = (write.MediaType, copy.ToArray()); - } + using MemoryStream copy = new(); + await write.Content.CopyToAsync(copy, cancellationToken); + lock (_blobs) + { + _blobs[(write.OwnerId, write.Name)] = (write.MediaType, copy.ToArray()); + } - return new BlobRef(write.OwnerId, write.Name, write.MediaType, write.Length); - } + return new BlobRef(write.OwnerId, write.Name, write.MediaType, write.Length); + } - public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out var blob) - ? new BlobRead(blob.MediaType, blob.Bytes.Length, new MemoryStream(blob.Bytes)) - : null); + public ValueTask OpenReadAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out (string MediaType, byte[] Bytes) blob) + ? new BlobRead(blob.MediaType, blob.Bytes.Length, new MemoryStream(blob.Bytes)) + : null); + } - public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) - => ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out var blob) - ? new BlobRef(ownerId, name, blob.MediaType, blob.Bytes.Length) - : null); + public ValueTask StatAsync(string ownerId, string name, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(_blobs.TryGetValue((ownerId, name), out (string MediaType, byte[] Bytes) blob) + ? new BlobRef(ownerId, name, blob.MediaType, blob.Bytes.Length) + : null); + } - public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) - => ValueTask.FromResult(new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}")); + public ValueTask LinkAsync(BlobRef blob, TimeSpan lifetime, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(new Uri($"https://blobs.test/{blob.OwnerId}/{blob.Name}?ttl={(int)lifetime.TotalSeconds}")); + } - public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) - { - lock (_blobs) + public ValueTask DeleteByOwnerAsync(string ownerId, CancellationToken cancellationToken = default) { - foreach (var key in _blobs.Keys.Where(key => key.Owner == ownerId).ToList()) + lock (_blobs) { - _blobs.Remove(key); + foreach ((string Owner, string Name) key in _blobs.Keys.Where(key => key.Owner == ownerId).ToList()) + { + _ = _blobs.Remove(key); + } } - } - return ValueTask.CompletedTask; + return ValueTask.CompletedTask; + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs index 407a9c4f..494e60cf 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeChatClientAdapter.cs @@ -2,28 +2,28 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// An offline vendor adapter: one kind, one client factory, no socket and no key. -/// -internal sealed class FakeChatClientAdapter : IChatClientAdapter +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly Func _client; - - public FakeChatClientAdapter(string kind, Func client) + /// + /// An offline vendor adapter: one kind, one client factory, no socket and no key. + /// + internal sealed class FakeChatClientAdapter(string kind, Func client) : IChatClientAdapter { - Kind = kind; - _client = client; - } + private readonly Func _client = client; - public string Kind { get; } + public string Kind { get; } = kind; - public ValueTask CreateClientAsync( - LlmProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(_client()); + public ValueTask CreateClientAsync( + LlmProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(_client()); + } - public int? GetContextWindow(LlmProviderConfiguration entry) => 128_000; + public int? GetContextWindow(LlmProviderConfiguration entry) + { + return 128_000; + } + } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationInput.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationInput.cs index fd1afdfb..6b96b7e2 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationInput.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationInput.cs @@ -2,69 +2,67 @@ using AgentCore.Application.Ports; using AgentCore.Application.Conversation; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// An input port that replays a scripted stream, refuses a second reader, and counts its disposals. -/// What the caller does, in order. Empty is a conversation the caller never spoke on. -internal sealed class FakeConversationInput(params ConversationInput[] script) : IConversationInputPort +namespace AgentCore.AspNetCore.Tests.Fakes { - private int _listening; + /// An input port that replays a scripted stream, refuses a second reader, and counts its disposals. + /// What the caller does, in order. Empty is a conversation the caller never spoke on. + internal sealed class FakeConversationInput(params ConversationInput[] script) : IConversationInputPort + { + private int _listening; - /// Gets how many times this port was disposed. - public int Disposals { get; private set; } + /// Gets how many times this port was disposed. + public int Disposals { get; private set; } - /// - /// - /// - /// The refusal is the point of this fake as much as the script is: one socket read twice would - /// give each reader half the conversation, and the port promises a second call throws rather than - /// splitting one conversation in two. - /// - /// - /// The script running out is this fake's end of the conversation, and it completes the stream. A - /// cancelled read throws instead, which is the rule - /// sets and which the real relay connection obeys the same way — a double that ended quietly - /// where the real port throws would teach a consumer a catch it does not need, and hide - /// the one it does. - /// - /// - public IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default) - { - // Thrown from here, not from the iterator below: an iterator's body does not run until - // something enumerates it, so a guard inside it would let a second ListenAsync return a - // stream that only throws later, or never, if nobody enumerates it. - if (Interlocked.CompareExchange(ref _listening, 1, 0) != 0) + /// + /// + /// + /// The refusal is the point of this fake as much as the script is: one socket read twice would + /// give each reader half the conversation, and the port promises a second call throws rather than + /// splitting one conversation in two. + /// + /// + /// The script running out is this fake's end of the conversation, and it completes the stream. A + /// cancelled read throws instead, which is the rule + /// sets and which the real relay connection obeys the same way — a double that ended quietly + /// where the real port throws would teach a consumer a catch it does not need, and hide + /// the one it does. + /// + /// + public IAsyncEnumerable ListenAsync(CancellationToken cancellationToken = default) { - throw new InvalidOperationException("This port is already being read."); + // Thrown from here, not from the iterator below: an iterator's body does not run until + // something enumerates it, so a guard inside it would let a second ListenAsync return a + // stream that only throws later, or never, if nobody enumerates it. + return Interlocked.CompareExchange(ref _listening, 1, 0) != 0 + ? throw new InvalidOperationException("This port is already being read.") + : ReplayAsync(cancellationToken); } - return ReplayAsync(cancellationToken); - } - - public ValueTask DisposeAsync() - { - Disposals++; - return ValueTask.CompletedTask; - } + public ValueTask DisposeAsync() + { + Disposals++; + return ValueTask.CompletedTask; + } - /// Replays the script, one item at a time. - /// Ends the stream. - /// Every scripted item, in order. - private async IAsyncEnumerable ReplayAsync( - [EnumeratorCancellation] CancellationToken cancellationToken) - { - foreach (var input in script) + /// Replays the script, one item at a time. + /// Ends the stream. + /// Every scripted item, in order. + private async IAsyncEnumerable ReplayAsync( + [EnumeratorCancellation] CancellationToken cancellationToken) { - // Yielded from a continuation rather than inline, so a consumer of this fake meets the - // same interleaving a real socket gives it and never a stream that completes - // synchronously inside its own await foreach. - await Task.Yield(); + foreach (ConversationInput input in script) + { + // Yielded from a continuation rather than inline, so a consumer of this fake meets the + // same interleaving a real socket gives it and never a stream that completes + // synchronously inside its own await foreach. + await Task.Yield(); - // Throws rather than breaking out of the loop: a cancelled read is not the end of a - // conversation, and this fake must not be the one place a consumer learns otherwise. - cancellationToken.ThrowIfCancellationRequested(); + // Throws rather than breaking out of the loop: a cancelled read is not the end of a + // conversation, and this fake must not be the one place a consumer learns otherwise. + cancellationToken.ThrowIfCancellationRequested(); - yield return input; + yield return input; + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationOutput.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationOutput.cs index 5e5cfb6c..45593a2f 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationOutput.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeConversationOutput.cs @@ -1,53 +1,54 @@ using AgentCore.Application.Ports; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// An output port that records what it was told to say, and when it was stopped. -internal sealed class FakeConversationOutput : IConversationOutputPort +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly List _spoken = []; - private readonly Lock _gate = new(); - - /// Gets every fragment this port was given, in order. - public IReadOnlyList Spoken + /// An output port that records what it was told to say, and when it was stopped. + internal sealed class FakeConversationOutput : IConversationOutputPort { - get { lock (_gate) { return [.. _spoken]; } } - } + private readonly List _spoken = []; + private readonly Lock _gate = new(); - /// Gets how many replies were closed. - public int Completions { get; private set; } + /// Gets every fragment this port was given, in order. + public IReadOnlyList Spoken + { + get { lock (_gate) { return [.. _spoken]; } } + } - /// Gets how many times a barge-in stopped this port. - public int Stops { get; private set; } + /// Gets how many replies were closed. + public int Completions { get; private set; } - /// Gets how many times this port was disposed. - public int Disposals { get; private set; } + /// Gets how many times a barge-in stopped this port. + public int Stops { get; private set; } - public ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default) - { - lock (_gate) + /// Gets how many times this port was disposed. + public int Disposals { get; private set; } + + public ValueTask SpeakAsync(string fragment, CancellationToken cancellationToken = default) { - _spoken.Add(fragment); - } + lock (_gate) + { + _spoken.Add(fragment); + } - return ValueTask.CompletedTask; - } + return ValueTask.CompletedTask; + } - public ValueTask CompleteAsync(CancellationToken cancellationToken = default) - { - Completions++; - return ValueTask.CompletedTask; - } + public ValueTask CompleteAsync(CancellationToken cancellationToken = default) + { + Completions++; + return ValueTask.CompletedTask; + } - public ValueTask StopAsync(CancellationToken cancellationToken = default) - { - Stops++; - return ValueTask.CompletedTask; - } + public ValueTask StopAsync(CancellationToken cancellationToken = default) + { + Stops++; + return ValueTask.CompletedTask; + } - public ValueTask DisposeAsync() - { - Disposals++; - return ValueTask.CompletedTask; + public ValueTask DisposeAsync() + { + Disposals++; + return ValueTask.CompletedTask; + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeRelayClient.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeRelayClient.cs index 680c1929..09556614 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeRelayClient.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeRelayClient.cs @@ -4,292 +4,306 @@ using System.Threading.Channels; using Xunit; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// The vendor side of the socket, scripted by a test. -/// -/// -/// Telnyx opens the socket to us, so AgentCore is the server and there is nothing to fake on the -/// far side. This class is the client the vendor would be. The socket is real, because framing is -/// a wire behaviour and an in-memory pipe would not prove that the read loop rejoins a fragmented -/// message. -/// -internal sealed class FakeRelayClient : IAsyncDisposable +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly ClientWebSocket _socket; - private readonly Channel _channel = Channel.CreateUnbounded( - new UnboundedChannelOptions { SingleReader = true, SingleWriter = true }); - private readonly CancellationTokenSource _pumpCancellation = new(); - private readonly Task _pump; - - private FakeRelayClient(ClientWebSocket socket) - { - _socket = socket; - - // One background loop owns every ReceiveAsync on this socket for its whole life. Cancelling - // a pending ReceiveAsync moves ClientWebSocket to WebSocketState.Aborted for good, and every - // later send or close then throws. A reader that gives up early — ReadFramesForAsync on a - // quiet window — must never be the thing that cancels a receive, so it never touches the - // socket at all. It only stops waiting on this channel. - _pump = Task.Run(() => PumpAsync(_pumpCancellation.Token)); - } - - /// Opens one socket to the host. - /// The ws:// address of the relay route. - /// The connected client. - public static async Task ConnectAsync(Uri address) - { - ClientWebSocket socket = new(); - await socket.ConnectAsync(address, TestContext.Current.CancellationToken); - return new FakeRelayClient(socket); - } - - /// Sends one frame as one message. - public Task SendAsync(string json) => SendRawAsync(json); - - /// Sends any text as one message, well-formed or not. - public async Task SendRawAsync(string text) - { - await _socket.SendAsync( - Encoding.UTF8.GetBytes(text), - WebSocketMessageType.Text, - endOfMessage: true, - TestContext.Current.CancellationToken); - } - - /// Sends one frame split across many WebSocket fragments. - /// The frame. - /// How many pieces to split it into. + /// + /// The vendor side of the socket, scripted by a test. + /// /// - /// The vendor may fragment any message, and a read loop that parses one receive at a time - /// fails on the first piece. This method is how a test proves the loop rejoins them. The - /// partition is balanced rather than a fixed chunk size: a fixed size rounded up can finish in - /// fewer sends than asked whenever the byte count divides evenly by a smaller size than the one - /// computed for pieces, so a caller's requested count would not be - /// what actually left the wire. Spreading the remainder one byte at a time across the first - /// pieces instead makes the loop run exactly times by construction. + /// Telnyx opens the socket to us, so AgentCore is the server and there is nothing to fake on the + /// far side. This class is the client the vendor would be. The socket is real, because framing is + /// a wire behaviour and an in-memory pipe would not prove that the read loop rejoins a fragmented + /// message. /// - public async Task SendFragmentedAsync(string json, int fragments) + internal sealed class FakeRelayClient : IAsyncDisposable { - var bytes = Encoding.UTF8.GetBytes(json); - Assert.True( - fragments > 0 && fragments <= bytes.Length, - $"cannot split {bytes.Length} bytes into {fragments} non-empty fragments."); + private readonly ClientWebSocket _socket; + private readonly Channel _channel = Channel.CreateUnbounded( + new UnboundedChannelOptions { SingleReader = true, SingleWriter = true }); + private readonly CancellationTokenSource _pumpCancellation = new(); + private readonly Task _pump; - var baseSize = bytes.Length / fragments; - var remainder = bytes.Length % fragments; - var offset = 0; + private FakeRelayClient(ClientWebSocket socket) + { + _socket = socket; + + // One background loop owns every ReceiveAsync on this socket for its whole life. Cancelling + // a pending ReceiveAsync moves ClientWebSocket to WebSocketState.Aborted for good, and every + // later send or close then throws. A reader that gives up early — ReadFramesForAsync on a + // quiet window — must never be the thing that cancels a receive, so it never touches the + // socket at all. It only stops waiting on this channel. + _pump = Task.Run(() => PumpAsync(_pumpCancellation.Token)); + } - for (var i = 0; i < fragments; i++) + /// Opens one socket to the host. + /// The ws:// address of the relay route. + /// The connected client. + public static async Task ConnectAsync(Uri address) { - var length = baseSize + (i < remainder ? 1 : 0); - var last = i == fragments - 1; + ClientWebSocket socket = new(); + await socket.ConnectAsync(address, TestContext.Current.CancellationToken); + return new FakeRelayClient(socket); + } + + /// Sends one frame as one message. + public Task SendAsync(string json) + { + return SendRawAsync(json); + } + /// Sends any text as one message, well-formed or not. + public async Task SendRawAsync(string text) + { await _socket.SendAsync( - bytes.AsMemory(offset, length), + Encoding.UTF8.GetBytes(text), WebSocketMessageType.Text, - endOfMessage: last, + endOfMessage: true, TestContext.Current.CancellationToken); - - offset += length; } - } - - /// Reads one outbound frame. - /// The frame as a node tree. - public async Task ReadFrameAsync() - { - var item = await ReadItemAsync(TestContext.Current.CancellationToken).ConfigureAwait(false); - Assert.False(item.IsClose, "expected a data frame, but the host closed the socket first."); - return item.Frame!; - } - /// Reads every text frame of one reply, up to and including the closing one. - /// The token of each frame, in order. - public async Task> ReadTextFramesUntilLastAsync() - { - List tokens = []; - while (true) + /// Sends one frame split across many WebSocket fragments. + /// The frame. + /// How many pieces to split it into. + /// + /// The vendor may fragment any message, and a read loop that parses one receive at a time + /// fails on the first piece. This method is how a test proves the loop rejoins them. The + /// partition is balanced rather than a fixed chunk size: a fixed size rounded up can finish in + /// fewer sends than asked whenever the byte count divides evenly by a smaller size than the one + /// computed for pieces, so a caller's requested count would not be + /// what actually left the wire. Spreading the remainder one byte at a time across the first + /// pieces instead makes the loop run exactly times by construction. + /// + public async Task SendFragmentedAsync(string json, int fragments) { - var frame = await ReadFrameAsync(); - Assert.Equal("text", frame["type"]!.GetValue()); - tokens.Add(frame["token"]!.GetValue()); + byte[] bytes = Encoding.UTF8.GetBytes(json); + Assert.True( + fragments > 0 && fragments <= bytes.Length, + $"cannot split {bytes.Length} bytes into {fragments} non-empty fragments."); + + int baseSize = bytes.Length / fragments; + int remainder = bytes.Length % fragments; + int offset = 0; - if (frame["last"]!.GetValue()) + for (int i = 0; i < fragments; i++) { - return tokens; + int length = baseSize + (i < remainder ? 1 : 0); + bool last = i == fragments - 1; + + await _socket.SendAsync( + bytes.AsMemory(offset, length), + WebSocketMessageType.Text, + endOfMessage: last, + TestContext.Current.CancellationToken); + + offset += length; } } - } - /// Collects every frame that arrives inside a window. - /// How long to listen before giving up. - /// The frames received, in order. Empty when none arrived in the window. - /// - /// A test uses this to prove that no frame arrived, for example that a dropped interim - /// transcript never reaches the model. Silence is a valid outcome on this socket, so a quiet - /// window returns an empty list instead of throwing. The wait times out on the channel this - /// class reads from, never on the socket itself, so a quiet window leaves the socket exactly as - /// usable afterwards as it was before. - /// - public async Task> ReadFramesForAsync(TimeSpan window) - { - List frames = []; - using CancellationTokenSource timeout = new(window); - using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( - timeout.Token, TestContext.Current.CancellationToken); + /// Reads one outbound frame. + /// The frame as a node tree. + public async Task ReadFrameAsync() + { + RelayItem item = await ReadItemAsync(TestContext.Current.CancellationToken).ConfigureAwait(false); + Assert.False(item.IsClose, "expected a data frame, but the host closed the socket first."); + return item.Frame!; + } - try + /// Reads every text frame of one reply, up to and including the closing one. + /// The token of each frame, in order. + public async Task> ReadTextFramesUntilLastAsync() { + List tokens = []; while (true) { - var item = await ReadItemAsync(linked.Token).ConfigureAwait(false); - if (item.IsClose) + JsonNode frame = await ReadFrameAsync(); + Assert.Equal("text", frame["type"]!.GetValue()); + tokens.Add(frame["token"]!.GetValue()); + + if (frame["last"]!.GetValue()) { - return frames; + return tokens; } - - frames.Add(item.Frame!); } } - catch (OperationCanceledException) when (timeout.IsCancellationRequested) - { - return frames; - } - } - /// Waits for the host to close, and reports how. - /// The close status and its description. - public async Task<(WebSocketCloseStatus? Status, string? Description)> ReadCloseAsync() - { - while (true) + /// Collects every frame that arrives inside a window. + /// How long to listen before giving up. + /// The frames received, in order. Empty when none arrived in the window. + /// + /// A test uses this to prove that no frame arrived, for example that a dropped interim + /// transcript never reaches the model. Silence is a valid outcome on this socket, so a quiet + /// window returns an empty list instead of throwing. The wait times out on the channel this + /// class reads from, never on the socket itself, so a quiet window leaves the socket exactly as + /// usable afterwards as it was before. + /// + public async Task> ReadFramesForAsync(TimeSpan window) { - var item = await ReadItemAsync(TestContext.Current.CancellationToken).ConfigureAwait(false); - if (item.IsClose) + List frames = []; + using CancellationTokenSource timeout = new(window); + using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource( + timeout.Token, TestContext.Current.CancellationToken); + + try + { + while (true) + { + RelayItem item = await ReadItemAsync(linked.Token).ConfigureAwait(false); + if (item.IsClose) + { + return frames; + } + + frames.Add(item.Frame!); + } + } + catch (OperationCanceledException) when (timeout.IsCancellationRequested) { - return (item.CloseStatus, item.CloseDescription); + return frames; } } - } - - /// Drops the socket with no close frame, exactly like a conversation that died. - public void Abort() => _socket.Abort(); - /// Stops the pump and closes the socket. - /// - /// The pump is cancelled and awaited first, and only then does this method look at - /// . waits for the peer's - /// close reply by receiving on the same socket, and a receive already in flight on the pump - /// would collide with that wait. Retiring the pump before that call keeps this the one place a - /// receive is ever cancelled on purpose, rather than leaving it dangling for a reader to trip - /// over. - /// - public async ValueTask DisposeAsync() - { - _pumpCancellation.Cancel(); - - try + /// Waits for the host to close, and reports how. + /// The close status and its description. + public async Task<(WebSocketCloseStatus? Status, string? Description)> ReadCloseAsync() { - await _pump.ConfigureAwait(false); + while (true) + { + RelayItem item = await ReadItemAsync(TestContext.Current.CancellationToken).ConfigureAwait(false); + if (item.IsClose) + { + return (item.CloseStatus, item.CloseDescription); + } + } } - catch (Exception) + + /// Drops the socket with no close frame, exactly like a conversation that died. + public void Abort() { - // The pump already reported its outcome on the channel; its task result carries nothing - // a disposing test needs. + _socket.Abort(); } - if (_socket.State is WebSocketState.Open) + /// Stops the pump and closes the socket. + /// + /// The pump is cancelled and awaited first, and only then does this method look at + /// . waits for the peer's + /// close reply by receiving on the same socket, and a receive already in flight on the pump + /// would collide with that wait. Retiring the pump before that call keeps this the one place a + /// receive is ever cancelled on purpose, rather than leaving it dangling for a reader to trip + /// over. + /// + public async ValueTask DisposeAsync() { + _pumpCancellation.Cancel(); + try { - await _socket.CloseAsync(WebSocketCloseStatus.NormalClosure, null, CancellationToken.None); + await _pump.ConfigureAwait(false); } - catch (WebSocketException) + catch (Exception) { - // The host already went away. That is the end of a conversation, not a test failure. + // The pump already reported its outcome on the channel; its task result carries nothing + // a disposing test needs. } - } - _pumpCancellation.Dispose(); - _socket.Dispose(); - } + if (_socket.State is WebSocketState.Open) + { + try + { + await _socket.CloseAsync(WebSocketCloseStatus.NormalClosure, null, CancellationToken.None); + } + catch (WebSocketException) + { + // The host already went away. That is the end of a conversation, not a test failure. + } + } - /// Reads one item off the channel the pump fills. - private async Task ReadItemAsync(CancellationToken cancellationToken) - => await _channel.Reader.ReadAsync(cancellationToken).ConfigureAwait(false); + _pumpCancellation.Dispose(); + _socket.Dispose(); + } - /// Owns every call on this socket. - /// - /// A reader that gives up on a window and a reader that wants the next frame must never race - /// each other onto the same receive, so exactly one loop, started once, does every receive and - /// hands finished messages to whichever reader is waiting on the channel. - /// - private async Task PumpAsync(CancellationToken cancellationToken) - { - try + /// Reads one item off the channel the pump fills. + private async Task ReadItemAsync(CancellationToken cancellationToken) { - while (true) - { - var buffer = new byte[8 * 1024]; - using MemoryStream message = new(); + return await _channel.Reader.ReadAsync(cancellationToken).ConfigureAwait(false); + } - WebSocketReceiveResult result; + /// Owns every call on this socket. + /// + /// A reader that gives up on a window and a reader that wants the next frame must never race + /// each other onto the same receive, so exactly one loop, started once, does every receive and + /// hands finished messages to whichever reader is waiting on the channel. + /// + private async Task PumpAsync(CancellationToken cancellationToken) + { + try + { while (true) { - result = await _socket.ReceiveAsync(buffer, cancellationToken).ConfigureAwait(false); - if (result.MessageType == WebSocketMessageType.Close) - { - await _channel.Writer.WriteAsync( - RelayItem.OfClose(_socket.CloseStatus, _socket.CloseStatusDescription), - cancellationToken).ConfigureAwait(false); - _channel.Writer.TryComplete(); - return; - } + byte[] buffer = new byte[8 * 1024]; + using MemoryStream message = new(); - message.Write(buffer, 0, result.Count); - if (result.EndOfMessage) + WebSocketReceiveResult result; + while (true) { - break; + result = await _socket.ReceiveAsync(buffer, cancellationToken).ConfigureAwait(false); + if (result.MessageType == WebSocketMessageType.Close) + { + await _channel.Writer.WriteAsync( + RelayItem.OfClose(_socket.CloseStatus, _socket.CloseStatusDescription), + cancellationToken).ConfigureAwait(false); + _ = _channel.Writer.TryComplete(); + return; + } + + message.Write(buffer, 0, result.Count); + if (result.EndOfMessage) + { + break; + } } - } - var frame = JsonNode.Parse(Encoding.UTF8.GetString(message.ToArray()))!; - await _channel.Writer.WriteAsync(RelayItem.OfFrame(frame), cancellationToken).ConfigureAwait(false); + JsonNode frame = JsonNode.Parse(Encoding.UTF8.GetString(message.ToArray()))!; + await _channel.Writer.WriteAsync(RelayItem.OfFrame(frame), cancellationToken).ConfigureAwait(false); + } + } + catch (Exception exception) + { + // The channel carries the fault forward, because a reader must see the real cause — + // a malformed frame from JsonNode.Parse, for one — and not a generic closed-channel + // exception that hides it. A test author who reads a bad frame from AgentCore needs + // that failure, not a report that this fake broke. + _ = _channel.Writer.TryComplete(exception); } } - catch (Exception exception) - { - // The channel carries the fault forward, because a reader must see the real cause — - // a malformed frame from JsonNode.Parse, for one — and not a generic closed-channel - // exception that hides it. A test author who reads a bad frame from AgentCore needs - // that failure, not a report that this fake broke. - _channel.Writer.TryComplete(exception); - } - } - /// One thing the pump collected off the wire: a frame, or the close handshake. - private readonly record struct RelayItem - { - private RelayItem(JsonNode? frame, WebSocketCloseStatus? closeStatus, string? closeDescription, bool isClose) + /// One thing the pump collected off the wire: a frame, or the close handshake. + private readonly record struct RelayItem { - Frame = frame; - CloseStatus = closeStatus; - CloseDescription = closeDescription; - IsClose = isClose; - } + private RelayItem(JsonNode? frame, WebSocketCloseStatus? closeStatus, string? closeDescription, bool isClose) + { + Frame = frame; + CloseStatus = closeStatus; + CloseDescription = closeDescription; + IsClose = isClose; + } - public JsonNode? Frame { get; } + public JsonNode? Frame { get; } - public WebSocketCloseStatus? CloseStatus { get; } + public WebSocketCloseStatus? CloseStatus { get; } - public string? CloseDescription { get; } + public string? CloseDescription { get; } - public bool IsClose { get; } + public bool IsClose { get; } - public static RelayItem OfFrame(JsonNode frame) => new(frame, null, null, isClose: false); + public static RelayItem OfFrame(JsonNode frame) + { + return new(frame, null, null, isClose: false); + } - public static RelayItem OfClose(WebSocketCloseStatus? status, string? description) - => new(null, status, description, isClose: true); + public static RelayItem OfClose(WebSocketCloseStatus? status, string? description) + { + return new(null, status, description, isClose: true); + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeWebSocket.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeWebSocket.cs index 45d7d2d9..85744991 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/FakeWebSocket.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/FakeWebSocket.cs @@ -12,407 +12,430 @@ using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// A a test drives by hand, with no Kestrel and no client socket. -/// -/// -/// -/// is still the right fake for anything the wire owns: framing, a -/// fragmented message, real backpressure, and the close handshake. Three things it cannot reach, -/// and this class exists for exactly those three. -/// -/// -/// -/// The write loop's turn-id gate. The gate sits between the dequeue and the one -/// SendAsync call the connection makes, and no real socket lets a test stop the loop in that -/// gap. does: the write loop reads immediately -/// after it dequeues an item, so parking that one read parks the loop with the item in hand and -/// the gate still ahead of it. -/// -/// -/// The close status. records the arguments rather than the bytes, so -/// a status still reaches a test after a real socket would already have aborted. -/// -/// -/// A faulting send. makes the write loop throw on demand, which -/// nothing on a healthy loopback socket does. -/// -/// -/// -/// One queued message is one WebSocket message with one fragment. Fragmentation is a wire behaviour -/// and it already has its own test over a real socket. -/// -/// -internal sealed class FakeWebSocket : WebSocket +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly Channel _inbound = Channel.CreateUnbounded( - new UnboundedChannelOptions { SingleReader = true, SingleWriter = false }); + /// + /// A a test drives by hand, with no Kestrel and no client socket. + /// + /// + /// + /// is still the right fake for anything the wire owns: framing, a + /// fragmented message, real backpressure, and the close handshake. Three things it cannot reach, + /// and this class exists for exactly those three. + /// + /// + /// + /// The write loop's turn-id gate. The gate sits between the dequeue and the one + /// SendAsync call the connection makes, and no real socket lets a test stop the loop in that + /// gap. does: the write loop reads immediately + /// after it dequeues an item, so parking that one read parks the loop with the item in hand and + /// the gate still ahead of it. + /// + /// + /// The close status. records the arguments rather than the bytes, so + /// a status still reaches a test after a real socket would already have aborted. + /// + /// + /// A faulting send. makes the write loop throw on demand, which + /// nothing on a healthy loopback socket does. + /// + /// + /// + /// One queued message is one WebSocket message with one fragment. Fragmentation is a wire behaviour + /// and it already has its own test over a real socket. + /// + /// + internal sealed class FakeWebSocket : WebSocket + { + private readonly Channel _inbound = Channel.CreateUnbounded( + new UnboundedChannelOptions { SingleReader = true, SingleWriter = false }); - private readonly Lock _gate = new(); - private readonly List _sent = []; - private readonly TaskCompletionSource _parked = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _released = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly Lock _gate = new(); + private readonly List _sent = []; + private readonly TaskCompletionSource _parked = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _released = new(TaskCreationOptions.RunContinuationsAsynchronously); - private volatile bool _parkNextStateRead; - private Exception? _sendFault; - private WebSocketState _state = WebSocketState.Open; + private volatile bool _parkNextStateRead; + private Exception? _sendFault; + private WebSocketState _state = WebSocketState.Open; - /// Gets a task that completes once the write loop parks inside . - public Task Parked => _parked.Task; + /// Gets a task that completes once the write loop parks inside . + public Task Parked => _parked.Task; - /// Gets the status and description CloseOutputAsync was called with, or null. - public (WebSocketCloseStatus Status, string? Description)? CloseSent { get; private set; } + /// Gets the status and description CloseOutputAsync was called with, or null. + public (WebSocketCloseStatus Status, string? Description)? CloseSent { get; private set; } - /// - public override WebSocketCloseStatus? CloseStatus => null; + /// + public override WebSocketCloseStatus? CloseStatus => null; - /// - public override string? CloseStatusDescription => null; + /// + public override string? CloseStatusDescription => null; - /// - public override string? SubProtocol => null; + /// + public override string? SubProtocol => null; - /// - /// - /// The write loop reads this once for each item it dequeues, before its turn-id gate and before - /// its one send. That makes this property the only observable point between the two, so parking - /// here is what lets a test hold an item in the loop's own hand while a barge-in lands. - /// - public override WebSocketState State - { - get + /// + /// + /// The write loop reads this once for each item it dequeues, before its turn-id gate and before + /// its one send. That makes this property the only observable point between the two, so parking + /// here is what lets a test hold an item in the loop's own hand while a barge-in lands. + /// + public override WebSocketState State { - // Read before the park, and answered from that read. The loop asked "is the socket - // usable" at the moment it took the item, and teardown can run while it is parked; an - // answer taken after the park would report the socket already closing, the loop would - // return before its own gate, and the gate would then look proven by a test that never - // reached it. - var state = _state; - - if (_parkNextStateRead) + get { - _parkNextStateRead = false; - _parked.TrySetResult(); - - // Blocking on purpose, and only ever on the write loop's own thread. An async park - // is not available: this is a property, and the loop reads it synchronously. - _released.Task.GetAwaiter().GetResult(); + // Read before the park, and answered from that read. The loop asked "is the socket + // usable" at the moment it took the item, and teardown can run while it is parked; an + // answer taken after the park would report the socket already closing, the loop would + // return before its own gate, and the gate would then look proven by a test that never + // reached it. + WebSocketState state = _state; + + if (_parkNextStateRead) + { + _parkNextStateRead = false; + _ = _parked.TrySetResult(); + + // Blocking on purpose, and only ever on the write loop's own thread. An async park + // is not available: this is a property, and the loop reads it synchronously. + _released.Task.GetAwaiter().GetResult(); + } + + return state; } - - return state; } - } - /// Gets every message the connection sent, as text, in order. - public IReadOnlyList Sent - { - get + /// Gets every message the connection sent, as text, in order. + public IReadOnlyList Sent { - lock (_gate) + get { - return [.. _sent]; + lock (_gate) + { + return [.. _sent]; + } } } - } - /// Arms the next read of to block until . - public void ParkNextStateRead() => _parkNextStateRead = true; + /// Arms the next read of to block until . + public void ParkNextStateRead() + { + _parkNextStateRead = true; + } - /// Lets the parked read of finish, and never parks again. - /// A test calls this from a finally, so a failed assertion never strands the loop. - public void ReleaseParkedState() - { - _parkNextStateRead = false; - _released.TrySetResult(); - } + /// Lets the parked read of finish, and never parks again. + /// A test calls this from a finally, so a failed assertion never strands the loop. + public void ReleaseParkedState() + { + _parkNextStateRead = false; + _ = _released.TrySetResult(); + } + + /// Makes every send throw, so the write loop faults. + /// The cause the loop takes. + public void FailEverySend(Exception fault) + { + _sendFault = fault; + } + + /// Queues one inbound message, exactly as the vendor would send it. + /// The frame. + public void Queue(string json) + { + _ = _inbound.Writer.TryWrite(Encoding.UTF8.GetBytes(json)); + } - /// Makes every send throw, so the write loop faults. - /// The cause the loop takes. - public void FailEverySend(Exception fault) => _sendFault = fault; + /// Queues the vendor's own close frame, which ends the read loop. + public void QueueClose() + { + _ = _inbound.Writer.TryWrite(null); + } - /// Queues one inbound message, exactly as the vendor would send it. - /// The frame. - public void Queue(string json) => _inbound.Writer.TryWrite(Encoding.UTF8.GetBytes(json)); + /// + public override async ValueTask ReceiveAsync( + Memory buffer, + CancellationToken cancellationToken) + { + byte[]? message = await _inbound.Reader.ReadAsync(cancellationToken).ConfigureAwait(false); - /// Queues the vendor's own close frame, which ends the read loop. - public void QueueClose() => _inbound.Writer.TryWrite(null); + if (message is null) + { + _state = WebSocketState.CloseReceived; + return new ValueWebSocketReceiveResult(0, WebSocketMessageType.Close, endOfMessage: true); + } - /// - public override async ValueTask ReceiveAsync( - Memory buffer, - CancellationToken cancellationToken) - { - var message = await _inbound.Reader.ReadAsync(cancellationToken).ConfigureAwait(false); + if (message.Length > buffer.Length) + { + throw new InvalidOperationException( + $"a queued frame of {message.Length} bytes does not fit the connection's own " + + $"{buffer.Length}-byte buffer. This fake sends one message as one fragment."); + } + + message.CopyTo(buffer.Span); + return new ValueWebSocketReceiveResult(message.Length, WebSocketMessageType.Text, endOfMessage: true); + } - if (message is null) + /// + /// + /// This is the overload the connection actually reaches. It passes a byte[], and C# + /// resolves that to the parameter rather than to the + /// one. A fake that only overrode the memory form would never + /// see a send at all, and every assertion about what did or did not reach the socket would then + /// pass for the wrong reason. + /// + public override Task SendAsync( + ArraySegment buffer, + WebSocketMessageType messageType, + bool endOfMessage, + CancellationToken cancellationToken) { - _state = WebSocketState.CloseReceived; - return new ValueWebSocketReceiveResult(0, WebSocketMessageType.Close, endOfMessage: true); + Record(buffer.AsMemory().Span); + return Task.CompletedTask; } - if (message.Length > buffer.Length) + /// + /// Kept beside the form, so either one a caller picks is recorded. + public override ValueTask SendAsync( + ReadOnlyMemory buffer, + WebSocketMessageType messageType, + bool endOfMessage, + CancellationToken cancellationToken) { - throw new InvalidOperationException( - $"a queued frame of {message.Length} bytes does not fit the connection's own " - + $"{buffer.Length}-byte buffer. This fake sends one message as one fragment."); + Record(buffer.Span); + return ValueTask.CompletedTask; } - message.CopyTo(buffer.Span); - return new ValueWebSocketReceiveResult(message.Length, WebSocketMessageType.Text, endOfMessage: true); - } + /// Records one send, or throws the fault a test injected. + /// The bytes the connection handed over. + private void Record(ReadOnlySpan buffer) + { + if (_sendFault is { } fault) + { + throw fault; + } - /// - /// - /// This is the overload the connection actually reaches. It passes a byte[], and C# - /// resolves that to the parameter rather than to the - /// one. A fake that only overrode the memory form would never - /// see a send at all, and every assertion about what did or did not reach the socket would then - /// pass for the wrong reason. - /// - public override Task SendAsync( - ArraySegment buffer, - WebSocketMessageType messageType, - bool endOfMessage, - CancellationToken cancellationToken) - { - Record(buffer.AsMemory().Span); - return Task.CompletedTask; - } + lock (_gate) + { + _sent.Add(Encoding.UTF8.GetString(buffer)); + } + } - /// - /// Kept beside the form, so either one a caller picks is recorded. - public override ValueTask SendAsync( - ReadOnlyMemory buffer, - WebSocketMessageType messageType, - bool endOfMessage, - CancellationToken cancellationToken) - { - Record(buffer.Span); - return ValueTask.CompletedTask; - } + /// + public override Task CloseOutputAsync( + WebSocketCloseStatus closeStatus, + string? statusDescription, + CancellationToken cancellationToken) + { + CloseSent = (closeStatus, statusDescription); + _state = WebSocketState.CloseSent; + return Task.CompletedTask; + } - /// Records one send, or throws the fault a test injected. - /// The bytes the connection handed over. - private void Record(ReadOnlySpan buffer) - { - if (_sendFault is { } fault) + /// + /// + /// The connection never calls this: CloseAsync waits for the peer's close frame, and a + /// conversation that already dropped never sends one. A conversation that reaches here is a defect worth a red + /// test rather than a silent pass. + /// + public override Task CloseAsync( + WebSocketCloseStatus closeStatus, + string? statusDescription, + CancellationToken cancellationToken) { - throw fault; + throw new NotSupportedException("the connection closes with CloseOutputAsync, never CloseAsync."); } - lock (_gate) + /// + /// The connection receives into a , so nothing reaches this form. + public override Task ReceiveAsync( + ArraySegment buffer, + CancellationToken cancellationToken) { - _sent.Add(Encoding.UTF8.GetString(buffer)); + throw new NotSupportedException("the connection receives into a Memory."); } - } - /// - public override Task CloseOutputAsync( - WebSocketCloseStatus closeStatus, - string? statusDescription, - CancellationToken cancellationToken) - { - CloseSent = (closeStatus, statusDescription); - _state = WebSocketState.CloseSent; - return Task.CompletedTask; + /// + public override void Abort() + { + _state = WebSocketState.Aborted; + } + + /// + /// + /// Completing the inbound channel here is what releases a receive the read loop abandoned to + /// its idle race. That receive owns a rented buffer until it finishes, so leaving it pending + /// forever would keep the array out of ArrayPool for the life of the test run. + /// + public override void Dispose() + { + _state = WebSocketState.Closed; + _ = _inbound.Writer.TryComplete(); + ReleaseParkedState(); + } } - /// - /// - /// The connection never calls this: CloseAsync waits for the peer's close frame, and a - /// conversation that already dropped never sends one. A conversation that reaches here is a defect worth a red - /// test rather than a silent pass. - /// - public override Task CloseAsync( - WebSocketCloseStatus closeStatus, - string? statusDescription, - CancellationToken cancellationToken) - => throw new NotSupportedException("the connection closes with CloseOutputAsync, never CloseAsync."); - - /// - /// The connection receives into a , so nothing reaches this form. - public override Task ReceiveAsync( - ArraySegment buffer, - CancellationToken cancellationToken) - => throw new NotSupportedException("the connection receives into a Memory."); - - /// - public override void Abort() => _state = WebSocketState.Aborted; - - /// + /// + /// An application lifetime a test owns, so a test can stop the host without one. + /// /// - /// Completing the inbound channel here is what releases a receive the read loop abandoned to - /// its idle race. That receive owns a rented buffer until it finishes, so leaving it pending - /// forever would keep the array out of ArrayPool for the life of the test run. + /// The connection links its own token to and reads that same token + /// again when it picks a close status, so this is the only seam a test needs to prove the + /// host-stopping path. /// - public override void Dispose() + internal sealed class TestHostLifetime : IHostApplicationLifetime, IDisposable { - _state = WebSocketState.Closed; - _inbound.Writer.TryComplete(); - ReleaseParkedState(); - } -} - -/// -/// An application lifetime a test owns, so a test can stop the host without one. -/// -/// -/// The connection links its own token to and reads that same token -/// again when it picks a close status, so this is the only seam a test needs to prove the -/// host-stopping path. -/// -internal sealed class TestHostLifetime : IHostApplicationLifetime, IDisposable -{ - private readonly CancellationTokenSource _started = new(); - private readonly CancellationTokenSource _stopping = new(); - private readonly CancellationTokenSource _stopped = new(); - - public CancellationToken ApplicationStarted => _started.Token; + private readonly CancellationTokenSource _started = new(); + private readonly CancellationTokenSource _stopping = new(); + private readonly CancellationTokenSource _stopped = new(); - public CancellationToken ApplicationStopping => _stopping.Token; + public CancellationToken ApplicationStarted => _started.Token; - public CancellationToken ApplicationStopped => _stopped.Token; + public CancellationToken ApplicationStopping => _stopping.Token; - public void StopApplication() - { - _stopping.Cancel(); - _stopped.Cancel(); - } + public CancellationToken ApplicationStopped => _stopped.Token; - public void Dispose() - { - _started.Dispose(); - _stopping.Dispose(); - _stopped.Dispose(); - } -} + public void StopApplication() + { + _stopping.Cancel(); + _stopped.Cancel(); + } -/// -/// One driven straight over a . -/// -/// -/// RunAsync takes the abstract , so nothing here needs Kestrel, a -/// port, or a client socket. The service provider is the real one AddAgentCore builds, so -/// the session factory, the store, and the clock behave exactly as they do on a live conversation. -/// -internal sealed class RelayConnectionHarness : IAsyncDisposable -{ - private readonly ServiceProvider _services; - private readonly TestHostLifetime _lifetime; - - private RelayConnectionHarness( - ServiceProvider services, - TestHostLifetime lifetime, - FakeWebSocket socket, - Task connection) - { - _services = services; - _lifetime = lifetime; - Socket = socket; - Connection = connection; + public void Dispose() + { + _started.Dispose(); + _stopping.Dispose(); + _stopped.Dispose(); + } } - /// Gets the socket a test queues frames on and reads sends off. - public FakeWebSocket Socket { get; } - - /// Gets the container the connection resolves everything from. + /// + /// One driven straight over a . + /// /// - /// The provider is the real one AddAgentCore builds, so a test reads the live session - /// store, the audit queue, and the store behind it exactly as the connection does. It is exposed - /// rather than mirrored in properties of this class, because what one test wants out of the - /// container is no business of the next one. + /// RunAsync takes the abstract , so nothing here needs Kestrel, a + /// port, or a client socket. The service provider is the real one AddAgentCore builds, so + /// the session factory, the store, and the clock behave exactly as they do on a live conversation. /// - public IServiceProvider Services => _services; - - /// Gets the task that completes when the connection has torn itself down. - public Task Connection { get; } - - /// Starts one connection over one document and one fake model. - /// The document, as YAML. - /// The model behind every agent. - /// Anything a test adds to the logging pipeline. - /// Anything a test binds on the relay endpoint's own options. - /// - /// Anything else the test binds on the container's own options, for example the clock every - /// conversation and every connection then runs on. - /// - /// - /// Anything a test registers over what AddAgentCore registered. It runs after that conversation, - /// so a registration here is the last one and the connection resolves it. - /// - /// The running harness. - public static async Task StartAsync( - string yaml, - IChatClient reply, - Action? logging = null, - Action? relay = null, - Action? configure = null, - Action? services = null) + internal sealed class RelayConnectionHarness : IAsyncDisposable { - ServiceCollection collection = new(); - collection.AddLogging(builder => + private readonly ServiceProvider _services; + private readonly TestHostLifetime _lifetime; + + private RelayConnectionHarness( + ServiceProvider services, + TestHostLifetime lifetime, + FakeWebSocket socket, + Task connection) { - builder.ClearProviders(); - logging?.Invoke(builder); - }); + _services = services; + _lifetime = lifetime; + Socket = socket; + Connection = connection; + } - TestHostLifetime lifetime = new(); - collection.AddSingleton(lifetime); - collection.AddAgentCore(options => + /// Gets the socket a test queues frames on and reads sends off. + public FakeWebSocket Socket { get; } + + /// Gets the container the connection resolves everything from. + /// + /// The provider is the real one AddAgentCore builds, so a test reads the live session + /// store, the audit queue, and the store behind it exactly as the connection does. It is exposed + /// rather than mirrored in properties of this class, because what one test wants out of the + /// container is no business of the next one. + /// + public IServiceProvider Services => _services; + + /// Gets the task that completes when the connection has torn itself down. + public Task Connection { get; } + + /// Starts one connection over one document and one fake model. + /// The document, as YAML. + /// The model behind every agent. + /// Anything a test adds to the logging pipeline. + /// Anything a test binds on the relay endpoint's own options. + /// + /// Anything else the test binds on the container's own options, for example the clock every + /// conversation and every connection then runs on. + /// + /// + /// Anything a test registers over what AddAgentCore registered. It runs after that conversation, + /// so a registration here is the last one and the connection resolves it. + /// + /// The running harness. + public static async Task StartAsync( + string yaml, + IChatClient reply, + Action? logging = null, + Action? relay = null, + Action? configure = null, + Action? services = null) { - options.Configuration = ConfigurationLoader.LoadYaml(yaml); - options.UseChatClients(_ => new RoutingChatClientFactory(reply)); - configure?.Invoke(options); - }); - - services?.Invoke(collection); + ServiceCollection collection = new(); + _ = collection.AddLogging(builder => + { + _ = builder.ClearProviders(); + logging?.Invoke(builder); + }); - var provider = collection.BuildServiceProvider(); + TestHostLifetime lifetime = new(); + _ = collection.AddSingleton(lifetime); + _ = collection.AddAgentCore(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(yaml); + _ = options.UseChatClients(_ => new RoutingChatClientFactory(reply)); + configure?.Invoke(options); + }); - // There is no host here, so nothing else would run the boot. This is the same hook a host - // uses, in the same order, so the harness reaches a graph composed exactly as production - // composes it. - foreach (var service in provider.GetServices().OfType()) - { - await service.StartingAsync(CancellationToken.None); - } + services?.Invoke(collection); - DefaultHttpContext http = new() { RequestServices = provider }; - http.Request.RouteValues[ConversationEndpointRouteBuilderExtensions.EntryRouteParameter] = "main"; + ServiceProvider provider = collection.BuildServiceProvider(); - TelnyxRelayOptions options = new(); - relay?.Invoke(options); + // There is no host here, so nothing else would run the boot. This is the same hook a host + // uses, in the same order, so the harness reaches a graph composed exactly as production + // composes it. + foreach (IHostedLifecycleService service in provider.GetServices().OfType()) + { + await service.StartingAsync(CancellationToken.None); + } - FakeWebSocket socket = new(); - var connection = TelnyxRelayConnection.RunAsync(http, socket, options); + DefaultHttpContext http = new() { RequestServices = provider }; + http.Request.RouteValues[ConversationEndpointRouteBuilderExtensions.EntryRouteParameter] = "main"; - return new RelayConnectionHarness(provider, lifetime, socket, connection); - } - /// Stops the host, which is what the EndpointUnavailable close status reports. - public void StopApplication() => _lifetime.StopApplication(); + TelnyxRelayOptions options = new(); + relay?.Invoke(options); - /// Ends the connection and releases everything behind it. - public async ValueTask DisposeAsync() - { - // A test that failed early may have left the write loop parked or the read loop waiting, so - // both are released here before anything waits on the connection task. - Socket.ReleaseParkedState(); - Socket.QueueClose(); + FakeWebSocket socket = new(); + Task connection = TelnyxRelayConnection.RunAsync(http, socket, options); - try - { - await Connection.WaitAsync(TimeSpan.FromSeconds(20)).ConfigureAwait(false); + return new RelayConnectionHarness(provider, lifetime, socket, connection); } - catch (Exception) + /// Stops the host, which is what the EndpointUnavailable close status reports. + public void StopApplication() { - // The connection's own faults belong to whichever assertion a test already made about - // them. Disposal only has to stop waiting. + _lifetime.StopApplication(); } - Socket.Dispose(); - _lifetime.Dispose(); - await _services.DisposeAsync().ConfigureAwait(false); + /// Ends the connection and releases everything behind it. + public async ValueTask DisposeAsync() + { + // A test that failed early may have left the write loop parked or the read loop waiting, so + // both are released here before anything waits on the connection task. + Socket.ReleaseParkedState(); + Socket.QueueClose(); + + try + { + await Connection.WaitAsync(TimeSpan.FromSeconds(20)).ConfigureAwait(false); + } + catch (Exception) + { + // The connection's own faults belong to whichever assertion a test already made about + // them. Disposal only has to stop waiting. + } + + Socket.Dispose(); + _lifetime.Dispose(); + await _services.DisposeAsync().ConfigureAwait(false); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/HostFakes.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/HostFakes.cs index d97e76c1..7479d4a4 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/HostFakes.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/HostFakes.cs @@ -1,346 +1,344 @@ using System.Runtime.CompilerServices; using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// A deterministic offline model that answers one reply for each request, in order. -/// -/// -/// The turn loop makes two model calls in one turn, the reply and the extractor, and they need -/// different answers. This client answers a list, and it holds the last answer once the list runs -/// out. The streaming path yields one update for each word, so a test can see the reply arrive in -/// pieces rather than in one block. -/// -internal sealed class FragmentingChatClient : IChatClient +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly string[] _replies; - private int _calls; - - public FragmentingChatClient(params string[] replies) => _replies = replies; - - /// Gets how many requests this client answered. - public int Calls => Volatile.Read(ref _calls); - - /// Gets the messages of the most recent request, oldest first, or null before any conversation. + /// + /// A deterministic offline model that answers one reply for each request, in order. + /// /// - /// A test reads this to prove which text actually reached the model — for example that an - /// interim transcript never substitutes for the final one, rather than only counting how many - /// times the model ran. + /// The turn loop makes two model calls in one turn, the reply and the extractor, and they need + /// different answers. This client answers a list, and it holds the last answer once the list runs + /// out. The streaming path yields one update for each word, so a test can see the reply arrive in + /// pieces rather than in one block. /// - public IReadOnlyList? LastRequest { get; private set; } - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) + internal sealed class FragmentingChatClient(params string[] replies) : IChatClient { - ArgumentNullException.ThrowIfNull(messages); + private readonly string[] _replies = replies; + private int _calls; + + /// Gets how many requests this client answered. + public int Calls => Volatile.Read(ref _calls); + + /// Gets the messages of the most recent request, oldest first, or null before any conversation. + /// + /// A test reads this to prove which text actually reached the model — for example that an + /// interim transcript never substitutes for the final one, rather than only counting how many + /// times the model ran. + /// + public IReadOnlyList? LastRequest { get; private set; } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - var index = Interlocked.Increment(ref _calls) - 1; - var reply = _replies[Math.Min(index, _replies.Length - 1)]; - var responseId = Guid.NewGuid().ToString("N"); - LastRequest = [.. messages]; + int index = Interlocked.Increment(ref _calls) - 1; + string reply = _replies[Math.Min(index, _replies.Length - 1)]; + string responseId = Guid.NewGuid().ToString("N"); + LastRequest = [.. messages]; - foreach (var fragment in Fragments(reply)) - { - await Task.Yield(); - yield return new ChatResponseUpdate(ChatRole.Assistant, fragment) + foreach (string fragment in Fragments(reply)) { - ResponseId = responseId, - MessageId = responseId, - }; + await Task.Yield(); + yield return new ChatResponseUpdate(ChatRole.Assistant, fragment) + { + ResponseId = responseId, + MessageId = responseId, + }; + } } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - updates.Add(update); + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public void Dispose() + { + // Nothing to release. + } - public void Dispose() - { - // Nothing to release. + /// Cuts one reply into the pieces the streaming path yields. + /// + /// An extractor answer is one JSON document and must not be cut, because the extractor parses the + /// whole text. Everything else is speech, and speech arrives word by word. + /// + private static IEnumerable Fragments(string reply) + { + return reply.StartsWith('{') ? [reply] : reply.Split(' ').Select((word, index) => index == 0 ? word : " " + word); + } } - /// Cuts one reply into the pieces the streaming path yields. + /// + /// A deterministic offline model that streams one reply, and pauses after the first piece leaves. + /// /// - /// An extractor answer is one JSON document and must not be cut, because the extractor parses the - /// whole text. Everything else is speech, and speech arrives word by word. + /// A barge-in test needs to send an interrupt frame while a reply is mid-flight, and that race is + /// unwinnable against a client that finishes streaming before the test can act. Gating on a + /// instead of a delay means the pause is exact: the test learns + /// the moment the first piece left, and the client waits until the test says to go on. /// - private static IEnumerable Fragments(string reply) + internal sealed class BlockingChatClient(string reply) : IChatClient { - if (reply.StartsWith('{')) - { - return [reply]; - } + private readonly string _reply = reply; + private readonly TaskCompletionSource _started = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _released = new(TaskCreationOptions.RunContinuationsAsynchronously); + private int _calls; - return reply.Split(' ').Select((word, index) => index == 0 ? word : " " + word); - } -} + /// Gets how many requests this client answered. + public int Calls => Volatile.Read(ref _calls); -/// -/// A deterministic offline model that streams one reply, and pauses after the first piece leaves. -/// -/// -/// A barge-in test needs to send an interrupt frame while a reply is mid-flight, and that race is -/// unwinnable against a client that finishes streaming before the test can act. Gating on a -/// instead of a delay means the pause is exact: the test learns -/// the moment the first piece left, and the client waits until the test says to go on. -/// -internal sealed class BlockingChatClient : IChatClient -{ - private readonly string _reply; - private readonly TaskCompletionSource _started = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _released = new(TaskCreationOptions.RunContinuationsAsynchronously); - private int _calls; + /// Waits until the first update of the reply has left the client. + /// A task that completes once the first piece is on its way. + public Task WaitUntilStreamingAsync() + { + return _started.Task; + } - public BlockingChatClient(string reply) => _reply = reply; + /// Lets every update after the first flow. + public void Release() + { + _ = _released.TrySetResult(); + } - /// Gets how many requests this client answered. - public int Calls => Volatile.Read(ref _calls); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - /// Waits until the first update of the reply has left the client. - /// A task that completes once the first piece is on its way. - public Task WaitUntilStreamingAsync() => _started.Task; + _ = Interlocked.Increment(ref _calls); + string responseId = Guid.NewGuid().ToString("N"); + List fragments = [.. Fragments(_reply)]; - /// Lets every update after the first flow. - public void Release() => _released.TrySetResult(); + for (int index = 0; index < fragments.Count; index++) + { + if (index == 1) + { + // The first piece already left below. This is the gate a barge-in test opens. + await _released.Task; + } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); + yield return new ChatResponseUpdate(ChatRole.Assistant, fragments[index]) + { + ResponseId = responseId, + MessageId = responseId, + }; - Interlocked.Increment(ref _calls); - var responseId = Guid.NewGuid().ToString("N"); - var fragments = Fragments(_reply).ToList(); + if (index == 0) + { + // This line runs on the next pull, which only happens once the caller already has + // the first update, so "started" here really does mean "left the client". + _ = _started.TrySetResult(); + } + } + } - for (var index = 0; index < fragments.Count; index++) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - if (index == 1) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - // The first piece already left below. This is the gate a barge-in test opens. - await _released.Task; + updates.Add(update); } - await Task.Yield(); - yield return new ChatResponseUpdate(ChatRole.Assistant, fragments[index]) - { - ResponseId = responseId, - MessageId = responseId, - }; - - if (index == 0) - { - // This line runs on the next pull, which only happens once the caller already has - // the first update, so "started" here really does mean "left the client". - _started.TrySetResult(); - } + return updates.ToChatResponse(); } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public void Dispose() + { + // Nothing to release. + } - public void Dispose() - { - // Nothing to release. + /// Cuts one reply into the pieces the streaming path yields. + /// + /// An extractor answer is one JSON document and must not be cut, because the extractor parses the + /// whole text. Everything else is speech, and speech arrives word by word. + /// + private static IEnumerable Fragments(string reply) + { + return reply.StartsWith('{') ? [reply] : reply.Split(' ').Select((word, index) => index == 0 ? word : " " + word); + } } - /// Cuts one reply into the pieces the streaming path yields. + /// + /// Streams a first reply that pauses after its first piece, then holds the second reply back + /// before it says a word. + /// /// - /// An extractor answer is one JSON document and must not be cut, because the extractor parses the - /// whole text. Everything else is speech, and speech arrives word by word. + /// This is the shape a held prompt produces on a real conversation. Turn one pauses long enough for a + /// second final prompt to be held, then finishes streaming; RunPendingPrompt starts turn two + /// inside turn one's own finally; and the vendor is still speaking turn one while turn two + /// has produced nothing at all. No other fake here can hold the second turn apart from the first. /// - private static IEnumerable Fragments(string reply) + internal sealed class HeldPromptChatClient(string first, string second) : IChatClient { - if (reply.StartsWith('{')) + private readonly string _first = first; + private readonly string _second = second; + private readonly TaskCompletionSource _firstStreaming = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _firstGate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _secondGate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private int _calls; + + /// Gets a task that completes once the second turn's model call is in flight and blocked. + public TaskCompletionSource SecondTurnStarted { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /// Gets whether the second turn opens with one update the relay can never speak. + /// + /// + /// ConversationSession calls a run audible at its first piece of content, and content is not + /// the same thing as a word. A tool call, a tool result, and a line of reasoning all count, and + /// none of them carries text, so none of them ever reaches the vendor as a text frame. Set + /// this, and turn two yields exactly one such update — a , the + /// shape a reasoning model really does stream before its answer — and only then blocks. That is + /// the one window in which the core believes turn two is audible while the connection's own + /// _spokenTurnId still names turn one, which is the turn Telnyx is still speaking. + /// + /// + /// Left , turn two says nothing whatever before it blocks, which is the + /// window AnInterruptWhileAHeldTurnHasSaidNothing_LeavesThatTurnFreeToSpeak already covers + /// and which both sides of the seam already agree about on their own. + /// + /// + public bool SecondTurnOpensWithUnspokenContent { get; init; } + + /// Waits until the first piece of the first reply has left this client. + public Task WaitUntilFirstTurnStreamingAsync() { - return [reply]; + return _firstStreaming.Task; } - return reply.Split(' ').Select((word, index) => index == 0 ? word : " " + word); - } -} - -/// -/// Streams a first reply that pauses after its first piece, then holds the second reply back -/// before it says a word. -/// -/// -/// This is the shape a held prompt produces on a real conversation. Turn one pauses long enough for a -/// second final prompt to be held, then finishes streaming; RunPendingPrompt starts turn two -/// inside turn one's own finally; and the vendor is still speaking turn one while turn two -/// has produced nothing at all. No other fake here can hold the second turn apart from the first. -/// -internal sealed class HeldPromptChatClient : IChatClient -{ - private readonly string _first; - private readonly string _second; - private readonly TaskCompletionSource _firstStreaming = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _firstGate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _secondGate = new(TaskCreationOptions.RunContinuationsAsynchronously); - private int _calls; - - public HeldPromptChatClient(string first, string second) - { - _first = first; - _second = second; - } - - /// Gets a task that completes once the second turn's model call is in flight and blocked. - public TaskCompletionSource SecondTurnStarted { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); - - /// Gets whether the second turn opens with one update the relay can never speak. - /// - /// - /// ConversationSession calls a run audible at its first piece of content, and content is not - /// the same thing as a word. A tool call, a tool result, and a line of reasoning all count, and - /// none of them carries text, so none of them ever reaches the vendor as a text frame. Set - /// this, and turn two yields exactly one such update — a , the - /// shape a reasoning model really does stream before its answer — and only then blocks. That is - /// the one window in which the core believes turn two is audible while the connection's own - /// _spokenTurnId still names turn one, which is the turn Telnyx is still speaking. - /// - /// - /// Left , turn two says nothing whatever before it blocks, which is the - /// window AnInterruptWhileAHeldTurnHasSaidNothing_LeavesThatTurnFreeToSpeak already covers - /// and which both sides of the seam already agree about on their own. - /// - /// - public bool SecondTurnOpensWithUnspokenContent { get; init; } - - /// Waits until the first piece of the first reply has left this client. - public Task WaitUntilFirstTurnStreamingAsync() => _firstStreaming.Task; + /// Lets the rest of the first reply flow. + public void ReleaseFirstTurn() + { + _ = _firstGate.TrySetResult(); + } - /// Lets the rest of the first reply flow. - public void ReleaseFirstTurn() => _firstGate.TrySetResult(); + /// Lets the second reply flow. + public void ReleaseSecondTurn() + { + _ = _secondGate.TrySetResult(); + } - /// Lets the second reply flow. - public void ReleaseSecondTurn() => _secondGate.TrySetResult(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); + int index = Interlocked.Increment(ref _calls); + string responseId = Guid.NewGuid().ToString("N"); - var index = Interlocked.Increment(ref _calls); - var responseId = Guid.NewGuid().ToString("N"); + if (index > 1) + { + if (SecondTurnOpensWithUnspokenContent) + { + // Yielded before SecondTurnStarted is set, and the line after a yield only runs once + // the consumer comes back for the next update. Waiting on that signal therefore + // proves this update has already travelled the whole way through ConversationSession — which + // is where it raises the audible flag this fake exists to raise — and through the + // connection's own update loop, which reads no text on it and so leaves + // _spokenTurnId naming turn one. + yield return new ChatResponseUpdate(ChatRole.Assistant, [new TextReasoningContent("thinking")]) + { + ResponseId = responseId, + MessageId = responseId, + }; + } + + _ = SecondTurnStarted.TrySetResult(); + + // The token is deliberately not read here. A defect that cancelled this turn would + // otherwise end it quietly and look like the pass this fake exists to disprove. + await _secondGate.Task.ConfigureAwait(false); + } - if (index > 1) - { - if (SecondTurnOpensWithUnspokenContent) + List fragments = [.. Fragments(index == 1 ? _first : _second)]; + for (int piece = 0; piece < fragments.Count; piece++) { - // Yielded before SecondTurnStarted is set, and the line after a yield only runs once - // the consumer comes back for the next update. Waiting on that signal therefore - // proves this update has already travelled the whole way through ConversationSession — which - // is where it raises the audible flag this fake exists to raise — and through the - // connection's own update loop, which reads no text on it and so leaves - // _spokenTurnId naming turn one. - yield return new ChatResponseUpdate(ChatRole.Assistant, [new TextReasoningContent("thinking")]) + if (index == 1 && piece == 1) + { + await _firstGate.Task.ConfigureAwait(false); + } + + await Task.Yield(); + yield return new ChatResponseUpdate(ChatRole.Assistant, fragments[piece]) { ResponseId = responseId, MessageId = responseId, }; - } - SecondTurnStarted.TrySetResult(); - - // The token is deliberately not read here. A defect that cancelled this turn would - // otherwise end it quietly and look like the pass this fake exists to disprove. - await _secondGate.Task.ConfigureAwait(false); + if (index == 1 && piece == 0) + { + // This line runs on the next pull, so "streaming" here means the first piece has + // really left the client and the connection has already queued it. + _ = _firstStreaming.TrySetResult(); + } + } } - var fragments = Fragments(index == 1 ? _first : _second).ToList(); - for (var piece = 0; piece < fragments.Count; piece++) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - if (index == 1 && piece == 1) + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) { - await _firstGate.Task.ConfigureAwait(false); + updates.Add(update); } - await Task.Yield(); - yield return new ChatResponseUpdate(ChatRole.Assistant, fragments[piece]) - { - ResponseId = responseId, - MessageId = responseId, - }; - - if (index == 1 && piece == 0) - { - // This line runs on the next pull, so "streaming" here means the first piece has - // really left the client and the connection has already queued it. - _firstStreaming.TrySetResult(); - } + return updates.ToChatResponse(); } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public void Dispose() + { + // Nothing to release. + } - public void Dispose() - { - // Nothing to release. + /// Cuts one reply into the pieces the streaming path yields. + private static IEnumerable Fragments(string reply) + { + return reply.Split(' ').Select((word, index) => index == 0 ? word : " " + word); + } } - - /// Cuts one reply into the pieces the streaming path yields. - private static IEnumerable Fragments(string reply) - => reply.Split(' ').Select((word, index) => index == 0 ? word : " " + word); } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/RelayFrames.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/RelayFrames.cs index f66cd3c0..8d343006 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/RelayFrames.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/RelayFrames.cs @@ -1,42 +1,53 @@ -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// The frames Telnyx sends, as the vendor page prints them. -/// -/// -/// The bodies are golden inputs, so a test's expectations trace back to §7.1 and the frame reader -/// this project already ships. A test that needs a different shape writes the JSON itself rather -/// than adding a parameter here, so this file stays a record of the real wire. -/// -internal static class RelayFrames +namespace AgentCore.AspNetCore.Tests.Fakes { - /// Builds the first frame of a conversation. - public static string Setup(string conversationSessionId = "conversation-one", string callControlId = "v2:leg-one") - => $$""" + /// + /// The frames Telnyx sends, as the vendor page prints them. + /// + /// + /// The bodies are golden inputs, so a test's expectations trace back to §7.1 and the frame reader + /// this project already ships. A test that needs a different shape writes the JSON itself rather + /// than adding a parameter here, so this file stays a record of the real wire. + /// + internal static class RelayFrames + { + /// Builds the first frame of a conversation. + public static string Setup(string conversationSessionId = "conversation-one", string callControlId = "v2:leg-one") + { + return $$""" {"type":"setup","sessionId":"session-one","accountSid":"account-one", "callSid":"{{callControlId}}","callControlId":"{{callControlId}}", "conversationSessionId":"{{conversationSessionId}}","callLegId":"leg-one", "from":"+13122010094","to":"+13122123456","direction":"inbound", "callerName":"","customParameters":{},"conversationStatus":"active"} """; + } - /// Builds one transcript frame. - /// What the caller said. - /// True for a final transcript, false for an interim one. - public static string Prompt(string text, bool last) - => $$"""{"type":"prompt","voicePrompt":"{{text}}","lang":"en","last":{{(last ? "true" : "false")}}}"""; + /// Builds one transcript frame. + /// What the caller said. + /// True for a final transcript, false for an interim one. + public static string Prompt(string text, bool last) + { + return $$"""{"type":"prompt","voicePrompt":"{{text}}","lang":"en","last":{{(last ? "true" : "false")}}}"""; + } - /// Builds the truncation record. - public static string Interrupt(string heard, int durationMs) - => $$""" + /// Builds the truncation record. + public static string Interrupt(string heard, int durationMs) + { + return $$""" {"type":"interrupt","utteranceUntilInterrupt":"{{heard}}","durationUntilInterruptMs":{{durationMs}}} """; + } - /// Builds one key press. - public static string Dtmf(string digit) - => $$"""{"type":"dtmf","digit":"{{digit}}"}"""; + /// Builds one key press. + public static string Dtmf(string digit) + { + return $$"""{"type":"dtmf","digit":"{{digit}}"}"""; + } - /// Builds the frame the vendor sends when it refuses one of ours. - public static string Error(string description) - => $$"""{"type":"error","description":"{{description}}"}"""; + /// Builds the frame the vendor sends when it refuses one of ours. + public static string Error(string description) + { + return $$"""{"type":"error","description":"{{description}}"}"""; + } + } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/ResponsesHost.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/ResponsesHost.cs index 86533023..b72aabf0 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/ResponsesHost.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/ResponsesHost.cs @@ -13,145 +13,148 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// One real host, on a real socket, over a fake model, answering the Responses path. -/// -/// -/// Kestrel takes port zero and reports the port it got, so many tests run at once. The socket is real -/// on purpose: a server-sent event is a wire behaviour, and an in-memory pipe would not prove that the -/// endpoint writes one event for each update. No test here reaches a network or needs an API key. -/// -internal sealed class ResponsesHost : IAsyncDisposable +namespace AgentCore.AspNetCore.Tests.Fakes { - private const string DataPrefix = "data: "; - private readonly WebApplication _app; - - private ResponsesHost(WebApplication app, HttpClient client) + /// + /// One real host, on a real socket, over a fake model, answering the Responses path. + /// + /// + /// Kestrel takes port zero and reports the port it got, so many tests run at once. The socket is real + /// on purpose: a server-sent event is a wire behaviour, and an in-memory pipe would not prove that the + /// endpoint writes one event for each update. No test here reaches a network or needs an API key. + /// + internal sealed class ResponsesHost : IAsyncDisposable { - _app = app; - Client = client; - } + private const string DataPrefix = "data: "; + private readonly WebApplication _app; - /// Gets the client that speaks to the host. - public HttpClient Client { get; } + private ResponsesHost(WebApplication app, HttpClient client) + { + _app = app; + Client = client; + } - /// Gets the started host's services, for a test that reads what a turn stored. - public IServiceProvider Services => _app.Services; + /// Gets the client that speaks to the host. + public HttpClient Client { get; } - /// Starts one host over one document. - /// The document, as YAML. - /// The model behind every name the routing factory does not hold. - /// Anything else the test binds on the options. - /// The started host. - public static async Task StartAsync( - string yaml, IChatClient reply, Action? configure = null) - { - var builder = WebApplication.CreateSlimBuilder(); - builder.WebHost.UseUrls("http://127.0.0.1:0"); - builder.Logging.ClearProviders(); + /// Gets the started host's services, for a test that reads what a turn stored. + public IServiceProvider Services => _app.Services; - builder.Services.AddAgentCore(options => + /// Starts one host over one document. + /// The document, as YAML. + /// The model behind every name the routing factory does not hold. + /// Anything else the test binds on the options. + /// The started host. + public static async Task StartAsync( + string yaml, IChatClient reply, Action? configure = null) { - options.Configuration = ConfigurationLoader.LoadYaml(yaml); - options.UseChatClients(_ => new RoutingChatClientFactory(reply)); - configure?.Invoke(options); - }); - - var app = builder.Build(); - app.MapResponses(); - await app.StartAsync(); - - var address = app.Services - .GetRequiredService() - .Features - .Get()! - .Addresses - .First(); - - HttpClient client = new() { BaseAddress = new Uri(address, UriKind.Absolute) }; - return new ResponsesHost(app, client); - } + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + _ = builder.WebHost.UseUrls("http://127.0.0.1:0"); + _ = builder.Logging.ClearProviders(); - /// Sends one Responses request body. - /// The request body. - /// Request headers to send beside the body, or none. - /// The answer. - public async Task PostAsync(string json, IReadOnlyDictionary? headers = null) - { - using HttpRequestMessage request = new(HttpMethod.Post, "/v1/main/responses") - { - Content = new StringContent(json, Encoding.UTF8, "application/json"), - }; + _ = builder.Services.AddAgentCore(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(yaml); + _ = options.UseChatClients(_ => new RoutingChatClientFactory(reply)); + configure?.Invoke(options); + }); + + WebApplication app = builder.Build(); + _ = app.MapResponses(); + await app.StartAsync(); + + string address = app.Services + .GetRequiredService() + .Features + .Get()! + .Addresses + .First(); + + HttpClient client = new() { BaseAddress = new Uri(address, UriKind.Absolute) }; + return new ResponsesHost(app, client); + } - foreach (var (name, value) in headers ?? new Dictionary()) + /// Sends one Responses request body. + /// The request body. + /// Request headers to send beside the body, or none. + /// The answer. + public async Task PostAsync(string json, IReadOnlyDictionary? headers = null) { - request.Headers.TryAddWithoutValidation(name, value); - } + using HttpRequestMessage request = new(HttpMethod.Post, "/v1/main/responses") + { + Content = new StringContent(json, Encoding.UTF8, "application/json"), + }; - return await Client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, TestContext.Current.CancellationToken); - } + foreach ((string? name, string? value) in headers ?? new Dictionary()) + { + _ = request.Headers.TryAddWithoutValidation(name, value); + } - /// Reads every server-sent event of one answer. - /// The answer, with the body still open. - /// The text after each data: prefix, in order. - public static async Task> ReadEventsAsync(HttpResponseMessage response) - { - List events = []; - await using var body = await response.Content.ReadAsStreamAsync(TestContext.Current.CancellationToken); - using StreamReader reader = new(body, Encoding.UTF8); + return await Client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, TestContext.Current.CancellationToken); + } - while (await reader.ReadLineAsync(TestContext.Current.CancellationToken) is { } line) + /// Reads every server-sent event of one answer. + /// The answer, with the body still open. + /// The text after each data: prefix, in order. + public static async Task> ReadEventsAsync(HttpResponseMessage response) { - if (line.StartsWith(DataPrefix, StringComparison.Ordinal)) + List events = []; + await using Stream body = await response.Content.ReadAsStreamAsync(TestContext.Current.CancellationToken); + using StreamReader reader = new(body, Encoding.UTF8); + + while (await reader.ReadLineAsync(TestContext.Current.CancellationToken) is { } line) { - events.Add(line[DataPrefix.Length..]); + if (line.StartsWith(DataPrefix, StringComparison.Ordinal)) + { + events.Add(line[DataPrefix.Length..]); + } } - } - return events; - } + return events; + } - /// Reads the text of every text delta of one stream. - /// The events the stream carried. - /// The pieces, in order. - public static List TextDeltas(IEnumerable events) - { - List pieces = []; - foreach (var raw in events) + /// Reads the text of every text delta of one stream. + /// The events the stream carried. + /// The pieces, in order. + public static List TextDeltas(IEnumerable events) { - var frame = JsonNode.Parse(raw)!.AsObject(); - if (string.Equals(frame["type"]?.GetValue(), "response.output_text.delta", StringComparison.Ordinal) - && frame["delta"]?.GetValue() is { Length: > 0 } text) + List pieces = []; + foreach (string raw in events) { - pieces.Add(text); + JsonObject frame = JsonNode.Parse(raw)!.AsObject(); + if (string.Equals(frame["type"]?.GetValue(), "response.output_text.delta", StringComparison.Ordinal) + && frame["delta"]?.GetValue() is { Length: > 0 } text) + { + pieces.Add(text); + } } - } - return pieces; - } + return pieces; + } - /// Reads one answer as a node tree. - /// The answer. - /// The body. - public static async Task ReadJsonAsync(HttpResponseMessage response) - { - var text = await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken); - return JsonNode.Parse(text)!; - } + /// Reads one answer as a node tree. + /// The answer. + /// The body. + public static async Task ReadJsonAsync(HttpResponseMessage response) + { + string text = await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken); + return JsonNode.Parse(text)!; + } - /// Reads one answer as text. - /// The answer. - /// The body. - public static Task ReadTextAsync(HttpResponseMessage response) - => response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken); + /// Reads one answer as text. + /// The answer. + /// The body. + public static Task ReadTextAsync(HttpResponseMessage response) + { + return response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken); + } - /// - public async ValueTask DisposeAsync() - { - Client.Dispose(); - await _app.StopAsync(); - await _app.DisposeAsync(); + /// + public async ValueTask DisposeAsync() + { + Client.Dispose(); + await _app.StopAsync(); + await _app.DisposeAsync(); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/ScriptedHttpMessageHandler.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/ScriptedHttpMessageHandler.cs index 2d631e8a..300f94fe 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/ScriptedHttpMessageHandler.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/ScriptedHttpMessageHandler.cs @@ -1,42 +1,41 @@ using System.Net; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// A handler that answers one scripted status for each attempt, so a retry test reaches no network. -/// -/// -/// The last status of the script answers every attempt after it, so a script of one status answers -/// forever. counts what the pipeline above this handler actually sent. -/// -internal sealed class ScriptedHttpMessageHandler : HttpMessageHandler +namespace AgentCore.AspNetCore.Tests.Fakes { - private readonly HttpStatusCode[] _script; + /// + /// A handler that answers one scripted status for each attempt, so a retry test reaches no network. + /// + /// + /// The last status of the script answers every attempt after it, so a script of one status answers + /// forever. counts what the pipeline above this handler actually sent. + /// + internal sealed class ScriptedHttpMessageHandler(params HttpStatusCode[] script) : HttpMessageHandler + { + private readonly HttpStatusCode[] _script = script; - public ScriptedHttpMessageHandler(params HttpStatusCode[] script) => _script = script; + /// Gets the number of requests this handler saw. + public int Attempts { get; private set; } - /// Gets the number of requests this handler saw. - public int Attempts { get; private set; } + /// Gets or sets the Retry-After header every answer carries, in seconds. + public int? RetryAfterSeconds { get; set; } - /// Gets or sets the Retry-After header every answer carries, in seconds. - public int? RetryAfterSeconds { get; set; } + protected override Task SendAsync( + HttpRequestMessage request, + CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); - protected override Task SendAsync( - HttpRequestMessage request, - CancellationToken cancellationToken) - { - cancellationToken.ThrowIfCancellationRequested(); + HttpStatusCode status = _script[Math.Min(Attempts, _script.Length - 1)]; + Attempts++; - var status = _script[Math.Min(Attempts, _script.Length - 1)]; - Attempts++; + HttpResponseMessage response = new(status); + if (RetryAfterSeconds is { } seconds) + { + response.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue( + TimeSpan.FromSeconds(seconds)); + } - HttpResponseMessage response = new(status); - if (RetryAfterSeconds is { } seconds) - { - response.Headers.RetryAfter = new System.Net.Http.Headers.RetryConditionHeaderValue( - TimeSpan.FromSeconds(seconds)); + return Task.FromResult(response); } - - return Task.FromResult(response); } } diff --git a/tests/AgentCore.AspNetCore.Tests/Fakes/TelnyxRelayHost.cs b/tests/AgentCore.AspNetCore.Tests/Fakes/TelnyxRelayHost.cs index 0cb0037f..34655d3b 100644 --- a/tests/AgentCore.AspNetCore.Tests/Fakes/TelnyxRelayHost.cs +++ b/tests/AgentCore.AspNetCore.Tests/Fakes/TelnyxRelayHost.cs @@ -15,302 +15,323 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Fakes; - -/// -/// One real host with the relay route mapped, over a fake model. -/// -/// -/// Kestrel takes port zero and reports the port it got, so many tests run at once. The socket is -/// real on purpose: framing, fragmentation, and the close handshake are wire behaviours, and the -/// in-memory socket of TestServer never frames anything. No test here reaches a network, and no -/// test needs a Telnyx account. That is T59. -/// -internal sealed class TelnyxRelayHost : IAsyncDisposable +namespace AgentCore.AspNetCore.Tests.Fakes { - /// The vendor-neutral conversation route, with the document's one entry filled in. - public const string MainConversation = "/v1/main/call"; - - /// The relay's own route, with the document's one entry filled in. - public const string MainRelay = "/v1/main/telnyx/relay"; - - private readonly WebApplication _app; - private readonly Uri _socketAddress; - private readonly HttpClient _client; - private readonly ErrorCapturingLoggerProvider _errors; - - private TelnyxRelayHost(WebApplication app, Uri socketAddress, HttpClient client, ErrorCapturingLoggerProvider errors) - { - _app = app; - _socketAddress = socketAddress; - _client = client; - _errors = errors; - } - - /// Gets the sessions the host resolved, so a test reads the live ones. - public IConversationSessions Sessions => _app.Services.GetRequiredService().ForSessions("main"); - - /// Gets the ws:// address of the relay route. - /// - /// covers every test that wants the vendor side driven for it. A - /// test that needs to control exactly when bytes are read off the wire — proving something - /// about backpressure, for one, since 's own pump always drains - /// the socket as fast as it can — opens its own - /// against this address instead. - /// - public Uri Address => _socketAddress; - - /// Gets the last exception any part of the host logged at error level, or null. + /// + /// One real host with the relay route mapped, over a fake model. + /// /// - /// A host that forgot app.UseWebSockets() answers every relay request with an unhandled - /// exception, and there is no field on the endpoint itself that carries it — only the log line - /// ASP.NET Core's own hosting layer writes when a request delegate throws. This reads that line, - /// captured by , which this host always installs - /// regardless of what a test's own logging callback adds. + /// Kestrel takes port zero and reports the port it got, so many tests run at once. The socket is + /// real on purpose: framing, fragmentation, and the close handshake are wire behaviours, and the + /// in-memory socket of TestServer never frames anything. No test here reaches a network, and no + /// test needs a Telnyx account. That is T59. /// - public string? LastError => _errors.LastMessage; - - /// Starts one host over one document, with the WebSocket middleware in place. - /// The document, as YAML. - /// The model behind every agent. - /// Anything else the test binds on the options. - /// - /// Anything a test adds to the logging pipeline, for example a provider that observes a line - /// the connection writes. The default clears every provider, so nothing is captured unless a - /// test asks for it here. - /// - /// Anything a test binds on the relay endpoint's own options. - /// The started host. - public static Task StartAsync( - string yaml, - IChatClient reply, - Action? configure = null, - Action? logging = null, - Action? relay = null) - => StartCoreAsync(yaml, reply, configure, logging, relay, useWebSockets: true, useConversationSeam: false); - - /// Starts one host that maps its route through app.MapCall() rather than the vendor extension. - /// The document, as YAML. It must name providers.conversation and providers.speech. - /// The model behind every agent. - /// - /// Anything else the test binds on the options. A test using this overload conversations - /// options.UseConversation(new TelnyxRelayConversationAdapter()) here, because nothing else registers the - /// transport the seam is meant to pick. - /// - /// Anything a test adds to the logging pipeline. - /// The started host, answering on . - /// - /// maps the relay through the internal MapTelnyxRelay and so - /// bypasses the seam entirely, which is right for the several dozen frame-level tests that use - /// it and wrong for proving that the shipped vendor is reachable from the vendor-neutral route. - /// This overload is the one that joins the two. - /// - public static Task StartThroughConversationSeamAsync( - string yaml, - IChatClient reply, - Action? configure = null, - Action? logging = null) - => StartCoreAsync(yaml, reply, configure, logging, relay: null, useWebSockets: true, useConversationSeam: true); - - /// Starts one host the same way does, but never calls app.UseWebSockets(). - /// The document, as YAML. - /// The model behind every agent. - /// Anything else the test binds on the options. - /// Anything a test adds to the logging pipeline. - /// The started host. - /// - /// The middleware is the host's own job, not the library's — MapTelnyxRelay only maps the - /// route. This is how a test proves what happens when a host forgets it. - /// - public static Task StartWithoutWebSocketsAsync( - string yaml, - IChatClient reply, - Action? configure = null, - Action? logging = null) - => StartCoreAsync(yaml, reply, configure, logging, relay: null, useWebSockets: false, useConversationSeam: false); - - private static async Task StartCoreAsync( - string yaml, - IChatClient reply, - Action? configure, - Action? logging, - Action? relay, - bool useWebSockets, - bool useConversationSeam) + internal sealed class TelnyxRelayHost : IAsyncDisposable { - var builder = WebApplication.CreateSlimBuilder(); - builder.WebHost.UseUrls("http://127.0.0.1:0"); - builder.Logging.ClearProviders(); - logging?.Invoke(builder.Logging); + /// The vendor-neutral conversation route, with the document's one entry filled in. + public const string MainConversation = "/v1/main/call"; - ErrorCapturingLoggerProvider errors = new(); - builder.Logging.AddProvider(errors); + /// The relay's own route, with the document's one entry filled in. + public const string MainRelay = "/v1/main/telnyx/relay"; - builder.Services.AddAgentCore(options => - { - options.Configuration = ConfigurationLoader.LoadYaml(yaml); - options.UseChatClients(_ => new RoutingChatClientFactory(reply)); - configure?.Invoke(options); - }); + private readonly WebApplication _app; + private readonly HttpClient _client; + private readonly ErrorCapturingLoggerProvider _errors; - var app = builder.Build(); + private TelnyxRelayHost(WebApplication app, Uri socketAddress, HttpClient client, ErrorCapturingLoggerProvider errors) + { + _app = app; + Address = socketAddress; + _client = client; + _errors = errors; + } - if (useWebSockets) + /// Gets the sessions the host resolved, so a test reads the live ones. + public IConversationSessions Sessions => _app.Services.GetRequiredService().ForSessions("main"); + + /// Gets the ws:// address of the relay route. + /// + /// covers every test that wants the vendor side driven for it. A + /// test that needs to control exactly when bytes are read off the wire — proving something + /// about backpressure, for one, since 's own pump always drains + /// the socket as fast as it can — opens its own + /// against this address instead. + /// + public Uri Address { get; } + + /// Gets the last exception any part of the host logged at error level, or null. + /// + /// A host that forgot app.UseWebSockets() answers every relay request with an unhandled + /// exception, and there is no field on the endpoint itself that carries it — only the log line + /// ASP.NET Core's own hosting layer writes when a request delegate throws. This reads that line, + /// captured by , which this host always installs + /// regardless of what a test's own logging callback adds. + /// + public string? LastError => _errors.LastMessage; + + /// Starts one host over one document, with the WebSocket middleware in place. + /// The document, as YAML. + /// The model behind every agent. + /// Anything else the test binds on the options. + /// + /// Anything a test adds to the logging pipeline, for example a provider that observes a line + /// the connection writes. The default clears every provider, so nothing is captured unless a + /// test asks for it here. + /// + /// Anything a test binds on the relay endpoint's own options. + /// The started host. + public static Task StartAsync( + string yaml, + IChatClient reply, + Action? configure = null, + Action? logging = null, + Action? relay = null) { - // The library maps an endpoint. The middleware is the host's job, and a host that - // forgets it gets an unhandled InvalidOperationException on every call instead — see - // AHostThatForgotUseWebSockets_FailsWithAMessageThatNamesTheFix, which proves the - // failing path in its own fact. - app.UseWebSockets(new WebSocketOptions - { - KeepAliveInterval = TimeSpan.FromSeconds(5), - KeepAliveTimeout = TimeSpan.FromSeconds(5), - }); + return StartCoreAsync(yaml, reply, configure, logging, relay, useWebSockets: true, useConversationSeam: false); } - string route; - if (useConversationSeam) + /// Starts one host that maps its route through app.MapCall() rather than the vendor extension. + /// The document, as YAML. It must name providers.conversation and providers.speech. + /// The model behind every agent. + /// + /// Anything else the test binds on the options. A test using this overload conversations + /// options.UseConversation(new TelnyxRelayConversationAdapter()) here, because nothing else registers the + /// transport the seam is meant to pick. + /// + /// Anything a test adds to the logging pipeline. + /// The started host, answering on . + /// + /// maps the relay through the internal MapTelnyxRelay and so + /// bypasses the seam entirely, which is right for the several dozen frame-level tests that use + /// it and wrong for proving that the shipped vendor is reachable from the vendor-neutral route. + /// This overload is the one that joins the two. + /// + public static Task StartThroughConversationSeamAsync( + string yaml, + IChatClient reply, + Action? configure = null, + Action? logging = null) { - // The vendor-neutral seam picks the transport out of providers.conversation and the adapter the - // test registered. Nothing here names a route or a vendor. - route = MainConversation; - app.MapCall(); + return StartCoreAsync(yaml, reply, configure, logging, relay: null, useWebSockets: true, useConversationSeam: true); } - else + + /// Starts one host the same way does, but never calls app.UseWebSockets(). + /// The document, as YAML. + /// The model behind every agent. + /// Anything else the test binds on the options. + /// Anything a test adds to the logging pipeline. + /// The started host. + /// + /// The middleware is the host's own job, not the library's — MapTelnyxRelay only maps the + /// route. This is how a test proves what happens when a host forgets it. + /// + public static Task StartWithoutWebSocketsAsync( + string yaml, + IChatClient reply, + Action? configure = null, + Action? logging = null) { - route = MainRelay; - var relayOptions = new TelnyxRelayOptions(); - relay?.Invoke(relayOptions); - app.MapTelnyxRelay(TelnyxRelayEndpointRouteBuilderExtensions.DefaultPattern, relayOptions); + return StartCoreAsync(yaml, reply, configure, logging, relay: null, useWebSockets: false, useConversationSeam: false); } - await app.StartAsync(); + private static async Task StartCoreAsync( + string yaml, + IChatClient reply, + Action? configure, + Action? logging, + Action? relay, + bool useWebSockets, + bool useConversationSeam) + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + _ = builder.WebHost.UseUrls("http://127.0.0.1:0"); + _ = builder.Logging.ClearProviders(); + logging?.Invoke(builder.Logging); - var address = app.Services - .GetRequiredService() - .Features - .Get()! - .Addresses - .First(); + ErrorCapturingLoggerProvider errors = new(); + _ = builder.Logging.AddProvider(errors); - var httpAddress = new Uri(address, UriKind.Absolute); - var socket = new Uri( - address.Replace("http://", "ws://", StringComparison.Ordinal) + route); + _ = builder.Services.AddAgentCore(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(yaml); + _ = options.UseChatClients(_ => new RoutingChatClientFactory(reply)); + configure?.Invoke(options); + }); - HttpClient client = new() { BaseAddress = httpAddress }; + WebApplication app = builder.Build(); - return new TelnyxRelayHost(app, socket, client, errors); - } + if (useWebSockets) + { + // The library maps an endpoint. The middleware is the host's job, and a host that + // forgets it gets an unhandled InvalidOperationException on every call instead — see + // AHostThatForgotUseWebSockets_FailsWithAMessageThatNamesTheFix, which proves the + // failing path in its own fact. + _ = app.UseWebSockets(new WebSocketOptions + { + KeepAliveInterval = TimeSpan.FromSeconds(5), + KeepAliveTimeout = TimeSpan.FromSeconds(5), + }); + } - /// Opens one relay socket to this host. - /// The connected fake relay. - public Task ConnectAsync() => FakeRelayClient.ConnectAsync(_socketAddress); - - /// Sends a plain HTTP GET to one route of this host. - /// The route, for example the relay endpoint's own pattern. - /// The answer. - public Task GetAsync(string pattern) - => _client.GetAsync(pattern, TestContext.Current.CancellationToken); - - /// Reads the session of one conversation, or null when the store dropped it. - /// The conversation id, which is the conversationSessionId of the setup frame. - /// The session, or null. - public async Task FindSessionAsync(string conversationId) - => await Sessions.TryGetAsync(conversationId, TestContext.Current.CancellationToken); - - /// Waits until the store no longer holds one conversation. - /// The conversation id. - /// A task that completes when the session is gone. - /// The session was still there after two seconds. - public async Task WaitForConversationEndAsync(string conversationId) - { - for (var attempt = 0; attempt < 200; attempt++) - { - if (await FindSessionAsync(conversationId) is null) + string route; + if (useConversationSeam) { - return; + // The vendor-neutral seam picks the transport out of providers.conversation and the adapter the + // test registered. Nothing here names a route or a vendor. + route = MainConversation; + _ = app.MapCall(); } + else + { + route = MainRelay; + TelnyxRelayOptions relayOptions = new(); + relay?.Invoke(relayOptions); + _ = app.MapTelnyxRelay(TelnyxRelayEndpointRouteBuilderExtensions.DefaultPattern, relayOptions); + } + + await app.StartAsync(); + + string address = app.Services + .GetRequiredService() + .Features + .Get()! + .Addresses + .First(); + + Uri httpAddress = new(address, UriKind.Absolute); + Uri socket = new( + address.Replace("http://", "ws://", StringComparison.Ordinal) + route); + + HttpClient client = new() { BaseAddress = httpAddress }; - await Task.Delay(10, TestContext.Current.CancellationToken); + return new TelnyxRelayHost(app, socket, client, errors); } - throw new TimeoutException($"the session of conversation '{conversationId}' outlived its socket."); - } + /// Opens one relay socket to this host. + /// The connected fake relay. + public Task ConnectAsync() + { + return FakeRelayClient.ConnectAsync(Address); + } - /// Waits until the store holds one conversation. - /// The conversation id. - /// A task that completes once the session appears. - /// - /// A setup frame's SendAsync completing on the client only means the bytes left the - /// client; it proves nothing about whether the server has read and dispatched them yet. A test - /// that then tears the socket down immediately would otherwise race the server's own session - /// creation, and a pass would not prove the removal it meant to prove. - /// - /// The session never appeared within two seconds. - public async Task WaitForSessionAsync(string conversationId) - { - for (var attempt = 0; attempt < 200; attempt++) + /// Sends a plain HTTP GET to one route of this host. + /// The route, for example the relay endpoint's own pattern. + /// The answer. + public Task GetAsync(string pattern) + { + return _client.GetAsync(pattern, TestContext.Current.CancellationToken); + } + + /// Reads the session of one conversation, or null when the store dropped it. + /// The conversation id, which is the conversationSessionId of the setup frame. + /// The session, or null. + public async Task FindSessionAsync(string conversationId) { - if (await FindSessionAsync(conversationId) is not null) + return await Sessions.TryGetAsync(conversationId, TestContext.Current.CancellationToken); + } + + /// Waits until the store no longer holds one conversation. + /// The conversation id. + /// A task that completes when the session is gone. + /// The session was still there after two seconds. + public async Task WaitForConversationEndAsync(string conversationId) + { + for (int attempt = 0; attempt < 200; attempt++) { - return; + if (await FindSessionAsync(conversationId) is null) + { + return; + } + + await Task.Delay(10, TestContext.Current.CancellationToken); } - await Task.Delay(10, TestContext.Current.CancellationToken); + throw new TimeoutException($"the session of conversation '{conversationId}' outlived its socket."); } - throw new TimeoutException($"the session of conversation '{conversationId}' never appeared."); - } + /// Waits until the store holds one conversation. + /// The conversation id. + /// A task that completes once the session appears. + /// + /// A setup frame's SendAsync completing on the client only means the bytes left the + /// client; it proves nothing about whether the server has read and dispatched them yet. A test + /// that then tears the socket down immediately would otherwise race the server's own session + /// creation, and a pass would not prove the removal it meant to prove. + /// + /// The session never appeared within two seconds. + public async Task WaitForSessionAsync(string conversationId) + { + for (int attempt = 0; attempt < 200; attempt++) + { + if (await FindSessionAsync(conversationId) is not null) + { + return; + } - /// Stops the host and releases the socket. - public async ValueTask DisposeAsync() - { - _client.Dispose(); - await _app.StopAsync(); - await _app.DisposeAsync(); + await Task.Delay(10, TestContext.Current.CancellationToken); + } + + throw new TimeoutException($"the session of conversation '{conversationId}' never appeared."); + } + + /// Stops the host and releases the socket. + public async ValueTask DisposeAsync() + { + _client.Dispose(); + await _app.StopAsync(); + await _app.DisposeAsync(); + } } -} -/// Captures the message of the last exception any category logged at error level or above. -/// -/// ASP.NET Core's own hosting layer logs an unhandled exception from a request delegate rather than -/// letting a test observe it any other way, so this is the only handle -/// has on it. Every category is captured, not just the relay connection's own logger, because the -/// missing-middleware fault this exists for is thrown and logged by the framework, not by -/// AgentCore.TelnyxRelay. -/// -internal sealed class ErrorCapturingLoggerProvider : ILoggerProvider -{ - private volatile string? _lastMessage; + /// Captures the message of the last exception any category logged at error level or above. + /// + /// ASP.NET Core's own hosting layer logs an unhandled exception from a request delegate rather than + /// letting a test observe it any other way, so this is the only handle + /// has on it. Every category is captured, not just the relay connection's own logger, because the + /// missing-middleware fault this exists for is thrown and logged by the framework, not by + /// AgentCore.TelnyxRelay. + /// + internal sealed class ErrorCapturingLoggerProvider : ILoggerProvider + { + private volatile string? _lastMessage; - /// Gets the message of the last exception captured, or null when none was. - public string? LastMessage => _lastMessage; + /// Gets the message of the last exception captured, or null when none was. + public string? LastMessage => _lastMessage; - public ILogger CreateLogger(string categoryName) => new Logger(this); + public ILogger CreateLogger(string categoryName) + { + return new Logger(this); + } - public void Dispose() - { - // Nothing to release. - } + public void Dispose() + { + // Nothing to release. + } - private sealed class Logger(ErrorCapturingLoggerProvider owner) : ILogger - { - public IDisposable? BeginScope(TState state) - where TState : notnull - => null; - - public bool IsEnabled(LogLevel logLevel) => logLevel >= LogLevel.Error; - - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + private sealed class Logger(ErrorCapturingLoggerProvider owner) : ILogger { - if (exception is not null) + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } + + public bool IsEnabled(LogLevel logLevel) + { + return logLevel >= LogLevel.Error; + } + + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) { - owner._lastMessage = exception.Message; + if (exception is not null) + { + owner._lastMessage = exception.Message; + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Llm/OpenAI/OpenAiChatClientAdapterTests.cs b/tests/AgentCore.AspNetCore.Tests/Llm/OpenAI/OpenAiChatClientAdapterTests.cs index 09674a4c..5d447308 100644 --- a/tests/AgentCore.AspNetCore.Tests/Llm/OpenAI/OpenAiChatClientAdapterTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Llm/OpenAI/OpenAiChatClientAdapterTests.cs @@ -4,25 +4,25 @@ using AgentCore.Application.Llm; using AgentCore.Application.Ports; using AgentCore.Application.Secrets; -using AgentCore.AspNetCore.Tests.Fakes; using AgentCore.Infrastructure.Llm.OpenAI; using Xunit; +using Microsoft.Extensions.AI; -namespace AgentCore.AspNetCore.Tests.Llm.OpenAI; - -/// -/// The OpenAI adapter. It owns the vendor only: the SDK client, the key, the model name. -/// -/// -/// Building a client opens no socket, so every test here runs offline. The key is a fake string, and -/// no test sends a request. -/// -public sealed class OpenAiChatClientAdapterTests +namespace AgentCore.AspNetCore.Tests.Llm.OpenAI { - private const string FakeKey = "sk-test-not-a-real-key"; + /// + /// The OpenAI adapter. It owns the vendor only: the SDK client, the key, the model name. + /// + /// + /// Building a client opens no socket, so every test here runs offline. The key is a fake string, and + /// no test sends a request. + /// + public sealed class OpenAiChatClientAdapterTests + { + private const string FakeKey = "sk-test-not-a-real-key"; - private const string TwoModelsYaml = - """ + private const string TwoModelsYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -40,98 +40,105 @@ public sealed class OpenAiChatClientAdapterTests agent: only """; - [Fact] - public void TheAdapter_ServesTheOpenAiKind() - { - Assert.Equal("openai", new OpenAiChatClientAdapter().Kind); - } - - [Fact] - public async Task TheApiKey_ComesFromTheResolverChain() - { - var entry = FirstEntry(); - MapSecretResolver resolver = new(); - resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, FakeKey); - - var client = await new OpenAiChatClientAdapter().CreateClientAsync( - entry, - resolver, - TestContext.Current.CancellationToken); + [Fact] + public void TheAdapter_ServesTheOpenAiKind() + { + Assert.Equal("openai", new OpenAiChatClientAdapter().Kind); + } - Assert.NotNull(client); - } + [Fact] + public async Task TheApiKey_ComesFromTheResolverChain() + { + LlmProviderConfiguration entry = FirstEntry(); + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, FakeKey); - [Fact] - public async Task TheApiKey_ResolvesOnceHoweverManyEntriesTheDocumentDeclares() - { - CountingSecretResolver resolver = new(); - OpenAiChatClientAdapter adapter = new(); - var llm = Document().Providers!.Llm; + IChatClient client = await new OpenAiChatClientAdapter().CreateClientAsync( + entry, + resolver, + TestContext.Current.CancellationToken); - await adapter.CreateClientAsync(llm[0], resolver, TestContext.Current.CancellationToken); - await adapter.CreateClientAsync(llm[1], resolver, TestContext.Current.CancellationToken); + Assert.NotNull(client); + } - // One vendor client for the whole document, so one key read and one connection pool. - Assert.Equal(1, resolver.Resolutions); - } + [Fact] + public async Task TheApiKey_ResolvesOnceHoweverManyEntriesTheDocumentDeclares() + { + CountingSecretResolver resolver = new(); + OpenAiChatClientAdapter adapter = new(); + IReadOnlyList llm = Document().Providers!.Llm; - [Fact] - public async Task NoApiKeyAnywhere_FailsAndSaysWhereToPutOne() - { - var saved = Environment.GetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName); - Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, null); + _ = await adapter.CreateClientAsync(llm[0], resolver, TestContext.Current.CancellationToken); + _ = await adapter.CreateClientAsync(llm[1], resolver, TestContext.Current.CancellationToken); - try - { - var failure = await Assert.ThrowsAsync( - async () => await new OpenAiChatClientAdapter().CreateClientAsync( - FirstEntry(), - new MapSecretResolver(), - TestContext.Current.CancellationToken)); - - Assert.Contains(OpenAiChatClientAdapter.ApiKeySecretName, failure.Message, StringComparison.Ordinal); - Assert.Contains(OpenAiChatClientAdapter.ApiKeyVariableName, failure.Message, StringComparison.Ordinal); + // One vendor client for the whole document, so one key read and one connection pool. + Assert.Equal(1, resolver.Resolutions); } - finally + + [Fact] + public async Task NoApiKeyAnywhere_FailsAndSaysWhereToPutOne() { - Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, saved); + string? saved = Environment.GetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName); + Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, null); + + try + { + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await new OpenAiChatClientAdapter().CreateClientAsync( + FirstEntry(), + new MapSecretResolver(), + TestContext.Current.CancellationToken)); + + Assert.Contains(OpenAiChatClientAdapter.ApiKeySecretName, failure.Message, StringComparison.Ordinal); + Assert.Contains(OpenAiChatClientAdapter.ApiKeyVariableName, failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, saved); + } } - } - [Fact] - public async Task TheComposite_ServesAnOpenAiDocumentThroughThisAdapter() - { - MapSecretResolver resolver = new(); - resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, FakeKey); - - using var factory = await CompositeChatClientFactory.CreateAsync( - Document(), - resolver, - [new OpenAiChatClientAdapter()], - TestContext.Current.CancellationToken); + [Fact] + public async Task TheComposite_ServesAnOpenAiDocumentThroughThisAdapter() + { + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, FakeKey); - var reply = factory.GetChatClient(new ModelReference { Ref = "reply" }); + using CompositeChatClientFactory factory = await CompositeChatClientFactory.CreateAsync( + Document(), + resolver, + [new OpenAiChatClientAdapter()], + TestContext.Current.CancellationToken); - Assert.Same(reply, factory.GetChatClient(new ModelReference { Ref = "reply" })); - Assert.NotSame(reply, factory.GetChatClient(new ModelReference { Ref = "fill" })); - } + IChatClient reply = factory.GetChatClient(new ModelReference { Ref = "reply" }); - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private static AgentCoreConfiguration Document() => ConfigurationLoader.LoadYaml(TwoModelsYaml); + Assert.Same(reply, factory.GetChatClient(new ModelReference { Ref = "reply" })); + Assert.NotSame(reply, factory.GetChatClient(new ModelReference { Ref = "fill" })); + } - private static LlmProviderConfiguration FirstEntry() => Document().Providers!.Llm[0]; + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private static AgentCoreConfiguration Document() + { + return ConfigurationLoader.LoadYaml(TwoModelsYaml); + } - /// A resolver that counts its reads, so a test proves the key resolves once. - private sealed class CountingSecretResolver : ISecretResolverPort - { - public int Resolutions { get; private set; } + private static LlmProviderConfiguration FirstEntry() + { + return Document().Providers!.Llm[0]; + } - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + /// A resolver that counts its reads, so a test proves the key resolves once. + private sealed class CountingSecretResolver : ISecretResolverPort { - Resolutions++; - return ValueTask.FromResult(FakeKey); + public int Resolutions { get; private set; } + + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + Resolutions++; + return ValueTask.FromResult(FakeKey); + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Sessions/ConversationSessionsRelayTests.cs b/tests/AgentCore.AspNetCore.Tests/Sessions/ConversationSessionsRelayTests.cs index c2e43b65..9f4f26dd 100644 --- a/tests/AgentCore.AspNetCore.Tests/Sessions/ConversationSessionsRelayTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Sessions/ConversationSessionsRelayTests.cs @@ -1,5 +1,6 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; @@ -8,79 +9,83 @@ using AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; using AgentCore.TestSupport; using Microsoft.Extensions.AI; -using Microsoft.Extensions.DependencyInjection; using Xunit; -namespace AgentCore.AspNetCore.Tests.Sessions; - -/// -/// What the relay socket asks of over the life of one conversation. -/// -/// -/// The unit tests of the store itself live in AgentCore.Application.Tests beside the store. This -/// file holds only what needs a real socket to prove. -/// -public sealed class ConversationSessionsRelayTests +namespace AgentCore.AspNetCore.Tests.Sessions { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact(Timeout = 30_000)] - public async Task ATurnTellsTheStoreItsConversationIsStillBeingHad() + /// + /// What the relay socket asks of over the life of one conversation. + /// + /// + /// The unit tests of the store itself live in AgentCore.Application.Tests beside the store. This + /// file holds only what needs a real socket to prove. + /// + public sealed class ConversationSessionsRelayTests { - // The relay opens its session once and holds it for the whole conversation, so nothing else reads - // it back. A read is the one sign a store gets that a conversation is still live, so without one - // the idle sweep drops a long call out from under the turn about to run. - using FragmentingChatClient reply = new("your order ships Friday"); - var factory = Factory(TelnyxRelayTurnTests.PolicyYaml, reply); - CountingConversationSessions sessions = new(factory); + private static CancellationToken Token => TestContext.Current.CancellationToken; - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - configure: options => options.UseConversationSessions((_, _) => sessions)); + [Fact(Timeout = 30_000)] + public async Task ATurnTellsTheStoreItsConversationIsStillBeingHad() + { + // The relay opens its session once and holds it for the whole conversation, so nothing else reads + // it back. A read is the one sign a store gets that a conversation is still live, so without one + // the idle sweep drops a long call out from under the turn about to run. + using FragmentingChatClient reply = new("your order ships Friday"); + ConversationSessionFactory factory = Factory(TelnyxRelayTurnTests.PolicyYaml, reply); + CountingConversationSessions sessions = new(factory); - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-live")); - harness.Socket.Queue(RelayFrames.Prompt("when does my order ship?", last: true)); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + configure: options => options.UseConversationSessions((_, _) => sessions)); - for (var attempt = 0; attempt < 400 && sessions.Reads == 0; attempt++) - { - await Task.Delay(10, Token); + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-live")); + harness.Socket.Queue(RelayFrames.Prompt("when does my order ship?", last: true)); + + for (int attempt = 0; attempt < 400 && sessions.Reads == 0; attempt++) + { + await Task.Delay(10, Token); + } + + Assert.True(sessions.Reads > 0, "the turn never told the store its conversation is still being had."); } - Assert.True(sessions.Reads > 0, "the turn never told the store its conversation is still being had."); - } + private static ConversationSessionFactory Factory(string yaml, IChatClient reply) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(chatClients))["main"]; - private static ConversationSessionFactory Factory(string yaml, IChatClient reply) - { - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(reply); - var compiled = ConfigurationCompiler.CompileAll(document, new AgentCompilationContext(chatClients))["main"]; + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients)); + } - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients)); - } + private sealed class CountingConversationSessions(IConversationSessionFactory factory) : IConversationSessions + { + private readonly InMemoryConversationSessions _inner = + new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); - private sealed class CountingConversationSessions(IConversationSessionFactory factory) : IConversationSessions - { - private readonly InMemoryConversationSessions _inner = - new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); + private int _reads; - private int _reads; + public int Reads => Volatile.Read(ref _reads); - public int Reads => Volatile.Read(ref _reads); + public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) + { + return _inner.OpenAsync(conversationId, cancellationToken); + } - public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) - => _inner.OpenAsync(conversationId, cancellationToken); + public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) + { + _ = Interlocked.Increment(ref _reads); + return _inner.TryGetAsync(conversationId, cancellationToken); + } - public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) - { - Interlocked.Increment(ref _reads); - return _inner.TryGetAsync(conversationId, cancellationToken); + public ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) + { + return _inner.CloseAsync(conversationId, cancellationToken); + } } - - public ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) - => _inner.CloseAsync(conversationId, cancellationToken); } } diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayBargeInTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayBargeInTests.cs index b3093d85..e9712972 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayBargeInTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayBargeInTests.cs @@ -1,4 +1,3 @@ -using AgentCore.TestSupport; using System.Net.WebSockets; using System.Text; using System.Text.Json.Nodes; @@ -8,787 +7,791 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// What happens when the caller speaks over the reply. -/// -/// -/// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, -/// no network conversation, and no API key anywhere in this file. -/// -public sealed class TelnyxRelayBargeInTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - [Fact(Timeout = 30_000)] - public async Task AnInterruptDuringAReply_RecordsWhatTheCallerHeard() + /// + /// What happens when the caller speaks over the reply. + /// + /// + /// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, + /// no network conversation, and no API key anywhere in this file. + /// + public sealed class TelnyxRelayBargeInTests { - // The vendor measured both values, so nothing here is estimated. D28 and item 6a. - // - // BlockingChatClient's gate ignores cancellation, so a defect that left the turn - // machinery stuck would hang this test rather than fail it red. The ten-second deadline - // below is this test's own backstop, and reply.Release() sits in a finally so a failed - // assertion above still opens the gate instead of leaving the server's turn blocked for - // the rest of the host's shutdown timeout. - using BlockingChatClient reply = new("one two three four five"); - EventObservedLoggerProvider capture = new("InterruptReceived"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-barge")); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + [Fact(Timeout = 30_000)] + public async Task AnInterruptDuringAReply_RecordsWhatTheCallerHeard() + { + // The vendor measured both values, so nothing here is estimated. D28 and item 6a. + // + // BlockingChatClient's gate ignores cancellation, so a defect that left the turn + // machinery stuck would hang this test rather than fail it red. The ten-second deadline + // below is this test's own backstop, and reply.Release() sits in a finally so a failed + // assertion above still opens the gate instead of leaving the server's turn blocked for + // the rest of the host's shutdown timeout. + using BlockingChatClient reply = new("one two three four five"); + EventObservedLoggerProvider capture = new("InterruptReceived"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); try { - await relay.ReadFrameAsync().WaitAsync(bounded.Token); // the reply started - await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); - - await relay.SendAsync(RelayFrames.Interrupt("one two", durationMs: 640)); - - // SendAsync completing only means the bytes left this client, the same way - // TelnyxRelayHost.WaitForSessionAsync's own remark explains for a setup frame. The - // connection must actually raise the turn id and conversation ConversationSession.Interrupt before - // the gate below opens, or a fragment already queued behind the gate could still - // beat the guard onto the wire. - await capture.Observed.WaitAsync(bounded.Token); + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-barge")); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + try + { + _ = await relay.ReadFrameAsync().WaitAsync(bounded.Token); // the reply started + await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Interrupt("one two", durationMs: 640)); + + // SendAsync completing only means the bytes left this client, the same way + // TelnyxRelayHost.WaitForSessionAsync's own remark explains for a setup frame. The + // connection must actually raise the turn id and conversation ConversationSession.Interrupt before + // the gate below opens, or a fragment already queued behind the gate could still + // beat the guard onto the wire. + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the barge-in within ten seconds."); + } } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + finally { - Assert.Fail("the connection never reported the barge-in within ten seconds."); + reply.Release(); } - } - finally - { - reply.Release(); - } - var session = await host.FindSessionAsync("conversation-barge"); - Assert.NotNull(session); + ConversationSession? session = await host.FindSessionAsync("conversation-barge"); + Assert.NotNull(session); - var turn = await WaitForTurnAsync(session!); + TurnResult turn = await WaitForTurnAsync(session!); - Assert.Equal("one two", turn.ReplyText); - Assert.Equal(TimeSpan.FromMilliseconds(640), turn.InterruptedAfter); - } + Assert.Equal("one two", turn.ReplyText); + Assert.Equal(TimeSpan.FromMilliseconds(640), turn.InterruptedAfter); + } - [Fact(Timeout = 30_000)] - public async Task AfterAnInterrupt_NoFurtherTextFrameReachesTheRelay() - { - // Cancelling stops the producer. It does not stop a consumer that is mid-write, and a - // token that lands after the interrupt makes the vendor speak audio nobody asked for. - // pipecat names this exact straggler in its eval harness. - // - // This proves RunTurnAsync's own guard: interrupting before the gate on the fake model is - // ever released means nothing has reached _outbound yet when HandleInterrupt runs, so every - // later fragment must be stopped by the per-update check inside RunTurnAsync's own loop. - // AFrameAlreadyInsideTheWriteLoop_IsNotFollowedByAnotherAfterAnInterrupt below covers the - // case this test's timing cannot reach: a fragment that already reached the channel before - // the interrupt did, sitting there while the write loop is genuinely busy elsewhere. - using BlockingChatClient reply = new("one two three four five six seven eight"); - EventObservedLoggerProvider capture = new("InterruptReceived"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try + [Fact(Timeout = 30_000)] + public async Task AfterAnInterrupt_NoFurtherTextFrameReachesTheRelay() { - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-race")); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + // Cancelling stops the producer. It does not stop a consumer that is mid-write, and a + // token that lands after the interrupt makes the vendor speak audio nobody asked for. + // pipecat names this exact straggler in its eval harness. + // + // This proves RunTurnAsync's own guard: interrupting before the gate on the fake model is + // ever released means nothing has reached _outbound yet when HandleInterrupt runs, so every + // later fragment must be stopped by the per-update check inside RunTurnAsync's own loop. + // AFrameAlreadyInsideTheWriteLoop_IsNotFollowedByAnotherAfterAnInterrupt below covers the + // case this test's timing cannot reach: a fragment that already reached the channel before + // the interrupt did, sitting there while the write loop is genuinely busy elsewhere. + using BlockingChatClient reply = new("one two three four five six seven eight"); + EventObservedLoggerProvider capture = new("InterruptReceived"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); try { - await relay.ReadFrameAsync().WaitAsync(bounded.Token); - await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-race")); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + try + { + _ = await relay.ReadFrameAsync().WaitAsync(bounded.Token); + await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Interrupt("one", durationMs: 300)); + + // The same reason as the test above: the gate must not open until the connection + // has actually raised the turn id, or this test would be timing the delivery of + // one WebSocket frame rather than the guard this task exists to prove. + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the barge-in within ten seconds."); + } + } + finally + { + // Release every remaining update. None of them may reach the socket. This sits in a + // finally so a failed assertion above still lets the fake client's task finish rather + // than leaving it, and the host's shutdown, blocked on a gate nobody will ever open. + reply.Release(); + } - await relay.SendAsync(RelayFrames.Interrupt("one", durationMs: 300)); + List later = await relay.ReadFramesForAsync(TimeSpan.FromMilliseconds(400)); + Assert.DoesNotContain(later, frame => frame["type"]!.GetValue() == "text"); + } + + [Fact(Timeout = 30_000)] + public async Task AnItemAlreadyQueuedBehindAStuckSend_IsRemovedByTheUnconditionalDrain() + { + // This does not exercise either id-based guard — not RunTurnAsync's own per-update check, + // and not the write loop's >= comparison in front of its one SendAsync call. Both stay + // disabled and this still passes, because HandleInterrupt's own drain — the unconditional + // `while (_outbound.Reader.TryRead(out _)) { }` that runs before either guard is ever + // reached — already removes the item this test cares about while it is still sitting in + // the channel, before either comparison gets a chance to matter. What this proves is that + // the drain reaches an item already queued, not one still in flight through a guard: a + // single, deliberately huge fragment is the whole reply, so nothing else competes for it. + // The write loop dequeues it almost immediately and calls SendAsync, and that call has no + // choice but to block on genuine TCP backpressure, because nothing reads this socket until + // this test says so. While it is stuck there, the turn's own closing token queues up right + // behind it — still sitting in _outbound, not yet dequeued, when the interrupt fires. The + // drain reaches it there and removes it. Only once this test finally reads does the huge + // fragment complete and arrive, already committed to the wire before the interrupt ever + // happened. Nothing may follow it: not the closing token the drain already removed, and + // not anything else, even though the write loop spent this whole test genuinely busy + // rather than idle when the interrupt landed. + // + // FakeRelayClient cannot prove this: its own pump reads the socket continuously in the + // background from the moment it connects, for every other test's benefit, which means + // nothing is ever actually stuck waiting on a reader through it — this test's first attempt + // used it, held a fixed delay, and failed intermittently exactly because of that pump + // draining the "stuck" frame in the background the whole time. A raw ClientWebSocket here + // is what makes the block real: the OS send buffer this connection can autotune to (4 MiB, + // confirmed via /proc/sys/net/ipv4/tcp_wmem on the machine this was verified on) cannot + // absorb an 8 MiB message with no reader draining it, so SendAsync has no choice but to + // wait. There is still no purely observable signal for "the write loop is now stuck inside + // that wait," so the fixed delay below stands in for one, sized to outlast a same-process + // production of one string and two channel writes many times over. + string hugeFragment = new('x', 8 * 1024 * 1024); + using FragmentingChatClient reply = new(hugeFragment); + EventObservedLoggerProvider capture = new("InterruptReceived"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + + using ClientWebSocket socket = new(); + await socket.ConnectAsync(host.Address, TestContext.Current.CancellationToken); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + await SendRawAsync(socket, RelayFrames.Setup(conversationSessionId: "conversation-held")); + await SendRawAsync(socket, RelayFrames.Prompt("hi", last: true)); + + await Task.Delay(300, TestContext.Current.CancellationToken); - // The same reason as the test above: the gate must not open until the connection - // has actually raised the turn id, or this test would be timing the delivery of - // one WebSocket frame rather than the guard this task exists to prove. + try + { + await SendRawAsync(socket, RelayFrames.Interrupt("nothing played", durationMs: 0)); await capture.Observed.WaitAsync(bounded.Token); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { Assert.Fail("the connection never reported the barge-in within ten seconds."); } - } - finally - { - // Release every remaining update. None of them may reach the socket. This sits in a - // finally so a failed assertion above still lets the fake client's task finish rather - // than leaving it, and the host's shutdown, blocked on a gate nobody will ever open. - reply.Release(); - } - var later = await relay.ReadFramesForAsync(TimeSpan.FromMilliseconds(400)); - Assert.DoesNotContain(later, frame => frame["type"]!.GetValue() == "text"); - } - - [Fact(Timeout = 30_000)] - public async Task AnItemAlreadyQueuedBehindAStuckSend_IsRemovedByTheUnconditionalDrain() - { - // This does not exercise either id-based guard — not RunTurnAsync's own per-update check, - // and not the write loop's >= comparison in front of its one SendAsync call. Both stay - // disabled and this still passes, because HandleInterrupt's own drain — the unconditional - // `while (_outbound.Reader.TryRead(out _)) { }` that runs before either guard is ever - // reached — already removes the item this test cares about while it is still sitting in - // the channel, before either comparison gets a chance to matter. What this proves is that - // the drain reaches an item already queued, not one still in flight through a guard: a - // single, deliberately huge fragment is the whole reply, so nothing else competes for it. - // The write loop dequeues it almost immediately and calls SendAsync, and that call has no - // choice but to block on genuine TCP backpressure, because nothing reads this socket until - // this test says so. While it is stuck there, the turn's own closing token queues up right - // behind it — still sitting in _outbound, not yet dequeued, when the interrupt fires. The - // drain reaches it there and removes it. Only once this test finally reads does the huge - // fragment complete and arrive, already committed to the wire before the interrupt ever - // happened. Nothing may follow it: not the closing token the drain already removed, and - // not anything else, even though the write loop spent this whole test genuinely busy - // rather than idle when the interrupt landed. - // - // FakeRelayClient cannot prove this: its own pump reads the socket continuously in the - // background from the moment it connects, for every other test's benefit, which means - // nothing is ever actually stuck waiting on a reader through it — this test's first attempt - // used it, held a fixed delay, and failed intermittently exactly because of that pump - // draining the "stuck" frame in the background the whole time. A raw ClientWebSocket here - // is what makes the block real: the OS send buffer this connection can autotune to (4 MiB, - // confirmed via /proc/sys/net/ipv4/tcp_wmem on the machine this was verified on) cannot - // absorb an 8 MiB message with no reader draining it, so SendAsync has no choice but to - // wait. There is still no purely observable signal for "the write loop is now stuck inside - // that wait," so the fixed delay below stands in for one, sized to outlast a same-process - // production of one string and two channel writes many times over. - var hugeFragment = new string('x', 8 * 1024 * 1024); - using FragmentingChatClient reply = new(hugeFragment); - EventObservedLoggerProvider capture = new("InterruptReceived"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - - using ClientWebSocket socket = new(); - await socket.ConnectAsync(host.Address, TestContext.Current.CancellationToken); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await SendRawAsync(socket, RelayFrames.Setup(conversationSessionId: "conversation-held")); - await SendRawAsync(socket, RelayFrames.Prompt("hi", last: true)); - - await Task.Delay(300, TestContext.Current.CancellationToken); - - try - { - await SendRawAsync(socket, RelayFrames.Interrupt("nothing played", durationMs: 0)); - await capture.Observed.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never reported the barge-in within ten seconds."); - } + try + { + string stuck = await ReceiveOneMessageAsync(socket, bounded.Token); + JsonNode node = JsonNode.Parse(stuck)!; + Assert.Equal("text", node["type"]!.GetValue()); + Assert.False(node["last"]!.GetValue()); + Assert.Equal(hugeFragment, node["token"]!.GetValue()); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail( + "the fragment already committed to the wire before the interrupt never arrived " + + "within ten seconds — it may not have been stuck in the write loop at all."); + } - try - { - var stuck = await ReceiveOneMessageAsync(socket, bounded.Token); - var node = JsonNode.Parse(stuck)!; - Assert.Equal("text", node["type"]!.GetValue()); - Assert.False(node["last"]!.GetValue()); - Assert.Equal(hugeFragment, node["token"]!.GetValue()); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail( - "the fragment already committed to the wire before the interrupt never arrived " - + "within ten seconds — it may not have been stuck in the write loop at all."); + // Cancelling this receive is the proof that nothing else arrives in the window: it aborts + // the socket, which is fine, because this is the last thing this test does with it. + using CancellationTokenSource window = new(TimeSpan.FromMilliseconds(400)); + try + { + string extra = await ReceiveOneMessageAsync(socket, window.Token); + Assert.Fail($"an unexpected frame reached the relay after the interrupt: {extra}"); + } + catch (OperationCanceledException) when (window.IsCancellationRequested) + { + // Silence is the pass: nothing followed the frame already in flight. + } } - // Cancelling this receive is the proof that nothing else arrives in the window: it aborts - // the socket, which is fine, because this is the last thing this test does with it. - using CancellationTokenSource window = new(TimeSpan.FromMilliseconds(400)); - try - { - var extra = await ReceiveOneMessageAsync(socket, window.Token); - Assert.Fail($"an unexpected frame reached the relay after the interrupt: {extra}"); - } - catch (OperationCanceledException) when (window.IsCancellationRequested) + /// Sends one frame as one WebSocket message, bypassing 's own pump. + private static Task SendRawAsync(ClientWebSocket socket, string json) { - // Silence is the pass: nothing followed the frame already in flight. + return socket.SendAsync( + Encoding.UTF8.GetBytes(json), + WebSocketMessageType.Text, + endOfMessage: true, + TestContext.Current.CancellationToken); } - } - /// Sends one frame as one WebSocket message, bypassing 's own pump. - private static Task SendRawAsync(ClientWebSocket socket, string json) - => socket.SendAsync( - Encoding.UTF8.GetBytes(json), - WebSocketMessageType.Text, - endOfMessage: true, - TestContext.Current.CancellationToken); - - /// Reads exactly one message off a raw socket, reassembling it from as many fragments as it takes. - private static async Task ReceiveOneMessageAsync(ClientWebSocket socket, CancellationToken cancellationToken) - { - var buffer = new byte[64 * 1024]; - using MemoryStream message = new(); - WebSocketReceiveResult result; - do + /// Reads exactly one message off a raw socket, reassembling it from as many fragments as it takes. + private static async Task ReceiveOneMessageAsync(ClientWebSocket socket, CancellationToken cancellationToken) { - result = await socket.ReceiveAsync(buffer, cancellationToken); - if (result.MessageType == WebSocketMessageType.Close) + byte[] buffer = new byte[64 * 1024]; + using MemoryStream message = new(); + WebSocketReceiveResult result; + do { - throw new InvalidOperationException("the host closed the socket before sending a frame."); + result = await socket.ReceiveAsync(buffer, cancellationToken); + if (result.MessageType == WebSocketMessageType.Close) + { + throw new InvalidOperationException("the host closed the socket before sending a frame."); + } + + message.Write(buffer, 0, result.Count); } + while (!result.EndOfMessage); - message.Write(buffer, 0, result.Count); + return Encoding.UTF8.GetString(message.ToArray()); } - while (!result.EndOfMessage); - - return Encoding.UTF8.GetString(message.ToArray()); - } - - [Fact(Timeout = 30_000)] - public async Task AnInterruptWithNoTurnRunning_ChangesNothing() - { - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendAsync(RelayFrames.Interrupt("nothing played", durationMs: 10)); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - - try - { - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + [Fact(Timeout = 30_000)] + public async Task AnInterruptWithNoTurnRunning_ChangesNothing() { - Assert.Fail("the turn after the ignored interrupt never finished within ten seconds."); - } - } + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); - [Fact(Timeout = 30_000)] - public async Task AnInterruptWithNoUtteranceUntilInterrupt_IsRefusedAndTheConversationContinues() - { - // Section 7.1's rule for an unknown frame type applies here too: a frame the vendor got - // wrong must not drop the conversation. RelayFrames.Interrupt always emits both fields, so a raw - // frame is sent by hand here, missing utteranceUntilInterrupt entirely — the one shape - // HandleInterrupt's own guard exists to survive, since System.Text.Json deserializes a - // missing non-nullable string as null rather than throwing, and ConversationSession.Interrupt - // itself would otherwise take an ArgumentNullException straight into the read loop. - using FragmentingChatClient reply = new("hello"); - EventObservedLoggerProvider capture = new("MalformedInterruptFrame"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendRawAsync("""{"type":"interrupt","durationUntilInterruptMs":10}"""); - - try - { - await capture.Observed.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never reported refusing the malformed interrupt within ten seconds."); - } + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Interrupt("nothing played", durationMs: 10)); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - try - { - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the turn after the refused interrupt never finished within ten seconds."); + try + { + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the turn after the ignored interrupt never finished within ten seconds."); + } } - } - [Fact(Timeout = 30_000)] - public async Task AnInterruptWithANegativeDuration_IsRefusedAndTheConversationContinues() - { - // The same guard, the other malformed shape it exists for: System.Text.Json enforces no - // range check on durationUntilInterruptMs, so a negative value would otherwise reach - // ConversationSession.Interrupt's own ArgumentOutOfRangeException uncaught and take the read loop - // down with it. D28 forbids clamping it into something plausible instead of refusing it. - using FragmentingChatClient reply = new("hello"); - EventObservedLoggerProvider capture = new("MalformedInterruptFrame"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendRawAsync( - """{"type":"interrupt","utteranceUntilInterrupt":"hello","durationUntilInterruptMs":-5}"""); - - try - { - await capture.Observed.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + [Fact(Timeout = 30_000)] + public async Task AnInterruptWithNoUtteranceUntilInterrupt_IsRefusedAndTheConversationContinues() { - Assert.Fail("the connection never reported refusing the malformed interrupt within ten seconds."); - } + // Section 7.1's rule for an unknown frame type applies here too: a frame the vendor got + // wrong must not drop the conversation. RelayFrames.Interrupt always emits both fields, so a raw + // frame is sent by hand here, missing utteranceUntilInterrupt entirely — the one shape + // HandleInterrupt's own guard exists to survive, since System.Text.Json deserializes a + // missing non-nullable string as null rather than throwing, and ConversationSession.Interrupt + // itself would otherwise take an ArgumentNullException straight into the read loop. + using FragmentingChatClient reply = new("hello"); + EventObservedLoggerProvider capture = new("MalformedInterruptFrame"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - - try - { - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the turn after the refused interrupt never finished within ten seconds."); - } - } + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - [Fact(Timeout = 30_000)] - public async Task ASecondFinalPromptDuringATurn_RunsAfterTheFirstTurnEnds() - { - // The caller can finish a second sentence before the agent speaks. There is no interrupt - // frame, so there is no heard text, and IConversationPort throws on a second turn. Holding - // one prompt keeps the caller's words; throwing would drop the conversation. - // - // reply.Conversations == 2 alone cannot tell the held path from an accident: if the release below - // happened to win the race against the server actually dispatching "two" while the first - // turn was still running, "two" would just start its own ordinary second turn instead of - // being held — and Calls would still read 2, the same as it would against code with no - // pending-prompt feature at all. Waiting for PromptHeld closes that gap: it only fires from - // inside the branch that holds a prompt, so seeing it is proof this is the path that ran. - // - // BlockingChatClient's gate ignores cancellation, so a defect in the pending-prompt chain - // would hang this test rather than fail it red, hence the deadline below. - using BlockingChatClient reply = new("first reply"); - EventObservedLoggerProvider capture = new("PromptHeld"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { await relay.SendAsync(RelayFrames.Setup()); - await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + await relay.SendRawAsync(/*lang=json,strict*/ """{"type":"interrupt","durationUntilInterruptMs":10}"""); try { - await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); - - await relay.SendAsync(RelayFrames.Prompt("two", last: true)); await capture.Observed.WaitAsync(bounded.Token); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the connection never reported holding the second prompt within ten seconds."); + Assert.Fail("the connection never reported refusing the malformed interrupt within ten seconds."); } - } - finally - { - reply.Release(); - } - try - { - await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // the first turn - await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // the held one + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + try + { + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the turn after the refused interrupt never finished within ten seconds."); + } } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + + [Fact(Timeout = 30_000)] + public async Task AnInterruptWithANegativeDuration_IsRefusedAndTheConversationContinues() { - Assert.Fail("the held prompt never ran its turn within ten seconds."); - } + // The same guard, the other malformed shape it exists for: System.Text.Json enforces no + // range check on durationUntilInterruptMs, so a negative value would otherwise reach + // ConversationSession.Interrupt's own ArgumentOutOfRangeException uncaught and take the read loop + // down with it. D28 forbids clamping it into something plausible instead of refusing it. + using FragmentingChatClient reply = new("hello"); + EventObservedLoggerProvider capture = new("MalformedInterruptFrame"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); - Assert.Equal(2, reply.Calls); - } + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - [Fact(Timeout = 30_000)] - public async Task AThirdFinalPromptDuringATurn_IsDroppedAndLoggedOnce() - { - // Item 6a of section 11 draws the line at one held prompt. This proves the line actually - // holds: a third and a fourth final prompt, arriving while one is already held, both run no - // turn of their own, and PendingPromptDropped — which the connection only ever logs once - // for the conversation — fires exactly once despite two drops, not once per dropped frame. - using BlockingChatClient reply = new("first reply"); - EventObservedLoggerProvider heldCapture = new("PromptHeld"); - EventObservedLoggerProvider droppedCapture = new("PendingPromptDropped"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => - { - logging.AddProvider(heldCapture); - logging.AddProvider(droppedCapture); - }); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { await relay.SendAsync(RelayFrames.Setup()); - await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + await relay.SendRawAsync( + /*lang=json,strict*/ + """{"type":"interrupt","utteranceUntilInterrupt":"hello","durationUntilInterruptMs":-5}"""); try { - await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); - - await relay.SendAsync(RelayFrames.Prompt("two", last: true)); - await heldCapture.Observed.WaitAsync(bounded.Token); + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported refusing the malformed interrupt within ten seconds."); + } - await relay.SendAsync(RelayFrames.Prompt("three", last: true)); - await droppedCapture.Observed.WaitAsync(bounded.Token); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - // A fourth cannot raise a second log line to wait on — the flag that guards it - // never resets. Releasing the gate right after SendAsync returns would only prove - // the bytes left this client, the same gap every other wait in this file closes: - // reply.Release() below unblocks turn one, which can cascade through - // RunPendingPrompt and clear _pendingPrompt for the held "two" before "four" has - // even reached the read loop — and a "four" that arrives to find nothing pending - // is held for a turn of its own instead of dropped, rather than proving anything - // about a second drop. This waits for the read loop to have plainly had enough - // time to reach and drop a small already-received frame, which needs nothing past - // dispatch and a lock acquisition, before the gate opens. - await relay.SendAsync(RelayFrames.Prompt("four", last: true)); - await Task.Delay(200, TestContext.Current.CancellationToken); + try + { + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the connection never reported holding or dropping a prompt within ten seconds."); + Assert.Fail("the turn after the refused interrupt never finished within ten seconds."); } } - finally - { - reply.Release(); - } - try - { - await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // "one" - await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // the held "two" - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the held prompt never ran its turn within ten seconds."); - } + [Fact(Timeout = 30_000)] + public async Task ASecondFinalPromptDuringATurn_RunsAfterTheFirstTurnEnds() + { + // The caller can finish a second sentence before the agent speaks. There is no interrupt + // frame, so there is no heard text, and IConversationPort throws on a second turn. Holding + // one prompt keeps the caller's words; throwing would drop the conversation. + // + // reply.Conversations == 2 alone cannot tell the held path from an accident: if the release below + // happened to win the race against the server actually dispatching "two" while the first + // turn was still running, "two" would just start its own ordinary second turn instead of + // being held — and Calls would still read 2, the same as it would against code with no + // pending-prompt feature at all. Waiting for PromptHeld closes that gap: it only fires from + // inside the branch that holds a prompt, so seeing it is proof this is the path that ran. + // + // BlockingChatClient's gate ignores cancellation, so a defect in the pending-prompt chain + // would hang this test rather than fail it red, hence the deadline below. + using BlockingChatClient reply = new("first reply"); + EventObservedLoggerProvider capture = new("PromptHeld"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - Assert.Equal(2, reply.Calls); - Assert.Equal(1, droppedCapture.Count); - } + try + { + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + + try + { + await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Prompt("two", last: true)); + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported holding the second prompt within ten seconds."); + } + } + finally + { + reply.Release(); + } - [Fact(Timeout = 30_000)] - public async Task ATurnAfterABargeIn_AnswersNormally() - { - // Item 6a is half proved by AfterAnInterrupt_NoFurtherTextFrameReachesTheRelay: a barge-in - // ends one turn cleanly. The other half — the conversation itself goes on — needs its own proof, - // because nothing else here shows the caller can speak again and get a real answer rather - // than silence or a leftover interrupted reply. - using BlockingChatClient reply = new("hello there caller"); - EventObservedLoggerProvider capture = new("InterruptReceived"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-continues")); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + try + { + _ = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // the first turn + _ = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // the held one + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the held prompt never ran its turn within ten seconds."); + } + + Assert.Equal(2, reply.Calls); + } + + [Fact(Timeout = 30_000)] + public async Task AThirdFinalPromptDuringATurn_IsDroppedAndLoggedOnce() + { + // Item 6a of section 11 draws the line at one held prompt. This proves the line actually + // holds: a third and a fourth final prompt, arriving while one is already held, both run no + // turn of their own, and PendingPromptDropped — which the connection only ever logs once + // for the conversation — fires exactly once despite two drops, not once per dropped frame. + using BlockingChatClient reply = new("first reply"); + EventObservedLoggerProvider heldCapture = new("PromptHeld"); + EventObservedLoggerProvider droppedCapture = new("PendingPromptDropped"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => + { + _ = logging.AddProvider(heldCapture); + _ = logging.AddProvider(droppedCapture); + }); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); try { - await relay.ReadFrameAsync().WaitAsync(bounded.Token); - await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + + try + { + await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Prompt("two", last: true)); + await heldCapture.Observed.WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Prompt("three", last: true)); + await droppedCapture.Observed.WaitAsync(bounded.Token); + + // A fourth cannot raise a second log line to wait on — the flag that guards it + // never resets. Releasing the gate right after SendAsync returns would only prove + // the bytes left this client, the same gap every other wait in this file closes: + // reply.Release() below unblocks turn one, which can cascade through + // RunPendingPrompt and clear _pendingPrompt for the held "two" before "four" has + // even reached the read loop — and a "four" that arrives to find nothing pending + // is held for a turn of its own instead of dropped, rather than proving anything + // about a second drop. This waits for the read loop to have plainly had enough + // time to reach and drop a small already-received frame, which needs nothing past + // dispatch and a lock acquisition, before the gate opens. + await relay.SendAsync(RelayFrames.Prompt("four", last: true)); + await Task.Delay(200, TestContext.Current.CancellationToken); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported holding or dropping a prompt within ten seconds."); + } + } + finally + { + reply.Release(); + } - await relay.SendAsync(RelayFrames.Interrupt("hello", durationMs: 200)); - await capture.Observed.WaitAsync(bounded.Token); + try + { + _ = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // "one" + _ = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); // the held "two" } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the connection never reported the barge-in within ten seconds."); + Assert.Fail("the held prompt never ran its turn within ten seconds."); } + + Assert.Equal(2, reply.Calls); + Assert.Equal(1, droppedCapture.Count); } - finally + + [Fact(Timeout = 30_000)] + public async Task ATurnAfterABargeIn_AnswersNormally() { - reply.Release(); - } + // Item 6a is half proved by AfterAnInterrupt_NoFurtherTextFrameReachesTheRelay: a barge-in + // ends one turn cleanly. The other half — the conversation itself goes on — needs its own proof, + // because nothing else here shows the caller can speak again and get a real answer rather + // than silence or a leftover interrupted reply. + using BlockingChatClient reply = new("hello there caller"); + EventObservedLoggerProvider capture = new("InterruptReceived"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); - var session = await host.FindSessionAsync("conversation-continues"); - Assert.NotNull(session); + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - var firstTurn = await WaitForTurnAsync(session!); - Assert.Equal(TimeSpan.FromMilliseconds(200), firstTurn.InterruptedAfter); + try + { + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-continues")); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + try + { + _ = await relay.ReadFrameAsync().WaitAsync(bounded.Token); + await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Interrupt("hello", durationMs: 200)); + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the barge-in within ten seconds."); + } + } + finally + { + reply.Release(); + } - await relay.SendAsync(RelayFrames.Prompt("go on", last: true)); + ConversationSession? session = await host.FindSessionAsync("conversation-continues"); + Assert.NotNull(session); - try - { - var tokens = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); - Assert.Equal("hello there caller", string.Concat(tokens)); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the turn after the barge-in never finished within ten seconds."); - } + TurnResult firstTurn = await WaitForTurnAsync(session!); + Assert.Equal(TimeSpan.FromMilliseconds(200), firstTurn.InterruptedAfter); - Assert.Null(session!.LastTurn!.InterruptedAfter); - } + await relay.SendAsync(RelayFrames.Prompt("go on", last: true)); - [Fact(Timeout = 30_000)] - public async Task AnInterruptWhileAHeldTurnHasSaidNothing_LeavesThatTurnFreeToSpeak() - { - // Telnyx paces the audio, so turn one is still playing when RunPendingPrompt starts turn - // two inside turn one's own finally. A barge-in that marks the turn running *now* would - // silence turn two, drop its closing frame, and leave the caller listening to dead air. - // The interrupt belongs to the turn whose output the caller was actually hearing. - using HeldPromptChatClient reply = new("first reply", "second reply"); - EventObservedLoggerProvider held = new("PromptHeld"); - EventObservedLoggerProvider interrupted = new("InterruptReceived"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => - { - logging.AddProvider(held); - logging.AddProvider(interrupted); - }); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-held-turn")); - await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + try + { + List tokens = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); + Assert.Equal("hello there caller", string.Concat(tokens)); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the turn after the barge-in never finished within ten seconds."); + } + + Assert.Null(session!.LastTurn!.InterruptedAfter); + } + + [Fact(Timeout = 30_000)] + public async Task AnInterruptWhileAHeldTurnHasSaidNothing_LeavesThatTurnFreeToSpeak() + { + // Telnyx paces the audio, so turn one is still playing when RunPendingPrompt starts turn + // two inside turn one's own finally. A barge-in that marks the turn running *now* would + // silence turn two, drop its closing frame, and leave the caller listening to dead air. + // The interrupt belongs to the turn whose output the caller was actually hearing. + using HeldPromptChatClient reply = new("first reply", "second reply"); + EventObservedLoggerProvider held = new("PromptHeld"); + EventObservedLoggerProvider interrupted = new("InterruptReceived"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => + { + _ = logging.AddProvider(held); + _ = logging.AddProvider(interrupted); + }); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + try + { + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-held-turn")); + await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + + try + { + await reply.WaitUntilFirstTurnStreamingAsync().WaitAsync(bounded.Token); + + // The second sentence lands while turn one still runs, so it is held rather than + // started, which is the only way to reach the two-turn overlap this test needs. + await relay.SendAsync(RelayFrames.Prompt("two", last: true)); + await held.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported holding the second prompt within ten seconds."); + } + } + finally + { + reply.ReleaseFirstTurn(); + } try { - await reply.WaitUntilFirstTurnStreamingAsync().WaitAsync(bounded.Token); + // Turn one's whole reply, closing frame included, is on the wire before the barge-in. + List first = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); + Assert.Equal("first reply", string.Concat(first)); - // The second sentence lands while turn one still runs, so it is held rather than - // started, which is the only way to reach the two-turn overlap this test needs. - await relay.SendAsync(RelayFrames.Prompt("two", last: true)); - await held.Observed.WaitAsync(bounded.Token); + // Turn two is now running and has produced nothing. The caller is still hearing turn one. + await reply.SecondTurnStarted.Task.WaitAsync(bounded.Token); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the connection never reported holding the second prompt within ten seconds."); + Assert.Fail("the held turn never started within ten seconds."); } - } - finally - { - reply.ReleaseFirstTurn(); - } - try - { - // Turn one's whole reply, closing frame included, is on the wire before the barge-in. - var first = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); - Assert.Equal("first reply", string.Concat(first)); + try + { + await relay.SendAsync(RelayFrames.Interrupt("first", durationMs: 640)); + await interrupted.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the barge-in within ten seconds."); + } + finally + { + reply.ReleaseSecondTurn(); + } - // Turn two is now running and has produced nothing. The caller is still hearing turn one. - await reply.SecondTurnStarted.Task.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the held turn never started within ten seconds."); + try + { + List second = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); + Assert.Equal("second reply", string.Concat(second)); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail( + "the held turn's answer never reached the relay within ten seconds; the barge-in " + + "silenced a turn the caller had not heard."); + } } - try - { - await relay.SendAsync(RelayFrames.Interrupt("first", durationMs: 640)); - await interrupted.Observed.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never reported the barge-in within ten seconds."); - } - finally - { - reply.ReleaseSecondTurn(); - } + [Fact(Timeout = 30_000)] + public async Task AnInterruptWhileAHeldTurnHasOnlyThoughtAloud_StillAmendsTheTurnTheCallerHeard() + { + // The sibling test above holds turn two before it produces anything at all, and both sides + // of the seam then agree on their own: the connection marks _spokenTurnId, which still names + // turn one, and ConversationSession finds its own run not audible. This test closes the gap between + // those two answers. A run becomes audible to ConversationSession at its first piece of *content*, + // and content is not a word: a tool call, a tool result, or a line of reasoning makes turn + // two audible to the core while not one syllable of it has reached the relay. The connection + // still marks turn one, correctly, and still lets turn two speak — but ConversationSession, asked + // nothing about which turn was heard, would cut turn two at its first thought and write the + // caller's heard text onto a turn nobody heard. cutsRunningTurn is the answer the connection + // already has, carried across the seam so the core stops guessing. + using HeldPromptChatClient reply = new("first reply", "second reply") + { + SecondTurnOpensWithUnspokenContent = true, + }; + EventObservedLoggerProvider held = new("PromptHeld"); + EventObservedLoggerProvider interrupted = new("InterruptReceived"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => + { + _ = logging.AddProvider(held); + _ = logging.AddProvider(interrupted); + }); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - try - { - var second = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); - Assert.Equal("second reply", string.Concat(second)); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail( - "the held turn's answer never reached the relay within ten seconds; the barge-in " - + "silenced a turn the caller had not heard."); - } - } + try + { + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-thinking-turn")); + await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + + try + { + await reply.WaitUntilFirstTurnStreamingAsync().WaitAsync(bounded.Token); + + await relay.SendAsync(RelayFrames.Prompt("two", last: true)); + await held.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported holding the second prompt within ten seconds."); + } + } + finally + { + reply.ReleaseFirstTurn(); + } - [Fact(Timeout = 30_000)] - public async Task AnInterruptWhileAHeldTurnHasOnlyThoughtAloud_StillAmendsTheTurnTheCallerHeard() - { - // The sibling test above holds turn two before it produces anything at all, and both sides - // of the seam then agree on their own: the connection marks _spokenTurnId, which still names - // turn one, and ConversationSession finds its own run not audible. This test closes the gap between - // those two answers. A run becomes audible to ConversationSession at its first piece of *content*, - // and content is not a word: a tool call, a tool result, or a line of reasoning makes turn - // two audible to the core while not one syllable of it has reached the relay. The connection - // still marks turn one, correctly, and still lets turn two speak — but ConversationSession, asked - // nothing about which turn was heard, would cut turn two at its first thought and write the - // caller's heard text onto a turn nobody heard. cutsRunningTurn is the answer the connection - // already has, carried across the seam so the core stops guessing. - using HeldPromptChatClient reply = new("first reply", "second reply") - { - SecondTurnOpensWithUnspokenContent = true, - }; - EventObservedLoggerProvider held = new("PromptHeld"); - EventObservedLoggerProvider interrupted = new("InterruptReceived"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => - { - logging.AddProvider(held); - logging.AddProvider(interrupted); - }); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-thinking-turn")); - await relay.SendAsync(RelayFrames.Prompt("one", last: true)); + ConversationSession? session = await host.FindSessionAsync("conversation-thinking-turn"); + Assert.NotNull(session); try { - await reply.WaitUntilFirstTurnStreamingAsync().WaitAsync(bounded.Token); + // Turn one's whole reply, closing frame included, is on the wire before the barge-in. + Assert.Equal("first reply", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - await relay.SendAsync(RelayFrames.Prompt("two", last: true)); - await held.Observed.WaitAsync(bounded.Token); + // Turn two is now running and has thought aloud once. The core calls it audible; the + // caller has heard nothing of it, because reasoning carries no text frame. + await reply.SecondTurnStarted.Task.WaitAsync(bounded.Token); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the connection never reported holding the second prompt within ten seconds."); + Assert.Fail("the held turn never reached its first thought within ten seconds."); } - } - finally - { - reply.ReleaseFirstTurn(); - } - var session = await host.FindSessionAsync("conversation-thinking-turn"); - Assert.NotNull(session); + TurnResult? first = session!.LastTurn; + Assert.NotNull(first); + Assert.Null(first!.InterruptedAfter); - try - { - // Turn one's whole reply, closing frame included, is on the wire before the barge-in. - Assert.Equal("first reply", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - - // Turn two is now running and has thought aloud once. The core calls it audible; the - // caller has heard nothing of it, because reasoning carries no text frame. - await reply.SecondTurnStarted.Task.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the held turn never reached its first thought within ten seconds."); - } - - var first = session!.LastTurn; - Assert.NotNull(first); - Assert.Null(first!.InterruptedAfter); + try + { + await relay.SendAsync(RelayFrames.Interrupt("first", durationMs: 640)); + await interrupted.Observed.WaitAsync(bounded.Token); + + // Read before the gate opens, while turn one is still the turn that finished last. D28: + // both values are the ones the vendor reported, and nothing here estimated either. + Assert.Equal(first.TurnIndex, session.LastTurn!.TurnIndex); + Assert.Equal("first", session.LastTurn.ReplyText); + Assert.Equal(TimeSpan.FromMilliseconds(640), session.LastTurn.InterruptedAfter); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the barge-in within ten seconds."); + } + finally + { + reply.ReleaseSecondTurn(); + } - try - { - await relay.SendAsync(RelayFrames.Interrupt("first", durationMs: 640)); - await interrupted.Observed.WaitAsync(bounded.Token); - - // Read before the gate opens, while turn one is still the turn that finished last. D28: - // both values are the ones the vendor reported, and nothing here estimated either. - Assert.Equal(first.TurnIndex, session.LastTurn!.TurnIndex); - Assert.Equal("first", session.LastTurn.ReplyText); - Assert.Equal(TimeSpan.FromMilliseconds(640), session.LastTurn.InterruptedAfter); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never reported the barge-in within ten seconds."); - } - finally - { - reply.ReleaseSecondTurn(); - } + try + { + List second = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); + Assert.Equal("second reply", string.Concat(second)); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail( + "the held turn's answer never reached the relay within ten seconds; the barge-in " + + "cut a turn the caller had only heard silence from."); + } - try - { - var second = await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token); - Assert.Equal("second reply", string.Concat(second)); + // Turn two ran to its own end. Nothing wrote the heard text onto it. + Assert.Equal("second reply", session.LastTurn!.ReplyText); + Assert.Null(session.LastTurn.InterruptedAfter); } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail( - "the held turn's answer never reached the relay within ten seconds; the barge-in " - + "cut a turn the caller had only heard silence from."); - } - - // Turn two ran to its own end. Nothing wrote the heard text onto it. - Assert.Equal("second reply", session.LastTurn!.ReplyText); - Assert.Null(session.LastTurn.InterruptedAfter); - } - /// Polls for the turn a barge-in ends, bounded the same way TelnyxRelayHost's own waits are. - private static async Task WaitForTurnAsync(ConversationSession session) - { - for (var attempt = 0; attempt < 1_000; attempt++) + /// Polls for the turn a barge-in ends, bounded the same way TelnyxRelayHost's own waits are. + private static async Task WaitForTurnAsync(ConversationSession session) { - if (session.LastTurn is { } turn) + for (int attempt = 0; attempt < 1_000; attempt++) { - return turn; + if (session.LastTurn is { } turn) + { + return turn; + } + + await Task.Delay(10, TestContext.Current.CancellationToken); } - await Task.Delay(10, TestContext.Current.CancellationToken); + throw new TimeoutException("the interrupted turn never finished within ten seconds."); } - - throw new TimeoutException("the interrupted turn never finished within ten seconds."); } } diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayConversationEndTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayConversationEndTests.cs index 1ae2b455..d1548775 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayConversationEndTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayConversationEndTests.cs @@ -7,7 +7,6 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Sessions.Memory; -using AgentCore.Application.Transcript; using AgentCore.Application.Conversation.Memory; using AgentCore.AspNetCore.DependencyInjection.Startup; using AgentCore.AspNetCore.Tests.Fakes; @@ -16,45 +15,46 @@ using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; using Xunit; +using AgentCore.Application.Configuration.Schema; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// How the chain of one conversation closes when the socket ends. -/// -/// -/// -/// Section 11, item 6 and T55/T56: every conversation writes hash-chained events ending in -/// conversation.ended, and the reason is one member of the closed set -/// names. The turn loop closes its own chain when the stage machine -/// reaches a terminal stage, and that is the only ending the core can see. Every other ending is -/// the adapter's to write, because only the adapter sees the socket end — which is what -/// says in its own remarks. -/// -/// -/// Every test here drives TelnyxRelayConnection.RunAsync over -/// rather than over a real port. The close of a conversation is exactly the moment a real socket stops -/// being observable — aborts its own socket on the way out, so a -/// graceful vendor close cannot be scripted over the wire at all — and the fake is what lets a test -/// script the vendor's own close frame, a faulting write loop, and a host that stops, each on its -/// own. Everything else about the connection is the real thing, including the session factory, the -/// store, the observers, and the audit queue AddAgentCore registers. -/// -/// -/// Every test here runs offline against a fake model. There is no Telnyx account, no network conversation, -/// and no API key anywhere in this file. That is T59. -/// -/// -public sealed class TelnyxRelayConversationEndTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - /// A document whose first turn moves the machine into a terminal stage. + /// + /// How the chain of one conversation closes when the socket ends. + /// /// - /// The transition carries no guard, so one turn is enough to reach close and the turn - /// loop closes the chain itself with agent.completed. That is the one ending teardown - /// must not write over. + /// + /// Section 11, item 6 and T55/T56: every conversation writes hash-chained events ending in + /// conversation.ended, and the reason is one member of the closed set + /// names. The turn loop closes its own chain when the stage machine + /// reaches a terminal stage, and that is the only ending the core can see. Every other ending is + /// the adapter's to write, because only the adapter sees the socket end — which is what + /// says in its own remarks. + /// + /// + /// Every test here drives TelnyxRelayConnection.RunAsync over + /// rather than over a real port. The close of a conversation is exactly the moment a real socket stops + /// being observable — aborts its own socket on the way out, so a + /// graceful vendor close cannot be scripted over the wire at all — and the fake is what lets a test + /// script the vendor's own close frame, a faulting write loop, and a host that stops, each on its + /// own. Everything else about the connection is the real thing, including the session factory, the + /// store, the observers, and the audit queue AddAgentCore registers. + /// + /// + /// Every test here runs offline against a fake model. There is no Telnyx account, no network conversation, + /// and no API key anywhere in this file. That is T59. + /// /// - private const string TerminalStageYaml = - """ + public sealed class TelnyxRelayConversationEndTests + { + /// A document whose first turn moves the machine into a terminal stage. + /// + /// The transition carries no guard, so one turn is enough to reach close and the turn + /// loop closes the chain itself with agent.completed. That is the one ending teardown + /// must not write over. + /// + private const string TerminalStageYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -78,594 +78,623 @@ public sealed class TelnyxRelayConversationEndTests - { kind: openai, model: gpt-4.1-mini, as: reply } """; - [Fact(Timeout = 30_000)] - public async Task ASocketTheRelayEnds_WritesOneConversationEndedThatNamesTheCallerHangup() - { - // The ordinary end of a conversation. The read loop sees the vendor's own close frame, teardown - // picks NormalClosure, and the chain has to close on the reason a report counts years - // later — not stop mid-chain with no terminal event at all. - using FragmentingChatClient reply = new("hello"); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply); - - // One channel, read in order, and DispatchAsync awaits StartConversationAsync: the session exists - // before the read loop ever sees the close behind it, so nothing here has to poll for it. - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-hangup")); - harness.Socket.QueueClose(); - - await WaitForTeardownAsync(harness); - - var events = await ReadChainAsync(harness, "conversation-hangup"); - - Assert.Equal( - [AuditEventKind.ConversationStarted, AuditEventKind.ConversationEnded], - events.Select(item => item.Kind).ToArray()); - Assert.Equal("caller.hangup", EndReasonOf(events)); - Assert.All(events, AuditEventVocabulary.Validate); - } - - [Fact(Timeout = 30_000)] - public async Task AConnectionWhoseWriteLoopFaulted_WritesOneConversationEndedThatNamesTheFault() - { - // Nothing on a healthy socket makes a send throw, so the fault is injected. The write loop - // faults, teardown picks InternalServerError, and the ending recorded must be the fault - // rather than a hang-up nobody performed. - using FragmentingChatClient reply = new("hello there caller"); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply); - - harness.Socket.FailEverySend(new InvalidOperationException("the send failed.")); - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-write-faulted")); - harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); - - await WaitForTeardownAsync(harness); - - var events = await ReadChainAsync(harness, "conversation-write-faulted"); - - Assert.Equal(AuditEventKind.ConversationEnded, events[^1].Kind); - Assert.Single(events, item => item.Kind == AuditEventKind.ConversationEnded); - Assert.Equal("conversation.faulted", EndReasonOf(events)); - Assert.All(events, AuditEventVocabulary.Validate); - } - - [Fact(Timeout = 30_000)] - public async Task AHostThatStopsUnderALiveConversation_WritesOneConversationEndedThatNamesTheFault() - { - // The caller did not hang up: the process went away underneath them. The closed set of - // section 4 holds four endings and this is not one of the other three, so the honest one is - // the fault. Recording it as caller.hangup would have a report count a shutdown as a caller - // choosing to leave. - using FragmentingChatClient reply = new("hello"); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-host-stopping")); - await WaitForSessionAsync(harness, "conversation-host-stopping"); - harness.StopApplication(); - - await WaitForTeardownAsync(harness); - - var events = await ReadChainAsync(harness, "conversation-host-stopping"); - - Assert.Equal(AuditEventKind.ConversationEnded, events[^1].Kind); - Assert.Equal("conversation.faulted", EndReasonOf(events)); - Assert.All(events, AuditEventVocabulary.Validate); - } - - [Fact(Timeout = 30_000)] - public async Task AConversationThatAlreadyReachedItsTerminalStage_GetsNoSecondTerminalEvent() - { - // The turn loop closed this chain itself, with agent.completed and the stage that ended it. - // EndConversation is idempotent, and this is the proof that the idempotence really holds through - // the adapter's path: one conversation.ended in the chain, and the reason is the agent's, not the - // socket's. - using FragmentingChatClient reply = new("goodbye then"); - await using var harness = await RelayConnectionHarness.StartAsync(TerminalStageYaml, reply); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-completed")); - harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); - - // The session's own completion flag, and never the last frame on the wire: the reply's - // closing frame leaves before the turn loop commits the turn, so a test that closed the - // socket on that frame would race the very event it is about to assert on. - var session = await WaitForCompletedConversationAsync(harness, "conversation-completed"); - Assert.True(session.IsComplete); - - harness.Socket.QueueClose(); - await WaitForTeardownAsync(harness); - - var events = await ReadChainAsync(harness, "conversation-completed"); - - Assert.Single(events, item => item.Kind == AuditEventKind.ConversationEnded); - Assert.Equal("agent.completed", EndReasonOf(events)); - Assert.All(events, AuditEventVocabulary.Validate); - } - - [Fact(Timeout = 30_000)] - public async Task ASocketThatEndedBeforeTheSetupFrame_WritesNothingAndTearsDownCleanly() - { - // No setup frame ever arrived, so there is no conversation, no session, and nothing to close. A - // chain with a conversation.ended and no conversation.started would be a record of a conversation that never - // happened, and teardown must not throw its way out of the request handler either. - using FragmentingChatClient reply = new("hello"); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply); - - harness.Socket.QueueClose(); - - await WaitForTeardownAsync(harness); - - Assert.True(harness.Connection.IsCompletedSuccessfully); - await Queue(harness).FlushAsync(TestContext.Current.CancellationToken); - Assert.Empty(Sink(harness).Events); - } - - [Fact(Timeout = 30_000)] - public async Task AClockThatThrowsWhileTheChainCloses_StillTearsDownAndStillReleasesTheSession() - { - // Section 7.1: teardown never throws out of the request handler. The one input the closing - // event reads that can throw is the clock, so it is the one a test can make throw. A throw - // here must cost the chain its last event and nothing else — never the session close behind - // it, which is what waits for the words the conversation's last turn still owed store 1. - FaultingClock clock = new(); - using FragmentingChatClient reply = new("hello"); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - configure: options => options.TimeProvider = clock); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-broken-clock")); - await WaitForSessionAsync(harness, "conversation-broken-clock"); - - // Armed only once the session exists: the session reads the clock as it is built, and a - // clock that failed that read would end the test before the path it is meant to reach. - clock.FailFromNowOn(); - harness.Socket.QueueClose(); - - await WaitForTeardownAsync(harness); - - Assert.True(harness.Connection.IsCompletedSuccessfully); - Assert.Null(await Sessions(harness).TryGetAsync("conversation-broken-clock", TestContext.Current.CancellationToken)); - } - - [Fact(Timeout = 30_000)] - public async Task EndConversation_HangUp_FlushesTranscriptBeforeSessionRemoval() - { - // Arrange - // - // Store 1 is written off the turn, so a conversation can end with its last words still in flight. - // The session is the only thing that can wait for them, so once it leaves the store nothing - // can: the record of that call would lose the turn the caller just had, and no error would - // say so. Same shape as the teardown that removed a session without closing its chain. - ParkingConversationStore transcript = new(); - using FragmentingChatClient reply = new("your order ships Friday"); - var factory = TranscriptBackedSessions(TelnyxRelayTurnTests.PolicyYaml, reply, transcript); - OrderedConversationSessions sessions = new(factory, () => transcript.Landed); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - relay: options => options.CloseTimeout = TimeSpan.FromSeconds(30), - configure: options => options.UseConversationSessions((_, _) => sessions)); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-flush")); - harness.Socket.Queue(RelayFrames.Prompt("when does my order ship?", last: true)); - await transcript.Parked.WaitAsync(TimeSpan.FromSeconds(20), TestContext.Current.CancellationToken); - - // Act - harness.Socket.QueueClose(); - - // The write is still parked, so a close that waits for it cannot return and this wait runs - // out. A close that does not wait returns at once and the wait ends early — which is the - // failure this test exists to catch, and why the release below comes after the wait. - await WaitQuietlyAsync(sessions.Closed, TimeSpan.FromSeconds(2)); - transcript.Release(); - await WaitForTeardownAsync(harness); - - // Assert - Assert.True( - sessions.TranscriptLandedAtClose, - "the close returned while store 1 still owed the conversation its last turn."); - Assert.Null(await sessions.TryGetAsync("conversation-flush", TestContext.Current.CancellationToken)); - } - - [Fact(Timeout = 30_000)] - public async Task StartConversation_SecondSetupFrame_FlushesTheReplacedTranscriptBeforeDroppingIt() - { - // Arrange - // - // A second setup frame replaces the session rather than refusing the socket, and the first - // one is dropped there and then. It is dropped by the same rule teardown obeys: the session - // is the only thing that can wait for the words it queued, so the first conversation's record would - // lose its last turn. - ParkingConversationStore transcript = new(); - using FragmentingChatClient reply = new("your order ships Friday"); - var factory = TranscriptBackedSessions(TelnyxRelayTurnTests.PolicyYaml, reply, transcript); - OrderedConversationSessions sessions = new(factory, () => transcript.Landed); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - relay: options => options.CloseTimeout = TimeSpan.FromSeconds(30), - configure: options => options.UseConversationSessions((_, _) => sessions)); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-first")); - harness.Socket.Queue(RelayFrames.Prompt("when does my order ship?", last: true)); - await transcript.Parked.WaitAsync(TimeSpan.FromSeconds(20), TestContext.Current.CancellationToken); - - // Act - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-second")); - - // Read as in EndConversation_HangUp_FlushesTranscriptBeforeSessionRemoval: the wait runs out while - // the write is parked, and ends early when the drop did not wait for it. - await WaitQuietlyAsync(sessions.Closed, TimeSpan.FromSeconds(2)); - transcript.Release(); - - // Assert - await WaitForSessionAsync(harness, "conversation-second"); - Assert.True( - sessions.TranscriptLandedAtClose, - "the close returned while store 1 still owed its call the last turn."); - } - - [Fact(Timeout = 30_000)] - public async Task EndConversation_StoreThatThrowsOnTheClose_LogsItAndStillTearsDown() - { - // Arrange - // - // IConversationSessions is a public seam, and the close is the last thing teardown does. The - // in-memory store never fails, so a store held over the network is the only one that can - // fail here — and its failure must not leave the request handler, which section 7.1 forbids. - EventObservedLoggerProvider capture = new("ConversationCloseFaulted"); - using FragmentingChatClient reply = new("your order ships Friday"); - FaultingConversationSessions sessions = new( - SessionsFor(TelnyxRelayTurnTests.PolicyYaml, reply), - new InvalidOperationException("the store is gone.")); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture), - configure: options => options.UseConversationSessions((_, _) => sessions)); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-store-faulted")); - - // Act - harness.Socket.QueueClose(); - await WaitForTeardownAsync(harness); - - // Assert - // - // WaitForTeardownAsync is what proves the throw stayed inside. The line is what proves the - // failure was reported rather than swallowed into silence: nothing retries the removal, so - // that session is in the store for the rest of the process and an operator has to hear it. - await capture.Observed.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken); - Assert.Equal(LogLevel.Error, capture.Level); - Assert.True(sessions.CloseAttempted, "teardown never reached the close at all."); - } - - [Fact(Timeout = 30_000)] - public async Task EndConversation_StoreThatNeverAnswersTheClose_TimesOutRatherThanWedgingTeardown() - { - // Arrange - // - // The other half of the same seam. A store that stops answering is not a store that throws: - // an unbounded wait here would hold this connection, its Kestrel request, and its - // registration on ApplicationStopping for the life of the process, and every conversation after it - // would do the same. - EventObservedLoggerProvider capture = new("TeardownTimedOut"); - using FragmentingChatClient reply = new("your order ships Friday"); - HangingConversationSessions sessions = new(SessionsFor(TelnyxRelayTurnTests.PolicyYaml, reply)); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture), - relay: options => options.CloseTimeout = TimeSpan.FromSeconds(1), - configure: options => options.UseConversationSessions((_, _) => sessions)); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-store-hung")); - - try - { - // Act - harness.Socket.QueueClose(); - await WaitForTeardownAsync(harness); - - // Assert - // - // The text is read rather than the line alone: TeardownTimedOut is written about - // whichever task ran out of time, and nothing else in this conversation is slow, so a match on - // the name alone would still pass if the close were left unbounded and some other wait - // timed out instead. - await capture.Observed.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken); - Assert.Contains("the session close", capture.Message); - } - finally - { - // The close is still parked, and disposal below waits on the connection. - sessions.Release(); - } - } - - /// The same factory over the memory store, for a test with no store 1 of its own. - /// The document to compile. - /// The model behind every reference in it. - /// The factory. - private static ConversationSessionFactory SessionsFor(string yaml, IChatClient reply) - => TranscriptBackedSessions(yaml, reply, new InMemoryConversationStore()); - - /// Builds the session factory of one document over a given store 1. - /// The document, as YAML. - /// The model behind every agent. - /// Where the words of a conversation are written. - /// The factory, ready to register over the one AddAgentCore built. - /// - /// A document that names no providers.conversations compiles onto the memory store, so this is the - /// only seam a test has for putting a slow store behind a conversation. It is why the whole factory is - /// rebuilt rather than decorated: the store is compiled into the agent, and the factory holds - /// the compiled agent. - /// - private static ConversationSessionFactory TranscriptBackedSessions( - string yaml, IChatClient reply, IConversationStore transcript) - { - var document = ConfigurationLoader.LoadYaml(yaml); - RoutingChatClientFactory chatClients = new(reply); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(chatClients) { ConversationStore = transcript })["main"]; - - return new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - ConversationSessionFactory.CreateExtractor(compiled, chatClients)); - } - - /// Waits for one task, and treats running out of time as an answer rather than a fault. - /// What to wait for. - /// How long to give it. - /// A task that completes either way. - private static async Task WaitQuietlyAsync(Task task, TimeSpan bound) - { - try - { - await task.WaitAsync(bound, TestContext.Current.CancellationToken); - } - catch (TimeoutException) - { - // The wait running out is what this caller is asking about. - } - } - - /// Waits for one connection to finish its own teardown. - /// The running connection. - /// A task that completes once teardown has run to its end. - /// - /// The connection task is awaited through a guard rather than directly, so a teardown that - /// throws — which section 7.1 forbids — fails here by name instead of surfacing as whatever - /// assertion happened to run next. - /// - private static async Task WaitForTeardownAsync(RelayConnectionHarness harness) - { - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(20)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { - await harness.Connection.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never tore down within twenty seconds."); - } - catch (Exception fault) - { - Assert.Fail($"teardown threw out of the request handler, which section 7.1 forbids: {fault}"); - } - } - - /// Waits until the store holds one conversation. - /// The running connection. - /// The id of the conversation. - /// A task that completes once the session appears. - private static async Task WaitForSessionAsync(RelayConnectionHarness harness, string conversationId) - { - for (var attempt = 0; attempt < 200; attempt++) - { - if (await Sessions(harness).TryGetAsync(conversationId, TestContext.Current.CancellationToken) is not null) - { - return; - } - - await Task.Delay(10, TestContext.Current.CancellationToken); - } - - Assert.Fail($"the session of conversation '{conversationId}' never appeared."); - } - - /// Waits until one conversation has closed its own chain from the terminal stage. - /// The running connection. - /// The id of the conversation. - /// The completed session. - private static async Task WaitForCompletedConversationAsync(RelayConnectionHarness harness, string conversationId) - { - for (var attempt = 0; attempt < 400; attempt++) - { - if (await Sessions(harness).TryGetAsync(conversationId, TestContext.Current.CancellationToken) - is { IsComplete: true } session) - { - return session; - } - - await Task.Delay(10, TestContext.Current.CancellationToken); - } - - Assert.Fail($"the conversation '{conversationId}' never reached its terminal stage."); - throw new InvalidOperationException("unreachable: Assert.Fail always throws."); - } - - /// Flushes the queue and reads back the chain of one conversation. - /// The connection that has already torn down. - /// The id of the conversation. - /// The events of that conversation, oldest first. - /// - /// The queue is what keeps the append off the turn, so a reader that wants the rows now asks - /// for them now. Nothing here waits on the chain being non-empty: every test that calls this - /// has already waited for the teardown that writes the last event. - /// - private static async Task> ReadChainAsync( - RelayConnectionHarness harness, - string conversationId) - { - await Queue(harness).FlushAsync(TestContext.Current.CancellationToken); - return Sink(harness).EventsOf(conversationId); - } - - /// Reads the end reason of the last event of one chain. - /// The chain. - /// The wire token under . - private static string EndReasonOf(IReadOnlyList events) - { - var ended = Assert.Single(events, item => item.Kind == AuditEventKind.ConversationEnded); - return ended.Payload[AuditPayloadKeys.EndReason]; - } - - /// Reads back the queue the composition root put in front of the store. - private static QueuedAuditSink Queue(RelayConnectionHarness harness) - => Assert.IsType(harness.Services.GetRequiredService()); - - /// Reads back the store the chain lands in. - private static InMemoryAuditSink Sink(RelayConnectionHarness harness) - => Assert.IsType(harness.Services.GetRequiredService().Store); - - /// Reads back the live sessions. - private static IConversationSessions Sessions(RelayConnectionHarness harness) - => harness.Services.GetRequiredService().ForSessions("main"); - } - - /// - /// A clock a test breaks on demand. - /// - /// - /// is the one call ConversationSession.EndConversation makes that can - /// throw at all: the reason is a member of a closed set the connection picks itself, and the - /// dispatcher behind the event swallows everything an observer raises. Breaking the clock is - /// therefore the only way a test can reach the guard that keeps section 7.1's promise — teardown - /// never throws out of the request handler. - /// - internal sealed class FaultingClock : TimeProvider - { - private volatile bool _failing; - - /// Makes every later reading of the wall clock throw. - public void FailFromNowOn() => _failing = true; - - /// - /// - /// Only this reading fails. The timestamps a turn measures with and the timers the pump's idle - /// deadline runs on are left alone, so a broken clock ends nothing but the one event under test. - /// - public override DateTimeOffset GetUtcNow() - => _failing - ? throw new InvalidOperationException("the clock failed.") - : base.GetUtcNow(); - } - - /// - /// The live sessions, with a note of what store 1 had done by the time a close returned. - /// - internal sealed class OrderedConversationSessions(IConversationSessionFactory factory, Func transcriptLanded) - : IConversationSessions - { - private readonly InMemoryConversationSessions _inner = - new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); - - private readonly TaskCompletionSource _closed = new(TaskCreationOptions.RunContinuationsAsynchronously); - - /// Gets a task that completes when a session has finished closing. - public Task Closed => _closed.Task; - - /// Gets whether store 1 had written the conversation's words by the time the close returned. - public bool? TranscriptLandedAtClose { get; private set; } - - /// - public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) - => _inner.OpenAsync(conversationId, cancellationToken); - - /// - public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) - => _inner.TryGetAsync(conversationId, cancellationToken); - - /// - public async ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) - { - await _inner.CloseAsync(conversationId, cancellationToken); - TranscriptLandedAtClose ??= transcriptLanded(); - _closed.TrySetResult(); - } - } - - /// Sessions that open normally and fail only when asked to close one. - /// Builds the sessions this holds. - /// What the close throws. - /// - /// It throws before its first await rather than from inside an async body, which is the harder of - /// the two for teardown to catch: a synchronous throw out of a method lands - /// at the conversation site, not on the returned task. - /// - internal sealed class FaultingConversationSessions(IConversationSessionFactory factory, Exception fault) : IConversationSessions - { - private readonly InMemoryConversationSessions _inner = - new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); - - /// Gets whether teardown ever reached the close. - public bool CloseAttempted { get; private set; } - - /// - public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) - => _inner.OpenAsync(conversationId, cancellationToken); - - /// - public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) - => _inner.TryGetAsync(conversationId, cancellationToken); - - /// - public ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) - { - CloseAttempted = true; - throw fault; - } - } - - /// Sessions whose close never answers until a test releases it. - internal sealed class HangingConversationSessions(IConversationSessionFactory factory) : IConversationSessions - { - private readonly InMemoryConversationSessions _inner = - new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); - - private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); - - /// - public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) - => _inner.OpenAsync(conversationId, cancellationToken); - - /// - public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) - => _inner.TryGetAsync(conversationId, cancellationToken); - - /// - /// - /// It ignores on purpose. Teardown passes - /// there, so a store that honoured a token would prove - /// nothing about the bound teardown puts on the wait itself. - /// - public async ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) - { - await _release.Task; - await _inner.CloseAsync(conversationId, CancellationToken.None); - } - - /// Lets the parked close finish. - public void Release() => _release.TrySetResult(); - } + [Fact(Timeout = 30_000)] + public async Task ASocketTheRelayEnds_WritesOneConversationEndedThatNamesTheCallerHangup() + { + // The ordinary end of a conversation. The read loop sees the vendor's own close frame, teardown + // picks NormalClosure, and the chain has to close on the reason a report counts years + // later — not stop mid-chain with no terminal event at all. + using FragmentingChatClient reply = new("hello"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply); + + // One channel, read in order, and DispatchAsync awaits StartConversationAsync: the session exists + // before the read loop ever sees the close behind it, so nothing here has to poll for it. + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-hangup")); + harness.Socket.QueueClose(); + + await WaitForTeardownAsync(harness); + + IReadOnlyList events = await ReadChainAsync(harness, "conversation-hangup"); + + Assert.Equal( + [AuditEventKind.ConversationStarted, AuditEventKind.ConversationEnded], + events.Select(item => item.Kind).ToArray()); + Assert.Equal("caller.hangup", EndReasonOf(events)); + Assert.All(events, AuditEventVocabulary.Validate); + } + + [Fact(Timeout = 30_000)] + public async Task AConnectionWhoseWriteLoopFaulted_WritesOneConversationEndedThatNamesTheFault() + { + // Nothing on a healthy socket makes a send throw, so the fault is injected. The write loop + // faults, teardown picks InternalServerError, and the ending recorded must be the fault + // rather than a hang-up nobody performed. + using FragmentingChatClient reply = new("hello there caller"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply); + + harness.Socket.FailEverySend(new InvalidOperationException("the send failed.")); + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-write-faulted")); + harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); + + await WaitForTeardownAsync(harness); + + IReadOnlyList events = await ReadChainAsync(harness, "conversation-write-faulted"); + + Assert.Equal(AuditEventKind.ConversationEnded, events[^1].Kind); + _ = Assert.Single(events, item => item.Kind == AuditEventKind.ConversationEnded); + Assert.Equal("conversation.faulted", EndReasonOf(events)); + Assert.All(events, AuditEventVocabulary.Validate); + } + + [Fact(Timeout = 30_000)] + public async Task AHostThatStopsUnderALiveConversation_WritesOneConversationEndedThatNamesTheFault() + { + // The caller did not hang up: the process went away underneath them. The closed set of + // section 4 holds four endings and this is not one of the other three, so the honest one is + // the fault. Recording it as caller.hangup would have a report count a shutdown as a caller + // choosing to leave. + using FragmentingChatClient reply = new("hello"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-host-stopping")); + await WaitForSessionAsync(harness, "conversation-host-stopping"); + harness.StopApplication(); + + await WaitForTeardownAsync(harness); + + IReadOnlyList events = await ReadChainAsync(harness, "conversation-host-stopping"); + + Assert.Equal(AuditEventKind.ConversationEnded, events[^1].Kind); + Assert.Equal("conversation.faulted", EndReasonOf(events)); + Assert.All(events, AuditEventVocabulary.Validate); + } + + [Fact(Timeout = 30_000)] + public async Task AConversationThatAlreadyReachedItsTerminalStage_GetsNoSecondTerminalEvent() + { + // The turn loop closed this chain itself, with agent.completed and the stage that ended it. + // EndConversation is idempotent, and this is the proof that the idempotence really holds through + // the adapter's path: one conversation.ended in the chain, and the reason is the agent's, not the + // socket's. + using FragmentingChatClient reply = new("goodbye then"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync(TerminalStageYaml, reply); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-completed")); + harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); + + // The session's own completion flag, and never the last frame on the wire: the reply's + // closing frame leaves before the turn loop commits the turn, so a test that closed the + // socket on that frame would race the very event it is about to assert on. + ConversationSession session = await WaitForCompletedConversationAsync(harness, "conversation-completed"); + Assert.True(session.IsComplete); + + harness.Socket.QueueClose(); + await WaitForTeardownAsync(harness); + + IReadOnlyList events = await ReadChainAsync(harness, "conversation-completed"); + + _ = Assert.Single(events, item => item.Kind == AuditEventKind.ConversationEnded); + Assert.Equal("agent.completed", EndReasonOf(events)); + Assert.All(events, AuditEventVocabulary.Validate); + } + + [Fact(Timeout = 30_000)] + public async Task ASocketThatEndedBeforeTheSetupFrame_WritesNothingAndTearsDownCleanly() + { + // No setup frame ever arrived, so there is no conversation, no session, and nothing to close. A + // chain with a conversation.ended and no conversation.started would be a record of a conversation that never + // happened, and teardown must not throw its way out of the request handler either. + using FragmentingChatClient reply = new("hello"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply); + + harness.Socket.QueueClose(); + + await WaitForTeardownAsync(harness); + + Assert.True(harness.Connection.IsCompletedSuccessfully); + await Queue(harness).FlushAsync(TestContext.Current.CancellationToken); + Assert.Empty(Sink(harness).Events); + } + + [Fact(Timeout = 30_000)] + public async Task AClockThatThrowsWhileTheChainCloses_StillTearsDownAndStillReleasesTheSession() + { + // Section 7.1: teardown never throws out of the request handler. The one input the closing + // event reads that can throw is the clock, so it is the one a test can make throw. A throw + // here must cost the chain its last event and nothing else — never the session close behind + // it, which is what waits for the words the conversation's last turn still owed store 1. + FaultingClock clock = new(); + using FragmentingChatClient reply = new("hello"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + configure: options => options.TimeProvider = clock); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-broken-clock")); + await WaitForSessionAsync(harness, "conversation-broken-clock"); + + // Armed only once the session exists: the session reads the clock as it is built, and a + // clock that failed that read would end the test before the path it is meant to reach. + clock.FailFromNowOn(); + harness.Socket.QueueClose(); + + await WaitForTeardownAsync(harness); + + Assert.True(harness.Connection.IsCompletedSuccessfully); + Assert.Null(await Sessions(harness).TryGetAsync("conversation-broken-clock", TestContext.Current.CancellationToken)); + } + + [Fact(Timeout = 30_000)] + public async Task EndConversation_HangUp_FlushesTranscriptBeforeSessionRemoval() + { + // Arrange + // + // Store 1 is written off the turn, so a conversation can end with its last words still in flight. + // The session is the only thing that can wait for them, so once it leaves the store nothing + // can: the record of that call would lose the turn the caller just had, and no error would + // say so. Same shape as the teardown that removed a session without closing its chain. + ParkingConversationStore transcript = new(); + using FragmentingChatClient reply = new("your order ships Friday"); + ConversationSessionFactory factory = TranscriptBackedSessions(TelnyxRelayTurnTests.PolicyYaml, reply, transcript); + OrderedConversationSessions sessions = new(factory, () => transcript.Landed); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + relay: options => options.CloseTimeout = TimeSpan.FromSeconds(30), + configure: options => options.UseConversationSessions((_, _) => sessions)); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-flush")); + harness.Socket.Queue(RelayFrames.Prompt("when does my order ship?", last: true)); + await transcript.Parked.WaitAsync(TimeSpan.FromSeconds(20), TestContext.Current.CancellationToken); + + // Act + harness.Socket.QueueClose(); + + // The write is still parked, so a close that waits for it cannot return and this wait runs + // out. A close that does not wait returns at once and the wait ends early — which is the + // failure this test exists to catch, and why the release below comes after the wait. + await WaitQuietlyAsync(sessions.Closed, TimeSpan.FromSeconds(2)); + transcript.Release(); + await WaitForTeardownAsync(harness); + + // Assert + Assert.True( + sessions.TranscriptLandedAtClose, + "the close returned while store 1 still owed the conversation its last turn."); + Assert.Null(await sessions.TryGetAsync("conversation-flush", TestContext.Current.CancellationToken)); + } + + [Fact(Timeout = 30_000)] + public async Task StartConversation_SecondSetupFrame_FlushesTheReplacedTranscriptBeforeDroppingIt() + { + // Arrange + // + // A second setup frame replaces the session rather than refusing the socket, and the first + // one is dropped there and then. It is dropped by the same rule teardown obeys: the session + // is the only thing that can wait for the words it queued, so the first conversation's record would + // lose its last turn. + ParkingConversationStore transcript = new(); + using FragmentingChatClient reply = new("your order ships Friday"); + ConversationSessionFactory factory = TranscriptBackedSessions(TelnyxRelayTurnTests.PolicyYaml, reply, transcript); + OrderedConversationSessions sessions = new(factory, () => transcript.Landed); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + relay: options => options.CloseTimeout = TimeSpan.FromSeconds(30), + configure: options => options.UseConversationSessions((_, _) => sessions)); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-first")); + harness.Socket.Queue(RelayFrames.Prompt("when does my order ship?", last: true)); + await transcript.Parked.WaitAsync(TimeSpan.FromSeconds(20), TestContext.Current.CancellationToken); + + // Act + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-second")); + + // Read as in EndConversation_HangUp_FlushesTranscriptBeforeSessionRemoval: the wait runs out while + // the write is parked, and ends early when the drop did not wait for it. + await WaitQuietlyAsync(sessions.Closed, TimeSpan.FromSeconds(2)); + transcript.Release(); + + // Assert + await WaitForSessionAsync(harness, "conversation-second"); + Assert.True( + sessions.TranscriptLandedAtClose, + "the close returned while store 1 still owed its call the last turn."); + } + + [Fact(Timeout = 30_000)] + public async Task EndConversation_StoreThatThrowsOnTheClose_LogsItAndStillTearsDown() + { + // Arrange + // + // IConversationSessions is a public seam, and the close is the last thing teardown does. The + // in-memory store never fails, so a store held over the network is the only one that can + // fail here — and its failure must not leave the request handler, which section 7.1 forbids. + EventObservedLoggerProvider capture = new("ConversationCloseFaulted"); + using FragmentingChatClient reply = new("your order ships Friday"); + FaultingConversationSessions sessions = new( + SessionsFor(TelnyxRelayTurnTests.PolicyYaml, reply), + new InvalidOperationException("the store is gone.")); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture), + configure: options => options.UseConversationSessions((_, _) => sessions)); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-store-faulted")); + + // Act + harness.Socket.QueueClose(); + await WaitForTeardownAsync(harness); + + // Assert + // + // WaitForTeardownAsync is what proves the throw stayed inside. The line is what proves the + // failure was reported rather than swallowed into silence: nothing retries the removal, so + // that session is in the store for the rest of the process and an operator has to hear it. + await capture.Observed.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken); + Assert.Equal(LogLevel.Error, capture.Level); + Assert.True(sessions.CloseAttempted, "teardown never reached the close at all."); + } + + [Fact(Timeout = 30_000)] + public async Task EndConversation_StoreThatNeverAnswersTheClose_TimesOutRatherThanWedgingTeardown() + { + // Arrange + // + // The other half of the same seam. A store that stops answering is not a store that throws: + // an unbounded wait here would hold this connection, its Kestrel request, and its + // registration on ApplicationStopping for the life of the process, and every conversation after it + // would do the same. + EventObservedLoggerProvider capture = new("TeardownTimedOut"); + using FragmentingChatClient reply = new("your order ships Friday"); + HangingConversationSessions sessions = new(SessionsFor(TelnyxRelayTurnTests.PolicyYaml, reply)); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture), + relay: options => options.CloseTimeout = TimeSpan.FromSeconds(1), + configure: options => options.UseConversationSessions((_, _) => sessions)); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-store-hung")); + + try + { + // Act + harness.Socket.QueueClose(); + await WaitForTeardownAsync(harness); + + // Assert + // + // The text is read rather than the line alone: TeardownTimedOut is written about + // whichever task ran out of time, and nothing else in this conversation is slow, so a match on + // the name alone would still pass if the close were left unbounded and some other wait + // timed out instead. + await capture.Observed.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken); + Assert.Contains("the session close", capture.Message); + } + finally + { + // The close is still parked, and disposal below waits on the connection. + sessions.Release(); + } + } + + /// The same factory over the memory store, for a test with no store 1 of its own. + /// The document to compile. + /// The model behind every reference in it. + /// The factory. + private static ConversationSessionFactory SessionsFor(string yaml, IChatClient reply) + { + return TranscriptBackedSessions(yaml, reply, new InMemoryConversationStore()); + } + + /// Builds the session factory of one document over a given store 1. + /// The document, as YAML. + /// The model behind every agent. + /// Where the words of a conversation are written. + /// The factory, ready to register over the one AddAgentCore built. + /// + /// A document that names no providers.conversations compiles onto the memory store, so this is the + /// only seam a test has for putting a slow store behind a conversation. It is why the whole factory is + /// rebuilt rather than decorated: the store is compiled into the agent, and the factory holds + /// the compiled agent. + /// + private static ConversationSessionFactory TranscriptBackedSessions( + string yaml, IChatClient reply, IConversationStore transcript) + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(yaml); + RoutingChatClientFactory chatClients = new(reply); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(chatClients) { ConversationStore = transcript })["main"]; + + return new ConversationSessionFactory( + compiled, + new GuardEvaluator(compiled.Configuration.Guards), + ConversationSessionFactory.CreateExtractor(compiled, chatClients)); + } + + /// Waits for one task, and treats running out of time as an answer rather than a fault. + /// What to wait for. + /// How long to give it. + /// A task that completes either way. + private static async Task WaitQuietlyAsync(Task task, TimeSpan bound) + { + try + { + await task.WaitAsync(bound, TestContext.Current.CancellationToken); + } + catch (TimeoutException) + { + // The wait running out is what this caller is asking about. + } + } + + /// Waits for one connection to finish its own teardown. + /// The running connection. + /// A task that completes once teardown has run to its end. + /// + /// The connection task is awaited through a guard rather than directly, so a teardown that + /// throws — which section 7.1 forbids — fails here by name instead of surfacing as whatever + /// assertion happened to run next. + /// + private static async Task WaitForTeardownAsync(RelayConnectionHarness harness) + { + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(20)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + try + { + await harness.Connection.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never tore down within twenty seconds."); + } + catch (Exception fault) + { + Assert.Fail($"teardown threw out of the request handler, which section 7.1 forbids: {fault}"); + } + } + + /// Waits until the store holds one conversation. + /// The running connection. + /// The id of the conversation. + /// A task that completes once the session appears. + private static async Task WaitForSessionAsync(RelayConnectionHarness harness, string conversationId) + { + for (int attempt = 0; attempt < 200; attempt++) + { + if (await Sessions(harness).TryGetAsync(conversationId, TestContext.Current.CancellationToken) is not null) + { + return; + } + + await Task.Delay(10, TestContext.Current.CancellationToken); + } + + Assert.Fail($"the session of conversation '{conversationId}' never appeared."); + } + + /// Waits until one conversation has closed its own chain from the terminal stage. + /// The running connection. + /// The id of the conversation. + /// The completed session. + private static async Task WaitForCompletedConversationAsync(RelayConnectionHarness harness, string conversationId) + { + for (int attempt = 0; attempt < 400; attempt++) + { + if (await Sessions(harness).TryGetAsync(conversationId, TestContext.Current.CancellationToken) + is { IsComplete: true } session) + { + return session; + } + + await Task.Delay(10, TestContext.Current.CancellationToken); + } + + Assert.Fail($"the conversation '{conversationId}' never reached its terminal stage."); + throw new InvalidOperationException("unreachable: Assert.Fail always throws."); + } + + /// Flushes the queue and reads back the chain of one conversation. + /// The connection that has already torn down. + /// The id of the conversation. + /// The events of that conversation, oldest first. + /// + /// The queue is what keeps the append off the turn, so a reader that wants the rows now asks + /// for them now. Nothing here waits on the chain being non-empty: every test that calls this + /// has already waited for the teardown that writes the last event. + /// + private static async Task> ReadChainAsync( + RelayConnectionHarness harness, + string conversationId) + { + await Queue(harness).FlushAsync(TestContext.Current.CancellationToken); + return Sink(harness).EventsOf(conversationId); + } + + /// Reads the end reason of the last event of one chain. + /// The chain. + /// The wire token under . + private static string EndReasonOf(IReadOnlyList events) + { + AuditEvent ended = Assert.Single(events, item => item.Kind == AuditEventKind.ConversationEnded); + return ended.Payload[AuditPayloadKeys.EndReason]; + } + + /// Reads back the queue the composition root put in front of the store. + private static QueuedAuditSink Queue(RelayConnectionHarness harness) + { + return Assert.IsType(harness.Services.GetRequiredService()); + } + + /// Reads back the store the chain lands in. + private static InMemoryAuditSink Sink(RelayConnectionHarness harness) + { + return Assert.IsType(harness.Services.GetRequiredService().Store); + } + + /// Reads back the live sessions. + private static IConversationSessions Sessions(RelayConnectionHarness harness) + { + return harness.Services.GetRequiredService().ForSessions("main"); + } + } + + /// + /// A clock a test breaks on demand. + /// + /// + /// is the one call ConversationSession.EndConversation makes that can + /// throw at all: the reason is a member of a closed set the connection picks itself, and the + /// dispatcher behind the event swallows everything an observer raises. Breaking the clock is + /// therefore the only way a test can reach the guard that keeps section 7.1's promise — teardown + /// never throws out of the request handler. + /// + internal sealed class FaultingClock : TimeProvider + { + private volatile bool _failing; + + /// Makes every later reading of the wall clock throw. + public void FailFromNowOn() + { + _failing = true; + } + + /// + /// + /// Only this reading fails. The timestamps a turn measures with and the timers the pump's idle + /// deadline runs on are left alone, so a broken clock ends nothing but the one event under test. + /// + public override DateTimeOffset GetUtcNow() + { + return _failing + ? throw new InvalidOperationException("the clock failed.") + : base.GetUtcNow(); + } + } + + /// + /// The live sessions, with a note of what store 1 had done by the time a close returned. + /// + internal sealed class OrderedConversationSessions(IConversationSessionFactory factory, Func transcriptLanded) + : IConversationSessions + { + private readonly InMemoryConversationSessions _inner = + new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); + + private readonly TaskCompletionSource _closed = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /// Gets a task that completes when a session has finished closing. + public Task Closed => _closed.Task; + + /// Gets whether store 1 had written the conversation's words by the time the close returned. + public bool? TranscriptLandedAtClose { get; private set; } + + /// + public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) + { + return _inner.OpenAsync(conversationId, cancellationToken); + } + + /// + public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) + { + return _inner.TryGetAsync(conversationId, cancellationToken); + } + + /// + public async ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) + { + await _inner.CloseAsync(conversationId, cancellationToken); + TranscriptLandedAtClose ??= transcriptLanded(); + _ = _closed.TrySetResult(); + } + } + + /// Sessions that open normally and fail only when asked to close one. + /// Builds the sessions this holds. + /// What the close throws. + /// + /// It throws before its first await rather than from inside an async body, which is the harder of + /// the two for teardown to catch: a synchronous throw out of a method lands + /// at the conversation site, not on the returned task. + /// + internal sealed class FaultingConversationSessions(IConversationSessionFactory factory, Exception fault) : IConversationSessions + { + private readonly InMemoryConversationSessions _inner = + new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); + + /// Gets whether teardown ever reached the close. + public bool CloseAttempted { get; private set; } + + /// + public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) + { + return _inner.OpenAsync(conversationId, cancellationToken); + } + + /// + public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) + { + return _inner.TryGetAsync(conversationId, cancellationToken); + } + + /// + public ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) + { + CloseAttempted = true; + throw fault; + } + } + + /// Sessions whose close never answers until a test releases it. + internal sealed class HangingConversationSessions(IConversationSessionFactory factory) : IConversationSessions + { + private readonly InMemoryConversationSessions _inner = + new(factory, InMemoryConversationSessions.DefaultIdleTimeout, TimeProvider.System); + + private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /// + public ValueTask OpenAsync(string? conversationId, CancellationToken cancellationToken = default) + { + return _inner.OpenAsync(conversationId, cancellationToken); + } + + /// + public ValueTask TryGetAsync(string conversationId, CancellationToken cancellationToken = default) + { + return _inner.TryGetAsync(conversationId, cancellationToken); + } + + /// + /// + /// It ignores on purpose. Teardown passes + /// there, so a store that honoured a token would prove + /// nothing about the bound teardown puts on the wait itself. + /// + public async ValueTask CloseAsync(string conversationId, CancellationToken cancellationToken = default) + { + await _release.Task; + await _inner.CloseAsync(conversationId, CancellationToken.None); + } + + /// Lets the parked close finish. + public void Release() + { + _ = _release.TrySetResult(); + } + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayEndpointTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayEndpointTests.cs index f7142a4e..7d3519dd 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayEndpointTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayEndpointTests.cs @@ -2,254 +2,254 @@ using System.Net; using System.Net.WebSockets; using AgentCore.AspNetCore.Tests.Fakes; -using AgentCore.AspNetCore.Vendors.TelnyxRelay; using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// How the route behaves before a conversation, and how the socket ends. -/// -/// -/// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, -/// no network conversation, and no API key anywhere in this file. -/// -public sealed class TelnyxRelayEndpointTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - [Fact(Timeout = 30_000)] - public async Task APlainGet_IsRefused() + /// + /// How the route behaves before a conversation, and how the socket ends. + /// + /// + /// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, + /// no network conversation, and no API key anywhere in this file. + /// + public sealed class TelnyxRelayEndpointTests { - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - - var answer = await host.GetAsync(TelnyxRelayHost.MainRelay); + [Fact(Timeout = 30_000)] + public async Task APlainGet_IsRefused() + { + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - Assert.Equal(HttpStatusCode.BadRequest, answer.StatusCode); - } + HttpResponseMessage answer = await host.GetAsync(TelnyxRelayHost.MainRelay); - [Fact(Timeout = 30_000)] - public async Task AHostThatForgotUseWebSockets_FailsWithAMessageThatNamesTheFix() - { - // The library maps an endpoint, and UseWebSockets is middleware the host owns. Without it - // the endpoint throws InvalidOperationException rather than answering 400 — ASP.NET Core's - // own hosting layer has no exception-handling middleware here, so ASP.NET Core turns that - // unhandled throw into an empty 500, and the reason must not be a mystery in the log. - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartWithoutWebSocketsAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply); - - var answer = await host.GetAsync(TelnyxRelayHost.MainRelay); - - Assert.Equal(HttpStatusCode.InternalServerError, answer.StatusCode); - Assert.Contains("UseWebSockets", host.LastError, StringComparison.Ordinal); - } + Assert.Equal(HttpStatusCode.BadRequest, answer.StatusCode); + } - // --------------------------------------------------------------------------------------------- - // The three option-range facts that stood here are now in - // AgentCore.AspNetCore.Tests/Conversation/ConversationOptionsFromDocumentTests. The limits come out of - // providers.conversation rather than out of a C# argument, so the same three ranges are refused by a - // ConfigurationLoadException carrying the pointer of the offending field, and there is no - // longer a map-time ArgumentOutOfRangeException for this file to assert. Spec §12. - // --------------------------------------------------------------------------------------------- + [Fact(Timeout = 30_000)] + public async Task AHostThatForgotUseWebSockets_FailsWithAMessageThatNamesTheFix() + { + // The library maps an endpoint, and UseWebSockets is middleware the host owns. Without it + // the endpoint throws InvalidOperationException rather than answering 400 — ASP.NET Core's + // own hosting layer has no exception-handling middleware here, so ASP.NET Core turns that + // unhandled throw into an empty 500, and the reason must not be a mystery in the log. + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartWithoutWebSocketsAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply); + + HttpResponseMessage answer = await host.GetAsync(TelnyxRelayHost.MainRelay); + + Assert.Equal(HttpStatusCode.InternalServerError, answer.StatusCode); + Assert.Contains("UseWebSockets", host.LastError, StringComparison.Ordinal); + } - [Fact(Timeout = 30_000)] - public async Task MalformedJson_ClosesWithInvalidPayloadData() - { - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); + // --------------------------------------------------------------------------------------------- + // The three option-range facts that stood here are now in + // AgentCore.AspNetCore.Tests/Conversation/ConversationOptionsFromDocumentTests. The limits come out of + // providers.conversation rather than out of a C# argument, so the same three ranges are refused by a + // ConfigurationLoadException carrying the pointer of the offending field, and there is no + // longer a map-time ArgumentOutOfRangeException for this file to assert. Spec §12. + // --------------------------------------------------------------------------------------------- - await relay.SendRawAsync("{ this is not JSON"); + [Fact(Timeout = 30_000)] + public async Task MalformedJson_ClosesWithInvalidPayloadData() + { + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); - var close = await relay.ReadCloseAsync(); - Assert.Equal(WebSocketCloseStatus.InvalidPayloadData, close.Status); - } + await relay.SendRawAsync("{ this is not JSON"); - [Fact(Timeout = 30_000)] - public async Task MalformedJson_LogsTheRefusalAtWarningNotError() - { - // Round 1, item 2: a protocol violation is the relay's own mistake, not this endpoint's - // bug, and DetermineCloseStatus already carries the right close status off the same - // exception. RelayProtocolViolation must log it at Warning — the level PromptBeforeSetup, - // FrameRefused, and MalformedInterruptFrame already use for a bad frame — and not at the - // Error level ReadLoopFaulted uses for an unhandled defect. - using FragmentingChatClient reply = new("hello"); - EventObservedLoggerProvider capture = new("RelayProtocolViolation"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - await relay.SendRawAsync("{ this is not JSON"); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try - { - await capture.Observed.WaitAsync(bounded.Token); + (WebSocketCloseStatus? Status, string? Description) = await relay.ReadCloseAsync(); + Assert.Equal(WebSocketCloseStatus.InvalidPayloadData, Status); } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + + [Fact(Timeout = 30_000)] + public async Task MalformedJson_LogsTheRefusalAtWarningNotError() { - Assert.Fail("the connection never logged the protocol violation within ten seconds."); - } + // Round 1, item 2: a protocol violation is the relay's own mistake, not this endpoint's + // bug, and DetermineCloseStatus already carries the right close status off the same + // exception. RelayProtocolViolation must log it at Warning — the level PromptBeforeSetup, + // FrameRefused, and MalformedInterruptFrame already use for a bad frame — and not at the + // Error level ReadLoopFaulted uses for an unhandled defect. + using FragmentingChatClient reply = new("hello"); + EventObservedLoggerProvider capture = new("RelayProtocolViolation"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendRawAsync("{ this is not JSON"); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + try + { + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never logged the protocol violation within ten seconds."); + } - Assert.Equal(LogLevel.Warning, capture.Level); - } + Assert.Equal(LogLevel.Warning, capture.Level); + } - [Fact(Timeout = 30_000)] - public async Task AFrameOverTheLimit_ClosesWithMessageTooBig() - { - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - relay: options => options.MaxFrameBytes = 256); - await using var relay = await host.ConnectAsync(); + [Fact(Timeout = 30_000)] + public async Task AFrameOverTheLimit_ClosesWithMessageTooBig() + { + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + relay: options => options.MaxFrameBytes = 256); + await using FakeRelayClient relay = await host.ConnectAsync(); - await relay.SendAsync(RelayFrames.Prompt(new string('a', 1024), last: true)); + await relay.SendAsync(RelayFrames.Prompt(new string('a', 1024), last: true)); - var close = await relay.ReadCloseAsync(); - Assert.Equal(WebSocketCloseStatus.MessageTooBig, close.Status); - } + (WebSocketCloseStatus? Status, string? Description) = await relay.ReadCloseAsync(); + Assert.Equal(WebSocketCloseStatus.MessageTooBig, Status); + } - [Fact(Timeout = 30_000)] - public async Task AClientThatVanishesWithNoCloseFrame_ReleasesTheSession() - { - // The vendor never reconnects, so a dead socket is a finished conversation. - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); + [Fact(Timeout = 30_000)] + public async Task AClientThatVanishesWithNoCloseFrame_ReleasesTheSession() + { + // The vendor never reconnects, so a dead socket is a finished conversation. + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - var relay = await host.ConnectAsync(); - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-dropped")); - await host.WaitForSessionAsync("conversation-dropped"); + FakeRelayClient relay = await host.ConnectAsync(); + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-dropped")); + await host.WaitForSessionAsync("conversation-dropped"); - relay.Abort(); + relay.Abort(); - await host.WaitForConversationEndAsync("conversation-dropped"); - Assert.Null(await host.FindSessionAsync("conversation-dropped")); - } + await host.WaitForConversationEndAsync("conversation-dropped"); + Assert.Null(await host.FindSessionAsync("conversation-dropped")); + } - [Fact(Timeout = 30_000)] - public async Task ASocketThatGoesSilent_EndsTheConversationAtTheIdleDeadline() - { - // The vendor never reconnects, so a silent socket is a conversation that already ended. Nothing - // else notices it: the keep-alive ping only catches a peer the network itself stopped - // answering. The clock is a FakeTimeProvider, moved forward below with no real sleep at - // all, so this test proves the idle deadline fires rather than passing because the - // timeout never triggers — if it never fired, closing would still be incomplete when the - // bounded wait below gives up. - FakeTimeProvider clock = new(DateTimeOffset.UtcNow); - EventObservedLoggerProvider capture = new("IdleTimeoutReached"); - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - configure: options => options.TimeProvider = clock, - logging: logging => logging.AddProvider(capture), - relay: options => options.IdleTimeout = TimeSpan.FromSeconds(30)); - await using var relay = await host.ConnectAsync(); - - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-silent")); - await host.WaitForSessionAsync("conversation-silent"); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - var closing = relay.ReadCloseAsync(); - (WebSocketCloseStatus? Status, string? Description) close; - try + [Fact(Timeout = 30_000)] + public async Task ASocketThatGoesSilent_EndsTheConversationAtTheIdleDeadline() { - // WaitForSessionAsync only proves the setup frame reached the store; it says nothing - // about whether the read loop has already armed its next idle deadline against this - // clock by the time this runs. Advancing once could land before that deadline exists - // and move nothing that matters. Advancing repeatedly instead closes that race: - // whichever conversation lands after the deadline is armed pushes the clock straight past its - // due time, however many earlier conversations landed too early to move anything. - while (!closing.IsCompleted) + // The vendor never reconnects, so a silent socket is a conversation that already ended. Nothing + // else notices it: the keep-alive ping only catches a peer the network itself stopped + // answering. The clock is a FakeTimeProvider, moved forward below with no real sleep at + // all, so this test proves the idle deadline fires rather than passing because the + // timeout never triggers — if it never fired, closing would still be incomplete when the + // bounded wait below gives up. + FakeTimeProvider clock = new(DateTimeOffset.UtcNow); + EventObservedLoggerProvider capture = new("IdleTimeoutReached"); + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + configure: options => options.TimeProvider = clock, + logging: logging => logging.AddProvider(capture), + relay: options => options.IdleTimeout = TimeSpan.FromSeconds(30)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-silent")); + await host.WaitForSessionAsync("conversation-silent"); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + Task<(WebSocketCloseStatus? Status, string? Description)> closing = relay.ReadCloseAsync(); + (WebSocketCloseStatus? Status, string? Description) close; + try { - clock.Advance(TimeSpan.FromSeconds(31)); - await Task.Delay(20, bounded.Token); - } + // WaitForSessionAsync only proves the setup frame reached the store; it says nothing + // about whether the read loop has already armed its next idle deadline against this + // clock by the time this runs. Advancing once could land before that deadline exists + // and move nothing that matters. Advancing repeatedly instead closes that race: + // whichever conversation lands after the deadline is armed pushes the clock straight past its + // due time, however many earlier conversations landed too early to move anything. + while (!closing.IsCompleted) + { + clock.Advance(TimeSpan.FromSeconds(31)); + await Task.Delay(20, bounded.Token); + } - close = await closing; - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the socket never closed within ten seconds of the idle deadline firing."); - return; - } + close = await closing; + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the socket never closed within ten seconds of the idle deadline firing."); + return; + } - Assert.Equal(WebSocketCloseStatus.NormalClosure, close.Status); - Assert.True(capture.Observed.IsCompletedSuccessfully, "the idle deadline closed the socket without logging IdleTimeoutReached."); - Assert.Equal(LogLevel.Information, capture.Level); + Assert.Equal(WebSocketCloseStatus.NormalClosure, close.Status); + Assert.True(capture.Observed.IsCompletedSuccessfully, "the idle deadline closed the socket without logging IdleTimeoutReached."); + Assert.Equal(LogLevel.Information, capture.Level); - await host.WaitForConversationEndAsync("conversation-silent"); - } + await host.WaitForConversationEndAsync("conversation-silent"); + } - [Fact(Timeout = 30_000)] - public async Task ABusyConversation_NeverTimesOutBetweenMessages() - { - // Task 8: each inbound frame resets the idle clock. Proven here by advancing the fake - // clock five times, each step under IdleTimeout on its own but well over it summed — a - // clock that failed to reset on every dtmf frame between the steps would have closed this - // conversation by the second step at the latest. Dtmf is the frame to drive this with because - // TelnyxRelayLog.DtmfReceived logs no argument at all, so counting it never risks logging - // the digit itself. - const int steps = 5; - FakeTimeProvider clock = new(DateTimeOffset.UtcNow); - EventObservedLoggerProvider dtmf = new("DtmfReceived"); - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - configure: options => options.TimeProvider = clock, - logging: logging => logging.AddProvider(dtmf), - relay: options => options.IdleTimeout = TimeSpan.FromSeconds(2)); - await using var relay = await host.ConnectAsync(); - - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-busy")); - await host.WaitForSessionAsync("conversation-busy"); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try + [Fact(Timeout = 30_000)] + public async Task ABusyConversation_NeverTimesOutBetweenMessages() { - for (var step = 0; step < steps; step++) + // Task 8: each inbound frame resets the idle clock. Proven here by advancing the fake + // clock five times, each step under IdleTimeout on its own but well over it summed — a + // clock that failed to reset on every dtmf frame between the steps would have closed this + // conversation by the second step at the latest. Dtmf is the frame to drive this with because + // TelnyxRelayLog.DtmfReceived logs no argument at all, so counting it never risks logging + // the digit itself. + const int steps = 5; + FakeTimeProvider clock = new(DateTimeOffset.UtcNow); + EventObservedLoggerProvider dtmf = new("DtmfReceived"); + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + configure: options => options.TimeProvider = clock, + logging: logging => logging.AddProvider(dtmf), + relay: options => options.IdleTimeout = TimeSpan.FromSeconds(2)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-busy")); + await host.WaitForSessionAsync("conversation-busy"); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + try { - // 1.5s against a 2s deadline: under the deadline on its own, five times over it - // summed, so this can only pass if every dtmf frame below actually rearms the - // deadline rather than leaving the one armed at setup still counting down. - clock.Advance(TimeSpan.FromSeconds(1.5)); - await relay.SendAsync(RelayFrames.Dtmf("1")); - - // Waits for this step's own dtmf frame to be logged, rather than a fixed real - // sleep: a guessed delay could still be running when the next iteration's Advance - // fires, landing a second advance against the deadline armed for this message - // before the server had a chance to rearm it for the next one — a false close that - // would have nothing to do with whether resets actually work. Watching the count - // reach this step, the same way the interrupt tests wait on a log line rather than - // sleeping, is what keeps every Advance conversation behind the message it depends on. - var expected = step + 1; - while (dtmf.Count < expected) + for (int step = 0; step < steps; step++) { - await Task.Delay(5, bounded.Token); + // 1.5s against a 2s deadline: under the deadline on its own, five times over it + // summed, so this can only pass if every dtmf frame below actually rearms the + // deadline rather than leaving the one armed at setup still counting down. + clock.Advance(TimeSpan.FromSeconds(1.5)); + await relay.SendAsync(RelayFrames.Dtmf("1")); + + // Waits for this step's own dtmf frame to be logged, rather than a fixed real + // sleep: a guessed delay could still be running when the next iteration's Advance + // fires, landing a second advance against the deadline armed for this message + // before the server had a chance to rearm it for the next one — a false close that + // would have nothing to do with whether resets actually work. Watching the count + // reach this step, the same way the interrupt tests wait on a log line rather than + // sleeping, is what keeps every Advance conversation behind the message it depends on. + int expected = step + 1; + while (dtmf.Count < expected) + { + await Task.Delay(5, bounded.Token); + } } } - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail($"only {dtmf.Count} of {steps} dtmf frames were processed within ten seconds; the conversation likely closed early."); - return; - } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail($"only {dtmf.Count} of {steps} dtmf frames were processed within ten seconds; the conversation likely closed early."); + return; + } - Assert.NotNull(await host.FindSessionAsync("conversation-busy")); + Assert.NotNull(await host.FindSessionAsync("conversation-busy")); + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameCostTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameCostTests.cs index 083de507..020eaa01 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameCostTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameCostTests.cs @@ -1,4 +1,3 @@ -using AgentCore.TestSupport; using System.Diagnostics.Metrics; using System.Runtime.CompilerServices; using AgentCore.Application.Diagnostics; @@ -6,252 +5,276 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// What one inbound frame costs in observability. Section 3.1 and T61: never once for each frame. -/// -/// -/// -/// Section 3.1 states the rule as "never log or meter once for each audio frame". There is no audio -/// anywhere in this solution — item 6c holds "no audio buffer, codec, sample rate, or playback -/// clock" by construction, and the Conversation Relay carries text frames over a WebSocket instead — -/// so the frame is what that rule is actually about. It is the thing that arrives many times a -/// second on a live conversation, and it is the thing that must not cost a log line or a metric point. -/// -/// -/// The proof is a comparison rather than a threshold, because a threshold would have to guess how -/// many lines a conversation is allowed. One connection is driven twice, once with a few frames and once -/// with ten times as many, and the two runs must leave exactly the same number of log records and -/// exactly the same number of metric measurements behind. A signal that fires once for each frame -/// grows with the frame count and fails here; a signal that fires once for the conversation or once for the -/// turn does not, because both runs run one conversation and no turn at all. -/// -/// -/// The frames are interim transcripts — prompt with last: false — which T70 drops -/// outright: DispatchAsync matches them with an empty case RelayFrame.Prompt: and the -/// turn starts on the final one instead. Fifty of them must therefore do exactly as much work as -/// five of them, namely none, so anything this test does see growing is observability and nothing -/// else. -/// -/// -/// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, -/// no network conversation, and no API key anywhere in this file. -/// -/// -[Collection(TelnyxRelayFrameCostSuite.Name)] -public sealed class TelnyxRelayFrameCostTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - /// The small run. - private const int FewFrames = 5; - - /// The large run. Ten times the frames, and it must cost the same. - private const int ManyFrames = 50; - - [Fact(Timeout = 60_000)] - public async Task TenTimesTheInboundFrames_CostNoMoreLogRecordsAndNoMoreMetricMeasurements() - { - var few = await MeasureAsync(FewFrames, "conversation-frame-cost-few"); - var many = await MeasureAsync(ManyFrames, "conversation-frame-cost-many"); - - // The listener really found this library's meter. Without this the measurement assertion - // below could pass on two empty subscriptions and prove nothing at all. - Assert.NotEqual(0, few.Instruments); - Assert.Equal(few.Instruments, many.Instruments); - - // The provider really was in the host's logging pipeline, for the same reason. - Assert.NotEqual(0, few.Records); - - // Section 3.1, both halves of it. Ten times the frames, and not one line and not one - // measurement more. The counts are not zero — a conversation still logs what a conversation costs, and the - // one dtmf frame each run ends with is one line in both — but nothing here is charged to a - // frame, so nothing here moves when the frame count does. - Assert.Equal(few.Records, many.Records); - Assert.Equal(few.Measurements, many.Measurements); - } - - /// Drives one connection over interim prompts and counts what it cost. - /// How many prompt frames with last: false to send. - /// The conversationSessionId of this run's setup frame. - /// What the run wrote, metered, and subscribed to. - private static async Task MeasureAsync(int frames, string conversationId) + /// + /// What one inbound frame costs in observability. Section 3.1 and T61: never once for each frame. + /// + /// + /// + /// Section 3.1 states the rule as "never log or meter once for each audio frame". There is no audio + /// anywhere in this solution — item 6c holds "no audio buffer, codec, sample rate, or playback + /// clock" by construction, and the Conversation Relay carries text frames over a WebSocket instead — + /// so the frame is what that rule is actually about. It is the thing that arrives many times a + /// second on a live conversation, and it is the thing that must not cost a log line or a metric point. + /// + /// + /// The proof is a comparison rather than a threshold, because a threshold would have to guess how + /// many lines a conversation is allowed. One connection is driven twice, once with a few frames and once + /// with ten times as many, and the two runs must leave exactly the same number of log records and + /// exactly the same number of metric measurements behind. A signal that fires once for each frame + /// grows with the frame count and fails here; a signal that fires once for the conversation or once for the + /// turn does not, because both runs run one conversation and no turn at all. + /// + /// + /// The frames are interim transcripts — prompt with last: false — which T70 drops + /// outright: DispatchAsync matches them with an empty case RelayFrame.Prompt: and the + /// turn starts on the final one instead. Fifty of them must therefore do exactly as much work as + /// five of them, namely none, so anything this test does see growing is observability and nothing + /// else. + /// + /// + /// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, + /// no network conversation, and no API key anywhere in this file. + /// + /// + [Collection(TelnyxRelayFrameCostSuite.Name)] + public sealed class TelnyxRelayFrameCostTests { - // The instruments are static fields of AgentCoreTelemetry, and a const never touches a type - // initializer, so nothing this file references would otherwise create the meter. Forcing - // the initializer before the listener starts is what makes the instrument count a real - // check that the listener found this library rather than an empty subscription. - RuntimeHelpers.RunClassConstructor(typeof(AgentCoreTelemetry).TypeHandle); + /// The small run. + private const int FewFrames = 5; - Lock gate = new(); - var measurements = 0; - var instruments = 0; + /// The large run. Ten times the frames, and it must cost the same. + private const int ManyFrames = 50; - void RecordMeasurement() + [Fact(Timeout = 60_000)] + public async Task TenTimesTheInboundFrames_CostNoMoreLogRecordsAndNoMoreMetricMeasurements() { - lock (gate) - { - measurements++; - } + FrameCost few = await MeasureAsync(FewFrames, "conversation-frame-cost-few"); + FrameCost many = await MeasureAsync(ManyFrames, "conversation-frame-cost-many"); + + // The listener really found this library's meter. Without this the measurement assertion + // below could pass on two empty subscriptions and prove nothing at all. + Assert.NotEqual(0, few.Instruments); + Assert.Equal(few.Instruments, many.Instruments); + + // The provider really was in the host's logging pipeline, for the same reason. + Assert.NotEqual(0, few.Records); + + // Section 3.1, both halves of it. Ten times the frames, and not one line and not one + // measurement more. The counts are not zero — a conversation still logs what a conversation costs, and the + // one dtmf frame each run ends with is one line in both — but nothing here is charged to a + // frame, so nothing here moves when the frame count does. + Assert.Equal(few.Records, many.Records); + Assert.Equal(few.Measurements, many.Measurements); } - using MeterListener listener = new(); - listener.InstrumentPublished = (instrument, active) => + /// Drives one connection over interim prompts and counts what it cost. + /// How many prompt frames with last: false to send. + /// The conversationSessionId of this run's setup frame. + /// What the run wrote, metered, and subscribed to. + private static async Task MeasureAsync(int frames, string conversationId) { - // Meter name and nothing else. T61 forbids a conversation id on a metric attribute, so there is - // deliberately no tag on any of these instruments that could narrow this to one conversation — - // which is why this collection runs alone, below. - if (!string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal)) - { - return; - } + // The instruments are static fields of AgentCoreTelemetry, and a const never touches a type + // initializer, so nothing this file references would otherwise create the meter. Forcing + // the initializer before the listener starts is what makes the instrument count a real + // check that the listener found this library rather than an empty subscription. + RuntimeHelpers.RunClassConstructor(typeof(AgentCoreTelemetry).TypeHandle); - lock (gate) + Lock gate = new(); + int measurements = 0; + int instruments = 0; + + void RecordMeasurement() { - instruments++; + lock (gate) + { + measurements++; + } } - active.EnableMeasurementEvents(instrument); - }; - - // Every numeric type an instrument may carry, not only the double of the turn histogram and - // the long of the three counters. A per-frame instrument somebody adds later is counted - // here whatever its type, rather than slipping past an incomplete set of callbacks. - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); - listener.Start(); - - RecordCountingLoggerProvider records = new(); - - // An interim prompt leaves no trace at all — that is the point of it — so nothing about it - // can be waited on. A dtmf frame behind the last of them can be: the socket delivers - // messages in order and the read loop dispatches them in order, so the line this frame - // writes is proof that every prompt ahead of it has already been read and dropped. It costs - // one log record, the same one, in both runs. - EventObservedLoggerProvider sentinel = new("DtmfReceived"); - - using FragmentingChatClient reply = new("hello"); - var host = await TelnyxRelayHost.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging: logging => + using MeterListener listener = new(); + listener.InstrumentPublished = (instrument, active) => { - logging.AddProvider(records); - logging.AddProvider(sentinel); - }); - - try - { - await using var relay = await host.ConnectAsync(); + // Meter name and nothing else. T61 forbids a conversation id on a metric attribute, so there is + // deliberately no tag on any of these instruments that could narrow this to one conversation — + // which is why this collection runs alone, below. + if (!string.Equals(instrument.Meter.Name, AgentCoreTelemetry.MeterName, StringComparison.Ordinal)) + { + return; + } + + lock (gate) + { + instruments++; + } + + active.EnableMeasurementEvents(instrument); + }; + + // Every numeric type an instrument may carry, not only the double of the turn histogram and + // the long of the three counters. A per-frame instrument somebody adds later is counted + // here whatever its type, rather than slipping past an incomplete set of callbacks. + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.SetMeasurementEventCallback((_, _, _, _) => RecordMeasurement()); + listener.Start(); + + RecordCountingLoggerProvider records = new(); + + // An interim prompt leaves no trace at all — that is the point of it — so nothing about it + // can be waited on. A dtmf frame behind the last of them can be: the socket delivers + // messages in order and the read loop dispatches them in order, so the line this frame + // writes is proof that every prompt ahead of it has already been read and dropped. It costs + // one log record, the same one, in both runs. + EventObservedLoggerProvider sentinel = new("DtmfReceived"); + + using FragmentingChatClient reply = new("hello"); + TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging: logging => + { + _ = logging.AddProvider(records); + _ = logging.AddProvider(sentinel); + }); - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: conversationId)); - await host.WaitForSessionAsync(conversationId); - - for (var frame = 0; frame < frames; frame++) + try + { + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: conversationId)); + await host.WaitForSessionAsync(conversationId); + + for (int frame = 0; frame < frames; frame++) + { + // The same words every time, so the two runs differ in frame count and in nothing + // else. + await relay.SendAsync(RelayFrames.Prompt("hello", last: false)); + } + + await relay.SendAsync(RelayFrames.Dtmf("1")); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(20)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + try + { + await sentinel.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail($"the connection never read past the {frames} interim prompts within twenty seconds."); + } + + // Counted here, with the conversation still up, rather than after the socket and the host are + // torn down. Teardown is once for a conversation and never once for a frame, so it is not what + // this test is about, and it is the one part of a run that is not reproducible line for + // line: FakeRelayClient.DisposeAsync cancels its own pending receive, which — as that + // class documents — leaves the socket Aborted rather than closed, so the connection + // sometimes reaches ConversationDroppedWithNoCloseFrame before the host stops and sometimes does + // not, and the host's own shutdown lines interleave with Kestrel's either way. Every + // line up to and including the one the sentinel just waited for is fixed. + listener.Dispose(); + return new FrameCost(records.Count, measurements, instruments); + } + finally { - // The same words every time, so the two runs differ in frame count and in nothing - // else. - await relay.SendAsync(RelayFrames.Prompt("hello", last: false)); + await host.DisposeAsync(); } + } - await relay.SendAsync(RelayFrames.Dtmf("1")); + /// What one run of cost. + /// How many log records the host wrote, at every level and category. + /// How many measurements the instruments of this library took. + /// How many instruments of this library the listener subscribed to. + private readonly record struct FrameCost(int Records, int Measurements, int Instruments); + } - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(20)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); + /// + /// The collection runs in, alone. + /// + /// + /// A subscribes to a meter for the whole process, and T61 is the reason + /// it cannot narrow that to one conversation: no instrument of this library carries a conversation id, a session id, + /// or a turn id, because one such attribute is one permanent series. A turn running in another test + /// class at the same moment would therefore land on this listener and be counted as this conversation's + /// cost. Parallelisation is switched off for this collection so that never happens; xUnit runs a + /// collection marked this way apart from every other collection in the assembly. + /// + [CollectionDefinition(Name, DisableParallelization = true)] + public sealed class TelnyxRelayFrameCostSuite + { + /// The name both the definition and the test class name it by. + public const string Name = "telnyx relay frame cost"; + } - try - { - await sentinel.Observed.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + /// + /// Counts every log record the host wrote, whatever its category, level, or event id. + /// + /// + /// counts the lines of one named event, which is what a + /// test proving that a particular line fired needs. Section 3.1 is the opposite question — nothing + /// at all may fire once for each frame, whether or not anyone thought to name it — so this one + /// counts the whole pipeline instead and cares about no name. + /// + internal sealed class RecordCountingLoggerProvider : ILoggerProvider + { + private readonly Lock _gate = new(); + + public int Count + { + get { - Assert.Fail($"the connection never read past the {frames} interim prompts within twenty seconds."); + lock (_gate) + { + return field; + } } - // Counted here, with the conversation still up, rather than after the socket and the host are - // torn down. Teardown is once for a conversation and never once for a frame, so it is not what - // this test is about, and it is the one part of a run that is not reproducible line for - // line: FakeRelayClient.DisposeAsync cancels its own pending receive, which — as that - // class documents — leaves the socket Aborted rather than closed, so the connection - // sometimes reaches ConversationDroppedWithNoCloseFrame before the host stops and sometimes does - // not, and the host's own shutdown lines interleave with Kestrel's either way. Every - // line up to and including the one the sentinel just waited for is fixed. - listener.Dispose(); - return new FrameCost(records.Count, measurements, instruments); + private set; } - finally + + public ILogger CreateLogger(string categoryName) { - await host.DisposeAsync(); + return new Logger(this); } - } - - /// What one run of cost. - /// How many log records the host wrote, at every level and category. - /// How many measurements the instruments of this library took. - /// How many instruments of this library the listener subscribed to. - private readonly record struct FrameCost(int Records, int Measurements, int Instruments); -} -/// -/// The collection runs in, alone. -/// -/// -/// A subscribes to a meter for the whole process, and T61 is the reason -/// it cannot narrow that to one conversation: no instrument of this library carries a conversation id, a session id, -/// or a turn id, because one such attribute is one permanent series. A turn running in another test -/// class at the same moment would therefore land on this listener and be counted as this conversation's -/// cost. Parallelisation is switched off for this collection so that never happens; xUnit runs a -/// collection marked this way apart from every other collection in the assembly. -/// -[CollectionDefinition(TelnyxRelayFrameCostSuite.Name, DisableParallelization = true)] -public sealed class TelnyxRelayFrameCostSuite -{ - /// The name both the definition and the test class name it by. - public const string Name = "telnyx relay frame cost"; -} - -/// -/// Counts every log record the host wrote, whatever its category, level, or event id. -/// -/// -/// counts the lines of one named event, which is what a -/// test proving that a particular line fired needs. Section 3.1 is the opposite question — nothing -/// at all may fire once for each frame, whether or not anyone thought to name it — so this one -/// counts the whole pipeline instead and cares about no name. -/// -internal sealed class RecordCountingLoggerProvider : ILoggerProvider -{ - private int _count; - - /// Gets how many records have reached this provider so far. - public int Count => Volatile.Read(ref _count); + public void Dispose() + { + // Nothing to release. + } - public ILogger CreateLogger(string categoryName) => new Logger(this); + private sealed class Logger(RecordCountingLoggerProvider owner) : ILogger + { + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } - public void Dispose() - { - // Nothing to release. - } + public bool IsEnabled(LogLevel logLevel) + { + return true; + } - private sealed class Logger(RecordCountingLoggerProvider owner) : ILogger - { - public IDisposable? BeginScope(TState state) - where TState : notnull - => null; - - public bool IsEnabled(LogLevel logLevel) => true; - - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) - => Interlocked.Increment(ref owner._count); + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + lock (owner._gate) + { + owner.Count++; + } + } + } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameReaderTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameReaderTests.cs index 02053cbf..c1ecbfd4 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameReaderTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayFrameReaderTests.cs @@ -3,27 +3,28 @@ using AgentCore.AspNetCore.Vendors.TelnyxRelay; using Xunit; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// The reader against the frames the vendor documents. -/// -/// -/// Every JSON body below is copied from the Telnyx Conversation Relay page, so these are golden -/// inputs and not invented ones. Every test here runs offline. There is no network conversation and no API -/// key anywhere in this file. -/// -public sealed class TelnyxRelayFrameReaderTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - // ------------------------------------------------------------------------------------------- - // The five inbound frames. - // ------------------------------------------------------------------------------------------- - - [Fact] - public void ASetupFrame_ReadsTheIdsTheTransferWillNeed() - { - const string Json = - """ + /// + /// The reader against the frames the vendor documents. + /// + /// + /// Every JSON body below is copied from the Telnyx Conversation Relay page, so these are golden + /// inputs and not invented ones. Every test here runs offline. There is no network conversation and no API + /// key anywhere in this file. + /// + public sealed class TelnyxRelayFrameReaderTests + { + // ------------------------------------------------------------------------------------------- + // The five inbound frames. + // ------------------------------------------------------------------------------------------- + + [Fact] + public void ASetupFrame_ReadsTheIdsTheTransferWillNeed() + { + const string Json = + /*lang=json,strict*/ + """ {"type":"setup","sessionId":"7a7e6a4f","accountSid":"1f1a8b6f", "callSid":"v2:abc","callControlId":"v2:abc","conversationSessionId":"ff55a038", "callLegId":"428c31b6","from":"+13122010094","to":"+13122123456", @@ -31,204 +32,214 @@ public void ASetupFrame_ReadsTheIdsTheTransferWillNeed() "customParameters":{"customer_id":"customer_123"}} """; - Assert.True(Read(Json, out var frame, out _)); - - var setup = Assert.IsType(frame); - Assert.Equal("7a7e6a4f", setup.SessionId); - Assert.Equal("v2:abc", setup.CallSid); - Assert.Equal("v2:abc", setup.CallControlId); - Assert.Equal("ff55a038", setup.ConversationSessionId); - Assert.Equal("+13122010094", setup.From); - Assert.Equal("+13122123456", setup.To); - Assert.Equal("customer_123", setup.CustomParameters!["customer_id"]); - } - - [Fact] - public void APromptFrame_ReadsTheTranscriptAndTheFinalFlag() - { - const string Json = - """{"type":"prompt","voicePrompt":"hello there how are you","lang":"en","last":true}"""; - - Assert.True(Read(Json, out var frame, out _)); - - var prompt = Assert.IsType(frame); - Assert.Equal("hello there how are you", prompt.VoicePrompt); - Assert.Equal("en", prompt.Lang); - Assert.True(prompt.Last); - } - - [Fact] - public void AnInterruptFrame_ReadsTheHeardTextAndTheDurationInMilliseconds() - { - // Section 7.1 first printed a TimeSpan here. The wire carries an integer of milliseconds. - const string Json = - """ + Assert.True(Read(Json, out RelayFrame? frame, out _)); + + RelayFrame.Setup setup = Assert.IsType(frame); + Assert.Equal("7a7e6a4f", setup.SessionId); + Assert.Equal("v2:abc", setup.CallSid); + Assert.Equal("v2:abc", setup.CallControlId); + Assert.Equal("ff55a038", setup.ConversationSessionId); + Assert.Equal("+13122010094", setup.From); + Assert.Equal("+13122123456", setup.To); + Assert.Equal("customer_123", setup.CustomParameters!["customer_id"]); + } + + [Fact] + public void APromptFrame_ReadsTheTranscriptAndTheFinalFlag() + { + const string Json = + /*lang=json,strict*/ + """{"type":"prompt","voicePrompt":"hello there how are you","lang":"en","last":true}"""; + + Assert.True(Read(Json, out RelayFrame? frame, out _)); + + RelayFrame.Prompt prompt = Assert.IsType(frame); + Assert.Equal("hello there how are you", prompt.VoicePrompt); + Assert.Equal("en", prompt.Lang); + Assert.True(prompt.Last); + } + + [Fact] + public void AnInterruptFrame_ReadsTheHeardTextAndTheDurationInMilliseconds() + { + // Section 7.1 first printed a TimeSpan here. The wire carries an integer of milliseconds. + const string Json = + /*lang=json,strict*/ + """ {"type":"interrupt","utteranceUntilInterrupt":"Welcome to Telnyx, how can I help", "durationUntilInterruptMs":1820} """; - Assert.True(Read(Json, out var frame, out _)); - - var interrupt = Assert.IsType(frame); - Assert.Equal("Welcome to Telnyx, how can I help", interrupt.UtteranceUntilInterrupt); - Assert.Equal(1820, interrupt.DurationUntilInterruptMs); - } - - [Fact] - public void ADtmfFrame_ReadsTheSingleDigit() - { - Assert.True(Read("""{"type":"dtmf","digit":"1"}""", out var frame, out _)); - Assert.Equal("1", Assert.IsType(frame).Digit); - } - - [Fact] - public void AnErrorFrame_ReadsTheDescription() - { - const string Json = - """{"type":"error","description":"Invalid message: missing required field: token"}"""; - - Assert.True(Read(Json, out var frame, out _)); - Assert.StartsWith("Invalid message", Assert.IsType(frame).Description); - } - - // ------------------------------------------------------------------------------------------- - // What the reader refuses, and how. It never throws on vendor input. - // ------------------------------------------------------------------------------------------- - - [Fact] - public void AnUnknownType_IsRefusedAndNamed() - { - // A vendor that adds a frame must not be able to drop a conversation. Section 7.1. - Assert.False(Read("""{"type":"whisper","text":"x"}""", out var frame, out var unknown)); - Assert.Null(frame); - Assert.Equal("whisper", unknown); - } - - [Fact] - public void AMalformedBody_IsRefusedAndThrowsNothing() - { - Assert.False(Read("{ this is not JSON", out var frame, out var unknown, out var refused)); - Assert.Null(frame); - Assert.Null(unknown); - Assert.Null(refused); - } - - [Fact] - public void ADecimalInterruptDuration_IsARefusedBodyAndNotAnUnreadableFrame() - { - // The wire carries an integer of milliseconds, and the record binds one. A vendor that - // starts sending 1820.5 must not thereby end a conversation at the exact moment of a barge-in, so - // the type is named on refusedType and the caller keeps the socket. Section 7.1. - const string Json = - """ + Assert.True(Read(Json, out RelayFrame? frame, out _)); + + RelayFrame.Interrupt interrupt = Assert.IsType(frame); + Assert.Equal("Welcome to Telnyx, how can I help", interrupt.UtteranceUntilInterrupt); + Assert.Equal(1820, interrupt.DurationUntilInterruptMs); + } + + [Fact] + public void ADtmfFrame_ReadsTheSingleDigit() + { + Assert.True(Read(/*lang=json,strict*/ """{"type":"dtmf","digit":"1"}""", out RelayFrame? frame, out _)); + Assert.Equal("1", Assert.IsType(frame).Digit); + } + + [Fact] + public void AnErrorFrame_ReadsTheDescription() + { + const string Json = + /*lang=json,strict*/ + """{"type":"error","description":"Invalid message: missing required field: token"}"""; + + Assert.True(Read(Json, out RelayFrame? frame, out _)); + Assert.StartsWith("Invalid message", Assert.IsType(frame).Description); + } + + // ------------------------------------------------------------------------------------------- + // What the reader refuses, and how. It never throws on vendor input. + // ------------------------------------------------------------------------------------------- + + [Fact] + public void AnUnknownType_IsRefusedAndNamed() + { + // A vendor that adds a frame must not be able to drop a conversation. Section 7.1. + Assert.False(Read(/*lang=json,strict*/ """{"type":"whisper","text":"x"}""", out RelayFrame? frame, out string? unknown)); + Assert.Null(frame); + Assert.Equal("whisper", unknown); + } + + [Fact] + public void AMalformedBody_IsRefusedAndThrowsNothing() + { + Assert.False(Read("{ this is not JSON", out RelayFrame? frame, out string? unknown, out string? refused)); + Assert.Null(frame); + Assert.Null(unknown); + Assert.Null(refused); + } + + [Fact] + public void ADecimalInterruptDuration_IsARefusedBodyAndNotAnUnreadableFrame() + { + // The wire carries an integer of milliseconds, and the record binds one. A vendor that + // starts sending 1820.5 must not thereby end a conversation at the exact moment of a barge-in, so + // the type is named on refusedType and the caller keeps the socket. Section 7.1. + const string Json = + /*lang=json,strict*/ + """ {"type":"interrupt","utteranceUntilInterrupt":"Welcome to Telnyx, how can I help", "durationUntilInterruptMs":1820.5} """; - Assert.False(Read(Json, out var frame, out var unknown, out var refused)); - Assert.Null(frame); - Assert.Null(unknown); - Assert.Equal("interrupt", refused); - } - - [Fact] - public void ANonStringCustomParameter_IsARefusedBodyAndNotAnUnreadableFrame() - { - // customParameters binds to a dictionary of strings, and the host chooses what goes in it. - // A number there would otherwise end the conversation on the setup frame, before it ever began. - const string Json = - """ + Assert.False(Read(Json, out RelayFrame? frame, out string? unknown, out string? refused)); + Assert.Null(frame); + Assert.Null(unknown); + Assert.Equal("interrupt", refused); + } + + [Fact] + public void ANonStringCustomParameter_IsARefusedBodyAndNotAnUnreadableFrame() + { + // customParameters binds to a dictionary of strings, and the host chooses what goes in it. + // A number there would otherwise end the conversation on the setup frame, before it ever began. + const string Json = + /*lang=json,strict*/ + """ {"type":"setup","sessionId":"7a7e6a4f","callSid":"v2:abc","callControlId":"v2:abc", "conversationSessionId":"ff55a038","from":"+13122010094","to":"+13122123456", "customParameters":{"a":7}} """; - Assert.False(Read(Json, out var frame, out var unknown, out var refused)); - Assert.Null(frame); - Assert.Null(unknown); - Assert.Equal("setup", refused); - } - - [Fact] - public void AnUnmodelledType_NamesUnknownTypeAndNeverRefusedType() - { - // The two names answer different questions, and a caller acts differently on each: an - // unmodelled type is a frame from a later version of the vendor, and a refused body is a - // field of a frame this build already knows. - Assert.False(Read("""{"type":"whisper","text":"x"}""", out _, out var unknown, out var refused)); - Assert.Equal("whisper", unknown); - Assert.Null(refused); - } - - [Fact] - public void AFrameWithNoType_IsRefused() - { - Assert.False(Read("""{"voicePrompt":"hi","last":true}""", out var frame, out _)); - Assert.Null(frame); - } - - [Fact] - public void ATypeThatIsNotFirst_IsStillRead() - { - // Nothing in the vendor contract promises the discriminator comes first, and this is one - // reason the reader switches by hand instead of using polymorphic deserialization. - Assert.True(Read("""{"digit":"5","type":"dtmf"}""", out var frame, out _)); - Assert.Equal("5", Assert.IsType(frame).Digit); - } - - [Fact] - public void AnEmptyBody_IsRefusedAndThrowsNothing() - { - Assert.False(Read(string.Empty, out var frame, out var unknown)); - Assert.Null(frame); - Assert.Null(unknown); - } - - [Fact] - public void AJsonArray_IsRefusedAndThrowsNothing() - { - // Valid JSON, but not an object, so there is no "type" field to read. - Assert.False(Read("[1,2,3]", out var frame, out var unknown)); - Assert.Null(frame); - Assert.Null(unknown); - } - - [Fact] - public void ATypeFieldThatIsNotAString_IsRefusedAndThrowsNothing() - { - Assert.False(Read("""{"type":123}""", out var frame, out var unknown)); - Assert.Null(frame); - Assert.Null(unknown); - } - - [Fact] - public void TrailingBytesAfterACompleteObject_AreToleratedNotRejected() - { - // JsonDocument.ParseValue reads only the first complete JSON value and leaves the rest of - // the buffer unread, so it does not throw on the trailing text and the reader accepts the - // frame it did parse. This documents that behaviour; the reader does not reject it. - Assert.True(Read("""{"type":"dtmf","digit":"1"} extra garbage""", out var frame, out _)); - Assert.Equal("1", Assert.IsType(frame).Digit); + Assert.False(Read(Json, out RelayFrame? frame, out string? unknown, out string? refused)); + Assert.Null(frame); + Assert.Null(unknown); + Assert.Equal("setup", refused); + } + + [Fact] + public void AnUnmodelledType_NamesUnknownTypeAndNeverRefusedType() + { + // The two names answer different questions, and a caller acts differently on each: an + // unmodelled type is a frame from a later version of the vendor, and a refused body is a + // field of a frame this build already knows. + Assert.False(Read(/*lang=json,strict*/ """{"type":"whisper","text":"x"}""", out _, out string? unknown, out string? refused)); + Assert.Equal("whisper", unknown); + Assert.Null(refused); + } + + [Fact] + public void AFrameWithNoType_IsRefused() + { + Assert.False(Read(/*lang=json,strict*/ """{"voicePrompt":"hi","last":true}""", out RelayFrame? frame, out _)); + Assert.Null(frame); + } + + [Fact] + public void ATypeThatIsNotFirst_IsStillRead() + { + // Nothing in the vendor contract promises the discriminator comes first, and this is one + // reason the reader switches by hand instead of using polymorphic deserialization. + Assert.True(Read(/*lang=json,strict*/ """{"digit":"5","type":"dtmf"}""", out RelayFrame? frame, out _)); + Assert.Equal("5", Assert.IsType(frame).Digit); + } + + [Fact] + public void AnEmptyBody_IsRefusedAndThrowsNothing() + { + Assert.False(Read(string.Empty, out RelayFrame? frame, out string? unknown)); + Assert.Null(frame); + Assert.Null(unknown); + } + + [Fact] + public void AJsonArray_IsRefusedAndThrowsNothing() + { + // Valid JSON, but not an object, so there is no "type" field to read. + Assert.False(Read("[1,2,3]", out RelayFrame? frame, out string? unknown)); + Assert.Null(frame); + Assert.Null(unknown); + } + + [Fact] + public void ATypeFieldThatIsNotAString_IsRefusedAndThrowsNothing() + { + Assert.False(Read(/*lang=json,strict*/ """{"type":123}""", out RelayFrame? frame, out string? unknown)); + Assert.Null(frame); + Assert.Null(unknown); + } + + [Fact] + public void TrailingBytesAfterACompleteObject_AreToleratedNotRejected() + { + // JsonDocument.ParseValue reads only the first complete JSON value and leaves the rest of + // the buffer unread, so it does not throw on the trailing text and the reader accepts the + // frame it did parse. This documents that behaviour; the reader does not reject it. + Assert.True(Read("""{"type":"dtmf","digit":"1"} extra garbage""", out RelayFrame? frame, out _)); + Assert.Equal("1", Assert.IsType(frame).Digit); + } + + // ------------------------------------------------------------------------------------------- + // The outbound wire, so a future change to Type cannot silently drop the discriminator. + // ------------------------------------------------------------------------------------------- + + [Fact] + public void ARelayToken_SerializesWithTheTextDiscriminator() + { + string json = JsonSerializer.Serialize(new RelayToken("hello", Last: true), TelnyxRelayJson.Options); + + Assert.Contains("\"type\":\"text\"", json); + Assert.Contains("\"token\":\"hello\"", json); + Assert.Contains("\"last\":true", json); + } + + private static bool Read(string json, out RelayFrame? frame, out string? unknownType) + { + return Read(json, out frame, out unknownType, out _); + } + + private static bool Read(string json, out RelayFrame? frame, out string? unknownType, out string? refusedType) + { + return TelnyxRelayFrameReader.TryRead( + Encoding.UTF8.GetBytes(json), out frame, out unknownType, out refusedType); + } } - - // ------------------------------------------------------------------------------------------- - // The outbound wire, so a future change to Type cannot silently drop the discriminator. - // ------------------------------------------------------------------------------------------- - - [Fact] - public void ARelayToken_SerializesWithTheTextDiscriminator() - { - var json = JsonSerializer.Serialize(new RelayToken("hello", Last: true), TelnyxRelayJson.Options); - - Assert.Contains("\"type\":\"text\"", json); - Assert.Contains("\"token\":\"hello\"", json); - Assert.Contains("\"last\":true", json); - } - - private static bool Read(string json, out RelayFrame? frame, out string? unknownType) - => Read(json, out frame, out unknownType, out _); - - private static bool Read(string json, out RelayFrame? frame, out string? unknownType, out string? refusedType) - => TelnyxRelayFrameReader.TryRead( - Encoding.UTF8.GetBytes(json), out frame, out unknownType, out refusedType); } diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayTurnTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayTurnTests.cs index 86957bcc..2a3fb3a5 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayTurnTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayTurnTests.cs @@ -1,21 +1,21 @@ -using AgentCore.TestSupport; using AgentCore.AspNetCore.Tests.Fakes; using Microsoft.Extensions.Logging; using Xunit; +using AgentCore.Application.Runtime; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// One relay socket runs one conversation, and one final prompt runs one turn. -/// -/// -/// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, -/// no network conversation, and no API key anywhere in this file. -/// -public sealed class TelnyxRelayTurnTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - internal const string PolicyYaml = - """ + /// + /// One relay socket runs one conversation, and one final prompt runs one turn. + /// + /// + /// Every test here runs offline against a fake model and a fake relay. There is no Telnyx account, + /// no network conversation, and no API key anywhere in this file. + /// + public sealed class TelnyxRelayTurnTests + { + internal const string PolicyYaml = + """ apiVersion: agentcore/v1 agents: defaults: @@ -34,397 +34,408 @@ public sealed class TelnyxRelayTurnTests agent: greeter """; - // ------------------------------------------------------------------------------------------- - // The happy path. - // ------------------------------------------------------------------------------------------- - - [Fact] - public async Task AFinalPrompt_RunsOneTurnAndSendsOneTextFrameForEachUpdate() - { - using FragmentingChatClient reply = new("hello there caller"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); + // ------------------------------------------------------------------------------------------- + // The happy path. + // ------------------------------------------------------------------------------------------- - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - - var tokens = await relay.ReadTextFramesUntilLastAsync(); + [Fact] + public async Task AFinalPrompt_RunsOneTurnAndSendsOneTextFrameForEachUpdate() + { + using FragmentingChatClient reply = new("hello there caller"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); - Assert.True(tokens.Count > 1, "the reply must stream, not arrive as one frame."); - Assert.Equal("hello there caller", string.Concat(tokens)); - } + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - [Fact] - public async Task ASetupFrame_NamesTheConversationAfterTheConversationSessionId() - { - // conversationSessionId groups the legs of one logical conversation, so it survives the warm transfer of - // slice 2. A leg id would not. - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); - - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "logical-conversation-7")); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - await relay.ReadTextFramesUntilLastAsync(); - - var session = await host.FindSessionAsync("logical-conversation-7"); - Assert.NotNull(session); - Assert.Equal("logical-conversation-7", session.ConversationId); - } + List tokens = await relay.ReadTextFramesUntilLastAsync(); - // ------------------------------------------------------------------------------------------- - // The rule this task exists for: the read loop never waits for the turn. - // ------------------------------------------------------------------------------------------- + Assert.True(tokens.Count > 1, "the reply must stream, not arrive as one frame."); + Assert.Equal("hello there caller", string.Concat(tokens)); + } - [Fact(Timeout = 30_000)] - public async Task AFurtherFrame_ReachesTheConnectionWhileTheReplyIsStillStreaming() - { - // A read loop that awaited RunTurnStreamingAsync directly, rather than starting it and - // moving on, could not call ReceiveAsync again until the reply finished. The dtmf frame - // below is sent, and observed to have landed, before the gate on the reply is ever - // released — so a read loop that blocked on the turn would leave the "await capture" line - // hanging rather than let this test finish. Dtmf carries no barge-in logic of its own, so - // this proves only the rule this task owns, and nothing Task 6 will add. - // - // No test in this project carries a timeout, so TestContext.Current.CancellationToken never - // fires on its own for one test. The ten-second deadline below is this test's own backstop, - // and the [Fact(Timeout)] above is the second one in case that backstop itself never runs. - // reply.Release() lives in a finally so a failed assertion above still opens the gate, - // rather than leaving the server's turn blocked for the rest of the host's shutdown timeout. - using BlockingChatClient reply = new("hello there caller"); - DtmfObservedLoggerProvider capture = new(); - await using var host = await TelnyxRelayHost.StartAsync( - PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - try + [Fact] + public async Task ASetupFrame_NamesTheConversationAfterTheConversationSessionId() { - await relay.SendAsync(RelayFrames.Setup()); + // conversationSessionId groups the legs of one logical conversation, so it survives the warm transfer of + // slice 2. A leg id would not. + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "logical-conversation-7")); await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + _ = await relay.ReadTextFramesUntilLastAsync(); - // The gate opens right after the first fragment leaves, so the turn is still streaming - // here. - try - { - await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the reply never started streaming within ten seconds."); - } + ConversationSession? session = await host.FindSessionAsync("logical-conversation-7"); + Assert.NotNull(session); + Assert.Equal("logical-conversation-7", session.ConversationId); + } - await relay.SendAsync(RelayFrames.Dtmf("5")); + // ------------------------------------------------------------------------------------------- + // The rule this task exists for: the read loop never waits for the turn. + // ------------------------------------------------------------------------------------------- + + [Fact(Timeout = 30_000)] + public async Task AFurtherFrame_ReachesTheConnectionWhileTheReplyIsStillStreaming() + { + // A read loop that awaited RunTurnStreamingAsync directly, rather than starting it and + // moving on, could not call ReceiveAsync again until the reply finished. The dtmf frame + // below is sent, and observed to have landed, before the gate on the reply is ever + // released — so a read loop that blocked on the turn would leave the "await capture" line + // hanging rather than let this test finish. Dtmf carries no barge-in logic of its own, so + // this proves only the rule this task owns, and nothing Task 6 will add. + // + // No test in this project carries a timeout, so TestContext.Current.CancellationToken never + // fires on its own for one test. The ten-second deadline below is this test's own backstop, + // and the [Fact(Timeout)] above is the second one in case that backstop itself never runs. + // reply.Release() lives in a finally so a failed assertion above still opens the gate, + // rather than leaving the server's turn blocked for the rest of the host's shutdown timeout. + using BlockingChatClient reply = new("hello there caller"); + DtmfObservedLoggerProvider capture = new(); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); try { - await capture.Observed.WaitAsync(bounded.Token); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + // The gate opens right after the first fragment leaves, so the turn is still streaming + // here. + try + { + await reply.WaitUntilStreamingAsync().WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the reply never started streaming within ten seconds."); + } + + await relay.SendAsync(RelayFrames.Dtmf("5")); + + try + { + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail( + "the connection never logged that a digit arrived within ten seconds; the read " + + "loop may be blocked on the turn."); + } } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + finally { - Assert.Fail( - "the connection never logged that a digit arrived within ten seconds; the read " - + "loop may be blocked on the turn."); + reply.Release(); } - } - finally - { - reply.Release(); - } - var tokens = await relay.ReadTextFramesUntilLastAsync(); - Assert.Equal("hello there caller", string.Concat(tokens)); - } + List tokens = await relay.ReadTextFramesUntilLastAsync(); + Assert.Equal("hello there caller", string.Concat(tokens)); + } - // ------------------------------------------------------------------------------------------- - // What the read loop must survive. - // ------------------------------------------------------------------------------------------- + // ------------------------------------------------------------------------------------------- + // What the read loop must survive. + // ------------------------------------------------------------------------------------------- - [Fact] - public async Task AnInterimPrompt_RunsNoTurn() - { - // The relay sends many interim transcripts per turn. One turn per partial word would run - // the model many times over and speak nonsense. - // - // Conversations == 1 alone would not catch a reader that started a turn on every prompt frame: the - // later interim prompts would then hit the in-flight guard and be dropped for the wrong - // reason, and Calls would still read 1. Asserting on the text the model actually saw is - // what tells the two apart — the model must see the final transcript, never an interim one. - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); - - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendAsync(RelayFrames.Prompt("hel", last: false)); - await relay.SendAsync(RelayFrames.Prompt("hello th", last: false)); - await relay.SendAsync(RelayFrames.Prompt("hello there", last: true)); - - await relay.ReadTextFramesUntilLastAsync(); - - Assert.Equal(1, reply.Calls); - Assert.NotNull(reply.LastRequest); - Assert.Contains(reply.LastRequest!, message => message.Text == "hello there"); - } + [Fact] + public async Task AnInterimPrompt_RunsNoTurn() + { + // The relay sends many interim transcripts per turn. One turn per partial word would run + // the model many times over and speak nonsense. + // + // Conversations == 1 alone would not catch a reader that started a turn on every prompt frame: the + // later interim prompts would then hit the in-flight guard and be dropped for the wrong + // reason, and Calls would still read 1. Asserting on the text the model actually saw is + // what tells the two apart — the model must see the final transcript, never an interim one. + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); - [Fact] - public async Task APromptSplitAcrossThreeFragments_ArrivesAsOneFrame() - { - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Prompt("hel", last: false)); + await relay.SendAsync(RelayFrames.Prompt("hello th", last: false)); + await relay.SendAsync(RelayFrames.Prompt("hello there", last: true)); - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendFragmentedAsync(RelayFrames.Prompt("hi", last: true), fragments: 3); + _ = await relay.ReadTextFramesUntilLastAsync(); - var tokens = await relay.ReadTextFramesUntilLastAsync(); - Assert.Equal("hello", string.Concat(tokens)); - } + Assert.Equal(1, reply.Calls); + Assert.NotNull(reply.LastRequest); + Assert.Contains(reply.LastRequest!, message => message.Text == "hello there"); + } - [Fact] - public async Task AnUnknownFrameType_IsIgnoredAndTheConversationGoesOn() - { - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); + [Fact] + public async Task APromptSplitAcrossThreeFragments_ArrivesAsOneFrame() + { + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendRawAsync("""{"type":"whisper","text":"a frame from next year"}"""); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendFragmentedAsync(RelayFrames.Prompt("hi", last: true), fragments: 3); - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync())); - } + List tokens = await relay.ReadTextFramesUntilLastAsync(); + Assert.Equal("hello", string.Concat(tokens)); + } - [Fact(Timeout = 30_000)] - public async Task ADecimalDurationOnAnInterruptFrame_IsRefusedAndTheConversationGoesOn() - { - // Section 7.1: a vendor that changes a frame must not be able to drop a conversation. The type is - // known and only one field will not bind, so the frame is refused and the socket lives. - // A decimal here would otherwise end a live conversation at the exact moment of a barge-in. - using FragmentingChatClient reply = new("hello"); - EventObservedLoggerProvider capture = new("FrameBodyRefused"); - await using var host = await TelnyxRelayHost.StartAsync( - PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendRawAsync( - """{"type":"interrupt","utteranceUntilInterrupt":"hello","durationUntilInterruptMs":1820.5}"""); - - try + [Fact] + public async Task AnUnknownFrameType_IsIgnoredAndTheConversationGoesOn() { - await capture.Observed.WaitAsync(bounded.Token); + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendRawAsync(/*lang=json,strict*/ """{"type":"whisper","text":"a frame from next year"}"""); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync())); } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + + [Fact(Timeout = 30_000)] + public async Task ADecimalDurationOnAnInterruptFrame_IsRefusedAndTheConversationGoesOn() { - Assert.Fail("the connection never reported refusing the frame body within ten seconds."); - } + // Section 7.1: a vendor that changes a frame must not be able to drop a conversation. The type is + // known and only one field will not bind, so the frame is refused and the socket lives. + // A decimal here would otherwise end a live conversation at the exact moment of a barge-in. + using FragmentingChatClient reply = new("hello"); + EventObservedLoggerProvider capture = new("FrameBodyRefused"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - Assert.Equal(LogLevel.Warning, capture.Level); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendRawAsync( + /*lang=json,strict*/ + """{"type":"interrupt","utteranceUntilInterrupt":"hello","durationUntilInterruptMs":1820.5}"""); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + try + { + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported refusing the frame body within ten seconds."); + } - try - { - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the turn after the refused frame never finished within ten seconds."); + Assert.Equal(LogLevel.Warning, capture.Level); + + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + try + { + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the turn after the refused frame never finished within ten seconds."); + } } - } - [Fact(Timeout = 30_000)] - public async Task ANonStringCustomParameterOnASetupFrame_IsRefusedAndTheConversationGoesOn() - { - // The same rule, on the one frame that starts a conversation. customParameters binds to a - // dictionary of strings, so a number in it will not bind, and refusing the whole socket - // would kill the conversation before it ever began. - using FragmentingChatClient reply = new("hello"); - EventObservedLoggerProvider capture = new("FrameBodyRefused"); - await using var host = await TelnyxRelayHost.StartAsync( - PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await relay.SendRawAsync( - """ + [Fact(Timeout = 30_000)] + public async Task ANonStringCustomParameterOnASetupFrame_IsRefusedAndTheConversationGoesOn() + { + // The same rule, on the one frame that starts a conversation. customParameters binds to a + // dictionary of strings, so a number in it will not bind, and refusing the whole socket + // would kill the conversation before it ever began. + using FragmentingChatClient reply = new("hello"); + EventObservedLoggerProvider capture = new("FrameBodyRefused"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + await relay.SendRawAsync( + /*lang=json,strict*/ + """ {"type":"setup","sessionId":"session-one","callSid":"v2:leg-one", "callControlId":"v2:leg-one","conversationSessionId":"conversation-bad-parameters","callLegId":"leg-one", "from":"+13122010094","to":"+13122123456","direction":"inbound", "customParameters":{"a":7},"conversationStatus":"active"} """); - try - { - await capture.Observed.WaitAsync(bounded.Token); + try + { + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported refusing the setup body within ten seconds."); + } + + // The socket is still usable, which is the whole point: the vendor gets another chance. + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-after-bad-setup")); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + + try + { + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the turn after the refused setup never finished within ten seconds."); + } } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + + [Fact] + public async Task AnErrorFrame_KeepsTheSocketOpen() { - Assert.Fail("the connection never reported refusing the setup body within ten seconds."); - } + // This frame reports our defect, not a conversation fault. Dropping the conversation would be worse. + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); - // The socket is still usable, which is the whole point: the vendor gets another chance. - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-after-bad-setup")); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + await relay.SendAsync(RelayFrames.Setup()); + await relay.SendAsync(RelayFrames.Error("Invalid message: missing required field: token")); + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - try - { - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync())); } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + + [Fact(Timeout = 30_000)] + public async Task ASecondSetupFrame_ReplacesTheFirstSessionAndReleasesIt() { - Assert.Fail("the turn after the refused setup never finished within ten seconds."); - } - } + // One socket carries one conversation, so a second setup frame is the vendor's defect. Section 7.1 + // still forbids dropping a conversation over one, so it replaces rather than refuses. Teardown only + // ever closes the session the connection currently holds, so a first session left behind + // would never have anything wait for the words it still owed store 1. + using FragmentingChatClient reply = new("hello"); + EventObservedLoggerProvider capture = new("SecondSetupFrame"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync( + PolicyYaml, + reply, + logging: logging => logging.AddProvider(capture)); + await using FakeRelayClient relay = await host.ConnectAsync(); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-first")); + await host.WaitForSessionAsync("conversation-first"); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-second")); - [Fact] - public async Task AnErrorFrame_KeepsTheSocketOpen() - { - // This frame reports our defect, not a conversation fault. Dropping the conversation would be worse. - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); + try + { + await capture.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the second setup frame within ten seconds."); + } - await relay.SendAsync(RelayFrames.Setup()); - await relay.SendAsync(RelayFrames.Error("Invalid message: missing required field: token")); - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); + await host.WaitForSessionAsync("conversation-second"); + Assert.Null(await host.FindSessionAsync("conversation-first")); - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync())); - } + // The conversation itself goes on, on the session the vendor's latest word named. + await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - [Fact(Timeout = 30_000)] - public async Task ASecondSetupFrame_ReplacesTheFirstSessionAndReleasesIt() - { - // One socket carries one conversation, so a second setup frame is the vendor's defect. Section 7.1 - // still forbids dropping a conversation over one, so it replaces rather than refuses. Teardown only - // ever closes the session the connection currently holds, so a first session left behind - // would never have anything wait for the words it still owed store 1. - using FragmentingChatClient reply = new("hello"); - EventObservedLoggerProvider capture = new("SecondSetupFrame"); - await using var host = await TelnyxRelayHost.StartAsync( - PolicyYaml, - reply, - logging: logging => logging.AddProvider(capture)); - await using var relay = await host.ConnectAsync(); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-first")); - await host.WaitForSessionAsync("conversation-first"); - - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-second")); - - try - { - await capture.Observed.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never reported the second setup frame within ten seconds."); + try + { + Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the turn after the second setup frame never finished within ten seconds."); + } } - await host.WaitForSessionAsync("conversation-second"); - Assert.Null(await host.FindSessionAsync("conversation-first")); + // ------------------------------------------------------------------------------------------- + // What teardown does. + // ------------------------------------------------------------------------------------------- - // The conversation itself goes on, on the session the vendor's latest word named. - await relay.SendAsync(RelayFrames.Prompt("hi", last: true)); - - try - { - Assert.Equal("hello", string.Concat(await relay.ReadTextFramesUntilLastAsync().WaitAsync(bounded.Token))); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + [Fact(Timeout = 30_000)] + public async Task ARelayThatVanishesWithNoCloseFrame_ReleasesTheSession() { - Assert.Fail("the turn after the second setup frame never finished within ten seconds."); + // The vendor never reconnects, so a dead socket is a finished conversation. Abort sends no close + // frame at all, so this is what proves the read loop unblocks on the connection's own + // cancellation rather than on the close handshake, and that the session store drops the + // call once it does. WaitForSessionAsync first makes sure the server actually created the + // session before the abort below, so a pass here proves removal and not merely the absence + // of something that was never added. + using FragmentingChatClient reply = new("hello"); + await using TelnyxRelayHost host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); + await using FakeRelayClient relay = await host.ConnectAsync(); + + await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-dropped")); + await host.WaitForSessionAsync("conversation-dropped"); + + relay.Abort(); + + await host.WaitForConversationEndAsync("conversation-dropped"); + Assert.Null(await host.FindSessionAsync("conversation-dropped")); } } - // ------------------------------------------------------------------------------------------- - // What teardown does. - // ------------------------------------------------------------------------------------------- - - [Fact(Timeout = 30_000)] - public async Task ARelayThatVanishesWithNoCloseFrame_ReleasesTheSession() + /// + /// Completes once the connection writes the "the caller pressed a key" line. + /// + /// + /// Matched by rather than its numeric id, because the numeric id is not + /// a value a test should depend on. This is the only signal a dtmf frame leaves behind — the digit + /// itself never reaches a log line — so it is also the only way a test can prove the connection + /// read the frame at all. + /// + internal sealed class DtmfObservedLoggerProvider : ILoggerProvider { - // The vendor never reconnects, so a dead socket is a finished conversation. Abort sends no close - // frame at all, so this is what proves the read loop unblocks on the connection's own - // cancellation rather than on the close handshake, and that the session store drops the - // call once it does. WaitForSessionAsync first makes sure the server actually created the - // session before the abort below, so a pass here proves removal and not merely the absence - // of something that was never added. - using FragmentingChatClient reply = new("hello"); - await using var host = await TelnyxRelayHost.StartAsync(PolicyYaml, reply); - await using var relay = await host.ConnectAsync(); - - await relay.SendAsync(RelayFrames.Setup(conversationSessionId: "conversation-dropped")); - await host.WaitForSessionAsync("conversation-dropped"); - - relay.Abort(); - - await host.WaitForConversationEndAsync("conversation-dropped"); - Assert.Null(await host.FindSessionAsync("conversation-dropped")); - } -} + private readonly TaskCompletionSource _observed = new(TaskCreationOptions.RunContinuationsAsynchronously); -/// -/// Completes once the connection writes the "the caller pressed a key" line. -/// -/// -/// Matched by rather than its numeric id, because the numeric id is not -/// a value a test should depend on. This is the only signal a dtmf frame leaves behind — the digit -/// itself never reaches a log line — so it is also the only way a test can prove the connection -/// read the frame at all. -/// -internal sealed class DtmfObservedLoggerProvider : ILoggerProvider -{ - private readonly TaskCompletionSource _observed = new(TaskCreationOptions.RunContinuationsAsynchronously); + /// Gets a task that completes once the connection logs that a digit arrived. + public Task Observed => _observed.Task; - /// Gets a task that completes once the connection logs that a digit arrived. - public Task Observed => _observed.Task; - - public ILogger CreateLogger(string categoryName) => new Logger(_observed); + public ILogger CreateLogger(string categoryName) + { + return new Logger(_observed); + } - public void Dispose() - { - // Nothing to release. - } + public void Dispose() + { + // Nothing to release. + } - private sealed class Logger(TaskCompletionSource observed) : ILogger - { - public IDisposable? BeginScope(TState state) - where TState : notnull - => null; - - public bool IsEnabled(LogLevel logLevel) => true; - - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + private sealed class Logger(TaskCompletionSource observed) : ILogger { - if (eventId.Name == "DtmfReceived") + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } + + public bool IsEnabled(LogLevel logLevel) + { + return true; + } + + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) { - observed.TrySetResult(); + if (eventId.Name == "DtmfReceived") + { + _ = observed.TrySetResult(); + } } } } diff --git a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayWriteLoopTests.cs b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayWriteLoopTests.cs index ccfc3f11..3fb67fcc 100644 --- a/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayWriteLoopTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Vendors/TelnyxRelay/TelnyxRelayWriteLoopTests.cs @@ -1,209 +1,209 @@ -using AgentCore.TestSupport; using System.Net.WebSockets; using System.Text.Json; using AgentCore.AspNetCore.Tests.Fakes; using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay; - -/// -/// What the write loop does that no real socket lets a test watch. -/// -/// -/// Every test here drives TelnyxRelayConnection.RunAsync over . -/// There is no Kestrel, no port, and no client socket. Everything else about the connection is the -/// real thing, including the session factory and the store AddAgentCore registers. -/// -public sealed class TelnyxRelayWriteLoopTests +namespace AgentCore.AspNetCore.Tests.Vendors.TelnyxRelay { - [Fact(Timeout = 30_000)] - public async Task AnItemParkedBetweenTheDequeueAndTheGate_NeverReachesTheSocket() + /// + /// What the write loop does that no real socket lets a test watch. + /// + /// + /// Every test here drives TelnyxRelayConnection.RunAsync over . + /// There is no Kestrel, no port, and no client socket. Everything else about the connection is the + /// real thing, including the session factory and the store AddAgentCore registers. + /// + public sealed class TelnyxRelayWriteLoopTests { - // This is the fix that closed an earlier Critical, and it is the one place a real socket - // cannot reach: the window between the write loop taking an item off the channel and the - // turn-id comparison in front of its one SendAsync call. HandleInterrupt's own drain cannot - // help here, because the item has already left the channel by the time the drain runs. Only - // the gate can stop it, so deleting the gate must turn this test red. - using BlockingChatClient reply = new("first second third"); - EventObservedLoggerProvider interrupted = new("InterruptReceived"); - await using var harness = await RelayConnectionHarness.StartAsync( - TelnyxRelayTurnTests.PolicyYaml, - reply, - logging => logging.AddProvider(interrupted)); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - // Armed before the first frame, because the write loop reads State for the first time only - // once a turn has actually queued something. - harness.Socket.ParkNextStateRead(); - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-gate")); - harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); - - try + [Fact(Timeout = 30_000)] + public async Task AnItemParkedBetweenTheDequeueAndTheGate_NeverReachesTheSocket() { + // This is the fix that closed an earlier Critical, and it is the one place a real socket + // cannot reach: the window between the write loop taking an item off the channel and the + // turn-id comparison in front of its one SendAsync call. HandleInterrupt's own drain cannot + // help here, because the item has already left the channel by the time the drain runs. Only + // the gate can stop it, so deleting the gate must turn this test red. + using BlockingChatClient reply = new("first second third"); + EventObservedLoggerProvider interrupted = new("InterruptReceived"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync( + TelnyxRelayTurnTests.PolicyYaml, + reply, + logging => logging.AddProvider(interrupted)); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + // Armed before the first frame, because the write loop reads State for the first time only + // once a turn has actually queued something. + harness.Socket.ParkNextStateRead(); + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-gate")); + harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); + try { - await harness.Socket.Parked.WaitAsync(bounded.Token); + try + { + await harness.Socket.Parked.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the write loop never reached its first item within ten seconds."); + } + + harness.Socket.Queue(RelayFrames.Interrupt("nothing played", durationMs: 0)); + + try + { + await interrupted.Observed.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never reported the barge-in within ten seconds."); + } } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) + finally { - Assert.Fail("the write loop never reached its first item within ten seconds."); + // Both gates are released here, so a failed assertion above still lets the write loop + // and the model finish rather than stranding a thread for the rest of the run. + harness.Socket.ReleaseParkedState(); + reply.Release(); } - harness.Socket.Queue(RelayFrames.Interrupt("nothing played", durationMs: 0)); + harness.Socket.QueueClose(); try { - await interrupted.Observed.WaitAsync(bounded.Token); + await harness.Connection.WaitAsync(bounded.Token); } catch (OperationCanceledException) when (deadline.IsCancellationRequested) { - Assert.Fail("the connection never reported the barge-in within ten seconds."); + Assert.Fail("the connection never tore down within ten seconds."); } - } - finally - { - // Both gates are released here, so a failed assertion above still lets the write loop - // and the model finish rather than stranding a thread for the rest of the run. - harness.Socket.ReleaseParkedState(); - reply.Release(); - } - - harness.Socket.QueueClose(); - try - { - await harness.Connection.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never tore down within ten seconds."); + Assert.Empty(harness.Socket.Sent); } - Assert.Empty(harness.Socket.Sent); - } + [Fact(Timeout = 30_000)] + public async Task AHostThatStops_ClosesWithEndpointUnavailable() + { + // A real socket aborts before this status can be observed on the wire, so the assertion is + // made on the arguments CloseOutputAsync was called with instead. + using FragmentingChatClient reply = new("hello"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - [Fact(Timeout = 30_000)] - public async Task AHostThatStops_ClosesWithEndpointUnavailable() - { - // A real socket aborts before this status can be observed on the wire, so the assertion is - // made on the arguments CloseOutputAsync was called with instead. - using FragmentingChatClient reply = new("hello"); - await using var harness = await RelayConnectionHarness.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-stopping")); + harness.StopApplication(); - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-stopping")); - harness.StopApplication(); + try + { + await harness.Connection.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never tore down after the host stopped, within ten seconds."); + } - try - { - await harness.Connection.WaitAsync(bounded.Token); - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never tore down after the host stopped, within ten seconds."); + (WebSocketCloseStatus Status, string? Description)? close = harness.Socket.CloseSent; + _ = Assert.NotNull(close); + Assert.Equal(WebSocketCloseStatus.EndpointUnavailable, close!.Value.Status); } - var close = harness.Socket.CloseSent; - Assert.NotNull(close); - Assert.Equal(WebSocketCloseStatus.EndpointUnavailable, close!.Value.Status); - } + [Fact(Timeout = 30_000)] + public async Task AWriteLoopThatFaults_ClosesWithInternalServerError() + { + // Nothing on a healthy loopback socket makes a send throw, so the fault is injected here. + // The status is this endpoint's own report of its own defect, and a real conversation would see it. + using FragmentingChatClient reply = new("hello there caller"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - [Fact(Timeout = 30_000)] - public async Task AWriteLoopThatFaults_ClosesWithInternalServerError() - { - // Nothing on a healthy loopback socket makes a send throw, so the fault is injected here. - // The status is this endpoint's own report of its own defect, and a real conversation would see it. - using FragmentingChatClient reply = new("hello there caller"); - await using var harness = await RelayConnectionHarness.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); + harness.Socket.FailEverySend(new InvalidOperationException("the send failed.")); + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-write-fault")); + harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); - harness.Socket.FailEverySend(new InvalidOperationException("the send failed.")); - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-write-fault")); - harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); + try + { + await harness.Connection.WaitAsync(bounded.Token); + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the connection never tore down after the write loop faulted, within ten seconds."); + } - try - { - await harness.Connection.WaitAsync(bounded.Token); + (WebSocketCloseStatus Status, string? Description)? close = harness.Socket.CloseSent; + _ = Assert.NotNull(close); + Assert.Equal(WebSocketCloseStatus.InternalServerError, close!.Value.Status); } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the connection never tore down after the write loop faulted, within ten seconds."); - } - - var close = harness.Socket.CloseSent; - Assert.NotNull(close); - Assert.Equal(WebSocketCloseStatus.InternalServerError, close!.Value.Status); - } - [Fact(Timeout = 30_000)] - public async Task ManyFragmentsInOneTurn_EachArriveIntactWhenTheWriterIsReused() - { - // A guard, not a red-first test: the behaviour it pins already holds and must keep holding. - // The write loop serializes every frame through one buffer and one JSON writer it resets - // between frames, and the only defect that reuse could introduce is a frame carrying - // another frame's bytes — a leftover tail after a short frame, a truncation, or two - // documents in one message. Three spoken fragments in one turn is the smallest reply that - // would show any of the three, and the assertions below read each frame back as JSON rather - // than counting sends, so a corrupted frame fails here instead of passing as "four sends". - using FragmentingChatClient reply = new("alpha bravo charlie"); - await using var harness = await RelayConnectionHarness.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); - - using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); - using var bounded = CancellationTokenSource.CreateLinkedTokenSource( - deadline.Token, TestContext.Current.CancellationToken); - - harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-reused-writer")); - harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); - - try + [Fact(Timeout = 30_000)] + public async Task ManyFragmentsInOneTurn_EachArriveIntactWhenTheWriterIsReused() { - // The reply closes on the empty last: true frame CompleteAsync queues, so waiting for a - // fourth send waits for the whole turn rather than timing it. Queueing the close before - // that frame arrived would cancel the turn mid-stream and cut the reply short. - while (harness.Socket.Sent.Count < 4) + // A guard, not a red-first test: the behaviour it pins already holds and must keep holding. + // The write loop serializes every frame through one buffer and one JSON writer it resets + // between frames, and the only defect that reuse could introduce is a frame carrying + // another frame's bytes — a leftover tail after a short frame, a truncation, or two + // documents in one message. Three spoken fragments in one turn is the smallest reply that + // would show any of the three, and the assertions below read each frame back as JSON rather + // than counting sends, so a corrupted frame fails here instead of passing as "four sends". + using FragmentingChatClient reply = new("alpha bravo charlie"); + await using RelayConnectionHarness harness = await RelayConnectionHarness.StartAsync(TelnyxRelayTurnTests.PolicyYaml, reply); + + using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10)); + using CancellationTokenSource bounded = CancellationTokenSource.CreateLinkedTokenSource( + deadline.Token, TestContext.Current.CancellationToken); + + harness.Socket.Queue(RelayFrames.Setup(conversationSessionId: "conversation-reused-writer")); + harness.Socket.Queue(RelayFrames.Prompt("hi", last: true)); + + try { - await Task.Delay(TimeSpan.FromMilliseconds(10), bounded.Token); + // The reply closes on the empty last: true frame CompleteAsync queues, so waiting for a + // fourth send waits for the whole turn rather than timing it. Queueing the close before + // that frame arrived would cancel the turn mid-stream and cut the reply short. + while (harness.Socket.Sent.Count < 4) + { + await Task.Delay(TimeSpan.FromMilliseconds(10), bounded.Token); + } + } + catch (OperationCanceledException) when (deadline.IsCancellationRequested) + { + Assert.Fail("the reply never reached its last frame within ten seconds."); } - } - catch (OperationCanceledException) when (deadline.IsCancellationRequested) - { - Assert.Fail("the reply never reached its last frame within ten seconds."); - } - var sent = harness.Socket.Sent; - Assert.Equal(4, sent.Count); + IReadOnlyList sent = harness.Socket.Sent; + Assert.Equal(4, sent.Count); - List tokens = []; - List lasts = []; + List tokens = []; + List lasts = []; - foreach (var frame in sent) - { - // Parsed, never substring-matched. A buffer whose written count survived a reset would - // put a leftover tail after the document, which JsonDocument.Parse refuses outright, - // and a writer reset out of order would leave the document incomplete. - using var document = JsonDocument.Parse(frame); - var root = document.RootElement; - - Assert.Equal("text", root.GetProperty("type").GetString()); - tokens.Add(root.GetProperty("token").GetString()!); - lasts.Add(root.GetProperty("last").GetBoolean()); - } + foreach (string frame in sent) + { + // Parsed, never substring-matched. A buffer whose written count survived a reset would + // put a leftover tail after the document, which JsonDocument.Parse refuses outright, + // and a writer reset out of order would leave the document incomplete. + using JsonDocument document = JsonDocument.Parse(frame); + JsonElement root = document.RootElement; + + Assert.Equal("text", root.GetProperty("type").GetString()); + tokens.Add(root.GetProperty("token").GetString()!); + lasts.Add(root.GetProperty("last").GetBoolean()); + } - // Distinct tokens, in the order the model streamed them, then the empty closing frame. - string[] expectedTokens = ["alpha", " bravo", " charlie", string.Empty]; - bool[] expectedLast = [false, false, false, true]; + // Distinct tokens, in the order the model streamed them, then the empty closing frame. + string[] expectedTokens = ["alpha", " bravo", " charlie", string.Empty]; + bool[] expectedLast = [false, false, false, true]; - Assert.Equal(expectedTokens, tokens); - Assert.Equal(expectedLast, lasts); + Assert.Equal(expectedTokens, tokens); + Assert.Equal(expectedLast, lasts); + } } } diff --git a/tests/AgentCore.Domain.Tests/Audit/AuditEventVocabularyTests.cs b/tests/AgentCore.Domain.Tests/Audit/AuditEventVocabularyTests.cs index d82754cc..8256a7ea 100644 --- a/tests/AgentCore.Domain.Tests/Audit/AuditEventVocabularyTests.cs +++ b/tests/AgentCore.Domain.Tests/Audit/AuditEventVocabularyTests.cs @@ -1,470 +1,483 @@ using AgentCore.Domain.Audit; using Xunit; -namespace AgentCore.Domain.Tests.Audit; - -/// -/// Both vocabularies are closed, their tokens are stable, and an amendment names the event it -/// amends. -/// -public sealed class AuditEventVocabularyTests +namespace AgentCore.Domain.Tests.Audit { - /// What the model produced on the turn these facts describe. - private const string Spoken = "Welcome to Sole, how can I help you today?"; - - /// What the caller heard of it before speaking over the rest. - private const string Heard = "Welcome to Sole, how can I"; - - private static readonly DateTimeOffset Start = DateTimeOffset.FromUnixTimeMilliseconds(1_700_000_000_000); - - [Theory] - [InlineData(AuditEventKind.ConversationStarted, "conversation.started")] - [InlineData(AuditEventKind.TurnCompleted, "turn.completed")] - [InlineData(AuditEventKind.ReplyInterrupted, "reply.interrupted")] - [InlineData(AuditEventKind.ToolFailed, "tool.failed")] - [InlineData(AuditEventKind.PromptFlagged, "prompt.flagged")] - [InlineData(AuditEventKind.ConversationEnded, "conversation.ended")] - public void EachKind_HasItsToken(AuditEventKind kind, string token) - { - // The token is stable forever. A C# rename must not change a hash PostgreSQL already stored. - Assert.Equal(token, AuditEventKinds.ToToken(kind)); - Assert.True(AuditEventKinds.TryParse(token, out AuditEventKind parsed)); - Assert.Equal(kind, parsed); - } - - [Fact] - public void TheVocabulary_IsClosed() + /// + /// Both vocabularies are closed, their tokens are stable, and an amendment names the event it + /// amends. + /// + public sealed class AuditEventVocabularyTests { - AuditEventKind[] declared = Enum.GetValues(); - - // Seven kinds, and the numbers run 0 to 7 with 4 missing. Value 4 was reply.flagged, retired - // on 2026-08-13 when reply moderation was withdrawn. A number is never reused, so a stored - // row can never come to mean something else. - Assert.Equal(7, declared.Length); - Assert.DoesNotContain(declared, kind => (int)kind == 4); - foreach (AuditEventKind kind in declared) + /// What the model produced on the turn these facts describe. + private const string Spoken = "Welcome to Sole, how can I help you today?"; + + /// What the caller heard of it before speaking over the rest. + private const string Heard = "Welcome to Sole, how can I"; + + private static readonly DateTimeOffset Start = DateTimeOffset.FromUnixTimeMilliseconds(1_700_000_000_000); + + [Theory] + [InlineData(AuditEventKind.ConversationStarted, "conversation.started")] + [InlineData(AuditEventKind.TurnCompleted, "turn.completed")] + [InlineData(AuditEventKind.ReplyInterrupted, "reply.interrupted")] + [InlineData(AuditEventKind.ToolFailed, "tool.failed")] + [InlineData(AuditEventKind.PromptFlagged, "prompt.flagged")] + [InlineData(AuditEventKind.ConversationEnded, "conversation.ended")] + public void EachKind_HasItsToken(AuditEventKind kind, string token) { - Assert.NotEmpty(AuditEventKinds.ToToken(kind)); + // The token is stable forever. A C# rename must not change a hash PostgreSQL already stored. + Assert.Equal(token, AuditEventKinds.ToToken(kind)); + Assert.True(AuditEventKinds.TryParse(token, out AuditEventKind parsed)); + Assert.Equal(kind, parsed); } - Assert.Throws(() => AuditEventKinds.ToToken((AuditEventKind)99)); - Assert.False(AuditEventKinds.TryParse("conversation.transferred", out _)); - } - - [Theory] - [InlineData(ConversationEndReason.CallerHungUp, "caller.hangup")] - [InlineData(ConversationEndReason.AgentCompleted, "agent.completed")] - [InlineData(ConversationEndReason.TransferredToHuman, "agent.transferred")] - [InlineData(ConversationEndReason.Faulted, "conversation.faulted")] - public void EachEndReason_HasItsToken(ConversationEndReason reason, string token) - { - // The token is stable forever, for the reason a kind token is. A report counts these years - // after the conversation, and the count breaks when a token moves. - Assert.Equal(token, ConversationEndReasons.ToToken(reason)); - Assert.True(ConversationEndReasons.TryParse(token, out ConversationEndReason parsed)); - Assert.Equal(reason, parsed); - } + [Fact] + public void TheVocabulary_IsClosed() + { + AuditEventKind[] declared = Enum.GetValues(); + + // Seven kinds, and the numbers run 0 to 7 with 4 missing. Value 4 was reply.flagged, retired + // on 2026-08-13 when reply moderation was withdrawn. A number is never reused, so a stored + // row can never come to mean something else. + Assert.Equal(7, declared.Length); + Assert.DoesNotContain(declared, kind => (int)kind == 4); + foreach (AuditEventKind kind in declared) + { + Assert.NotEmpty(AuditEventKinds.ToToken(kind)); + } - [Fact] - public void TheEndReasons_AreClosed() - { - ConversationEndReason[] declared = Enum.GetValues(); + _ = Assert.Throws(() => AuditEventKinds.ToToken((AuditEventKind)99)); + Assert.False(AuditEventKinds.TryParse("conversation.transferred", out _)); + } - // Section 4 names four ways a conversation ends, and the set holds those four and no more. - Assert.Equal(4, declared.Length); - foreach (ConversationEndReason reason in declared) + [Theory] + [InlineData(ConversationEndReason.CallerHungUp, "caller.hangup")] + [InlineData(ConversationEndReason.AgentCompleted, "agent.completed")] + [InlineData(ConversationEndReason.TransferredToHuman, "agent.transferred")] + [InlineData(ConversationEndReason.Faulted, "conversation.faulted")] + public void EachEndReason_HasItsToken(ConversationEndReason reason, string token) { - Assert.NotEmpty(ConversationEndReasons.ToToken(reason)); + // The token is stable forever, for the reason a kind token is. A report counts these years + // after the conversation, and the count breaks when a token moves. + Assert.Equal(token, ConversationEndReasons.ToToken(reason)); + Assert.True(ConversationEndReasons.TryParse(token, out ConversationEndReason parsed)); + Assert.Equal(reason, parsed); } - Assert.Throws(() => ConversationEndReasons.ToToken((ConversationEndReason)99)); - Assert.False(ConversationEndReasons.TryParse("hangup", out _)); - Assert.False(ConversationEndReasons.TryParse("caller hung up", out _)); - Assert.False(ConversationEndReasons.TryParse("CallerHungUp", out _)); - Assert.False(ConversationEndReasons.TryParse("0", out _)); - } - - [Theory] - [InlineData(ToolFailureKind.Undeclared, "tool.undeclared")] - [InlineData(ToolFailureKind.Faulted, "tool.faulted")] - public void EachToolFailureKind_HasItsToken(ToolFailureKind kind, string token) - { - // The token is stable forever, for the reason an end reason's is. A report that counts how - // often the model invented a tool name reads this token years after the conversation. - Assert.Equal(token, ToolFailureKinds.ToToken(kind)); - Assert.True(ToolFailureKinds.TryParse(token, out ToolFailureKind parsed)); - Assert.Equal(kind, parsed); - } + [Fact] + public void TheEndReasons_AreClosed() + { + ConversationEndReason[] declared = Enum.GetValues(); - [Fact] - public void TheToolFailureKinds_AreClosed() - { - ToolFailureKind[] declared = Enum.GetValues(); + // Section 4 names four ways a conversation ends, and the set holds those four and no more. + Assert.Equal(4, declared.Length); + foreach (ConversationEndReason reason in declared) + { + Assert.NotEmpty(ConversationEndReasons.ToToken(reason)); + } + + _ = Assert.Throws(() => ConversationEndReasons.ToToken((ConversationEndReason)99)); + Assert.False(ConversationEndReasons.TryParse("hangup", out _)); + Assert.False(ConversationEndReasons.TryParse("caller hung up", out _)); + Assert.False(ConversationEndReasons.TryParse("CallerHungUp", out _)); + Assert.False(ConversationEndReasons.TryParse("0", out _)); + } - // Two facts, and no more: the model named a tool the document does not declare, or a - // declared tool threw. The framework's own status set is wider and it is not ours. - Assert.Equal(2, declared.Length); - foreach (ToolFailureKind kind in declared) + [Theory] + [InlineData(ToolFailureKind.Undeclared, "tool.undeclared")] + [InlineData(ToolFailureKind.Faulted, "tool.faulted")] + public void EachToolFailureKind_HasItsToken(ToolFailureKind kind, string token) { - Assert.NotEmpty(ToolFailureKinds.ToToken(kind)); + // The token is stable forever, for the reason an end reason's is. A report that counts how + // often the model invented a tool name reads this token years after the conversation. + Assert.Equal(token, ToolFailureKinds.ToToken(kind)); + Assert.True(ToolFailureKinds.TryParse(token, out ToolFailureKind parsed)); + Assert.Equal(kind, parsed); } - Assert.Throws(() => ToolFailureKinds.ToToken((ToolFailureKind)99)); - Assert.False(ToolFailureKinds.TryParse("NotFound", out _)); - Assert.False(ToolFailureKinds.TryParse("Exception", out _)); - Assert.False(ToolFailureKinds.TryParse("1", out _)); - } + [Fact] + public void TheToolFailureKinds_AreClosed() + { + ToolFailureKind[] declared = Enum.GetValues(); - /// The reason is counted, so the chain refuses free text under it. - [Fact] - public void AConversationEndedEventWithAFreeTextReason_IsRefused() - { - AuditEvent free = Ended() with + // Two facts, and no more: the model named a tool the document does not declare, or a + // declared tool threw. The framework's own status set is wider and it is not ours. + Assert.Equal(2, declared.Length); + foreach (ToolFailureKind kind in declared) + { + Assert.NotEmpty(ToolFailureKinds.ToToken(kind)); + } + + _ = Assert.Throws(() => ToolFailureKinds.ToToken((ToolFailureKind)99)); + Assert.False(ToolFailureKinds.TryParse("NotFound", out _)); + Assert.False(ToolFailureKinds.TryParse("Exception", out _)); + Assert.False(ToolFailureKinds.TryParse("1", out _)); + } + + /// The reason is counted, so the chain refuses free text under it. + [Fact] + public void AConversationEndedEventWithAFreeTextReason_IsRefused() { - Payload = new Dictionary(StringComparer.Ordinal) + AuditEvent free = Ended() with { - [AuditPayloadKeys.EndReason] = "the caller hung up", - }, - }; + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.EndReason] = "the caller hung up", + }, + }; - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(free)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(free)); - Assert.Contains(AuditPayloadKeys.EndReason, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.EndReason, failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AConversationEndedEventWithoutAReason_IsRefused() - { - AuditEvent silent = Ended() with + [Fact] + public void AConversationEndedEventWithoutAReason_IsRefused() { - Payload = new Dictionary(StringComparer.Ordinal), - }; + AuditEvent silent = Ended() with + { + Payload = new Dictionary(StringComparer.Ordinal), + }; - Assert.Throws(() => AuditEventVocabulary.Validate(silent)); - } + _ = Assert.Throws(() => AuditEventVocabulary.Validate(silent)); + } - /// - /// T23: the table is append-only, so a barge-in is a second event that references the first. - /// - [Fact] - public void AnAmendment_ReferencesTheEventItAmends() - { - AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 2); - AuditEvent interruption = Interruption(eventId: Guid.CreateVersion7(), amends: turn.EventId, turnIndex: 2); + /// + /// T23: the table is append-only, so a barge-in is a second event that references the first. + /// + [Fact] + public void AnAmendment_ReferencesTheEventItAmends() + { + AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 2); + AuditEvent interruption = Interruption(eventId: Guid.CreateVersion7(), amends: turn.EventId, turnIndex: 2); - AuditEvent[] run = [turn, interruption]; + AuditEvent[] run = [turn, interruption]; - Assert.All(run, AuditEventVocabulary.Validate); - Assert.Equal(turn.EventId, interruption.AmendsEventId); - Assert.Equal(turn.ConversationId, interruption.ConversationId); - Assert.Equal(turn.TurnIndex, interruption.TurnIndex); + Assert.All(run, AuditEventVocabulary.Validate); + Assert.Equal(turn.EventId, interruption.AmendsEventId); + Assert.Equal(turn.ConversationId, interruption.ConversationId); + Assert.Equal(turn.TurnIndex, interruption.TurnIndex); - // The first event is untouched. Nothing rewrote the turn, and both events stand. - Assert.Equal(AuditHash.OfText(Spoken).Value, turn.Payload[AuditPayloadKeys.ReplyTextSha256]); - Assert.Null(turn.AmendsEventId); - } + // The first event is untouched. Nothing rewrote the turn, and both events stand. + Assert.Equal(AuditHash.OfText(Spoken).Value, turn.Payload[AuditPayloadKeys.ReplyTextSha256]); + Assert.Null(turn.AmendsEventId); + } - /// Section 11, item 6a: the event records the text the caller ACTUALLY HEARD. - [Fact] - public void AnInterruption_RecordsWhatTheCallerHeardAndNotWhatTheModelProduced() - { - AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 0); - AuditEvent interruption = Interruption(eventId: Guid.CreateVersion7(), amends: turn.EventId, turnIndex: 0); - - string produced = turn.Payload[AuditPayloadKeys.ReplyTextSha256]; - string heard = interruption.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]; - - // The chain holds proof of the words and never the words, so the reviewer's check is against - // store 1: the amendment proves what the caller heard, and it is not the whole reply. - Assert.NotEqual(produced, heard); - Assert.Equal(AuditHash.OfText(Heard).Value, heard); - Assert.Equal(AuditHash.OfText(Spoken).Value, produced); - Assert.Equal("1820", interruption.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); - } + /// Section 11, item 6a: the event records the text the caller ACTUALLY HEARD. + [Fact] + public void AnInterruption_RecordsWhatTheCallerHeardAndNotWhatTheModelProduced() + { + AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 0); + AuditEvent interruption = Interruption(eventId: Guid.CreateVersion7(), amends: turn.EventId, turnIndex: 0); + + string produced = turn.Payload[AuditPayloadKeys.ReplyTextSha256]; + string heard = interruption.Payload[AuditPayloadKeys.UtteranceUntilInterruptSha256]; + + // The chain holds proof of the words and never the words, so the reviewer's check is against + // store 1: the amendment proves what the caller heard, and it is not the whole reply. + Assert.NotEqual(produced, heard); + Assert.Equal(AuditHash.OfText(Heard).Value, heard); + Assert.Equal(AuditHash.OfText(Spoken).Value, produced); + Assert.Equal("1820", interruption.Payload[AuditPayloadKeys.DurationUntilInterruptMs]); + } - [Fact] - public void AnInterruptionThatAmendsNothing_IsRefused() - { - AuditEvent orphan = Interruption(eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7(), turnIndex: 0) - with - { AmendsEventId = null }; + [Fact] + public void AnInterruptionThatAmendsNothing_IsRefused() + { + AuditEvent orphan = Interruption(eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7(), turnIndex: 0) + with + { AmendsEventId = null }; - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(orphan)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(orphan)); - Assert.Contains("T23", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("T23", failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AnInterruptionWithoutTheUtterance_IsRefused() - { - AuditEvent silent = Interruption(eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7(), turnIndex: 0) with + [Fact] + public void AnInterruptionWithoutTheUtterance_IsRefused() { - Payload = new Dictionary(StringComparer.Ordinal) + AuditEvent silent = Interruption(eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7(), turnIndex: 0) with { - [AuditPayloadKeys.DurationUntilInterruptMs] = "1820", - }, - }; + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.DurationUntilInterruptMs] = "1820", + }, + }; - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(silent)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(silent)); - Assert.Contains(AuditPayloadKeys.UtteranceUntilInterruptSha256, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.UtteranceUntilInterruptSha256, failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Validate_EmptyHashOnInterrupt_IsRefused() - { - // The chain stores proof of the words and not the words, so the one value that must never - // reach it is a hash that proves nothing. An empty text still hashes to a full digest. - AuditEvent unproven = Interruption(eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7(), turnIndex: 0) with + [Fact] + public void Validate_EmptyHashOnInterrupt_IsRefused() { - Payload = new Dictionary(StringComparer.Ordinal) + // The chain stores proof of the words and not the words, so the one value that must never + // reach it is a hash that proves nothing. An empty text still hashes to a full digest. + AuditEvent unproven = Interruption(eventId: Guid.CreateVersion7(), amends: Guid.CreateVersion7(), turnIndex: 0) with { - [AuditPayloadKeys.UtteranceUntilInterruptSha256] = string.Empty, - [AuditPayloadKeys.DurationUntilInterruptMs] = "1820", - }, - }; + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.UtteranceUntilInterruptSha256] = string.Empty, + [AuditPayloadKeys.DurationUntilInterruptMs] = "1820", + }, + }; - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(unproven)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(unproven)); - Assert.Contains(AuditPayloadKeys.UtteranceUntilInterruptSha256, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.UtteranceUntilInterruptSha256, failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Validate_EmptyHashOnTurnCompleted_IsRefused() - { - AuditEvent unproven = Turn(eventId: Guid.CreateVersion7(), turnIndex: 0) with + [Fact] + public void Validate_EmptyHashOnTurnCompleted_IsRefused() { - Payload = new Dictionary(StringComparer.Ordinal) + AuditEvent unproven = Turn(eventId: Guid.CreateVersion7(), turnIndex: 0) with { - [AuditPayloadKeys.ReplyTextSha256] = string.Empty, - }, - }; + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ReplyTextSha256] = string.Empty, + }, + }; - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(unproven)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(unproven)); - Assert.Contains(AuditPayloadKeys.ReplyTextSha256, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.ReplyTextSha256, failure.Message, StringComparison.Ordinal); + } - [Fact] - public void Validate_RefusesAnEventWithNoIdentity() - { - AuditEvent malformed = Turn(eventId: Guid.Empty, turnIndex: 0); + [Fact] + public void Validate_RefusesAnEventWithNoIdentity() + { + AuditEvent malformed = Turn(eventId: Guid.Empty, turnIndex: 0); - var error = Assert.Throws(() => AuditEventVocabulary.Validate(malformed)); + ArgumentException error = Assert.Throws(() => AuditEventVocabulary.Validate(malformed)); - Assert.Contains("identity", error.Message, StringComparison.Ordinal); - } + Assert.Contains("identity", error.Message, StringComparison.Ordinal); + } - [Fact] - public void Validate_RefusesAnAmendmentThatNamesItself() - { - var id = Guid.CreateVersion7(); - AuditEvent circular = Interruption(eventId: id, amends: id, turnIndex: 2); + [Fact] + public void Validate_RefusesAnAmendmentThatNamesItself() + { + Guid id = Guid.CreateVersion7(); + AuditEvent circular = Interruption(eventId: id, amends: id, turnIndex: 2); - var error = Assert.Throws(() => AuditEventVocabulary.Validate(circular)); + ArgumentException error = Assert.Throws(() => AuditEventVocabulary.Validate(circular)); - Assert.Contains("names another event", error.Message, StringComparison.Ordinal); - } + Assert.Contains("names another event", error.Message, StringComparison.Ordinal); + } - [Fact] - public void Validate_AcceptsAnAmendmentThatNamesAnotherEvent() - { - AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 2); - AuditEvent interruption = - Interruption(eventId: Guid.CreateVersion7(), amends: turn.EventId, turnIndex: 2); + [Fact] + public void Validate_AcceptsAnAmendmentThatNamesAnotherEvent() + { + AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 2); + AuditEvent interruption = + Interruption(eventId: Guid.CreateVersion7(), amends: turn.EventId, turnIndex: 2); - AuditEventVocabulary.Validate(interruption); + AuditEventVocabulary.Validate(interruption); - Assert.Equal(turn.EventId, interruption.AmendsEventId); - } + Assert.Equal(turn.EventId, interruption.AmendsEventId); + } - [Fact] - public void AnEventWithoutAConversationId_IsRefused() - { - AuditEvent nameless = Turn(eventId: Guid.CreateVersion7(), turnIndex: 0) with { ConversationId = string.Empty }; + [Fact] + public void AnEventWithoutAConversationId_IsRefused() + { + AuditEvent nameless = Turn(eventId: Guid.CreateVersion7(), turnIndex: 0) with { ConversationId = string.Empty }; - Assert.Throws(() => AuditEventVocabulary.Validate(nameless)); - } + _ = Assert.Throws(() => AuditEventVocabulary.Validate(nameless)); + } - [Fact] - public void AHash_RefusesEverySpellingButLowercaseHexadecimal() - { - // PostgreSQL renders sha256() through encode(..., 'hex'), which is lowercase. - Assert.Throws(() => AuditHash.Parse(new string('A', AuditHash.Length))); - Assert.Throws(() => AuditHash.Parse(new string('0', AuditHash.Length - 1))); - Assert.Throws(() => AuditHash.Parse("not a hash")); - Assert.False(AuditHash.TryParse(null, out _)); - } + [Fact] + public void AHash_RefusesEverySpellingButLowercaseHexadecimal() + { + // PostgreSQL renders sha256() through encode(..., 'hex'), which is lowercase. + _ = Assert.Throws(() => AuditHash.Parse(new string('A', AuditHash.Length))); + _ = Assert.Throws(() => AuditHash.Parse(new string('0', AuditHash.Length - 1))); + _ = Assert.Throws(() => AuditHash.Parse("not a hash")); + Assert.False(AuditHash.TryParse(null, out _)); + } - /// - /// The moderation verdict is known BEFORE the model runs, so the event amends nothing. This is - /// the rule that differs from reply.interrupted, and it is the reason the two kinds are - /// two kinds. - /// - [Fact] - public void AFlaggedPrompt_NeedsNoAmendment() - { - AuditEvent flagged = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1); + /// + /// The moderation verdict is known BEFORE the model runs, so the event amends nothing. This is + /// the rule that differs from reply.interrupted, and it is the reason the two kinds are + /// two kinds. + /// + [Fact] + public void AFlaggedPrompt_NeedsNoAmendment() + { + AuditEvent flagged = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1); - Assert.Null(flagged.AmendsEventId); - Assert.Equal(1, flagged.TurnIndex); + Assert.Null(flagged.AmendsEventId); + Assert.Equal(1, flagged.TurnIndex); - AuditEvent[] run = [flagged]; + AuditEvent[] run = [flagged]; - Assert.All(run, AuditEventVocabulary.Validate); - } + Assert.All(run, AuditEventVocabulary.Validate); + } - /// - /// The kind alone says something flagged the caller. The categories are the only other fact the - /// event holds, and §9 makes the chain the only long-term record. - /// - [Fact] - public void AFlaggedPromptWithoutTheCategories_IsRefused() - { - AuditEvent silent = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1) with + /// + /// The kind alone says something flagged the caller. The categories are the only other fact the + /// event holds, and §9 makes the chain the only long-term record. + /// + [Fact] + public void AFlaggedPromptWithoutTheCategories_IsRefused() { - Payload = new Dictionary(StringComparer.Ordinal), - }; + AuditEvent silent = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1) with + { + Payload = new Dictionary(StringComparer.Ordinal), + }; - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(silent)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(silent)); - Assert.Contains(AuditPayloadKeys.ModerationCategories, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.ModerationCategories, failure.Message, StringComparison.Ordinal); + } - [Fact] - public void AFlaggedPromptWithAnEmptyCategoryList_IsRefused() - { - AuditEvent empty = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: string.Empty); + [Fact] + public void AFlaggedPromptWithAnEmptyCategoryList_IsRefused() + { + AuditEvent empty = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: string.Empty); - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(empty)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(empty)); - Assert.Contains(AuditPayloadKeys.ModerationCategories, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.ModerationCategories, failure.Message, StringComparison.Ordinal); + } - /// A reader splits on a comma and counts, and a blank member makes the count wrong. - [Theory] - [InlineData("harassment,,violence")] - [InlineData("harassment,")] - [InlineData(",harassment")] - public void AFlaggedPromptWithABlankCategory_IsRefused(string categories) - { - AuditEvent blank = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: categories); + /// A reader splits on a comma and counts, and a blank member makes the count wrong. + [Theory] + [InlineData("harassment,,violence")] + [InlineData("harassment,")] + [InlineData(",harassment")] + public void AFlaggedPromptWithABlankCategory_IsRefused(string categories) + { + AuditEvent blank = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: categories); - ArgumentException failure = Assert.Throws( - () => AuditEventVocabulary.Validate(blank)); + ArgumentException failure = Assert.Throws( + () => AuditEventVocabulary.Validate(blank)); - Assert.Contains(AuditPayloadKeys.ModerationCategories, failure.Message, StringComparison.Ordinal); - } + Assert.Contains(AuditPayloadKeys.ModerationCategories, failure.Message, StringComparison.Ordinal); + } - /// - /// The category list is stored exactly as the endpoint returned it. Nothing sorts it, and - /// nothing rewrites it. - /// - [Fact] - public void AFlaggedPromptKeepsTheOrderTheEndpointReturned() - { - AuditEvent first = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: "harassment,violence"); - AuditEvent second = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: "violence,harassment"); + /// + /// The category list is stored exactly as the endpoint returned it. Nothing sorts it, and + /// nothing rewrites it. + /// + [Fact] + public void AFlaggedPromptKeepsTheOrderTheEndpointReturned() + { + AuditEvent first = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: "harassment,violence"); + AuditEvent second = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1, categories: "violence,harassment"); - AuditEventVocabulary.Validate(first); - AuditEventVocabulary.Validate(second); + AuditEventVocabulary.Validate(first); + AuditEventVocabulary.Validate(second); - Assert.Equal("harassment,violence", first.Payload[AuditPayloadKeys.ModerationCategories]); - Assert.Equal("violence,harassment", second.Payload[AuditPayloadKeys.ModerationCategories]); - } + Assert.Equal("harassment,violence", first.Payload[AuditPayloadKeys.ModerationCategories]); + Assert.Equal("violence,harassment", second.Payload[AuditPayloadKeys.ModerationCategories]); + } - /// - /// The taxonomy belongs to the moderation endpoint and it is open, unlike - /// . A closed set would make throw on a - /// category OpenAI added, and destroy the record the chain exists to protect. - /// - [Fact] - public void ACategoryTheLibraryNeverNamed_IsAccepted() - { - AuditEvent novel = FlaggedPrompt( - eventId: Guid.CreateVersion7(), - turnIndex: 1, - categories: "illicit/violent,some-category-openai-added-last-tuesday"); + /// + /// The taxonomy belongs to the moderation endpoint and it is open, unlike + /// . A closed set would make throw on a + /// category OpenAI added, and destroy the record the chain exists to protect. + /// + [Fact] + public void ACategoryTheLibraryNeverNamed_IsAccepted() + { + AuditEvent novel = FlaggedPrompt( + eventId: Guid.CreateVersion7(), + turnIndex: 1, + categories: "illicit/violent,some-category-openai-added-last-tuesday"); - AuditEventVocabulary.Validate(novel); + AuditEventVocabulary.Validate(novel); - Assert.Equal( - "illicit/violent,some-category-openai-added-last-tuesday", - novel.Payload[AuditPayloadKeys.ModerationCategories]); - } + Assert.Equal( + "illicit/violent,some-category-openai-added-last-tuesday", + novel.Payload[AuditPayloadKeys.ModerationCategories]); + } - /// The rule requires no amendment, and it forbids none either. - [Fact] - public void AFlaggedPrompt_MayStillCarryAnAmendment() - { - AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 1); - AuditEvent flagged = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1) with { AmendsEventId = turn.EventId }; + /// The rule requires no amendment, and it forbids none either. + [Fact] + public void AFlaggedPrompt_MayStillCarryAnAmendment() + { + AuditEvent turn = Turn(eventId: Guid.CreateVersion7(), turnIndex: 1); + AuditEvent flagged = FlaggedPrompt(eventId: Guid.CreateVersion7(), turnIndex: 1) with { AmendsEventId = turn.EventId }; - AuditEvent[] run = [turn, flagged]; + AuditEvent[] run = [turn, flagged]; - Assert.All(run, AuditEventVocabulary.Validate); - Assert.Equal(turn.EventId, flagged.AmendsEventId); - } + Assert.All(run, AuditEventVocabulary.Validate); + Assert.Equal(turn.EventId, flagged.AmendsEventId); + } - private static AuditEvent Turn(Guid eventId, int turnIndex) => new() - { - ConversationId = "conversation-1", - EventId = eventId, - Kind = AuditEventKind.TurnCompleted, - OccurredAt = Start, - TurnIndex = turnIndex, - Payload = new Dictionary(StringComparer.Ordinal) + private static AuditEvent Turn(Guid eventId, int turnIndex) { - [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(Spoken).Value, - [AuditPayloadKeys.StageBefore] = "greeting", - [AuditPayloadKeys.StageAfter] = "identify", - }, - }; + return new() + { + ConversationId = "conversation-1", + EventId = eventId, + Kind = AuditEventKind.TurnCompleted, + OccurredAt = Start, + TurnIndex = turnIndex, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(Spoken).Value, + [AuditPayloadKeys.StageBefore] = "greeting", + [AuditPayloadKeys.StageAfter] = "identify", + }, + }; + } - private static AuditEvent Interruption(Guid eventId, Guid amends, int turnIndex) => new() - { - ConversationId = "conversation-1", - EventId = eventId, - Kind = AuditEventKind.ReplyInterrupted, - OccurredAt = Start.AddMilliseconds(1_820), - TurnIndex = turnIndex, - AmendsEventId = amends, - Payload = new Dictionary(StringComparer.Ordinal) + private static AuditEvent Interruption(Guid eventId, Guid amends, int turnIndex) { - [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText(Heard).Value, - [AuditPayloadKeys.DurationUntilInterruptMs] = "1820", - }, - }; + return new() + { + ConversationId = "conversation-1", + EventId = eventId, + Kind = AuditEventKind.ReplyInterrupted, + OccurredAt = Start.AddMilliseconds(1_820), + TurnIndex = turnIndex, + AmendsEventId = amends, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.UtteranceUntilInterruptSha256] = AuditHash.OfText(Heard).Value, + [AuditPayloadKeys.DurationUntilInterruptMs] = "1820", + }, + }; + } - private static AuditEvent FlaggedPrompt(Guid eventId, int turnIndex, string categories = "harassment") => new() - { - ConversationId = "conversation-1", - EventId = eventId, - Kind = AuditEventKind.PromptFlagged, - OccurredAt = Start.AddMilliseconds(2_400), - TurnIndex = turnIndex, - Payload = new Dictionary(StringComparer.Ordinal) + private static AuditEvent FlaggedPrompt(Guid eventId, int turnIndex, string categories = "harassment") { - [AuditPayloadKeys.ModerationCategories] = categories, - }, - }; + return new() + { + ConversationId = "conversation-1", + EventId = eventId, + Kind = AuditEventKind.PromptFlagged, + OccurredAt = Start.AddMilliseconds(2_400), + TurnIndex = turnIndex, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ModerationCategories] = categories, + }, + }; + } - private static AuditEvent Ended() => new() - { - ConversationId = "conversation-1", - EventId = Guid.CreateVersion7(), - Kind = AuditEventKind.ConversationEnded, - OccurredAt = Start.AddMilliseconds(9_000), - Payload = new Dictionary(StringComparer.Ordinal) + private static AuditEvent Ended() { - [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.CallerHungUp), - }, - }; + return new() + { + ConversationId = "conversation-1", + EventId = Guid.CreateVersion7(), + Kind = AuditEventKind.ConversationEnded, + OccurredAt = Start.AddMilliseconds(9_000), + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.CallerHungUp), + }, + }; + } + } } diff --git a/tests/AgentCore.Domain.Tests/Audit/AuditHashTests.cs b/tests/AgentCore.Domain.Tests/Audit/AuditHashTests.cs index 8fa43019..35bd163d 100644 --- a/tests/AgentCore.Domain.Tests/Audit/AuditHashTests.cs +++ b/tests/AgentCore.Domain.Tests/Audit/AuditHashTests.cs @@ -1,37 +1,38 @@ using AgentCore.Domain.Audit; using Xunit; -namespace AgentCore.Domain.Tests.Audit; - -/// -/// The digest the chain stores in place of the words a caller said or heard. -/// -/// -/// The words live in store 1 and stay erasable, so the chain must be able to prove a text it does -/// not hold. Both halves of that proof read the same bytes: this type, and -/// encode(sha256(convert_to(t, 'UTF8')), 'hex') in PostgreSQL. -/// -public sealed class AuditHashTests +namespace AgentCore.Domain.Tests.Audit { - [Theory] - [InlineData("abc", "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad")] - // The empty string is here on purpose: a turn that spoke nothing still writes 64 characters, - // and an empty VALUE is the one thing the chain refuses on a stored kind. - [InlineData("", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")] - public void OfText_AKnownVector_IsTheSha256OfItsUtf8Bytes(string text, string expected) + /// + /// The digest the chain stores in place of the words a caller said or heard. + /// + /// + /// The words live in store 1 and stay erasable, so the chain must be able to prove a text it does + /// not hold. Both halves of that proof read the same bytes: this type, and + /// encode(sha256(convert_to(t, 'UTF8')), 'hex') in PostgreSQL. + /// + public sealed class AuditHashTests { - AuditHash hash = AuditHash.OfText(text); + [Theory] + [InlineData("abc", "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad")] + // The empty string is here on purpose: a turn that spoke nothing still writes 64 characters, + // and an empty VALUE is the one thing the chain refuses on a stored kind. + [InlineData("", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")] + public void OfText_AKnownVector_IsTheSha256OfItsUtf8Bytes(string text, string expected) + { + AuditHash hash = AuditHash.OfText(text); - Assert.Equal(expected, hash.Value); - } + Assert.Equal(expected, hash.Value); + } - [Fact] - public void OfText_TextOutsideTheBasicMultilingualPlane_ReadsItsUtf8Bytes() - { - // PostgreSQL hashes the UTF-8 bytes. .NET strings are UTF-16, and a surrogate pair is where - // the two spellings would diverge if this read characters instead. - AuditHash hash = AuditHash.OfText("\U0001F600"); + [Fact] + public void OfText_TextOutsideTheBasicMultilingualPlane_ReadsItsUtf8Bytes() + { + // PostgreSQL hashes the UTF-8 bytes. .NET strings are UTF-16, and a surrogate pair is where + // the two spellings would diverge if this read characters instead. + AuditHash hash = AuditHash.OfText("\U0001F600"); - Assert.Equal("f0443a342c5ef54783a111b51ba56c938e474c32324d90c3a60c9c8e3a37e2d9", hash.Value); + Assert.Equal("f0443a342c5ef54783a111b51ba56c938e474c32324d90c3a60c9c8e3a37e2d9", hash.Value); + } } } diff --git a/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs b/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs index 62803781..86a99baa 100644 --- a/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs +++ b/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs @@ -1,22 +1,23 @@ using AgentCore.Domain.Knowledge; using Xunit; -namespace AgentCore.Domain.Tests.Knowledge; - -public sealed class KnowledgeScopeTests +namespace AgentCore.Domain.Tests.Knowledge { - [Fact] - public void TwoScopes_WithTheSameFacetsAndNoOrigins_AreEqual() + public sealed class KnowledgeScopeTests { - IReadOnlyDictionary facets = new Dictionary(StringComparer.Ordinal) + [Fact] + public void TwoScopes_WithTheSameFacetsAndNoOrigins_AreEqual() { - ["brand"] = "sole", - }; + IReadOnlyDictionary facets = new Dictionary(StringComparer.Ordinal) + { + ["brand"] = "sole", + }; - var first = new KnowledgeScope { Facets = facets }; - var second = new KnowledgeScope { Facets = facets }; + KnowledgeScope first = new() { Facets = facets }; + KnowledgeScope second = new() { Facets = facets }; - Assert.Equal(first, second); - Assert.Equal(first.GetHashCode(), second.GetHashCode()); + Assert.Equal(first, second); + Assert.Equal(first.GetHashCode(), second.GetHashCode()); + } } } diff --git a/tests/AgentCore.Domain.Tests/TurnResultTests.cs b/tests/AgentCore.Domain.Tests/TurnResultTests.cs index 3caf87a8..e9088cdf 100644 --- a/tests/AgentCore.Domain.Tests/TurnResultTests.cs +++ b/tests/AgentCore.Domain.Tests/TurnResultTests.cs @@ -1,52 +1,51 @@ -using AgentCore.Domain; using Xunit; -namespace AgentCore.Domain.Tests; - -/// -/// is a pure record, and Domain stays dependency-free. -/// -public sealed class TurnResultTests +namespace AgentCore.Domain.Tests { - [Fact] - public void TwoResultsWithTheSameContent_AreEqual() - { - TurnResult first = new("conversation-1", 0, "greeting", "identify", "hello", false, null); - TurnResult second = new("conversation-1", 0, "greeting", "identify", "hello", false, null); - - Assert.Equal(first, second); - Assert.Equal(first.GetHashCode(), second.GetHashCode()); - } - - [Fact] - public void AFailedExtraction_IsCarriedAndNotThrown() - { - TurnResult result = new("conversation-1", 2, "resolve", "resolve", "one moment", false, "the extractor returned an empty reply"); - - Assert.Equal("the extractor returned an empty reply", result.ExtractionFailure); - Assert.False(result.IsTerminal); - } - - [Fact] - public void ATerminalTurn_ReportsItself() - { - TurnResult result = new("conversation-1", 4, "escalate", "close", "goodbye", true, null); - - Assert.True(result.IsTerminal); - Assert.Equal("close", result.StageAfter); - } - - [Fact] - public void Domain_ReferencesNothingOutsideTheFramework() + /// + /// is a pure record, and Domain stays dependency-free. + /// + public sealed class TurnResultTests { - var referenced = typeof(TurnResult).Assembly - .GetReferencedAssemblies() - .Select(name => name.Name ?? string.Empty) - .ToList(); - - // Domain holds pure records and takes no package, so the turn loop and the model client stay out. - Assert.DoesNotContain(referenced, name => name.StartsWith("AgentCore.", StringComparison.Ordinal)); - Assert.DoesNotContain(referenced, name => name.StartsWith("Microsoft.Extensions.AI", StringComparison.Ordinal)); - Assert.DoesNotContain(referenced, name => name.StartsWith("Microsoft.Agents.AI", StringComparison.Ordinal)); + [Fact] + public void TwoResultsWithTheSameContent_AreEqual() + { + TurnResult first = new("conversation-1", 0, "greeting", "identify", "hello", false, null); + TurnResult second = new("conversation-1", 0, "greeting", "identify", "hello", false, null); + + Assert.Equal(first, second); + Assert.Equal(first.GetHashCode(), second.GetHashCode()); + } + + [Fact] + public void AFailedExtraction_IsCarriedAndNotThrown() + { + TurnResult result = new("conversation-1", 2, "resolve", "resolve", "one moment", false, "the extractor returned an empty reply"); + + Assert.Equal("the extractor returned an empty reply", result.ExtractionFailure); + Assert.False(result.IsTerminal); + } + + [Fact] + public void ATerminalTurn_ReportsItself() + { + TurnResult result = new("conversation-1", 4, "escalate", "close", "goodbye", true, null); + + Assert.True(result.IsTerminal); + Assert.Equal("close", result.StageAfter); + } + + [Fact] + public void Domain_ReferencesNothingOutsideTheFramework() + { + List referenced = [.. typeof(TurnResult).Assembly + .GetReferencedAssemblies() + .Select(name => name.Name ?? string.Empty)]; + + // Domain holds pure records and takes no package, so the turn loop and the model client stay out. + Assert.DoesNotContain(referenced, name => name.StartsWith("AgentCore.", StringComparison.Ordinal)); + Assert.DoesNotContain(referenced, name => name.StartsWith("Microsoft.Extensions.AI", StringComparison.Ordinal)); + Assert.DoesNotContain(referenced, name => name.StartsWith("Microsoft.Agents.AI", StringComparison.Ordinal)); + } } } diff --git a/tests/AgentCore.Evals/BaselineGateTests.cs b/tests/AgentCore.Evals/BaselineGateTests.cs index c0f6a12f..3c89fff7 100644 --- a/tests/AgentCore.Evals/BaselineGateTests.cs +++ b/tests/AgentCore.Evals/BaselineGateTests.cs @@ -1,102 +1,103 @@ using Xunit; -namespace AgentCore.Evals; - -/// -/// The gate that fails a merge on a score drop. -/// -/// -/// -/// The gate reads what the eval suites already wrote to the disk store, so it has to run after them. -/// That order is now structural: this class sits alone in , and -/// runs that collection after every other one. So a plain -/// dotnet test tests/AgentCore.Evals, with no filter, passes from an empty results directory. -/// -/// -/// The Gate category stays, because CI still splits the run in two: -/// -/// -/// dotnet test tests/AgentCore.Evals --filter "Category!=Gate" -/// dotnet test tests/AgentCore.Evals --filter "Category=Gate" -/// -/// -/// The split is what separates a broken harness from a dropped score in the CI log, and it lets the -/// two halves carry different secrets. It is no longer what supplies the order. Run the second command -/// on its own against an empty directory and it still fails, correctly: nothing wrote the results it -/// measures. -/// -/// -/// A drop larger than the recorded tolerance fails. A rise never fails. The gate writes what it -/// measured to eval-results/measured.json, so a person who accepts a change copies the numbers -/// into the baseline by hand. -/// -/// -/// There is no fixture-execution gate. The synthetic knowledge base and the retrieval self-test that -/// wrote to the "fixture" execution were both deleted with the old filesystem store (Ruling 9): the -/// store that replaced it needs a real embedding model for its dense leg, which the offline fixture -/// suite has no key for, so nothing writes a "Document Recall" score outside a real, key-gated golden -/// set. A gate that always skips is worse than no gate, so this class reads only the "golden-set" -/// execution below. -/// -/// -[Trait("Category", "Gate")] -[Collection(EvalGateCollection.Name)] -public sealed class BaselineGateTests +namespace AgentCore.Evals { - private const string MeasuredPath = "eval-results/measured.json"; - - [Fact] - public async Task DatasetExecution_HoldsItsRecordedScores() + /// + /// The gate that fails a merge on a score drop. + /// + /// + /// + /// The gate reads what the eval suites already wrote to the disk store, so it has to run after them. + /// That order is now structural: this class sits alone in , and + /// runs that collection after every other one. So a plain + /// dotnet test tests/AgentCore.Evals, with no filter, passes from an empty results directory. + /// + /// + /// The Gate category stays, because CI still splits the run in two: + /// + /// + /// dotnet test tests/AgentCore.Evals --filter "Category!=Gate" + /// dotnet test tests/AgentCore.Evals --filter "Category=Gate" + /// + /// + /// The split is what separates a broken harness from a dropped score in the CI log, and it lets the + /// two halves carry different secrets. It is no longer what supplies the order. Run the second command + /// on its own against an empty directory and it still fails, correctly: nothing wrote the results it + /// measures. + /// + /// + /// A drop larger than the recorded tolerance fails. A rise never fails. The gate writes what it + /// measured to eval-results/measured.json, so a person who accepts a change copies the numbers + /// into the baseline by hand. + /// + /// + /// There is no fixture-execution gate. The synthetic knowledge base and the retrieval self-test that + /// wrote to the "fixture" execution were both deleted with the old filesystem store (Ruling 9): the + /// store that replaced it needs a real embedding model for its dense leg, which the offline fixture + /// suite has no key for, so nothing writes a "Document Recall" score outside a real, key-gated golden + /// set. A gate that always skips is worse than no gate, so this class reads only the "golden-set" + /// execution below. + /// + /// + [Trait("Category", "Gate")] + [Collection(EvalGateCollection.Name)] + public sealed class BaselineGateTests { - Assert.SkipUnless( - ScoreBaseline.DatasetBaselinePath is not null, - $"{ScoreBaseline.BaselineVariable} names no baseline, so there is nothing to gate against."); + private const string MeasuredPath = "eval-results/measured.json"; - // Arrange - var baseline = ScoreBaseline.Load(ScoreBaseline.DatasetBaselinePath!); + [Fact] + public async Task DatasetExecution_HoldsItsRecordedScores() + { + Assert.SkipUnless( + ScoreBaseline.DatasetBaselinePath is not null, + $"{ScoreBaseline.BaselineVariable} names no baseline, so there is nothing to gate against."); - // Act - var measured = await ScoreBaseline.MeasureAsync( - EvalHarness.StorageRoot, - EvalHarness.DatasetExecution, - TestContext.Current.CancellationToken); + // Arrange + ScoreBaseline baseline = ScoreBaseline.Load(ScoreBaseline.DatasetBaselinePath!); - // Assert - AssertNoDrop(baseline, measured, EvalHarness.DatasetExecution); - } + // Act + IReadOnlyDictionary measured = await ScoreBaseline.MeasureAsync( + EvalHarness.StorageRoot, + EvalHarness.DatasetExecution, + TestContext.Current.CancellationToken); - private static void AssertNoDrop( - ScoreBaseline baseline, - IReadOnlyDictionary measured, - string executionName) - { - ScoreBaseline.WriteMeasured(MeasuredPath, measured, baseline.Tolerance); - - Assert.True( - measured.Count > 0, - $"the store holds no result for execution '{executionName}'. Run the eval suites first."); + // Assert + AssertNoDrop(baseline, measured, EvalHarness.DatasetExecution); + } - List drops = []; - foreach (var entry in baseline.Metrics) + private static void AssertNoDrop( + ScoreBaseline baseline, + IReadOnlyDictionary measured, + string executionName) { - if (!measured.TryGetValue(entry.Key, out var score)) - { - drops.Add($"'{entry.Key}' is in the baseline and no row measured it."); - continue; - } + ScoreBaseline.WriteMeasured(MeasuredPath, measured, baseline.Tolerance); + + Assert.True( + measured.Count > 0, + $"the store holds no result for execution '{executionName}'. Run the eval suites first."); - var floor = entry.Value - baseline.Tolerance; - if (score < floor) + List drops = []; + foreach (KeyValuePair entry in baseline.Metrics) { - drops.Add( - $"'{entry.Key}' scored {score} against a baseline of {entry.Value} " - + $"and a floor of {Math.Round(floor, 4)}."); + if (!measured.TryGetValue(entry.Key, out double score)) + { + drops.Add($"'{entry.Key}' is in the baseline and no row measured it."); + continue; + } + + double floor = entry.Value - baseline.Tolerance; + if (score < floor) + { + drops.Add( + $"'{entry.Key}' scored {score} against a baseline of {entry.Value} " + + $"and a floor of {Math.Round(floor, 4)}."); + } } - } - Assert.True( - drops.Count == 0, - $"execution '{executionName}' dropped. {string.Join(" ", drops)} " - + $"The measured scores are in {MeasuredPath}."); + Assert.True( + drops.Count == 0, + $"execution '{executionName}' dropped. {string.Join(" ", drops)} " + + $"The measured scores are in {MeasuredPath}."); + } } } diff --git a/tests/AgentCore.Evals/DatasetFixture.cs b/tests/AgentCore.Evals/DatasetFixture.cs index 5b5930fa..caa5fb39 100644 --- a/tests/AgentCore.Evals/DatasetFixture.cs +++ b/tests/AgentCore.Evals/DatasetFixture.cs @@ -1,32 +1,33 @@ using Xunit; -namespace AgentCore.Evals; - -/// -/// Builds the golden-set harness once for a test class. -/// -/// -/// Opening the knowledge base costs a socket, a secret read, and an embedding conversation, and every row of -/// a suite reads the same one. The fixture builds it once and holds it for the class. -/// -public sealed class DatasetFixture : IAsyncLifetime +namespace AgentCore.Evals { - /// Gets the harness, or when this run names no golden set. - public DatasetHarness? Harness { get; private set; } - - /// - public async ValueTask InitializeAsync() + /// + /// Builds the golden-set harness once for a test class. + /// + /// + /// Opening the knowledge base costs a socket, a secret read, and an embedding conversation, and every row of + /// a suite reads the same one. The fixture builds it once and holds it for the class. + /// + public sealed class DatasetFixture : IAsyncLifetime { - if (EvalHarness.DatasetIsConfigured) + /// Gets the harness, or when this run names no golden set. + public DatasetHarness? Harness { get; private set; } + + /// + public async ValueTask InitializeAsync() { - Harness = await DatasetHarness.CreateAsync(TestContext.Current.CancellationToken); + if (EvalHarness.DatasetIsConfigured) + { + Harness = await DatasetHarness.CreateAsync(TestContext.Current.CancellationToken); + } } - } - /// - public ValueTask DisposeAsync() - { - Harness?.Dispose(); - return ValueTask.CompletedTask; + /// + public ValueTask DisposeAsync() + { + Harness?.Dispose(); + return ValueTask.CompletedTask; + } } } diff --git a/tests/AgentCore.Evals/DatasetHarness.cs b/tests/AgentCore.Evals/DatasetHarness.cs index c69ff45e..c4efd18c 100644 --- a/tests/AgentCore.Evals/DatasetHarness.cs +++ b/tests/AgentCore.Evals/DatasetHarness.cs @@ -6,121 +6,119 @@ using AgentCore.Application.Secrets; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Microsoft.Extensions.AI; -using Microsoft.Extensions.AI.Evaluation; using Microsoft.Extensions.AI.Evaluation.Reporting; using Microsoft.Extensions.AI.Evaluation.Reporting.Storage; using OpenAI; -namespace AgentCore.Evals; - -/// -/// Everything one golden-set retrieval run needs, built once from one configuration document. -/// -/// -/// -/// The harness composes the adapter the shipped host composes, so the score describes the retrieval -/// stack a deployment runs: one , built from -/// providers.knowledge of the document AGENTCORE_EVAL_CONFIG names. -/// -/// -/// Ruling 14: passes for requireScope. A -/// golden set measures recall against the whole corpus a deployment holds, and -/// carries no facet a row could be checked against. Forcing every search through one fixed -/// KnowledgeScope would either filter rows about a different facet out of the corpus, or need -/// per-row facet data the row format does not have -- either way the recall number would describe -/// that one scope rather than the corpus the set exists to measure. scopeDeclared stays -/// regardless: it costs nothing here, since -/// always reports , and it is the safer default if this -/// harness is ever pointed at a second adapter that does not. -/// -/// -public sealed class DatasetHarness : IDisposable +namespace AgentCore.Evals { - /// The environment variable naming the embedding model this harness queries with. + /// + /// Everything one golden-set retrieval run needs, built once from one configuration document. + /// /// - /// providers.knowledge names the store and never the embedder -- the width check in - /// is what proves a deployment's chosen - /// model matches the collection, not a document field, matching the "AgentCore never creates" - /// stance documents for the store itself. - /// A deployment's own kb sync run is what actually fixes the model, so this harness has to - /// be told the same value some other way. It reads it here rather than inventing a schema field - /// no production host would ever read. + /// + /// The harness composes the adapter the shipped host composes, so the score describes the retrieval + /// stack a deployment runs: one , built from + /// providers.knowledge of the document AGENTCORE_EVAL_CONFIG names. + /// + /// + /// Ruling 14: passes for requireScope. A + /// golden set measures recall against the whole corpus a deployment holds, and + /// carries no facet a row could be checked against. Forcing every search through one fixed + /// KnowledgeScope would either filter rows about a different facet out of the corpus, or need + /// per-row facet data the row format does not have -- either way the recall number would describe + /// that one scope rather than the corpus the set exists to measure. scopeDeclared stays + /// regardless: it costs nothing here, since + /// always reports , and it is the safer default if this + /// harness is ever pointed at a second adapter that does not. + /// /// - public const string EmbeddingModelVariable = "AGENTCORE_EVAL_EMBEDDING_MODEL"; - - /// The model used when the environment names none. - public const string DefaultEmbeddingModel = "text-embedding-3-small"; - - private readonly IKnowledgeRetrievalPort _search; - - private DatasetHarness( - AgentCoreConfiguration configuration, IKnowledgeRetrievalPort search, ReportingConfiguration reporting) + public sealed class DatasetHarness : IDisposable { - Configuration = configuration; - _search = search; - Reporting = reporting; - } + /// The environment variable naming the embedding model this harness queries with. + /// + /// providers.knowledge names the store and never the embedder -- the width check in + /// is what proves a deployment's chosen + /// model matches the collection, not a document field, matching the "AgentCore never creates" + /// stance documents for the store itself. + /// A deployment's own kb sync run is what actually fixes the model, so this harness has to + /// be told the same value some other way. It reads it here rather than inventing a schema field + /// no production host would ever read. + /// + public const string EmbeddingModelVariable = "AGENTCORE_EVAL_EMBEDDING_MODEL"; + + /// The model used when the environment names none. + public const string DefaultEmbeddingModel = "text-embedding-3-small"; + + private DatasetHarness( + AgentCoreConfiguration configuration, IKnowledgeRetrievalPort search, ReportingConfiguration reporting) + { + Configuration = configuration; + Search = search; + Reporting = reporting; + } - /// Gets the document this run reads. - public AgentCoreConfiguration Configuration { get; } + /// Gets the document this run reads. + public AgentCoreConfiguration Configuration { get; } - /// Gets the ranking port providers.knowledge names. - public IKnowledgeRetrievalPort Search => _search; + /// Gets the ranking port providers.knowledge names. + public IKnowledgeRetrievalPort Search { get; } - /// Gets the reporting configuration the scenario runs write through. - public ReportingConfiguration Reporting { get; } + /// Gets the reporting configuration the scenario runs write through. + public ReportingConfiguration Reporting { get; } - /// Builds the harness from the document AGENTCORE_EVAL_CONFIG names. - public static async ValueTask CreateAsync(CancellationToken cancellationToken = default) - { - var configuration = EvalHarness.LoadConfiguration(); - var embeddings = await BuildEmbeddingsAsync(cancellationToken).ConfigureAwait(false); - - var search = await CompositeKnowledgeStoreFactory - .CreateAsync( + /// Builds the harness from the document AGENTCORE_EVAL_CONFIG names. + public static async ValueTask CreateAsync(CancellationToken cancellationToken = default) + { + AgentCoreConfiguration configuration = EvalHarness.LoadConfiguration(); + IEmbeddingGenerator> embeddings = await BuildEmbeddingsAsync(cancellationToken).ConfigureAwait(false); + + IKnowledgeRetrievalPort? search = await CompositeKnowledgeStoreFactory + .CreateAsync( + configuration, + EvalHarness.Secrets, + [new QdrantKnowledgeAdapter(embeddings)], + embeddings: null, + scopeDeclared: true, + requireScope: false, + cancellationToken) + .ConfigureAwait(false); + + return search is null + ? throw new InvalidOperationException( + "providers.knowledge has to name a store for the golden set to run.") + : new DatasetHarness( configuration, - EvalHarness.Secrets, - [new QdrantKnowledgeAdapter(embeddings)], - embeddings: null, - scopeDeclared: true, - requireScope: false, - cancellationToken) - .ConfigureAwait(false); + search, + DiskBasedReportingConfiguration.Create( + storageRootPath: EvalHarness.StorageRoot, + evaluators: [new DocumentRecallEvaluator()], + enableResponseCaching: false, + executionName: EvalHarness.DatasetExecution)); + } - if (search is null) + /// + public void Dispose() { - throw new InvalidOperationException( - "providers.knowledge has to name a store for the golden set to run."); + (Search as IDisposable)?.Dispose(); } - return new DatasetHarness( - configuration, - search, - DiskBasedReportingConfiguration.Create( - storageRootPath: EvalHarness.StorageRoot, - evaluators: [new DocumentRecallEvaluator()], - enableResponseCaching: false, - executionName: EvalHarness.DatasetExecution)); - } - - /// - public void Dispose() => (_search as IDisposable)?.Dispose(); - - /// Builds the embedder this harness queries with, over the OpenAI credential the chat clients share. - private static async ValueTask>> BuildEmbeddingsAsync( - CancellationToken cancellationToken) - { - var apiKey = await EvalHarness.Secrets - .RequireAsync( - KnownSecrets.OpenAi, - because: "The golden set embeds each query before it searches Qdrant.", - cancellationToken: cancellationToken) - .ConfigureAwait(false); - - var model = Environment.GetEnvironmentVariable(EmbeddingModelVariable) is { Length: > 0 } named - ? named - : DefaultEmbeddingModel; - - return new OpenAIClient(new ApiKeyCredential(apiKey)).GetEmbeddingClient(model).AsIEmbeddingGenerator(); + /// Builds the embedder this harness queries with, over the OpenAI credential the chat clients share. + private static async ValueTask>> BuildEmbeddingsAsync( + CancellationToken cancellationToken) + { + string apiKey = await EvalHarness.Secrets + .RequireAsync( + KnownSecrets.OpenAi, + because: "The golden set embeds each query before it searches Qdrant.", + cancellationToken: cancellationToken) + .ConfigureAwait(false); + + string model = Environment.GetEnvironmentVariable(EmbeddingModelVariable) is { Length: > 0 } named + ? named + : DefaultEmbeddingModel; + + return new OpenAIClient(new ApiKeyCredential(apiKey)).GetEmbeddingClient(model).AsIEmbeddingGenerator(); + } } } diff --git a/tests/AgentCore.Evals/EvalGateCollection.cs b/tests/AgentCore.Evals/EvalGateCollection.cs index b6425c02..54f3362c 100644 --- a/tests/AgentCore.Evals/EvalGateCollection.cs +++ b/tests/AgentCore.Evals/EvalGateCollection.cs @@ -1,27 +1,28 @@ using Xunit; -namespace AgentCore.Evals; - -/// -/// The collection of the one class that only reads the disk result store. -/// -/// -/// -/// The gate measures results it did not produce. Everything it reads is written by the suites in -/// , so it is the last thing in the assembly that may run. A run that -/// starts it first measures an empty directory and fails on a missing result rather than on a score. -/// -/// -/// A collection is the only unit the runner will order, so the gate needs one of its own. It cannot -/// share and still be ordered, because -/// sorts collections and never the classes inside one. -/// That split is the whole reason this type exists. is what -/// then puts it last. -/// -/// -[CollectionDefinition(Name)] -public sealed class EvalGateCollection +namespace AgentCore.Evals { - /// The name the gate carries. - public const string Name = "EvalGate"; + /// + /// The collection of the one class that only reads the disk result store. + /// + /// + /// + /// The gate measures results it did not produce. Everything it reads is written by the suites in + /// , so it is the last thing in the assembly that may run. A run that + /// starts it first measures an empty directory and fails on a missing result rather than on a score. + /// + /// + /// A collection is the only unit the runner will order, so the gate needs one of its own. It cannot + /// share and still be ordered, because + /// sorts collections and never the classes inside one. + /// That split is the whole reason this type exists. is what + /// then puts it last. + /// + /// + [CollectionDefinition(Name)] + public sealed class EvalGateCollection + { + /// The name the gate carries. + public const string Name = "EvalGate"; + } } diff --git a/tests/AgentCore.Evals/EvalHarness.cs b/tests/AgentCore.Evals/EvalHarness.cs index e9297d47..fe0ea1a1 100644 --- a/tests/AgentCore.Evals/EvalHarness.cs +++ b/tests/AgentCore.Evals/EvalHarness.cs @@ -2,99 +2,100 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Infrastructure.Secrets; -namespace AgentCore.Evals; - -/// -/// The settings both eval suites read. -/// -/// -/// -/// The store is on disk, and is the directory dotnet aieval report -/// reads. -/// -/// -/// The judge comes from evaluation.judge of the configuration document, and never from an -/// environment variable of its own. One document then tunes the online sampled path of T18 and this -/// offline gate together, and the key it reads is the one providers.llm already resolves. -/// -/// -public static class EvalHarness +namespace AgentCore.Evals { - /// The directory that holds the results and the response cache. - public const string StorageRoot = "eval-results"; + /// + /// The settings both eval suites read. + /// + /// + /// + /// The store is on disk, and is the directory dotnet aieval report + /// reads. + /// + /// + /// The judge comes from evaluation.judge of the configuration document, and never from an + /// environment variable of its own. One document then tunes the online sampled path of T18 and this + /// offline gate together, and the key it reads is the one providers.llm already resolves. + /// + /// + public static class EvalHarness + { + /// The directory that holds the results and the response cache. + public const string StorageRoot = "eval-results"; - /// The environment variable that names the configuration document of the real set. - public const string ConfigurationVariable = "AGENTCORE_EVAL_CONFIG"; + /// The environment variable that names the configuration document of the real set. + public const string ConfigurationVariable = "AGENTCORE_EVAL_CONFIG"; - /// The execution name of the golden-set suite. - public const string DatasetExecution = "golden-set"; + /// The execution name of the golden-set suite. + public const string DatasetExecution = "golden-set"; - /// The environment variable naming the Qdrant this harness reaches for. - /// - /// Read for presence only, as a third precondition beside - /// and : a deployer who sets the dataset and the configuration - /// document with no Qdrant target running should see a skip that names what is still missing, - /// rather than a raw connection failure the first time a row runs. AgentCore.Infrastructure - /// .Tests' QdrantServer reads the same variable, but this is a second test project and - /// gains nothing by referencing that one just to reuse a string, so the name is kept here as its - /// own constant instead. - /// - public const string QdrantVariable = "AGENTCORE_TEST_QDRANT"; + /// The environment variable naming the Qdrant this harness reaches for. + /// + /// Read for presence only, as a third precondition beside + /// and : a deployer who sets the dataset and the configuration + /// document with no Qdrant target running should see a skip that names what is still missing, + /// rather than a raw connection failure the first time a row runs. AgentCore.Infrastructure + /// .Tests' QdrantServer reads the same variable, but this is a second test project and + /// gains nothing by referencing that one just to reuse a string, so the name is kept here as its + /// own constant instead. + /// + public const string QdrantVariable = "AGENTCORE_TEST_QDRANT"; - /// The chain a deployment resolves a secret through: the environment, then a mounted file. - public static ChainedSecretResolver Secrets { get; } = - new([new EnvironmentSecretResolver(), new FileSecretResolver()]); + /// The chain a deployment resolves a secret through: the environment, then a mounted file. + public static ChainedSecretResolver Secrets { get; } = + new([new EnvironmentSecretResolver(), new FileSecretResolver()]); - /// Gets the path of the configuration document, or when none is named. - public static string? ConfigurationPath - { - get + /// Gets the path of the configuration document, or when none is named. + public static string? ConfigurationPath { - var path = Environment.GetEnvironmentVariable(ConfigurationVariable); - return string.IsNullOrEmpty(path) ? null : path; + get + { + string? path = Environment.GetEnvironmentVariable(ConfigurationVariable); + return string.IsNullOrEmpty(path) ? null : path; + } } - } - /// Gets whether a golden-set run is possible at all. - public static bool DatasetIsConfigured => DatasetSkipReason is null; + /// Gets whether a golden-set run is possible at all. + public static bool DatasetIsConfigured => DatasetSkipReason is null; - /// Gets why a golden-set run cannot happen, or when it can. - /// - /// Names every missing variable in one message, not just the first one this checks, so a deployer - /// who sets one and forgets another learns which on the first red run instead of chasing them one - /// at a time. - /// - public static string? DatasetSkipReason - { - get + /// Gets why a golden-set run cannot happen, or when it can. + /// + /// Names every missing variable in one message, not just the first one this checks, so a deployer + /// who sets one and forgets another learns which on the first red run instead of chasing them one + /// at a time. + /// + public static string? DatasetSkipReason { - List missing = []; - if (GoldenSet.DatasetPath is null) + get { - missing.Add(GoldenSet.DatasetVariable); - } + List missing = []; + if (GoldenSet.DatasetPath is null) + { + missing.Add(GoldenSet.DatasetVariable); + } - if (ConfigurationPath is null) - { - missing.Add(ConfigurationVariable); - } + if (ConfigurationPath is null) + { + missing.Add(ConfigurationVariable); + } - if (Environment.GetEnvironmentVariable(QdrantVariable) is not { Length: > 0 }) - { - missing.Add(QdrantVariable); - } + if (Environment.GetEnvironmentVariable(QdrantVariable) is not { Length: > 0 }) + { + missing.Add(QdrantVariable); + } - return missing.Count == 0 ? null : $"set {string.Join(" and ", missing)} to run the golden set."; + return missing.Count == 0 ? null : $"set {string.Join(" and ", missing)} to run the golden set."; + } } - } - /// Reads the configuration document of the real set. - /// No document is named. - public static AgentCoreConfiguration LoadConfiguration() - { - var path = ConfigurationPath - ?? throw new InvalidOperationException($"{ConfigurationVariable} names no configuration document."); + /// Reads the configuration document of the real set. + /// No document is named. + public static AgentCoreConfiguration LoadConfiguration() + { + string path = ConfigurationPath + ?? throw new InvalidOperationException($"{ConfigurationVariable} names no configuration document."); - return ConfigurationLoader.LoadFile(path); + return ConfigurationLoader.LoadFile(path); + } } } diff --git a/tests/AgentCore.Evals/EvalHarnessTests.cs b/tests/AgentCore.Evals/EvalHarnessTests.cs index cfce7885..e4d624d6 100644 --- a/tests/AgentCore.Evals/EvalHarnessTests.cs +++ b/tests/AgentCore.Evals/EvalHarnessTests.cs @@ -1,100 +1,101 @@ using Xunit; -namespace AgentCore.Evals; - -/// -/// Checks that names every missing variable, not just -/// the first one it finds. -/// -/// -/// A deployer who sets AGENTCORE_EVAL_DATASET and forgets AGENTCORE_TEST_QDRANT, or the -/// other way around, has to be told which one is still missing. A reason that only ever names the -/// first gate it checks is the silent-skip failure mode this suite exists to rule out. -/// -public sealed class EvalHarnessTests +namespace AgentCore.Evals { - [Fact] - public void DatasetSkipReason_NothingSet_NamesAllThreeVariables() - { - using var scope = EnvironmentScope.ClearAll(); - - var reason = EvalHarness.DatasetSkipReason; - - Assert.NotNull(reason); - Assert.Contains(GoldenSet.DatasetVariable, reason, StringComparison.Ordinal); - Assert.Contains(EvalHarness.ConfigurationVariable, reason, StringComparison.Ordinal); - Assert.Contains(EvalHarness.QdrantVariable, reason, StringComparison.Ordinal); - Assert.False(EvalHarness.DatasetIsConfigured); - } - - [Fact] - public void DatasetSkipReason_OnlyQdrantSet_NamesTheDatasetAndTheConfiguration() + /// + /// Checks that names every missing variable, not just + /// the first one it finds. + /// + /// + /// A deployer who sets AGENTCORE_EVAL_DATASET and forgets AGENTCORE_TEST_QDRANT, or the + /// other way around, has to be told which one is still missing. A reason that only ever names the + /// first gate it checks is the silent-skip failure mode this suite exists to rule out. + /// + public sealed class EvalHarnessTests { - using var scope = EnvironmentScope.ClearAll(); - Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, "localhost:6334"); + [Fact] + public void DatasetSkipReason_NothingSet_NamesAllThreeVariables() + { + using EnvironmentScope scope = EnvironmentScope.ClearAll(); - var reason = EvalHarness.DatasetSkipReason; + string? reason = EvalHarness.DatasetSkipReason; - Assert.NotNull(reason); - Assert.Contains(GoldenSet.DatasetVariable, reason, StringComparison.Ordinal); - Assert.Contains(EvalHarness.ConfigurationVariable, reason, StringComparison.Ordinal); - Assert.DoesNotContain(EvalHarness.QdrantVariable, reason, StringComparison.Ordinal); - Assert.False(EvalHarness.DatasetIsConfigured); - } + Assert.NotNull(reason); + Assert.Contains(GoldenSet.DatasetVariable, reason, StringComparison.Ordinal); + Assert.Contains(EvalHarness.ConfigurationVariable, reason, StringComparison.Ordinal); + Assert.Contains(EvalHarness.QdrantVariable, reason, StringComparison.Ordinal); + Assert.False(EvalHarness.DatasetIsConfigured); + } - [Fact] - public void DatasetSkipReason_DatasetAndConfigurationSetButNotQdrant_NamesOnlyQdrant() - { - using var scope = EnvironmentScope.ClearAll(); - Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, "golden.jsonl"); - Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, "agent.yaml"); + [Fact] + public void DatasetSkipReason_OnlyQdrantSet_NamesTheDatasetAndTheConfiguration() + { + using EnvironmentScope scope = EnvironmentScope.ClearAll(); + Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, "localhost:6334"); - var reason = EvalHarness.DatasetSkipReason; + string? reason = EvalHarness.DatasetSkipReason; - Assert.NotNull(reason); - Assert.DoesNotContain(GoldenSet.DatasetVariable, reason, StringComparison.Ordinal); - Assert.DoesNotContain(EvalHarness.ConfigurationVariable, reason, StringComparison.Ordinal); - Assert.Contains(EvalHarness.QdrantVariable, reason, StringComparison.Ordinal); - Assert.False(EvalHarness.DatasetIsConfigured); - } + Assert.NotNull(reason); + Assert.Contains(GoldenSet.DatasetVariable, reason, StringComparison.Ordinal); + Assert.Contains(EvalHarness.ConfigurationVariable, reason, StringComparison.Ordinal); + Assert.DoesNotContain(EvalHarness.QdrantVariable, reason, StringComparison.Ordinal); + Assert.False(EvalHarness.DatasetIsConfigured); + } - [Fact] - public void DatasetSkipReason_AllThreeSet_IsNull() - { - using var scope = EnvironmentScope.ClearAll(); - Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, "golden.jsonl"); - Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, "agent.yaml"); - Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, "localhost:6334"); + [Fact] + public void DatasetSkipReason_DatasetAndConfigurationSetButNotQdrant_NamesOnlyQdrant() + { + using EnvironmentScope scope = EnvironmentScope.ClearAll(); + Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, "golden.jsonl"); + Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, "agent.yaml"); - Assert.Null(EvalHarness.DatasetSkipReason); - Assert.True(EvalHarness.DatasetIsConfigured); - } + string? reason = EvalHarness.DatasetSkipReason; - /// Saves the three variables this suite touches, and restores them on dispose. - /// - /// This assembly disables parallelisation (see AssemblyInfo.cs), so a test that changes - /// process-wide environment variables cannot race another test reading the same three names. - /// - private sealed class EnvironmentScope : IDisposable - { - private readonly string? _dataset = Environment.GetEnvironmentVariable(GoldenSet.DatasetVariable); - private readonly string? _configuration = Environment.GetEnvironmentVariable(EvalHarness.ConfigurationVariable); - private readonly string? _qdrant = Environment.GetEnvironmentVariable(EvalHarness.QdrantVariable); + Assert.NotNull(reason); + Assert.DoesNotContain(GoldenSet.DatasetVariable, reason, StringComparison.Ordinal); + Assert.DoesNotContain(EvalHarness.ConfigurationVariable, reason, StringComparison.Ordinal); + Assert.Contains(EvalHarness.QdrantVariable, reason, StringComparison.Ordinal); + Assert.False(EvalHarness.DatasetIsConfigured); + } - public static EnvironmentScope ClearAll() + [Fact] + public void DatasetSkipReason_AllThreeSet_IsNull() { - EnvironmentScope scope = new(); - Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, null); - Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, null); - Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, null); - return scope; + using EnvironmentScope scope = EnvironmentScope.ClearAll(); + Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, "golden.jsonl"); + Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, "agent.yaml"); + Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, "localhost:6334"); + + Assert.Null(EvalHarness.DatasetSkipReason); + Assert.True(EvalHarness.DatasetIsConfigured); } - public void Dispose() + /// Saves the three variables this suite touches, and restores them on dispose. + /// + /// This assembly disables parallelisation (see AssemblyInfo.cs), so a test that changes + /// process-wide environment variables cannot race another test reading the same three names. + /// + private sealed class EnvironmentScope : IDisposable { - Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, _dataset); - Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, _configuration); - Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, _qdrant); + private readonly string? _dataset = Environment.GetEnvironmentVariable(GoldenSet.DatasetVariable); + private readonly string? _configuration = Environment.GetEnvironmentVariable(EvalHarness.ConfigurationVariable); + private readonly string? _qdrant = Environment.GetEnvironmentVariable(EvalHarness.QdrantVariable); + + public static EnvironmentScope ClearAll() + { + EnvironmentScope scope = new(); + Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, null); + Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, null); + Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, null); + return scope; + } + + public void Dispose() + { + Environment.SetEnvironmentVariable(GoldenSet.DatasetVariable, _dataset); + Environment.SetEnvironmentVariable(EvalHarness.ConfigurationVariable, _configuration); + Environment.SetEnvironmentVariable(EvalHarness.QdrantVariable, _qdrant); + } } } } diff --git a/tests/AgentCore.Evals/EvalStoreCollection.cs b/tests/AgentCore.Evals/EvalStoreCollection.cs index f041fa48..12b1ba65 100644 --- a/tests/AgentCore.Evals/EvalStoreCollection.cs +++ b/tests/AgentCore.Evals/EvalStoreCollection.cs @@ -1,34 +1,35 @@ using Xunit; -namespace AgentCore.Evals; - -/// -/// The collection of every class that writes results to the disk store. -/// -/// -/// -/// A test run gives each class a collection of its own and runs collections in parallel. Every class -/// in this one reads or writes the same store under , and -/// DiskBasedResultStore opens a result file without sharing it: a write creates the file, a -/// read holds it open, and neither lets the other in. Overlap them on one file and the write throws -/// an . The suite then goes red for a reason that has nothing to do with a -/// score, and it does so only sometimes, which is the worst way for a gate to fail. -/// -/// -/// Naming this collection puts those classes in one queue, so no two ever hold the same result file -/// at once. It buys nothing else. It fixes no order, and the classes in it may run in any order among -/// themselves, which is fine because none of them reads what another wrote. -/// -/// -/// does read what they wrote, and that is why it is not in here. It -/// sits alone in so that can -/// put it after this one: an orderer sorts collections, so a class that needs to run last needs a -/// collection to itself. -/// -/// -[CollectionDefinition(Name)] -public sealed class EvalStoreCollection +namespace AgentCore.Evals { - /// The name each class that writes to the store carries. - public const string Name = "EvalStore"; + /// + /// The collection of every class that writes results to the disk store. + /// + /// + /// + /// A test run gives each class a collection of its own and runs collections in parallel. Every class + /// in this one reads or writes the same store under , and + /// DiskBasedResultStore opens a result file without sharing it: a write creates the file, a + /// read holds it open, and neither lets the other in. Overlap them on one file and the write throws + /// an . The suite then goes red for a reason that has nothing to do with a + /// score, and it does so only sometimes, which is the worst way for a gate to fail. + /// + /// + /// Naming this collection puts those classes in one queue, so no two ever hold the same result file + /// at once. It buys nothing else. It fixes no order, and the classes in it may run in any order among + /// themselves, which is fine because none of them reads what another wrote. + /// + /// + /// does read what they wrote, and that is why it is not in here. It + /// sits alone in so that can + /// put it after this one: an orderer sorts collections, so a class that needs to run last needs a + /// collection to itself. + /// + /// + [CollectionDefinition(Name)] + public sealed class EvalStoreCollection + { + /// The name each class that writes to the store carries. + public const string Name = "EvalStore"; + } } diff --git a/tests/AgentCore.Evals/FixtureEvalTests.cs b/tests/AgentCore.Evals/FixtureEvalTests.cs index 88141d1b..bd222d6c 100644 --- a/tests/AgentCore.Evals/FixtureEvalTests.cs +++ b/tests/AgentCore.Evals/FixtureEvalTests.cs @@ -1,29 +1,30 @@ using Xunit; -namespace AgentCore.Evals; - -/// -/// Checks the shape of the synthetic golden set that travels with this repository. -/// -/// -/// This is a format check only, and it always runs. The retrieval self-test that used to run here -/// read a five-file knowledge base through the old filesystem store; that store is gone (Ruling 9), -/// and the store that replaced it needs a real embedding model for its dense leg, which this offline -/// suite has no key for. So this class proves the row format still parses and never scores a search. -/// -public sealed class FixtureEvalTests +namespace AgentCore.Evals { - [Fact] - public void Fixture_HoldsEnoughRowsToExerciseTheFormat() + /// + /// Checks the shape of the synthetic golden set that travels with this repository. + /// + /// + /// This is a format check only, and it always runs. The retrieval self-test that used to run here + /// read a five-file knowledge base through the old filesystem store; that store is gone (Ruling 9), + /// and the store that replaced it needs a real embedding model for its dense leg, which this offline + /// suite has no key for. So this class proves the row format still parses and never scores a search. + /// + public sealed class FixtureEvalTests { - // A row with one expected document and a row with two exercise both branches of the metric. + [Fact] + public void Fixture_HoldsEnoughRowsToExerciseTheFormat() + { + // A row with one expected document and a row with two exercise both branches of the metric. - // Arrange, Act - var rows = GoldenSet.Load(GoldenSet.FixturePath); + // Arrange, Act + IReadOnlyList rows = GoldenSet.Load(GoldenSet.FixturePath); - // Assert - Assert.Contains(rows, row => row.ExpectedDocumentIds.Count == 1); - Assert.Contains(rows, row => row.ExpectedDocumentIds.Count > 1); - Assert.Contains(rows, row => row.ExpectedFaultCodes.Count > 0); + // Assert + Assert.Contains(rows, row => row.ExpectedDocumentIds.Count == 1); + Assert.Contains(rows, row => row.ExpectedDocumentIds.Count > 1); + Assert.Contains(rows, row => row.ExpectedFaultCodes.Count > 0); + } } } diff --git a/tests/AgentCore.Evals/GateLastCollectionOrderer.cs b/tests/AgentCore.Evals/GateLastCollectionOrderer.cs index 9a6363d5..4ada367a 100644 --- a/tests/AgentCore.Evals/GateLastCollectionOrderer.cs +++ b/tests/AgentCore.Evals/GateLastCollectionOrderer.cs @@ -1,50 +1,55 @@ using Xunit.Sdk; using Xunit.v3; -namespace AgentCore.Evals; - -/// -/// Runs after every other collection in this assembly. -/// -/// -/// -/// The gate reads the scores the eval suites write, so it has to run after them. Until this type -/// existed the only thing supplying that order was a CI convention: two commands, one filtered to -/// Category!=Gate and one to Category=Gate. A person who clones the repository and runs -/// dotnet test once runs neither, measures an empty store, and sees a red gate that says -/// nothing about the model. This puts the rule in the assembly instead of in a command someone has to -/// remember, so the plain run is the one that behaves. -/// -/// -/// The sort reads and not the display -/// name, because the class name is the thing the compiler can check. Rename -/// and this still holds; delete the type and this stops -/// building, which is the failure worth having. A collection the runner invented for a class that -/// named none reports an empty class name and sorts with the rest. -/// -/// -/// Everything that is not the gate sorts equal, and is stable, so the writers keep whatever order -/// discovery gave them. This type fixes one thing and deliberately fixes nothing else. -/// -/// -/// Ordering collections only means something when they run one at a time, which is why the assembly -/// also disables parallelisation. See AssemblyInfo.cs. -/// -/// -public sealed class GateLastCollectionOrderer : ITestCollectionOrderer +namespace AgentCore.Evals { - private static readonly string GateCollection = typeof(EvalGateCollection).FullName!; + /// + /// Runs after every other collection in this assembly. + /// + /// + /// + /// The gate reads the scores the eval suites write, so it has to run after them. Until this type + /// existed the only thing supplying that order was a CI convention: two commands, one filtered to + /// Category!=Gate and one to Category=Gate. A person who clones the repository and runs + /// dotnet test once runs neither, measures an empty store, and sees a red gate that says + /// nothing about the model. This puts the rule in the assembly instead of in a command someone has to + /// remember, so the plain run is the one that behaves. + /// + /// + /// The sort reads and not the display + /// name, because the class name is the thing the compiler can check. Rename + /// and this still holds; delete the type and this stops + /// building, which is the failure worth having. A collection the runner invented for a class that + /// named none reports an empty class name and sorts with the rest. + /// + /// + /// Everything that is not the gate sorts equal, and is stable, so the writers keep whatever order + /// discovery gave them. This type fixes one thing and deliberately fixes nothing else. + /// + /// + /// Ordering collections only means something when they run one at a time, which is why the assembly + /// also disables parallelisation. See AssemblyInfo.cs. + /// + /// + public sealed class GateLastCollectionOrderer : ITestCollectionOrderer + { + private static readonly string GateCollection = typeof(EvalGateCollection).FullName!; - /// - public IReadOnlyCollection OrderTestCollections( - IReadOnlyCollection testCollections) - where TTestCollection : ITestCollection - // A method group will not bind here: TTestCollection is a type parameter, so the compiler - // wants the conversion to ITestCollection written out. The lambda writes it out. - => [.. testCollections.OrderBy(collection => RunsLast(collection))]; + /// + public IReadOnlyCollection OrderTestCollections( + IReadOnlyCollection testCollections) + where TTestCollection : ITestCollection + { + // A method group will not bind here: TTestCollection is a type parameter, so the compiler + // wants the conversion to ITestCollection written out. The lambda writes it out. + return [.. testCollections.OrderBy(collection => RunsLast(collection))]; + } - /// Sorts the gate to the back and leaves everything else where it was. - private static int RunsLast(ITestCollection collection) - => string.Equals(collection.TestCollectionClassName, GateCollection, StringComparison.Ordinal) ? 1 : 0; + /// Sorts the gate to the back and leaves everything else where it was. + private static int RunsLast(ITestCollection collection) + { + return string.Equals(collection.TestCollectionClassName, GateCollection, StringComparison.Ordinal) ? 1 : 0; + } + } } diff --git a/tests/AgentCore.Evals/GoldenRow.cs b/tests/AgentCore.Evals/GoldenRow.cs index f2126385..2d08cb98 100644 --- a/tests/AgentCore.Evals/GoldenRow.cs +++ b/tests/AgentCore.Evals/GoldenRow.cs @@ -1,43 +1,47 @@ using System.Text.Json.Serialization; -namespace AgentCore.Evals; - -/// -/// One row of a golden set. -/// -/// -/// -/// The row holds what a person can check by hand: the question, the file that answers it, and the -/// fault codes a correct answer states. It holds no expected reply text. Two correct replies word the -/// same fact differently, so a string comparison over the reply would call one of them wrong. -/// -/// -/// The row names a document and never a passage. A knowledge base that re-chunks the same text -/// answers the same question, and a score that moved would report a failure that is not there. -/// -/// -public sealed record GoldenRow +namespace AgentCore.Evals { - /// Gets the stable id of this row. It names the scenario in the report. - [JsonPropertyName("id")] - public required string Id { get; init; } + /// + /// One row of a golden set. + /// + /// + /// + /// The row holds what a person can check by hand: the question, the file that answers it, and the + /// fault codes a correct answer states. It holds no expected reply text. Two correct replies word the + /// same fact differently, so a string comparison over the reply would call one of them wrong. + /// + /// + /// The row names a document and never a passage. A knowledge base that re-chunks the same text + /// answers the same question, and a score that moved would report a failure that is not there. + /// + /// + public sealed record GoldenRow + { + /// Gets the stable id of this row. It names the scenario in the report. + [JsonPropertyName("id")] + public required string Id { get; init; } - /// Gets what the caller asks. - [JsonPropertyName("query")] - public required string Query { get; init; } + /// Gets what the caller asks. + [JsonPropertyName("query")] + public required string Query { get; init; } - /// Gets the document ids that answer the query. - [JsonPropertyName("expectedDocumentIds")] - public required IReadOnlyList ExpectedDocumentIds { get; init; } + /// Gets the document ids that answer the query. + [JsonPropertyName("expectedDocumentIds")] + public required IReadOnlyList ExpectedDocumentIds { get; init; } - /// Gets the fault codes a correct reply states. It is empty when the row names none. - [JsonPropertyName("expectedFaultCodes")] - public IReadOnlyList ExpectedFaultCodes { get; init; } = []; + /// Gets the fault codes a correct reply states. It is empty when the row names none. + [JsonPropertyName("expectedFaultCodes")] + public IReadOnlyList ExpectedFaultCodes { get; init; } = []; - /// Gets the free labels that slice the report, such as a machine family. - [JsonPropertyName("tags")] - public IReadOnlyList Tags { get; init; } = []; + /// Gets the free labels that slice the report, such as a machine family. + [JsonPropertyName("tags")] + public IReadOnlyList Tags { get; init; } = []; - /// Names this row in a test display and in the report. - public override string ToString() => Id; + /// Names this row in a test display and in the report. + public override string ToString() + { + return Id; + } + } } diff --git a/tests/AgentCore.Evals/GoldenSet.cs b/tests/AgentCore.Evals/GoldenSet.cs index 786cf50c..8830ce5b 100644 --- a/tests/AgentCore.Evals/GoldenSet.cs +++ b/tests/AgentCore.Evals/GoldenSet.cs @@ -1,94 +1,100 @@ using System.Text.Json; using Xunit; -namespace AgentCore.Evals; - -/// -/// Reads a golden set from one JSON Lines file. -/// -/// -/// -/// JSON Lines, and not one JSON array, because a diff of one changed row then shows one changed line. -/// A golden set is reviewed by a person, so the diff is part of the format. -/// -/// -/// Two sets exist, and they answer two questions. The fixture travels with this repository and proves -/// the harness works. The real set belongs to a deployment, holds its own knowledge base, and proves -/// that retrieval and the reply still work. The fixture never replaces the real set, and the real set -/// never replaces the fixture. -/// -/// -public static class GoldenSet +namespace AgentCore.Evals { - /// The environment variable that names the real set. + /// + /// Reads a golden set from one JSON Lines file. + /// /// - /// A deployment points this at its own file. With the variable unset, the golden-set suites skip - /// and only the fixture suite runs, so a contributor with no data still gets a green build. + /// + /// JSON Lines, and not one JSON array, because a diff of one changed row then shows one changed line. + /// A golden set is reviewed by a person, so the diff is part of the format. + /// + /// + /// Two sets exist, and they answer two questions. The fixture travels with this repository and proves + /// the harness works. The real set belongs to a deployment, holds its own knowledge base, and proves + /// that retrieval and the reply still work. The fixture never replaces the real set, and the real set + /// never replaces the fixture. + /// /// - public const string DatasetVariable = "AGENTCORE_EVAL_DATASET"; + public static class GoldenSet + { + /// The environment variable that names the real set. + /// + /// A deployment points this at its own file. With the variable unset, the golden-set suites skip + /// and only the fixture suite runs, so a contributor with no data still gets a green build. + /// + public const string DatasetVariable = "AGENTCORE_EVAL_DATASET"; - /// The synthetic set that travels with this repository. - public const string FixturePath = "golden/fixture.jsonl"; + /// The synthetic set that travels with this repository. + public const string FixturePath = "golden/fixture.jsonl"; - private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web); + private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web); - /// Gets the path of the real set, or when none is named. - public static string? DatasetPath - { - get + /// Gets the path of the real set, or when none is named. + public static string? DatasetPath { - var path = Environment.GetEnvironmentVariable(DatasetVariable); - return string.IsNullOrEmpty(path) ? null : path; + get + { + string? path = Environment.GetEnvironmentVariable(DatasetVariable); + return string.IsNullOrEmpty(path) ? null : path; + } } - } - - /// Reads one JSON Lines file. - /// The file. - /// The rows, in file order. - /// One line is not a row. - public static IReadOnlyList Load(string path) - { - ArgumentException.ThrowIfNullOrEmpty(path); - List rows = []; - var number = 0; - foreach (var line in File.ReadLines(path)) + /// Reads one JSON Lines file. + /// The file. + /// The rows, in file order. + /// One line is not a row. + public static IReadOnlyList Load(string path) { - number++; - if (line.Length == 0 || line.StartsWith('#')) + ArgumentException.ThrowIfNullOrEmpty(path); + + List rows = []; + int number = 0; + foreach (string line in File.ReadLines(path)) { - continue; + number++; + if (line.Length == 0 || line.StartsWith('#')) + { + continue; + } + + rows.Add( + JsonSerializer.Deserialize(line, Options) + ?? throw new InvalidDataException($"{path} line {number} is not a row.")); } - rows.Add( - JsonSerializer.Deserialize(line, Options) - ?? throw new InvalidDataException($"{path} line {number} is not a row.")); + return rows; } - return rows; - } - - /// Feeds the fixture rows to a theory. It never skips. - public static TheoryData Fixture() => Feed(Load(FixturePath)); - - /// - /// Feeds the rows of the real set to a theory, or nothing when no set is named. - /// - /// - /// An empty feed leaves the theory with no case to run, which is what a repository that holds no - /// data should report. It is not a failure. - /// - public static TheoryData Dataset() - => DatasetPath is { } path ? Feed(Load(path)) : []; + /// Feeds the fixture rows to a theory. It never skips. + public static TheoryData Fixture() + { + return Feed(Load(FixturePath)); + } - private static TheoryData Feed(IReadOnlyList rows) - { - TheoryData data = []; - foreach (var row in rows) + /// + /// Feeds the rows of the real set to a theory, or nothing when no set is named. + /// + /// + /// An empty feed leaves the theory with no case to run, which is what a repository that holds no + /// data should report. It is not a failure. + /// + public static TheoryData Dataset() { - data.Add(row); + return DatasetPath is { } path ? Feed(Load(path)) : []; } - return data; + private static TheoryData Feed(IReadOnlyList rows) + { + TheoryData data = []; + foreach (GoldenRow row in rows) + { + data.Add(row); + } + + return data; + } } } diff --git a/tests/AgentCore.Evals/GoldenSetEvalTests.cs b/tests/AgentCore.Evals/GoldenSetEvalTests.cs index 69b2b268..7b1fd00a 100644 --- a/tests/AgentCore.Evals/GoldenSetEvalTests.cs +++ b/tests/AgentCore.Evals/GoldenSetEvalTests.cs @@ -1,80 +1,80 @@ using AgentCore.Application.Evaluation; +using AgentCore.Domain.Knowledge; using Microsoft.Extensions.AI; using Microsoft.Extensions.AI.Evaluation; using Microsoft.Extensions.AI.Evaluation.Reporting; using Xunit; -namespace AgentCore.Evals; - -/// -/// The offline retrieval gate of D13, over the golden set a deployment owns. -/// -/// -/// -/// This suite measures one deployment's knowledge base and its retrieval settings. Neither lives in -/// this repository, so it runs only where AGENTCORE_EVAL_DATASET, AGENTCORE_EVAL_CONFIG -/// and AGENTCORE_TEST_QDRANT all name something. On main it skips, and -/// is the suite that proves the row format still parses. -/// -/// -/// A red result here means the deployment's knowledge base or retrieval settings changed, not that -/// the library broke. The usual causes are a renamed document, a re-chunked knowledge base, a new -/// embedding model, and a lowered score floor. -/// -/// -/// This was two suites until the port was narrowed to one method. The other one ran the same search -/// against the same store and asserted the same set membership with a plainer message; with no id -/// lookup left, it could no longer tell "the document is gone" from "the search did not rank it", -/// which was the only thing it added. Its message survives here, on the failure it was written for. -/// -/// -[Collection(EvalStoreCollection.Name)] -public sealed class GoldenSetEvalTests(DatasetFixture fixture) : IClassFixture +namespace AgentCore.Evals { - [Theory(SkipTestWithoutData = true)] - [MemberData(nameof(GoldenSet.Dataset), MemberType = typeof(GoldenSet))] - public async Task Retrieval_DatasetRow_ReturnsEveryExpectedDocument(GoldenRow row) + /// + /// The offline retrieval gate of D13, over the golden set a deployment owns. + /// + /// + /// + /// This suite measures one deployment's knowledge base and its retrieval settings. Neither lives in + /// this repository, so it runs only where AGENTCORE_EVAL_DATASET, AGENTCORE_EVAL_CONFIG + /// and AGENTCORE_TEST_QDRANT all name something. On main it skips, and + /// is the suite that proves the row format still parses. + /// + /// + /// A red result here means the deployment's knowledge base or retrieval settings changed, not that + /// the library broke. The usual causes are a renamed document, a re-chunked knowledge base, a new + /// embedding model, and a lowered score floor. + /// + /// + /// This was two suites until the port was narrowed to one method. The other one ran the same search + /// against the same store and asserted the same set membership with a plainer message; with no id + /// lookup left, it could no longer tell "the document is gone" from "the search did not rank it", + /// which was the only thing it added. Its message survives here, on the failure it was written for. + /// + /// + [Collection(EvalStoreCollection.Name)] + public sealed class GoldenSetEvalTests(DatasetFixture fixture) : IClassFixture { - var harness = Require(); + [Theory(SkipTestWithoutData = true)] + [MemberData(nameof(GoldenSet.Dataset), MemberType = typeof(GoldenSet))] + public async Task Retrieval_DatasetRow_ReturnsEveryExpectedDocument(GoldenRow row) + { + DatasetHarness harness = Require(); - // Arrange, Act - // Ruling 14: this harness opens no KnowledgeScope. See DatasetHarness for why requireScope is - // false and no per-row scope is meaningful here. - var hits = await harness.Search.SearchAsync(row.Query, null, TestContext.Current.CancellationToken); - var ids = hits.Select(card => card.CardId).Distinct(StringComparer.Ordinal).ToArray(); + // Arrange, Act + // Ruling 14: this harness opens no KnowledgeScope. See DatasetHarness for why requireScope is + // false and no per-row scope is meaningful here. + IReadOnlyList hits = await harness.Search.SearchAsync(row.Query, null, TestContext.Current.CancellationToken); + string[] ids = [.. hits.Select(card => card.CardId).Distinct(StringComparer.Ordinal)]; - await using ScenarioRun run = await harness.Reporting.CreateScenarioRunAsync( - row.Id, - iterationName: "retrieval", - cancellationToken: TestContext.Current.CancellationToken); + await using ScenarioRun run = await harness.Reporting.CreateScenarioRunAsync( + row.Id, + iterationName: "retrieval", + cancellationToken: TestContext.Current.CancellationToken); - EvaluationResult result = await run.EvaluateAsync( - messages: [new ChatMessage(ChatRole.User, row.Query)], - modelResponse: new ChatResponse(), - additionalContext: [new RetrievedDocumentsContext(row.ExpectedDocumentIds, ids)], - cancellationToken: TestContext.Current.CancellationToken); + EvaluationResult result = await run.EvaluateAsync( + messages: [new ChatMessage(ChatRole.User, row.Query)], + modelResponse: new ChatResponse(), + additionalContext: [new RetrievedDocumentsContext(row.ExpectedDocumentIds, ids)], + cancellationToken: TestContext.Current.CancellationToken); - // Assert - var recall = result.Get(DocumentRecallEvaluator.DocumentRecallMetricName); - var missing = row.ExpectedDocumentIds - .Where(id => !ids.Contains(id, StringComparer.Ordinal)) - .ToArray(); + // Assert + NumericMetric recall = result.Get(DocumentRecallEvaluator.DocumentRecallMetricName); + string[] missing = [.. row.ExpectedDocumentIds.Where(id => !ids.Contains(id, StringComparer.Ordinal))]; - // The evaluator's own Reason reads as a retrieval failure, and the usual cause is not one: a - // row goes stale when its document is renamed or deleted. Naming the ids that did not come - // back is what separates the two without a second run. - Assert.False( - recall.Interpretation!.Failed, - missing.Length == 0 - ? $"row {row.Id}: {recall.Reason}" - : $"row {row.Id} names {string.Join(", ", missing)}, and the search did not return it. " - + $"Either the document moved or was renamed, or the row is stale. {recall.Reason}"); - } + // The evaluator's own Reason reads as a retrieval failure, and the usual cause is not one: a + // row goes stale when its document is renamed or deleted. Naming the ids that did not come + // back is what separates the two without a second run. + Assert.False( + recall.Interpretation!.Failed, + missing.Length == 0 + ? $"row {row.Id}: {recall.Reason}" + : $"row {row.Id} names {string.Join(", ", missing)}, and the search did not return it. " + + $"Either the document moved or was renamed, or the row is stale. {recall.Reason}"); + } - private DatasetHarness Require() - { - Assert.SkipUnless(fixture.Harness is not null, EvalHarness.DatasetSkipReason ?? string.Empty); + private DatasetHarness Require() + { + Assert.SkipUnless(fixture.Harness is not null, EvalHarness.DatasetSkipReason ?? string.Empty); - return fixture.Harness!; + return fixture.Harness!; + } } } diff --git a/tests/AgentCore.Evals/ScoreBaseline.cs b/tests/AgentCore.Evals/ScoreBaseline.cs index 78ad231e..003c5647 100644 --- a/tests/AgentCore.Evals/ScoreBaseline.cs +++ b/tests/AgentCore.Evals/ScoreBaseline.cs @@ -4,128 +4,132 @@ using Microsoft.Extensions.AI.Evaluation.Reporting; using Microsoft.Extensions.AI.Evaluation.Reporting.Storage; -namespace AgentCore.Evals; - -/// -/// The scores one execution recorded, and the scores it is allowed to fall to. -/// -/// -/// -/// The gate compares an average for each metric against the number a person recorded. A drop larger -/// than fails the merge. A rise never fails, and a rise the team wants to keep -/// is copied into the file by hand: a baseline that moved on its own gates nothing. -/// -/// -/// A boolean metric averages as the share of rows that passed, so Fault Code Accuracy reads as -/// a rate from 0 through 1 and compares the same way a numeric metric does. -/// -/// -public sealed record ScoreBaseline +namespace AgentCore.Evals { - private static readonly JsonSerializerOptions Options = - new(JsonSerializerDefaults.Web) { WriteIndented = true }; + /// + /// The scores one execution recorded, and the scores it is allowed to fall to. + /// + /// + /// + /// The gate compares an average for each metric against the number a person recorded. A drop larger + /// than fails the merge. A rise never fails, and a rise the team wants to keep + /// is copied into the file by hand: a baseline that moved on its own gates nothing. + /// + /// + /// A boolean metric averages as the share of rows that passed, so Fault Code Accuracy reads as + /// a rate from 0 through 1 and compares the same way a numeric metric does. + /// + /// + public sealed record ScoreBaseline + { + private static readonly JsonSerializerOptions Options = + new(JsonSerializerDefaults.Web) { WriteIndented = true }; - /// The environment variable that names the baseline of the real set. - public const string BaselineVariable = "AGENTCORE_EVAL_BASELINE"; + /// The environment variable that names the baseline of the real set. + public const string BaselineVariable = "AGENTCORE_EVAL_BASELINE"; - /// Gets the day a person recorded these scores. - [JsonPropertyName("recordedAt")] - public string RecordedAt { get; init; } = string.Empty; + /// Gets the day a person recorded these scores. + [JsonPropertyName("recordedAt")] + public string RecordedAt { get; init; } = string.Empty; - /// Gets how far a score may fall before the gate fails. - [JsonPropertyName("tolerance")] - public double Tolerance { get; init; } + /// Gets how far a score may fall before the gate fails. + [JsonPropertyName("tolerance")] + public double Tolerance { get; init; } - /// Gets the recorded average for each metric name. - [JsonPropertyName("metrics")] - public IReadOnlyDictionary Metrics { get; init; } = - new Dictionary(StringComparer.Ordinal); + /// Gets the recorded average for each metric name. + [JsonPropertyName("metrics")] + public IReadOnlyDictionary Metrics { get; init; } = + new Dictionary(StringComparer.Ordinal); - /// Gets the path of the baseline of the real set, or when none is named. - public static string? DatasetBaselinePath - { - get + /// Gets the path of the baseline of the real set, or when none is named. + public static string? DatasetBaselinePath { - var path = Environment.GetEnvironmentVariable(BaselineVariable); - return string.IsNullOrEmpty(path) ? null : path; + get + { + string? path = Environment.GetEnvironmentVariable(BaselineVariable); + return string.IsNullOrEmpty(path) ? null : path; + } } - } - - /// Reads one baseline file. - public static ScoreBaseline Load(string path) - { - ArgumentException.ThrowIfNullOrEmpty(path); - - return JsonSerializer.Deserialize(File.ReadAllText(path), Options) - ?? throw new InvalidDataException($"{path} is not a baseline."); - } - - /// Writes the measured averages beside the store, so a person can copy them in. - /// - /// The gate never writes the baseline itself. It writes what it measured, and a person decides - /// whether a drop is a regression or a new normal. - /// - public static void WriteMeasured(string path, IReadOnlyDictionary measured, double tolerance) - { - ArgumentException.ThrowIfNullOrEmpty(path); - ArgumentNullException.ThrowIfNull(measured); - var directory = Path.GetDirectoryName(path); - if (!string.IsNullOrEmpty(directory)) + /// Reads one baseline file. + public static ScoreBaseline Load(string path) { - Directory.CreateDirectory(directory); + ArgumentException.ThrowIfNullOrEmpty(path); + + return JsonSerializer.Deserialize(File.ReadAllText(path), Options) + ?? throw new InvalidDataException($"{path} is not a baseline."); } - File.WriteAllText( - path, - JsonSerializer.Serialize( - new ScoreBaseline { Tolerance = tolerance, Metrics = measured }, - Options)); - } + /// Writes the measured averages beside the store, so a person can copy them in. + /// + /// The gate never writes the baseline itself. It writes what it measured, and a person decides + /// whether a drop is a regression or a new normal. + /// + public static void WriteMeasured(string path, IReadOnlyDictionary measured, double tolerance) + { + ArgumentException.ThrowIfNullOrEmpty(path); + ArgumentNullException.ThrowIfNull(measured); - /// Averages every metric of one execution in the disk store. - /// The directory the reporting configuration writes to. - /// The execution to read. - /// Cancels the read. - /// - /// The average for each metric name. A metric with no value in a row is left out of that average, - /// because an inconclusive row measured nothing and must not read as a zero. - /// - public static async ValueTask> MeasureAsync( - string storageRoot, - string executionName, - CancellationToken cancellationToken = default) - { - DiskBasedResultStore store = new(storageRoot); + string? directory = Path.GetDirectoryName(path); + if (!string.IsNullOrEmpty(directory)) + { + _ = Directory.CreateDirectory(directory); + } - Dictionary totals = new(StringComparer.Ordinal); + File.WriteAllText( + path, + JsonSerializer.Serialize( + new ScoreBaseline { Tolerance = tolerance, Metrics = measured }, + Options)); + } - await foreach (ScenarioRunResult result in store - .ReadResultsAsync(executionName, cancellationToken: cancellationToken) - .ConfigureAwait(false)) + /// Averages every metric of one execution in the disk store. + /// The directory the reporting configuration writes to. + /// The execution to read. + /// Cancels the read. + /// + /// The average for each metric name. A metric with no value in a row is left out of that average, + /// because an inconclusive row measured nothing and must not read as a zero. + /// + public static async ValueTask> MeasureAsync( + string storageRoot, + string executionName, + CancellationToken cancellationToken = default) { - foreach (EvaluationMetric metric in result.EvaluationResult.Metrics.Values) + DiskBasedResultStore store = new(storageRoot); + + Dictionary totals = new(StringComparer.Ordinal); + + await foreach (ScenarioRunResult result in store + .ReadResultsAsync(executionName, cancellationToken: cancellationToken) + .ConfigureAwait(false)) { - if (Value(metric) is not { } value) + foreach (EvaluationMetric metric in result.EvaluationResult.Metrics.Values) { - continue; - } + if (Value(metric) is not { } value) + { + continue; + } - var running = totals.TryGetValue(metric.Name, out var found) ? found : (0.0, 0); - totals[metric.Name] = (running.Item1 + value, running.Item2 + 1); + (double, int) running = totals.TryGetValue(metric.Name, out (double Sum, int Count) found) ? found : (0.0, 0); + totals[metric.Name] = (running.Item1 + value, running.Item2 + 1); + } } + + return totals.ToDictionary( + entry => entry.Key, + entry => Math.Round(entry.Value.Sum / entry.Value.Count, 4), + StringComparer.Ordinal); } - return totals.ToDictionary( - entry => entry.Key, - entry => Math.Round(entry.Value.Sum / entry.Value.Count, 4), - StringComparer.Ordinal); + private static double? Value(EvaluationMetric metric) + { + return metric switch + { + NumericMetric numeric => numeric.Value, + BooleanMetric boolean => boolean.Value is { } flag ? (flag ? 1.0 : 0.0) : null, + _ => null, + }; + } } - - private static double? Value(EvaluationMetric metric) => metric switch - { - NumericMetric numeric => numeric.Value, - BooleanMetric boolean => boolean.Value is { } flag ? (flag ? 1.0 : 0.0) : null, - _ => null, - }; } diff --git a/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs b/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs index 6f7aa992..b28f7081 100644 --- a/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs +++ b/tests/AgentCore.Hosting.Tests/AgentCoreHostTests.cs @@ -10,7 +10,6 @@ using AgentCore.Application.Ports; using AgentCore.Application.Secrets; using AgentCore.AspNetCore.DependencyInjection; -using AgentCore.AspNetCore.Endpoints; using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Audit.Postgres; using AgentCore.Infrastructure.Conversation.Postgres; @@ -20,189 +19,195 @@ using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; using Xunit; +using AgentCore.Application.Tools.Binding; -namespace AgentCore.Hosting.Tests; - -/// -/// The two calls a host makes, and the promises they carry. -/// -/// -/// -/// This library exists so a host owns no wiring, and the whole of that promise is that a host can -/// still overrule any part of it. Every test here is about who wins, because that is the one thing -/// the ordering inside Configure can get wrong without failing to compile: each Use* -/// seam is a setter, so defaults written after a host's callback would silently replace it. -/// -/// -/// Every test runs offline against a fake model. There is no OpenAI account, no network conversation, and -/// no API key anywhere in this file — which is itself the proof that the default vendor list costs -/// nothing until a document names it. -/// -/// -public sealed class AgentCoreHostTests +namespace AgentCore.Hosting.Tests { - /// A model that says one thing, which is all the compile table asks for. - private sealed class FakeChatClient : IChatClient + /// + /// The two calls a host makes, and the promises they carry. + /// + /// + /// + /// This library exists so a host owns no wiring, and the whole of that promise is that a host can + /// still overrule any part of it. Every test here is about who wins, because that is the one thing + /// the ordering inside Configure can get wrong without failing to compile: each Use* + /// seam is a setter, so defaults written after a host's callback would silently replace it. + /// + /// + /// Every test runs offline against a fake model. There is no OpenAI account, no network conversation, and + /// no API key anywhere in this file — which is itself the proof that the default vendor list costs + /// nothing until a document names it. + /// + /// + public sealed class AgentCoreHostTests { - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "hello"))); - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + /// A model that says one thing, which is all the compile table asks for. + private sealed class FakeChatClient : IChatClient { - await Task.CompletedTask.ConfigureAwait(false); - yield return new ChatResponseUpdate(ChatRole.Assistant, "hello"); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() - { - } - } + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "hello"))); + } - // --------------------------------------------------------------------------------------------- - // Who wins. The host does, on every seam, because its callback runs last. - // --------------------------------------------------------------------------------------------- + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.CompletedTask.ConfigureAwait(false); + yield return new ChatResponseUpdate(ChatRole.Assistant, "hello"); + } - [Fact] - public async Task AHostChatClientFactoryWinsOverTheDefaultVendor() - { - // The default list names the real OpenAI adapter. If it ran after the callback it would - // replace this factory, and the start would then want a key this test does not set. - using var host = await StartAsync(); + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - Assert.NotNull(host.Services.GetService()); - } + public void Dispose() + { + } + } - [Fact] - public async Task AHostThatHandsOverADocumentDoesNotAlsoGetTheDefaultPath() - { - // Both a path and a configuration is two documents, and AddAgentCoreAsync refuses that. The - // default path has to stand down for a host that named a document of its own. - using var host = await StartAsync(); + // --------------------------------------------------------------------------------------------- + // Who wins. The host does, on every seam, because its callback runs last. + // --------------------------------------------------------------------------------------------- - Assert.NotNull(host.Services.GetService()); - } + [Fact] + public async Task AHostChatClientFactoryWinsOverTheDefaultVendor() + { + // The default list names the real OpenAI adapter. If it ran after the callback it would + // replace this factory, and the start would then want a key this test does not set. + using WebApplication host = await StartAsync(); - // --------------------------------------------------------------------------------------------- - // The durable seams. Naming a vendor here is what makes providers.audit.kind: postgres startable. - // --------------------------------------------------------------------------------------------- + Assert.NotNull(host.Services.GetService()); + } - [Fact] - public async Task ProvidersAuditPostgresReachesTheAdapterRatherThanTheSelector() - { - // The failure this guards is the selector's: a kind no registered adapter serves. Reaching - // the credential instead is the proof that the default list names the PostgreSQL vendor. - var failure = await Assert.ThrowsAsync( - () => StartAsync(options => options.SecretResolver = new EmptySecretResolver(), Audit)); + [Fact] + public async Task AHostThatHandsOverADocumentDoesNotAlsoGetTheDefaultPath() + { + // Both a path and a configuration is two documents, and AddAgentCoreAsync refuses that. The + // default path has to stand down for a host that named a document of its own. + using WebApplication host = await StartAsync(); - Assert.Contains(KnownSecrets.PostgresConnectionString.Name, failure.Message, StringComparison.Ordinal); - } + Assert.NotNull(host.Services.GetService()); + } - [Fact] - public async Task ProvidersConversationsPostgresReachesTheAdapterRatherThanTheSelector() - { - var failure = await Assert.ThrowsAsync( - () => StartAsync(options => options.SecretResolver = new EmptySecretResolver(), Conversations)); + // --------------------------------------------------------------------------------------------- + // The durable seams. Naming a vendor here is what makes providers.audit.kind: postgres startable. + // --------------------------------------------------------------------------------------------- - Assert.Contains(KnownSecrets.PostgresConnectionString.Name, failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task ProvidersAuditPostgresReachesTheAdapterRatherThanTheSelector() + { + // The failure this guards is the selector's: a kind no registered adapter serves. Reaching + // the credential instead is the proof that the default list names the PostgreSQL vendor. + SecretResolutionException failure = await Assert.ThrowsAsync( + () => StartAsync(options => options.SecretResolver = new EmptySecretResolver(), Audit)); - [Fact] - public async Task ADocumentNamingNoDurableVendorStillGetsTheInProcessStores() - { - // Naming the PostgreSQL vendor must not make it the default. The factory answers an absent - // block before it reads the adapter list, and this is the line that holds it to that. - using var host = await StartAsync(); + Assert.Contains(KnownSecrets.PostgresConnectionString.Name, failure.Message, StringComparison.Ordinal); + } - Assert.IsType(host.Services.GetRequiredService().Store); - Assert.IsType(host.Services.GetRequiredService().Store); - Assert.IsType(host.Services.GetRequiredService().Store); - } + [Fact] + public async Task ProvidersConversationsPostgresReachesTheAdapterRatherThanTheSelector() + { + SecretResolutionException failure = await Assert.ThrowsAsync( + () => StartAsync(options => options.SecretResolver = new EmptySecretResolver(), Conversations)); - [Fact] - public async Task AHostAuditSinkWinsOverTheDefaultVendorOnTheSameKind() - { - // UseAuditSinks is a setter, so this replaces the list rather than joining it. Were the - // default written after the callback, the start would want a connection string instead. - using var host = await StartAsync( - options => options.UseAuditSinks(new FakeSinkAdapter()), - Audit); - - Assert.IsType(host.Services.GetRequiredService()); - Assert.IsType(host.Services.GetRequiredService().Store); - } + Assert.Contains(KnownSecrets.PostgresConnectionString.Name, failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task AHostConversationStoreWinsOverTheDefaultVendorOnTheSameKind() - { - using var host = await StartAsync( - options => options.UseConversationStores(new FakeConversationStoreAdapter()), - Conversations); + [Fact] + public async Task ADocumentNamingNoDurableVendorStillGetsTheInProcessStores() + { + // Naming the PostgreSQL vendor must not make it the default. The factory answers an absent + // block before it reads the adapter list, and this is the line that holds it to that. + using WebApplication host = await StartAsync(); - Assert.IsType(host.Services.GetRequiredService().Store); - } + _ = Assert.IsType(host.Services.GetRequiredService().Store); + _ = Assert.IsType(host.Services.GetRequiredService().Store); + _ = Assert.IsType(host.Services.GetRequiredService().Store); + } - // --------------------------------------------------------------------------------------------- - // providers.knowledge.analyzer. The default QdrantKnowledgeAdapter is registered inside - // Configure, before the host's own callback runs, so a host analyzer only reaches it if the - // wiring reapplies it afterward in FinishConfiguring. If that ordering regresses, the failure - // below reads "no registered IKnowledgeQueryAnalyzer" instead of a network error. - // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AHostAuditSinkWinsOverTheDefaultVendorOnTheSameKind() + { + // UseAuditSinks is a setter, so this replaces the list rather than joining it. Were the + // default written after the callback, the start would want a connection string instead. + using WebApplication host = await StartAsync( + options => options.UseAuditSinks(new FakeSinkAdapter()), + Audit); + + _ = Assert.IsType(host.Services.GetRequiredService()); + _ = Assert.IsType(host.Services.GetRequiredService().Store); + } - [Fact] - public async Task AHostKnowledgeQueryAnalyzerReachesTheDefaultAdapter() - { - // ResolveAnalyzer runs before the Qdrant client is built, so nothing on this loopback port - // is ever contacted unless the stub analyzer already resolved. Reaching a network failure, - // rather than "no registered IKnowledgeQueryAnalyzer", is the proof it did. - var failure = await Assert.ThrowsAnyAsync(() => StartAsync( - options => - { - options.UseEmbeddings(new FakeEmbeddingAdapter()); - options.UseKnowledgeQueryAnalyzers(new StubQueryAnalyzer()); - }, - Knowledge)); + [Fact] + public async Task AHostConversationStoreWinsOverTheDefaultVendorOnTheSameKind() + { + using WebApplication host = await StartAsync( + options => options.UseConversationStores(new FakeConversationStoreAdapter()), + Conversations); - Assert.DoesNotContain("no registered", failure.Message, StringComparison.Ordinal); - } + _ = Assert.IsType(host.Services.GetRequiredService().Store); + } - [Fact] - public async Task AHostKnowledgePointMapperReachesTheDefaultAdapter() - { - // ResolveMapper runs before the Qdrant client is built, so nothing on this loopback port is - // ever contacted unless the stub mapper already resolved. Reaching a network failure, rather - // than "no registered IKnowledgePointMapper", is the proof it did. - var failure = await Assert.ThrowsAnyAsync(() => StartAsync( - options => - { - options.UseEmbeddings(new FakeEmbeddingAdapter()); - options.UseKnowledgePointMappers(new StubPointMapper()); - }, - KnowledgeMapper)); + // --------------------------------------------------------------------------------------------- + // providers.knowledge.analyzer. The default QdrantKnowledgeAdapter is registered inside + // Configure, before the host's own callback runs, so a host analyzer only reaches it if the + // wiring reapplies it afterward in FinishConfiguring. If that ordering regresses, the failure + // below reads "no registered IKnowledgeQueryAnalyzer" instead of a network error. + // --------------------------------------------------------------------------------------------- - Assert.DoesNotContain("no registered", failure.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AHostKnowledgeQueryAnalyzerReachesTheDefaultAdapter() + { + // ResolveAnalyzer runs before the Qdrant client is built, so nothing on this loopback port + // is ever contacted unless the stub analyzer already resolved. Reaching a network failure, + // rather than "no registered IKnowledgeQueryAnalyzer", is the proof it did. + Exception failure = await Assert.ThrowsAnyAsync(() => StartAsync( + options => + { + _ = options.UseEmbeddings(new FakeEmbeddingAdapter()); + _ = options.UseKnowledgeQueryAnalyzers(new StubQueryAnalyzer()); + }, + Knowledge)); + + Assert.DoesNotContain("no registered", failure.Message, StringComparison.Ordinal); + } - // --------------------------------------------------------------------------------------------- - // The mcp: block. McpToolSource is registered from this project, not from AgentCore.AspNetCore — - // this test is what actually proves that wiring runs a real connection attempt, naming the - // server that failed to connect. - // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AHostKnowledgePointMapperReachesTheDefaultAdapter() + { + // ResolveMapper runs before the Qdrant client is built, so nothing on this loopback port is + // ever contacted unless the stub mapper already resolved. Reaching a network failure, rather + // than "no registered IKnowledgePointMapper", is the proof it did. + Exception failure = await Assert.ThrowsAnyAsync(() => StartAsync( + options => + { + _ = options.UseEmbeddings(new FakeEmbeddingAdapter()); + _ = options.UseKnowledgePointMappers(new StubPointMapper()); + }, + KnowledgeMapper)); + + Assert.DoesNotContain("no registered", failure.Message, StringComparison.Ordinal); + } - /// A document naming an mcp: server whose command does not exist. - /// - /// A missing executable fails Process.Start synchronously, so this reaches - /// immediately rather than waiting out any MCP - /// initialization timeout — the fast, offline failure this test needs. - /// - private const string McpDocument = """ + // --------------------------------------------------------------------------------------------- + // The mcp: block. McpToolSource is registered from this project, not from AgentCore.AspNetCore — + // this test is what actually proves that wiring runs a real connection attempt, naming the + // server that failed to connect. + // --------------------------------------------------------------------------------------------- + + /// A document naming an mcp: server whose command does not exist. + /// + /// A missing executable fails Process.Start synchronously, so this reaches + /// immediately rather than waiting out any MCP + /// initialization timeout — the fast, offline failure this test needs. + /// + private const string McpDocument = """ apiVersion: agentcore/v1 agents: items: @@ -224,198 +229,198 @@ public async Task AHostKnowledgePointMapperReachesTheDefaultAdapter() - { kind: fake, model: fake-model, as: reply } """; - [Fact] - public async Task AnMcpServerThatCannotBeReachedFailsTheStartNamingTheServer() - { - var builder = WebApplication.CreateSlimBuilder(); - builder.WebHost.UseUrls("http://127.0.0.1:0"); - builder.Logging.ClearProviders(); - - builder.AddAgentCoreHost(options => + [Fact] + public async Task AnMcpServerThatCannotBeReachedFailsTheStartNamingTheServer() { - options.Configuration = ConfigurationLoader.LoadYaml(McpDocument); - options.UseChatClients(_ => new RecordingChatClientFactory(new FakeChatClient())); - }); + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + _ = builder.WebHost.UseUrls("http://127.0.0.1:0"); + _ = builder.Logging.ClearProviders(); - await using var app = builder.Build(); + _ = builder.AddAgentCoreHost(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(McpDocument); + _ = options.UseChatClients(_ => new RecordingChatClientFactory(new FakeChatClient())); + }); - var failure = await Assert.ThrowsAsync( - () => app.StartAsync(TestContext.Current.CancellationToken)); + await using WebApplication app = builder.Build(); - Assert.Contains("no-such-server", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + () => app.StartAsync(TestContext.Current.CancellationToken)); - // --------------------------------------------------------------------------------------------- - // The CreateCase stub. It fills a gap and never takes a name the host wanted. - // --------------------------------------------------------------------------------------------- + Assert.Contains("no-such-server", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task AHostThatBindsNothingGetsTheStub() - { - AgentCoreOptions? options = null; - using var host = await StartAsync(captured => options = captured); + // --------------------------------------------------------------------------------------------- + // The CreateCase stub. It fills a gap and never takes a name the host wanted. + // --------------------------------------------------------------------------------------------- - Assert.True(options!.Bindings.TryGetBinding( - AgentCoreHostBuilderExtensions.CreateCaseBinding, - out var binding)); + [Fact] + public async Task AHostThatBindsNothingGetsTheStub() + { + AgentCoreOptions? options = null; + using WebApplication host = await StartAsync(captured => options = captured); - var result = await binding!(new JsonObject { ["summary"] = "a broken treadmill" }, TestContext.Current.CancellationToken); - var json = Assert.IsType(result); + Assert.True(options!.Bindings.TryGetBinding( + AgentCoreHostBuilderExtensions.CreateCaseBinding, + out ToolBinding? binding)); - Assert.False((bool)json["opened"]!); - Assert.Equal("a broken treadmill", (string?)json["summary"]); - } + object? result = await binding!(new JsonObject { ["summary"] = "a broken treadmill" }, TestContext.Current.CancellationToken); + JsonObject json = Assert.IsType(result); - [Fact] - public async Task AHostThatBindsCreateCaseKeepsItsOwnDelegate() - { - // Registering one name twice throws, so a stub added before the callback would turn a host - // that wants this binding into a host that cannot start at all. - AgentCoreOptions? options = null; - using var host = await StartAsync(configure => - { - options = configure; - configure.Bind( - AgentCoreHostBuilderExtensions.CreateCaseBinding, - (_, _) => ValueTask.FromResult(new JsonObject { ["opened"] = true })); - }); + Assert.False((bool)json["opened"]!); + Assert.Equal("a broken treadmill", (string?)json["summary"]); + } - Assert.True(options!.Bindings.TryGetBinding( - AgentCoreHostBuilderExtensions.CreateCaseBinding, - out var binding)); + [Fact] + public async Task AHostThatBindsCreateCaseKeepsItsOwnDelegate() + { + // Registering one name twice throws, so a stub added before the callback would turn a host + // that wants this binding into a host that cannot start at all. + AgentCoreOptions? options = null; + using WebApplication host = await StartAsync(configure => + { + options = configure; + _ = configure.Bind( + AgentCoreHostBuilderExtensions.CreateCaseBinding, + (_, _) => ValueTask.FromResult(new JsonObject { ["opened"] = true })); + }); - var result = await binding!([], TestContext.Current.CancellationToken); - Assert.True((bool)Assert.IsType(result)["opened"]!); - } + Assert.True(options!.Bindings.TryGetBinding( + AgentCoreHostBuilderExtensions.CreateCaseBinding, + out ToolBinding? binding)); - // --------------------------------------------------------------------------------------------- - // What this extension registered, the container has to close. - // --------------------------------------------------------------------------------------------- + object? result = await binding!([], TestContext.Current.CancellationToken); + Assert.True((bool)Assert.IsType(result)["opened"]!); + } - [Fact] - public async Task TheOutboundHttpPipelineClosesWithTheHost() - { - var host = await StartAsync(); - var clients = host.Services.GetRequiredService(); + // --------------------------------------------------------------------------------------------- + // What this extension registered, the container has to close. + // --------------------------------------------------------------------------------------------- - await host.DisposeAsync(); + [Fact] + public async Task TheOutboundHttpPipelineClosesWithTheHost() + { + WebApplication host = await StartAsync(); + AgentCoreHttpClients clients = host.Services.GetRequiredService(); - // The pipeline holds a container and a SocketsHttpHandler per client name. A host that stops - // and leaves them open leaks both, and a process that restarts it leaks them again. - Assert.Throws(() => clients.CreateClient("agentcore.test")); - } + await host.DisposeAsync(); - [Fact] - public async Task TheLoggerFactoryClosesWithTheHost() - { - var host = await StartAsync(); - var loggers = host.Services.GetRequiredService(); + // The pipeline holds a container and a SocketsHttpHandler per client name. A host that stops + // and leaves them open leaks both, and a process that restarts it leaks them again. + _ = Assert.Throws(() => clients.CreateClient("agentcore.test")); + } - await host.DisposeAsync(); + [Fact] + public async Task TheLoggerFactoryClosesWithTheHost() + { + WebApplication host = await StartAsync(); + ILoggerFactory loggers = host.Services.GetRequiredService(); - // The container built this factory, so nothing else can be holding its providers. - Assert.Throws(() => loggers.CreateLogger("after")); - } + await host.DisposeAsync(); - // --------------------------------------------------------------------------------------------- - // The routes. Mapping is the other half: the registrations above answer nothing on their own. - // --------------------------------------------------------------------------------------------- + // The container built this factory, so nothing else can be holding its providers. + _ = Assert.Throws(() => loggers.CreateLogger("after")); + } - [Fact] - public async Task HealthAnswersOnTheMappedRoute() - { - await using var app = await StartMappedAsync(); - using HttpClient client = new() { BaseAddress = Address(app) }; + // --------------------------------------------------------------------------------------------- + // The routes. Mapping is the other half: the registrations above answer nothing on their own. + // --------------------------------------------------------------------------------------------- - var response = await client.GetAsync( - AgentCoreHostEndpointExtensions.HealthPattern, - TestContext.Current.CancellationToken); + [Fact] + public async Task HealthAnswersOnTheMappedRoute() + { + await using WebApplication app = await StartMappedAsync(); + using HttpClient client = new() { BaseAddress = Address(app) }; - Assert.Equal(System.Net.HttpStatusCode.OK, response.StatusCode); - } + HttpResponseMessage response = await client.GetAsync( + AgentCoreHostEndpointExtensions.HealthPattern, + TestContext.Current.CancellationToken); - /// The default Responses route, with the document's one entry filled in. - private const string MainResponses = "/v1/main/responses"; + Assert.Equal(System.Net.HttpStatusCode.OK, response.StatusCode); + } - [Fact] - public async Task ResponsesAnswersOnTheDefaultRoute() - { - await using var app = await StartMappedAsync(); - using HttpClient client = new() { BaseAddress = Address(app) }; + /// The default Responses route, with the document's one entry filled in. + private const string MainResponses = "/v1/main/responses"; - // No user message is a caller mistake this endpoint names, and naming it proves the route - // reached the endpoint rather than the 404 handler. - var response = await PostEmptyAsync(client, MainResponses); + [Fact] + public async Task ResponsesAnswersOnTheDefaultRoute() + { + await using WebApplication app = await StartMappedAsync(); + using HttpClient client = new() { BaseAddress = Address(app) }; - Assert.Equal(System.Net.HttpStatusCode.BadRequest, response.StatusCode); - } + // No user message is a caller mistake this endpoint names, and naming it proves the route + // reached the endpoint rather than the 404 handler. + HttpResponseMessage response = await PostEmptyAsync(client, MainResponses); - [Fact] - public async Task ResponsesRefusesAnEntryTheDocumentDoesNotDeclare() - { - await using var app = await StartMappedAsync(); - using HttpClient client = new() { BaseAddress = Address(app) }; + Assert.Equal(System.Net.HttpStatusCode.BadRequest, response.StatusCode); + } - var response = await PostEmptyAsync(client, "/v1/nobody/responses"); + [Fact] + public async Task ResponsesRefusesAnEntryTheDocumentDoesNotDeclare() + { + await using WebApplication app = await StartMappedAsync(); + using HttpClient client = new() { BaseAddress = Address(app) }; - Assert.Equal(System.Net.HttpStatusCode.NotFound, response.StatusCode); - var body = await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken); - Assert.Contains("\"code\":\"unknown_entry\"", body); - Assert.Contains("Valid entries: main", body); - } + HttpResponseMessage response = await PostEmptyAsync(client, "/v1/nobody/responses"); - [Fact] - public async Task ResponsesMovesWhenTheHostNamesAnotherRoute() - { - // A host that mounts a second Responses surface of its own needs this one out of the - // way, and it must actually leave the default route behind when it moves. - await using var app = await StartMappedAsync("/agentcore/v1/{entry}/responses"); - using HttpClient client = new() { BaseAddress = Address(app) }; - - Assert.Equal( - System.Net.HttpStatusCode.BadRequest, - (await PostEmptyAsync(client, "/agentcore/v1/main/responses")).StatusCode); - Assert.Equal( - System.Net.HttpStatusCode.NotFound, - (await PostEmptyAsync(client, MainResponses)).StatusCode); - } + Assert.Equal(System.Net.HttpStatusCode.NotFound, response.StatusCode); + string body = await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken); + Assert.Contains("\"code\":\"unknown_entry\"", body); + Assert.Contains("Valid entries: main", body); + } - [Fact] - public async Task ConversationRefusesAnEntryTheDocumentDoesNotDeclare() - { - await using var app = await StartMappedAsync(); - using HttpClient client = new() { BaseAddress = Address(app) }; + [Fact] + public async Task ResponsesMovesWhenTheHostNamesAnotherRoute() + { + // A host that mounts a second Responses surface of its own needs this one out of the + // way, and it must actually leave the default route behind when it moves. + await using WebApplication app = await StartMappedAsync("/agentcore/v1/{entry}/responses"); + using HttpClient client = new() { BaseAddress = Address(app) }; + + Assert.Equal( + System.Net.HttpStatusCode.BadRequest, + (await PostEmptyAsync(client, "/agentcore/v1/main/responses")).StatusCode); + Assert.Equal( + System.Net.HttpStatusCode.NotFound, + (await PostEmptyAsync(client, MainResponses)).StatusCode); + } - var response = await client.GetAsync("/v1/nobody/call", TestContext.Current.CancellationToken); + [Fact] + public async Task ConversationRefusesAnEntryTheDocumentDoesNotDeclare() + { + await using WebApplication app = await StartMappedAsync(); + using HttpClient client = new() { BaseAddress = Address(app) }; - Assert.Equal(System.Net.HttpStatusCode.NotFound, response.StatusCode); - Assert.Contains( - "Valid entries: main", - await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken)); - } + HttpResponseMessage response = await client.GetAsync("/v1/nobody/call", TestContext.Current.CancellationToken); - [Fact] - public async Task ResponsesRefusesARouteWithNoEntryParameter() - { - await using var app = await BuildAsync(); + Assert.Equal(System.Net.HttpStatusCode.NotFound, response.StatusCode); + Assert.Contains( + "Valid entries: main", + await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken)); + } - var failure = Assert.Throws(() => app.MapAgentCoreHost("/v1/responses")); + [Fact] + public async Task ResponsesRefusesARouteWithNoEntryParameter() + { + await using WebApplication app = await BuildAsync(); - Assert.Contains("{entry}", failure.Message); - } + ArgumentException failure = Assert.Throws(() => app.MapAgentCoreHost("/v1/responses")); - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- + Assert.Contains("{entry}", failure.Message); + } - /// The smallest document the schema accepts: one agent, one model, and the required pair. - /// - /// A document that writes a providers block at all must write conversation and - /// speech too, and both speech roles must name the same vendor the conversation does. Those kinds - /// resolve here because the default list this library registers already names that transport — - /// which is the point: a test writes no vendor of its own except the model. - /// - private const string Document = """ + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + + /// The smallest document the schema accepts: one agent, one model, and the required pair. + /// + /// A document that writes a providers block at all must write conversation and + /// speech too, and both speech roles must name the same vendor the conversation does. Those kinds + /// resolve here because the default list this library registers already names that transport — + /// which is the point: a test writes no vendor of its own except the model. + /// + private const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -432,255 +437,279 @@ public async Task ResponsesRefusesARouteWithNoEntryParameter() - { kind: fake, model: fake-model, as: reply } """; - /// The providers line that asks for the durable audit vendor. - private const string Audit = " audit: { kind: postgres }"; - - /// The providers line that asks for the durable transcript vendor. + /// The providers line that asks for the durable audit vendor. + private const string Audit = " audit: { kind: postgres }"; + + /// The providers line that asks for the durable transcript vendor. + + /// The providers line that asks for the durable conversation store vendor. + private const string Conversations = " conversations: { kind: postgres }"; + + /// + /// The providers lines for a knowledge store on an endpoint nothing listens on, so the + /// only question a test against it can settle is whether the analyzer resolved. + /// + private const string Knowledge = + " embeddings: { kind: " + FakeEmbeddingAdapter.ProviderKind + ", model: n/a }\n" + + " knowledge: { kind: qdrant, endpoint: \"https://127.0.0.1:1\", collection: \"missing\", " + + "analyzer: " + StubQueryAnalyzer.AnalyzerName + " }"; + + /// Like , but naming a mapper instead of an analyzer. + private const string KnowledgeMapper = + " embeddings: { kind: " + FakeEmbeddingAdapter.ProviderKind + ", model: n/a }\n" + + " knowledge: { kind: qdrant, endpoint: \"https://127.0.0.1:1\", collection: \"missing\", " + + "mapper: " + StubPointMapper.MapperName + " }"; + + /// Builds a host the way a deployable does, over a fake model and no key. + /// Anything else the test says on the options. + /// A further line under providers, or null for the document above. + /// The built host, not started. + private static async Task BuildAsync( + Action? configure = null, + string? providers = null) + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + _ = builder.WebHost.UseUrls("http://127.0.0.1:0"); + _ = builder.Logging.ClearProviders(); - /// The providers line that asks for the durable conversation store vendor. - private const string Conversations = " conversations: { kind: postgres }"; + string document = providers is null ? Document : Document + Environment.NewLine + providers; - /// - /// The providers lines for a knowledge store on an endpoint nothing listens on, so the - /// only question a test against it can settle is whether the analyzer resolved. - /// - private const string Knowledge = - " embeddings: { kind: " + FakeEmbeddingAdapter.ProviderKind + ", model: n/a }\n" - + " knowledge: { kind: qdrant, endpoint: \"https://127.0.0.1:1\", collection: \"missing\", " - + "analyzer: " + StubQueryAnalyzer.AnalyzerName + " }"; - - /// Like , but naming a mapper instead of an analyzer. - private const string KnowledgeMapper = - " embeddings: { kind: " + FakeEmbeddingAdapter.ProviderKind + ", model: n/a }\n" - + " knowledge: { kind: qdrant, endpoint: \"https://127.0.0.1:1\", collection: \"missing\", " - + "mapper: " + StubPointMapper.MapperName + " }"; - - /// Builds a host the way a deployable does, over a fake model and no key. - /// Anything else the test says on the options. - /// A further line under providers, or null for the document above. - /// The built host, not started. - private static async Task BuildAsync( - Action? configure = null, - string? providers = null) - { - var builder = WebApplication.CreateSlimBuilder(); - builder.WebHost.UseUrls("http://127.0.0.1:0"); - builder.Logging.ClearProviders(); + _ = builder.AddAgentCoreHost(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(document); + _ = options.UseChatClients(_ => new RecordingChatClientFactory(new FakeChatClient())); + configure?.Invoke(options); + }); - var document = providers is null ? Document : Document + Environment.NewLine + providers; + return builder.Build(); + } - builder.AddAgentCoreHost(options => + /// Starts a host and reads its container, with nothing mapped and nothing listening. + /// Anything else the test says on the options. + /// A further line under providers, or null for the plain document. + /// The started host. + /// + /// It really starts: the document is read, and every adapter it names is opened, by the hosted + /// lifecycle service the composition root registers. Building alone opens nothing. + /// + private static async Task StartAsync( + Action? configure = null, + string? providers = null) { - options.Configuration = ConfigurationLoader.LoadYaml(document); - options.UseChatClients(_ => new RecordingChatClientFactory(new FakeChatClient())); - configure?.Invoke(options); - }); - - return builder.Build(); - } + WebApplication app = await BuildAsync(configure, providers); - /// Starts a host and reads its container, with nothing mapped and nothing listening. - /// Anything else the test says on the options. - /// A further line under providers, or null for the plain document. - /// The started host. - /// - /// It really starts: the document is read, and every adapter it names is opened, by the hosted - /// lifecycle service the composition root registers. Building alone opens nothing. - /// - private static async Task StartAsync( - Action? configure = null, - string? providers = null) - { - var app = await BuildAsync(configure, providers); + try + { + await app.StartAsync(TestContext.Current.CancellationToken); + } + catch + { + // A failed start never stops what started, so disposal is the only cleanup path — and it + // is the one a real host takes too, inside RunAsync's own finally. + await app.DisposeAsync(); + throw; + } - try - { - await app.StartAsync(TestContext.Current.CancellationToken); + return app; } - catch + + /// A chain that holds the connection string and answers nothing for it. + /// + /// A held-but-blank name fails without falling back, so these tests reach the same failure on a + /// machine that happens to export POSTGRES_CONNECTION_STRING. + /// + private sealed class EmptySecretResolver : ISecretResolverPort { - // A failed start never stops what started, so disposal is the only cleanup path — and it - // is the one a real host takes too, inside RunAsync's own finally. - await app.DisposeAsync(); - throw; + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult( + string.Equals(name, KnownSecrets.PostgresConnectionString.Name, StringComparison.Ordinal) + ? string.Empty + : null); + } } - return app; - } - - /// A chain that holds the connection string and answers nothing for it. - /// - /// A held-but-blank name fails without falling back, so these tests reach the same failure on a - /// machine that happens to export POSTGRES_CONNECTION_STRING. - /// - private sealed class EmptySecretResolver : ISecretResolverPort - { - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - => ValueTask.FromResult( - string.Equals(name, KnownSecrets.PostgresConnectionString.Name, StringComparison.Ordinal) - ? string.Empty - : null); - } + /// An audit vendor answering to the same kind the default list names. + private sealed class FakeSinkAdapter : IAuditSinkAdapter + { + public string Kind => PostgresAuditSinkAdapter.ProviderKind; - /// An audit vendor answering to the same kind the default list names. - private sealed class FakeSinkAdapter : IAuditSinkAdapter - { - public string Kind => PostgresAuditSinkAdapter.ProviderKind; + public ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(new InMemoryAuditSink()); + } + } - public ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(new InMemoryAuditSink()); - } + /// A conversation store vendor answering to the same kind the default list names. + private sealed class FakeConversationStoreAdapter : IConversationStoreAdapter + { + public string Kind => PostgresConversationStoreAdapter.ProviderKind; - /// A conversation store vendor answering to the same kind the default list names. - private sealed class FakeConversationStoreAdapter : IConversationStoreAdapter - { - public string Kind => PostgresConversationStoreAdapter.ProviderKind; + public ValueTask OpenAsync( + VendorProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult(new InMemoryConversationStore()); + } + } - public ValueTask OpenAsync( - VendorProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult(new InMemoryConversationStore()); - } + /// An embedding vendor whose generator is never actually asked to embed anything. + /// + /// QdrantKnowledgeAdapter.CreateSearchAsync only needs a non-null generator to get past + /// its own providers.embeddings check; the analyzer resolves right after, and every test + /// using this adapter fails before either could reach the generator itself. + /// + private sealed class FakeEmbeddingAdapter : IEmbeddingGeneratorAdapter + { + public const string ProviderKind = "hosting-tests-embed"; - /// An embedding vendor whose generator is never actually asked to embed anything. - /// - /// QdrantKnowledgeAdapter.CreateSearchAsync only needs a non-null generator to get past - /// its own providers.embeddings check; the analyzer resolves right after, and every test - /// using this adapter fails before either could reach the generator itself. - /// - private sealed class FakeEmbeddingAdapter : IEmbeddingGeneratorAdapter - { - public const string ProviderKind = "hosting-tests-embed"; + public string Kind => ProviderKind; - public string Kind => ProviderKind; + public ValueTask>> CreateGeneratorAsync( + EmbeddingProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>>(new NeverUsedEmbeddingGenerator()); + } - public ValueTask>> CreateGeneratorAsync( - EmbeddingProviderConfiguration entry, - ISecretResolverPort? secrets, - CancellationToken cancellationToken = default) - => ValueTask.FromResult>>(new NeverUsedEmbeddingGenerator()); + private sealed class NeverUsedEmbeddingGenerator : IEmbeddingGenerator> + { + public Task>> GenerateAsync( + IEnumerable values, + EmbeddingGenerationOptions? options = null, + CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("Nothing in these tests should ever embed a query."); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } + } + } - private sealed class NeverUsedEmbeddingGenerator : IEmbeddingGenerator> + /// An analyzer a host registers by name, distinct from either built-in. + private sealed class StubQueryAnalyzer : IKnowledgeQueryAnalyzer { - public Task>> GenerateAsync( - IEnumerable values, - EmbeddingGenerationOptions? options = null, - CancellationToken cancellationToken = default) - => throw new InvalidOperationException("Nothing in these tests should ever embed a query."); + public const string AnalyzerName = "hosting-tests-stub-analyzer"; - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public string Name => AnalyzerName; - public void Dispose() + public IReadOnlyList RequiredTerms(string query) { + return []; } } - } - /// An analyzer a host registers by name, distinct from either built-in. - private sealed class StubQueryAnalyzer : IKnowledgeQueryAnalyzer - { - public const string AnalyzerName = "hosting-tests-stub-analyzer"; + /// A mapper a host registers by name, distinct from either built-in. + private sealed class StubPointMapper : IKnowledgePointMapper + { + public const string MapperName = "hosting-tests-stub-mapper"; - public string Name => AnalyzerName; + public string Name => MapperName; - public IReadOnlyList RequiredTerms(string query) => []; - } + public KnowledgeCard? Map(KnowledgePoint point) + { + return null; + } + } - /// A mapper a host registers by name, distinct from either built-in. - private sealed class StubPointMapper : IKnowledgePointMapper - { - public const string MapperName = "hosting-tests-stub-mapper"; + /// Builds a host, maps every route, and puts it on a real socket. + /// The route the Responses endpoint answers on, or null for the default. + /// The started host. + private static async Task StartMappedAsync(string? responsesPattern = null) + { + WebApplication app = await BuildAsync(); + _ = app.MapAgentCoreHost(responsesPattern); + await app.StartAsync(TestContext.Current.CancellationToken); + return app; + } - public string Name => MapperName; + /// Reads the address Kestrel took, since the tests ask for port zero. + /// The started host. + /// The base address. + private static Uri Address(WebApplication app) + { + return new(app.Services + .GetRequiredService() + .Features + .Get()! + .Addresses + .First(), UriKind.Absolute); + } - public KnowledgeCard? Map(KnowledgePoint point) => null; - } + /// Posts a request with no user message, which every mapped route answers 400 to. + /// The client that speaks to the host. + /// The route to post to. + /// The answer. + private static Task PostEmptyAsync(HttpClient client, string route) + { + return client.PostAsync( + route, + new StringContent(/*lang=json,strict*/ "{\"input\":[]}", System.Text.Encoding.UTF8, "application/json"), + TestContext.Current.CancellationToken); + } - /// Builds a host, maps every route, and puts it on a real socket. - /// The route the Responses endpoint answers on, or null for the default. - /// The started host. - private static async Task StartMappedAsync(string? responsesPattern = null) - { - var app = await BuildAsync(); - app.MapAgentCoreHost(responsesPattern); - await app.StartAsync(TestContext.Current.CancellationToken); - return app; - } + // --------------------------------------------------------------------------------------------- + // A transport: http MCP server is reached on this host's own pipeline, minus the one part of it + // that does not apply to a stream. + // --------------------------------------------------------------------------------------------- - /// Reads the address Kestrel took, since the tests ask for port zero. - /// The started host. - /// The base address. - private static Uri Address(WebApplication app) - => new(app.Services - .GetRequiredService() - .Features - .Get()! - .Addresses - .First(), UriKind.Absolute); - - /// Posts a request with no user message, which every mapped route answers 400 to. - /// The client that speaks to the host. - /// The route to post to. - /// The answer. - private static Task PostEmptyAsync(HttpClient client, string route) - => client.PostAsync( - route, - new StringContent("{\"input\":[]}", System.Text.Encoding.UTF8, "application/json"), - TestContext.Current.CancellationToken); - - // --------------------------------------------------------------------------------------------- - // A transport: http MCP server is reached on this host's own pipeline, minus the one part of it - // that does not apply to a stream. - // --------------------------------------------------------------------------------------------- - - [Fact] - public async Task AnMcpServerIsReachedOnThePipelinesOwnHandlerChain() - { - CountingHandler primary = new(); - using AgentCoreHttpClients pipeline = new(primary); + [Fact] + public async Task AnMcpServerIsReachedOnThePipelinesOwnHandlerChain() + { + CountingHandler primary = new(); + using AgentCoreHttpClients pipeline = new(primary); - using var client = AgentCoreHostBuilderExtensions.McpHttpClient(pipeline); - await client.GetAsync(new Uri("https://mcp.example.com/"), TestContext.Current.CancellationToken); + using HttpClient client = AgentCoreHostBuilderExtensions.McpHttpClient(pipeline); + _ = await client.GetAsync(new Uri("https://mcp.example.com/"), TestContext.Current.CancellationToken); - // The request reached the handler the pipeline was built around, so MCP shares its proxy - // settings, certificate configuration and logging rather than a client of its own. - Assert.Equal(1, primary.Sends); - } + // The request reached the handler the pipeline was built around, so MCP shares its proxy + // settings, certificate configuration and logging rather than a client of its own. + Assert.Equal(1, primary.Sends); + } - /// - /// MCP over HTTP holds a stream open for the life of the session, so the pipeline's own - /// hundred-second request deadline would sever it every hundred seconds. - /// - [Fact] - public void AnMcpServersClientCarriesNoRequestDeadline() - { - CountingHandler primary = new(); - using AgentCoreHttpClients pipeline = new(primary); + /// + /// MCP over HTTP holds a stream open for the life of the session, so the pipeline's own + /// hundred-second request deadline would sever it every hundred seconds. + /// + [Fact] + public void AnMcpServersClientCarriesNoRequestDeadline() + { + CountingHandler primary = new(); + using AgentCoreHttpClients pipeline = new(primary); - using var mcp = AgentCoreHostBuilderExtensions.McpHttpClient(pipeline); - using var ordinary = pipeline.CreateClient("agentcore.tools"); + using HttpClient mcp = AgentCoreHostBuilderExtensions.McpHttpClient(pipeline); + using HttpClient ordinary = pipeline.CreateClient("agentcore.tools"); - Assert.Equal(Timeout.InfiniteTimeSpan, mcp.Timeout); - Assert.Equal(AgentCoreHttpClients.RequestDeadline, ordinary.Timeout); - } + Assert.Equal(Timeout.InfiniteTimeSpan, mcp.Timeout); + Assert.Equal(AgentCoreHttpClients.RequestDeadline, ordinary.Timeout); + } - /// Answers everything, and counts how often it was asked. - private sealed class CountingHandler : HttpMessageHandler - { - private int _sends; + /// Answers everything, and counts how often it was asked. + private sealed class CountingHandler : HttpMessageHandler + { + private int _sends; - public int Sends => Volatile.Read(ref _sends); + public int Sends => Volatile.Read(ref _sends); - protected override Task SendAsync( - HttpRequestMessage request, CancellationToken cancellationToken) - { - Interlocked.Increment(ref _sends); - return Task.FromResult(new HttpResponseMessage(System.Net.HttpStatusCode.OK)); + protected override Task SendAsync( + HttpRequestMessage request, CancellationToken cancellationToken) + { + _ = Interlocked.Increment(ref _sends); + return Task.FromResult(new HttpResponseMessage(System.Net.HttpStatusCode.OK)); + } } } } diff --git a/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs b/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs index 1f82b179..008efbd7 100644 --- a/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs +++ b/tests/AgentCore.Hosting.Tests/ConfigurationSecretResolverTests.cs @@ -1,8 +1,6 @@ using AgentCore.TestSupport; -using AgentCore.Application.Ports; using AgentCore.Application.Configuration.Parsing; using AgentCore.AspNetCore.DependencyInjection; -using AgentCore.Application.Configuration.Schema; using AgentCore.Hosting.Secrets; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; @@ -11,112 +9,112 @@ using Microsoft.Extensions.Logging; using Xunit; -namespace AgentCore.Hosting.Tests; - -/// -/// The third link of the secret chain: whatever the host's own configuration holds. -/// -/// -/// -/// The environment and the /run/secrets directory are how a deployment hands a credential -/// over. Neither helps a developer running dotnet run, who has dotnet user-secrets and -/// an appsettings.Development.json already. This link reaches both, because both are -/// configuration providers and nothing else about them is this library's business. -/// -/// -/// It reads ONE section and never the whole document. A bare key at the root would collide with -/// unrelated host settings, and the environment provider that WebApplicationBuilder already -/// installs would make this link answer for variables the first link owns. -/// -/// Every test here runs offline. There is no network conversation and no API key in this file. -/// -public sealed class ConfigurationSecretResolverTests +namespace AgentCore.Hosting.Tests { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task TheConfigurationResolverReadsTheNameTheDocumentWrote() + /// + /// The third link of the secret chain: whatever the host's own configuration holds. + /// + /// + /// + /// The environment and the /run/secrets directory are how a deployment hands a credential + /// over. Neither helps a developer running dotnet run, who has dotnet user-secrets and + /// an appsettings.Development.json already. This link reaches both, because both are + /// configuration providers and nothing else about them is this library's business. + /// + /// + /// It reads ONE section and never the whole document. A bare key at the root would collide with + /// unrelated host settings, and the environment provider that WebApplicationBuilder already + /// installs would make this link answer for variables the first link owns. + /// + /// Every test here runs offline. There is no network conversation and no API key in this file. + /// + public sealed class ConfigurationSecretResolverTests { - var resolver = Resolver(("AgentCore:Secrets:orders-api-key", "sk-1")); + private static CancellationToken Token => TestContext.Current.CancellationToken; - Assert.Equal("sk-1", await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheConfigurationResolverReadsTheNameTheDocumentWrote() + { + ConfigurationSecretResolver resolver = Resolver(("AgentCore:Secrets:orders-api-key", "sk-1")); - [Fact] - public async Task TheConfigurationResolverAlsoReadsTheShoutingForm() - { - // The same courtesy the environment link gives: a deployment that already writes - // ORDERS_API_KEY keeps the spelling it has. - var resolver = Resolver(("AgentCore:Secrets:ORDERS_API_KEY", "sk-2")); + Assert.Equal("sk-1", await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Equal("sk-2", await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheConfigurationResolverAlsoReadsTheShoutingForm() + { + // The same courtesy the environment link gives: a deployment that already writes + // ORDERS_API_KEY keeps the spelling it has. + ConfigurationSecretResolver resolver = Resolver(("AgentCore:Secrets:ORDERS_API_KEY", "sk-2")); - [Fact] - public async Task TheConfigurationResolverAnswersNullForAnUnknownName() - { - var resolver = Resolver(("AgentCore:Secrets:something-else", "sk-3")); + Assert.Equal("sk-2", await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheConfigurationResolverAnswersNullForAnUnknownName() + { + ConfigurationSecretResolver resolver = Resolver(("AgentCore:Secrets:something-else", "sk-3")); - [Fact] - public async Task TheConfigurationResolverReadsAnEmptyValueAsUnset() - { - // A miss, so the chain goes on rather than handing an adapter an empty credential. - var resolver = Resolver(("AgentCore:Secrets:orders-api-key", "")); + Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheConfigurationResolverReadsAnEmptyValueAsUnset() + { + // A miss, so the chain goes on rather than handing an adapter an empty credential. + ConfigurationSecretResolver resolver = Resolver(("AgentCore:Secrets:orders-api-key", "")); - [Fact] - public async Task TheConfigurationResolverIgnoresAKeyOutsideItsSection() - { - // A root key is host settings, not a credential store. Reading it would let any unrelated - // setting answer for a secret name that happened to match. - var resolver = Resolver(("orders-api-key", "sk-4"), ("Secrets:orders-api-key", "sk-5")); + Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheConfigurationResolverIgnoresAKeyOutsideItsSection() + { + // A root key is host settings, not a credential store. Reading it would let any unrelated + // setting answer for a secret name that happened to match. + ConfigurationSecretResolver resolver = Resolver(("orders-api-key", "sk-4"), ("Secrets:orders-api-key", "sk-5")); - [Fact] - public async Task AHostResolvesASecretFromItsOwnConfiguration() - { - // The whole point: dotnet user-secrets and appsettings.Development.json both land here. - AgentCoreOptions? options = null; - using var host = await BuildAsync( - captured => options = captured, - ("AgentCore:Secrets:orders-api-key", "sk-from-config")); - - Assert.NotNull(options!.SecretResolver); - Assert.Equal("sk-from-config", await options.SecretResolver.TryResolveAsync("orders-api-key", Token)); - } + Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); + } - [Fact] - public async Task AnEnvironmentVariableWinsOverTheSameNameInConfiguration() - { - // A deployment's own variable must beat anything a committed settings file carries. - const string Name = "agentcore-hosting-tests-precedence-key"; - Environment.SetEnvironmentVariable(Name, "sk-from-environment"); - try + [Fact] + public async Task AHostResolvesASecretFromItsOwnConfiguration() { + // The whole point: dotnet user-secrets and appsettings.Development.json both land here. AgentCoreOptions? options = null; - using var host = await BuildAsync( + using WebApplication host = await BuildAsync( captured => options = captured, - ($"AgentCore:Secrets:{Name}", "sk-from-config")); + ("AgentCore:Secrets:orders-api-key", "sk-from-config")); - Assert.Equal("sk-from-environment", await options!.SecretResolver!.TryResolveAsync(Name, Token)); + Assert.NotNull(options!.SecretResolver); + Assert.Equal("sk-from-config", await options.SecretResolver.TryResolveAsync("orders-api-key", Token)); } - finally + + [Fact] + public async Task AnEnvironmentVariableWinsOverTheSameNameInConfiguration() { - Environment.SetEnvironmentVariable(Name, null); + // A deployment's own variable must beat anything a committed settings file carries. + const string Name = "agentcore-hosting-tests-precedence-key"; + Environment.SetEnvironmentVariable(Name, "sk-from-environment"); + try + { + AgentCoreOptions? options = null; + using WebApplication host = await BuildAsync( + captured => options = captured, + ($"AgentCore:Secrets:{Name}", "sk-from-config")); + + Assert.Equal("sk-from-environment", await options!.SecretResolver!.TryResolveAsync(Name, Token)); + } + finally + { + Environment.SetEnvironmentVariable(Name, null); + } } - } - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private const string Document = """ + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private const string Document = """ apiVersion: agentcore/v1 agents: items: @@ -133,53 +131,61 @@ public async Task AnEnvironmentVariableWinsOverTheSameNameInConfiguration() - { kind: fake, model: fake-model, as: reply } """; - private static ConfigurationSecretResolver Resolver(params (string Key, string Value)[] entries) - => new ConfigurationSecretResolver( - new ConfigurationBuilder() - .AddInMemoryCollection(entries.Select(entry => new KeyValuePair(entry.Key, entry.Value))) - .Build()); - - private static async Task BuildAsync( - Action configure, - params (string Key, string Value)[] settings) - { - var builder = WebApplication.CreateSlimBuilder(); - builder.WebHost.UseUrls("http://127.0.0.1:0"); - builder.Logging.ClearProviders(); - builder.Configuration.AddInMemoryCollection( - settings.Select(entry => new KeyValuePair(entry.Key, entry.Value))); - - builder.AddAgentCoreHost(options => + private static ConfigurationSecretResolver Resolver(params (string Key, string Value)[] entries) { - options.Configuration = ConfigurationLoader.LoadYaml(Document); - options.UseChatClients(_ => new RecordingChatClientFactory(new FakeSecretChainChatClient())); - configure(options); - }); - - return builder.Build(); - } + return new ConfigurationSecretResolver( + new ConfigurationBuilder() + .AddInMemoryCollection(entries.Select(entry => new KeyValuePair(entry.Key, entry.Value))) + .Build()); + } - private sealed class FakeSecretChainChatClient : IChatClient - { - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "hello"))); - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + private static async Task BuildAsync( + Action configure, + params (string Key, string Value)[] settings) { - await Task.CompletedTask.ConfigureAwait(false); - yield return new ChatResponseUpdate(ChatRole.Assistant, "hello"); + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + _ = builder.WebHost.UseUrls("http://127.0.0.1:0"); + _ = builder.Logging.ClearProviders(); + _ = builder.Configuration.AddInMemoryCollection( + settings.Select(entry => new KeyValuePair(entry.Key, entry.Value))); + + _ = builder.AddAgentCoreHost(options => + { + options.Configuration = ConfigurationLoader.LoadYaml(Document); + _ = options.UseChatClients(_ => new RecordingChatClientFactory(new FakeSecretChainChatClient())); + configure(options); + }); + + return builder.Build(); } - public object? GetService(Type serviceType, object? serviceKey = null) => null; - - public void Dispose() + private sealed class FakeSecretChainChatClient : IChatClient { + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "hello"))); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.CompletedTask.ConfigureAwait(false); + yield return new ChatResponseUpdate(ChatRole.Assistant, "hello"); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkAdapterTests.cs b/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkAdapterTests.cs index 8c89b8cb..5bfa9ff1 100644 --- a/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkAdapterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkAdapterTests.cs @@ -4,87 +4,87 @@ using AgentCore.Application.Secrets; using AgentCore.Infrastructure.Audit.Postgres; using AgentCore.Infrastructure.Tests.Database.Postgres; -using AgentCore.Infrastructure.Tests.Fakes; -using Npgsql; using Xunit; -namespace AgentCore.Infrastructure.Tests.Audit.Postgres; - -/// -/// The postgres audit vendor, which is also where the schema is applied. -/// -public sealed class PostgresAuditSinkAdapterTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Audit.Postgres { - private static readonly VendorProviderConfiguration Entry = - new() { Kind = PostgresAuditSinkAdapter.ProviderKind }; - - /// - protected override bool Migrated => false; - - [Fact] - public void Kind_Always_IsPostgres() - { - // Arrange - PostgresAuditSinkAdapter adapter = new(); - - // Act - var kind = adapter.Kind; - - // Assert - Assert.Equal("postgres", kind); - } - - [Fact] - public async Task OpenAsync_NoConnectionStringAnywhere_FailsTheStart() - { - // Arrange - PostgresAuditSinkAdapter adapter = new(); - ISecretResolverPort empty = new MapSecretResolver(); - - // Act - var failure = await Record.ExceptionAsync(() => adapter.OpenAsync(Entry, empty, Token).AsTask()); - - // Assert - Assert.IsType(failure); - } - - [PostgresFact] - public async Task OpenAsync_UnmigratedDatabase_AppliesTheSchema() + /// + /// The postgres audit vendor, which is also where the schema is applied. + /// + public sealed class PostgresAuditSinkAdapterTests : PostgresDatabaseTest { - // Arrange - PostgresAuditSinkAdapter adapter = new(); - ISecretResolverPort secrets = Resolver(); - - // Act - await using var sink = (PostgresAuditSink)await adapter.OpenAsync(Entry, secrets, Token); - - // Assert - Assert.True(await ScalarAsync("SELECT to_regclass('agentcore.audit_event') IS NOT NULL")); + private static readonly VendorProviderConfiguration Entry = + new() { Kind = PostgresAuditSinkAdapter.ProviderKind }; + + /// + protected override bool Migrated => false; + + [Fact] + public void Kind_Always_IsPostgres() + { + // Arrange + PostgresAuditSinkAdapter adapter = new(); + + // Act + string kind = adapter.Kind; + + // Assert + Assert.Equal("postgres", kind); + } + + [Fact] + public async Task OpenAsync_NoConnectionStringAnywhere_FailsTheStart() + { + // Arrange + PostgresAuditSinkAdapter adapter = new(); + ISecretResolverPort empty = new MapSecretResolver(); + + // Act + Exception? failure = await Record.ExceptionAsync(() => adapter.OpenAsync(Entry, empty, Token).AsTask()); + + // Assert + _ = Assert.IsType(failure); + } + + [PostgresFact] + public async Task OpenAsync_UnmigratedDatabase_AppliesTheSchema() + { + // Arrange + PostgresAuditSinkAdapter adapter = new(); + ISecretResolverPort secrets = Resolver(); + + // Act + await using PostgresAuditSink sink = (PostgresAuditSink)await adapter.OpenAsync(Entry, secrets, Token); + + // Assert + Assert.True(await ScalarAsync("SELECT to_regclass('agentcore.audit_event') IS NOT NULL")); + } + + [PostgresFact] + public async Task OpenAsync_UnmigratedDatabase_ReturnsASinkThatAppends() + { + // Arrange + PostgresAuditSinkAdapter adapter = new(); + await using PostgresAuditSink sink = (PostgresAuditSink)await adapter.OpenAsync(Entry, Resolver(), Token); + + // Act + await sink.AppendAsync( + new() + { + ConversationId = "C1", + EventId = Guid.CreateVersion7(), + Kind = Domain.Audit.AuditEventKind.ConversationStarted, + OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 0, TimeSpan.Zero), + }, + Token); + + // Assert + Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); + } + + private MapSecretResolver Resolver() + { + return new MapSecretResolver().With(KnownSecrets.PostgresConnectionStringName, Database.ConnectionString); + } } - - [PostgresFact] - public async Task OpenAsync_UnmigratedDatabase_ReturnsASinkThatAppends() - { - // Arrange - PostgresAuditSinkAdapter adapter = new(); - await using var sink = (PostgresAuditSink)await adapter.OpenAsync(Entry, Resolver(), Token); - - // Act - await sink.AppendAsync( - new() - { - ConversationId = "C1", - EventId = Guid.CreateVersion7(), - Kind = AgentCore.Domain.Audit.AuditEventKind.ConversationStarted, - OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 0, TimeSpan.Zero), - }, - Token); - - // Assert - Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } - - private MapSecretResolver Resolver() => - new MapSecretResolver().With(KnownSecrets.PostgresConnectionStringName, Database.ConnectionString); - } diff --git a/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkTests.cs b/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkTests.cs index 7549cd70..6a434a5a 100644 --- a/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Audit/Postgres/PostgresAuditSinkTests.cs @@ -4,341 +4,354 @@ using Npgsql; using Xunit; -namespace AgentCore.Infrastructure.Tests.Audit.Postgres; - -/// -/// Store 3 in PostgreSQL. -/// -/// -/// These need a live PostgreSQL and skip without one — names the -/// variable. Each test takes a database of its own. -/// -public sealed class PostgresAuditSinkTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Audit.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task AppendAsync_OneEvent_WritesOneRow() + /// + /// Store 3 in PostgreSQL. + /// + /// + /// These need a live PostgreSQL and skip without one — names the + /// variable. Each test takes a database of its own. + /// + public sealed class PostgresAuditSinkTests : PostgresDatabaseTest { - // Arrange - PostgresAuditSink sink = new(DataSource); + /// + protected override bool Migrated => true; - // Act - await sink.AppendAsync(Started("C1"), Token); + [PostgresFact] + public async Task AppendAsync_OneEvent_WritesOneRow() + { + // Arrange + PostgresAuditSink sink = new(DataSource); - // Assert - Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } + // Act + await sink.AppendAsync(Started("C1"), Token); - [PostgresFact] - public async Task AppendManyAsync_ARun_WritesEveryEventInOrder() - { - // Arrange - PostgresAuditSink sink = new(DataSource); - AuditEvent[] run = [Started("C1"), TurnCompleted("C1", 0), Ended("C1")]; + // Assert + Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); + } - // Act - await sink.AppendManyAsync(run, Token); + [PostgresFact] + public async Task AppendManyAsync_ARun_WritesEveryEventInOrder() + { + // Arrange + PostgresAuditSink sink = new(DataSource); + AuditEvent[] run = [Started("C1"), TurnCompleted("C1", 0), Ended("C1")]; - // Assert — write_position is insertion order, and it lines up with the sequence the store - // assigned because a single-conversation batch is numbered in submission order. - var sequences = await ReadSequencesAsync(); - Assert.Equal([0L, 1L, 2L], sequences); - } + // Act + await sink.AppendManyAsync(run, Token); - [PostgresFact] - public async Task AppendAsync_EventWithNoTurnOrAmendment_StoresBothAsNull() - { - // Arrange - PostgresAuditSink sink = new(DataSource); + // Assert — write_position is insertion order, and it lines up with the sequence the store + // assigned because a single-conversation batch is numbered in submission order. + List sequences = await ReadSequencesAsync(); + Assert.Equal([0L, 1L, 2L], sequences); + } - // Act - await sink.AppendAsync(Started("C1"), Token); + [PostgresFact] + public async Task AppendAsync_EventWithNoTurnOrAmendment_StoresBothAsNull() + { + // Arrange + PostgresAuditSink sink = new(DataSource); - // Assert - var nulls = await ScalarAsync("SELECT turn_index IS NULL AND amends_event_id IS NULL FROM agentcore.audit_event"); - Assert.True(nulls); - } + // Act + await sink.AppendAsync(Started("C1"), Token); - [PostgresFact] - public async Task AppendAsync_EventWithPayload_StoresItAsAJsonObject() - { - // Arrange - PostgresAuditSink sink = new(DataSource); + // Assert + bool nulls = await ScalarAsync("SELECT turn_index IS NULL AND amends_event_id IS NULL FROM agentcore.audit_event"); + Assert.True(nulls); + } - // Act - await sink.AppendAsync(TurnCompleted("C1", 0), Token); + [PostgresFact] + public async Task AppendAsync_EventWithPayload_StoresItAsAJsonObject() + { + // Arrange + PostgresAuditSink sink = new(DataSource); - // Assert - var reply = await ScalarAsync($"SELECT payload ->> '{AuditPayloadKeys.ReplyTextSha256}' FROM agentcore.audit_event"); - Assert.Equal(AuditHash.OfText("the belt ships Friday").Value, reply); - } + // Act + await sink.AppendAsync(TurnCompleted("C1", 0), Token); - [PostgresFact] - public async Task AppendManyAsync_RunHoldingAMalformedEvent_WritesNoneOfIt() - { - // Arrange — an ending with no reason is unreadable a year later, so it is refused before any - // row of the run is written rather than after the first two landed. - PostgresAuditSink sink = new(DataSource); - AuditEvent reasonless = Ended("C1") with { Payload = new Dictionary(StringComparer.Ordinal) }; - AuditEvent[] run = [Started("C1"), TurnCompleted("C1", 0), reasonless]; + // Assert + string reply = await ScalarAsync($"SELECT payload ->> '{AuditPayloadKeys.ReplyTextSha256}' FROM agentcore.audit_event"); + Assert.Equal(AuditHash.OfText("the belt ships Friday").Value, reply); + } - // Act - await Assert.ThrowsAsync(() => sink.AppendManyAsync(run, Token).AsTask()); + [PostgresFact] + public async Task AppendManyAsync_RunHoldingAMalformedEvent_WritesNoneOfIt() + { + // Arrange — an ending with no reason is unreadable a year later, so it is refused before any + // row of the run is written rather than after the first two landed. + PostgresAuditSink sink = new(DataSource); + AuditEvent reasonless = Ended("C1") with { Payload = new Dictionary(StringComparer.Ordinal) }; + AuditEvent[] run = [Started("C1"), TurnCompleted("C1", 0), reasonless]; - // Assert - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } + // Act + _ = await Assert.ThrowsAsync(() => sink.AppendManyAsync(run, Token).AsTask()); - [PostgresFact] - public async Task AppendAsync_ConcurrentWritersOnSeparateConversations_WriteEveryRow() - { - // Arrange — four hosts on one table. Nothing serialises them: there is no head to claim. - var connectionString = Database.ConnectionString; - var writers = Enumerable.Range(0, 4) - .Select(writer => Task.Run( - async () => - { - PostgresAuditSink sink = new(NpgsqlDataSource.Create(connectionString)); - await using (sink) + // Assert + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); + } + + [PostgresFact] + public async Task AppendAsync_ConcurrentWritersOnSeparateConversations_WriteEveryRow() + { + // Arrange — four hosts on one table. Nothing serialises them: there is no head to claim. + string connectionString = Database.ConnectionString; + IEnumerable writers = Enumerable.Range(0, 4) + .Select(writer => Task.Run( + async () => { - foreach (var _ in Enumerable.Range(0, 5)) + PostgresAuditSink sink = new(NpgsqlDataSource.Create(connectionString)); + await using (sink) { - await sink.AppendAsync(Started($"C{writer}"), Token); + foreach (int _ in Enumerable.Range(0, 5)) + { + await sink.AppendAsync(Started($"C{writer}"), Token); + } } - } - }, - Token)); + }, + Token)); - // Act - await Task.WhenAll(writers); + // Act + await Task.WhenAll(writers); - // Assert - Assert.Equal(20L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } + // Assert + Assert.Equal(20L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); + } - [PostgresFact] - public async Task TheStoreNumbersTheChainFromZero() - { - // Every event below shares the same OccurredAt, and EventId is a random-within-a-millisecond - // UUID v7 — so the only signal that could accidentally look like an ordering (occurred_at, or - // event_id) is deliberately useless here. Asserting kind alongside sequence is what would - // catch a regression to ORDER BY d.event_id: that still leaves every sequence dense from - // zero, but scrambles which kind lands on which number, intermittently. - PostgresAuditSink sink = new(DataSource); - - await sink.AppendManyAsync( - [ - Event("C1", AuditEventKind.ConversationStarted), - Event("C1", AuditEventKind.TurnCompleted), - Event("C1", AuditEventKind.ConversationEnded), - ], Token); - - var sequences = await SequencesOfAsync("C1"); - var kinds = await KindsOfAsync("C1"); - Assert.Equal([0L, 1L, 2L], sequences); - Assert.Equal(["conversation.started", "turn.completed", "conversation.ended"], kinds); - } + [PostgresFact] + public async Task TheStoreNumbersTheChainFromZero() + { + // Every event below shares the same OccurredAt, and EventId is a random-within-a-millisecond + // UUID v7 — so the only signal that could accidentally look like an ordering (occurred_at, or + // event_id) is deliberately useless here. Asserting kind alongside sequence is what would + // catch a regression to ORDER BY d.event_id: that still leaves every sequence dense from + // zero, but scrambles which kind lands on which number, intermittently. + PostgresAuditSink sink = new(DataSource); + + await sink.AppendManyAsync( + [ + Event("C1", AuditEventKind.ConversationStarted), + Event("C1", AuditEventKind.TurnCompleted), + Event("C1", AuditEventKind.ConversationEnded), + ], Token); + + long[] sequences = await SequencesOfAsync("C1"); + string[] kinds = await KindsOfAsync("C1"); + Assert.Equal([0L, 1L, 2L], sequences); + Assert.Equal(["conversation.started", "turn.completed", "conversation.ended"], kinds); + } - [PostgresFact] - public async Task ASecondBatchContinuesTheChain() - { - PostgresAuditSink sink = new(DataSource); + [PostgresFact] + public async Task ASecondBatchContinuesTheChain() + { + PostgresAuditSink sink = new(DataSource); - await sink.AppendManyAsync([Event("C1", AuditEventKind.ConversationStarted)], Token); - await sink.AppendManyAsync([Event("C1", AuditEventKind.TurnCompleted)], Token); + await sink.AppendManyAsync([Event("C1", AuditEventKind.ConversationStarted)], Token); + await sink.AppendManyAsync([Event("C1", AuditEventKind.TurnCompleted)], Token); - var sequences = await SequencesOfAsync("C1"); - Assert.Equal([0L, 1L], sequences); - } + long[] sequences = await SequencesOfAsync("C1"); + Assert.Equal([0L, 1L], sequences); + } - [PostgresFact] - public async Task OneBatchNumbersTwoCallsIndependently() - { - PostgresAuditSink sink = new(DataSource); - - await sink.AppendManyAsync( - [ - Event("C1", AuditEventKind.ConversationStarted), - Event("C2", AuditEventKind.ConversationStarted), - Event("C1", AuditEventKind.TurnCompleted), - ], Token); - - var c1Sequences = await SequencesOfAsync("C1"); - var c2Sequences = await SequencesOfAsync("C2"); - Assert.Equal([0L, 1L], c1Sequences); - Assert.Equal([0L], c2Sequences); - } + [PostgresFact] + public async Task OneBatchNumbersTwoCallsIndependently() + { + PostgresAuditSink sink = new(DataSource); + + await sink.AppendManyAsync( + [ + Event("C1", AuditEventKind.ConversationStarted), + Event("C2", AuditEventKind.ConversationStarted), + Event("C1", AuditEventKind.TurnCompleted), + ], Token); + + long[] c1Sequences = await SequencesOfAsync("C1"); + long[] c2Sequences = await SequencesOfAsync("C2"); + Assert.Equal([0L, 1L], c1Sequences); + Assert.Equal([0L], c2Sequences); + } - [PostgresFact] - public async Task AReplayedBatchWritesNothingTwice() - { - PostgresAuditSink sink = new(DataSource); - AuditEvent[] run = [Event("C1", AuditEventKind.ConversationStarted)]; + [PostgresFact] + public async Task AReplayedBatchWritesNothingTwice() + { + PostgresAuditSink sink = new(DataSource); + AuditEvent[] run = [Event("C1", AuditEventKind.ConversationStarted)]; - await sink.AppendManyAsync(run, Token); - await sink.AppendManyAsync(run, Token); + await sink.AppendManyAsync(run, Token); + await sink.AppendManyAsync(run, Token); - var sequences = await SequencesOfAsync("C1"); - Assert.Equal([0L], sequences); - } + long[] sequences = await SequencesOfAsync("C1"); + Assert.Equal([0L], sequences); + } - [PostgresFact] - public async Task APartiallyReplayedBatchLeavesNoGap() - { - // Arrange — C1 already holds a and b at 0 and 1. The second batch replays both and adds c. - // row_number() must never count a and b: they survive nowhere (ON CONFLICT drops them), so - // numbering them would reserve a sequence — here, 2 and 3 — that no row ever lands on, and c - // would land at 4 instead of 2. The NOT EXISTS filter is what keeps this dense. - PostgresAuditSink sink = new(DataSource); - AuditEvent a = Event("C1", AuditEventKind.ConversationStarted); - AuditEvent b = Event("C1", AuditEventKind.TurnCompleted); - AuditEvent c = Event("C1", AuditEventKind.ConversationEnded); - - await sink.AppendManyAsync([a, b], Token); - - // Act - await sink.AppendManyAsync([a, b, c], Token); - - // Assert - var sequences = await SequencesOfAsync("C1"); - Assert.Equal([0L, 1L, 2L], sequences); - } + [PostgresFact] + public async Task APartiallyReplayedBatchLeavesNoGap() + { + // Arrange — C1 already holds a and b at 0 and 1. The second batch replays both and adds c. + // row_number() must never count a and b: they survive nowhere (ON CONFLICT drops them), so + // numbering them would reserve a sequence — here, 2 and 3 — that no row ever lands on, and c + // would land at 4 instead of 2. The NOT EXISTS filter is what keeps this dense. + PostgresAuditSink sink = new(DataSource); + AuditEvent a = Event("C1", AuditEventKind.ConversationStarted); + AuditEvent b = Event("C1", AuditEventKind.TurnCompleted); + AuditEvent c = Event("C1", AuditEventKind.ConversationEnded); + + await sink.AppendManyAsync([a, b], Token); + + // Act + await sink.AppendManyAsync([a, b, c], Token); + + // Assert + long[] sequences = await SequencesOfAsync("C1"); + Assert.Equal([0L, 1L, 2L], sequences); + } - [PostgresFact] - public async Task ConcurrentWritersOnTheSameConversation_NumberDenselyWithNoGapOrDuplicate() - { - // Arrange — one conversation id, several writers. Without the advisory lock two writers can both - // read the same max(sequence) and both compute the same numbers; one of them then loses a - // unique-violation race that QueuedAuditSink would swallow as a dropped batch. The lock is - // what makes that race impossible instead of merely unlikely. - const int writerCount = 4; - const int eventsPerWriter = 5; - var connectionString = Database.ConnectionString; - - var writers = Enumerable.Range(0, writerCount) - .Select(_ => Task.Run( - async () => - { - PostgresAuditSink sink = new(NpgsqlDataSource.Create(connectionString)); - await using (sink) + [PostgresFact] + public async Task ConcurrentWritersOnTheSameConversation_NumberDenselyWithNoGapOrDuplicate() + { + // Arrange — one conversation id, several writers. Without the advisory lock two writers can both + // read the same max(sequence) and both compute the same numbers; one of them then loses a + // unique-violation race that QueuedAuditSink would swallow as a dropped batch. The lock is + // what makes that race impossible instead of merely unlikely. + const int writerCount = 4; + const int eventsPerWriter = 5; + string connectionString = Database.ConnectionString; + + IEnumerable writers = Enumerable.Range(0, writerCount) + .Select(_ => Task.Run( + async () => { - foreach (var _ in Enumerable.Range(0, eventsPerWriter)) + PostgresAuditSink sink = new(NpgsqlDataSource.Create(connectionString)); + await using (sink) { - await sink.AppendAsync(Event("C1", AuditEventKind.TurnCompleted), Token); + foreach (int _ in Enumerable.Range(0, eventsPerWriter)) + { + await sink.AppendAsync(Event("C1", AuditEventKind.TurnCompleted), Token); + } } - } - }, - Token)); - - // Act - await Task.WhenAll(writers); - - // Assert — dense from zero with no gap and no duplicate. A gap or a short count means a - // writer's row was silently dropped; a duplicate cannot reach the table at all, because - // audit_event_conversation_sequence_unique refuses it, so either failure mode shows up here as the - // read sequences failing to equal the full contiguous range. - var sequences = await SequencesOfAsync("C1"); - Assert.Equal( - Enumerable.Range(0, writerCount * eventsPerWriter).Select(i => (long)i), - sequences); - } + }, + Token)); + + // Act + await Task.WhenAll(writers); + + // Assert — dense from zero with no gap and no duplicate. A gap or a short count means a + // writer's row was silently dropped; a duplicate cannot reach the table at all, because + // audit_event_conversation_sequence_unique refuses it, so either failure mode shows up here as the + // read sequences failing to equal the full contiguous range. + long[] sequences = await SequencesOfAsync("C1"); + Assert.Equal( + Enumerable.Range(0, writerCount * eventsPerWriter).Select(i => (long)i), + sequences); + } - private static AuditEvent Started(string conversationId) => new() - { - ConversationId = conversationId, - EventId = Guid.CreateVersion7(), - Kind = AuditEventKind.ConversationStarted, - OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 0, TimeSpan.Zero), - }; + private static AuditEvent Started(string conversationId) + { + return new() + { + ConversationId = conversationId, + EventId = Guid.CreateVersion7(), + Kind = AuditEventKind.ConversationStarted, + OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 0, TimeSpan.Zero), + }; + } - private static AuditEvent TurnCompleted(string conversationId, int turnIndex) => new() - { - ConversationId = conversationId, - EventId = Guid.CreateVersion7(), - Kind = AuditEventKind.TurnCompleted, - OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 1, TimeSpan.Zero), - TurnIndex = turnIndex, - Payload = new Dictionary(StringComparer.Ordinal) + private static AuditEvent TurnCompleted(string conversationId, int turnIndex) { - [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText("the belt ships Friday").Value, - }, - }; + return new() + { + ConversationId = conversationId, + EventId = Guid.CreateVersion7(), + Kind = AuditEventKind.TurnCompleted, + OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 1, TimeSpan.Zero), + TurnIndex = turnIndex, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText("the belt ships Friday").Value, + }, + }; + } - private static AuditEvent Ended(string conversationId) => new() - { - ConversationId = conversationId, - EventId = Guid.CreateVersion7(), - Kind = AuditEventKind.ConversationEnded, - OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 2, TimeSpan.Zero), - Payload = new Dictionary(StringComparer.Ordinal) + private static AuditEvent Ended(string conversationId) { - [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.CallerHungUp), - }, - }; + return new() + { + ConversationId = conversationId, + EventId = Guid.CreateVersion7(), + Kind = AuditEventKind.ConversationEnded, + OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 2, TimeSpan.Zero), + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.CallerHungUp), + }, + }; + } - private static AuditEvent Event(string conversationId, AuditEventKind kind) => new() - { - ConversationId = conversationId, - EventId = Guid.CreateVersion7(), - Kind = kind, - OccurredAt = DateTimeOffset.UnixEpoch, - Payload = kind == AuditEventKind.ConversationEnded - ? new Dictionary(StringComparer.Ordinal) + private static AuditEvent Event(string conversationId, AuditEventKind kind) + { + return new() { - [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.AgentCompleted), - } - : new Dictionary(StringComparer.Ordinal), - }; + ConversationId = conversationId, + EventId = Guid.CreateVersion7(), + Kind = kind, + OccurredAt = DateTimeOffset.UnixEpoch, + Payload = kind == AuditEventKind.ConversationEnded + ? new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.EndReason] = ConversationEndReasons.ToToken(ConversationEndReason.AgentCompleted), + } + : new Dictionary(StringComparer.Ordinal), + }; + } - /// Reads the sequences back in the order the table wrote them. - private async Task> ReadSequencesAsync() - { - List sequences = []; + /// Reads the sequences back in the order the table wrote them. + private async Task> ReadSequencesAsync() + { + List sequences = []; - await using NpgsqlCommand command = DataSource.CreateCommand( - "SELECT sequence FROM agentcore.audit_event ORDER BY write_position"); - await using var reader = await command.ExecuteReaderAsync(Token); + await using NpgsqlCommand command = DataSource.CreateCommand( + "SELECT sequence FROM agentcore.audit_event ORDER BY write_position"); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Token); - while (await reader.ReadAsync(Token)) - { - sequences.Add(reader.GetInt64(0)); + while (await reader.ReadAsync(Token)) + { + sequences.Add(reader.GetInt64(0)); + } + + return sequences; } - return sequences; - } + private async Task SequencesOfAsync(string conversationId) + { + await using NpgsqlCommand command = DataSource.CreateCommand( + "SELECT sequence FROM agentcore.audit_event WHERE conversation_id = $1 ORDER BY sequence"); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - private async Task SequencesOfAsync(string conversationId) - { - await using var command = DataSource.CreateCommand( - "SELECT sequence FROM agentcore.audit_event WHERE conversation_id = $1 ORDER BY sequence"); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + List sequences = []; + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Token); + while (await reader.ReadAsync(Token)) + { + sequences.Add(reader.GetInt64(0)); + } - List sequences = []; - await using var reader = await command.ExecuteReaderAsync(Token); - while (await reader.ReadAsync(Token)) - { - sequences.Add(reader.GetInt64(0)); + return [.. sequences]; } - return [.. sequences]; - } + /// Reads the kinds back in sequence order, so a test can pin which fact landed where. + private async Task KindsOfAsync(string conversationId) + { + await using NpgsqlCommand command = DataSource.CreateCommand( + "SELECT kind FROM agentcore.audit_event WHERE conversation_id = $1 ORDER BY sequence"); + _ = command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); - /// Reads the kinds back in sequence order, so a test can pin which fact landed where. - private async Task KindsOfAsync(string conversationId) - { - await using var command = DataSource.CreateCommand( - "SELECT kind FROM agentcore.audit_event WHERE conversation_id = $1 ORDER BY sequence"); - command.Parameters.Add(new NpgsqlParameter { Value = conversationId }); + List kinds = []; + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Token); + while (await reader.ReadAsync(Token)) + { + kinds.Add(reader.GetString(0)); + } - List kinds = []; - await using var reader = await command.ExecuteReaderAsync(Token); - while (await reader.ReadAsync(Token)) - { - kinds.Add(reader.GetString(0)); + return [.. kinds]; } - - return [.. kinds]; } } diff --git a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreAdapterTests.cs b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreAdapterTests.cs index 8e60a649..6fc412f8 100644 --- a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreAdapterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreAdapterTests.cs @@ -1,32 +1,33 @@ using AgentCore.Infrastructure.Blobs.S3; using Xunit; -namespace AgentCore.Infrastructure.Tests.Blobs.S3; - -/// The s3 vendor's reading of a Backblaze-shaped endpoint. -public sealed class S3BlobStoreAdapterTests +namespace AgentCore.Infrastructure.Tests.Blobs.S3 { - [Theory] - [InlineData("https://s3.us-west-004.backblazeb2.com", "us-west-004")] - [InlineData("https://s3.eu-central-003.backblazeb2.com", "eu-central-003")] - [InlineData("https://S3.us-east-005.backblazeb2.com/", "us-east-005")] - public void RegionOf_BackblazeHost_ReadsTheLabelAfterS3(string endpoint, string expected) + /// The s3 vendor's reading of a Backblaze-shaped endpoint. + public sealed class S3BlobStoreAdapterTests { - Assert.Equal(expected, S3BlobStoreAdapter.RegionOf(endpoint)); - } + [Theory] + [InlineData("https://s3.us-west-004.backblazeb2.com", "us-west-004")] + [InlineData("https://s3.eu-central-003.backblazeb2.com", "eu-central-003")] + [InlineData("https://S3.us-east-005.backblazeb2.com/", "us-east-005")] + public void RegionOf_BackblazeHost_ReadsTheLabelAfterS3(string endpoint, string expected) + { + Assert.Equal(expected, S3BlobStoreAdapter.RegionOf(endpoint)); + } - [Theory] - [InlineData("https://fly.storage.tigris.dev")] - [InlineData("http://localhost:9000")] - [InlineData("not a url")] - public void RegionOf_OtherHost_FallsBackToTheDefault(string endpoint) - { - Assert.Equal(S3BlobStoreAdapter.DefaultRegion, S3BlobStoreAdapter.RegionOf(endpoint)); - } + [Theory] + [InlineData("https://fly.storage.tigris.dev")] + [InlineData("http://localhost:9000")] + [InlineData("not a url")] + public void RegionOf_OtherHost_FallsBackToTheDefault(string endpoint) + { + Assert.Equal(S3BlobStoreAdapter.DefaultRegion, S3BlobStoreAdapter.RegionOf(endpoint)); + } - [Fact] - public void Kind_IsS3() - { - Assert.Equal("s3", new S3BlobStoreAdapter().Kind); + [Fact] + public void Kind_IsS3() + { + Assert.Equal("s3", new S3BlobStoreAdapter().Kind); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreLinkTests.cs b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreLinkTests.cs index 49420f53..e20bde19 100644 --- a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreLinkTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreLinkTests.cs @@ -1,3 +1,4 @@ +using System.Collections.Specialized; using System.Web; using AgentCore.Application.Blobs; using AgentCore.Infrastructure.Blobs.S3; @@ -5,91 +6,94 @@ using Amazon.S3; using Xunit; -namespace AgentCore.Infrastructure.Tests.Blobs.S3; - -/// -/// The presigned link, checked without a bucket: SigV4 signing is local. A browser GET sends -/// Host and nothing else the bucket can check, so X-Amz-SignedHeaders must be -/// exactly host; anything more and the bucket answers SignatureDoesNotMatch. -/// -public sealed class S3BlobStoreLinkTests +namespace AgentCore.Infrastructure.Tests.Blobs.S3 { - private static S3BlobStore Open(string endpoint = "https://s3.us-east-005.backblazeb2.com") - => new( - new AmazonS3Client( - new BasicAWSCredentials("fakeKeyId", "fakeSecret"), - new AmazonS3Config - { - ServiceURL = endpoint, - AuthenticationRegion = "us-east-005", - ForcePathStyle = true, - }), - "SpiritAI"); - - [Fact] - public async Task LinkAsync_PlainHttpEndpoint_LinksOverHttp() + /// + /// The presigned link, checked without a bucket: SigV4 signing is local. A browser GET sends + /// Host and nothing else the bucket can check, so X-Amz-SignedHeaders must be + /// exactly host; anything more and the bucket answers SignatureDoesNotMatch. + /// + public sealed class S3BlobStoreLinkTests { - // Arrange - using var store = Open("http://localhost:59000"); + private static S3BlobStore Open(string endpoint = "https://s3.us-east-005.backblazeb2.com") + { + return new( + new AmazonS3Client( + new BasicAWSCredentials("fakeKeyId", "fakeSecret"), + new AmazonS3Config + { + ServiceURL = endpoint, + AuthenticationRegion = "us-east-005", + ForcePathStyle = true, + }), + "SpiritAI"); + } - // Act - var url = await store.LinkAsync(new BlobRef("conversation-1", "rows.csv", "text/csv", 8), TimeSpan.FromMinutes(1), TestContext.Current.CancellationToken); + [Fact] + public async Task LinkAsync_PlainHttpEndpoint_LinksOverHttp() + { + // Arrange + using S3BlobStore store = Open("http://localhost:59000"); - // Assert - Assert.NotNull(url); - Assert.Equal("http", url.Scheme); - Assert.Equal("localhost", url.Host); - Assert.Equal(59000, url.Port); - } + // Act + Uri? url = await store.LinkAsync(new BlobRef("conversation-1", "rows.csv", "text/csv", 8), TimeSpan.FromMinutes(1), TestContext.Current.CancellationToken); - [Fact] - public async Task LinkAsync_SignsHostOnly_AndCarriesTheResponseOverrides() - { - // Arrange - using var store = Open(); - BlobRef blob = new("conversation-1", "chart.png", "image/png", 48213); + // Assert + Assert.NotNull(url); + Assert.Equal("http", url.Scheme); + Assert.Equal("localhost", url.Host); + Assert.Equal(59000, url.Port); + } - // Act - var url = await store.LinkAsync(blob, TimeSpan.FromMinutes(15), TestContext.Current.CancellationToken); + [Fact] + public async Task LinkAsync_SignsHostOnly_AndCarriesTheResponseOverrides() + { + // Arrange + using S3BlobStore store = Open(); + BlobRef blob = new("conversation-1", "chart.png", "image/png", 48213); - // Assert - Assert.NotNull(url); - Assert.Equal("https", url.Scheme); - Assert.Equal("s3.us-east-005.backblazeb2.com", url.Host); - Assert.Equal("/SpiritAI/conversation-1/chart.png", url.AbsolutePath); + // Act + Uri? url = await store.LinkAsync(blob, TimeSpan.FromMinutes(15), TestContext.Current.CancellationToken); - var query = HttpUtility.ParseQueryString(url.Query); - Assert.Equal("host", query["X-Amz-SignedHeaders"]); - Assert.Equal("900", query["X-Amz-Expires"]); - Assert.Equal("AWS4-HMAC-SHA256", query["X-Amz-Algorithm"]); - Assert.Equal("image/png", query["response-content-type"]); - Assert.Equal("inline; filename*=UTF-8''chart.png", query["response-content-disposition"]); - Assert.NotEmpty(query["X-Amz-Signature"]!); - } + // Assert + Assert.NotNull(url); + Assert.Equal("https", url.Scheme); + Assert.Equal("s3.us-east-005.backblazeb2.com", url.Host); + Assert.Equal("/SpiritAI/conversation-1/chart.png", url.AbsolutePath); - [Fact] - public async Task LinkAsync_Csv_IsServedAsAnAttachment() - { - // Arrange - using var store = Open(); + NameValueCollection query = HttpUtility.ParseQueryString(url.Query); + Assert.Equal("host", query["X-Amz-SignedHeaders"]); + Assert.Equal("900", query["X-Amz-Expires"]); + Assert.Equal("AWS4-HMAC-SHA256", query["X-Amz-Algorithm"]); + Assert.Equal("image/png", query["response-content-type"]); + Assert.Equal("inline; filename*=UTF-8''chart.png", query["response-content-disposition"]); + Assert.NotEmpty(query["X-Amz-Signature"]!); + } - // Act - var url = await store.LinkAsync(new BlobRef("conversation-1", "rows.csv", "text/csv", 8), TimeSpan.FromMinutes(1), TestContext.Current.CancellationToken); + [Fact] + public async Task LinkAsync_Csv_IsServedAsAnAttachment() + { + // Arrange + using S3BlobStore store = Open(); - // Assert - var query = HttpUtility.ParseQueryString(url!.Query); - Assert.Equal("attachment; filename*=UTF-8''rows.csv", query["response-content-disposition"]); - Assert.Equal("60", query["X-Amz-Expires"]); - } + // Act + Uri? url = await store.LinkAsync(new BlobRef("conversation-1", "rows.csv", "text/csv", 8), TimeSpan.FromMinutes(1), TestContext.Current.CancellationToken); - [Fact] - public async Task LinkAsync_UnsafeName_Throws() - { - // Arrange - using var store = Open(); + // Assert + NameValueCollection query = HttpUtility.ParseQueryString(url!.Query); + Assert.Equal("attachment; filename*=UTF-8''rows.csv", query["response-content-disposition"]); + Assert.Equal("60", query["X-Amz-Expires"]); + } + + [Fact] + public async Task LinkAsync_UnsafeName_Throws() + { + // Arrange + using S3BlobStore store = Open(); - // Act + Assert - await Assert.ThrowsAsync(async () => - await store.LinkAsync(new BlobRef("conversation-1", "../x.png", "image/png", 1), TimeSpan.FromMinutes(1), TestContext.Current.CancellationToken)); + // Act + Assert + _ = await Assert.ThrowsAsync(async () => + await store.LinkAsync(new BlobRef("conversation-1", "../x.png", "image/png", 1), TimeSpan.FromMinutes(1), TestContext.Current.CancellationToken)); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreTests.cs b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreTests.cs index 7e0f0b99..0a9baac2 100644 --- a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3BlobStoreTests.cs @@ -5,175 +5,176 @@ using AgentCore.Infrastructure.Blobs.S3; using Xunit; -namespace AgentCore.Infrastructure.Tests.Blobs.S3; - -/// Put, read, replace and sweep, against a real bucket. -public sealed class S3BlobStoreTests : IAsyncLifetime +namespace AgentCore.Infrastructure.Tests.Blobs.S3 { - private readonly string _owner = "test-" + Guid.NewGuid().ToString("N"); + /// Put, read, replace and sweep, against a real bucket. + public sealed class S3BlobStoreTests : IAsyncLifetime + { + private readonly string _owner = "test-" + Guid.NewGuid().ToString("N"); - private IBlobStore? _store; + private IBlobStore? _store; - private IBlobStore Store => _store ?? throw new InvalidOperationException("Not opened."); + private IBlobStore Store => _store ?? throw new InvalidOperationException("Not opened."); - /// - public async ValueTask InitializeAsync() - { - if (!S3Bucket.IsConfigured) + /// + public async ValueTask InitializeAsync() { - return; + if (!S3Bucket.IsConfigured) + { + return; + } + + BlobProviderConfiguration entry = new() + { + Kind = S3BlobStoreAdapter.ProviderKind, + Endpoint = S3Bucket.Endpoint, + Bucket = S3Bucket.Bucket, + }; + + _store = await new S3BlobStoreAdapter().OpenAsync(entry, secrets: null, TestContext.Current.CancellationToken); } - BlobProviderConfiguration entry = new() + /// + public async ValueTask DisposeAsync() { - Kind = S3BlobStoreAdapter.ProviderKind, - Endpoint = S3Bucket.Endpoint, - Bucket = S3Bucket.Bucket, - }; + if (_store is null) + { + return; + } - _store = await new S3BlobStoreAdapter().OpenAsync(entry, secrets: null, TestContext.Current.CancellationToken); - } - - /// - public async ValueTask DisposeAsync() - { - if (_store is null) - { - return; + await _store.DeleteByOwnerAsync(_owner, CancellationToken.None); + (_store as IDisposable)?.Dispose(); } - await _store.DeleteByOwnerAsync(_owner, CancellationToken.None); - (_store as IDisposable)?.Dispose(); - } - - [S3Fact] - public async Task PutAsync_ThenOpenReadAsync_ReturnsTheSameBytesAndMediaType() - { - // Arrange - var bytes = Encoding.UTF8.GetBytes("a,b\n1,2\n"); - var token = TestContext.Current.CancellationToken; - - // Act - var put = await Store.PutAsync(new BlobWrite(_owner, "rows.csv", "text/csv", new MemoryStream(bytes), bytes.Length), token); - await using var read = await Store.OpenReadAsync(_owner, "rows.csv", token); - - // Assert - Assert.Equal(new BlobRef(_owner, "rows.csv", "text/csv", bytes.Length), put); - Assert.NotNull(read); - Assert.Equal("text/csv", read.MediaType); - Assert.Equal(bytes.Length, read.Length); - using MemoryStream copy = new(); - await read.Content.CopyToAsync(copy, token); - Assert.Equal(bytes, copy.ToArray()); - } + [S3Fact] + public async Task PutAsync_ThenOpenReadAsync_ReturnsTheSameBytesAndMediaType() + { + // Arrange + byte[] bytes = Encoding.UTF8.GetBytes("a,b\n1,2\n"); + CancellationToken token = TestContext.Current.CancellationToken; - [S3Fact] - public async Task PutAsync_SameNameTwice_SecondReplacesFirst() - { - // Arrange - var token = TestContext.Current.CancellationToken; - var first = Encoding.UTF8.GetBytes("first"); - var second = Encoding.UTF8.GetBytes("second, longer"); - - // Act - await Store.PutAsync(new BlobWrite(_owner, "chart.png", "image/png", new MemoryStream(first), first.Length), token); - await Store.PutAsync(new BlobWrite(_owner, "chart.png", "image/png", new MemoryStream(second), second.Length), token); - await using var read = await Store.OpenReadAsync(_owner, "chart.png", token); - - // Assert - Assert.NotNull(read); - Assert.Equal(second.Length, read.Length); - } + // Act + BlobRef put = await Store.PutAsync(new BlobWrite(_owner, "rows.csv", "text/csv", new MemoryStream(bytes), bytes.Length), token); + await using BlobRead? read = await Store.OpenReadAsync(_owner, "rows.csv", token); - [S3Fact] - public async Task OpenReadAsync_UnknownName_ReturnsNull() - { - // Act - var read = await Store.OpenReadAsync(_owner, "missing.pdf", TestContext.Current.CancellationToken); + // Assert + Assert.Equal(new BlobRef(_owner, "rows.csv", "text/csv", bytes.Length), put); + Assert.NotNull(read); + Assert.Equal("text/csv", read.MediaType); + Assert.Equal(bytes.Length, read.Length); + using MemoryStream copy = new(); + await read.Content.CopyToAsync(copy, token); + Assert.Equal(bytes, copy.ToArray()); + } - // Assert - Assert.Null(read); - } + [S3Fact] + public async Task PutAsync_SameNameTwice_SecondReplacesFirst() + { + // Arrange + CancellationToken token = TestContext.Current.CancellationToken; + byte[] first = Encoding.UTF8.GetBytes("first"); + byte[] second = Encoding.UTF8.GetBytes("second, longer"); - [S3Fact] - public async Task DeleteByOwnerAsync_RemovesEveryBlobOfThatOwnerOnly() - { - // Arrange - var token = TestContext.Current.CancellationToken; - var other = _owner + "-other"; - var bytes = new byte[] { 1, 2, 3 }; + // Act + _ = await Store.PutAsync(new BlobWrite(_owner, "chart.png", "image/png", new MemoryStream(first), first.Length), token); + _ = await Store.PutAsync(new BlobWrite(_owner, "chart.png", "image/png", new MemoryStream(second), second.Length), token); + await using BlobRead? read = await Store.OpenReadAsync(_owner, "chart.png", token); - await Store.PutAsync(new BlobWrite(_owner, "a.png", "image/png", new MemoryStream(bytes), bytes.Length), token); - await Store.PutAsync(new BlobWrite(_owner, "b.pdf", "application/pdf", new MemoryStream(bytes), bytes.Length), token); - await Store.PutAsync(new BlobWrite(other, "a.png", "image/png", new MemoryStream(bytes), bytes.Length), token); + // Assert + Assert.NotNull(read); + Assert.Equal(second.Length, read.Length); + } - try + [S3Fact] + public async Task OpenReadAsync_UnknownName_ReturnsNull() { // Act - await Store.DeleteByOwnerAsync(_owner, token); + BlobRead? read = await Store.OpenReadAsync(_owner, "missing.pdf", TestContext.Current.CancellationToken); // Assert - Assert.Null(await Store.OpenReadAsync(_owner, "a.png", token)); - Assert.Null(await Store.OpenReadAsync(_owner, "b.pdf", token)); - await using var kept = await Store.OpenReadAsync(other, "a.png", token); - Assert.NotNull(kept); + Assert.Null(read); } - finally + + [S3Fact] + public async Task DeleteByOwnerAsync_RemovesEveryBlobOfThatOwnerOnly() { - await Store.DeleteByOwnerAsync(other, CancellationToken.None); + // Arrange + CancellationToken token = TestContext.Current.CancellationToken; + string other = _owner + "-other"; + byte[] bytes = [1, 2, 3]; + + _ = await Store.PutAsync(new BlobWrite(_owner, "a.png", "image/png", new MemoryStream(bytes), bytes.Length), token); + _ = await Store.PutAsync(new BlobWrite(_owner, "b.pdf", "application/pdf", new MemoryStream(bytes), bytes.Length), token); + _ = await Store.PutAsync(new BlobWrite(other, "a.png", "image/png", new MemoryStream(bytes), bytes.Length), token); + + try + { + // Act + await Store.DeleteByOwnerAsync(_owner, token); + + // Assert + Assert.Null(await Store.OpenReadAsync(_owner, "a.png", token)); + Assert.Null(await Store.OpenReadAsync(_owner, "b.pdf", token)); + await using BlobRead? kept = await Store.OpenReadAsync(other, "a.png", token); + Assert.NotNull(kept); + } + finally + { + await Store.DeleteByOwnerAsync(other, CancellationToken.None); + } } - } - [S3Fact] - public async Task StatAsync_StoredBlob_ReturnsItsFactsWithoutTheBytes() - { - // Arrange - var bytes = Encoding.UTF8.GetBytes("a,b\n1,2\n"); - var token = TestContext.Current.CancellationToken; - await Store.PutAsync(new BlobWrite(_owner, "rows.csv", "text/csv", new MemoryStream(bytes), bytes.Length), token); + [S3Fact] + public async Task StatAsync_StoredBlob_ReturnsItsFactsWithoutTheBytes() + { + // Arrange + byte[] bytes = Encoding.UTF8.GetBytes("a,b\n1,2\n"); + CancellationToken token = TestContext.Current.CancellationToken; + _ = await Store.PutAsync(new BlobWrite(_owner, "rows.csv", "text/csv", new MemoryStream(bytes), bytes.Length), token); - // Act - var stat = await Store.StatAsync(_owner, "rows.csv", token); + // Act + BlobRef? stat = await Store.StatAsync(_owner, "rows.csv", token); - // Assert - Assert.Equal(new BlobRef(_owner, "rows.csv", "text/csv", bytes.Length), stat); - } + // Assert + Assert.Equal(new BlobRef(_owner, "rows.csv", "text/csv", bytes.Length), stat); + } - [S3Fact] - public async Task StatAsync_UnknownName_ReturnsNull() - { - // Act - var stat = await Store.StatAsync(_owner, "never.png", TestContext.Current.CancellationToken); + [S3Fact] + public async Task StatAsync_UnknownName_ReturnsNull() + { + // Act + BlobRef? stat = await Store.StatAsync(_owner, "never.png", TestContext.Current.CancellationToken); - // Assert - Assert.Null(stat); - } + // Assert + Assert.Null(stat); + } - [S3Fact] - public async Task LinkAsync_StoredBlob_IsFetchableWithNoCredential() - { - // Arrange - var bytes = new byte[] { 0x89, 0x50, 0x4E, 0x47 }; - var token = TestContext.Current.CancellationToken; - var blob = await Store.PutAsync(new BlobWrite(_owner, "chart.png", "image/png", new MemoryStream(bytes), bytes.Length), token); - - // Act - var url = await Store.LinkAsync(blob, TimeSpan.FromMinutes(1), token); - using HttpClient anonymous = new(); - using var fetched = await anonymous.GetAsync(url, token); - - // Assert - Assert.Equal(System.Net.HttpStatusCode.OK, fetched.StatusCode); - Assert.Equal("image/png", fetched.Content.Headers.ContentType?.MediaType); - Assert.Equal("inline", fetched.Content.Headers.ContentDisposition?.DispositionType); - Assert.Equal(bytes, await fetched.Content.ReadAsByteArrayAsync(token)); - } + [S3Fact] + public async Task LinkAsync_StoredBlob_IsFetchableWithNoCredential() + { + // Arrange + byte[] bytes = [0x89, 0x50, 0x4E, 0x47]; + CancellationToken token = TestContext.Current.CancellationToken; + BlobRef blob = await Store.PutAsync(new BlobWrite(_owner, "chart.png", "image/png", new MemoryStream(bytes), bytes.Length), token); - [S3Fact] - public async Task DeleteByOwnerAsync_NothingStored_DoesNotThrow() - { - var error = await Record.ExceptionAsync(() => Store.DeleteByOwnerAsync(_owner, TestContext.Current.CancellationToken).AsTask()); + // Act + Uri? url = await Store.LinkAsync(blob, TimeSpan.FromMinutes(1), token); + using HttpClient anonymous = new(); + using HttpResponseMessage fetched = await anonymous.GetAsync(url, token); - Assert.Null(error); + // Assert + Assert.Equal(System.Net.HttpStatusCode.OK, fetched.StatusCode); + Assert.Equal("image/png", fetched.Content.Headers.ContentType?.MediaType); + Assert.Equal("inline", fetched.Content.Headers.ContentDisposition?.DispositionType); + Assert.Equal(bytes, await fetched.Content.ReadAsByteArrayAsync(token)); + } + + [S3Fact] + public async Task DeleteByOwnerAsync_NothingStored_DoesNotThrow() + { + Exception? error = await Record.ExceptionAsync(() => Store.DeleteByOwnerAsync(_owner, TestContext.Current.CancellationToken).AsTask()); + + Assert.Null(error); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3Bucket.cs b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3Bucket.cs index a44fd2d6..b95aeacb 100644 --- a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3Bucket.cs +++ b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3Bucket.cs @@ -1,28 +1,31 @@ -namespace AgentCore.Infrastructure.Tests.Blobs.S3; - -/// The S3-compatible bucket the integration tests write into, if the environment names one. -/// -/// AGENTCORE_TEST_S3_ENDPOINT and AGENTCORE_TEST_S3_BUCKET name it. The credential is -/// read the way the adapter reads it: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. -/// -public static class S3Bucket +namespace AgentCore.Infrastructure.Tests.Blobs.S3 { - private const string EndpointVariable = "AGENTCORE_TEST_S3_ENDPOINT"; + /// The S3-compatible bucket the integration tests write into, if the environment names one. + /// + /// AGENTCORE_TEST_S3_ENDPOINT and AGENTCORE_TEST_S3_BUCKET name it. The credential is + /// read the way the adapter reads it: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. + /// + public static class S3Bucket + { + private const string EndpointVariable = "AGENTCORE_TEST_S3_ENDPOINT"; - private const string BucketVariable = "AGENTCORE_TEST_S3_BUCKET"; + private const string BucketVariable = "AGENTCORE_TEST_S3_BUCKET"; - /// Why a test skipped, when it did. - public const string SkipReason = "Set AGENTCORE_TEST_S3_ENDPOINT and AGENTCORE_TEST_S3_BUCKET to run."; + /// Why a test skipped, when it did. + public const string SkipReason = "Set AGENTCORE_TEST_S3_ENDPOINT and AGENTCORE_TEST_S3_BUCKET to run."; - /// The service URL, or null when the environment names none. - public static string? Endpoint => Read(EndpointVariable); + /// The service URL, or null when the environment names none. + public static string? Endpoint => Read(EndpointVariable); - /// The bucket, or null when the environment names none. - public static string? Bucket => Read(BucketVariable); + /// The bucket, or null when the environment names none. + public static string? Bucket => Read(BucketVariable); - /// Whether a bucket was named. - public static bool IsConfigured => Endpoint is not null && Bucket is not null; + /// Whether a bucket was named. + public static bool IsConfigured => Endpoint is not null && Bucket is not null; - private static string? Read(string variable) => - Environment.GetEnvironmentVariable(variable) is { Length: > 0 } value ? value : null; + private static string? Read(string variable) + { + return Environment.GetEnvironmentVariable(variable) is { Length: > 0 } value ? value : null; + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3FactAttribute.cs b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3FactAttribute.cs index 4fe1ac1b..b3e805f6 100644 --- a/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3FactAttribute.cs +++ b/tests/AgentCore.Infrastructure.Tests/Blobs/S3/S3FactAttribute.cs @@ -1,21 +1,22 @@ using System.Runtime.CompilerServices; using Xunit; -namespace AgentCore.Infrastructure.Tests.Blobs.S3; - -/// A test that needs a live S3-compatible bucket, and skips itself when none is named. -public sealed class S3FactAttribute : FactAttribute +namespace AgentCore.Infrastructure.Tests.Blobs.S3 { - /// Creates the attribute. - /// Supplied by the compiler. - /// Supplied by the compiler. - public S3FactAttribute( - [CallerFilePath] string? sourceFilePath = null, - [CallerLineNumber] int sourceLineNumber = -1) - : base(sourceFilePath, sourceLineNumber) + /// A test that needs a live S3-compatible bucket, and skips itself when none is named. + public sealed class S3FactAttribute : FactAttribute { - Skip = S3Bucket.SkipReason; - SkipUnless = nameof(S3Bucket.IsConfigured); - SkipType = typeof(S3Bucket); + /// Creates the attribute. + /// Supplied by the compiler. + /// Supplied by the compiler. + public S3FactAttribute( + [CallerFilePath] string? sourceFilePath = null, + [CallerLineNumber] int sourceLineNumber = -1) + : base(sourceFilePath, sourceLineNumber) + { + Skip = S3Bucket.SkipReason; + SkipUnless = nameof(S3Bucket.IsConfigured); + SkipType = typeof(S3Bucket); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ContinuationStoreTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ContinuationStoreTests.cs index ebe63b75..a226dfad 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ContinuationStoreTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ContinuationStoreTests.cs @@ -3,68 +3,69 @@ using AgentCore.Infrastructure.Tests.Database.Postgres; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// The continuation map beside the conversations: one envelope per opaque id. -public sealed class ContinuationStoreTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task Migration_Applied_MakesTheContinuationTable() + /// The continuation map beside the conversations: one envelope per opaque id. + public sealed class ContinuationStoreTests : PostgresDatabaseTest { - // Act - var tables = await ScalarAsync( - """ + /// + protected override bool Migrated => true; + + [PostgresFact] + public async Task Migration_Applied_MakesTheContinuationTable() + { + // Act + long tables = await ScalarAsync( + """ SELECT count(*) FROM information_schema.tables WHERE table_schema = 'agentcore' AND table_name = 'response_continuation' """); - // Assert - Assert.Equal(1, tables); - } + // Assert + Assert.Equal(1, tables); + } - [PostgresFact] - public async Task RoundTrip_SaveGetDelete() - { - // Arrange - PostgresConversationStore store = new(DataSource); - using var document = JsonDocument.Parse("""{ "conversationId": "c1", "state": {} }"""); + [PostgresFact] + public async Task RoundTrip_SaveGetDelete() + { + // Arrange + PostgresConversationStore store = new(DataSource); + using JsonDocument document = JsonDocument.Parse("""{ "conversationId": "c1", "state": {} }"""); - // Act - await store.SaveContinuationAsync("conv_1", document.RootElement, Token); - var found = await store.GetContinuationAsync("conv_1", Token); + // Act + await store.SaveContinuationAsync("conv_1", document.RootElement, Token); + JsonElement? found = await store.GetContinuationAsync("conv_1", Token); - // Assert - Assert.NotNull(found); - Assert.True(JsonElement.DeepEquals(document.RootElement, found.Value)); + // Assert + _ = Assert.NotNull(found); + Assert.True(JsonElement.DeepEquals(document.RootElement, found.Value)); - // Act - using var replacement = JsonDocument.Parse("{}"); - await store.SaveContinuationAsync("conv_1", replacement.RootElement, Token); - var replaced = await store.GetContinuationAsync("conv_1", Token); + // Act + using JsonDocument replacement = JsonDocument.Parse("{}"); + await store.SaveContinuationAsync("conv_1", replacement.RootElement, Token); + JsonElement? replaced = await store.GetContinuationAsync("conv_1", Token); - // Assert - Assert.Equal("{}", replaced?.GetRawText()); + // Assert + Assert.Equal("{}", replaced?.GetRawText()); - // Act - await store.DeleteContinuationAsync("conv_1", Token); + // Act + await store.DeleteContinuationAsync("conv_1", Token); - // Assert - Assert.Null(await store.GetContinuationAsync("conv_1", Token)); - } + // Assert + Assert.Null(await store.GetContinuationAsync("conv_1", Token)); + } - [PostgresFact] - public async Task GetContinuation_UnknownId_AnswersNull() - { - // Arrange - PostgresConversationStore store = new(DataSource); + [PostgresFact] + public async Task GetContinuation_UnknownId_AnswersNull() + { + // Arrange + PostgresConversationStore store = new(DataSource); - // Act - var found = await store.GetContinuationAsync("conv_missing", Token); + // Act + JsonElement? found = await store.GetContinuationAsync("conv_missing", Token); - // Assert - Assert.Null(found); + // Assert + Assert.Null(found); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ConversationThreadSchemaTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ConversationThreadSchemaTests.cs index 4ff12240..b78e428c 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ConversationThreadSchemaTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/ConversationThreadSchemaTests.cs @@ -2,82 +2,82 @@ using Npgsql; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// Store 0's shape, and what the running role may do to it. -/// -/// conversation and role are both non-reserved keywords in PostgreSQL and need no quoting. That -/// is what the first test proves: the migration would fail to apply at all if it were untrue. -/// -/// The primary key's column order is read from the catalogue rather than inferred from behaviour. A -/// listing filters by principal, so principal has to lead, and either order satisfies uniqueness. -/// -/// -public sealed class ConversationThreadSchemaTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task Migration_Applied_MakesBothTables() + /// Store 0's shape, and what the running role may do to it. + /// + /// conversation and role are both non-reserved keywords in PostgreSQL and need no quoting. That + /// is what the first test proves: the migration would fail to apply at all if it were untrue. + /// + /// The primary key's column order is read from the catalogue rather than inferred from behaviour. A + /// listing filters by principal, so principal has to lead, and either order satisfies uniqueness. + /// + /// + public sealed class ConversationThreadSchemaTests : PostgresDatabaseTest { - // Act - var tables = await ScalarAsync( - """ + /// + protected override bool Migrated => true; + + [PostgresFact] + public async Task Migration_Applied_MakesBothTables() + { + // Act + long tables = await ScalarAsync( + """ SELECT count(*) FROM information_schema.tables WHERE table_schema = 'agentcore' AND table_name IN ('conversation', 'conversation_principal') """); - // Assert - Assert.Equal(2, tables); - } - - [PostgresFact] - public async Task Conversation_AStatusOutsideTheTwo_IsRefused() - { - // Act - var refusal = await Record.ExceptionAsync( - () => ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id, status) VALUES ('c1', 'nonsense')")); - - // Assert - Assert.Equal("23514", Assert.IsType(refusal).SqlState); - } - - [PostgresFact] - public async Task ConversationPrincipal_ItsConversationDeleted_GoesWithIt() - { - // Arrange - await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('c1')"); - await ExecuteAsync("INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('c1', 'p1', 'caller')"); - - // Act - await ExecuteAsync("DELETE FROM agentcore.conversation WHERE conversation_id = 'c1'"); - - // Assert - Assert.Equal(0, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task ConversationPrincipal_TheSamePairTwice_IsRefusedByThePrimaryKey() - { - // Arrange - await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('c1')"); - await ExecuteAsync("INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('c1', 'p1', 'caller')"); - - // Act - var refusal = await Record.ExceptionAsync( - () => ExecuteAsync("INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('c1', 'p1', 'agent')")); - - // Assert - Assert.Equal("23505", Assert.IsType(refusal).SqlState); - } - - [PostgresFact] - public async Task ConversationPrincipal_ItsPrimaryKey_LeadsWithThePrincipal() - { - // Act - var columns = await ScalarAsync( - """ + // Assert + Assert.Equal(2, tables); + } + + [PostgresFact] + public async Task Conversation_AStatusOutsideTheTwo_IsRefused() + { + // Act + Exception? refusal = await Record.ExceptionAsync( + () => ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id, status) VALUES ('c1', 'nonsense')")); + + // Assert + Assert.Equal("23514", Assert.IsType(refusal).SqlState); + } + + [PostgresFact] + public async Task ConversationPrincipal_ItsConversationDeleted_GoesWithIt() + { + // Arrange + await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('c1')"); + await ExecuteAsync("INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('c1', 'p1', 'caller')"); + + // Act + await ExecuteAsync("DELETE FROM agentcore.conversation WHERE conversation_id = 'c1'"); + + // Assert + Assert.Equal(0, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task ConversationPrincipal_TheSamePairTwice_IsRefusedByThePrimaryKey() + { + // Arrange + await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('c1')"); + await ExecuteAsync("INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('c1', 'p1', 'caller')"); + + // Act + Exception? refusal = await Record.ExceptionAsync( + () => ExecuteAsync("INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('c1', 'p1', 'agent')")); + + // Assert + Assert.Equal("23505", Assert.IsType(refusal).SqlState); + } + + [PostgresFact] + public async Task ConversationPrincipal_ItsPrimaryKey_LeadsWithThePrincipal() + { + // Act + string columns = await ScalarAsync( + """ SELECT string_agg(a.attname, ',' ORDER BY k.ord) FROM pg_index i JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord) ON true @@ -85,42 +85,43 @@ JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord) ON true WHERE i.indrelid = 'agentcore.conversation_principal'::regclass AND i.indisprimary """); - // Assert - Assert.Equal("principal_key,conversation_id", columns); - } + // Assert + Assert.Equal("principal_key,conversation_id", columns); + } - [PostgresFact] - public async Task ConversationPrincipal_TheOtherDirection_HasItsOwnIndex() - { - // Act - var indexes = await ScalarAsync( - """ + [PostgresFact] + public async Task ConversationPrincipal_TheOtherDirection_HasItsOwnIndex() + { + // Act + long indexes = await ScalarAsync( + """ SELECT count(*) FROM pg_indexes WHERE schemaname = 'agentcore' AND tablename = 'conversation_principal' AND indexname = 'conversation_principal_conversation_idx' """); - // Assert - Assert.Equal(1, indexes); - } - - [PostgresTheory] - [InlineData("agentcore.conversation", "SELECT")] - [InlineData("agentcore.conversation", "INSERT")] - [InlineData("agentcore.conversation", "UPDATE")] - [InlineData("agentcore.conversation", "DELETE")] - [InlineData("agentcore.conversation_principal", "SELECT")] - [InlineData("agentcore.conversation_principal", "INSERT")] - [InlineData("agentcore.conversation_principal", "UPDATE")] - [InlineData("agentcore.conversation_principal", "DELETE")] - public async Task Writer_EachStoreZeroPrivilege_IsGranted(string table, string privilege) - { - // Act - var granted = await ScalarAsync( - $"SELECT has_table_privilege('agentcore_writer', '{table}', '{privilege}')"); - - // Assert - Assert.True(granted); + // Assert + Assert.Equal(1, indexes); + } + + [PostgresTheory] + [InlineData("agentcore.conversation", "SELECT")] + [InlineData("agentcore.conversation", "INSERT")] + [InlineData("agentcore.conversation", "UPDATE")] + [InlineData("agentcore.conversation", "DELETE")] + [InlineData("agentcore.conversation_principal", "SELECT")] + [InlineData("agentcore.conversation_principal", "INSERT")] + [InlineData("agentcore.conversation_principal", "UPDATE")] + [InlineData("agentcore.conversation_principal", "DELETE")] + public async Task Writer_EachStoreZeroPrivilege_IsGranted(string table, string privilege) + { + // Act + bool granted = await ScalarAsync( + $"SELECT has_table_privilege('agentcore_writer', '{table}', '{privilege}')"); + + // Assert + Assert.True(granted); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationListTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationListTests.cs index 5e26e917..34766981 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationListTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationListTests.cs @@ -3,224 +3,227 @@ using AgentCore.Infrastructure.Tests.Database.Postgres; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// The listing behind a thread sidebar. -public sealed class PostgresConversationListTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task ListAsync_APrincipalWithNoConversations_IsEmptyAndHasNoCursor() + /// The listing behind a thread sidebar. + public sealed class PostgresConversationListTests : PostgresDatabaseTest { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); + /// + protected override bool Migrated => true; - // Act - var page = await store.ListAsync("nobody", after: null, limit: 10, cancellationToken: Token); + [PostgresFact] + public async Task ListAsync_APrincipalWithNoConversations_IsEmptyAndHasNoCursor() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); - // Assert - Assert.Empty(page.Conversations); - Assert.Null(page.NextCursor); - } + // Act + ConversationPage page = await store.ListAsync("nobody", after: null, limit: 10, cancellationToken: Token); - [PostgresFact] - public async Task ListAsync_AnotherPrincipalsConversation_IsNotReturned() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "mine", "person-a"); - await Claim(store, "theirs", "person-b"); + // Assert + Assert.Empty(page.Conversations); + Assert.Null(page.NextCursor); + } - // Act - var page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + [PostgresFact] + public async Task ListAsync_AnotherPrincipalsConversation_IsNotReturned() + { + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "mine", "person-a"); + await Claim(store, "theirs", "person-b"); - // Assert - Assert.Equal(["mine"], page.Conversations.Select(conversation => conversation.ConversationId)); - } + // Act + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - [PostgresFact] - public async Task ListAsync_AConversationWithTwoKeys_IsFoundByEither() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Act - var byTenant = await store.ListAsync("tenant-a", after: null, limit: 10, cancellationToken: Token); - var byPerson = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - - // Assert - Assert.Single(byTenant.Conversations); - Assert.Single(byPerson.Conversations); - } + // Assert + Assert.Equal(["mine"], page.Conversations.Select(conversation => conversation.ConversationId)); + } - [PostgresFact] - public async Task ListAsync_MostRecentlySpokenFirst_IsTheOrder() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "old", "person-a"); - await Claim(store, "new", "person-a"); - await Spoke("old", "-2 hours"); - await Spoke("new", "-1 minute"); - - // Act - var page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - - // Assert - Assert.Equal(["new", "old"], page.Conversations.Select(conversation => conversation.ConversationId)); - } + [PostgresFact] + public async Task ListAsync_AConversationWithTwoKeys_IsFoundByEither() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Act + ConversationPage byTenant = await store.ListAsync("tenant-a", after: null, limit: 10, cancellationToken: Token); + ConversationPage byPerson = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + + // Assert + _ = Assert.Single(byTenant.Conversations); + _ = Assert.Single(byPerson.Conversations); + } - [PostgresFact] - public async Task ListAsync_AConversationWithNoMessages_IsListedByItsCreationTime() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "spoken", "person-a"); - await Spoke("spoken", "-2 hours"); - await Claim(store, "silent", "person-a"); + [PostgresFact] + public async Task ListAsync_MostRecentlySpokenFirst_IsTheOrder() + { + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "old", "person-a"); + await Claim(store, "new", "person-a"); + await Spoke("old", "-2 hours"); + await Spoke("new", "-1 minute"); + + // Act + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + + // Assert + Assert.Equal(["new", "old"], page.Conversations.Select(conversation => conversation.ConversationId)); + } - // Act - var page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + [PostgresFact] + public async Task ListAsync_AConversationWithNoMessages_IsListedByItsCreationTime() + { + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "spoken", "person-a"); + await Spoke("spoken", "-2 hours"); + await Claim(store, "silent", "person-a"); - // Assert - Assert.Equal(["silent", "spoken"], page.Conversations.Select(conversation => conversation.ConversationId)); - } + // Act + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - [PostgresFact] - public async Task ListAsync_ArchivedByDefault_IsStillListed() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "c1", "person-a"); - await store.SetStatusAsync("c1", ConversationStatus.Archived, Token); + // Assert + Assert.Equal(["silent", "spoken"], page.Conversations.Select(conversation => conversation.ConversationId)); + } - // Act - var page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); + [PostgresFact] + public async Task ListAsync_ArchivedByDefault_IsStillListed() + { + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "c1", "person-a"); + await store.SetStatusAsync("c1", ConversationStatus.Archived, Token); - // Assert - Assert.Single(page.Conversations); - Assert.Equal(ConversationStatus.Archived, page.Conversations[0].Status); - } + // Act + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, cancellationToken: Token); - [PostgresFact] - public async Task ListAsync_NarrowedToRegular_LeavesArchivedOut() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "kept", "person-a"); - await Claim(store, "filed", "person-a"); - await store.SetStatusAsync("filed", ConversationStatus.Archived, Token); + // Assert + _ = Assert.Single(page.Conversations); + Assert.Equal(ConversationStatus.Archived, page.Conversations[0].Status); + } - // Act - var page = await store.ListAsync("person-a", after: null, limit: 10, ConversationStatus.Regular, Token); + [PostgresFact] + public async Task ListAsync_NarrowedToRegular_LeavesArchivedOut() + { + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "kept", "person-a"); + await Claim(store, "filed", "person-a"); + await store.SetStatusAsync("filed", ConversationStatus.Archived, Token); - // Assert - Assert.Equal(["kept"], page.Conversations.Select(conversation => conversation.ConversationId)); - } + // Act + ConversationPage page = await store.ListAsync("person-a", after: null, limit: 10, ConversationStatus.Regular, Token); - [PostgresFact] - public async Task ListAsync_PagedToTheEnd_ReturnsEveryConversationExactlyOnce() - { - // Arrange - PostgresConversationStore store = new(DataSource); - for (var i = 0; i < 25; i++) - { - await Claim(store, $"c{i:D2}", "person-a"); - await Spoke($"c{i:D2}", $"-{i} minutes"); + // Assert + Assert.Equal(["kept"], page.Conversations.Select(conversation => conversation.ConversationId)); } - // Act - List seen = []; - string? cursor = null; - do + [PostgresFact] + public async Task ListAsync_PagedToTheEnd_ReturnsEveryConversationExactlyOnce() { - var page = await store.ListAsync("person-a", cursor, limit: 7, cancellationToken: Token); - seen.AddRange(page.Conversations.Select(conversation => conversation.ConversationId)); - cursor = page.NextCursor; + // Arrange + PostgresConversationStore store = new(DataSource); + for (int i = 0; i < 25; i++) + { + await Claim(store, $"c{i:D2}", "person-a"); + await Spoke($"c{i:D2}", $"-{i} minutes"); + } + + // Act + List seen = []; + string? cursor = null; + do + { + ConversationPage page = await store.ListAsync("person-a", cursor, limit: 7, cancellationToken: Token); + seen.AddRange(page.Conversations.Select(conversation => conversation.ConversationId)); + cursor = page.NextCursor; + } + while (cursor is not null); + + // Assert + Assert.Equal(25, seen.Count); + Assert.Equal(25, seen.Distinct().Count()); } - while (cursor is not null); - - // Assert - Assert.Equal(25, seen.Count); - Assert.Equal(25, seen.Distinct().Count()); - } - [PostgresFact] - public async Task ListAsync_ConversationsSharingOneTimestamp_AreStillPagedWithoutLoss() - { - // Arrange - PostgresConversationStore store = new(DataSource); - for (var i = 0; i < 6; i++) + [PostgresFact] + public async Task ListAsync_ConversationsSharingOneTimestamp_AreStillPagedWithoutLoss() { - await Claim(store, $"c{i}", "person-a"); + // Arrange + PostgresConversationStore store = new(DataSource); + for (int i = 0; i < 6; i++) + { + await Claim(store, $"c{i}", "person-a"); + } + + await ExecuteAsync("UPDATE agentcore.conversation SET created_at = timestamptz '2026-01-01 00:00:00+00'"); + + // Act + List seen = []; + string? cursor = null; + do + { + ConversationPage page = await store.ListAsync("person-a", cursor, limit: 2, cancellationToken: Token); + seen.AddRange(page.Conversations.Select(conversation => conversation.ConversationId)); + cursor = page.NextCursor; + } + while (cursor is not null); + + // Assert + Assert.Equal(6, seen.Count); + Assert.Equal(6, seen.Distinct().Count()); } - await ExecuteAsync("UPDATE agentcore.conversation SET created_at = timestamptz '2026-01-01 00:00:00+00'"); - - // Act - List seen = []; - string? cursor = null; - do + [PostgresFact] + public async Task ListAsync_AnExactlyFullLastPage_EndsOnTheFollowingEmptyOne() { - var page = await store.ListAsync("person-a", cursor, limit: 2, cancellationToken: Token); - seen.AddRange(page.Conversations.Select(conversation => conversation.ConversationId)); - cursor = page.NextCursor; + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "c1", "person-a"); + await Claim(store, "c2", "person-a"); + + // Act + ConversationPage first = await store.ListAsync("person-a", after: null, limit: 2, cancellationToken: Token); + ConversationPage second = await store.ListAsync("person-a", first.NextCursor, limit: 2, cancellationToken: Token); + + // Assert + Assert.NotNull(first.NextCursor); + Assert.Empty(second.Conversations); + Assert.Null(second.NextCursor); } - while (cursor is not null); - - // Assert - Assert.Equal(6, seen.Count); - Assert.Equal(6, seen.Distinct().Count()); - } - [PostgresFact] - public async Task ListAsync_AnExactlyFullLastPage_EndsOnTheFollowingEmptyOne() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "c1", "person-a"); - await Claim(store, "c2", "person-a"); - - // Act - var first = await store.ListAsync("person-a", after: null, limit: 2, cancellationToken: Token); - var second = await store.ListAsync("person-a", first.NextCursor, limit: 2, cancellationToken: Token); - - // Assert - Assert.NotNull(first.NextCursor); - Assert.Empty(second.Conversations); - Assert.Null(second.NextCursor); - } - - [PostgresFact] - public async Task ListAsync_ACursorThatIsNotOne_ServesTheFirstPage() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await Claim(store, "c1", "person-a"); + [PostgresFact] + public async Task ListAsync_ACursorThatIsNotOne_ServesTheFirstPage() + { + // Arrange + PostgresConversationStore store = new(DataSource); + await Claim(store, "c1", "person-a"); - // Act - var page = await store.ListAsync("person-a", "not-a-cursor", limit: 10, cancellationToken: Token); + // Act + ConversationPage page = await store.ListAsync("person-a", "not-a-cursor", limit: 10, cancellationToken: Token); - // Assert - Assert.Single(page.Conversations); - } + // Assert + _ = Assert.Single(page.Conversations); + } - private static async Task Claim(PostgresConversationStore store, string conversationId, string principalKey) - { - await store.CreateAsync(conversationId, Token); - await store.AttachPrincipalAsync(conversationId, principalKey, "caller", Token); - } + private static async Task Claim(PostgresConversationStore store, string conversationId, string principalKey) + { + _ = await store.CreateAsync(conversationId, Token); + await store.AttachPrincipalAsync(conversationId, principalKey, "caller", Token); + } - private Task Spoke(string conversationId, string ago) => - ExecuteAsync( - $$""" + private Task Spoke(string conversationId, string ago) + { + return ExecuteAsync( + $$""" INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id, created_at, updated_at) VALUES ('{{conversationId}}', 1, 0, 'user', '{}'::jsonb, 'm1', now(), now() + interval '{{ago}}') """); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationPrincipalTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationPrincipalTests.cs index 4d37c7c1..65cd840a 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationPrincipalTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationPrincipalTests.cs @@ -2,104 +2,105 @@ using AgentCore.Infrastructure.Tests.Database.Postgres; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// Who may see a conversation. -public sealed class PostgresConversationPrincipalTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task AttachPrincipalAsync_AKey_WritesOneRow() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Assert - Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task AttachPrincipalAsync_TheSamePairTwice_IsNotAThrowAndStaysOneRow() + /// Who may see a conversation. + public sealed class PostgresConversationPrincipalTests : PostgresDatabaseTest { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Act - var thrown = await Record.ExceptionAsync( - () => store.AttachPrincipalAsync("c1", "person-a", "agent", Token).AsTask()); - - // Assert - Assert.Null(thrown); - Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task AttachPrincipalAsync_TheSamePairTwice_KeepsTheFirstAttachedAt() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - var first = await ScalarAsync("SELECT attached_at FROM agentcore.conversation_principal"); - - // Act - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Assert - Assert.Equal(first, await ScalarAsync("SELECT attached_at FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task AttachPrincipalAsync_TwoKeysOnOneConversation_BothStay() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Assert - Assert.Equal(2, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task DetachPrincipalAsync_OneOfTwoKeys_LeavesTheOther() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Act - await store.DetachPrincipalAsync("c1", "person-a", Token); - - // Assert - Assert.Equal("tenant-a", await ScalarAsync("SELECT principal_key FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task DetachPrincipalAsync_AKeyThatWasNeverAttached_IsNotAThrow() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - var thrown = await Record.ExceptionAsync( - () => store.DetachPrincipalAsync("c1", "nobody", Token).AsTask()); - - // Assert - Assert.Null(thrown); + /// + protected override bool Migrated => true; + + [PostgresFact] + public async Task AttachPrincipalAsync_AKey_WritesOneRow() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Assert + Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task AttachPrincipalAsync_TheSamePairTwice_IsNotAThrowAndStaysOneRow() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Act + Exception? thrown = await Record.ExceptionAsync( + () => store.AttachPrincipalAsync("c1", "person-a", "agent", Token).AsTask()); + + // Assert + Assert.Null(thrown); + Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task AttachPrincipalAsync_TheSamePairTwice_KeepsTheFirstAttachedAt() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + DateTime first = await ScalarAsync("SELECT attached_at FROM agentcore.conversation_principal"); + + // Act + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Assert + Assert.Equal(first, await ScalarAsync("SELECT attached_at FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task AttachPrincipalAsync_TwoKeysOnOneConversation_BothStay() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Assert + Assert.Equal(2, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task DetachPrincipalAsync_OneOfTwoKeys_LeavesTheOther() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "tenant-a", "tenant", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Act + await store.DetachPrincipalAsync("c1", "person-a", Token); + + // Assert + Assert.Equal("tenant-a", await ScalarAsync("SELECT principal_key FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task DetachPrincipalAsync_AKeyThatWasNeverAttached_IsNotAThrow() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + Exception? thrown = await Record.ExceptionAsync( + () => store.DetachPrincipalAsync("c1", "nobody", Token).AsTask()); + + // Assert + Assert.Null(thrown); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs index edb60682..2b6410d0 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreAppendTests.cs @@ -1,4 +1,3 @@ -using System.Text.Json; using System.Text.RegularExpressions; using AgentCore.Application.Conversation; using AgentCore.Application.Ports; @@ -9,208 +8,209 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// -/// The store numbers every row from the conversation's own counter, in PostgreSQL: the seam that lets a -/// host append to a conversation from outside any turn, on any machine, without colliding with the conversation's -/// live session. -/// -#pragma warning disable CA1859 // store is typed as IConversationStore throughout: AppendAsync(conversationId, message, ct) - // is a default interface method, and only resolves through the interface type. -public sealed partial class PostgresConversationStoreAppendTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task AppendAsync_OneMessage_OnAFreshConversation_IsOrdinalZeroAndTurnZero() + /// + /// The store numbers every row from the conversation's own counter, in PostgreSQL: the seam that lets a + /// host append to a conversation from outside any turn, on any machine, without colliding with the conversation's + /// live session. + /// +#pragma warning disable CA1859 // store is typed as IConversationStore throughout: AppendAsync(conversationId, message, ct) + // is a default interface method, and only resolves through the interface type. + public sealed partial class PostgresConversationStoreAppendTests : PostgresDatabaseTest { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); + /// + protected override bool Migrated => true; - // Act - var row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "hello"), Token); + [PostgresFact] + public async Task AppendAsync_OneMessage_OnAFreshConversation_IsOrdinalZeroAndTurnZero() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); - // Assert - Assert.Equal(0, row.Ordinal); - Assert.Equal(0, row.TurnIndex); - Assert.Matches(HexId(), row.MessageId); - } + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "hello"), Token); - [PostgresFact] - public async Task AppendAsync_OneMessage_WithItsOwnId_KeepsIt() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - ChatMessage message = new(ChatRole.User, "hello") { MessageId = "caller-named" }; + // Assert + Assert.Equal(0, row.Ordinal); + Assert.Equal(0, row.TurnIndex); + Assert.Matches(HexId(), row.MessageId); + } - // Act - var row = await store.AppendMessageAsync("c1", message, Token); + [PostgresFact] + public async Task AppendAsync_OneMessage_WithItsOwnId_KeepsIt() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + ChatMessage message = new(ChatRole.User, "hello") { MessageId = "caller-named" }; - // Assert - Assert.Equal("caller-named", row.MessageId); - } + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", message, Token); - [PostgresFact] - public async Task AppendAsync_TwoOutsideAppends_AreNumberedZeroThenOne() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - - // Act - var first = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); - var second = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); - - // Assert - Assert.Equal(0, first.Ordinal); - Assert.Equal(1, second.Ordinal); - var conversation = await store.GetAsync("c1", Token); - Assert.Equal(2, conversation?.NextOrdinal); - } + // Assert + Assert.Equal("caller-named", row.MessageId); + } - [PostgresFact] - public async Task AppendAsync_ABatchWithAnExplicitTurnIndex_NumbersThreeConsecutiveRowsInDraftOrder() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); - - ConversationMessageDraft[] drafts = - [ - new(4, new ChatMessage(ChatRole.User, "a"), "m-a"), - new(4, new ChatMessage(ChatRole.Assistant, "b"), "m-b"), - new(4, new ChatMessage(ChatRole.User, "c"), "m-c"), - ]; - - // Act - var rows = await store.AppendAsync("c1", drafts, cancellationToken: Token); - - // Assert - Assert.Equal([1, 2, 3], rows.Select(row => row.Ordinal)); - Assert.All(rows, row => Assert.Equal(4, row.TurnIndex)); - Assert.Equal(["m-a", "m-b", "m-c"], rows.Select(row => row.MessageId)); - } + [PostgresFact] + public async Task AppendAsync_TwoOutsideAppends_AreNumberedZeroThenOne() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + ConversationMessage first = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); + ConversationMessage second = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); + + // Assert + Assert.Equal(0, first.Ordinal); + Assert.Equal(1, second.Ordinal); + ConversationRecord? conversation = await store.GetAsync("c1", Token); + Assert.Equal(2, conversation?.NextOrdinal); + } - [PostgresFact] - public async Task AppendAsync_OutsideAppend_AfterABatchThatWroteState_IsStampedWithTheStoredNextTurnIndex() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - await store.AppendAsync( - "c1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { NextTurnIndex = 7 }, - Token); - - // Act - var row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); - - // Assert - Assert.Equal(7, row.TurnIndex); - } + [PostgresFact] + public async Task AppendAsync_ABatchWithAnExplicitTurnIndex_NumbersThreeConsecutiveRowsInDraftOrder() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); + + ConversationMessageDraft[] drafts = + [ + new(4, new ChatMessage(ChatRole.User, "a"), "m-a"), + new(4, new ChatMessage(ChatRole.Assistant, "b"), "m-b"), + new(4, new ChatMessage(ChatRole.User, "c"), "m-c"), + ]; + + // Act + IReadOnlyList rows = await store.AppendAsync("c1", drafts, cancellationToken: Token); + + // Assert + Assert.Equal([1, 2, 3], rows.Select(row => row.Ordinal)); + Assert.All(rows, row => Assert.Equal(4, row.TurnIndex)); + Assert.Equal(["m-a", "m-b", "m-c"], rows.Select(row => row.MessageId)); + } - [PostgresFact] - public async Task AppendAsync_TwoWritersFiftyEach_LandsOneHundredRowsWithNoCollision() - { - // Arrange — the shape the owner proved under concurrency in a probe: 2 writers x 50 appends - // -> 100 rows, 0..99, 0 retries. The store's data source pools connections, so two tasks - // running concurrently naturally reach PostgreSQL on separate physical connections. - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); + [PostgresFact] + public async Task AppendAsync_OutsideAppend_AfterABatchThatWroteState_IsStampedWithTheStoredNextTurnIndex() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync( + "c1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { NextTurnIndex = 7 }, + Token); + + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "outside"), Token); + + // Assert + Assert.Equal(7, row.TurnIndex); + } - async Task WriteFiftyAsync(string label) + [PostgresFact] + public async Task AppendAsync_TwoWritersFiftyEach_LandsOneHundredRowsWithNoCollision() { - for (var i = 0; i < 50; i++) + // Arrange — the shape the owner proved under concurrency in a probe: 2 writers x 50 appends + // -> 100 rows, 0..99, 0 retries. The store's data source pools connections, so two tasks + // running concurrently naturally reach PostgreSQL on separate physical connections. + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + + async Task WriteFiftyAsync(string label) { - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, $"{label}-{i}"), Token); + for (int i = 0; i < 50; i++) + { + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, $"{label}-{i}"), Token); + } } - } - // Act - await Task.WhenAll(WriteFiftyAsync("a"), WriteFiftyAsync("b")); + // Act + await Task.WhenAll(WriteFiftyAsync("a"), WriteFiftyAsync("b")); - // Assert - var rows = await store.ReadAllAsync("c1", Token); - Assert.Equal(100, rows.Count); - Assert.Equal(Enumerable.Range(0, 100), rows.Select(row => row.Ordinal).Order()); - } + // Assert + IReadOnlyList rows = await store.ReadAllAsync("c1", Token); + Assert.Equal(100, rows.Count); + Assert.Equal(Enumerable.Range(0, 100), rows.Select(row => row.Ordinal).Order()); + } - [PostgresFact] - public async Task AppendAsync_AConversationThatDoesNotExist_ThrowsNamingIt() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); + [PostgresFact] + public async Task AppendAsync_AConversationThatDoesNotExist_ThrowsNamingIt() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); - // Act - var failure = await Record.ExceptionAsync( - () => store.AppendMessageAsync("missing", new ChatMessage(ChatRole.User, "hello"), Token).AsTask()); + // Act + Exception? failure = await Record.ExceptionAsync( + () => store.AppendMessageAsync("missing", new ChatMessage(ChatRole.User, "hello"), Token).AsTask()); - // Assert - var invalid = Assert.IsType(failure); - Assert.Contains("missing", invalid.Message, StringComparison.Ordinal); - } + // Assert + InvalidOperationException invalid = Assert.IsType(failure); + Assert.Contains("missing", invalid.Message, StringComparison.Ordinal); + } - [PostgresFact] - public async Task RewriteAsync_OneRow_ChangesOnlyThatRowsContent() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "first") { MessageId = "m0" }, Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "second") { MessageId = "m1" }, Token); - - // Act - await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.User, "corrected"), Token); - - // Assert - var rows = await store.ReadAllAsync("c1", Token); - Assert.Equal(["corrected", "second"], rows.Select(row => row.Content.Text)); - } + [PostgresFact] + public async Task RewriteAsync_OneRow_ChangesOnlyThatRowsContent() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "first") { MessageId = "m0" }, Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "second") { MessageId = "m1" }, Token); + + // Act + await store.RewriteAsync("c1", "m0", new ChatMessage(ChatRole.User, "corrected"), Token); + + // Assert + IReadOnlyList rows = await store.ReadAllAsync("c1", Token); + Assert.Equal(["corrected", "second"], rows.Select(row => row.Content.Text)); + } - [PostgresFact] - public async Task AppendAsync_AfterATruncate_NeverReusesTheOrdinalsItTook() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "zero"), Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); - await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); - await store.TruncateAsync("c1", 1, Token); - - // Act - var row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "three"), Token); - - // Assert - Assert.Equal(3, row.Ordinal); - } + [PostgresFact] + public async Task AppendAsync_AfterATruncate_NeverReusesTheOrdinalsItTook() + { + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "zero"), Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "one"), Token); + _ = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "two"), Token); + _ = await store.TruncateAsync("c1", 1, Token); + + // Act + ConversationMessage row = await store.AppendMessageAsync("c1", new ChatMessage(ChatRole.User, "three"), Token); + + // Assert + Assert.Equal(3, row.Ordinal); + } - [PostgresFact] - public async Task AppendAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() - { - // Arrange - IConversationStore store = new PostgresConversationStore(DataSource); - await store.CreateAsync("c1", Token); - ChatMessage message = new(ChatRole.User, "hello") + [PostgresFact] + public async Task AppendAsync_ARowWithAdditionalProperties_KeepsThemAcrossTheRoundTrip() { - AdditionalProperties = new() { ["speaker"] = "human" }, - }; + // Arrange + IConversationStore store = new PostgresConversationStore(DataSource); + _ = await store.CreateAsync("c1", Token); + ChatMessage message = new(ChatRole.User, "hello") + { + AdditionalProperties = new() { ["speaker"] = "human" }, + }; - // Act - await store.AppendMessageAsync("c1", message, Token); + // Act + _ = await store.AppendMessageAsync("c1", message, Token); - // Assert - var rows = await store.ReadAllAsync("c1", Token); - Assert.Equal("human", Assert.Single(rows).Content.AdditionalProperties?["speaker"]?.ToString()); - } + // Assert + IReadOnlyList rows = await store.ReadAllAsync("c1", Token); + Assert.Equal("human", Assert.Single(rows).Content.AdditionalProperties?["speaker"]?.ToString()); + } - [GeneratedRegex("^[0-9a-f]{32}$")] - private static partial Regex HexId(); -} + [GeneratedRegex("^[0-9a-f]{32}$")] + private static partial Regex HexId(); + } #pragma warning restore CA1859 +} diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs index 45f8d673..3efe9da7 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSummaryRowTests.cs @@ -3,40 +3,55 @@ using AgentCore.Infrastructure.Tests.Database.Postgres; using AgentCore.TestSupport; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// The summary row facts of , against PostgreSQL. -public sealed class PostgresConversationStoreSummaryRowTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - protected override bool Migrated => true; - - private IConversationStore Store => new PostgresConversationStore(DataSource); - - [PostgresFact] - public Task ReadForSession_HandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers() - => ConversationStoreSummaryRowFacts.SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(Store, Token); - - [PostgresFact] - public Task ReadForSession_WithNoSummary_HandsBackEveryRow() - => ConversationStoreSummaryRowFacts.SessionReadWithNoSummaryHandsBackEveryRow(Store, Token); - - [PostgresFact] - public Task ConsumerReads_LeaveEverySummaryOut() - => ConversationStoreSummaryRowFacts.ConsumerReadsLeaveEverySummaryOut(Store, Token); - - [PostgresFact] - public Task Truncate_UnderWhatTheSummaryCovers_TakesTheSummary() - => ConversationStoreSummaryRowFacts.TruncateUnderWhatTheSummaryCoversTakesTheSummary(Store, Token); - - [PostgresFact] - public Task Truncate_AboveWhatTheSummaryCovers_KeepsTheSummaryWhateverItsOrdinal() - => ConversationStoreSummaryRowFacts.TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(Store, Token); - - [PostgresFact] - public Task Truncate_AboveTheSummary_LeavesEverythingUnderItAlone() - => ConversationStoreSummaryRowFacts.TruncateAboveTheSummaryLeavesEverythingUnderItAlone(Store, Token); - - [PostgresFact] - public Task OrdinalOf_FindsASpokenRow_AndNotASummary() - => ConversationStoreSummaryRowFacts.OrdinalOfFindsASpokenRowAndNotASummary(Store, Token); + /// The summary row facts of , against PostgreSQL. + public sealed class PostgresConversationStoreSummaryRowTests : PostgresDatabaseTest + { + protected override bool Migrated => true; + + private IConversationStore Store => new PostgresConversationStore(DataSource); + + [PostgresFact] + public Task ReadForSession_HandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers() + { + return ConversationStoreSummaryRowFacts.SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(Store, Token); + } + + [PostgresFact] + public Task ReadForSession_WithNoSummary_HandsBackEveryRow() + { + return ConversationStoreSummaryRowFacts.SessionReadWithNoSummaryHandsBackEveryRow(Store, Token); + } + + [PostgresFact] + public Task ConsumerReads_LeaveEverySummaryOut() + { + return ConversationStoreSummaryRowFacts.ConsumerReadsLeaveEverySummaryOut(Store, Token); + } + + [PostgresFact] + public Task Truncate_UnderWhatTheSummaryCovers_TakesTheSummary() + { + return ConversationStoreSummaryRowFacts.TruncateUnderWhatTheSummaryCoversTakesTheSummary(Store, Token); + } + + [PostgresFact] + public Task Truncate_AboveWhatTheSummaryCovers_KeepsTheSummaryWhateverItsOrdinal() + { + return ConversationStoreSummaryRowFacts.TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(Store, Token); + } + + [PostgresFact] + public Task Truncate_AboveTheSummary_LeavesEverythingUnderItAlone() + { + return ConversationStoreSummaryRowFacts.TruncateAboveTheSummaryLeavesEverythingUnderItAlone(Store, Token); + } + + [PostgresFact] + public Task OrdinalOf_FindsASpokenRow_AndNotASummary() + { + return ConversationStoreSummaryRowFacts.OrdinalOfFindsASpokenRowAndNotASummary(Store, Token); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSweepTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSweepTests.cs index f7b8a61c..279ecaa7 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSweepTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreSweepTests.cs @@ -4,130 +4,133 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// -/// Retention, which deletes the conversation and lets the cascade take the words. -/// -public sealed class PostgresConversationStoreSweepTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - private static readonly TimeSpan Window = TimeSpan.FromDays(30); + /// + /// Retention, which deletes the conversation and lets the cascade take the words. + /// + public sealed class PostgresConversationStoreSweepTests : PostgresDatabaseTest + { + private static readonly TimeSpan Window = TimeSpan.FromDays(30); - /// - protected override bool Migrated => true; + /// + protected override bool Migrated => true; - private static ConversationMessageDraft Word() => - new(0, new ChatMessage(ChatRole.User, "hello"), "m0"); + private static ConversationMessageDraft Word() + { + return new(0, new ChatMessage(ChatRole.User, "hello"), "m0"); + } - [PostgresFact] - public async Task SweepAsync_AConversationWhoseLastMessageIsOld_TakesTheConversationAndItsWords() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("old", Token); - await store.AppendAsync("old", [Word()], cancellationToken: Token); - await ExecuteAsync("UPDATE agentcore.conversation_message SET updated_at = now() - interval '90 days'"); - - // Act - var swept = await store.SweepAsync(Window, cancellationToken: Token); - - // Assert - Assert.Equal(1, swept); - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); - } + [PostgresFact] + public async Task SweepAsync_AConversationWhoseLastMessageIsOld_TakesTheConversationAndItsWords() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("old", Token); + _ = await store.AppendAsync("old", [Word()], cancellationToken: Token); + await ExecuteAsync("UPDATE agentcore.conversation_message SET updated_at = now() - interval '90 days'"); + + // Act + int swept = await store.SweepAsync(Window, cancellationToken: Token); + + // Assert + Assert.Equal(1, swept); + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); + } - [PostgresFact] - public async Task SweepAsync_AConversationWithNoWordsAtAll_TakesItOnCreatedAt() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("empty", Token); - await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); + [PostgresFact] + public async Task SweepAsync_AConversationWithNoWordsAtAll_TakesItOnCreatedAt() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("empty", Token); + await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); - // Act - var swept = await store.SweepAsync(Window, cancellationToken: Token); + // Act + int swept = await store.SweepAsync(Window, cancellationToken: Token); - // Assert - Assert.Equal(1, swept); - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - } + // Assert + Assert.Equal(1, swept); + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + } - /// - /// created_at is old and the message is fresh, so the message time must win. This is the whole - /// point of coalescing rather than reading either column alone. - /// - [PostgresFact] - public async Task SweepAsync_AConversationSpokenOnInsideTheWindow_LeavesIt() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("fresh", Token); - await store.AppendAsync("fresh", [Word()], cancellationToken: Token); - await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); - - // Act - var swept = await store.SweepAsync(Window, cancellationToken: Token); - - // Assert - Assert.Equal(0, swept); - Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - } + /// + /// created_at is old and the message is fresh, so the message time must win. This is the whole + /// point of coalescing rather than reading either column alone. + /// + [PostgresFact] + public async Task SweepAsync_AConversationSpokenOnInsideTheWindow_LeavesIt() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("fresh", Token); + _ = await store.AppendAsync("fresh", [Word()], cancellationToken: Token); + await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); + + // Act + int swept = await store.SweepAsync(Window, cancellationToken: Token); + + // Assert + Assert.Equal(0, swept); + Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + } - [PostgresFact] - public async Task SweepAsync_ASweptConversation_LeavesItsAuditEvents() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("old", Token); - await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); - await ExecuteAsync( - """ + [PostgresFact] + public async Task SweepAsync_ASweptConversation_LeavesItsAuditEvents() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("old", Token); + await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); + await ExecuteAsync( + """ INSERT INTO agentcore.audit_event (conversation_id, event_id, sequence, kind, occurred_at) VALUES ('old', gen_random_uuid(), 0, 'conversation.started', now()) """); - // Act - await store.SweepAsync(Window, cancellationToken: Token); + // Act + _ = await store.SweepAsync(Window, cancellationToken: Token); - // Assert - Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } + // Assert + Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); + } - [PostgresFact] - public async Task SweepAsync_MoreExpiredConversationsThanOneBatch_LoopsUntilNoneAreLeft() - { - // Arrange - PostgresConversationStore store = new(DataSource); - for (var i = 0; i < 5; i++) + [PostgresFact] + public async Task SweepAsync_MoreExpiredConversationsThanOneBatch_LoopsUntilNoneAreLeft() { - await store.CreateAsync($"c{i}", Token); - } + // Arrange + PostgresConversationStore store = new(DataSource); + for (int i = 0; i < 5; i++) + { + _ = await store.CreateAsync($"c{i}", Token); + } - await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); + await ExecuteAsync("UPDATE agentcore.conversation SET created_at = now() - interval '90 days'"); - // Act - var swept = await store.SweepAsync(Window, batchSize: 2, cancellationToken: Token); + // Act + int swept = await store.SweepAsync(Window, batchSize: 2, cancellationToken: Token); - // Assert - Assert.Equal(5, swept); - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - } + // Assert + Assert.Equal(5, swept); + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + } - [PostgresFact] - public async Task EraseAsync_AConversationsWords_LeavesTheConversationItselfListed() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.AppendAsync("c1", [Word()], cancellationToken: Token); - - // Act - var erased = await store.EraseAsync("c1", Token); - - // Assert — erase empties a thread that stays; delete takes the thread and the words with it. - Assert.Equal(1, erased); - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); - Assert.NotNull(await store.GetAsync("c1", Token)); + [PostgresFact] + public async Task EraseAsync_AConversationsWords_LeavesTheConversationItselfListed() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + _ = await store.AppendAsync("c1", [Word()], cancellationToken: Token); + + // Act + int erased = await store.EraseAsync("c1", Token); + + // Assert — erase empties a thread that stays; delete takes the thread and the words with it. + Assert.Equal(1, erased); + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); + Assert.NotNull(await store.GetAsync("c1", Token)); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTests.cs index 3e2fda2f..d5f361d6 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTests.cs @@ -1,232 +1,232 @@ using System.Text.Json; using AgentCore.Application.Conversation; -using AgentCore.Application.Ports; using AgentCore.Infrastructure.Conversation.Postgres; using AgentCore.Infrastructure.Tests.Database.Postgres; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// Store 0, in PostgreSQL. -public sealed class PostgresConversationStoreTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - [PostgresFact] - public async Task CreateAsync_ANewConversation_WritesOneRow() - { - // Arrange - PostgresConversationStore store = new(DataSource); - - // Act - var conversation = await store.CreateAsync("c1", Token); - - // Assert - Assert.Equal("c1", conversation.ConversationId); - Assert.Null(conversation.Title); - Assert.Equal(ConversationStatus.Regular, conversation.Status); - Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - } - - [PostgresFact] - public async Task CreateAsync_TheSameIdTwice_StaysOneRowAndKeepsTheFirst() - { - // Arrange - PostgresConversationStore store = new(DataSource); - - // Act - var first = await store.CreateAsync("c1", Token); - await store.RenameAsync("c1", "kept", Token); - var second = await store.CreateAsync("c1", Token); - - // Assert - Assert.Equal(first.CreatedAt, second.CreatedAt); - Assert.Equal("kept", second.Title); - Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - } - - [PostgresFact] - public async Task GetAsync_AConversationThatWasNeverMade_IsNull() - { - // Arrange - PostgresConversationStore store = new(DataSource); - - // Act - var found = await store.GetAsync("missing", Token); - - // Assert - Assert.Null(found); - } - - [PostgresFact] - public async Task GetAsync_AConversationWithNoMessages_ReportsNoLastActivity() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - var found = await store.GetAsync("c1", Token); - - // Assert - Assert.Null(found!.LastMessageAt); - } - - [PostgresFact] - public async Task GetAsync_AConversationWithMessages_ReportsTheNewestMessageTime() + /// Store 0, in PostgreSQL. + public sealed class PostgresConversationStoreTests : PostgresDatabaseTest { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await ExecuteAsync( - """ + /// + protected override bool Migrated => true; + + [PostgresFact] + public async Task CreateAsync_ANewConversation_WritesOneRow() + { + // Arrange + PostgresConversationStore store = new(DataSource); + + // Act + ConversationRecord conversation = await store.CreateAsync("c1", Token); + + // Assert + Assert.Equal("c1", conversation.ConversationId); + Assert.Null(conversation.Title); + Assert.Equal(ConversationStatus.Regular, conversation.Status); + Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + } + + [PostgresFact] + public async Task CreateAsync_TheSameIdTwice_StaysOneRowAndKeepsTheFirst() + { + // Arrange + PostgresConversationStore store = new(DataSource); + + // Act + ConversationRecord first = await store.CreateAsync("c1", Token); + await store.RenameAsync("c1", "kept", Token); + ConversationRecord second = await store.CreateAsync("c1", Token); + + // Assert + Assert.Equal(first.CreatedAt, second.CreatedAt); + Assert.Equal("kept", second.Title); + Assert.Equal(1, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + } + + [PostgresFact] + public async Task GetAsync_AConversationThatWasNeverMade_IsNull() + { + // Arrange + PostgresConversationStore store = new(DataSource); + + // Act + ConversationRecord? found = await store.GetAsync("missing", Token); + + // Assert + Assert.Null(found); + } + + [PostgresFact] + public async Task GetAsync_AConversationWithNoMessages_ReportsNoLastActivity() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + ConversationRecord? found = await store.GetAsync("c1", Token); + + // Assert + Assert.Null(found!.LastMessageAt); + } + + [PostgresFact] + public async Task GetAsync_AConversationWithMessages_ReportsTheNewestMessageTime() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await ExecuteAsync( + """ INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id, created_at, updated_at) VALUES ('c1', 1, 0, 'user', '{}'::jsonb, 'm1', now(), now() + interval '1 hour') """); - // Act - var found = await store.GetAsync("c1", Token); - - // Assert - Assert.True(found!.LastMessageAt > found.CreatedAt); - } - - [PostgresFact] - public async Task RenameAsync_AConversation_ChangesOnlyItsTitle() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - await store.RenameAsync("c1", "A squeaky belt", Token); - - // Assert - var found = await store.GetAsync("c1", Token); - Assert.Equal("A squeaky belt", found!.Title); - Assert.Equal(ConversationStatus.Regular, found.Status); - } - - [PostgresFact] - public async Task SetStatusAsync_Archived_IsReadBack() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - await store.SetStatusAsync("c1", ConversationStatus.Archived, Token); - - // Assert - Assert.Equal(ConversationStatus.Archived, (await store.GetAsync("c1", Token))!.Status); - } - - [PostgresFact] - public async Task SetCustomAsync_SomeFields_AreReadBackWhole() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - using var document = JsonDocument.Parse("""{"crmId":"A-1","tags":["belt"]}"""); - - // Act - await store.SetCustomAsync("c1", document.RootElement, Token); - - // Assert - var found = await store.GetAsync("c1", Token); - Assert.Equal("A-1", found!.Custom!.Value.GetProperty("crmId").GetString()); - } - - [PostgresFact] - public async Task SetCustomAsync_Null_ClearsTheFields() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - using var document = JsonDocument.Parse("""{"crmId":"A-1"}"""); - await store.SetCustomAsync("c1", document.RootElement, Token); - - // Act - await store.SetCustomAsync("c1", null, Token); - - // Assert - Assert.Null((await store.GetAsync("c1", Token))!.Custom); - } - - [PostgresFact] - public async Task SetExternalIdAsync_AConsumersOwnId_IsReadBack() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - - // Act - await store.SetExternalIdAsync("c1", "crm-77", Token); - - // Assert - Assert.Equal("crm-77", (await store.GetAsync("c1", Token))!.ExternalId); - } - - [PostgresFact] - public async Task SetExternalIdAsync_Null_ClearsTheId() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.SetExternalIdAsync("c1", "crm-77", Token); - - // Act - await store.SetExternalIdAsync("c1", null, Token); - - // Assert - Assert.Null((await store.GetAsync("c1", Token))!.ExternalId); - } - - [PostgresFact] - public async Task DeleteAsync_AConversation_LeavesNoRowAndNoClaim() - { - // Arrange - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); - - // Act - await store.DeleteAsync("c1", Token); - - // Assert - Assert.Equal(0, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); - Assert.Equal(0, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); - } - - [PostgresFact] - public async Task DeleteAsync_AConversation_TakesItsSameIdContinuationWithIt() - { - // Arrange — one id plays three roles now, so the row delete takes the key with it. Per-turn - // response ids are gone with their own rows only through DeleteContinuationAsync; nothing - // here enumerates them. - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("c1", Token); - using var document = System.Text.Json.JsonDocument.Parse("""{ "conversationId": "c1" }"""); - await store.SaveContinuationAsync("c1", document.RootElement, Token); - - // Act - await store.DeleteAsync("c1", Token); - - // Assert - Assert.Null(await store.GetContinuationAsync("c1", Token)); - } - - [PostgresFact] - public async Task DeleteAsync_AConversationThatWasNeverMade_IsNotAThrow() - { - // Arrange - PostgresConversationStore store = new(DataSource); - - // Act - var thrown = await Record.ExceptionAsync(() => store.DeleteAsync("missing", Token).AsTask()); - - // Assert - Assert.Null(thrown); + // Act + ConversationRecord? found = await store.GetAsync("c1", Token); + + // Assert + Assert.True(found!.LastMessageAt > found.CreatedAt); + } + + [PostgresFact] + public async Task RenameAsync_AConversation_ChangesOnlyItsTitle() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + await store.RenameAsync("c1", "A squeaky belt", Token); + + // Assert + ConversationRecord? found = await store.GetAsync("c1", Token); + Assert.Equal("A squeaky belt", found!.Title); + Assert.Equal(ConversationStatus.Regular, found.Status); + } + + [PostgresFact] + public async Task SetStatusAsync_Archived_IsReadBack() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + await store.SetStatusAsync("c1", ConversationStatus.Archived, Token); + + // Assert + Assert.Equal(ConversationStatus.Archived, (await store.GetAsync("c1", Token))!.Status); + } + + [PostgresFact] + public async Task SetCustomAsync_SomeFields_AreReadBackWhole() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + using JsonDocument document = JsonDocument.Parse("""{"crmId":"A-1","tags":["belt"]}"""); + + // Act + await store.SetCustomAsync("c1", document.RootElement, Token); + + // Assert + ConversationRecord? found = await store.GetAsync("c1", Token); + Assert.Equal("A-1", found!.Custom!.Value.GetProperty("crmId").GetString()); + } + + [PostgresFact] + public async Task SetCustomAsync_Null_ClearsTheFields() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + using JsonDocument document = JsonDocument.Parse("""{"crmId":"A-1"}"""); + await store.SetCustomAsync("c1", document.RootElement, Token); + + // Act + await store.SetCustomAsync("c1", null, Token); + + // Assert + Assert.Null((await store.GetAsync("c1", Token))!.Custom); + } + + [PostgresFact] + public async Task SetExternalIdAsync_AConsumersOwnId_IsReadBack() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + + // Act + await store.SetExternalIdAsync("c1", "crm-77", Token); + + // Assert + Assert.Equal("crm-77", (await store.GetAsync("c1", Token))!.ExternalId); + } + + [PostgresFact] + public async Task SetExternalIdAsync_Null_ClearsTheId() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await store.SetExternalIdAsync("c1", "crm-77", Token); + + // Act + await store.SetExternalIdAsync("c1", null, Token); + + // Assert + Assert.Null((await store.GetAsync("c1", Token))!.ExternalId); + } + + [PostgresFact] + public async Task DeleteAsync_AConversation_LeavesNoRowAndNoClaim() + { + // Arrange + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + await store.AttachPrincipalAsync("c1", "person-a", "caller", Token); + + // Act + await store.DeleteAsync("c1", Token); + + // Assert + Assert.Equal(0, await ScalarAsync("SELECT count(*) FROM agentcore.conversation")); + Assert.Equal(0, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); + } + + [PostgresFact] + public async Task DeleteAsync_AConversation_TakesItsSameIdContinuationWithIt() + { + // Arrange — one id plays three roles now, so the row delete takes the key with it. Per-turn + // response ids are gone with their own rows only through DeleteContinuationAsync; nothing + // here enumerates them. + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("c1", Token); + using JsonDocument document = JsonDocument.Parse("""{ "conversationId": "c1" }"""); + await store.SaveContinuationAsync("c1", document.RootElement, Token); + + // Act + await store.DeleteAsync("c1", Token); + + // Assert + Assert.Null(await store.GetContinuationAsync("c1", Token)); + } + + [PostgresFact] + public async Task DeleteAsync_AConversationThatWasNeverMade_IsNotAThrow() + { + // Arrange + PostgresConversationStore store = new(DataSource); + + // Act + Exception? thrown = await Record.ExceptionAsync(() => store.DeleteAsync("missing", Token).AsTask()); + + // Assert + Assert.Null(thrown); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs index 61cad129..56fe622f 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreTruncateTests.cs @@ -7,115 +7,116 @@ using Npgsql; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// -/// What an edit does to store 1 in PostgreSQL: which rows go, which stay, and what the names the -/// caller knows its messages by are good for. -/// -public sealed class PostgresConversationStoreTruncateTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - private async Task OpenAsync() - { - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("C1", Token); - return store; - } - - [PostgresFact] - public async Task Truncate_TakesTheNamedOrdinalAndEverythingAfterIt() - { - var store = await OpenAsync(); - await store.AppendAsync( - "C1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a1"), "m1"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q2"), "m2"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a2"), "m3"), - ], - state: null, - Token); - - var went = await store.TruncateAsync("C1", 2, Token); - - Assert.Equal(new ConversationCut(2, new WithdrawnTurns(1, 1)), went); - var rows = await store.ReadAllAsync("C1", Token); - Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); - } - - [PostgresFact] - public async Task Truncate_LeavesTheNextAppendFreeToClimbPastTheGap() - { - // The ordinals a truncation takes are never issued again, so an append after one leaves a - // hole. Nothing may object to that: store 3 keeps audit rows against the turns that stood in - // the gap, and reissuing a number would put two turns in one place in the chain. - var store = await OpenAsync(); - await store.AppendAsync( - "C1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a1"), "m1"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q2"), "m2"), - ], - state: null, - Token); - await store.TruncateAsync("C1", 2, Token); - - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2 again"), "m3")], - state: null, - Token); - - var rows = await store.ReadAllAsync("C1", Token); - Assert.Equal([0, 1, 3], rows.Select(row => row.Ordinal)); - Assert.Equal([0, 0, 2], rows.Select(row => row.TurnIndex)); - } - - [PostgresFact] - public async Task AMessageName_RoundTripsAndIsUniqueWithinTheConversation() + /// + /// What an edit does to store 1 in PostgreSQL: which rows go, which stay, and what the names the + /// caller knows its messages by are good for. + /// + public sealed class PostgresConversationStoreTruncateTests : PostgresDatabaseTest { - var store = await OpenAsync(); - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0")], - state: null, - Token); - - Assert.Equal("m0", (await store.ReadAllAsync("C1", Token))[0].MessageId); - - var clash = await Record.ExceptionAsync( - () => store.AppendAsync( + /// + protected override bool Migrated => true; + + private async Task OpenAsync() + { + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("C1", Token); + return store; + } + + [PostgresFact] + public async Task Truncate_TakesTheNamedOrdinalAndEverythingAfterIt() + { + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync( "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q2"), "m0")], + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a1"), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q2"), "m2"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a2"), "m3"), + ], state: null, - Token).AsTask()); - - Assert.Equal("23505", Assert.IsType(clash).SqlState); - } - - [PostgresFact] - public async Task Truncate_LeavesTheStateAndTheConversationRowAlone() - { - // An edit withdraws words. It does not withdraw how far the conversation has got — the marks in the - // state are what stop the next turn standing where a deleted row stood. - var store = await OpenAsync(); - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0")], - new ConversationSessionState { Stage = "collecting", NextTurnIndex = 1 }, - Token); - - await store.TruncateAsync("C1", 0, Token); + Token); + + ConversationCut went = await store.TruncateAsync("C1", 2, Token); + + Assert.Equal(new ConversationCut(2, new WithdrawnTurns(1, 1)), went); + IReadOnlyList rows = await store.ReadAllAsync("C1", Token); + Assert.Equal([0, 1], rows.Select(row => row.Ordinal)); + } + + [PostgresFact] + public async Task Truncate_LeavesTheNextAppendFreeToClimbPastTheGap() + { + // The ordinals a truncation takes are never issued again, so an append after one leaves a + // hole. Nothing may object to that: store 3 keeps audit rows against the turns that stood in + // the gap, and reissuing a number would put two turns in one place in the chain. + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync( + "C1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a1"), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q2"), "m2"), + ], + state: null, + Token); + _ = await store.TruncateAsync("C1", 2, Token); - var record = await store.GetAsync("C1", Token); - Assert.Equal("collecting", record?.State?.Stage); - Assert.Equal(1, record?.NextOrdinal); - Assert.Equal(1, record?.State?.NextTurnIndex); - Assert.Empty(await store.ReadAllAsync("C1", Token)); + _ = await store.AppendAsync( + "C1", + [new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2 again"), "m3")], + state: null, + Token); + + IReadOnlyList rows = await store.ReadAllAsync("C1", Token); + Assert.Equal([0, 1, 3], rows.Select(row => row.Ordinal)); + Assert.Equal([0, 0, 2], rows.Select(row => row.TurnIndex)); + } + + [PostgresFact] + public async Task AMessageName_RoundTripsAndIsUniqueWithinTheConversation() + { + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync( + "C1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0")], + state: null, + Token); + + Assert.Equal("m0", (await store.ReadAllAsync("C1", Token))[0].MessageId); + + Exception? clash = await Record.ExceptionAsync( + () => store.AppendAsync( + "C1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q2"), "m0")], + state: null, + Token).AsTask()); + + Assert.Equal("23505", Assert.IsType(clash).SqlState); + } + + [PostgresFact] + public async Task Truncate_LeavesTheStateAndTheConversationRowAlone() + { + // An edit withdraws words. It does not withdraw how far the conversation has got — the marks in the + // state are what stop the next turn standing where a deleted row stood. + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync( + "C1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q1"), "m0")], + new ConversationSessionState { Stage = "collecting", NextTurnIndex = 1 }, + Token); + + _ = await store.TruncateAsync("C1", 0, Token); + + ConversationRecord? record = await store.GetAsync("C1", Token); + Assert.Equal("collecting", record?.State?.Stage); + Assert.Equal(1, record?.NextOrdinal); + Assert.Equal(1, record?.State?.NextTurnIndex); + Assert.Empty(await store.ReadAllAsync("C1", Token)); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs index ed4f7fce..247c7c0d 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWindowTests.cs @@ -4,75 +4,76 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// Reading store 1 in PostgreSQL a window of turns at a time: newest turns first, every turn whole. -public sealed class PostgresConversationStoreWindowTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - /// - protected override bool Migrated => true; - - /// Four turns. Turn 2 answers through a tool, so it holds four rows rather than two. - private async Task FourTurnsAsync() + /// Reading store 1 in PostgreSQL a window of turns at a time: newest turns first, every turn whole. + public sealed class PostgresConversationStoreWindowTests : PostgresDatabaseTest { - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("C1", Token); - await store.AppendAsync( - "C1", - [ - new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q0"), "m0"), - new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a0"), "m1"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q1"), "m2"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a1"), "m3"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2"), "m4"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call", "lookup")]), "m5"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call", "found")]), "m6"), - new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, "a2"), "m7"), - new ConversationMessageDraft(3, new ChatMessage(ChatRole.User, "q3"), "m8"), - new ConversationMessageDraft(3, new ChatMessage(ChatRole.Assistant, "a3"), "m9"), - ], - state: null, - Token); - return store; - } + /// + protected override bool Migrated => true; - [PostgresFact] - public async Task ReadWindow_NoStart_ReadsTheNewestTurnsWholeOldestRowFirst() - { - var store = await FourTurnsAsync(); + /// Four turns. Turn 2 answers through a tool, so it holds four rows rather than two. + private async Task FourTurnsAsync() + { + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("C1", Token); + _ = await store.AppendAsync( + "C1", + [ + new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "q0"), "m0"), + new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "a0"), "m1"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "q1"), "m2"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.Assistant, "a1"), "m3"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.User, "q2"), "m4"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call", "lookup")]), "m5"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call", "found")]), "m6"), + new ConversationMessageDraft(2, new ChatMessage(ChatRole.Assistant, "a2"), "m7"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.User, "q3"), "m8"), + new ConversationMessageDraft(3, new ChatMessage(ChatRole.Assistant, "a3"), "m9"), + ], + state: null, + Token); + return store; + } - var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(null, 2), Token); + [PostgresFact] + public async Task ReadWindow_NoStart_ReadsTheNewestTurnsWholeOldestRowFirst() + { + PostgresConversationStore store = await FourTurnsAsync(); - Assert.Equal(["m4", "m5", "m6", "m7", "m8", "m9"], rows.Select(row => row.MessageId)); - } + IReadOnlyList rows = await store.ReadWindowAsync("C1", new TranscriptWindow(null, 2), Token); - [PostgresFact] - public async Task ReadWindow_BeforeATurn_ReadsTheTurnsJustBelowIt() - { - var store = await FourTurnsAsync(); + Assert.Equal(["m4", "m5", "m6", "m7", "m8", "m9"], rows.Select(row => row.MessageId)); + } - var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(2, 2), Token); + [PostgresFact] + public async Task ReadWindow_BeforeATurn_ReadsTheTurnsJustBelowIt() + { + PostgresConversationStore store = await FourTurnsAsync(); - Assert.Equal(["m0", "m1", "m2", "m3"], rows.Select(row => row.MessageId)); - } + IReadOnlyList rows = await store.ReadWindowAsync("C1", new TranscriptWindow(2, 2), Token); - [PostgresFact] - public async Task ReadWindow_PastTheStart_ReadsWhatIsLeft() - { - var store = await FourTurnsAsync(); + Assert.Equal(["m0", "m1", "m2", "m3"], rows.Select(row => row.MessageId)); + } - var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(1, 5), Token); + [PostgresFact] + public async Task ReadWindow_PastTheStart_ReadsWhatIsLeft() + { + PostgresConversationStore store = await FourTurnsAsync(); - Assert.Equal(["m0", "m1"], rows.Select(row => row.MessageId)); - } + IReadOnlyList rows = await store.ReadWindowAsync("C1", new TranscriptWindow(1, 5), Token); - [PostgresFact] - public async Task ReadWindow_BeforeTheFirstTurn_ReadsNothing() - { - var store = await FourTurnsAsync(); + Assert.Equal(["m0", "m1"], rows.Select(row => row.MessageId)); + } + + [PostgresFact] + public async Task ReadWindow_BeforeTheFirstTurn_ReadsNothing() + { + PostgresConversationStore store = await FourTurnsAsync(); - var rows = await store.ReadWindowAsync("C1", new TranscriptWindow(0, 5), Token); + IReadOnlyList rows = await store.ReadWindowAsync("C1", new TranscriptWindow(0, 5), Token); - Assert.Empty(rows); + Assert.Empty(rows); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs index 54e2d556..3b3e0861 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs @@ -1,7 +1,6 @@ using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Conversation; -using AgentCore.Application.Runtime; using AgentCore.Application.Transcript; using AgentCore.Domain.Audit; using AgentCore.Infrastructure.Audit.Postgres; @@ -11,463 +10,461 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Infrastructure.Tests.Conversation.Postgres; - -/// -/// The words half of the store, in PostgreSQL. -/// -public sealed class PostgresConversationStoreWordsTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Conversation.Postgres { - private static readonly TimeSpan NinetyDays = TimeSpan.FromDays(90); - - /// Opens the store with the conversation rows these tests write words against already made. - private async Task OpenAsync() + /// + /// The words half of the store, in PostgreSQL. + /// + public sealed class PostgresConversationStoreWordsTests : PostgresDatabaseTest { - PostgresConversationStore store = new(DataSource); - await store.CreateAsync("C1", Token); - await store.CreateAsync("C2", Token); - return store; - } - /// - protected override bool Migrated => true; + /// Opens the store with the conversation rows these tests write words against already made. + private async Task OpenAsync() + { + PostgresConversationStore store = new(DataSource); + _ = await store.CreateAsync("C1", Token); + _ = await store.CreateAsync("C2", Token); + return store; + } - // --------------------------------------------------------------------------------------------- - // Append. - // --------------------------------------------------------------------------------------------- - [PostgresFact] - public async Task AppendAsync_ATurn_WritesOneRowForEachMessage() - { - // Arrange - var store = await OpenAsync(); + /// + protected override bool Migrated => true; - // Act - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + // --------------------------------------------------------------------------------------------- + // Append. + // --------------------------------------------------------------------------------------------- + [PostgresFact] + public async Task AppendAsync_ATurn_WritesOneRowForEachMessage() + { + // Arrange + PostgresConversationStore store = await OpenAsync(); - // Assert - Assert.Equal(2L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); - } + // Act + _ = await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - [PostgresFact] - public async Task AppendAsync_ATurn_LiftsTheRoleOutOfTheContent() - { - // Arrange - var store = await OpenAsync(); + // Assert + Assert.Equal(2L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); + } - // Act - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + [PostgresFact] + public async Task AppendAsync_ATurn_LiftsTheRoleOutOfTheContent() + { + // Arrange + PostgresConversationStore store = await OpenAsync(); - // Assert — retention and redaction read the role, and never parse the content to find it. - Assert.Equal( - "user,assistant", - await ScalarAsync("SELECT string_agg(role, ',' ORDER BY ordinal) FROM agentcore.conversation_message")); - } + // Act + _ = await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - [PostgresFact] - public async Task AppendAsync_AToolCallingTurn_RoundTripsEveryContentPart() - { - // Arrange — the framework ships the polymorphic converters, so a tool call and its result - // survive with no code of ours. - var store = await OpenAsync(); - ChatMessage announced = new( - ChatRole.Assistant, - [new TextContent("Let me check that."), new FunctionCallContent("id1", "lookup", null)]); - ChatMessage result = new(ChatRole.Tool, [new FunctionResultContent("id1", "Friday")]); - - // Act - await store.AppendAsync( - "C1", - [ - new ConversationMessageDraft(0, announced, "m0"), - new ConversationMessageDraft(0, result, "m1"), - ], - cancellationToken: Token); - - // Assert - var rows = await store.ReadAllAsync("C1", Token); - Assert.Equal( - ["Let me check that.", "lookup", "id1"], - [ - rows[0].Content.Contents.OfType().Single().Text, - rows[0].Content.Contents.OfType().Single().Name, - rows[1].Content.Contents.OfType().Single().CallId, - ]); - } + // Assert — retention and redaction read the role, and never parse the content to find it. + Assert.Equal( + "user,assistant", + await ScalarAsync("SELECT string_agg(role, ',' ORDER BY ordinal) FROM agentcore.conversation_message")); + } - [PostgresFact] - public async Task AppendAsync_NoMessages_TouchesNothing() - { - // Arrange - var store = await OpenAsync(); + [PostgresFact] + public async Task AppendAsync_AToolCallingTurn_RoundTripsEveryContentPart() + { + // Arrange — the framework ships the polymorphic converters, so a tool call and its result + // survive with no code of ours. + PostgresConversationStore store = await OpenAsync(); + ChatMessage announced = new( + ChatRole.Assistant, + [new TextContent("Let me check that."), new FunctionCallContent("id1", "lookup", null)]); + ChatMessage result = new(ChatRole.Tool, [new FunctionResultContent("id1", "Friday")]); + + // Act + _ = await store.AppendAsync( + "C1", + [ + new ConversationMessageDraft(0, announced, "m0"), + new ConversationMessageDraft(0, result, "m1"), + ], + cancellationToken: Token); - // Act - await store.AppendAsync("C1", [], cancellationToken: Token); + // Assert + IReadOnlyList rows = await store.ReadAllAsync("C1", Token); + Assert.Equal( + ["Let me check that.", "lookup", "id1"], + [ + rows[0].Content.Contents.OfType().Single().Text, + rows[0].Content.Contents.OfType().Single().Name, + rows[1].Content.Contents.OfType().Single().CallId, + ]); + } - // Assert - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); - } + [PostgresFact] + public async Task AppendAsync_NoMessages_TouchesNothing() + { + // Arrange + PostgresConversationStore store = await OpenAsync(); - [PostgresFact] - public async Task ItWritesTheStateBesideTheWords() - { - var store = await OpenAsync(); + // Act + _ = await store.AppendAsync("C1", [], cancellationToken: Token); - ConversationSessionState state = new() + // Assert + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); + } + + [PostgresFact] + public async Task ItWritesTheStateBesideTheWords() { - Stage = "collecting", - Slots = new Dictionary(StringComparer.Ordinal) + PostgresConversationStore store = await OpenAsync(); + + ConversationSessionState state = new() { - ["model"] = JsonValue.Create("F63"), - }, - }; + Stage = "collecting", + Slots = new Dictionary(StringComparer.Ordinal) + { + ["model"] = JsonValue.Create("F63"), + }, + }; - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - state, - Token); + _ = await store.AppendAsync( + "C1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + state, + Token); - var record = await store.GetAsync("C1", Token); + ConversationRecord? record = await store.GetAsync("C1", Token); - Assert.NotNull(record?.State); - Assert.Equal("collecting", record.State.Stage); - Assert.Equal("F63", record.State.Slots["model"]!.GetValue()); - } + Assert.NotNull(record?.State); + Assert.Equal("collecting", record.State.Stage); + Assert.Equal("F63", record.State.Slots["model"]!.GetValue()); + } - [PostgresFact] - public async Task AConversationWithNoStateReadsAsNull() - { - PostgresConversationStore store = new(DataSource); + [PostgresFact] + public async Task AConversationWithNoStateReadsAsNull() + { + PostgresConversationStore store = new(DataSource); - var record = await store.CreateAsync("C3", Token); + ConversationRecord record = await store.CreateAsync("C3", Token); - Assert.Null(record.State); - } + Assert.Null(record.State); + } - [PostgresFact] - public async Task AnAppendWithNoStateLeavesTheStoredStateAlone() - { - var store = await OpenAsync(); - - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { Stage = "collecting" }, - Token); - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "hi"), "m1")], - state: null, - Token); - - var record = await store.GetAsync("C1", Token); - - Assert.Equal("collecting", record?.State?.Stage); - } + [PostgresFact] + public async Task AnAppendWithNoStateLeavesTheStoredStateAlone() + { + PostgresConversationStore store = await OpenAsync(); - [PostgresFact] - public async Task AnAppendThatFails_LandsNeitherTheWordsNorTheState() - { - // Arrange — D5's whole claim: the blob rides the turn's own batch, so the words and the state - // are of one moment and cannot disagree. Nothing else tests it, and what it rests on is - // implicit: AppendAsync opens no explicit transaction, and atomicity comes from Npgsql - // sending the batch between two Sync messages, which makes PostgreSQL wrap it in one - // implicit transaction of its own. That is a property of the driver, not of this code, so it - // is worth a test that fails the day a version of Npgsql splits the batch. - var store = await OpenAsync(); - await store.AppendAsync( - "C1", - [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], - new ConversationSessionState { Stage = "a" }, - Token); - - // Act — a batch whose FIRST row is new and whose second repeats a message id the conversation - // already holds. The store owns ordinal assignment now, so a caller can no longer force an - // ordinal collision; the unique constraint on (conversation_id, message_id) is what fails instead, - // and "m2" landing would be what a batch that was never one transaction looks like. - var failure = await Record.ExceptionAsync( - () => store.AppendAsync( + _ = await store.AppendAsync( "C1", - [ - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "lands first"), "m2"), - new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "again"), "m0"), - ], - new ConversationSessionState { Stage = "b" }, - Token).AsTask()); - - // Assert — the throw, then the row that had already succeeded, then the state the failed - // batch tried to write. A stage of "b" beside one message would be a conversation whose blob had - // moved on without its words; a surviving "m2" would be a batch that was never one - // transaction. - Assert.NotNull(failure); - var record = await store.GetAsync("C1", Token); - Assert.Equal("a", record?.State?.Stage); - - var rows = await store.ReadAllAsync("C1", Token); - Assert.Single(rows); - Assert.Equal("m0", rows[0].MessageId); - } + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { Stage = "collecting" }, + Token); + _ = await store.AppendAsync( + "C1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.Assistant, "hi"), "m1")], + state: null, + Token); - [PostgresFact] - public async Task AStateBlobThatWillNotParse_ReadsAsNoBlobRatherThanClosingTheConversation() - { - // Arrange — jsonb refuses malformed JSON, so a bad blob is well-formed JSON of the wrong - // shape: an older or newer build's column, or a hand-edited row. Version cannot save this - // one, because Version is only readable after the deserialize has already succeeded. - var store = await OpenAsync(); - await ExecuteAsync("UPDATE agentcore.conversation SET state = '[1, 2, 3]'::jsonb WHERE conversation_id = 'C1'"); - - // Act - var record = await store.GetAsync("C1", Token); - - // Assert — no throw, and no state. A throw here would escape GetAsync, CreateAsync and - // OpenSessionAsync, and the conversation could never be opened again by anyone: one bad row would - // refuse every turn of that call forever, with no diagnostic and no way back. - Assert.NotNull(record); - Assert.Null(record.State); - } + ConversationRecord? record = await store.GetAsync("C1", Token); - // --------------------------------------------------------------------------------------------- - // Rewrite. R4: the record holds the words the caller heard. - // --------------------------------------------------------------------------------------------- - [PostgresFact] - public async Task RewriteAsync_ARow_ReplacesTheWordsOfThatRowOnly() - { - // Arrange - var store = await OpenAsync(); - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + Assert.Equal("collecting", record?.State?.Stage); + } - // Act - await store.RewriteAsync("C1", "m1", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); + [PostgresFact] + public async Task AnAppendThatFails_LandsNeitherTheWordsNorTheState() + { + // Arrange — D5's whole claim: the blob rides the turn's own batch, so the words and the state + // are of one moment and cannot disagree. Nothing else tests it, and what it rests on is + // implicit: AppendAsync opens no explicit transaction, and atomicity comes from Npgsql + // sending the batch between two Sync messages, which makes PostgreSQL wrap it in one + // implicit transaction of its own. That is a property of the driver, not of this code, so it + // is worth a test that fails the day a version of Npgsql splits the batch. + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync( + "C1", + [new ConversationMessageDraft(0, new ChatMessage(ChatRole.User, "hello"), "m0")], + new ConversationSessionState { Stage = "a" }, + Token); + + // Act — a batch whose FIRST row is new and whose second repeats a message id the conversation + // already holds. The store owns ordinal assignment now, so a caller can no longer force an + // ordinal collision; the unique constraint on (conversation_id, message_id) is what fails instead, + // and "m2" landing would be what a batch that was never one transaction looks like. + Exception? failure = await Record.ExceptionAsync( + () => store.AppendAsync( + "C1", + [ + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "lands first"), "m2"), + new ConversationMessageDraft(1, new ChatMessage(ChatRole.User, "again"), "m0"), + ], + new ConversationSessionState { Stage = "b" }, + Token).AsTask()); + + // Assert — the throw, then the row that had already succeeded, then the state the failed + // batch tried to write. A stage of "b" beside one message would be a conversation whose blob had + // moved on without its words; a surviving "m2" would be a batch that was never one + // transaction. + Assert.NotNull(failure); + ConversationRecord? record = await store.GetAsync("C1", Token); + Assert.Equal("a", record?.State?.Stage); + + IReadOnlyList rows = await store.ReadAllAsync("C1", Token); + _ = Assert.Single(rows); + Assert.Equal("m0", rows[0].MessageId); + } - // Assert - var rows = await store.ReadAllAsync("C1", Token); - Assert.Equal(["what about order 41", "Order 41 sh"], rows.Select(row => row.Content.Text).ToArray()); - } + [PostgresFact] + public async Task AStateBlobThatWillNotParse_ReadsAsNoBlobRatherThanClosingTheConversation() + { + // Arrange — jsonb refuses malformed JSON, so a bad blob is well-formed JSON of the wrong + // shape: an older or newer build's column, or a hand-edited row. Version cannot save this + // one, because Version is only readable after the deserialize has already succeeded. + PostgresConversationStore store = await OpenAsync(); + await ExecuteAsync("UPDATE agentcore.conversation SET state = '[1, 2, 3]'::jsonb WHERE conversation_id = 'C1'"); + + // Act + ConversationRecord? record = await store.GetAsync("C1", Token); + + // Assert — no throw, and no state. A throw here would escape GetAsync, CreateAsync and + // OpenSessionAsync, and the conversation could never be opened again by anyone: one bad row would + // refuse every turn of that call forever, with no diagnostic and no way back. + Assert.NotNull(record); + Assert.Null(record.State); + } - [PostgresFact] - public async Task RewriteAsync_ARow_MovesUpdatedAtAndLeavesCreatedAt() - { - // Arrange — the retention sweep reads updated_at, so a corrected turn ages from its - // correction. - var store = await OpenAsync(); - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - await ExecuteAsync("UPDATE agentcore.conversation_message SET created_at = now() - interval '1 hour', updated_at = created_at"); - - // Act - await store.RewriteAsync("C1", "m1", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); - - // Assert - Assert.True(await ScalarAsync( - "SELECT updated_at > created_at FROM agentcore.conversation_message WHERE conversation_id = 'C1' AND message_id = 'm1'")); - } + // --------------------------------------------------------------------------------------------- + // Rewrite. R4: the record holds the words the caller heard. + // --------------------------------------------------------------------------------------------- + [PostgresFact] + public async Task RewriteAsync_ARow_ReplacesTheWordsOfThatRowOnly() + { + // Arrange + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - [PostgresFact] - public async Task RewriteAsync_AMessageIdThatIsNotThere_WritesNothing() - { - // Arrange — a barge-in that raced the append it corrects. The append carries the corrected - // words, so there is nothing to report and nothing to guess at. - var store = await OpenAsync(); - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + // Act + await store.RewriteAsync("C1", "m1", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); - // Act - await store.RewriteAsync("C1", "does-not-exist", new ChatMessage(ChatRole.Assistant, "never spoken"), Token); + // Assert + IReadOnlyList rows = await store.ReadAllAsync("C1", Token); + Assert.Equal(["what about order 41", "Order 41 sh"], [.. rows.Select(row => row.Content.Text)]); + } - // Assert - Assert.Equal(2L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); - } + [PostgresFact] + public async Task RewriteAsync_ARow_MovesUpdatedAtAndLeavesCreatedAt() + { + // Arrange — the retention sweep reads updated_at, so a corrected turn ages from its + // correction. + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + await ExecuteAsync("UPDATE agentcore.conversation_message SET created_at = now() - interval '1 hour', updated_at = created_at"); + + // Act + await store.RewriteAsync("C1", "m1", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); + + // Assert + Assert.True(await ScalarAsync( + "SELECT updated_at > created_at FROM agentcore.conversation_message WHERE conversation_id = 'C1' AND message_id = 'm1'")); + } - // --------------------------------------------------------------------------------------------- - // Erase, and the sweep. - // --------------------------------------------------------------------------------------------- - [PostgresFact] - public async Task EraseAsync_OneConversation_DeletesItsRowsAndLeavesTheOthers() - { - // Arrange - var store = await OpenAsync(); - await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - await store.AppendAsync("C2", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); - - // Act - var erased = await store.EraseAsync("C1", Token); - - // Assert - Assert.Equal(2, erased); - Assert.Empty(await store.ReadAllAsync("C1", Token)); - Assert.Equal(2, (await store.ReadAllAsync("C2", Token)).Count); - } + [PostgresFact] + public async Task RewriteAsync_AMessageIdThatIsNotThere_WritesNothing() + { + // Arrange — a barge-in that raced the append it corrects. The append carries the corrected + // words, so there is nothing to report and nothing to guess at. + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + // Act + await store.RewriteAsync("C1", "does-not-exist", new ChatMessage(ChatRole.Assistant, "never spoken"), Token); + // Assert + Assert.Equal(2L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); + } + // --------------------------------------------------------------------------------------------- + // Erase, and the sweep. + // --------------------------------------------------------------------------------------------- + [PostgresFact] + public async Task EraseAsync_OneConversation_DeletesItsRowsAndLeavesTheOthers() + { + // Arrange + PostgresConversationStore store = await OpenAsync(); + _ = await store.AppendAsync("C1", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + _ = await store.AppendAsync("C2", Turn(turnIndex: 0, idSeed: 0), cancellationToken: Token); + + // Act + int erased = await store.EraseAsync("C1", Token); + + // Assert + Assert.Equal(2, erased); + Assert.Empty(await store.ReadAllAsync("C1", Token)); + Assert.Equal(2, (await store.ReadAllAsync("C2", Token)).Count); + } - // --------------------------------------------------------------------------------------------- - // Store 1 against store 3. - // --------------------------------------------------------------------------------------------- - [PostgresFact] - public async Task ReadSpokenTurnsAsync_AToolCallingTurn_ReturnsOneRowForThatTurn() - { - // Arrange — the DISTINCT ON guard. The turn writes an assistant message carrying the tool - // conversation and another carrying the reply; without it both come back, and the textless one - // reports a false tamper on every tool-calling turn. - var store = await OpenAsync(); - await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); - - // Act - var turns = await store.ReadSpokenTurnsAsync("C1", Token); - - // Assert - var turn = Assert.Single(turns); - Assert.Equal("Order 41 ships Friday.", turn.Spoken); - } - [PostgresFact] - public async Task ReadSpokenTurnsAsync_AToolCallingTurn_MatchesTheHashTheChainHolds() - { - // Arrange - var store = await OpenAsync(); - await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); - // Act - var turns = await store.ReadSpokenTurnsAsync("C1", Token); - // Assert — what the nightly check does: hash the words store 1 holds, and compare. - Assert.Equal(AuditHash.OfText(turns[0].Spoken).Value, turns[0].ReplyTextSha256); - } + // --------------------------------------------------------------------------------------------- + // Store 1 against store 3. + // --------------------------------------------------------------------------------------------- + [PostgresFact] + public async Task ReadSpokenTurnsAsync_AToolCallingTurn_ReturnsOneRowForThatTurn() + { + // Arrange — the DISTINCT ON guard. The turn writes an assistant message carrying the tool + // conversation and another carrying the reply; without it both come back, and the textless one + // reports a false tamper on every tool-calling turn. + PostgresConversationStore store = await OpenAsync(); + _ = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); + + // Act + IReadOnlyList turns = await store.ReadSpokenTurnsAsync("C1", Token); + + // Assert + TranscriptTurnDigest turn = Assert.Single(turns); + Assert.Equal("Order 41 ships Friday.", turn.Spoken); + } - [PostgresFact] - public async Task ReadSpokenTurnsAsync_AToolCallingTurnThatAlsoDrew_MatchesTheHashTheChainHolds() - { - // Arrange — a RenderContent rides the tool-result message alongside its FunctionResultContent. - // The verify query never looks at that row's role, but jsonb round-tripping a second content - // type on it must not upset the DISTINCT ON guard or the hash comparison. - var store = await OpenAsync(); - await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday.", drew: true); - - // Act - var turns = await store.ReadSpokenTurnsAsync("C1", Token); - - // Assert - var turn = Assert.Single(turns); - Assert.Equal(AuditHash.OfText(turn.Spoken).Value, turn.ReplyTextSha256); - } + [PostgresFact] + public async Task ReadSpokenTurnsAsync_AToolCallingTurn_MatchesTheHashTheChainHolds() + { + // Arrange + PostgresConversationStore store = await OpenAsync(); + _ = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); - [PostgresFact] - public async Task ReadSpokenTurnsAsync_ATurnWhoseWordsWereErased_ReturnsNoRowForIt() - { - // Arrange — the erasure working, and not a tamper. The chain keeps its row and goes on - // proving what it proved. - var store = await OpenAsync(); - await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); - await store.EraseAsync("C1", Token); - - // Act - var turns = await store.ReadSpokenTurnsAsync("C1", Token); - - // Assert - Assert.Empty(turns); - Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } + // Act + IReadOnlyList turns = await store.ReadSpokenTurnsAsync("C1", Token); - [PostgresFact] - public async Task ReadSpokenTurnsAsync_ATurnAmendedInTheChain_ReturnsOneRowHoldingTheLatestHash() - { - // Arrange — a barge-in amends a turn, so the chain carries a second turn.completed for it. - // Without the guard on the chain side the join multiplies and one turn answers twice. - var store = await OpenAsync(); - var firstEventId = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); - await store.RewriteAsync("C1", "m3", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); - await AmendTurnAsync("C1", turnIndex: 0, amends: firstEventId, spoken: "Order 41 sh"); - - // Act - var turns = await store.ReadSpokenTurnsAsync("C1", Token); - - // Assert - var turn = Assert.Single(turns); - Assert.Equal(AuditHash.OfText("Order 41 sh").Value, turn.ReplyTextSha256); - } + // Assert — what the nightly check does: hash the words store 1 holds, and compare. + Assert.Equal(AuditHash.OfText(turns[0].Spoken).Value, turns[0].ReplyTextSha256); + } - /// - /// One ordinary turn: what the caller said, and what the caller heard. - /// only keeps message ids unique across appends to the same conversation — the store assigns the - /// ordinal, so it no longer says where the turn lands. - /// - private static ConversationMessageDraft[] Turn(int turnIndex, int idSeed) => - [ - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, "what about order 41"), $"m{idSeed}"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, "Order 41 ships Friday."), $"m{idSeed + 1}"), - ]; - - /// Writes a tool-calling turn to store 1 and its turn.completed row to store 3. - private async Task WriteToolCallingTurnAsync( - PostgresConversationStore store, string conversationId, int turnIndex, string spoken, bool drew = false) - { - List toolResultContents = [new FunctionResultContent("id1", "Friday")]; - if (drew) + [PostgresFact] + public async Task ReadSpokenTurnsAsync_AToolCallingTurnThatAlsoDrew_MatchesTheHashTheChainHolds() { - toolResultContents.Add(new RenderContent - { - Name = "generative-ui", - RenderId = "chart-1", - Data = JsonSerializer.SerializeToElement(new { title = "Q3 revenue" }), - }); + // Arrange — a RenderContent rides the tool-result message alongside its FunctionResultContent. + // The verify query never looks at that row's role, but jsonb round-tripping a second content + // type on it must not upset the DISTINCT ON guard or the hash comparison. + PostgresConversationStore store = await OpenAsync(); + _ = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday.", drew: true); + + // Act + IReadOnlyList turns = await store.ReadSpokenTurnsAsync("C1", Token); + + // Assert + TranscriptTurnDigest turn = Assert.Single(turns); + Assert.Equal(AuditHash.OfText(turn.Spoken).Value, turn.ReplyTextSha256); + } + + [PostgresFact] + public async Task ReadSpokenTurnsAsync_ATurnWhoseWordsWereErased_ReturnsNoRowForIt() + { + // Arrange — the erasure working, and not a tamper. The chain keeps its row and goes on + // proving what it proved. + PostgresConversationStore store = await OpenAsync(); + _ = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); + _ = await store.EraseAsync("C1", Token); + + // Act + IReadOnlyList turns = await store.ReadSpokenTurnsAsync("C1", Token); + + // Assert + Assert.Empty(turns); + Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); } - await store.AppendAsync( - conversationId, - [ - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, "what about order 41"), "m0"), - new ConversationMessageDraft(turnIndex, new ChatMessage( - ChatRole.Assistant, [new FunctionCallContent("id1", "lookup", null)]), "m1"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Tool, toolResultContents), "m2"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, spoken), "m3"), - ], - cancellationToken: Token); - - // Not disposed: the sink would take the test's own pool with it. - Guid eventId = Guid.CreateVersion7(); - PostgresAuditSink chain = new(DataSource); - await chain.AppendAsync( - new AuditEvent + [PostgresFact] + public async Task ReadSpokenTurnsAsync_ATurnAmendedInTheChain_ReturnsOneRowHoldingTheLatestHash() + { + // Arrange — a barge-in amends a turn, so the chain carries a second turn.completed for it. + // Without the guard on the chain side the join multiplies and one turn answers twice. + PostgresConversationStore store = await OpenAsync(); + Guid firstEventId = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday."); + await store.RewriteAsync("C1", "m3", new ChatMessage(ChatRole.Assistant, "Order 41 sh"), Token); + await AmendTurnAsync("C1", turnIndex: 0, amends: firstEventId, spoken: "Order 41 sh"); + + // Act + IReadOnlyList turns = await store.ReadSpokenTurnsAsync("C1", Token); + + // Assert + TranscriptTurnDigest turn = Assert.Single(turns); + Assert.Equal(AuditHash.OfText("Order 41 sh").Value, turn.ReplyTextSha256); + } + + /// + /// One ordinary turn: what the caller said, and what the caller heard. + /// only keeps message ids unique across appends to the same conversation — the store assigns the + /// ordinal, so it no longer says where the turn lands. + /// + private static ConversationMessageDraft[] Turn(int turnIndex, int idSeed) + { + return [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, "what about order 41"), $"m{idSeed}"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, "Order 41 ships Friday."), $"m{idSeed + 1}"), + ]; + } + + /// Writes a tool-calling turn to store 1 and its turn.completed row to store 3. + private async Task WriteToolCallingTurnAsync( + PostgresConversationStore store, string conversationId, int turnIndex, string spoken, bool drew = false) + { + List toolResultContents = [new FunctionResultContent("id1", "Friday")]; + if (drew) { - ConversationId = conversationId, - EventId = eventId, - Kind = AuditEventKind.TurnCompleted, - OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 1, TimeSpan.Zero), - TurnIndex = turnIndex, - Payload = new Dictionary(StringComparer.Ordinal) + toolResultContents.Add(new RenderContent { - [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(spoken).Value, + Name = "generative-ui", + RenderId = "chart-1", + Data = JsonSerializer.SerializeToElement(new { title = "Q3 revenue" }), + }); + } + + _ = await store.AppendAsync( + conversationId, + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, "what about order 41"), "m0"), + new ConversationMessageDraft(turnIndex, new ChatMessage( + ChatRole.Assistant, [new FunctionCallContent("id1", "lookup", null)]), "m1"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Tool, toolResultContents), "m2"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, spoken), "m3"), + ], + cancellationToken: Token); + + // Not disposed: the sink would take the test's own pool with it. + Guid eventId = Guid.CreateVersion7(); + PostgresAuditSink chain = new(DataSource); + await chain.AppendAsync( + new AuditEvent + { + ConversationId = conversationId, + EventId = eventId, + Kind = AuditEventKind.TurnCompleted, + OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 1, TimeSpan.Zero), + TurnIndex = turnIndex, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(spoken).Value, + }, }, - }, - Token); + Token); - return eventId; - } + return eventId; + } - /// Writes a second turn.completed that corrects the first, as a barge-in does. - private async Task AmendTurnAsync(string conversationId, int turnIndex, Guid amends, string spoken) - { - // Not disposed: the sink would take the test's own pool with it. - PostgresAuditSink chain = new(DataSource); - await chain.AppendAsync( - new AuditEvent - { - ConversationId = conversationId, - EventId = Guid.CreateVersion7(), - Kind = AuditEventKind.TurnCompleted, - OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 2, TimeSpan.Zero), - TurnIndex = turnIndex, - AmendsEventId = amends, - Payload = new Dictionary(StringComparer.Ordinal) + /// Writes a second turn.completed that corrects the first, as a barge-in does. + private async Task AmendTurnAsync(string conversationId, int turnIndex, Guid amends, string spoken) + { + // Not disposed: the sink would take the test's own pool with it. + PostgresAuditSink chain = new(DataSource); + await chain.AppendAsync( + new AuditEvent { - [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(spoken).Value, + ConversationId = conversationId, + EventId = Guid.CreateVersion7(), + Kind = AuditEventKind.TurnCompleted, + OccurredAt = new DateTimeOffset(2026, 8, 19, 9, 0, 2, TimeSpan.Zero), + TurnIndex = turnIndex, + AmendsEventId = amends, + Payload = new Dictionary(StringComparer.Ordinal) + { + [AuditPayloadKeys.ReplyTextSha256] = AuditHash.OfText(spoken).Value, + }, }, - }, - Token); + Token); + } } - - /// Moves one conversation's rows back in time, so the sweep can be asked about them. - private Task AgeAsync(string conversationId, TimeSpan age) => ExecuteAsync( - $"UPDATE agentcore.conversation_message SET updated_at = now() - interval '{age.TotalDays} days' WHERE conversation_id = '{conversationId}'"); } diff --git a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresCluster.cs b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresCluster.cs index 522441ea..aa7ef84a 100644 --- a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresCluster.cs +++ b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresCluster.cs @@ -1,17 +1,18 @@ -namespace AgentCore.Infrastructure.Tests.Database.Postgres; - -/// The PostgreSQL cluster the integration tests run against, if the environment names one. -public static class PostgresCluster +namespace AgentCore.Infrastructure.Tests.Database.Postgres { - private const string Variable = "AGENTCORE_TEST_POSTGRES"; + /// The PostgreSQL cluster the integration tests run against, if the environment names one. + public static class PostgresCluster + { + private const string Variable = "AGENTCORE_TEST_POSTGRES"; - /// Why a test skipped, when it did. - public const string SkipReason = "Set AGENTCORE_TEST_POSTGRES to run."; + /// Why a test skipped, when it did. + public const string SkipReason = "Set AGENTCORE_TEST_POSTGRES to run."; - /// The connection string, or null when the environment names no cluster. - public static string? ConnectionString => - Environment.GetEnvironmentVariable(Variable) is { Length: > 0 } value ? value : null; + /// The connection string, or null when the environment names no cluster. + public static string? ConnectionString => + Environment.GetEnvironmentVariable(Variable) is { Length: > 0 } value ? value : null; - /// Whether a cluster was named. - public static bool IsConfigured => ConnectionString is not null; + /// Whether a cluster was named. + public static bool IsConfigured => ConnectionString is not null; + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresDatabaseTest.cs b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresDatabaseTest.cs index a98723aa..143bf0a9 100644 --- a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresDatabaseTest.cs +++ b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresDatabaseTest.cs @@ -1,67 +1,68 @@ using Npgsql; using Xunit; -namespace AgentCore.Infrastructure.Tests.Database.Postgres; - -/// -/// A test that runs against a PostgreSQL database of its own. -/// -/// -/// Every test here needs the same four things — a fresh database, a token, a way to run a statement, -/// and a way to read one value — so they live once. Mark the tests themselves with -/// or , which is what makes -/// them skip when the environment names no cluster. -/// -public abstract class PostgresDatabaseTest : IAsyncLifetime +namespace AgentCore.Infrastructure.Tests.Database.Postgres { - private PostgresTestDatabase? _database; + /// + /// A test that runs against a PostgreSQL database of its own. + /// + /// + /// Every test here needs the same four things — a fresh database, a token, a way to run a statement, + /// and a way to read one value — so they live once. Mark the tests themselves with + /// or , which is what makes + /// them skip when the environment names no cluster. + /// + public abstract class PostgresDatabaseTest : IAsyncLifetime + { + private PostgresTestDatabase? _database; - /// Whether the schema is applied before the test body runs. - protected abstract bool Migrated { get; } + /// Whether the schema is applied before the test body runs. + protected abstract bool Migrated { get; } - /// The token every conversation in a test body carries. - protected static CancellationToken Token => TestContext.Current.CancellationToken; + /// The token every conversation in a test body carries. + protected static CancellationToken Token => TestContext.Current.CancellationToken; - /// The database this test owns. - protected PostgresTestDatabase Database => - _database ?? throw new InvalidOperationException("No database was created."); + /// The database this test owns. + protected PostgresTestDatabase Database => + _database ?? throw new InvalidOperationException("No database was created."); - /// The pool that reaches it. - protected NpgsqlDataSource DataSource => Database.DataSource; + /// The pool that reaches it. + protected NpgsqlDataSource DataSource => Database.DataSource; - /// - public async ValueTask InitializeAsync() - { - if (PostgresCluster.IsConfigured) + /// + public async ValueTask InitializeAsync() { - _database = Migrated - ? await PostgresTestDatabase.CreateMigratedAsync(Token) - : await PostgresTestDatabase.CreateAsync(Token); + if (PostgresCluster.IsConfigured) + { + _database = Migrated + ? await PostgresTestDatabase.CreateMigratedAsync(Token) + : await PostgresTestDatabase.CreateAsync(Token); + } } - } - /// - public async ValueTask DisposeAsync() - { - if (_database is not null) + /// + public async ValueTask DisposeAsync() { - await _database.DisposeAsync(); - } + if (_database is not null) + { + await _database.DisposeAsync(); + } - GC.SuppressFinalize(this); - } + GC.SuppressFinalize(this); + } - /// Runs a statement and keeps no result. - protected async Task ExecuteAsync(string sql) - { - await using var command = DataSource.CreateCommand(sql); - await command.ExecuteNonQueryAsync(Token); - } + /// Runs a statement and keeps no result. + protected async Task ExecuteAsync(string sql) + { + await using NpgsqlCommand command = DataSource.CreateCommand(sql); + _ = await command.ExecuteNonQueryAsync(Token); + } - /// Runs a statement and reads its first value. - protected async Task ScalarAsync(string sql) - { - await using var command = DataSource.CreateCommand(sql); - return (T)(await command.ExecuteScalarAsync(Token))!; + /// Runs a statement and reads its first value. + protected async Task ScalarAsync(string sql) + { + await using NpgsqlCommand command = DataSource.CreateCommand(sql); + return (T)(await command.ExecuteScalarAsync(Token))!; + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresFactAttribute.cs b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresFactAttribute.cs index 2c1a7ef9..23ffb1de 100644 --- a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresFactAttribute.cs +++ b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresFactAttribute.cs @@ -1,26 +1,27 @@ using System.Runtime.CompilerServices; using Xunit; -namespace AgentCore.Infrastructure.Tests.Database.Postgres; - -/// A test that needs a live PostgreSQL, and skips itself when none is named. -/// -/// AGENTCORE_TEST_POSTGRES names the cluster, for example -/// Host=localhost;Port=55432;Username=postgres;Password=pw. The role it names must be allowed -/// to create databases and roles. Steps 7 to 10 of the build add more tests behind the same gate. -/// -public sealed class PostgresFactAttribute : FactAttribute +namespace AgentCore.Infrastructure.Tests.Database.Postgres { - /// Creates the attribute. - /// Supplied by the compiler. - /// Supplied by the compiler. - public PostgresFactAttribute( - [CallerFilePath] string? sourceFilePath = null, - [CallerLineNumber] int sourceLineNumber = -1) - : base(sourceFilePath, sourceLineNumber) + /// A test that needs a live PostgreSQL, and skips itself when none is named. + /// + /// AGENTCORE_TEST_POSTGRES names the cluster, for example + /// Host=localhost;Port=55432;Username=postgres;Password=pw. The role it names must be allowed + /// to create databases and roles. Steps 7 to 10 of the build add more tests behind the same gate. + /// + public sealed class PostgresFactAttribute : FactAttribute { - Skip = PostgresCluster.SkipReason; - SkipUnless = nameof(PostgresCluster.IsConfigured); - SkipType = typeof(PostgresCluster); + /// Creates the attribute. + /// Supplied by the compiler. + /// Supplied by the compiler. + public PostgresFactAttribute( + [CallerFilePath] string? sourceFilePath = null, + [CallerLineNumber] int sourceLineNumber = -1) + : base(sourceFilePath, sourceLineNumber) + { + Skip = PostgresCluster.SkipReason; + SkipUnless = nameof(PostgresCluster.IsConfigured); + SkipType = typeof(PostgresCluster); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresSchemaTests.cs b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresSchemaTests.cs index d3c7eac4..73b962b4 100644 --- a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresSchemaTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresSchemaTests.cs @@ -2,286 +2,292 @@ using Npgsql; using Xunit; -namespace AgentCore.Infrastructure.Tests.Database.Postgres; - -/// -/// The PostgreSQL schema store 1 and store 3 run on. -/// -public sealed class PostgresSchemaTests : PostgresDatabaseTest +namespace AgentCore.Infrastructure.Tests.Database.Postgres { - /// - protected override bool Migrated => false; - - [PostgresTheory] - [InlineData("agentcore.conversation")] - [InlineData("agentcore.conversation_principal")] - [InlineData("agentcore.conversation_message")] - [InlineData("agentcore.audit_event")] - [InlineData("agentcore.schema_migration")] - public async Task ApplyAsync_FreshDatabase_CreatesTheTable(string table) - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - - // Act - var exists = await ScalarAsync($"SELECT to_regclass('{table}') IS NOT NULL"); - - // Assert - Assert.True(exists); - } - - [PostgresFact] - public async Task ApplyAsync_FreshDatabase_GivesConversationANextOrdinalColumn() + /// + /// The PostgreSQL schema store 1 and store 3 run on. + /// + public sealed class PostgresSchemaTests : PostgresDatabaseTest { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - - // Act - var column = await ScalarAsync( - """ + /// + protected override bool Migrated => false; + + [PostgresTheory] + [InlineData("agentcore.conversation")] + [InlineData("agentcore.conversation_principal")] + [InlineData("agentcore.conversation_message")] + [InlineData("agentcore.audit_event")] + [InlineData("agentcore.schema_migration")] + public async Task ApplyAsync_FreshDatabase_CreatesTheTable(string table) + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Act + bool exists = await ScalarAsync($"SELECT to_regclass('{table}') IS NOT NULL"); + + // Assert + Assert.True(exists); + } + + [PostgresFact] + public async Task ApplyAsync_FreshDatabase_GivesConversationANextOrdinalColumn() + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Act + string column = await ScalarAsync( + """ SELECT is_nullable || ',' || column_default FROM information_schema.columns WHERE table_schema = 'agentcore' AND table_name = 'conversation' AND column_name = 'next_ordinal' """); - // Assert - Assert.Equal("NO,0", column); - } - - [PostgresFact] - public async Task ApplyAsync_FreshDatabase_AppliesEveryMigration() - { - // Arrange, Act - var applied = await PostgresSchema.ApplyAsync(DataSource, Token); - - // Assert - Assert.Equal(PostgresSchema.Versions, applied); - } - - [PostgresFact] - public async Task ApplyAsync_AlreadyCurrent_AppliesNothing() - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - - // Act - var second = await PostgresSchema.ApplyAsync(DataSource, Token); - - // Assert - Assert.Empty(second); - } - - [PostgresFact] - public async Task ApplyAsync_AsTheWriterRoleOnACurrentDatabase_AppliesNothing() - { - // Arrange — this is what the host does on every start. The running system logs in as a member - // of agentcore_writer, which may create nothing, so a start that tried to migrate would fail - // on an ordinary boot rather than only on a fresh database. - await PostgresSchema.ApplyAsync(DataSource, Token); - await using var asWriter = await OpenAsWriterAsync(); - - // Act - var applied = await PostgresSchema.ApplyAsync(asWriter, Token); - - // Assert - Assert.Empty(applied); - } - - [PostgresTheory] - [InlineData("UPDATE", false)] - [InlineData("DELETE", false)] - [InlineData("TRUNCATE", false)] - [InlineData("INSERT", true)] - [InlineData("SELECT", true)] - public async Task ApplyAsync_FreshDatabase_LeavesTheWriterInsertAndSelectOnly(string privilege, bool expected) - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - - // Act - var held = await ScalarAsync($"SELECT has_table_privilege('agentcore_writer', 'agentcore.audit_event', '{privilege}')"); - - // Assert - Assert.Equal(expected, held); - } - - [PostgresTheory] - [InlineData("UPDATE")] - [InlineData("DELETE")] - [InlineData("TRUNCATE")] - public async Task ApplyAsync_PublicHoldsGrantAll_StillLeavesTheWriterWithoutThePrivilege(string privilege) - { - // Arrange — the hole the PUBLIC revoke exists to close. An earlier migration left PUBLIC - // holding everything on new tables, and revoking from the role alone does not take it back. - await ExecuteAsync("ALTER DEFAULT PRIVILEGES GRANT ALL ON TABLES TO PUBLIC"); - await PostgresSchema.ApplyAsync(DataSource, Token); - - // Act - var held = await ScalarAsync($"SELECT has_table_privilege('agentcore_writer', 'agentcore.audit_event', '{privilege}')"); - - // Assert - Assert.False(held); - } - - [PostgresTheory] - [InlineData("UPDATE agentcore.audit_event SET kind = 'tampered'")] - [InlineData("DELETE FROM agentcore.audit_event")] - [InlineData("TRUNCATE agentcore.audit_event")] - public async Task AuditEvent_OwnerWritesOverAnExistingRow_IsRefusedByTrigger(string statement) - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - await InsertOneEventAsync(); - - // Act - var refusal = await Record.ExceptionAsync(() => ExecuteAsync(statement)); - - // Assert - Assert.Contains("append-only", Assert.IsType(refusal).MessageText, StringComparison.Ordinal); - } - - [PostgresFact] - public async Task AuditEvent_SuppliedWritePosition_IsRefused() - { - // Arrange — the database allocates write_position, so pin that it refuses a supplied one. - await PostgresSchema.ApplyAsync(DataSource, Token); - - // Act - var refusal = await Record.ExceptionAsync(() => ExecuteAsync( - """ + // Assert + Assert.Equal("NO,0", column); + } + + [PostgresFact] + public async Task ApplyAsync_FreshDatabase_AppliesEveryMigration() + { + // Arrange, Act + IReadOnlyList applied = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Assert + Assert.Equal(PostgresSchema.Versions, applied); + } + + [PostgresFact] + public async Task ApplyAsync_AlreadyCurrent_AppliesNothing() + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Act + IReadOnlyList second = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Assert + Assert.Empty(second); + } + + [PostgresFact] + public async Task ApplyAsync_AsTheWriterRoleOnACurrentDatabase_AppliesNothing() + { + // Arrange — this is what the host does on every start. The running system logs in as a member + // of agentcore_writer, which may create nothing, so a start that tried to migrate would fail + // on an ordinary boot rather than only on a fresh database. + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await using NpgsqlDataSource asWriter = await OpenAsWriterAsync(); + + // Act + IReadOnlyList applied = await PostgresSchema.ApplyAsync(asWriter, Token); + + // Assert + Assert.Empty(applied); + } + + [PostgresTheory] + [InlineData("UPDATE", false)] + [InlineData("DELETE", false)] + [InlineData("TRUNCATE", false)] + [InlineData("INSERT", true)] + [InlineData("SELECT", true)] + public async Task ApplyAsync_FreshDatabase_LeavesTheWriterInsertAndSelectOnly(string privilege, bool expected) + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Act + bool held = await ScalarAsync($"SELECT has_table_privilege('agentcore_writer', 'agentcore.audit_event', '{privilege}')"); + + // Assert + Assert.Equal(expected, held); + } + + [PostgresTheory] + [InlineData("UPDATE")] + [InlineData("DELETE")] + [InlineData("TRUNCATE")] + public async Task ApplyAsync_PublicHoldsGrantAll_StillLeavesTheWriterWithoutThePrivilege(string privilege) + { + // Arrange — the hole the PUBLIC revoke exists to close. An earlier migration left PUBLIC + // holding everything on new tables, and revoking from the role alone does not take it back. + await ExecuteAsync("ALTER DEFAULT PRIVILEGES GRANT ALL ON TABLES TO PUBLIC"); + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Act + bool held = await ScalarAsync($"SELECT has_table_privilege('agentcore_writer', 'agentcore.audit_event', '{privilege}')"); + + // Assert + Assert.False(held); + } + + [PostgresTheory] + [InlineData("UPDATE agentcore.audit_event SET kind = 'tampered'")] + [InlineData("DELETE FROM agentcore.audit_event")] + [InlineData("TRUNCATE agentcore.audit_event")] + public async Task AuditEvent_OwnerWritesOverAnExistingRow_IsRefusedByTrigger(string statement) + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await InsertOneEventAsync(); + + // Act + Exception? refusal = await Record.ExceptionAsync(() => ExecuteAsync(statement)); + + // Assert + Assert.Contains("append-only", Assert.IsType(refusal).MessageText, StringComparison.Ordinal); + } + + [PostgresFact] + public async Task AuditEvent_SuppliedWritePosition_IsRefused() + { + // Arrange — the database allocates write_position, so pin that it refuses a supplied one. + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + + // Act + Exception? refusal = await Record.ExceptionAsync(() => ExecuteAsync( + """ INSERT INTO agentcore.audit_event (write_position, conversation_id, event_id, sequence, kind, occurred_at) VALUES (1, 'C1', gen_random_uuid(), 1, 'conversation.started', now()) """)); - // Assert - Assert.Equal("428C9", Assert.IsType(refusal).SqlState); - } - - [PostgresFact] - public async Task AuditEvent_SecondRowOnTheSameConversationAndSequence_IsRefused() - { - // Arrange — raw SQL stands in for the store here, so the table itself is what catches two - // rows landing on the same conversation and sequence. - await PostgresSchema.ApplyAsync(DataSource, Token); - await InsertOneEventAsync(); - - // Act - var refusal = await Record.ExceptionAsync(() => ExecuteAsync( - """ + // Assert + Assert.Equal("428C9", Assert.IsType(refusal).SqlState); + } + + [PostgresFact] + public async Task AuditEvent_SecondRowOnTheSameConversationAndSequence_IsRefused() + { + // Arrange — raw SQL stands in for the store here, so the table itself is what catches two + // rows landing on the same conversation and sequence. + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await InsertOneEventAsync(); + + // Act + Exception? refusal = await Record.ExceptionAsync(() => ExecuteAsync( + """ INSERT INTO agentcore.audit_event (conversation_id, event_id, sequence, kind, occurred_at) VALUES ('C1', gen_random_uuid(), 1, 'conversation.ended', now()) """)); - // Assert - Assert.Equal("23505", Assert.IsType(refusal).SqlState); - } - - [PostgresFact] - public async Task AuditEvent_SessionReplicationRoleIsReplica_BypassesEveryTrigger() - { - // Arrange — session_replication_role bypasses all three triggers in one statement with no - // DDL. Nothing detects that edit; see the fourth design amendment in docs/BUILD.md. - await PostgresSchema.ApplyAsync(DataSource, Token); - await ExecuteAsync( - """ + // Assert + Assert.Equal("23505", Assert.IsType(refusal).SqlState); + } + + [PostgresFact] + public async Task AuditEvent_SessionReplicationRoleIsReplica_BypassesEveryTrigger() + { + // Arrange — session_replication_role bypasses all three triggers in one statement with no + // DDL. Nothing detects that edit; see the fourth design amendment in docs/BUILD.md. + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await ExecuteAsync( + """ INSERT INTO agentcore.audit_event (conversation_id, event_id, sequence, kind, occurred_at) VALUES ('C1', gen_random_uuid(), 0, 'conversation.started', now()) """); - // Act - await ExecuteAsync( - """ + // Act + await ExecuteAsync( + """ SET session_replication_role = replica; UPDATE agentcore.audit_event SET kind = 'conversation.ended' WHERE sequence = 0; SET session_replication_role = origin; """); - // Assert - Assert.Equal("conversation.ended", await ScalarAsync("SELECT kind FROM agentcore.audit_event WHERE sequence = 0")); - } - - [PostgresFact] - public async Task ConversationMessage_SecondMessageOnTheSameOrdinal_IsRefused() - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('C1')"); - await ExecuteAsync( - "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('C1', 0, 0, 'user', '{}', 'm0')"); - - // Act - var refusal = await Record.ExceptionAsync(() => ExecuteAsync( - "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('C1', 0, 0, 'assistant', '{}', 'm1')")); - - // Assert - Assert.Equal("23505", Assert.IsType(refusal).SqlState); - } - - [PostgresFact] - public async Task Versions_AreTheOneMigrationThisAssemblyCarries() - => Assert.Equal(["001_agentcore"], PostgresSchema.Versions); - - [PostgresFact] - public async Task ConversationMessage_WithNoConversationRow_IsRefused() - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('present')"); - - // Act - var refusal = await Record.ExceptionAsync(() => ExecuteAsync( - "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('absent', 0, 0, 'user', '{}', 'm0')")); - - // Assert - Assert.Equal("23503", Assert.IsType(refusal).SqlState); - } - - /// - /// The cascade is the whole reason one store holds both. It reaches conversation_message and - /// conversation_principal, and it deliberately does not reach audit_event: a trigger refuses every - /// DELETE there, and the trail outlives the conversation on purpose. - /// - [PostgresFact] - public async Task DeletingAConversation_TakesItsMessagesAndPrincipals_AndLeavesItsAuditEvents() - { - // Arrange - await PostgresSchema.ApplyAsync(DataSource, Token); - await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('C1')"); - await ExecuteAsync( - "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('C1', 0, 0, 'user', '{}', 'm0')"); - await ExecuteAsync( - "INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('C1', 'p1', 'owner')"); - await InsertOneEventAsync(); - - // Act - await ExecuteAsync("DELETE FROM agentcore.conversation WHERE conversation_id = 'C1'"); - - // Assert - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); - Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); - Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); - } - - private Task InsertOneEventAsync() => ExecuteAsync( - """ + // Assert + Assert.Equal("conversation.ended", await ScalarAsync("SELECT kind FROM agentcore.audit_event WHERE sequence = 0")); + } + + [PostgresFact] + public async Task ConversationMessage_SecondMessageOnTheSameOrdinal_IsRefused() + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('C1')"); + await ExecuteAsync( + "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('C1', 0, 0, 'user', '{}', 'm0')"); + + // Act + Exception? refusal = await Record.ExceptionAsync(() => ExecuteAsync( + "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('C1', 0, 0, 'assistant', '{}', 'm1')")); + + // Assert + Assert.Equal("23505", Assert.IsType(refusal).SqlState); + } + + [PostgresFact] + public async Task Versions_AreTheOneMigrationThisAssemblyCarries() + { + Assert.Equal(["001_agentcore"], PostgresSchema.Versions); + } + + [PostgresFact] + public async Task ConversationMessage_WithNoConversationRow_IsRefused() + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('present')"); + + // Act + Exception? refusal = await Record.ExceptionAsync(() => ExecuteAsync( + "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('absent', 0, 0, 'user', '{}', 'm0')")); + + // Assert + Assert.Equal("23503", Assert.IsType(refusal).SqlState); + } + + /// + /// The cascade is the whole reason one store holds both. It reaches conversation_message and + /// conversation_principal, and it deliberately does not reach audit_event: a trigger refuses every + /// DELETE there, and the trail outlives the conversation on purpose. + /// + [PostgresFact] + public async Task DeletingAConversation_TakesItsMessagesAndPrincipals_AndLeavesItsAuditEvents() + { + // Arrange + _ = await PostgresSchema.ApplyAsync(DataSource, Token); + await ExecuteAsync("INSERT INTO agentcore.conversation (conversation_id) VALUES ('C1')"); + await ExecuteAsync( + "INSERT INTO agentcore.conversation_message (conversation_id, ordinal, turn_index, role, content, message_id) VALUES ('C1', 0, 0, 'user', '{}', 'm0')"); + await ExecuteAsync( + "INSERT INTO agentcore.conversation_principal (conversation_id, principal_key, role) VALUES ('C1', 'p1', 'owner')"); + await InsertOneEventAsync(); + + // Act + await ExecuteAsync("DELETE FROM agentcore.conversation WHERE conversation_id = 'C1'"); + + // Assert + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_message")); + Assert.Equal(0L, await ScalarAsync("SELECT count(*) FROM agentcore.conversation_principal")); + Assert.Equal(1L, await ScalarAsync("SELECT count(*) FROM agentcore.audit_event")); + } + + private Task InsertOneEventAsync() + { + return ExecuteAsync( + """ INSERT INTO agentcore.audit_event (conversation_id, event_id, sequence, kind, occurred_at) VALUES ('C1', gen_random_uuid(), 1, 'conversation.started', now()) """); + } - /// Opens a pool that logs in as an ordinary member of agentcore_writer. - private async Task OpenAsWriterAsync() - { - var login = "agentcore_member_" + Guid.NewGuid().ToString("n"); + /// Opens a pool that logs in as an ordinary member of agentcore_writer. + private async Task OpenAsWriterAsync() + { + string login = "agentcore_member_" + Guid.NewGuid().ToString("n"); - await ExecuteAsync($"CREATE ROLE \"{login}\" LOGIN PASSWORD 'member' NOSUPERUSER NOCREATEDB NOCREATEROLE"); - await ExecuteAsync($"GRANT agentcore_writer TO \"{login}\""); + await ExecuteAsync($"CREATE ROLE \"{login}\" LOGIN PASSWORD 'member' NOSUPERUSER NOCREATEDB NOCREATEROLE"); + await ExecuteAsync($"GRANT agentcore_writer TO \"{login}\""); - return NpgsqlDataSource.Create( - new NpgsqlConnectionStringBuilder(Database.ConnectionString) - { - Username = login, - Password = "member", - }); - } + return NpgsqlDataSource.Create( + new NpgsqlConnectionStringBuilder(Database.ConnectionString) + { + Username = login, + Password = "member", + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTestDatabase.cs b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTestDatabase.cs index 907c7b53..7dcbf210 100644 --- a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTestDatabase.cs +++ b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTestDatabase.cs @@ -1,80 +1,81 @@ using AgentCore.Infrastructure.Database.Postgres; using Npgsql; -namespace AgentCore.Infrastructure.Tests.Database.Postgres; - -/// -/// A database of its own for one test, dropped when the test ends. -/// -/// -/// A migration is not a thing two tests can share, and neither is a hash chain: the head of one is -/// global to the table. So every test that touches either gets an empty database and takes it away -/// again. Roles are cluster-wide and outlive it, which is what the migration's create-if-absent -/// handler is for. -/// -public sealed class PostgresTestDatabase : IAsyncDisposable +namespace AgentCore.Infrastructure.Tests.Database.Postgres { - private readonly string _name; - - private PostgresTestDatabase(string name, string connectionString, NpgsqlDataSource dataSource) - { - _name = name; - ConnectionString = connectionString; - DataSource = dataSource; - } - - /// The pool that reaches the new database. - public NpgsqlDataSource DataSource { get; } - - /// The connection string, password and all. + /// + /// A database of its own for one test, dropped when the test ends. + /// /// - /// is not this: Npgsql redacts the password out of - /// it unless the string asked to persist security info, so a test that hands it to an adapter - /// hands over one that cannot log in. + /// A migration is not a thing two tests can share, and neither is a hash chain: the head of one is + /// global to the table. So every test that touches either gets an empty database and takes it away + /// again. Roles are cluster-wide and outlive it, which is what the migration's create-if-absent + /// handler is for. /// - public string ConnectionString { get; } - - /// Creates an empty database on the cluster the environment names. - /// Cancels the work. - /// The database, which the caller disposes. - public static async Task CreateAsync(CancellationToken cancellationToken) + public sealed class PostgresTestDatabase : IAsyncDisposable { - var cluster = PostgresCluster.ConnectionString - ?? throw new InvalidOperationException(PostgresCluster.SkipReason); - - var name = "agentcore_test_" + Guid.NewGuid().ToString("n"); + private readonly string _name; - await using (NpgsqlConnection admin = new(cluster)) + private PostgresTestDatabase(string name, string connectionString, NpgsqlDataSource dataSource) { - await admin.OpenAsync(cancellationToken); - await using NpgsqlCommand create = new($"CREATE DATABASE \"{name}\"", admin); - await create.ExecuteNonQueryAsync(cancellationToken); + _name = name; + ConnectionString = connectionString; + DataSource = dataSource; } - var connectionString = new NpgsqlConnectionStringBuilder(cluster) { Database = name }.ConnectionString; + /// The pool that reaches the new database. + public NpgsqlDataSource DataSource { get; } - return new PostgresTestDatabase(name, connectionString, NpgsqlDataSource.Create(connectionString)); - } + /// The connection string, password and all. + /// + /// is not this: Npgsql redacts the password out of + /// it unless the string asked to persist security info, so a test that hands it to an adapter + /// hands over one that cannot log in. + /// + public string ConnectionString { get; } - /// Creates an empty database and applies the schema to it. - /// Cancels the work. - /// The migrated database, which the caller disposes. - public static async Task CreateMigratedAsync(CancellationToken cancellationToken) - { - PostgresTestDatabase database = await CreateAsync(cancellationToken); - await PostgresSchema.ApplyAsync(database.DataSource, cancellationToken); - return database; - } + /// Creates an empty database on the cluster the environment names. + /// Cancels the work. + /// The database, which the caller disposes. + public static async Task CreateAsync(CancellationToken cancellationToken) + { + string cluster = PostgresCluster.ConnectionString + ?? throw new InvalidOperationException(PostgresCluster.SkipReason); - /// Closes the pool and drops the database. - /// A task that completes when the database is gone. - public async ValueTask DisposeAsync() - { - await DataSource.DisposeAsync(); + string name = "agentcore_test_" + Guid.NewGuid().ToString("n"); + + await using (NpgsqlConnection admin = new(cluster)) + { + await admin.OpenAsync(cancellationToken); + await using NpgsqlCommand create = new($"CREATE DATABASE \"{name}\"", admin); + _ = await create.ExecuteNonQueryAsync(cancellationToken); + } + + string connectionString = new NpgsqlConnectionStringBuilder(cluster) { Database = name }.ConnectionString; - await using NpgsqlConnection admin = new(PostgresCluster.ConnectionString); - await admin.OpenAsync(); - await using NpgsqlCommand drop = new($"DROP DATABASE IF EXISTS \"{_name}\" WITH (FORCE)", admin); - await drop.ExecuteNonQueryAsync(); + return new PostgresTestDatabase(name, connectionString, NpgsqlDataSource.Create(connectionString)); + } + + /// Creates an empty database and applies the schema to it. + /// Cancels the work. + /// The migrated database, which the caller disposes. + public static async Task CreateMigratedAsync(CancellationToken cancellationToken) + { + PostgresTestDatabase database = await CreateAsync(cancellationToken); + _ = await PostgresSchema.ApplyAsync(database.DataSource, cancellationToken); + return database; + } + + /// Closes the pool and drops the database. + /// A task that completes when the database is gone. + public async ValueTask DisposeAsync() + { + await DataSource.DisposeAsync(); + + await using NpgsqlConnection admin = new(PostgresCluster.ConnectionString); + await admin.OpenAsync(); + await using NpgsqlCommand drop = new($"DROP DATABASE IF EXISTS \"{_name}\" WITH (FORCE)", admin); + _ = await drop.ExecuteNonQueryAsync(); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTheoryAttribute.cs b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTheoryAttribute.cs index 7d95c60a..f582b61d 100644 --- a/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTheoryAttribute.cs +++ b/tests/AgentCore.Infrastructure.Tests/Database/Postgres/PostgresTheoryAttribute.cs @@ -1,22 +1,23 @@ using System.Runtime.CompilerServices; using Xunit; -namespace AgentCore.Infrastructure.Tests.Database.Postgres; - -/// A theory that needs a live PostgreSQL, and skips itself when none is named. -/// See for the variable it reads. -public sealed class PostgresTheoryAttribute : TheoryAttribute +namespace AgentCore.Infrastructure.Tests.Database.Postgres { - /// Creates the attribute. - /// Supplied by the compiler. - /// Supplied by the compiler. - public PostgresTheoryAttribute( - [CallerFilePath] string? sourceFilePath = null, - [CallerLineNumber] int sourceLineNumber = -1) - : base(sourceFilePath, sourceLineNumber) + /// A theory that needs a live PostgreSQL, and skips itself when none is named. + /// See for the variable it reads. + public sealed class PostgresTheoryAttribute : TheoryAttribute { - Skip = PostgresCluster.SkipReason; - SkipUnless = nameof(PostgresCluster.IsConfigured); - SkipType = typeof(PostgresCluster); + /// Creates the attribute. + /// Supplied by the compiler. + /// Supplied by the compiler. + public PostgresTheoryAttribute( + [CallerFilePath] string? sourceFilePath = null, + [CallerLineNumber] int sourceLineNumber = -1) + : base(sourceFilePath, sourceLineNumber) + { + Skip = PostgresCluster.SkipReason; + SkipUnless = nameof(PostgresCluster.IsConfigured); + SkipType = typeof(PostgresCluster); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Evaluation/OpenAiModeration/OpenAiModerationEvaluatorTests.cs b/tests/AgentCore.Infrastructure.Tests/Evaluation/OpenAiModeration/OpenAiModerationEvaluatorTests.cs index 27e576cd..1eb34549 100644 --- a/tests/AgentCore.Infrastructure.Tests/Evaluation/OpenAiModeration/OpenAiModerationEvaluatorTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Evaluation/OpenAiModeration/OpenAiModerationEvaluatorTests.cs @@ -12,29 +12,30 @@ using Microsoft.Extensions.AI.Evaluation; using Xunit; -namespace AgentCore.Infrastructure.Tests.Evaluation.OpenAiModeration; - -/// -/// The moderation half of the evaluation seam, over the OpenAI moderations route. -/// -/// -/// -/// Every test here reaches the network zero times. The evaluator takes its -/// from an internal constructor for exactly this reason, and the tests that build it the way a host -/// does pass and . -/// -/// -/// The rule the failure tests hold to is D9: a judge never blocks a turn. A 500, a 429, a timeout, -/// and a body that is not JSON all produce one inconclusive metric and no exception. -/// -/// -public sealed class OpenAiModerationEvaluatorTests +namespace AgentCore.Infrastructure.Tests.Evaluation.OpenAiModeration { - private const string ApiKey = "sk-test-not-a-real-key"; - private const string Reply = "Turn the machine off at the wall."; + /// + /// The moderation half of the evaluation seam, over the OpenAI moderations route. + /// + /// + /// + /// Every test here reaches the network zero times. The evaluator takes its + /// from an internal constructor for exactly this reason, and the tests that build it the way a host + /// does pass and . + /// + /// + /// The rule the failure tests hold to is D9: a judge never blocks a turn. A 500, a 429, a timeout, + /// and a body that is not JSON all produce one inconclusive metric and no exception. + /// + /// + public sealed class OpenAiModerationEvaluatorTests + { + private const string ApiKey = "sk-test-not-a-real-key"; + private const string Reply = "Turn the machine off at the wall."; - private const string Clean = - """ + private const string Clean = + /*lang=json,strict*/ + """ { "id": "modr-test", "model": "omni-moderation-latest", @@ -48,8 +49,9 @@ public sealed class OpenAiModerationEvaluatorTests } """; - private const string Flagged = - """ + private const string Flagged = + /*lang=json,strict*/ + """ { "id": "modr-test", "model": "omni-moderation-latest", @@ -81,496 +83,512 @@ public sealed class OpenAiModerationEvaluatorTests } """; - private static CancellationToken Token => TestContext.Current.CancellationToken; + private static CancellationToken Token => TestContext.Current.CancellationToken; - [Fact] - public async Task TheEvaluatorNamesOneMetric() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - var evaluator = await BuildAsync(endpoint); + [Fact] + public async Task TheEvaluatorNamesOneMetric() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); - Assert.Equal(["Content Safety"], evaluator.EvaluationMetricNames); - Assert.Equal("Content Safety", OpenAiModerationEvaluator.ContentSafetyMetricName); - } + Assert.Equal(["Content Safety"], evaluator.EvaluationMetricNames); + Assert.Equal("Content Safety", OpenAiModerationEvaluator.ContentSafetyMetricName); + } - /// - /// D13 names thirteen category flags, and this counts them. - /// - /// - /// The run-time path never indexes by this list. It enumerates whatever the endpoint returned, so - /// a fourteenth category reaches the audit chain with no code change. The list is here so the - /// vocabulary of the vendor is written down once, with its slashes and hyphens intact. - /// - [Fact] - public void TheEvaluatorNamesTheThirteenCategoriesD13Counts() - => Assert.Equal( - [ - "harassment", - "harassment/threatening", - "hate", - "hate/threatening", - "illicit", - "illicit/violent", - "self-harm", - "self-harm/instructions", - "self-harm/intent", - "sexual", - "sexual/minors", - "violence", - "violence/graphic", - ], - OpenAiModerationEvaluator.Categories); - - [Fact] - public async Task ItPostsTheTextToTheModerationsRouteWithTheOmniModel() - { - List bodies = []; - using var endpoint = Answering(bodies, HttpStatusCode.OK, Clean); - var evaluator = await BuildAsync(endpoint); + /// + /// D13 names thirteen category flags, and this counts them. + /// + /// + /// The run-time path never indexes by this list. It enumerates whatever the endpoint returned, so + /// a fourteenth category reaches the audit chain with no code change. The list is here so the + /// vocabulary of the vendor is written down once, with its slashes and hyphens intact. + /// + [Fact] + public void TheEvaluatorNamesTheThirteenCategoriesD13Counts() + { + Assert.Equal( + [ + "harassment", + "harassment/threatening", + "hate", + "hate/threatening", + "illicit", + "illicit/violent", + "self-harm", + "self-harm/instructions", + "self-harm/intent", + "sexual", + "sexual/minors", + "violence", + "violence/graphic", + ], + OpenAiModerationEvaluator.Categories); + } - await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); + [Fact] + public async Task ItPostsTheTextToTheModerationsRouteWithTheOmniModel() + { + List bodies = []; + using StubHttpMessageHandler endpoint = Answering(bodies, HttpStatusCode.OK, Clean); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); - var request = Assert.Single(endpoint.Requests); - Assert.Equal(HttpMethod.Post, request.Method); - Assert.Equal("https://api.openai.com", request.RequestUri!.GetLeftPart(UriPartial.Authority)); - Assert.Equal("/v1/moderations", request.RequestUri.AbsolutePath); + _ = await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); - using var body = JsonDocument.Parse(Assert.Single(bodies)); - Assert.Equal("omni-moderation-latest", body.RootElement.GetProperty("model").GetString()); - Assert.Equal(Reply, body.RootElement.GetProperty("input").GetString()); + HttpRequestMessage request = Assert.Single(endpoint.Requests); + Assert.Equal(HttpMethod.Post, request.Method); + Assert.Equal("https://api.openai.com", request.RequestUri!.GetLeftPart(UriPartial.Authority)); + Assert.Equal("/v1/moderations", request.RequestUri.AbsolutePath); - // One string, and no second field. D13 asks for one POST and nothing beside it. - Assert.Equal(2, body.RootElement.EnumerateObject().Count()); - } + using JsonDocument body = JsonDocument.Parse(Assert.Single(bodies)); + Assert.Equal("omni-moderation-latest", body.RootElement.GetProperty("model").GetString()); + Assert.Equal(Reply, body.RootElement.GetProperty("input").GetString()); - [Fact] - public async Task ACleanTextPassesAndCarriesAVerdictWithNoCategory() - { - var result = await EvaluateAsync(Clean); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - - Assert.True(metric.Value); - Assert.Equal(EvaluationRating.Exceptional, metric.Interpretation!.Rating); - Assert.False(metric.Interpretation.Failed); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.False(verdict!.Flagged); - Assert.Empty(verdict.Categories); - } + // One string, and no second field. D13 asks for one POST and nothing beside it. + Assert.Equal(2, body.RootElement.EnumerateObject().Count()); + } - [Fact] - public async Task AFlaggedTextFailsAndNamesEveryFlaggedCategory() - { - var result = await EvaluateAsync(Flagged); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - - Assert.False(metric.Value); - Assert.Equal(EvaluationRating.Unacceptable, metric.Interpretation!.Rating); - Assert.True(metric.Interpretation.Failed); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.True(verdict!.Flagged); - Assert.Equal(["harassment", "harassment/threatening", "violence"], verdict.Categories); - } + [Fact] + public async Task ACleanTextPassesAndCarriesAVerdictWithNoCategory() + { + EvaluationResult result = await EvaluateAsync(Clean); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + + Assert.True(metric.Value); + Assert.Equal(EvaluationRating.Exceptional, metric.Interpretation!.Rating); + Assert.False(metric.Interpretation.Failed); + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.False(verdict!.Flagged); + Assert.Empty(verdict.Categories); + } - /// - /// The categories keep the order the endpoint returned them in. - /// - /// - /// AuditPayloadKeys.ModerationCategories promises that order to a reader of the audit - /// chain, so the reader enumerates the JSON object and sorts nothing. - /// - [Fact] - public async Task TheVerdictKeepsTheOrderTheEndpointReturned() - { - var result = await EvaluateAsync( - """ + [Fact] + public async Task AFlaggedTextFailsAndNamesEveryFlaggedCategory() + { + EvaluationResult result = await EvaluateAsync(Flagged); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + + Assert.False(metric.Value); + Assert.Equal(EvaluationRating.Unacceptable, metric.Interpretation!.Rating); + Assert.True(metric.Interpretation.Failed); + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.True(verdict!.Flagged); + Assert.Equal(["harassment", "harassment/threatening", "violence"], verdict.Categories); + } + + /// + /// The categories keep the order the endpoint returned them in. + /// + /// + /// AuditPayloadKeys.ModerationCategories promises that order to a reader of the audit + /// chain, so the reader enumerates the JSON object and sorts nothing. + /// + [Fact] + public async Task TheVerdictKeepsTheOrderTheEndpointReturned() + { + EvaluationResult result = await EvaluateAsync( + /*lang=json,strict*/ + """ { "results": [ { "flagged": true, "categories": { "violence": true, "harassment": true } } ] } """); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.Equal(["violence", "harassment"], verdict!.Categories); - } + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.Equal(["violence", "harassment"], verdict!.Categories); + } - /// - /// The wire types illicit and illicit/violent as nullable, and a null is not a flag. - /// - /// - /// A reader that calls GetBoolean() on those two keys throws on a body OpenAI is allowed to - /// send. This reader tests for JsonValueKind.True and treats every other kind as not - /// flagged. - /// - [Fact] - public async Task ANullIllicitFlagIsNotAFlag() - { - var result = await EvaluateAsync( - """ + /// + /// The wire types illicit and illicit/violent as nullable, and a null is not a flag. + /// + /// + /// A reader that calls GetBoolean() on those two keys throws on a body OpenAI is allowed to + /// send. This reader tests for JsonValueKind.True and treats every other kind as not + /// flagged. + /// + [Fact] + public async Task ANullIllicitFlagIsNotAFlag() + { + EvaluationResult result = await EvaluateAsync( + /*lang=json,strict*/ + """ { "results": [ { "flagged": false, "categories": { "illicit": null, "illicit/violent": null } } ] } """); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - Assert.True(metric.Value); - Assert.Null(metric.Diagnostics); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.Empty(verdict!.Categories); - } + Assert.True(metric.Value); + Assert.Null(metric.Diagnostics); + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.Empty(verdict!.Categories); + } - [Fact] - public async Task AnUnknownCategoryIsRecordedRatherThanDropped() - { - var result = await EvaluateAsync( - """ + [Fact] + public async Task AnUnknownCategoryIsRecordedRatherThanDropped() + { + EvaluationResult result = await EvaluateAsync( + /*lang=json,strict*/ + """ { "results": [ { "flagged": true, "categories": { "political/extremism": true } } ] } """); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.Equal(["political/extremism"], verdict!.Categories); - } + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.Equal(["political/extremism"], verdict!.Categories); + } - /// - /// The endpoint owns the verdict, and this reader never recomputes it from the flags. - /// - /// - /// Recomputing would drift the day OpenAI moves a threshold, and a model that flags without - /// naming a category would then read as clean. - /// - [Fact] - public async Task ItReadsTheEndpointVerdictAndDoesNotRecomputeIt() - { - var result = await EvaluateAsync( - """ + /// + /// The endpoint owns the verdict, and this reader never recomputes it from the flags. + /// + /// + /// Recomputing would drift the day OpenAI moves a threshold, and a model that flags without + /// naming a category would then read as clean. + /// + [Fact] + public async Task ItReadsTheEndpointVerdictAndDoesNotRecomputeIt() + { + EvaluationResult result = await EvaluateAsync( + /*lang=json,strict*/ + """ { "results": [ { "flagged": true, "categories": { "harassment": false, "violence": false } } ] } """); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - - Assert.False(metric.Value); - Assert.True(metric.Interpretation!.Failed); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.True(verdict!.Flagged); - Assert.Empty(verdict.Categories); - } - - [Fact] - public async Task TheFlaggedCategoryScoresReachTheMetadata() - { - var result = await EvaluateAsync(Flagged); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - - Assert.NotNull(metric.Metadata); - Assert.Equal("omni-moderation-latest", metric.Metadata["model"]); - Assert.Equal("0.9971", metric.Metadata["violence"]); - Assert.Equal("0.5216", metric.Metadata["harassment"]); - - // A category the endpoint did not flag carries no score, because nothing reads it. - Assert.False(metric.Metadata.ContainsKey("hate")); - } + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - [Fact] - public async Task AnEmptyTextCostsNoRequestAndPasses() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - var evaluator = await BuildAsync(endpoint); - - var result = await evaluator.EvaluateAsync([], Response(" "), cancellationToken: Token); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - - Assert.Empty(endpoint.Requests); - Assert.True(metric.Value); - Assert.False(metric.Interpretation!.Failed); - Assert.True(ModerationVerdict.TryRead(result, out var verdict)); - Assert.False(verdict!.Flagged); - Assert.Empty(verdict.Categories); - } + Assert.False(metric.Value); + Assert.True(metric.Interpretation!.Failed); + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.True(verdict!.Flagged); + Assert.Empty(verdict.Categories); + } - /// - /// A vendor outage is inconclusive, and it is never an exception. - /// - /// - /// D9 says a judge must never block a turn, and moderation runs on every turn. A throw would make - /// an OpenAI outage a caller-facing failure. No verdict is attached, so the caller reads - /// "unchecked" and not "checked and clean". - /// - [Fact] - public async Task AFailedRequestIsInconclusiveAndNeverThrows() - { - var result = await EvaluateAsync(HttpStatusCode.InternalServerError, "{}"); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.False(metric.Interpretation.Failed); - Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); - Assert.False(ModerationVerdict.TryRead(result, out var verdict)); - Assert.Null(verdict); - } + [Fact] + public async Task TheFlaggedCategoryScoresReachTheMetadata() + { + EvaluationResult result = await EvaluateAsync(Flagged); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - [Fact] - public async Task ARateLimitIsInconclusiveAndNamesTheStatus() - { - var result = await EvaluateAsync(HttpStatusCode.TooManyRequests, "{}"); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + Assert.NotNull(metric.Metadata); + Assert.Equal("omni-moderation-latest", metric.Metadata["model"]); + Assert.Equal("0.9971", metric.Metadata["violence"]); + Assert.Equal("0.5216", metric.Metadata["harassment"]); - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.False(metric.Interpretation.Failed); + // A category the endpoint did not flag carries no score, because nothing reads it. + Assert.False(metric.Metadata.ContainsKey("hate")); + } - var diagnostic = Assert.Single(metric.Diagnostics!); - Assert.Equal(EvaluationDiagnosticSeverity.Error, diagnostic.Severity); - Assert.Contains("429", diagnostic.Message, StringComparison.Ordinal); - } + [Fact] + public async Task AnEmptyTextCostsNoRequestAndPasses() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); + + EvaluationResult result = await evaluator.EvaluateAsync([], Response(" "), cancellationToken: Token); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + + Assert.Empty(endpoint.Requests); + Assert.True(metric.Value); + Assert.False(metric.Interpretation!.Failed); + Assert.True(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.False(verdict!.Flagged); + Assert.Empty(verdict.Categories); + } - [Fact] - public async Task ATimeoutIsInconclusiveAndNeverThrows() - { - using var endpoint = StubHttpMessageHandler.TimingOut(); - var evaluator = await BuildAsync(endpoint); + /// + /// A vendor outage is inconclusive, and it is never an exception. + /// + /// + /// D9 says a judge must never block a turn, and moderation runs on every turn. A throw would make + /// an OpenAI outage a caller-facing failure. No verdict is attached, so the caller reads + /// "unchecked" and not "checked and clean". + /// + [Fact] + public async Task AFailedRequestIsInconclusiveAndNeverThrows() + { + EvaluationResult result = await EvaluateAsync(HttpStatusCode.InternalServerError, "{}"); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.False(metric.Interpretation.Failed); + Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); + Assert.False(ModerationVerdict.TryRead(result, out ModerationVerdict? verdict)); + Assert.Null(verdict); + } - var result = await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + [Fact] + public async Task ARateLimitIsInconclusiveAndNamesTheStatus() + { + EvaluationResult result = await EvaluateAsync(HttpStatusCode.TooManyRequests, "{}"); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.False(metric.Interpretation.Failed); - Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); - Assert.False(ModerationVerdict.TryRead(result, out _)); - } + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.False(metric.Interpretation.Failed); - [Fact] - public async Task ABodyThatIsNotJsonIsInconclusive() - { - var result = await EvaluateAsync("not json"); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + EvaluationDiagnostic diagnostic = Assert.Single(metric.Diagnostics!); + Assert.Equal(EvaluationDiagnosticSeverity.Error, diagnostic.Severity); + Assert.Contains("429", diagnostic.Message, StringComparison.Ordinal); + } - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); - Assert.False(ModerationVerdict.TryRead(result, out _)); - } + [Fact] + public async Task ATimeoutIsInconclusiveAndNeverThrows() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.TimingOut(); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); - [Fact] - public async Task AnEmptyResultsArrayIsInconclusive() - { - var result = await EvaluateAsync("""{ "results": [] }"""); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + EvaluationResult result = await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); - Assert.False(ModerationVerdict.TryRead(result, out _)); - } + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.False(metric.Interpretation.Failed); + Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); + Assert.False(ModerationVerdict.TryRead(result, out _)); + } - [Fact] - public async Task AResultWithNoFlaggedFieldIsInconclusive() - { - var result = await EvaluateAsync("""{ "results": [ { "categories": { "hate": true } } ] }"""); - var metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); + [Fact] + public async Task ABodyThatIsNotJsonIsInconclusive() + { + EvaluationResult result = await EvaluateAsync("not json"); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - Assert.Null(metric.Value); - Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); - Assert.False(ModerationVerdict.TryRead(result, out _)); - } + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); + Assert.False(ModerationVerdict.TryRead(result, out _)); + } - /// - /// A cancel is the decision of the caller, and it is not a vendor failure. - /// - /// - /// The evaluator tells a deadline from a cancel by testing the token inside the exception filter, - /// so a timeout becomes a diagnostic and this stays an exception. - /// - [Fact] - public async Task ACallerCancelStillThrows() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - var evaluator = await BuildAsync(endpoint); - - await Assert.ThrowsAnyAsync( - async () => await evaluator.EvaluateAsync( - [], - Response(Reply), - cancellationToken: new CancellationToken(canceled: true))); - } + [Fact] + public async Task AnEmptyResultsArrayIsInconclusive() + { + EvaluationResult result = await EvaluateAsync(/*lang=json,strict*/ """{ "results": [] }"""); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - [Fact] - public async Task ANullResponseIsRefused() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - var evaluator = await BuildAsync(endpoint); + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.Equal(EvaluationDiagnosticSeverity.Error, Assert.Single(metric.Diagnostics!).Severity); + Assert.False(ModerationVerdict.TryRead(result, out _)); + } - await Assert.ThrowsAsync( - async () => await evaluator.EvaluateAsync([], null!, cancellationToken: Token)); - } + [Fact] + public async Task AResultWithNoFlaggedFieldIsInconclusive() + { + EvaluationResult result = await EvaluateAsync(/*lang=json,strict*/ """{ "results": [ { "categories": { "hate": true } } ] }"""); + BooleanMetric metric = result.Get(OpenAiModerationEvaluator.ContentSafetyMetricName); - /// - /// The build opens the named client on the pipeline of the host, and reads the shared OpenAI key. - /// - /// - /// D13 says one key serves all four OpenAI conversations, so this adapter declares no name of its own and - /// asks for the constant OpenAiChatClientAdapter owns. - /// - [Fact] - public async Task CreateAsyncOpensTheNamedClientAndReadsTheSharedOpenAiSecret() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - StubHandlerFactory pipeline = new(endpoint); - MapSecretResolver resolver = new(); - resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); + Assert.Null(metric.Value); + Assert.Equal(EvaluationRating.Inconclusive, metric.Interpretation!.Rating); + Assert.False(ModerationVerdict.TryRead(result, out _)); + } - var evaluator = await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); - await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); + /// + /// A cancel is the decision of the caller, and it is not a vendor failure. + /// + /// + /// The evaluator tells a deadline from a cancel by testing the token inside the exception filter, + /// so a timeout becomes a diagnostic and this stays an exception. + /// + [Fact] + public async Task ACallerCancelStillThrows() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); + + _ = await Assert.ThrowsAnyAsync( + async () => await evaluator.EvaluateAsync( + [], + Response(Reply), + cancellationToken: new CancellationToken(canceled: true))); + } - Assert.Equal(["agentcore.openai.moderation"], pipeline.Names); - Assert.Equal([OpenAiChatClientAdapter.ApiKeySecretName], resolver.Asked); - Assert.Equal("Bearer " + ApiKey, Assert.Single(endpoint.Requests).Headers.Authorization!.ToString()); - } + [Fact] + public async Task ANullResponseIsRefused() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); - [Fact] - public async Task CreateAsyncFallsBackToTheEnvironmentVariable() - { - var saved = Environment.GetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName); - Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, ApiKey); + _ = await Assert.ThrowsAsync( + async () => await evaluator.EvaluateAsync([], null!, cancellationToken: Token)); + } - try + /// + /// The build opens the named client on the pipeline of the host, and reads the shared OpenAI key. + /// + /// + /// D13 says one key serves all four OpenAI conversations, so this adapter declares no name of its own and + /// asks for the constant OpenAiChatClientAdapter owns. + /// + [Fact] + public async Task CreateAsyncOpensTheNamedClientAndReadsTheSharedOpenAiSecret() { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); StubHandlerFactory pipeline = new(endpoint); MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); - var evaluator = await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); - await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); + OpenAiModerationEvaluator evaluator = await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); + _ = await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); - // The chain is asked first, and the variable answers only when the chain holds nothing. + Assert.Equal(["agentcore.openai.moderation"], pipeline.Names); Assert.Equal([OpenAiChatClientAdapter.ApiKeySecretName], resolver.Asked); Assert.Equal("Bearer " + ApiKey, Assert.Single(endpoint.Requests).Headers.Authorization!.ToString()); } - finally + + [Fact] + public async Task CreateAsyncFallsBackToTheEnvironmentVariable() { - Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, saved); - } - } + string? saved = Environment.GetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName); + Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, ApiKey); - [Fact] - public async Task CreateAsyncRefusesToBuildWithNoKeyAnywhere() - { - var saved = Environment.GetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName); - Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, null); + try + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + StubHandlerFactory pipeline = new(endpoint); + MapSecretResolver resolver = new(); + + OpenAiModerationEvaluator evaluator = await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); + _ = await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); - try + // The chain is asked first, and the variable answers only when the chain holds nothing. + Assert.Equal([OpenAiChatClientAdapter.ApiKeySecretName], resolver.Asked); + Assert.Equal("Bearer " + ApiKey, Assert.Single(endpoint.Requests).Headers.Authorization!.ToString()); + } + finally + { + Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, saved); + } + } + + [Fact] + public async Task CreateAsyncRefusesToBuildWithNoKeyAnywhere() { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - StubHandlerFactory pipeline = new(endpoint); + string? saved = Environment.GetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName); + Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, null); - var failure = await Assert.ThrowsAsync( - async () => await OpenAiModerationEvaluator.CreateAsync(pipeline, new MapSecretResolver(), Token)); + try + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + StubHandlerFactory pipeline = new(endpoint); + + SecretResolutionException failure = await Assert.ThrowsAsync( + async () => await OpenAiModerationEvaluator.CreateAsync(pipeline, new MapSecretResolver(), Token)); - Assert.Contains(OpenAiChatClientAdapter.ApiKeySecretName, failure.Message, StringComparison.Ordinal); - Assert.Contains(OpenAiChatClientAdapter.ApiKeyVariableName, failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain(ApiKey, failure.Message, StringComparison.Ordinal); + Assert.Contains(OpenAiChatClientAdapter.ApiKeySecretName, failure.Message, StringComparison.Ordinal); + Assert.Contains(OpenAiChatClientAdapter.ApiKeyVariableName, failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain(ApiKey, failure.Message, StringComparison.Ordinal); + } + finally + { + Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, saved); + } } - finally + + [Fact] + public async Task CreateAsyncRefusesAPipelineThatIsNothing() { - Environment.SetEnvironmentVariable(OpenAiChatClientAdapter.ApiKeyVariableName, saved); + _ = await Assert.ThrowsAsync( + async () => await OpenAiModerationEvaluator.CreateAsync(null!, new MapSecretResolver(), Token)); } - } - - [Fact] - public async Task CreateAsyncRefusesAPipelineThatIsNothing() - => await Assert.ThrowsAsync( - async () => await OpenAiModerationEvaluator.CreateAsync(null!, new MapSecretResolver(), Token)); - [Fact] - public async Task CreateAsyncOpensNoSocket() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - StubHandlerFactory pipeline = new(endpoint); - MapSecretResolver resolver = new(); - resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); + [Fact] + public async Task CreateAsyncOpensNoSocket() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + StubHandlerFactory pipeline = new(endpoint); + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); - _ = await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); + _ = await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); - // A host with no route to api.openai.com still starts. The first turn is the first request. - Assert.Empty(endpoint.Requests); - } + // A host with no route to api.openai.com still starts. The first turn is the first request. + Assert.Empty(endpoint.Requests); + } - /// - /// The moderation conversation gives the turn back, rather than holding it for the default 100 seconds. - /// - [Fact] - public async Task TheDeadlineIsShorterThanTheShippedDefault() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); - MapSecretResolver resolver = new(); - resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); + /// + /// The moderation conversation gives the turn back, rather than holding it for the default 100 seconds. + /// + [Fact] + public async Task TheDeadlineIsShorterThanTheShippedDefault() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.OK, Clean); + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); - var evaluator = await OpenAiModerationEvaluator.CreateAsync( - new StubHandlerFactory(endpoint), - resolver, - Token); + OpenAiModerationEvaluator evaluator = await OpenAiModerationEvaluator.CreateAsync( + new StubHandlerFactory(endpoint), + resolver, + Token); - Assert.Equal(OpenAiModerationEvaluator.ModerationDeadline, evaluator.Deadline); - Assert.True(OpenAiModerationEvaluator.ModerationDeadline < TimeSpan.FromSeconds(100)); - } + Assert.Equal(OpenAiModerationEvaluator.ModerationDeadline, evaluator.Deadline); + Assert.True(OpenAiModerationEvaluator.ModerationDeadline < TimeSpan.FromSeconds(100)); + } - /// - /// Every request lands on the injected exactly once, and the SDK's own - /// retry loop never adds a second attempt of its own on top of it. - /// - /// - /// AgentCoreHttpClients is the one place D13 gives retry to. A vendor SDK that retried on - /// top of that pipeline would multiply the vendor's load and, because each of its own retries gets - /// a fresh deadline budget, could stretch a single check well past - /// . This count is the proof that - /// OpenAIClientOptions.RetryPolicy is turned off, for an error status the endpoint itself - /// answered with. - /// - [Fact] - public async Task ARequestReachesTheInjectedHttpClientExactlyOnceEvenOnAFailure() - { - using var endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.TooManyRequests, "{}"); - var evaluator = await BuildAsync(endpoint); + /// + /// Every request lands on the injected exactly once, and the SDK's own + /// retry loop never adds a second attempt of its own on top of it. + /// + /// + /// AgentCoreHttpClients is the one place D13 gives retry to. A vendor SDK that retried on + /// top of that pipeline would multiply the vendor's load and, because each of its own retries gets + /// a fresh deadline budget, could stretch a single check well past + /// . This count is the proof that + /// OpenAIClientOptions.RetryPolicy is turned off, for an error status the endpoint itself + /// answered with. + /// + [Fact] + public async Task ARequestReachesTheInjectedHttpClientExactlyOnceEvenOnAFailure() + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(HttpStatusCode.TooManyRequests, "{}"); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); - await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); + _ = await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); - Assert.Single(endpoint.Requests); - } + _ = Assert.Single(endpoint.Requests); + } - private static ChatResponse Response(string text) => new(new ChatMessage(ChatRole.Assistant, text)); + private static ChatResponse Response(string text) + { + return new(new ChatMessage(ChatRole.Assistant, text)); + } - /// Builds the evaluator the way a host does, over a stub in place of the network. - /// - /// The evaluator takes its from an internal - /// constructor for exactly this reason: every test reaches the network zero times, and this is - /// the one place that trades an for one. - /// - private static async Task BuildAsync(HttpMessageHandler handler) - { - StubHandlerFactory pipeline = new(handler); - MapSecretResolver resolver = new(); - resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); + /// Builds the evaluator the way a host does, over a stub in place of the network. + /// + /// The evaluator takes its from an internal + /// constructor for exactly this reason: every test reaches the network zero times, and this is + /// the one place that trades an for one. + /// + private static async Task BuildAsync(HttpMessageHandler handler) + { + StubHandlerFactory pipeline = new(handler); + MapSecretResolver resolver = new(); + _ = resolver.With(OpenAiChatClientAdapter.ApiKeySecretName, ApiKey); - return await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); - } + return await OpenAiModerationEvaluator.CreateAsync(pipeline, resolver, Token); + } - private static ValueTask EvaluateAsync(string body) - => EvaluateAsync(HttpStatusCode.OK, body); + private static ValueTask EvaluateAsync(string body) + { + return EvaluateAsync(HttpStatusCode.OK, body); + } - private static async ValueTask EvaluateAsync(HttpStatusCode status, string body) - { - using var endpoint = StubHttpMessageHandler.Answering(status, body); - var evaluator = await BuildAsync(endpoint); + private static async ValueTask EvaluateAsync(HttpStatusCode status, string body) + { + using StubHttpMessageHandler endpoint = StubHttpMessageHandler.Answering(status, body); + OpenAiModerationEvaluator evaluator = await BuildAsync(endpoint); - return await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); - } + return await evaluator.EvaluateAsync([], Response(Reply), cancellationToken: Token); + } - private static StubHttpMessageHandler Answering(List bodies, HttpStatusCode status, string answer) - => new(request => + private static StubHttpMessageHandler Answering(List bodies, HttpStatusCode status, string answer) { - bodies.Add(request.Content is null - ? string.Empty - : request.Content.ReadAsStringAsync(CancellationToken.None).GetAwaiter().GetResult()); - - return new HttpResponseMessage(status) - { - Content = new StringContent(answer, Encoding.UTF8, "application/json"), - }; - }); + return new(request => + { + bodies.Add(request.Content is null + ? string.Empty + : request.Content.ReadAsStringAsync(CancellationToken.None).GetAwaiter().GetResult()); + + return new HttpResponseMessage(status) + { + Content = new StringContent(answer, Encoding.UTF8, "application/json"), + }; + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Fakes/FakeEmbeddingGenerator.cs b/tests/AgentCore.Infrastructure.Tests/Fakes/FakeEmbeddingGenerator.cs index e8e34d1c..af4e5c85 100644 --- a/tests/AgentCore.Infrastructure.Tests/Fakes/FakeEmbeddingGenerator.cs +++ b/tests/AgentCore.Infrastructure.Tests/Fakes/FakeEmbeddingGenerator.cs @@ -1,46 +1,48 @@ using Microsoft.Extensions.AI; -namespace AgentCore.Infrastructure.Tests.Fakes; - -/// -/// An embedding generator that answers one fixed vector, so a test reaches no OpenAI endpoint. -/// -/// -/// QdrantKnowledgeStore and QdrantKnowledgeAdapter both take their generator from a -/// constructor for exactly this reason: the store embeds every query and the adapter embeds one probe -/// at startup, and neither should mean an OpenAI key to run a test. The vector is fixed, so a test's -/// ranking is decided by the corpus it wrote and by nothing else. -/// -internal sealed class FakeEmbeddingGenerator : IEmbeddingGenerator> +namespace AgentCore.Infrastructure.Tests.Fakes { - private readonly float[] _vector; + /// + /// An embedding generator that answers one fixed vector, so a test reaches no OpenAI endpoint. + /// + /// + /// QdrantKnowledgeStore and QdrantKnowledgeAdapter both take their generator from a + /// constructor for exactly this reason: the store embeds every query and the adapter embeds one probe + /// at startup, and neither should mean an OpenAI key to run a test. The vector is fixed, so a test's + /// ranking is decided by the corpus it wrote and by nothing else. + /// + internal sealed class FakeEmbeddingGenerator(params float[] vector) : IEmbeddingGenerator> + { + private readonly float[] _vector = vector; - public FakeEmbeddingGenerator(params float[] vector) => _vector = vector; + /// Gets every value this generator was asked to embed, in call order. + public List Inputs { get; } = []; - /// Gets every value this generator was asked to embed, in call order. - public List Inputs { get; } = []; + public Task>> GenerateAsync( + IEnumerable values, + EmbeddingGenerationOptions? options = null, + CancellationToken cancellationToken = default) + { + cancellationToken.ThrowIfCancellationRequested(); - public Task>> GenerateAsync( - IEnumerable values, - EmbeddingGenerationOptions? options = null, - CancellationToken cancellationToken = default) - { - cancellationToken.ThrowIfCancellationRequested(); + GeneratedEmbeddings> embeddings = []; + foreach (string value in values) + { + Inputs.Add(value); + embeddings.Add(new Embedding(_vector)); + } - GeneratedEmbeddings> embeddings = []; - foreach (var value in values) - { - Inputs.Add(value); - embeddings.Add(new Embedding(_vector)); + return Task.FromResult(embeddings); } - return Task.FromResult(embeddings); - } - - public object? GetService(Type serviceType, object? serviceKey = null) => null; + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } - public void Dispose() - { - // Nothing to release. + public void Dispose() + { + // Nothing to release. + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Fakes/StubHandlerFactory.cs b/tests/AgentCore.Infrastructure.Tests/Fakes/StubHandlerFactory.cs index 4a53d025..ee5eac69 100644 --- a/tests/AgentCore.Infrastructure.Tests/Fakes/StubHandlerFactory.cs +++ b/tests/AgentCore.Infrastructure.Tests/Fakes/StubHandlerFactory.cs @@ -1,25 +1,24 @@ -namespace AgentCore.Infrastructure.Tests.Fakes; - -/// -/// An offline pipeline that hands out one handler, and records every name it is asked for. -/// -/// -/// A host passes AgentCoreHttpClients here, which is where the connection lifetime, the -/// deadline, and the retry live. A test passes this, so an adapter reaches no network and the -/// recorded names prove which client an adapter opens. -/// -internal sealed class StubHandlerFactory : IHttpMessageHandlerFactory +namespace AgentCore.Infrastructure.Tests.Fakes { - private readonly HttpMessageHandler _handler; - - public StubHandlerFactory(HttpMessageHandler handler) => _handler = handler; + /// + /// An offline pipeline that hands out one handler, and records every name it is asked for. + /// + /// + /// A host passes AgentCoreHttpClients here, which is where the connection lifetime, the + /// deadline, and the retry live. A test passes this, so an adapter reaches no network and the + /// recorded names prove which client an adapter opens. + /// + internal sealed class StubHandlerFactory(HttpMessageHandler handler) : IHttpMessageHandlerFactory + { + private readonly HttpMessageHandler _handler = handler; - /// Gets every client name this factory was asked for, in call order. - public List Names { get; } = []; + /// Gets every client name this factory was asked for, in call order. + public List Names { get; } = []; - public HttpMessageHandler CreateHandler(string name) - { - Names.Add(name); - return _handler; + public HttpMessageHandler CreateHandler(string name) + { + Names.Add(name); + return _handler; + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs index 6cacf1e4..6e2db7cc 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs @@ -4,6 +4,7 @@ using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; +using AgentCore.Application.State; using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; @@ -14,175 +15,179 @@ using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// Section 12's "probe -- against real Qdrant" list. -/// -/// , and -/// are internal to AgentCore.Application, and this project carries no grant to reach them. Every -/// row here is instead driven through the same seam a production host uses: a real YAML document -/// compiled by with a real handed -/// in as , and a real turn. The -/// turn's own "reply" model is a fake that calls the compiled agent's own Search tool with the -/// row's question, the way a model that needs the cards would; the framework's own tool-calling loop -/// then runs the real search with the running turn. Reading the tool's answer back off the transcript -/// is what keeps every row on the production path: the loop's own flow is only entered around -/// ConversationSession's call into the reply model. -/// -/// -/// The store fuses a plain dense leg with a required-term leg by RRF (K49's amendment): a card the -/// required-term leg does not match can still surface through the dense leg alone, and -/// QdrantKnowledgeStoreTests.SearchAsync_LookalikeIdentifier_RanksTheIdentifierCardFirst already -/// pins that a matching identifier only lifts a card to the top rank, never excludes a non-matching -/// one. A required-term token therefore cannot isolate a single card from the shared corpus by itself; -/// the row that needs exactly one card (the two-machine card) combines a distinctive token with a -/// store Limit of 1, so only the fused winner survives. Every row that needs a card population -/// this shared fixture must not carry for every other row -- the company-wide card, the one-machine -/// multi-card union, and the empty-search row -- builds and drops its own small collection instead. -/// -/// -public sealed class AmbiguityCorpusFixture : IAsyncLifetime +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// The id of the added card whose facets.model names two machines. - public const string MultiMachineCardId = "syn-multi"; + /// + /// Section 12's "probe -- against real Qdrant" list. + /// + /// , and + /// are internal to AgentCore.Application, and this project carries no grant to reach them. Every + /// row here is instead driven through the same seam a production host uses: a real YAML document + /// compiled by with a real handed + /// in as , and a real turn. The + /// turn's own "reply" model is a fake that calls the compiled agent's own Search tool with the + /// row's question, the way a model that needs the cards would; the framework's own tool-calling loop + /// then runs the real search with the running turn. Reading the tool's answer back off the transcript + /// is what keeps every row on the production path: the loop's own flow is only entered around + /// ConversationSession's call into the reply model. + /// + /// + /// The store fuses a plain dense leg with a required-term leg by RRF (K49's amendment): a card the + /// required-term leg does not match can still surface through the dense leg alone, and + /// QdrantKnowledgeStoreTests.SearchAsync_LookalikeIdentifier_RanksTheIdentifierCardFirst already + /// pins that a matching identifier only lifts a card to the top rank, never excludes a non-matching + /// one. A required-term token therefore cannot isolate a single card from the shared corpus by itself; + /// the row that needs exactly one card (the two-machine card) combines a distinctive token with a + /// store Limit of 1, so only the fused winner survives. Every row that needs a card population + /// this shared fixture must not carry for every other row -- the company-wide card, the one-machine + /// multi-card union, and the empty-search row -- builds and drops its own small collection instead. + /// + /// + public sealed class AmbiguityCorpusFixture : IAsyncLifetime + { + /// The id of the added card whose facets.model names two machines. + public const string MultiMachineCardId = "syn-multi"; - /// The required-term token that reaches only . - public const string MultiMachineToken = "e77"; + /// The required-term token that reaches only . + public const string MultiMachineToken = "e77"; - /// A required-term token no card in this corpus carries. - public const string NothingToken = "e99"; + /// A required-term token no card in this corpus carries. + public const string NothingToken = "e99"; - /// The two machines names, in the order the note must join them. - public static readonly string[] MultiMachineModels = ["ct900", "ctsbs900"]; + /// The two machines names, in the order the note must join them. + public static readonly string[] MultiMachineModels = ["ct900", "ctsbs900"]; - /// The value every card here carries at facets.audience, so a second scope facet always resolves. - public const string Audience = "everyone"; + /// The value every card here carries at facets.audience, so a second scope facet always resolves. + public const string Audience = "everyone"; - public string Name { get; } = $"ambiguity-probe-{Guid.NewGuid():N}"; + public string Name { get; } = $"ambiguity-probe-{Guid.NewGuid():N}"; - public QdrantClient Client { get; private set; } = null!; + public QdrantClient Client { get; private set; } = null!; - public async ValueTask InitializeAsync() - { - if (!QdrantServer.IsConfigured) + public async ValueTask InitializeAsync() { - return; - } - - Client = QdrantServer.CreateClient(); - - // The 30-card synthetic corpus, unmodified, plus the multi-machine card the brief conversations for. - // Composing with KbShapedCorpus rather than inventing a second one: A4's own facet-read tests - // already proved this corpus's payload shape works, and a wrong facet path is this design's - // own central failure mode (section 12), so reusing the shape that is already proven is the - // point. The "*" card lives in its own throwaway collection instead (see - // CompanyWideQuestion_ExactlyOneMatchingCard_Answers_ProbeDoesNotRun): giving every card here - // model: "*" would make it the only card any scope: { model: "*" } search could ever find, - // which is exactly the row this shared fixture must not answer for every other one. - await KbShapedCorpus.CreateAsync(Client, Name, interleaved: true, TestContext.Current.CancellationToken); + if (!QdrantServer.IsConfigured) + { + return; + } - await Client.CreatePayloadIndexAsync( - Name, "facets.audience", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); + Client = QdrantServer.CreateClient(); + + // The 30-card synthetic corpus, unmodified, plus the multi-machine card the brief conversations for. + // Composing with KbShapedCorpus rather than inventing a second one: A4's own facet-read tests + // already proved this corpus's payload shape works, and a wrong facet path is this design's + // own central failure mode (section 12), so reusing the shape that is already proven is the + // point. The "*" card lives in its own throwaway collection instead (see + // CompanyWideQuestion_ExactlyOneMatchingCard_Answers_ProbeDoesNotRun): giving every card here + // model: "*" would make it the only card any scope: { model: "*" } search could ever find, + // which is exactly the row this shared fixture must not answer for every other one. + await KbShapedCorpus.CreateAsync(Client, Name, interleaved: true, TestContext.Current.CancellationToken); + + _ = await Client.CreatePayloadIndexAsync( + Name, "facets.audience", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); + + PointStruct[] added = + [ + CardWithModelList(MultiMachineCardId, $"err {MultiMachineToken} shared drive belt code on the console", MultiMachineModels), + ]; + _ = await Client.UpsertAsync(Name, added, cancellationToken: TestContext.Current.CancellationToken); + + // One conversation sets facets.audience on every point already in the collection -- the 30 base cards + // and the two just added -- rather than 32 individual patches. The all-points overload sends + // no points_selector at all, which this server version refuses ("points_selector is + // expected"); an empty filter is what Qdrant treats as "every point", and this client always + // wraps a Filter argument in a PointsSelector before it reaches the wire. + _ = await Client.SetPayloadAsync( + Name, + payload: new Dictionary { ["audience"] = new Value { StringValue = Audience } }, + filter: new Filter(), + key: "facets", + cancellationToken: TestContext.Current.CancellationToken); + } - var added = new[] + public async ValueTask DisposeAsync() { - CardWithModelList(MultiMachineCardId, $"err {MultiMachineToken} shared drive belt code on the console", MultiMachineModels), - }; - await Client.UpsertAsync(Name, added, cancellationToken: TestContext.Current.CancellationToken); - - // One conversation sets facets.audience on every point already in the collection -- the 30 base cards - // and the two just added -- rather than 32 individual patches. The all-points overload sends - // no points_selector at all, which this server version refuses ("points_selector is - // expected"); an empty filter is what Qdrant treats as "every point", and this client always - // wraps a Filter argument in a PointsSelector before it reaches the wire. - await Client.SetPayloadAsync( - Name, - payload: new Dictionary { ["audience"] = new Value { StringValue = Audience } }, - filter: new Filter(), - key: "facets", - cancellationToken: TestContext.Current.CancellationToken); - } + if (Client is null) + { + return; + } - public async ValueTask DisposeAsync() - { - if (Client is null) - { - return; + try + { + await Client.DeleteCollectionAsync(Name); + } + finally + { + Client.Dispose(); + } } - try - { - await Client.DeleteCollectionAsync(Name); - } - finally + internal static PointStruct CardWithModelScalar(string cardId, string text, string model) { - Client.Dispose(); + return Card(cardId, text, new Value { StringValue = model }); } - } - - internal static PointStruct CardWithModelScalar(string cardId, string text, string model) - => Card(cardId, text, new Value { StringValue = model }); - internal static PointStruct CardWithModelList(string cardId, string text, IReadOnlyList models) - => Card(cardId, text, new Value + internal static PointStruct CardWithModelList(string cardId, string text, IReadOnlyList models) { - ListValue = new ListValue { Values = { models.Select(model => new Value { StringValue = model }) } }, - }); + return Card(cardId, text, new Value + { + ListValue = new ListValue { Values = { models.Select(model => new Value { StringValue = model }) } }, + }); + } - internal static PointStruct Card(string cardId, string text, Value modelValue) - { - var point = new PointStruct + internal static PointStruct Card(string cardId, string text, Value modelValue) { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors + PointStruct point = new() { - Vectors_ = new NamedVectors { Vectors = { ["dense"] = KbShapedCorpus.QueryVector() } }, - }, - }; - - point.Payload["card_id"] = cardId; - point.Payload["text"] = text; - point.Payload["body"] = text; - point.Payload["authority"] = 3; - point.Payload["see_also"] = new Value { ListValue = new ListValue() }; - point.Payload["facets"] = new Value - { - StructValue = new Struct + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = new Vectors + { + Vectors_ = new NamedVectors { Vectors = { ["dense"] = KbShapedCorpus.QueryVector() } }, + }, + }; + + point.Payload["card_id"] = cardId; + point.Payload["text"] = text; + point.Payload["body"] = text; + point.Payload["authority"] = 3; + point.Payload["see_also"] = new Value { ListValue = new ListValue() }; + point.Payload["facets"] = new Value { - Fields = + StructValue = new Struct { - ["model"] = modelValue, - ["audience"] = new Value { StringValue = Audience }, + Fields = + { + ["model"] = modelValue, + ["audience"] = new Value { StringValue = Audience }, + }, }, - }, - }; - point.Payload["source"] = new Value - { - StructValue = new Struct + }; + point.Payload["source"] = new Value { - Fields = + StructValue = new Struct { - ["ref"] = new Value { StringValue = $"manifest-{cardId}" }, - ["locator"] = new Value { StringValue = "p.1" }, + Fields = + { + ["ref"] = new Value { StringValue = $"manifest-{cardId}" }, + ["locator"] = new Value { StringValue = "p.1" }, + }, }, - }, - }; + }; - return point; + return point; + } } -} -[Collection(QdrantServerCollection.Name)] -public sealed class AmbiguityIntegrationTests : IClassFixture -{ - private const string ModelDescription = "The model, as printed on the machine."; + [Collection(QdrantServerCollection.Name)] + public sealed class AmbiguityIntegrationTests(AmbiguityCorpusFixture corpus) : IClassFixture + { + private const string ModelDescription = "The model, as printed on the machine."; - private const string NoticeSourceName = "agentcore:notice"; + private const string NoticeSourceName = "agentcore:notice"; - /// Two droppable-shaped facets: model (the one the probe drops) and the always-concrete audience, so K33 never blocks the drop. - private const string TwoFacetYaml = - """ + /// Two droppable-shaped facets: model (the one the probe drops) and the always-concrete audience, so K33 never blocks the drop. + private const string TwoFacetYaml = + """ apiVersion: agentcore/v1 state: model: @@ -220,9 +225,9 @@ public sealed class AmbiguityIntegrationTests : IClassFixtureOne droppable-shaped facet only: dropping it would open the scope empty (K33). - private const string SingleFacetYaml = - """ + /// One droppable-shaped facet only: dropping it would open the scope empty (K33). + private const string SingleFacetYaml = + """ apiVersion: agentcore/v1 state: model: @@ -254,9 +259,9 @@ public sealed class AmbiguityIntegrationTests : IClassFixtureNo scope: at all: the agent opens the whole corpus regardless of what the caller has said. - private const string UnscopedYaml = - """ + /// No scope: at all: the agent opens the whole corpus regardless of what the caller has said. + private const string UnscopedYaml = + """ apiVersion: agentcore/v1 agents: items: @@ -266,477 +271,486 @@ public sealed class AmbiguityIntegrationTests : IClassFixtureA company-wide question with exactly one matching card answers, and the probe does not run. + /// + /// This card's own facets.model is the wildcard value, so a scope: { model: "*" } + /// search finds it under any query. It cannot live in the shared 31-card fixture: it would then be + /// the one card every other row's "unknown model" scope can always find too, since that scope + /// filter only ever admits a card whose own facet is literally "*". A throwaway collection, built + /// and dropped here, is what keeps this row's fact from leaking into every other one. + /// + [QdrantFact] + public async Task CompanyWideQuestion_ExactlyOneMatchingCard_Answers_ProbeDoesNotRun() + { + string collection = $"ambiguity-adhoc-{Guid.NewGuid():N}"; - public AmbiguityIntegrationTests(AmbiguityCorpusFixture corpus) => _corpus = corpus; + try + { + QdrantKnowledgeStore store = await FillAdHocCollectionAsync( + collection, + [AmbiguityCorpusFixture.CardWithModelScalar("syn-wild", "general policy text for every machine", "*")], + scoped: true); - // ----------------------------------------------------------------------------------------- - // Section 12's twelve real-Qdrant rows. - // ----------------------------------------------------------------------------------------- + SearchCapturingChatClient client = await RunAsync(BuildTwoFacetYaml(), "what is the policy for every machine", store); - /// A company-wide question with exactly one matching card answers, and the probe does not run. - /// - /// This card's own facets.model is the wildcard value, so a scope: { model: "*" } - /// search finds it under any query. It cannot live in the shared 31-card fixture: it would then be - /// the one card every other row's "unknown model" scope can always find too, since that scope - /// filter only ever admits a card whose own facet is literally "*". A throwaway collection, built - /// and dropped here, is what keeps this row's fact from leaking into every other one. - /// - [QdrantFact] - public async Task CompanyWideQuestion_ExactlyOneMatchingCard_Answers_ProbeDoesNotRun() - { - var collection = $"ambiguity-adhoc-{Guid.NewGuid():N}"; + // A genuine card reached the model -- the probe's own gate (cards.Count == 0) never + // opened, because a notice is the only shape a probe or a no-scope refusal ever returns. + Assert.Contains(client.Results, r => r.SourceName != NoticeSourceName); + Assert.Contains(client.Results, r => r.Text.Contains("general policy", StringComparison.Ordinal)); + } + finally + { + await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - try + /// A per-machine question produces the note, naming all three ids. + [QdrantFact] + public async Task PerMachineQuestion_ProducesTheNote_NamingAllThreeIds() { - var store = await FillAdHocCollectionAsync( - collection, - [AmbiguityCorpusFixture.CardWithModelScalar("syn-wild", "general policy text for every machine", "*")], - scoped: true); - - var client = await RunAsync(BuildTwoFacetYaml(), "what is the policy for every machine", store); + SearchCapturingChatClient client = await RunAsync(BuildTwoFacetYaml(), KbShapedCorpus.PlainQuery); - // A genuine card reached the model -- the probe's own gate (cards.Count == 0) never - // opened, because a notice is the only shape a probe or a no-scope refusal ever returns. - Assert.Contains(client.Results, r => r.SourceName != NoticeSourceName); - Assert.Contains(client.Results, r => r.Text.Contains("general policy", StringComparison.Ordinal)); + string text = Assert.Single(client.Results).Text; + Assert.Contains(ModelDescription, text, StringComparison.Ordinal); + Assert.Contains("ct900ent", text, StringComparison.Ordinal); + Assert.Contains("ctsbs900", text, StringComparison.Ordinal); + Assert.Contains("ct900,", text, StringComparison.Ordinal); } - finally + + /// A question whose cards all belong to one machine produces the one-candidate confirm text, not "holds nothing". + /// + /// §12's row names "cards", plural: several cards must actually reach the probe's union and + /// collapse to one value, not a single card standing in for the whole row (that shape is already + /// KnowledgeProbeTests.K24_OneCardIsNeverASpread's job, at the unit level). Four cards, all + /// carrying facets.model: ct900, live in their own throwaway collection so the union is + /// exactly {ct900} by real collapsing over multiple cards, not because there was nothing else to + /// find. + /// + [QdrantFact] + public async Task QuestionWhoseCardsAllBelongToOneMachine_ProducesTheOneCandidateConfirmText() { - await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); - } - } + string collection = $"ambiguity-adhoc-{Guid.NewGuid():N}"; - /// A per-machine question produces the note, naming all three ids. - [QdrantFact] - public async Task PerMachineQuestion_ProducesTheNote_NamingAllThreeIds() - { - var client = await RunAsync(BuildTwoFacetYaml(), KbShapedCorpus.PlainQuery); + try + { + PointStruct[] cards = [.. Enumerable.Range(0, 4) + .Select(i => AmbiguityCorpusFixture.CardWithModelScalar( + $"syn-single-{i}", $"card {i} deck belt maintenance text", "ct900"))]; + QdrantKnowledgeStore store = await FillAdHocCollectionAsync(collection, cards, scoped: true); - var text = Assert.Single(client.Results).Text; - Assert.Contains(ModelDescription, text, StringComparison.Ordinal); - Assert.Contains("ct900ent", text, StringComparison.Ordinal); - Assert.Contains("ctsbs900", text, StringComparison.Ordinal); - Assert.Contains("ct900,", text, StringComparison.Ordinal); - } + SearchCapturingChatClient client = await RunAsync(BuildTwoFacetYaml(), KbShapedCorpus.PlainQuery, store); - /// A question whose cards all belong to one machine produces the one-candidate confirm text, not "holds nothing". - /// - /// §12's row names "cards", plural: several cards must actually reach the probe's union and - /// collapse to one value, not a single card standing in for the whole row (that shape is already - /// KnowledgeProbeTests.K24_OneCardIsNeverASpread's job, at the unit level). Four cards, all - /// carrying facets.model: ct900, live in their own throwaway collection so the union is - /// exactly {ct900} by real collapsing over multiple cards, not because there was nothing else to - /// find. - /// - [QdrantFact] - public async Task QuestionWhoseCardsAllBelongToOneMachine_ProducesTheOneCandidateConfirmText() - { - var collection = $"ambiguity-adhoc-{Guid.NewGuid():N}"; + string text = Assert.Single(client.Results).Text; + Assert.DoesNotContain("holds nothing", text, StringComparison.Ordinal); + Assert.Contains("decides the answer here", text, StringComparison.Ordinal); + Assert.Contains("Everything found is for ct900.", text, StringComparison.Ordinal); + } + finally + { + await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - try + /// A card tagged with two machines produces a note naming both. + [QdrantFact] + public async Task CardTaggedWithTwoMachines_ProducesANoteNamingBoth() { - var cards = Enumerable.Range(0, 4) - .Select(i => AmbiguityCorpusFixture.CardWithModelScalar( - $"syn-single-{i}", $"card {i} deck belt maintenance text", "ct900")) - .ToArray(); - var store = await FillAdHocCollectionAsync(collection, cards, scoped: true); + SearchCapturingChatClient client = await RunAsync( + BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", limit: 1); + + string text = Assert.Single(client.Results).Text; + foreach (string model in AmbiguityCorpusFixture.MultiMachineModels) + { + Assert.Contains(model, text, StringComparison.Ordinal); + } + } - var client = await RunAsync(BuildTwoFacetYaml(), KbShapedCorpus.PlainQuery, store); + /// More than maxCandidates names none of them. + [QdrantFact] + public async Task MoreThanMaxCandidates_NamesNone() + { + SearchCapturingChatClient client = await RunAsync(BuildTwoFacetYaml(maxCandidates: 2), KbShapedCorpus.PlainQuery); - var text = Assert.Single(client.Results).Text; + string text = Assert.Single(client.Results).Text; Assert.DoesNotContain("holds nothing", text, StringComparison.Ordinal); - Assert.Contains("decides the answer here", text, StringComparison.Ordinal); - Assert.Contains("Everything found is for ct900.", text, StringComparison.Ordinal); + Assert.DoesNotContain("ct900", text, StringComparison.Ordinal); + Assert.DoesNotContain("ctsbs900", text, StringComparison.Ordinal); } - finally + + /// + /// A probe spread publishes no sources. TurnSources is internal to ConversationSession and + /// unreachable without a grant this project does not have, so this reads the same fact at its + /// outer edge instead: nothing card-shaped reached the model at all, only the notice -- which is + /// exactly what "published no sources" requires, since only a card-shaped result is ever cited. + /// + [QdrantFact] + public async Task AProbeSpread_PublishesNoSources() { - await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); - } - } + SearchCapturingChatClient client = await RunAsync(BuildTwoFacetYaml(maxCandidates: 2), KbShapedCorpus.PlainQuery); - /// A card tagged with two machines produces a note naming both. - [QdrantFact] - public async Task CardTaggedWithTwoMachines_ProducesANoteNamingBoth() - { - var client = await RunAsync( - BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", limit: 1); + // Assert.All over an empty sequence passes vacuously; this pins that the probe actually spoke + // before checking what it carried. + _ = Assert.Single(client.Results); + Assert.All(client.Results, r => Assert.Equal(NoticeSourceName, r.SourceName)); + } - var text = Assert.Single(client.Results).Text; - foreach (var model in AmbiguityCorpusFixture.MultiMachineModels) + /// No notice can be cited as a card: every notice this design emits carries the reserved source name. + [QdrantFact] + public async Task NoNoticeCanBeCitedAsACard() { - Assert.Contains(model, text, StringComparison.Ordinal); + SearchCapturingChatClient holdsNothing = await RunAsync(SingleFacetYaml, $"the screen says {AmbiguityCorpusFixture.NothingToken}"); + _ = Assert.Single(holdsNothing.Results); + Assert.All(holdsNothing.Results, r => Assert.Equal(NoticeSourceName, r.SourceName)); + + SearchCapturingChatClient named = await RunAsync( + BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", limit: 1); + _ = Assert.Single(named.Results); + Assert.All(named.Results, r => Assert.Equal(NoticeSourceName, r.SourceName)); } - } - /// More than maxCandidates names none of them. - [QdrantFact] - public async Task MoreThanMaxCandidates_NamesNone() - { - var client = await RunAsync(BuildTwoFacetYaml(maxCandidates: 2), KbShapedCorpus.PlainQuery); + /// A single-facet fromState deployment does not throw: the probe is skipped and the turn returns "holds nothing" (K33). + [QdrantFact] + public async Task SingleFacetFromStateDeployment_DoesNotThrow_ProbeIsSkipped_HoldsNothing() + { + SearchCapturingChatClient client = await RunAsync(SingleFacetYaml, $"the screen says {AmbiguityCorpusFixture.NothingToken}"); - var text = Assert.Single(client.Results).Text; - Assert.DoesNotContain("holds nothing", text, StringComparison.Ordinal); - Assert.DoesNotContain("ct900", text, StringComparison.Ordinal); - Assert.DoesNotContain("ctsbs900", text, StringComparison.Ordinal); - } + Assert.Contains("holds nothing", Assert.Single(client.Results).Text, StringComparison.Ordinal); + } - /// - /// A probe spread publishes no sources. TurnSources is internal to ConversationSession and - /// unreachable without a grant this project does not have, so this reads the same fact at its - /// outer edge instead: nothing card-shaped reached the model at all, only the notice -- which is - /// exactly what "published no sources" requires, since only a card-shaped result is ever cited. - /// - [QdrantFact] - public async Task AProbeSpread_PublishesNoSources() - { - var client = await RunAsync(BuildTwoFacetYaml(maxCandidates: 2), KbShapedCorpus.PlainQuery); + /// An unscoped agent's empty search returns an empty list (§8 step 2). + /// + /// An unscoped agent opens WholeCorpus -- no facets at all -- so the store's own filter is + /// empty and admits every point. Against the shared fixture that would always find something (the + /// closest card by dense rank, regardless of the query's own text, since a fixed test embedding + /// answers every query alike); a genuinely empty collection is what makes the search answer + /// nothing, and is the one true test of "empty", independent of ranking. + /// + [QdrantFact] + public async Task UnscopedAgent_EmptySearch_ReturnsAnEmptyList() + { + string collection = $"ambiguity-adhoc-{Guid.NewGuid():N}"; - // Assert.All over an empty sequence passes vacuously; this pins that the probe actually spoke - // before checking what it carried. - Assert.Single(client.Results); - Assert.All(client.Results, r => Assert.Equal(NoticeSourceName, r.SourceName)); - } + try + { + QdrantKnowledgeStore store = await FillAdHocCollectionAsync(collection, [], scoped: false); - /// No notice can be cited as a card: every notice this design emits carries the reserved source name. - [QdrantFact] - public async Task NoNoticeCanBeCitedAsACard() - { - var holdsNothing = await RunAsync(SingleFacetYaml, $"the screen says {AmbiguityCorpusFixture.NothingToken}"); - Assert.Single(holdsNothing.Results); - Assert.All(holdsNothing.Results, r => Assert.Equal(NoticeSourceName, r.SourceName)); - - var named = await RunAsync( - BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", limit: 1); - Assert.Single(named.Results); - Assert.All(named.Results, r => Assert.Equal(NoticeSourceName, r.SourceName)); - } + SearchCapturingChatClient client = await RunAsync(UnscopedYaml, "anything at all", store); - /// A single-facet fromState deployment does not throw: the probe is skipped and the turn returns "holds nothing" (K33). - [QdrantFact] - public async Task SingleFacetFromStateDeployment_DoesNotThrow_ProbeIsSkipped_HoldsNothing() - { - var client = await RunAsync(SingleFacetYaml, $"the screen says {AmbiguityCorpusFixture.NothingToken}"); + Assert.Empty(client.Results); + } + finally + { + await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - Assert.Contains("holds nothing", Assert.Single(client.Results).Text, StringComparison.Ordinal); - } + /// + /// A probe that throws returns "holds nothing", logs its own event, and leaves the main search's + /// audit record intact (K32). + /// + /// + /// The real store answers the main search; only the probe's own narrowed second search is a + /// synthetic throw, because the two searches share every scope facet but the one being dropped, so + /// there is no real Qdrant misconfiguration that fails one and not the other (verified by reading + /// QdrantKnowledgeStore's filter construction before choosing this shape). + /// + [QdrantFact] + public async Task ProbeThatThrows_ReturnsHoldsNothing_LogsItsOwnEvent_LeavesTheMainSearchAuditRecordIntact() + { + RecordingLoggerFactory loggers = new(); + ThrowingOnNarrowedScopePort port = new(BuildStore(), fullFacetCount: 2); - /// An unscoped agent's empty search returns an empty list (§8 step 2). - /// - /// An unscoped agent opens WholeCorpus -- no facets at all -- so the store's own filter is - /// empty and admits every point. Against the shared fixture that would always find something (the - /// closest card by dense rank, regardless of the query's own text, since a fixed test embedding - /// answers every query alike); a genuinely empty collection is what makes the search answer - /// nothing, and is the one true test of "empty", independent of ranking. - /// - [QdrantFact] - public async Task UnscopedAgent_EmptySearch_ReturnsAnEmptyList() - { - var collection = $"ambiguity-adhoc-{Guid.NewGuid():N}"; + SearchCapturingChatClient client = await RunAsync( + BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", port, loggers); - try - { - var store = await FillAdHocCollectionAsync(collection, [], scoped: false); + Assert.Contains("holds nothing", Assert.Single(client.Results).Text, StringComparison.Ordinal); - var client = await RunAsync(UnscopedYaml, "anything at all", store); + // EventId 17: KnowledgeProbeFailed -- the probe's own failure event. + CapturedLine probeFailed = Assert.Single(loggers.Of(17)); + Assert.Equal("model", probeFailed.Field("Facet")); - Assert.Empty(client.Results); - } - finally - { - await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + // EventId 11: KnowledgeRetrieved -- the main search's own audit record, recorded before the + // probe ever ran, and untouched by the probe's later failure. + _ = Assert.Single(loggers.Of(11)); + + // EventId 12: KnowledgeRetrievalFailed -- the main search itself never failed, so this never fires. + Assert.Empty(loggers.Of(12)); } - } - /// - /// A probe that throws returns "holds nothing", logs its own event, and leaves the main search's - /// audit record intact (K32). - /// - /// - /// The real store answers the main search; only the probe's own narrowed second search is a - /// synthetic throw, because the two searches share every scope facet but the one being dropped, so - /// there is no real Qdrant misconfiguration that fails one and not the other (verified by reading - /// QdrantKnowledgeStore's filter construction before choosing this shape). - /// - [QdrantFact] - public async Task ProbeThatThrows_ReturnsHoldsNothing_LogsItsOwnEvent_LeavesTheMainSearchAuditRecordIntact() - { - RecordingLoggerFactory loggers = new(); - var port = new ThrowingOnNarrowedScopePort(BuildStore(), fullFacetCount: 2); + // ----------------------------------------------------------------------------------------- + // Helpers. + // ----------------------------------------------------------------------------------------- - var client = await RunAsync( - BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", port, loggers); + private async Task RunAsync( + string yaml, + string callerQuestion, + IKnowledgeRetrievalPort? port = null, + RecordingLoggerFactory? loggers = null, + int limit = 10) + { + SearchCapturingChatClient capture = new(callerQuestion); + RoutingChatClientFactory chatClients = new(capture); + _ = chatClients.Route("fill", new FixedTextChatClient("{}")); - Assert.Contains("holds nothing", Assert.Single(client.Results).Text, StringComparison.Ordinal); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(chatClients) + { + Knowledge = port ?? BuildStore(limit), + Loggers = loggers, + })["main"]; - // EventId 17: KnowledgeProbeFailed -- the probe's own failure event. - var probeFailed = Assert.Single(loggers.Of(17)); - Assert.Equal("model", probeFailed.Field("Facet")); + StateExtractor? extractor = ConversationSessionFactory.CreateExtractor(compiled, chatClients); + ConversationSession session = new ConversationSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor) + .Create($"conversation-{Guid.NewGuid():N}"); - // EventId 11: KnowledgeRetrieved -- the main search's own audit record, recorded before the - // probe ever ran, and untouched by the probe's later failure. - Assert.Single(loggers.Of(11)); + _ = await session.RunTurnAsync(callerQuestion, TestContext.Current.CancellationToken); - // EventId 12: KnowledgeRetrievalFailed -- the main search itself never failed, so this never fires. - Assert.Empty(loggers.Of(12)); - } + return capture; + } - // ----------------------------------------------------------------------------------------- - // Helpers. - // ----------------------------------------------------------------------------------------- + private static string BuildTwoFacetYaml(int maxCandidates = 6) + { + return TwoFacetYaml.Replace("{{maxCandidates}}", maxCandidates.ToString(), StringComparison.Ordinal); + } - private async Task RunAsync( - string yaml, - string callerQuestion, - IKnowledgeRetrievalPort? port = null, - RecordingLoggerFactory? loggers = null, - int limit = 10) - { - SearchCapturingChatClient capture = new(callerQuestion); - RoutingChatClientFactory chatClients = new(capture); - chatClients.Route("fill", new FixedTextChatClient("{}")); + private QdrantKnowledgeStore BuildStore(int limit = 10) + { + return BuildStoreOver(_corpus.Name, limit, scoped: true); + } - var compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(yaml), - new AgentCompilationContext(chatClients) + private QdrantKnowledgeStore BuildStoreOver(string collection, int limit, bool scoped) + { + return new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions { - Knowledge = port ?? BuildStore(limit), - Loggers = loggers, - })["main"]; + Collection = collection, + Scoped = scoped, + VectorName = "dense", + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + ScopeWildcard = "*", + ScopeWildcardFacets = ["model"], + Analyzer = KbShapedCorpus.Analyzer, + Limit = limit, + ScoreFloor = 0.0, + }); + } - var extractor = ConversationSessionFactory.CreateExtractor(compiled, chatClients); - var session = new ConversationSessionFactory( - compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor) - .Create($"conversation-{Guid.NewGuid():N}"); + /// + /// Creates and fills one throwaway collection, already named by the caller, for one test. Used by + /// the rows whose own card population must not be visible to any other row's search of the shared + /// fixture (see 's remarks). + /// + /// + /// The caller generates and opens its own try **before** + /// calling this -- never the reverse. Collection creation, every index, and the upsert can each + /// throw against a live, sometimes-contended server, and if that happened inside an un-tried + /// helper the collection this conversation already created on the server would be orphaned with nothing + /// left to drop it. Creation, indexing and upsert all sit inside one try, with one + /// unconditional DeleteCollectionAsync in the caller's own finally. + /// + private async Task FillAdHocCollectionAsync( + string collection, PointStruct[] points, bool scoped) + { + CancellationToken cancellationToken = TestContext.Current.CancellationToken; - await session.RunTurnAsync(callerQuestion, TestContext.Current.CancellationToken); + await _corpus.Client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap + { + Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, + }, + cancellationToken: cancellationToken); - return capture; - } + _ = await _corpus.Client.CreatePayloadIndexAsync( + collection, "text", PayloadSchemaType.Text, cancellationToken: cancellationToken); + _ = await _corpus.Client.CreatePayloadIndexAsync( + collection, "facets.model", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); + _ = await _corpus.Client.CreatePayloadIndexAsync( + collection, "facets.audience", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - private static string BuildTwoFacetYaml(int maxCandidates = 6) - => TwoFacetYaml.Replace("{{maxCandidates}}", maxCandidates.ToString(), StringComparison.Ordinal); + if (points.Length > 0) + { + _ = await _corpus.Client.UpsertAsync(collection, points, cancellationToken: cancellationToken); + } - private QdrantKnowledgeStore BuildStore(int limit = 10) => BuildStoreOver(_corpus.Name, limit, scoped: true); + return BuildStoreOver(collection, limit: 10, scoped); + } - private QdrantKnowledgeStore BuildStoreOver(string collection, int limit, bool scoped) => new( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions + /// + /// A knowledge store that answers the full-scope (main) search from a real backing store and + /// throws for any narrowed one -- the shape §8 step 4's own probe search takes once a facet is + /// dropped. Used only for the row that needs the probe's own second search to fail. + /// + private sealed class ThrowingOnNarrowedScopePort : IKnowledgeRetrievalPort { - Collection = collection, - Scoped = scoped, - VectorName = "dense", - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - ScopeWildcard = "*", - ScopeWildcardFacets = ["model"], - Analyzer = KbShapedCorpus.Analyzer, - Limit = limit, - ScoreFloor = 0.0, - }); + private readonly IKnowledgeRetrievalPort _inner; + private readonly int _fullFacetCount; - /// - /// Creates and fills one throwaway collection, already named by the caller, for one test. Used by - /// the rows whose own card population must not be visible to any other row's search of the shared - /// fixture (see 's remarks). - /// - /// - /// The caller generates and opens its own try **before** - /// calling this -- never the reverse. Collection creation, every index, and the upsert can each - /// throw against a live, sometimes-contended server, and if that happened inside an un-tried - /// helper the collection this conversation already created on the server would be orphaned with nothing - /// left to drop it. Creation, indexing and upsert all sit inside one try, with one - /// unconditional DeleteCollectionAsync in the caller's own finally. - /// - private async Task FillAdHocCollectionAsync( - string collection, PointStruct[] points, bool scoped) - { - var cancellationToken = TestContext.Current.CancellationToken; + internal ThrowingOnNarrowedScopePort(IKnowledgeRetrievalPort inner, int fullFacetCount) + { + _inner = inner; + _fullFacetCount = fullFacetCount; + } - await _corpus.Client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap + public ValueTask> SearchAsync( + string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: cancellationToken); - - await _corpus.Client.CreatePayloadIndexAsync( - collection, "text", PayloadSchemaType.Text, cancellationToken: cancellationToken); - await _corpus.Client.CreatePayloadIndexAsync( - collection, "facets.model", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - await _corpus.Client.CreatePayloadIndexAsync( - collection, "facets.audience", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - - if (points.Length > 0) - { - await _corpus.Client.UpsertAsync(collection, points, cancellationToken: cancellationToken); + return scope?.Facets.Count == _fullFacetCount + ? _inner.SearchAsync(query, scope, cancellationToken) + : throw new InvalidOperationException("the probe's own second search is down (synthetic, for this row only)."); + } } - return BuildStoreOver(collection, limit: 10, scoped); - } - - /// - /// A knowledge store that answers the full-scope (main) search from a real backing store and - /// throws for any narrowed one -- the shape §8 step 4's own probe search takes once a facet is - /// dropped. Used only for the row that needs the probe's own second search to fail. - /// - private sealed class ThrowingOnNarrowedScopePort : IKnowledgeRetrievalPort - { - private readonly IKnowledgeRetrievalPort _inner; - private readonly int _fullFacetCount; - - internal ThrowingOnNarrowedScopePort(IKnowledgeRetrievalPort inner, int fullFacetCount) + /// + /// Stands in for the turn's reply model. Rather than answer, its first round calls the compiled + /// agent's own Search tool with the row's question, the way a model that needs the cards + /// would; the framework's own tool-calling loop then invokes the real search with the running + /// turn filed in its arguments, from inside the same flow scope opened + /// around this conversation. Its second round reads the tool's own answer back off the transcript and + /// keeps it, so every row asserts on what the production search actually returned. + /// + private sealed class SearchCapturingChatClient : IChatClient { - _inner = inner; - _fullFacetCount = fullFacetCount; - } + private readonly string _query; - public ValueTask> SearchAsync( - string query, KnowledgeScope? scope = null, CancellationToken cancellationToken = default) - { - if (scope?.Facets.Count == _fullFacetCount) + internal SearchCapturingChatClient(string query) { - return _inner.SearchAsync(query, scope, cancellationToken); + _query = query; } - throw new InvalidOperationException("the probe's own second search is down (synthetic, for this row only)."); - } - } + internal IReadOnlyList Results { get; private set; } = []; - /// - /// Stands in for the turn's reply model. Rather than answer, its first round calls the compiled - /// agent's own Search tool with the row's question, the way a model that needs the cards - /// would; the framework's own tool-calling loop then invokes the real search with the running - /// turn filed in its arguments, from inside the same flow scope opened - /// around this conversation. Its second round reads the tool's own answer back off the transcript and - /// keeps it, so every row asserts on what the production search actually returned. - /// - private sealed class SearchCapturingChatClient : IChatClient - { - private readonly string _query; - - internal SearchCapturingChatClient(string query) => _query = query; - - internal IReadOnlyList Results { get; private set; } = []; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - var responseId = Guid.NewGuid().ToString("N"); + string responseId = Guid.NewGuid().ToString("N"); - var toolAnswer = messages - .SelectMany(message => message.Contents.OfType()) - .Select(content => content.Result) - .OfType>() - .FirstOrDefault(); + IEnumerable? toolAnswer = messages + .SelectMany(message => message.Contents.OfType()) + .Select(content => content.Result) + .OfType>() + .FirstOrDefault(); - if (toolAnswer is null) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - $"search-{responseId}", - "Search", - new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = _query })]) + if (toolAnswer is null) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + $"search-{responseId}", + "Search", + new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = _query })]) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } + + Results = [.. toolAnswer]; + + yield return new ChatResponseUpdate(ChatRole.Assistant, "noted.") { ResponseId = responseId, MessageId = responseId, }; - yield break; } - Results = [.. toolAnswer]; - yield return new ChatResponseUpdate(ChatRole.Assistant, "noted.") + public async Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } + return updates.ToChatResponse(); + } - public async Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public object? GetService(Type serviceType, object? serviceKey = null) { - updates.Add(update); + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; } - return updates.ToChatResponse(); + public void Dispose() + { + // Nothing to release. + } } - public object? GetService(Type serviceType, object? serviceKey = null) + /// + /// A model that always answers with the same fixed text, ignoring whatever transcript it is + /// handed. Stands in for both the turn's reply model and its extractor: the reply's own words do + /// not matter to any row here, and the extractor's fixed text is read as JSON. + /// + private sealed class FixedTextChatClient : IChatClient { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + private readonly string _text; - public void Dispose() - { - // Nothing to release. - } - } - - /// - /// A model that always answers with the same fixed text, ignoring whatever transcript it is - /// handed. Stands in for both the turn's reply model and its extractor: the reply's own words do - /// not matter to any row here, and the extractor's fixed text is read as JSON. - /// - private sealed class FixedTextChatClient : IChatClient - { - private readonly string _text; + internal FixedTextChatClient(string text) + { + _text = text; + } - internal FixedTextChatClient(string text) => _text = text; + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + await Task.Yield(); - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(messages); - await Task.Yield(); + string responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, _text) + { + ResponseId = responseId, + MessageId = responseId, + }; + } - var responseId = Guid.NewGuid().ToString("N"); - yield return new ChatResponseUpdate(ChatRole.Assistant, _text) + public async Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) { - ResponseId = responseId, - MessageId = responseId, - }; - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - public async Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); + return updates.ToChatResponse(); } - return updates.ToChatResponse(); - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public void Dispose() + { + // Nothing to release. + } } - public void Dispose() - { - // Nothing to release. - } } - } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/DirectLinkLookupTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/DirectLinkLookupTests.cs index bd107431..ad647901 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/DirectLinkLookupTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/DirectLinkLookupTests.cs @@ -5,71 +5,75 @@ using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// links.lookup: direct against a fake channel. -/// -/// -/// No corpus anywhere in this plan keys its points by the card id itself: the synthetic corpus -/// uses uuid5 keys and the foreign corpus uses random ones, so a live server never runs this -/// branch. These two drive it through instead, needing no -/// Qdrant server at all. -/// -public sealed class DirectLinkLookupTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [Fact] - public async Task SearchAsync_DirectLookupWithNonGuidCardId_ThrowsNamingTheId() + /// + /// links.lookup: direct against a fake channel. + /// + /// + /// No corpus anywhere in this plan keys its points by the card id itself: the synthetic corpus + /// uses uuid5 keys and the foreign corpus uses random ones, so a live server never runs this + /// branch. These two drive it through instead, needing no + /// Qdrant server at all. + /// + public sealed class DirectLinkLookupTests { - const string linkedId = "not-a-guid"; - var channel = new RecordingSearchChannel([Point("card-1", linkedId)]); - var store = Store(channel); + [Fact] + public async Task SearchAsync_DirectLookupWithNonGuidCardId_ThrowsNamingTheId() + { + const string linkedId = "not-a-guid"; + RecordingSearchChannel channel = new([Point("card-1", linkedId)]); + QdrantKnowledgeStore store = Store(channel); - var thrown = await Assert.ThrowsAsync( - async () => await store.SearchAsync("anything", null, TestContext.Current.CancellationToken)); + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await store.SearchAsync("anything", null, TestContext.Current.CancellationToken)); - Assert.Contains(linkedId, thrown.Message, StringComparison.Ordinal); - } + Assert.Contains(linkedId, thrown.Message, StringComparison.Ordinal); + } - [Fact] - public async Task SearchAsync_DirectLookupWithGuidShapedCardId_ResolvesToThatGuid() - { - var linkedId = Guid.NewGuid(); - var channel = new RecordingSearchChannel([Point("card-1", linkedId.ToString())]); - var store = Store(channel); + [Fact] + public async Task SearchAsync_DirectLookupWithGuidShapedCardId_ResolvesToThatGuid() + { + Guid linkedId = Guid.NewGuid(); + RecordingSearchChannel channel = new([Point("card-1", linkedId.ToString())]); + QdrantKnowledgeStore store = Store(channel); - await store.SearchAsync("anything", null, TestContext.Current.CancellationToken); + _ = await store.SearchAsync("anything", null, TestContext.Current.CancellationToken); - var retrieved = Assert.Single(channel.RetrievedIds); - Assert.Equal(linkedId, Assert.Single(retrieved)); - } + IReadOnlyList retrieved = Assert.Single(channel.RetrievedIds); + Assert.Equal(linkedId, Assert.Single(retrieved)); + } - /// One scored point whose own id is and whose only link is . - private static ScoredPoint Point(string cardId, string linkedId) - { - var point = new ScoredPoint { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Score = 1f }; - point.Payload["card_id"] = cardId; - point.Payload["body"] = "text"; - point.Payload["see_also"] = new Value + /// One scored point whose own id is and whose only link is . + private static ScoredPoint Point(string cardId, string linkedId) { - ListValue = new ListValue { Values = { new Value { StringValue = linkedId } } }, - }; - return point; - } + ScoredPoint point = new() { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Score = 1f }; + point.Payload["card_id"] = cardId; + point.Payload["body"] = "text"; + point.Payload["see_also"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = linkedId } } }, + }; + return point; + } - private static QdrantKnowledgeStore Store(RecordingSearchChannel channel) => new( - channel, - new FakeEmbeddingGenerator([1f]), - new QdrantKnowledgeStoreOptions + private static QdrantKnowledgeStore Store(RecordingSearchChannel channel) { - Collection = "anything", - Scoped = false, - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - Links = new KnowledgeLinksConfiguration + return new( + channel, + new FakeEmbeddingGenerator([1f]), + new QdrantKnowledgeStoreOptions { - Field = "see_also", - Lookup = KnowledgeLinkLookup.Direct, - }, - ScoreFloor = 0.0, - }); + Collection = "anything", + Scoped = false, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + Links = new KnowledgeLinksConfiguration + { + Field = "see_also", + Lookup = KnowledgeLinkLookup.Direct, + }, + ScoreFloor = 0.0, + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs index 195ff7bb..62484a6d 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs @@ -1,6 +1,7 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; using AgentCore.Application.Ports; +using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; using AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; @@ -9,109 +10,113 @@ using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// Reading whole cards by one exact facet value, which is what a model year needs: a keyword match, -/// never a similarity. -/// -/// -/// Two adjacent model years read as near-identical to an embedding, so a ranked search for one -/// returns the other. A filtered scroll cannot make that mistake: a card carries the value or it -/// does not. -/// -public sealed class FacetReadTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [Fact] - public async Task ReadByFacetAsync_ReturnsTheCardsTheScrollAnswered() + /// + /// Reading whole cards by one exact facet value, which is what a model year needs: a keyword match, + /// never a similarity. + /// + /// + /// Two adjacent model years read as near-identical to an embedding, so a ranked search for one + /// returns the other. A filtered scroll cannot make that mistake: a card carries the value or it + /// does not. + /// + public sealed class FacetReadTests { - var channel = new FacetScrollChannel(Card("lcr-2023-model-overview"), Card("lcr-2023-belt-tension")); + [Fact] + public async Task ReadByFacetAsync_ReturnsTheCardsTheScrollAnswered() + { + FacetScrollChannel channel = new(Card("lcr-2023-model-overview"), Card("lcr-2023-belt-tension")); - var cards = await Store(channel).ReadByFacetAsync( - "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); + IReadOnlyList cards = await Store(channel).ReadByFacetAsync( + "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); - Assert.Equal( - ["lcr-2023-belt-tension", "lcr-2023-model-overview"], - cards.Select(card => card.CardId).Order(StringComparer.Ordinal)); - } + Assert.Equal( + ["lcr-2023-belt-tension", "lcr-2023-model-overview"], + cards.Select(card => card.CardId).Order(StringComparer.Ordinal)); + } - [Fact] - public async Task ReadByFacetAsync_FiltersOnThePathVerbatim() - { - var channel = new FacetScrollChannel(Card("lcr-2023-model-overview")); + [Fact] + public async Task ReadByFacetAsync_FiltersOnThePathVerbatim() + { + FacetScrollChannel channel = new(Card("lcr-2023-model-overview")); - await Store(channel).ReadByFacetAsync( - "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); + _ = await Store(channel).ReadByFacetAsync( + "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); - var condition = Assert.Single(channel.LastFilter!.Must).Field; - Assert.Equal("facets.model", condition.Key); - Assert.Equal("lcr-2023", condition.Match.Keyword); - } + FieldCondition condition = Assert.Single(channel.LastFilter!.Must).Field; + Assert.Equal("facets.model", condition.Key); + Assert.Equal("lcr-2023", condition.Match.Keyword); + } - [Fact] - public async Task ReadByFacetAsync_PassesTheLimitThrough() - { - var channel = new FacetScrollChannel(Card("lcr-2023-model-overview")); + [Fact] + public async Task ReadByFacetAsync_PassesTheLimitThrough() + { + FacetScrollChannel channel = new(Card("lcr-2023-model-overview")); - await Store(channel).ReadByFacetAsync( - "facets.model", "lcr-2023", 7, TestContext.Current.CancellationToken); + _ = await Store(channel).ReadByFacetAsync( + "facets.model", "lcr-2023", 7, TestContext.Current.CancellationToken); - Assert.Equal(7u, channel.LastLimit); - } + Assert.Equal(7u, channel.LastLimit); + } - [Fact] - public async Task ReadByFacetAsync_AnUnknownValueIsEmptyAndNotAnError() - { - var cards = await Store(new FacetScrollChannel()).ReadByFacetAsync( - "facets.model", "nope-1999", 50, TestContext.Current.CancellationToken); + [Fact] + public async Task ReadByFacetAsync_AnUnknownValueIsEmptyAndNotAnError() + { + IReadOnlyList cards = await Store(new FacetScrollChannel()).ReadByFacetAsync( + "facets.model", "nope-1999", 50, TestContext.Current.CancellationToken); - Assert.Empty(cards); - } + Assert.Empty(cards); + } - [Fact] - public async Task ReadByFacetAsync_NeverRanks() - { - // FacetScrollChannel throws on every method but ScrollAsync. Reaching this assertion is the - // proof that no vector was built and no embedding was generated. - var cards = await Store(new FacetScrollChannel(Card("lcr-2023-model-overview"))).ReadByFacetAsync( - "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); + [Fact] + public async Task ReadByFacetAsync_NeverRanks() + { + // FacetScrollChannel throws on every method but ScrollAsync. Reaching this assertion is the + // proof that no vector was built and no embedding was generated. + IReadOnlyList cards = await Store(new FacetScrollChannel(Card("lcr-2023-model-overview"))).ReadByFacetAsync( + "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); - Assert.Null(Assert.Single(cards).Score); - } + Assert.Null(Assert.Single(cards).Score); + } - [Fact] - public async Task ReadByFacetAsync_RejectsANegativeLimit() - { - await Assert.ThrowsAsync( - async () => await Store(new FacetScrollChannel()).ReadByFacetAsync( - "facets.model", "lcr-2023", -1, TestContext.Current.CancellationToken)); - } + [Fact] + public async Task ReadByFacetAsync_RejectsANegativeLimit() + { + _ = await Assert.ThrowsAsync( + async () => await Store(new FacetScrollChannel()).ReadByFacetAsync( + "facets.model", "lcr-2023", -1, TestContext.Current.CancellationToken)); + } - [Fact] - public void TheStoreServesTheFacetReadAsACapability() - { - // What a caller asks before it reads. The store answers for itself here; a wrapper would - // forward the same question inward. - IKnowledgeRetrievalPort store = Store(new FacetScrollChannel()); + [Fact] + public void TheStoreServesTheFacetReadAsACapability() + { + // What a caller asks before it reads. The store answers for itself here; a wrapper would + // forward the same question inward. + IKnowledgeRetrievalPort store = Store(new FacetScrollChannel()); - Assert.Same(store, store.GetService()); - } + Assert.Same(store, store.GetService()); + } - private static RetrievedPoint Card(string cardId) - { - var point = new RetrievedPoint { Id = new PointId { Uuid = Guid.NewGuid().ToString() } }; - point.Payload["card_id"] = cardId; - point.Payload["body"] = $"{cardId} body"; - return point; - } + private static RetrievedPoint Card(string cardId) + { + RetrievedPoint point = new() { Id = new PointId { Uuid = Guid.NewGuid().ToString() } }; + point.Payload["card_id"] = cardId; + point.Payload["body"] = $"{cardId} body"; + return point; + } - private static QdrantKnowledgeStore Store(IQdrantSearchChannel channel) => new( - channel, - new FakeEmbeddingGenerator([1f, 0f, 0f, 0f]), - new QdrantKnowledgeStoreOptions + private static QdrantKnowledgeStore Store(IQdrantSearchChannel channel) { - Collection = "kb", - Scoped = false, - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - }); + return new( + channel, + new FakeEmbeddingGenerator([1f, 0f, 0f, 0f]), + new QdrantKnowledgeStoreOptions + { + Collection = "kb", + Scoped = false, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs index 3ed07cf0..0c930500 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs @@ -1,79 +1,74 @@ using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; - -/// -/// A channel that answers scripted points and keeps every request the store built. -/// -/// -/// The store's whole naming contract is visible in the requests it writes: which payload key a -/// facet became, which key the required-term leg matches on, which key a link filter reads. A live -/// server answers those requests but never reports them, so a test against Qdrant can only observe -/// the naming indirectly, through whether the right rows came back. This observes it directly, and -/// needs no server at all. -/// -internal sealed class CapturingSearchChannel : IQdrantSearchChannel +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes { - private readonly IReadOnlyList _ranked; - private readonly IReadOnlyList _fetched; - - /// Creates the channel. + /// + /// A channel that answers scripted points and keeps every request the store built. + /// + /// + /// The store's whole naming contract is visible in the requests it writes: which payload key a + /// facet became, which key the required-term leg matches on, which key a link filter reads. A live + /// server answers those requests but never reports them, so a test against Qdrant can only observe + /// the naming indirectly, through whether the right rows came back. This observes it directly, and + /// needs no server at all. + /// + /// Creates the channel. /// What answers. /// What and answer. - public CapturingSearchChannel( - IReadOnlyList ranked, IReadOnlyList? fetched = null) + internal sealed class CapturingSearchChannel( + IReadOnlyList ranked, IReadOnlyList? fetched = null) : IQdrantSearchChannel { - _ranked = ranked; - _fetched = fetched ?? []; - } + private readonly IReadOnlyList _ranked = ranked; + private readonly IReadOnlyList _fetched = fetched ?? []; - /// Gets the fused query the store built, or null when it never searched. - public SearchQuery? Query { get; private set; } + /// Gets the fused query the store built, or null when it never searched. + public SearchQuery? Query { get; private set; } - /// Gets the filter the store scrolled with, or null when it never scrolled. - public Filter? ScrollFilter { get; private set; } + /// Gets the filter the store scrolled with, or null when it never scrolled. + public Filter? ScrollFilter { get; private set; } - /// Gets every id set the store fetched by key, in call order. - public List> RetrievedIds { get; } = []; + /// Gets every id set the store fetched by key, in call order. + public List> RetrievedIds { get; } = []; - /// Gets every Must field condition of the first prefetch leg, keyed by payload path. - public IReadOnlyDictionary DenseFilterKeywords => - Query is null - ? new Dictionary(StringComparer.Ordinal) - : Query.Prefetch[0].Filter.Must - .Where(condition => condition.Field is { Match.Keyword.Length: > 0 }) - .ToDictionary( - condition => condition.Field.Key, - condition => condition.Field.Match.Keyword, - StringComparer.Ordinal); + /// Gets every Must field condition of the first prefetch leg, keyed by payload path. + public IReadOnlyDictionary DenseFilterKeywords => + Query is null + ? new Dictionary(StringComparer.Ordinal) + : Query.Prefetch[0].Filter.Must + .Where(condition => condition.Field is { Match.Keyword.Length: > 0 }) + .ToDictionary( + condition => condition.Field.Key, + condition => condition.Field.Match.Keyword, + StringComparer.Ordinal); - /// Gets the payload keys every required-term leg matches text on. - public IReadOnlyList LexicalKeys => - Query is null - ? [] - : [.. Query.Prefetch - .SelectMany(leg => leg.Filter.Must) - .Where(condition => condition.Field is { Match.Text.Length: > 0 }) - .Select(condition => condition.Field.Key)]; + /// Gets the payload keys every required-term leg matches text on. + public IReadOnlyList LexicalKeys => + Query is null + ? [] + : [.. Query.Prefetch + .SelectMany(leg => leg.Filter.Must) + .Where(condition => condition.Field is { Match.Text.Length: > 0 }) + .Select(condition => condition.Field.Key)]; - public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) - { - Query = query; - return Task.FromResult(_ranked); - } + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) + { + Query = query; + return Task.FromResult(_ranked); + } - public Task> RetrieveAsync( - string collection, IReadOnlyList ids, CancellationToken cancellationToken) - { - RetrievedIds.Add(ids); - return Task.FromResult(_fetched); - } + public Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken) + { + RetrievedIds.Add(ids); + return Task.FromResult(_fetched); + } - public Task> ScrollAsync( - string collection, Filter filter, uint limit, CancellationToken cancellationToken) - { - ScrollFilter = filter; - return Task.FromResult(_fetched); + public Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken) + { + ScrollFilter = filter; + return Task.FromResult(_fetched); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs index dc8830ed..4e1c22ec 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs @@ -2,38 +2,43 @@ using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; - -/// -/// A channel that answers one scripted result and records the filter and -/// limit it was called with. -/// -/// -/// Every other method throws. A facet read that ranks, retrieves by key or reads distinct values is -/// not a facet read, and the throw is what proves it: no embedding is generated and no vector is sent. -/// -internal sealed class FacetScrollChannel(params RetrievedPoint[] points) : IQdrantSearchChannel +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes { - private readonly IReadOnlyList _points = points; - - /// Gets the filter the last scroll carried, or when none has run. - public Filter? LastFilter { get; private set; } - - /// Gets the limit the last scroll carried. - public uint LastLimit { get; private set; } - - public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) => - throw new NotSupportedException("a facet read never ranks."); - - public Task> RetrieveAsync( - string collection, IReadOnlyList ids, CancellationToken cancellationToken) => - throw new NotSupportedException("a facet read never fetches by key."); - - public Task> ScrollAsync( - string collection, Filter filter, uint limit, CancellationToken cancellationToken) + /// + /// A channel that answers one scripted result and records the filter and + /// limit it was called with. + /// + /// + /// Every other method throws. A facet read that ranks, retrieves by key or reads distinct values is + /// not a facet read, and the throw is what proves it: no embedding is generated and no vector is sent. + /// + internal sealed class FacetScrollChannel(params RetrievedPoint[] points) : IQdrantSearchChannel { - LastFilter = filter; - LastLimit = limit; - return Task.FromResult(_points); + private readonly IReadOnlyList _points = points; + + /// Gets the filter the last scroll carried, or when none has run. + public Filter? LastFilter { get; private set; } + + /// Gets the limit the last scroll carried. + public uint LastLimit { get; private set; } + + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) + { + throw new NotSupportedException("a facet read never ranks."); + } + + public Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken) + { + throw new NotSupportedException("a facet read never fetches by key."); + } + + public Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken) + { + LastFilter = filter; + LastLimit = limit; + return Task.FromResult(_points); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs index 82f8345c..9010bc0b 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs @@ -1,32 +1,31 @@ using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; - -/// A channel that never answers in time, for the two tests a live server cannot serve. -internal sealed class HangingSearchChannel : IQdrantSearchChannel +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes { - private readonly TimeSpan _delay; - - public HangingSearchChannel(TimeSpan delay) => _delay = delay; - - public async Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) + /// A channel that never answers in time, for the two tests a live server cannot serve. + internal sealed class HangingSearchChannel(TimeSpan delay) : IQdrantSearchChannel { - await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); - return []; - } + private readonly TimeSpan _delay = delay; - public async Task> RetrieveAsync( - string collection, IReadOnlyList ids, CancellationToken cancellationToken) - { - await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); - return []; - } + public async Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) + { + await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); + return []; + } - public async Task> ScrollAsync( - string collection, Filter filter, uint limit, CancellationToken cancellationToken) - { - await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); - return []; + public async Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken) + { + await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); + return []; + } + + public async Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken) + { + await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); + return []; + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs index d35619a5..5532549a 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs @@ -1,38 +1,41 @@ using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; - -/// -/// A channel that answers one scripted result and records every id -/// was asked to fetch by key. -/// -/// -/// Exists for links.lookup: direct, which no live-server test in this repository exercises: -/// the synthetic and foreign corpora both key their points randomly, so only filter and -/// uuid5 ever run against a real collection. direct needs nothing a live server would -/// add — the branch under test is 's own id handling, not Qdrant's. -/// -internal sealed class RecordingSearchChannel : IQdrantSearchChannel +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes { - private readonly IReadOnlyList _queryResult; + /// + /// A channel that answers one scripted result and records every id + /// was asked to fetch by key. + /// + /// + /// Exists for links.lookup: direct, which no live-server test in this repository exercises: + /// the synthetic and foreign corpora both key their points randomly, so only filter and + /// uuid5 ever run against a real collection. direct needs nothing a live server would + /// add — the branch under test is 's own id handling, not Qdrant's. + /// + internal sealed class RecordingSearchChannel(IReadOnlyList queryResult) : IQdrantSearchChannel + { + private readonly IReadOnlyList _queryResult = queryResult; - public RecordingSearchChannel(IReadOnlyList queryResult) => _queryResult = queryResult; + /// Gets every id set was called with, in call order. + public List> RetrievedIds { get; } = []; - /// Gets every id set was called with, in call order. - public List> RetrievedIds { get; } = []; + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) + { + return Task.FromResult(_queryResult); + } - public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) => - Task.FromResult(_queryResult); + public Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken) + { + RetrievedIds.Add(ids); + return Task.FromResult>([]); + } - public Task> RetrieveAsync( - string collection, IReadOnlyList ids, CancellationToken cancellationToken) - { - RetrievedIds.Add(ids); - return Task.FromResult>([]); + public Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken) + { + throw new NotSupportedException("These tests drive links.lookup: direct, which never scrolls."); + } } - - public Task> ScrollAsync( - string collection, Filter filter, uint limit, CancellationToken cancellationToken) => - throw new NotSupportedException("These tests drive links.lookup: direct, which never scrolls."); } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FieldsPointMapperTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FieldsPointMapperTests.cs index a76553f0..c7b3e9bd 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FieldsPointMapperTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FieldsPointMapperTests.cs @@ -1,144 +1,148 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; +using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// The built-in mapper is the fields: block applied to a neutral point. No Qdrant server: -/// the input is already vendor-free. -/// -/// -/// Every fixture below writes the block out. There is nothing to leave blank: an empty block maps -/// no role at all, which these tests prove last. -/// -public sealed class FieldsPointMapperTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [Fact] - public void Map_EveryRoleMapped_ReadsThemAllIncludingDottedPaths() + /// + /// The built-in mapper is the fields: block applied to a neutral point. No Qdrant server: + /// the input is already vendor-free. + /// + /// + /// Every fixture below writes the block out. There is nothing to leave blank: an empty block maps + /// no role at all, which these tests prove last. + /// + public sealed class FieldsPointMapperTests { - var mapper = new FieldsPointMapper(Mapped); - var point = new KnowledgePoint + [Fact] + public void Map_EveryRoleMapped_ReadsThemAllIncludingDottedPaths() { - PointId = "11111111-2222-3333-4444-555555555555", - Score = 0.5, - Payload = new Dictionary(StringComparer.Ordinal) + FieldsPointMapper mapper = new(Mapped); + KnowledgePoint point = new() { - ["card_id"] = "ct900-e33-incline-err", - ["body"] = "err e33 incline motor error", - ["authority"] = 3L, - ["source"] = new Dictionary(StringComparer.Ordinal) + PointId = "11111111-2222-3333-4444-555555555555", + Score = 0.5, + Payload = new Dictionary(StringComparer.Ordinal) { - ["ref"] = "ct900-om", - ["locator"] = "p.27", + ["card_id"] = "ct900-e33-incline-err", + ["body"] = "err e33 incline motor error", + ["authority"] = 3L, + ["source"] = new Dictionary(StringComparer.Ordinal) + { + ["ref"] = "ct900-om", + ["locator"] = "p.27", + }, }, - }, - }; - - var card = mapper.Map(point); - - Assert.NotNull(card); - Assert.Equal("ct900-e33-incline-err", card!.CardId); - Assert.Equal("err e33 incline motor error", card.Text); - Assert.Equal("ct900-om", card.SourceRef); - Assert.Equal("p.27", card.SourceLocator); - Assert.Equal(3, card.Authority); - Assert.Equal(0.5, card.Score); - Assert.False(card.ViaLink); - } - - [Fact] - public void Map_IdFieldAbsentFromThePayload_FallsBackToThePointKey() - { - var mapper = new FieldsPointMapper(Mapped); - var point = new KnowledgePoint + }; + + KnowledgeCard? card = mapper.Map(point); + + Assert.NotNull(card); + Assert.Equal("ct900-e33-incline-err", card!.CardId); + Assert.Equal("err e33 incline motor error", card.Text); + Assert.Equal("ct900-om", card.SourceRef); + Assert.Equal("p.27", card.SourceLocator); + Assert.Equal(3, card.Authority); + Assert.Equal(0.5, card.Score); + Assert.False(card.ViaLink); + } + + [Fact] + public void Map_IdFieldAbsentFromThePayload_FallsBackToThePointKey() { - PointId = "point-key-7", - Payload = new Dictionary(StringComparer.Ordinal) { ["body"] = "text" }, - }; + FieldsPointMapper mapper = new(Mapped); + KnowledgePoint point = new() + { + PointId = "point-key-7", + Payload = new Dictionary(StringComparer.Ordinal) { ["body"] = "text" }, + }; - var card = mapper.Map(point); + KnowledgeCard? card = mapper.Map(point); - Assert.Equal("point-key-7", card!.CardId); - Assert.Equal(string.Empty, card.SourceRef); - Assert.Equal(string.Empty, card.SourceLocator); - Assert.Null(card.Authority); - } + Assert.Equal("point-key-7", card!.CardId); + Assert.Equal(string.Empty, card.SourceRef); + Assert.Equal(string.Empty, card.SourceLocator); + Assert.Null(card.Authority); + } - [Fact] - public void Map_NonStringBody_ReadsEmptyRatherThanThrowing() - { - var mapper = new FieldsPointMapper(Mapped); - var point = new KnowledgePoint + [Fact] + public void Map_NonStringBody_ReadsEmptyRatherThanThrowing() { - PointId = "p", - Payload = new Dictionary(StringComparer.Ordinal) { ["body"] = 42L }, - }; + FieldsPointMapper mapper = new(Mapped); + KnowledgePoint point = new() + { + PointId = "p", + Payload = new Dictionary(StringComparer.Ordinal) { ["body"] = 42L }, + }; - Assert.Equal(string.Empty, mapper.Map(point)!.Text); - } + Assert.Equal(string.Empty, mapper.Map(point)!.Text); + } - [Fact] - public void Map_NothingMapped_ReadsNoRoleAtAll() - { - // The proof that no name is built in. The payload below carries every name the old defaults - // used, and a block that names none of them reads none of them. - var mapper = new FieldsPointMapper(new KnowledgeFieldsConfiguration()); - var point = new KnowledgePoint + [Fact] + public void Map_NothingMapped_ReadsNoRoleAtAll() { - PointId = "point-key-7", - Score = 0.5, - Payload = new Dictionary(StringComparer.Ordinal) + // The proof that no name is built in. The payload below carries every name the old defaults + // used, and a block that names none of them reads none of them. + FieldsPointMapper mapper = new(new KnowledgeFieldsConfiguration()); + KnowledgePoint point = new() { - ["card_id"] = "ct900-e33-incline-err", - ["body"] = "err e33 incline motor error", - ["authority"] = 3L, - }, - }; + PointId = "point-key-7", + Score = 0.5, + Payload = new Dictionary(StringComparer.Ordinal) + { + ["card_id"] = "ct900-e33-incline-err", + ["body"] = "err e33 incline motor error", + ["authority"] = 3L, + }, + }; - var card = mapper.Map(point); + KnowledgeCard? card = mapper.Map(point); - Assert.Equal("point-key-7", card!.CardId); - Assert.Equal(string.Empty, card.Text); - Assert.Null(card.Authority); - } + Assert.Equal("point-key-7", card!.CardId); + Assert.Equal(string.Empty, card.Text); + Assert.Null(card.Authority); + } - [Fact] - public void Name_IsFields() - => Assert.Equal("fields", new FieldsPointMapper(Mapped).Name); + [Fact] + public void Name_IsFields() + { + Assert.Equal("fields", new FieldsPointMapper(Mapped).Name); + } - [Fact] - public void Map_AlwaysCarriesTheWholePayloadInExtras() - { - // The escape hatch. A collection carries fields the six roles do not name, and a card that - // dropped them would force a second round trip to read one. - var mapper = new FieldsPointMapper(Mapped); - var point = new KnowledgePoint + [Fact] + public void Map_AlwaysCarriesTheWholePayloadInExtras() { - PointId = "p", - Payload = new Dictionary(StringComparer.Ordinal) + // The escape hatch. A collection carries fields the six roles do not name, and a card that + // dropped them would force a second round trip to read one. + FieldsPointMapper mapper = new(Mapped); + KnowledgePoint point = new() { - ["body"] = "text", - ["revision"] = "rev C", - ["effective_date"] = "2026-01-01", - }, - }; + PointId = "p", + Payload = new Dictionary(StringComparer.Ordinal) + { + ["body"] = "text", + ["revision"] = "rev C", + ["effective_date"] = "2026-01-01", + }, + }; - var card = mapper.Map(point)!; + KnowledgeCard card = mapper.Map(point)!; - Assert.Equal("rev C", card.Extras["revision"]); - Assert.Equal("2026-01-01", card.Extras["effective_date"]); - } + Assert.Equal("rev C", card.Extras["revision"]); + Assert.Equal("2026-01-01", card.Extras["effective_date"]); + } - /// A block that names every role, written out because nothing fills one in. - private static KnowledgeFieldsConfiguration Mapped => new() - { - Id = "card_id", - Body = "body", - Lexical = "text", - Source = "source.ref", - Locator = "source.locator", - Authority = "authority", - }; + /// A block that names every role, written out because nothing fills one in. + private static KnowledgeFieldsConfiguration Mapped => new() + { + Id = "card_id", + Body = "body", + Lexical = "text", + Source = "source.ref", + Locator = "source.locator", + Authority = "authority", + }; + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignCorpus.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignCorpus.cs index 54dbf42c..6c33207b 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignCorpus.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignCorpus.cs @@ -1,94 +1,98 @@ using Qdrant.Client; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// A collection that shares no name with the synthetic corpus, and none with AgentCore either. -/// -/// -/// Different vector name, flat top-level facets, a different id field, random point keys, and a -/// links field pointing at ids that no formula can derive. Every earlier test renamed one thing at -/// a time against the synthetic corpus, so each could still have passed on a store that read a -/// default somewhere; this one cannot. -/// -public static class ForeignCorpus +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// The vector width. - public const int Dim = 8; - - /// How many documents the corpus holds. - public const int Count = 6; - - /// The vector every query embeds to. Document 0 is nearest. - public static float[] QueryVector() + /// + /// A collection that shares no name with the synthetic corpus, and none with AgentCore either. + /// + /// + /// Different vector name, flat top-level facets, a different id field, random point keys, and a + /// links field pointing at ids that no formula can derive. Every earlier test renamed one thing at + /// a time against the synthetic corpus, so each could still have passed on a store that read a + /// default somewhere; this one cannot. + /// + public static class ForeignCorpus { - var v = new float[Dim]; - v[0] = 1f; - return v; - } + /// The vector width. + public const int Dim = 8; - /// The id of document . - public static string Id(int index) => $"DOC-{index:00}"; + /// How many documents the corpus holds. + public const int Count = 6; - /// Creates the collection and fills it. Point keys are random, so no formula derives them. - public static async Task CreateAsync( - QdrantClient client, string collection, CancellationToken cancellationToken) - { - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["embedding"] = new VectorParams { Size = Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: cancellationToken); - - await client.CreatePayloadIndexAsync( - collection, "doc_id", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - await client.CreatePayloadIndexAsync( - collection, "content", PayloadSchemaType.Text, cancellationToken: cancellationToken); - await client.CreatePayloadIndexAsync( - collection, "region", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - - var points = new List(Count); + /// The vector every query embeds to. Document 0 is nearest. + public static float[] QueryVector() + { + float[] v = new float[Dim]; + v[0] = 1f; + return v; + } - for (var i = 0; i < Count; i++) + /// The id of document . + public static string Id(int index) { - var angle = i * 0.2; - var vector = new float[Dim]; - vector[0] = (float)Math.Cos(angle); - vector[1] = (float)Math.Sin(angle); + return $"DOC-{index:00}"; + } - var point = new PointStruct - { - // Random, unrelated to doc_id. Only links.lookup: filter can find these. - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors + /// Creates the collection and fills it. Point keys are random, so no formula derives them. + public static async Task CreateAsync( + QdrantClient client, string collection, CancellationToken cancellationToken) + { + await client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap { - Vectors_ = new NamedVectors { Vectors = { ["embedding"] = vector } }, + Map = { ["embedding"] = new VectorParams { Size = Dim, Distance = Distance.Cosine } }, }, - }; + cancellationToken: cancellationToken); + + _ = await client.CreatePayloadIndexAsync( + collection, "doc_id", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); + _ = await client.CreatePayloadIndexAsync( + collection, "content", PayloadSchemaType.Text, cancellationToken: cancellationToken); + _ = await client.CreatePayloadIndexAsync( + collection, "region", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - point.Payload["doc_id"] = Id(i); - point.Payload["content"] = $"document {Id(i)} about warranty returns and shipping"; - point.Payload["origin"] = $"handbook-{i}"; - point.Payload["page"] = $"s.{i}"; - point.Payload["trust"] = 2; - point.Payload["region"] = i < 3 ? "emea" : "amer"; + List points = new(Count); - // Document 0, the nearest, links to the last one -- which is in the other region, so a - // scoped search must not show it. - point.Payload["related"] = new Value + for (int i = 0; i < Count; i++) { - ListValue = new ListValue + double angle = i * 0.2; + float[] vector = new float[Dim]; + vector[0] = (float)Math.Cos(angle); + vector[1] = (float)Math.Sin(angle); + + PointStruct point = new() { - Values = { i == 0 ? [new Value { StringValue = Id(Count - 1) }] : [] }, - }, - }; + // Random, unrelated to doc_id. Only links.lookup: filter can find these. + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = new Vectors + { + Vectors_ = new NamedVectors { Vectors = { ["embedding"] = vector } }, + }, + }; - points.Add(point); - } + point.Payload["doc_id"] = Id(i); + point.Payload["content"] = $"document {Id(i)} about warranty returns and shipping"; + point.Payload["origin"] = $"handbook-{i}"; + point.Payload["page"] = $"s.{i}"; + point.Payload["trust"] = 2; + point.Payload["region"] = i < 3 ? "emea" : "amer"; + + // Document 0, the nearest, links to the last one -- which is in the other region, so a + // scoped search must not show it. + point.Payload["related"] = new Value + { + ListValue = new ListValue + { + Values = { i == 0 ? [new Value { StringValue = Id(Count - 1) }] : [] }, + }, + }; - await client.UpsertAsync(collection, points, cancellationToken: cancellationToken); + points.Add(point); + } + + _ = await client.UpsertAsync(collection, points, cancellationToken: cancellationToken); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignSchemaTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignSchemaTests.cs index 1bb39616..027f95f0 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignSchemaTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ForeignSchemaTests.cs @@ -1,257 +1,271 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; +using AgentCore.Application.Ports; using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; using Qdrant.Client; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -public sealed class ForeignCorpusFixture : IAsyncLifetime +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - public string Name { get; } = $"foreign-{Guid.NewGuid():N}"; - - public QdrantClient Client { get; private set; } = null!; - - public async ValueTask InitializeAsync() + public sealed class ForeignCorpusFixture : IAsyncLifetime { - if (!QdrantServer.IsConfigured) - { - return; - } + public string Name { get; } = $"foreign-{Guid.NewGuid():N}"; - Client = QdrantServer.CreateClient(); - await ForeignCorpus.CreateAsync(Client, Name, TestContext.Current.CancellationToken); - } + public QdrantClient Client { get; private set; } = null!; - public async ValueTask DisposeAsync() - { - if (Client is null) + public async ValueTask InitializeAsync() { - return; - } + if (!QdrantServer.IsConfigured) + { + return; + } - try - { - await Client.DeleteCollectionAsync(Name); + Client = QdrantServer.CreateClient(); + await ForeignCorpus.CreateAsync(Client, Name, TestContext.Current.CancellationToken); } - finally + + public async ValueTask DisposeAsync() { - Client.Dispose(); + if (Client is null) + { + return; + } + + try + { + await Client.DeleteCollectionAsync(Name); + } + finally + { + Client.Dispose(); + } } } -} -/// -/// The whole path over a collection that shares no name with the synthetic corpus. -/// -[Collection(QdrantServerCollection.Name)] -public sealed class ForeignSchemaTests : IClassFixture -{ - private readonly ForeignCorpusFixture _corpus; - - public ForeignSchemaTests(ForeignCorpusFixture corpus) => _corpus = corpus; - - [QdrantFact] - public async Task Adapter_StartsAgainstAForeignCollection() + /// + /// The whole path over a collection that shares no name with the synthetic corpus. + /// + [Collection(QdrantServerCollection.Name)] + public sealed class ForeignSchemaTests(ForeignCorpusFixture corpus) : IClassFixture { - var store = await Adapter().CreateSearchAsync( - Entry(), secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken); + private readonly ForeignCorpusFixture _corpus = corpus; - Assert.NotNull(store); - (store as IDisposable)?.Dispose(); - } + [QdrantFact] + public async Task Adapter_StartsAgainstAForeignCollection() + { + IKnowledgeRetrievalPort store = await Adapter().CreateSearchAsync( + Entry(), secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken); - [QdrantFact] - public async Task Search_MapsEveryRenamedField() - { - var card = (await Store().SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken))[0]; - - Assert.StartsWith("DOC-", card.CardId, StringComparison.Ordinal); - Assert.Contains("warranty", card.Text, StringComparison.Ordinal); - Assert.StartsWith("handbook-", card.SourceRef, StringComparison.Ordinal); - Assert.StartsWith("s.", card.SourceLocator, StringComparison.Ordinal); - Assert.Equal(2, card.Authority); - } + Assert.NotNull(store); + (store as IDisposable)?.Dispose(); + } - [QdrantFact] - public async Task Search_FollowsLinksByFilterAcrossRandomPointKeys() - { - var cards = await Store().SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task Search_MapsEveryRenamedField() + { + KnowledgeCard card = (await Store().SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken))[0]; + + Assert.StartsWith("DOC-", card.CardId, StringComparison.Ordinal); + Assert.Contains("warranty", card.Text, StringComparison.Ordinal); + Assert.StartsWith("handbook-", card.SourceRef, StringComparison.Ordinal); + Assert.StartsWith("s.", card.SourceLocator, StringComparison.Ordinal); + Assert.Equal(2, card.Authority); + } - var linked = Assert.Single(cards, card => card.ViaLink); - Assert.Equal(ForeignCorpus.Id(ForeignCorpus.Count - 1), linked.CardId); - } + [QdrantFact] + public async Task Search_FollowsLinksByFilterAcrossRandomPointKeys() + { + IReadOnlyList cards = await Store().SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken); - [QdrantFact] - public async Task Search_TopLevelFacetScopeFiltersAndReChecksLinks() - { - // Document 0 is emea and links to the last document, which is amer. The scope must keep the - // ranked emea documents and drop the linked amer one. - var scope = new KnowledgeScope + KnowledgeCard linked = Assert.Single(cards, card => card.ViaLink); + Assert.Equal(ForeignCorpus.Id(ForeignCorpus.Count - 1), linked.CardId); + } + + [QdrantFact] + public async Task Search_TopLevelFacetScopeFiltersAndReChecksLinks() { - Facets = new Dictionary(StringComparer.Ordinal) { ["region"] = "emea" }, - }; + // Document 0 is emea and links to the last document, which is amer. The scope must keep the + // ranked emea documents and drop the linked amer one. + KnowledgeScope scope = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["region"] = "emea" }, + }; - var cards = await Store(scoped: true).SearchAsync( - "warranty returns", scope, TestContext.Current.CancellationToken); + IReadOnlyList cards = await Store(scoped: true).SearchAsync( + "warranty returns", scope, TestContext.Current.CancellationToken); - Assert.NotEmpty(cards); - Assert.All(cards, card => Assert.False(card.ViaLink)); - } + Assert.NotEmpty(cards); + Assert.All(cards, card => Assert.False(card.ViaLink)); + } - [QdrantFact] - public async Task Search_Limit_IsHonouredOnAForeignCollection() - { - // Limit, floor and fusion are the same code for every collection, but "the same code" is a - // claim about the store, and the store reads its keys off this document. Proving them only - // against the kb-shaped corpus leaves the naming and the ranking entangled. - var cards = await Store(limit: 2).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task Search_Limit_IsHonouredOnAForeignCollection() + { + // Limit, floor and fusion are the same code for every collection, but "the same code" is a + // claim about the store, and the store reads its keys off this document. Proving them only + // against the kb-shaped corpus leaves the naming and the ranking entangled. + IReadOnlyList cards = await Store(limit: 2).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken); - Assert.Equal(2, cards.Count(card => !card.ViaLink)); - } + Assert.Equal(2, cards.Count(card => !card.ViaLink)); + } - [QdrantFact] - public async Task Search_ScoreFloor_DropsEverythingBelowIt() - { - var all = await Store(limit: 10, floor: 0.0).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken); - var floored = await Store(limit: 10, floor: 0.25).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task Search_ScoreFloor_DropsEverythingBelowIt() + { + IReadOnlyList all = await Store(limit: 10, floor: 0.0).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken); + IReadOnlyList floored = await Store(limit: 10, floor: 0.25).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken); - Assert.All(floored.Where(card => card.Score is not null), card => Assert.True(card.Score >= 0.25)); - Assert.True(floored.Count <= all.Count); - } + Assert.All(floored.Where(card => card.Score is not null), card => Assert.True(card.Score >= 0.25)); + Assert.True(floored.Count <= all.Count); + } - [QdrantFact] - public async Task Search_NoLinksBlock_NeverExpands() - { - var cards = await Store(links: false).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task Search_NoLinksBlock_NeverExpands() + { + IReadOnlyList cards = await Store(links: false).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken); - Assert.NotEmpty(cards); - Assert.All(cards, card => Assert.False(card.ViaLink)); - } + Assert.NotEmpty(cards); + Assert.All(cards, card => Assert.False(card.ViaLink)); + } - [QdrantFact] - public async Task Search_TheIdRoleUnmapped_UsesThePointKey() - { - // The foreign corpus keys its points randomly, so a card id that is a GUID proves the store - // fell back to the key rather than to a field name of its own. - // - // Links go with it: every lookup mode resolves a linked id through fields.id, so links plus - // an unmapped id is a contradiction the store now refuses outright. - var entry = Entry() with { Fields = BaseEntry().Fields! with { Id = null }, Links = null }; + [QdrantFact] + public async Task Search_TheIdRoleUnmapped_UsesThePointKey() + { + // The foreign corpus keys its points randomly, so a card id that is a GUID proves the store + // fell back to the key rather than to a field name of its own. + // + // Links go with it: every lookup mode resolves a linked id through fields.id, so links plus + // an unmapped id is a contradiction the store now refuses outright. + KnowledgeProviderConfiguration entry = Entry() with { Fields = BaseEntry().Fields! with { Id = null }, Links = null }; - var card = (await StoreFrom(entry).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken))[0]; + KnowledgeCard card = (await StoreFrom(entry).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken))[0]; - Assert.True(Guid.TryParse(card.CardId, out _)); - } + Assert.True(Guid.TryParse(card.CardId, out _)); + } - [QdrantFact] - public async Task Search_TheLexicalRoleUnmapped_StillRanksByVector() - { - var entry = Entry() with { Fields = BaseEntry().Fields! with { Lexical = null } }; + [QdrantFact] + public async Task Search_TheLexicalRoleUnmapped_StillRanksByVector() + { + KnowledgeProviderConfiguration entry = Entry() with { Fields = BaseEntry().Fields! with { Lexical = null } }; - var cards = await StoreFrom(entry).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken); + IReadOnlyList cards = await StoreFrom(entry).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken); - Assert.NotEmpty(cards); - } + Assert.NotEmpty(cards); + } - [QdrantFact] - public async Task Search_TheCitationRolesUnmapped_LeaveThemEmpty() - { - var entry = Entry() with + [QdrantFact] + public async Task Search_TheCitationRolesUnmapped_LeaveThemEmpty() { - Fields = BaseEntry().Fields! with { Source = null, Locator = null, Authority = null }, - }; + KnowledgeProviderConfiguration entry = Entry() with + { + Fields = BaseEntry().Fields! with { Source = null, Locator = null, Authority = null }, + }; - var card = (await StoreFrom(entry).SearchAsync( - "warranty returns", null, TestContext.Current.CancellationToken))[0]; + KnowledgeCard card = (await StoreFrom(entry).SearchAsync( + "warranty returns", null, TestContext.Current.CancellationToken))[0]; - Assert.Equal(string.Empty, card.SourceRef); - Assert.Equal(string.Empty, card.SourceLocator); - Assert.Null(card.Authority); - } + Assert.Equal(string.Empty, card.SourceRef); + Assert.Equal(string.Empty, card.SourceLocator); + Assert.Null(card.Authority); + } - [QdrantFact] - public void Store_LinksWithNoIdMapped_IsRefusedOutright() - { - var entry = Entry() with { Fields = BaseEntry().Fields! with { Id = null } }; + [QdrantFact] + public void Store_LinksWithNoIdMapped_IsRefusedOutright() + { + KnowledgeProviderConfiguration entry = Entry() with { Fields = BaseEntry().Fields! with { Id = null } }; - var thrown = Assert.Throws(() => StoreFrom(entry)); + ArgumentException thrown = Assert.Throws(() => StoreFrom(entry)); - Assert.Contains("fields.id", thrown.Message, StringComparison.Ordinal); - } + Assert.Contains("fields.id", thrown.Message, StringComparison.Ordinal); + } - [QdrantFact] - public async Task Search_ScopedWithNoAmbient_Throws() - { - var store = Store(scoped: true); + [QdrantFact] + public async Task Search_ScopedWithNoAmbient_Throws() + { + QdrantKnowledgeStore store = Store(scoped: true); - await Assert.ThrowsAsync( - async () => await store.SearchAsync("warranty returns", null, TestContext.Current.CancellationToken)); - } + _ = await Assert.ThrowsAsync( + async () => await store.SearchAsync("warranty returns", null, TestContext.Current.CancellationToken)); + } - private static KnowledgeProviderConfiguration BaseEntry() => new() - { - Kind = QdrantKnowledgeAdapter.ProviderKind, - Collection = "replaced-per-fixture", - Vector = "embedding", - Fields = new KnowledgeFieldsConfiguration + private static KnowledgeProviderConfiguration BaseEntry() { - Id = "doc_id", - Body = "content", - Lexical = "content", - Source = "origin", - Locator = "page", - Authority = "trust", - }, - Scope = new KnowledgeScopeConfiguration { Template = "{key}" }, - Links = new KnowledgeLinksConfiguration + return new() + { + Kind = QdrantKnowledgeAdapter.ProviderKind, + Collection = "replaced-per-fixture", + Vector = "embedding", + Fields = new KnowledgeFieldsConfiguration + { + Id = "doc_id", + Body = "content", + Lexical = "content", + Source = "origin", + Locator = "page", + Authority = "trust", + }, + Scope = new KnowledgeScopeConfiguration { Template = "{key}" }, + Links = new KnowledgeLinksConfiguration + { + Field = "related", + Lookup = KnowledgeLinkLookup.Filter, + }, + Analyzer = NoQueryAnalyzer.AnalyzerName, + }; + } + + private KnowledgeProviderConfiguration Entry() { - Field = "related", - Lookup = KnowledgeLinkLookup.Filter, - }, - Analyzer = NoQueryAnalyzer.AnalyzerName, - }; + return BaseEntry() with { Collection = _corpus.Name }; + } - private KnowledgeProviderConfiguration Entry() => BaseEntry() with { Collection = _corpus.Name }; + private static QdrantKnowledgeAdapter Adapter() + { + return new(_ => QdrantServer.CreateClient()); + } - private static QdrantKnowledgeAdapter Adapter() => new(_ => QdrantServer.CreateClient()); + private static FakeEmbeddingGenerator Embedder() + { + return new(ForeignCorpus.QueryVector()); + } - private static FakeEmbeddingGenerator Embedder() => new(ForeignCorpus.QueryVector()); + private QdrantKnowledgeStore Store( + bool scoped = false, int limit = 3, double floor = 0.0, bool links = true) + { + KnowledgeProviderConfiguration entry = Entry(); - private QdrantKnowledgeStore Store( - bool scoped = false, int limit = 3, double floor = 0.0, bool links = true) - { - var entry = Entry(); + return StoreFrom(links ? entry : entry with { Links = null }, scoped, limit, floor); + } - return StoreFrom(links ? entry : entry with { Links = null }, scoped, limit, floor); + private QdrantKnowledgeStore StoreFrom( + KnowledgeProviderConfiguration entry, bool scoped = false, int limit = 3, double floor = 0.0) + { + return new( + new QdrantSearchChannel(_corpus.Client), + Embedder(), + new QdrantKnowledgeStoreOptions + { + Collection = entry.Collection, + Scoped = scoped, + VectorName = entry.Vector, + Fields = entry.Fields, + ScopeTemplate = entry.Scope.Template, + Links = entry.Links, + Analyzer = new NoQueryAnalyzer(), + Limit = limit, + ScoreFloor = floor, + }); + } } - - private QdrantKnowledgeStore StoreFrom( - KnowledgeProviderConfiguration entry, bool scoped = false, int limit = 3, double floor = 0.0) - => new( - new QdrantSearchChannel(_corpus.Client), - Embedder(), - new QdrantKnowledgeStoreOptions - { - Collection = entry.Collection, - Scoped = scoped, - VectorName = entry.Vector, - Fields = entry.Fields, - ScopeTemplate = entry.Scope.Template, - Links = entry.Links, - Analyzer = new NoQueryAnalyzer(), - Limit = limit, - ScoreFloor = floor, - }); } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileCorpus.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileCorpus.cs index f234de93..d7694543 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileCorpus.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileCorpus.cs @@ -1,89 +1,100 @@ using Qdrant.Client; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// A collection built the ways a real one goes wrong. -/// -/// -/// -/// and are both well-formed: different -/// naming, same discipline. Neither can show what happens when a collection does not carry what -/// the document claims it carries, and that is the case an operator actually meets — an ingester -/// renamed a field, or writes a body as chunks, or never built the text index. -/// -/// -/// Every failure these provoke must be loud AT STARTUP. A knowledge base that silently answers -/// with empty cards is worse than one that refuses to open, because nothing downstream can tell -/// the difference between "no answer" and "no knowledge base". -/// -/// -public static class HostileCorpus +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// The vector width. - public const int Dim = 8; - - /// The vector every query embeds to. - public static float[] QueryVector() + /// + /// A collection built the ways a real one goes wrong. + /// + /// + /// + /// and are both well-formed: different + /// naming, same discipline. Neither can show what happens when a collection does not carry what + /// the document claims it carries, and that is the case an operator actually meets — an ingester + /// renamed a field, or writes a body as chunks, or never built the text index. + /// + /// + /// Every failure these provoke must be loud AT STARTUP. A knowledge base that silently answers + /// with empty cards is worse than one that refuses to open, because nothing downstream can tell + /// the difference between "no answer" and "no knowledge base". + /// + /// + public static class HostileCorpus { - var v = new float[Dim]; - v[0] = 1f; - return v; - } + /// The vector width. + public const int Dim = 8; + + /// The vector every query embeds to. + public static float[] QueryVector() + { + float[] v = new float[Dim]; + v[0] = 1f; + return v; + } - /// Points keyed by NUMBER, not by uuid. No uuid5 or direct lookup can ever address one. - public static Task NumericKeysAsync(QdrantClient client, string collection, CancellationToken cancellationToken) - => BuildAsync(client, collection, point => + /// Points keyed by NUMBER, not by uuid. No uuid5 or direct lookup can ever address one. + public static Task NumericKeysAsync(QdrantClient client, string collection, CancellationToken cancellationToken) { - point.Id = new PointId { Num = 17 }; - point.Payload["doc_id"] = "DOC-01"; - point.Payload["content"] = "a numerically keyed point"; - point.Payload["related"] = List("DOC-99"); - }, cancellationToken); + return BuildAsync(client, collection, point => + { + point.Id = new PointId { Num = 17 }; + point.Payload["doc_id"] = "DOC-01"; + point.Payload["content"] = "a numerically keyed point"; + point.Payload["related"] = List("DOC-99"); + }, cancellationToken); + } - /// A body written as a LIST of chunks rather than one string. - public static Task ChunkedBodyAsync(QdrantClient client, string collection, CancellationToken cancellationToken) - => BuildAsync(client, collection, point => + /// A body written as a LIST of chunks rather than one string. + public static Task ChunkedBodyAsync(QdrantClient client, string collection, CancellationToken cancellationToken) { - point.Id = new PointId { Uuid = Guid.NewGuid().ToString() }; - point.Payload["doc_id"] = "DOC-01"; - point.Payload["content"] = List("first chunk", "second chunk"); - }, cancellationToken); + return BuildAsync(client, collection, point => + { + point.Id = new PointId { Uuid = Guid.NewGuid().ToString() }; + point.Payload["doc_id"] = "DOC-01"; + point.Payload["content"] = List("first chunk", "second chunk"); + }, cancellationToken); + } - /// A well-formed point that simply does not carry the citation roles. - public static Task NoCitationFieldsAsync(QdrantClient client, string collection, CancellationToken cancellationToken) - => BuildAsync(client, collection, point => + /// A well-formed point that simply does not carry the citation roles. + public static Task NoCitationFieldsAsync(QdrantClient client, string collection, CancellationToken cancellationToken) { - point.Id = new PointId { Uuid = Guid.NewGuid().ToString() }; - point.Payload["doc_id"] = "DOC-01"; - point.Payload["content"] = "a point with no origin and no page"; - }, cancellationToken); + return BuildAsync(client, collection, point => + { + point.Id = new PointId { Uuid = Guid.NewGuid().ToString() }; + point.Payload["doc_id"] = "DOC-01"; + point.Payload["content"] = "a point with no origin and no page"; + }, cancellationToken); + } - /// An authority written as TEXT where the document maps a trust rank. - public static Task TextAuthorityAsync(QdrantClient client, string collection, CancellationToken cancellationToken) - => BuildAsync(client, collection, point => + /// An authority written as TEXT where the document maps a trust rank. + public static Task TextAuthorityAsync(QdrantClient client, string collection, CancellationToken cancellationToken) { - point.Id = new PointId { Uuid = Guid.NewGuid().ToString() }; - point.Payload["doc_id"] = "DOC-01"; - point.Payload["content"] = "a point whose trust is a word"; - point.Payload["trust"] = "high"; - }, cancellationToken); + return BuildAsync(client, collection, point => + { + point.Id = new PointId { Uuid = Guid.NewGuid().ToString() }; + point.Payload["doc_id"] = "DOC-01"; + point.Payload["content"] = "a point whose trust is a word"; + point.Payload["trust"] = "high"; + }, cancellationToken); + } - private static Value List(params string[] values) - => new() { ListValue = new ListValue { Values = { values.Select(v => new Value { StringValue = v }) } } }; + private static Value List(params string[] values) + { + return new() { ListValue = new ListValue { Values = { values.Select(v => new Value { StringValue = v }) } } }; + } - private static async Task BuildAsync( - QdrantClient client, string collection, Action fill, CancellationToken cancellationToken) - { - await client.CreateCollectionAsync( - collection, - new VectorParams { Size = Dim, Distance = Distance.Cosine }, - cancellationToken: cancellationToken); + private static async Task BuildAsync( + QdrantClient client, string collection, Action fill, CancellationToken cancellationToken) + { + await client.CreateCollectionAsync( + collection, + new VectorParams { Size = Dim, Distance = Distance.Cosine }, + cancellationToken: cancellationToken); - var point = new PointStruct { Vectors = QueryVector() }; - fill(point); + PointStruct point = new() { Vectors = QueryVector() }; + fill(point); - await client.UpsertAsync(collection, [point], cancellationToken: cancellationToken); + _ = await client.UpsertAsync(collection, [point], cancellationToken: cancellationToken); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileSchemaTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileSchemaTests.cs index 7704cb44..881910c9 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileSchemaTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/HostileSchemaTests.cs @@ -4,163 +4,173 @@ using Qdrant.Client; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// A collection that does not carry what the document claims must fail the START. -/// -/// -/// The alternative is not an exception later — it is no exception at all. Every unmapped or -/// mismapped role reads as absent, so the store opens, every search answers, and every card -/// reaches the model with an empty body or a blank citation. Nothing downstream can tell that -/// apart from a knowledge base that simply had no match. -/// -[Collection(QdrantServerCollection.Name)] -public sealed class HostileSchemaTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [QdrantFact] - public async Task NumericPointKeys_UnderUuid5Links_FailTheStartAndPointAtFilter() + /// + /// A collection that does not carry what the document claims must fail the START. + /// + /// + /// The alternative is not an exception later — it is no exception at all. Every unmapped or + /// mismapped role reads as absent, so the store opens, every search answers, and every card + /// reaches the model with an empty body or a blank citation. Nothing downstream can tell that + /// apart from a knowledge base that simply had no match. + /// + [Collection(QdrantServerCollection.Name)] + public sealed class HostileSchemaTests { - // Only the roles this collection really carries. The payload proof runs BEFORE the - // point-key proof, so a document that also mismapped a citation role would fail on that - // first and never reach the branch under test here. - await Against( - HostileCorpus.NumericKeysAsync, - Entry() with - { - Fields = Fields with { Source = null, Locator = null, Authority = null }, - Links = new KnowledgeLinksConfiguration + [QdrantFact] + public async Task NumericPointKeys_UnderUuid5Links_FailTheStartAndPointAtFilter() + { + // Only the roles this collection really carries. The payload proof runs BEFORE the + // point-key proof, so a document that also mismapped a citation role would fail on that + // first and never reach the branch under test here. + await Against( + HostileCorpus.NumericKeysAsync, + Entry() with { - Field = "related", - Lookup = KnowledgeLinkLookup.Uuid5, + Fields = Fields with { Source = null, Locator = null, Authority = null }, + Links = new KnowledgeLinksConfiguration + { + Field = "related", + Lookup = KnowledgeLinkLookup.Uuid5, + }, }, - }, - message => - { - Assert.Contains("keyed by number", message, StringComparison.Ordinal); - Assert.Contains("links.lookup: filter", message, StringComparison.Ordinal); - }); - } - - [QdrantFact] - public async Task ABodyWrittenAsChunks_FailsTheStartNamingTheRole() - { - // The store reads one string. A list is not a shorter string: it reads as absent, and every - // card would carry an empty body. - await Against( - HostileCorpus.ChunkedBodyAsync, - Entry(), - message => - { - Assert.Contains("'content'", message, StringComparison.Ordinal); - Assert.Contains("fields.body", message, StringComparison.Ordinal); - }); - } + message => + { + Assert.Contains("keyed by number", message, StringComparison.Ordinal); + Assert.Contains("links.lookup: filter", message, StringComparison.Ordinal); + }); + } - [QdrantFact] - public async Task CitationRolesTheCollectionDoesNotCarry_FailTheStart() - { - // The exact silent failure the widened startup proof exists for: source and locator are - // mapped, the collection carries neither, and before the proof every citation was blank - // for the life of the deployment with nothing logged. - await Against( - HostileCorpus.NoCitationFieldsAsync, - Entry(), - message => - { - Assert.Contains("'origin'", message, StringComparison.Ordinal); - Assert.Contains("fields.source", message, StringComparison.Ordinal); - Assert.Contains("explicit null", message, StringComparison.Ordinal); - }); - } + [QdrantFact] + public async Task ABodyWrittenAsChunks_FailsTheStartNamingTheRole() + { + // The store reads one string. A list is not a shorter string: it reads as absent, and every + // card would carry an empty body. + await Against( + HostileCorpus.ChunkedBodyAsync, + Entry(), + message => + { + Assert.Contains("'content'", message, StringComparison.Ordinal); + Assert.Contains("fields.body", message, StringComparison.Ordinal); + }); + } - [QdrantFact] - public async Task ATextAuthority_FailsTheStartRatherThanReadingAsNoRank() - { - await Against( - HostileCorpus.TextAuthorityAsync, - Entry() with { Fields = Fields with { Source = null, Locator = null } }, - message => - { - Assert.Contains("numeric", message, StringComparison.Ordinal); - Assert.Contains("fields.authority", message, StringComparison.Ordinal); - }); - } + [QdrantFact] + public async Task CitationRolesTheCollectionDoesNotCarry_FailTheStart() + { + // The exact silent failure the widened startup proof exists for: source and locator are + // mapped, the collection carries neither, and before the proof every citation was blank + // for the life of the deployment with nothing logged. + await Against( + HostileCorpus.NoCitationFieldsAsync, + Entry(), + message => + { + Assert.Contains("'origin'", message, StringComparison.Ordinal); + Assert.Contains("fields.source", message, StringComparison.Ordinal); + Assert.Contains("explicit null", message, StringComparison.Ordinal); + }); + } - [QdrantFact] - public async Task DeclaringTheMissingRolesAsNull_OpensTheSameCollection() - { - // The other half of every failure above: the document says what the collection really has, - // and the same collection opens. A refusal a deployment cannot answer is just a bug. - var collection = $"hostile-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await HostileCorpus.NoCitationFieldsAsync(client, collection, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task ATextAuthority_FailsTheStartRatherThanReadingAsNoRank() + { + await Against( + HostileCorpus.TextAuthorityAsync, + Entry() with { Fields = Fields with { Source = null, Locator = null } }, + message => + { + Assert.Contains("numeric", message, StringComparison.Ordinal); + Assert.Contains("fields.authority", message, StringComparison.Ordinal); + }); + } - try + [QdrantFact] + public async Task DeclaringTheMissingRolesAsNull_OpensTheSameCollection() { - var entry = Entry() with + // The other half of every failure above: the document says what the collection really has, + // and the same collection opens. A refusal a deployment cannot answer is just a bug. + string collection = $"hostile-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await HostileCorpus.NoCitationFieldsAsync(client, collection, TestContext.Current.CancellationToken); + + try { - Collection = collection, - Fields = Fields with { Source = null, Locator = null, Authority = null }, - }; + KnowledgeProviderConfiguration entry = Entry() with + { + Collection = collection, + Fields = Fields with { Source = null, Locator = null, Authority = null }, + }; - using var port = (IDisposable)await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, TestContext.Current.CancellationToken); + using IDisposable port = (IDisposable)await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, TestContext.Current.CancellationToken); - Assert.NotNull(port); + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + /// Builds one hostile collection, starts against it, and reads the refusal. + private static async Task Against( + Func build, + KnowledgeProviderConfiguration entry, + Action assertMessage) { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); - } - } + string collection = $"hostile-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await build(client, collection, TestContext.Current.CancellationToken); - /// Builds one hostile collection, starts against it, and reads the refusal. - private static async Task Against( - Func build, - KnowledgeProviderConfiguration entry, - Action assertMessage) - { - var collection = $"hostile-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await build(client, collection, TestContext.Current.CancellationToken); + try + { + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await Adapter().CreateSearchAsync( + entry with { Collection = collection }, + secrets: null, + Embedder(), + requireScope: false, + TestContext.Current.CancellationToken)); + + assertMessage(thrown.Message); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - try + private static KnowledgeFieldsConfiguration Fields => new() { - var thrown = await Assert.ThrowsAsync( - async () => await Adapter().CreateSearchAsync( - entry with { Collection = collection }, - secrets: null, - Embedder(), - requireScope: false, - TestContext.Current.CancellationToken)); + Id = "doc_id", + Body = "content", + Lexical = "content", + Source = "origin", + Locator = "page", + Authority = "trust", + }; + + private static KnowledgeProviderConfiguration Entry() + { + return new() + { + Kind = QdrantKnowledgeAdapter.ProviderKind, + Collection = "replaced-per-test", + Fields = Fields, + }; + } - assertMessage(thrown.Message); + private static QdrantKnowledgeAdapter Adapter() + { + return new(_ => QdrantServer.CreateClient()); } - finally + + private static FakeEmbeddingGenerator Embedder() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + return new(HostileCorpus.QueryVector()); } } - - private static KnowledgeFieldsConfiguration Fields => new() - { - Id = "doc_id", - Body = "content", - Lexical = "content", - Source = "origin", - Locator = "page", - Authority = "trust", - }; - - private static KnowledgeProviderConfiguration Entry() => new() - { - Kind = QdrantKnowledgeAdapter.ProviderKind, - Collection = "replaced-per-test", - Fields = Fields, - }; - - private static QdrantKnowledgeAdapter Adapter() => new(_ => QdrantServer.CreateClient()); - - private static FakeEmbeddingGenerator Embedder() => new(HostileCorpus.QueryVector()); } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpus.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpus.cs index b942da66..561df6e4 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpus.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpus.cs @@ -5,304 +5,312 @@ using Qdrant.Client; using Qdrant.Client.Grpc; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// One card of the synthetic corpus. -public sealed record KbShapedCard +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// Gets the card id. - public required string CardId { get; init; } - - /// Gets the retrieval text. - public required string Text { get; init; } - - /// Gets the trust level. - public required int Authority { get; init; } - - /// Gets the product this card applies to. - public required string Model { get; init; } - - /// Gets the card ids this card links to. - public required IReadOnlyList SeeAlso { get; init; } - - /// Gets the products this card also applies to, as a LIST facet. - /// - /// A real knowledge bank writes facets.applies_to as an array, and Qdrant matches a keyword - /// against a list when any element matches. QdrantKnowledgeStore.Holds mirrors that rule for - /// the see_also re-check, and with a scalar-only corpus its list branch was never executed — so a - /// deployment scoped on an array facet would have dropped every linked card, silently. - /// - public required IReadOnlyList AppliesTo { get; init; } - - /// Gets the embedding. - public required float[] Vector { get; init; } -} + /// One card of the synthetic corpus. + public sealed record KbShapedCard + { + /// Gets the card id. + public required string CardId { get; init; } -/// -/// A hand-built corpus in the shape one particular ingester writes: 30 cards, 8 dimensions, no -/// OpenAI and no checked-in vector file. -/// -/// -/// -/// Named for the shape, not for the fact that it is synthetic. Every corpus in this folder is -/// synthetic; what matters about this one is that its payload keys, its nested facets and its -/// uuid5 point keys are ONE deployment's conventions. A test that passes here has proved the store -/// works against that shape and nothing more, which is why and -/// exist beside it. -/// -/// -/// The block a document writes to read it lives here too — , -/// , . AgentCore supplies none of it. -/// -/// -/// -/// Card 6 holds e27 and card 7 holds e33, so the look-alike case puts the identifier -/// card one dense rank BELOW its rival. Only the required-identifier prefetch lifts it. -/// -public static partial class KbShapedCorpus -{ - /// The vector width. Small on purpose: nothing here needs a real embedding model. - public const int Dim = 8; + /// Gets the retrieval text. + public required string Text { get; init; } - /// How many cards the corpus holds. - public const int Count = 30; + /// Gets the trust level. + public required int Authority { get; init; } - /// A query with no identifier in it. - public const string PlainQuery = "how do i clean the deck"; + /// Gets the product this card applies to. + public required string Model { get; init; } - /// - /// A query naming one identifier, e33, whose card (7) sits one dense rank below its rival e27's - /// card (6) -- so only the required-identifier prefetch lifts it. - /// - public const string LookalikeQuery = "the screen says e33"; + /// Gets the card ids this card links to. + public required IReadOnlyList SeeAlso { get; init; } - /// A query naming two identifiers that co-occur in no card. This is what proves `must`. - public const string TwoIdentifierQuery = "the screen says e33 e27"; + /// Gets the products this card also applies to, as a LIST facet. + /// + /// A real knowledge bank writes facets.applies_to as an array, and Qdrant matches a keyword + /// against a list when any element matches. QdrantKnowledgeStore.Holds mirrors that rule for + /// the see_also re-check, and with a scalar-only corpus its list branch was never executed — so a + /// deployment scoped on an array facet would have dropped every linked card, silently. + /// + public required IReadOnlyList AppliesTo { get; init; } - /// The value every card carries in its applies_to LIST facet, alongside its own model. - public const string SharedAudience = "shared"; + /// Gets the embedding. + public required float[] Vector { get; init; } + } /// - /// The required-term rule this corpus's own vocabulary implies: a short letter run followed by - /// a short digit run is a console code. + /// A hand-built corpus in the shape one particular ingester writes: 30 cards, 8 dimensions, no + /// OpenAI and no checked-in vector file. /// /// - /// This used to be a framework default, which is why the tests below once left the analyzer - /// unset and still got a required-term leg. It was one corpus's vocabulary living in the - /// framework, exactly like the payload names were. AgentCore now ships only none, so - /// the rule lives with the corpus that means it, next to and - /// . + /// + /// Named for the shape, not for the fact that it is synthetic. Every corpus in this folder is + /// synthetic; what matters about this one is that its payload keys, its nested facets and its + /// uuid5 point keys are ONE deployment's conventions. A test that passes here has proved the store + /// works against that shape and nothing more, which is why and + /// exist beside it. + /// + /// + /// The block a document writes to read it lives here too — , + /// , . AgentCore supplies none of it. + /// /// - public static IKnowledgeQueryAnalyzer Analyzer => new ConsoleCodeAnalyzer(); - - private const int E27 = 6; - private const int E33 = 7; - - /// The id of card . - public static string Id(int index) => $"syn-{index:00}"; - - /// The one vector every query embeds to. Card 0 is nearest it, card 29 farthest. - public static float[] QueryVector() - { - var v = new float[Dim]; - v[0] = 1f; - return v; - } - - /// Builds the corpus. - /// - /// Whether out-of-scope cards are spread through the ranking. When they cluster at the far end - /// instead, the nearest cards are all in scope anyway and a dropped scope filter changes nothing - /// any assertion can see. That is a trap a fixture author walks into without noticing, so scope - /// tests must pass . - /// - /// The cards, in dense-rank order. - public static IReadOnlyList Cards(bool interleaved) + /// + /// Card 6 holds e27 and card 7 holds e33, so the look-alike case puts the identifier + /// card one dense rank BELOW its rival. Only the required-identifier prefetch lifts it. + /// + public static partial class KbShapedCorpus { - var cards = new List(Count); + /// The vector width. Small on purpose: nothing here needs a real embedding model. + public const int Dim = 8; + + /// How many cards the corpus holds. + public const int Count = 30; + + /// A query with no identifier in it. + public const string PlainQuery = "how do i clean the deck"; + + /// + /// A query naming one identifier, e33, whose card (7) sits one dense rank below its rival e27's + /// card (6) -- so only the required-identifier prefetch lifts it. + /// + public const string LookalikeQuery = "the screen says e33"; + + /// A query naming two identifiers that co-occur in no card. This is what proves `must`. + public const string TwoIdentifierQuery = "the screen says e33 e27"; + + /// The value every card carries in its applies_to LIST facet, alongside its own model. + public const string SharedAudience = "shared"; + + /// + /// The required-term rule this corpus's own vocabulary implies: a short letter run followed by + /// a short digit run is a console code. + /// + /// + /// This used to be a framework default, which is why the tests below once left the analyzer + /// unset and still got a required-term leg. It was one corpus's vocabulary living in the + /// framework, exactly like the payload names were. AgentCore now ships only none, so + /// the rule lives with the corpus that means it, next to and + /// . + /// + public static IKnowledgeQueryAnalyzer Analyzer => new ConsoleCodeAnalyzer(); + + private const int E27 = 6; + private const int E33 = 7; + + /// The id of card . + public static string Id(int index) + { + return $"syn-{index:00}"; + } - for (var i = 0; i < Count; i++) + /// The one vector every query embeds to. Card 0 is nearest it, card 29 farthest. + public static float[] QueryVector() { - var angle = i * 0.05; - var vector = new float[Dim]; - vector[0] = (float)Math.Cos(angle); - vector[1] = (float)Math.Sin(angle); + float[] v = new float[Dim]; + v[0] = 1f; + return v; + } - var model = interleaved - ? (i % 3 != 2 ? "ct900" : i % 2 == 0 ? "ctsbs900" : "ct900ent") - : (i < 20 ? "ct900" : i < 25 ? "ctsbs900" : "ct900ent"); + /// Builds the corpus. + /// + /// Whether out-of-scope cards are spread through the ranking. When they cluster at the far end + /// instead, the nearest cards are all in scope anyway and a dropped scope filter changes nothing + /// any assertion can see. That is a trap a fixture author walks into without noticing, so scope + /// tests must pass . + /// + /// The cards, in dense-rank order. + public static IReadOnlyList Cards(bool interleaved) + { + List cards = new(Count); - cards.Add(new KbShapedCard + for (int i = 0; i < Count; i++) { - CardId = Id(i), - Text = i switch + double angle = i * 0.05; + float[] vector = new float[Dim]; + vector[0] = (float)Math.Cos(angle); + vector[1] = (float)Math.Sin(angle); + + string model = interleaved + ? (i % 3 != 2 ? "ct900" : i % 2 == 0 ? "ctsbs900" : "ct900ent") + : (i < 20 ? "ct900" : i < 25 ? "ctsbs900" : "ct900ent"); + + cards.Add(new KbShapedCard { - E27 => "err e27 communication code error on the console", - E33 => "err e33 incline motor error on the console", - _ => $"card {Id(i)} deck belt console maintenance text", - }, - Authority = 3 - (i % 3), - Model = model, - // The nearest card links to the farthest one, which is therefore never already - // on the page -- so a see_also assertion cannot pass by accident. - SeeAlso = i == 0 ? [Id(Count - 1)] : [], - - // Two elements, one of them shared by every card: a scope on SharedAudience holds for - // every card, and a scope on one model holds for that model's cards alone. Both - // answers come out of the SAME list branch, so a branch that always said yes and a - // branch that always said no are each caught by one of the two. - AppliesTo = [model, SharedAudience], - Vector = vector, - }); + CardId = Id(i), + Text = i switch + { + E27 => "err e27 communication code error on the console", + E33 => "err e33 incline motor error on the console", + _ => $"card {Id(i)} deck belt console maintenance text", + }, + Authority = 3 - (i % 3), + Model = model, + // The nearest card links to the farthest one, which is therefore never already + // on the page -- so a see_also assertion cannot pass by accident. + SeeAlso = i == 0 ? [Id(Count - 1)] : [], + + // Two elements, one of them shared by every card: a scope on SharedAudience holds for + // every card, and a scope on one model holds for that model's cards alone. Both + // answers come out of the SAME list branch, so a branch that always said yes and a + // branch that always said no are each caught by one of the two. + AppliesTo = [model, SharedAudience], + Vector = vector, + }); + } + + return cards; } - return cards; - } + /// + /// The fields: block a document writes to read THIS corpus. + /// + /// + /// Written out, never inherited. AgentCore ships no field names, so a corpus that wants to be + /// read has to describe itself, and the description belongs beside the corpus that made it true. + /// + public static KnowledgeFieldsConfiguration Fields => new() + { + Id = "card_id", + Body = "body", + Lexical = "text", + Source = "source.ref", + Locator = "source.locator", + Authority = "authority", + }; + + /// The payload path one facet key becomes here: a nested struct, so a dotted path. + public const string ScopeTemplate = "facets.{key}"; + + /// What this corpus puts in front of a card id before hashing it into a point key. + /// + /// Written out here and read back by every fixture, because the framework's own prefix default + /// is the empty string. A corpus that hashes with a prefix has to say which one. + /// + public const string LinkPrefix = "kb:"; + + /// The links: block a document writes to follow THIS corpus's links. + public static KnowledgeLinksConfiguration Links => new() + { + Field = "see_also", + Lookup = KnowledgeLinkLookup.Uuid5, + Prefix = LinkPrefix, + }; - /// - /// The fields: block a document writes to read THIS corpus. - /// - /// - /// Written out, never inherited. AgentCore ships no field names, so a corpus that wants to be - /// read has to describe itself, and the description belongs beside the corpus that made it true. - /// - public static KnowledgeFieldsConfiguration Fields => new() - { - Id = "card_id", - Body = "body", - Lexical = "text", - Source = "source.ref", - Locator = "source.locator", - Authority = "authority", - }; - - /// The payload path one facet key becomes here: a nested struct, so a dotted path. - public const string ScopeTemplate = "facets.{key}"; - - /// What this corpus puts in front of a card id before hashing it into a point key. - /// - /// Written out here and read back by every fixture, because the framework's own prefix default - /// is the empty string. A corpus that hashes with a prefix has to say which one. - /// - public const string LinkPrefix = "kb:"; + /// The point key of one card here. + public static Guid PointKey(string cardId) + { + return Uuid5PointId.For(cardId, Uuid5PointId.Namespace(KnowledgeLinksConfiguration.DefaultNamespace), LinkPrefix); + } - /// The links: block a document writes to follow THIS corpus's links. - public static KnowledgeLinksConfiguration Links => new() - { - Field = "see_also", - Lookup = KnowledgeLinkLookup.Uuid5, - Prefix = LinkPrefix, - }; - - /// The point key of one card here. - public static Guid PointKey(string cardId) - => Uuid5PointId.For(cardId, Uuid5PointId.Namespace(KnowledgeLinksConfiguration.DefaultNamespace), LinkPrefix); - - /// The scope: block a document writes to scope over THIS corpus. - public static KnowledgeScopeConfiguration Scope => new() { Template = ScopeTemplate }; - - /// Creates the collection and fills it, shaped the way a real ingester shapes one. - /// The client. - /// The collection name. The caller drops it afterwards. - /// See . - /// Cancels the build. - /// - /// The vector is named and the facets are a nested struct indexed at - /// facets.model, because that is what the knowledge repository writes. A test collection - /// shaped any other way proves nothing about production. - /// - public static async Task CreateAsync( - QdrantClient client, string collection, bool interleaved, CancellationToken cancellationToken) - { - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: cancellationToken); - - await client.CreatePayloadIndexAsync( - collection, "text", PayloadSchemaType.Text, cancellationToken: cancellationToken); - await client.CreatePayloadIndexAsync( - collection, "card_id", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - await client.CreatePayloadIndexAsync( - collection, "facets.model", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - await client.CreatePayloadIndexAsync( - collection, "facets.applies_to", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); - - var points = Cards(interleaved).Select(card => + /// The scope: block a document writes to scope over THIS corpus. + public static KnowledgeScopeConfiguration Scope => new() { Template = ScopeTemplate }; + + /// Creates the collection and fills it, shaped the way a real ingester shapes one. + /// The client. + /// The collection name. The caller drops it afterwards. + /// See . + /// Cancels the build. + /// + /// The vector is named and the facets are a nested struct indexed at + /// facets.model, because that is what the knowledge repository writes. A test collection + /// shaped any other way proves nothing about production. + /// + public static async Task CreateAsync( + QdrantClient client, string collection, bool interleaved, CancellationToken cancellationToken) { - var point = new PointStruct - { - Id = new PointId { Uuid = PointKey(card.CardId).ToString() }, - Vectors = new Vectors { Vectors_ = new NamedVectors { Vectors = { ["dense"] = card.Vector } } }, - }; - - point.Payload["card_id"] = card.CardId; - point.Payload["text"] = card.Text; - point.Payload["body"] = card.Text; - point.Payload["authority"] = card.Authority; - point.Payload["see_also"] = new Value - { - ListValue = new ListValue { Values = { card.SeeAlso.Select(id => new Value { StringValue = id }) } }, - }; - point.Payload["facets"] = new Value + await client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap + { + Map = { ["dense"] = new VectorParams { Size = Dim, Distance = Distance.Cosine } }, + }, + cancellationToken: cancellationToken); + + _ = await client.CreatePayloadIndexAsync( + collection, "text", PayloadSchemaType.Text, cancellationToken: cancellationToken); + _ = await client.CreatePayloadIndexAsync( + collection, "card_id", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); + _ = await client.CreatePayloadIndexAsync( + collection, "facets.model", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); + _ = await client.CreatePayloadIndexAsync( + collection, "facets.applies_to", PayloadSchemaType.Keyword, cancellationToken: cancellationToken); + + List points = [.. Cards(interleaved).Select(card => { - StructValue = new Struct + PointStruct point = new() + { + Id = new PointId { Uuid = PointKey(card.CardId).ToString() }, + Vectors = new Vectors { Vectors_ = new NamedVectors { Vectors = { ["dense"] = card.Vector } } }, + }; + + point.Payload["card_id"] = card.CardId; + point.Payload["text"] = card.Text; + point.Payload["body"] = card.Text; + point.Payload["authority"] = card.Authority; + point.Payload["see_also"] = new Value { - Fields = + ListValue = new ListValue { Values = { card.SeeAlso.Select(id => new Value { StringValue = id }) } }, + }; + point.Payload["facets"] = new Value + { + StructValue = new Struct { - ["model"] = new Value { StringValue = card.Model }, - - // An ARRAY facet, which is what the sibling knowledge-bank design writes for - // applies_to. Qdrant matches a keyword against any element of it, and - // QdrantKnowledgeStore.Holds has to mirror that for the see_also re-check. - ["applies_to"] = new Value + Fields = { - ListValue = new ListValue + ["model"] = new Value { StringValue = card.Model }, + + // An ARRAY facet, which is what the sibling knowledge-bank design writes for + // applies_to. Qdrant matches a keyword against any element of it, and + // QdrantKnowledgeStore.Holds has to mirror that for the see_also re-check. + ["applies_to"] = new Value { - Values = { card.AppliesTo.Select(model => new Value { StringValue = model }) }, + ListValue = new ListValue + { + Values = { card.AppliesTo.Select(model => new Value { StringValue = model }) }, + }, }, }, }, - }, - }; - point.Payload["source"] = new Value - { - StructValue = new Struct + }; + point.Payload["source"] = new Value { - Fields = + StructValue = new Struct { - ["ref"] = new Value { StringValue = $"manifest-{card.CardId}" }, - ["locator"] = new Value { StringValue = "p.1" }, + Fields = + { + ["ref"] = new Value { StringValue = $"manifest-{card.CardId}" }, + ["locator"] = new Value { StringValue = "p.1" }, + }, }, - }, - }; + }; - return point; - }).ToList(); + return point; + })]; - await client.UpsertAsync(collection, points, cancellationToken: cancellationToken); - } + _ = await client.UpsertAsync(collection, points, cancellationToken: cancellationToken); + } - /// Treats a short letter run followed by a short digit run as a required term. - private sealed partial class ConsoleCodeAnalyzer : IKnowledgeQueryAnalyzer - { - [GeneratedRegex("[a-z0-9]+")] - private static partial Regex Word { get; } + /// Treats a short letter run followed by a short digit run as a required term. + private sealed partial class ConsoleCodeAnalyzer : IKnowledgeQueryAnalyzer + { + [GeneratedRegex("[a-z0-9]+")] + private static partial Regex Word { get; } - [GeneratedRegex("^[a-z]{1,4}[0-9]{1,3}$")] - private static partial Regex Identifier { get; } + [GeneratedRegex("^[a-z]{1,4}[0-9]{1,3}$")] + private static partial Regex Identifier { get; } - public string Name => "console-codes"; + public string Name => "console-codes"; - public IReadOnlyList RequiredTerms(string query) => - [ - .. Word.Matches(query.ToLowerInvariant()) - .Select(match => match.Value) - .Where(token => Identifier.IsMatch(token)) - .Distinct(StringComparer.Ordinal), - ]; + public IReadOnlyList RequiredTerms(string query) + { + return [ + .. Word.Matches(query.ToLowerInvariant()) + .Select(match => match.Value) + .Where(token => Identifier.IsMatch(token)) + .Distinct(StringComparer.Ordinal), + ]; + } + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpusTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpusTests.cs index a9418803..3a60bbe0 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpusTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/KbShapedCorpusTests.cs @@ -1,178 +1,180 @@ +using Qdrant.Client; using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -[Collection(QdrantServerCollection.Name)] -public sealed class KbShapedCorpusTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [QdrantFact] - public async Task CreateAsync_BuildsANamedVectorCollectionWithNestedFacets() + [Collection(QdrantServerCollection.Name)] + public sealed class KbShapedCorpusTests { - using var client = QdrantServer.CreateClient(); - var collection = $"synthetic-{Guid.NewGuid():N}"; - - try + [QdrantFact] + public async Task CreateAsync_BuildsANamedVectorCollectionWithNestedFacets() { - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - - var info = await client.GetCollectionInfoAsync(collection, TestContext.Current.CancellationToken); - Assert.True(info.Config.Params.VectorsConfig.ParamsMap.Map.ContainsKey("dense")); - Assert.Equal( - (ulong)KbShapedCorpus.Count, - await client.CountAsync(collection, cancellationToken: TestContext.Current.CancellationToken)); - - // The facet must be a real nested path, not a flat key with a dot in it. - var filtered = await client.ScrollAsync( - collection, - filter: MatchKeyword("facets.model", "ct900"), - limit: 100, - cancellationToken: TestContext.Current.CancellationToken); - Assert.NotEmpty(filtered.Result); - - // The flat shape must find nothing. This is the negative control that would have - // caught A25 before it was written. - var flat = await client.ScrollAsync( - collection, - filter: MatchKeyword("facets_model", "ct900"), - limit: 100, - cancellationToken: TestContext.Current.CancellationToken); - Assert.Empty(flat.Result); + using QdrantClient client = QdrantServer.CreateClient(); + string collection = $"synthetic-{Guid.NewGuid():N}"; + + try + { + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + + CollectionInfo info = await client.GetCollectionInfoAsync(collection, TestContext.Current.CancellationToken); + Assert.True(info.Config.Params.VectorsConfig.ParamsMap.Map.ContainsKey("dense")); + Assert.Equal( + (ulong)KbShapedCorpus.Count, + await client.CountAsync(collection, cancellationToken: TestContext.Current.CancellationToken)); + + // The facet must be a real nested path, not a flat key with a dot in it. + ScrollResponse filtered = await client.ScrollAsync( + collection, + filter: MatchKeyword("facets.model", "ct900"), + limit: 100, + cancellationToken: TestContext.Current.CancellationToken); + Assert.NotEmpty(filtered.Result); + + // The flat shape must find nothing. This is the negative control that would have + // caught A25 before it was written. + ScrollResponse flat = await client.ScrollAsync( + collection, + filter: MatchKeyword("facets_model", "ct900"), + limit: 100, + cancellationToken: TestContext.Current.CancellationToken); + Assert.Empty(flat.Result); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + [QdrantFact] + public async Task SearchAsync_AgainstTheNamedDenseVector_ReturnsCardsInIndexOrder() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + using QdrantClient client = QdrantServer.CreateClient(); + string collection = $"synthetic-{Guid.NewGuid():N}"; + + try + { + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + + IReadOnlyList results = await client.QueryAsync( + collection, + query: KbShapedCorpus.QueryVector(), + usingVector: "dense", + limit: KbShapedCorpus.Count, + payloadSelector: true, + cancellationToken: TestContext.Current.CancellationToken); + + // A wrong distance function, a wrong vector name, or a broken upsert would all still + // return 30 points -- only checking the actual order proves the server round-trip. + List order = [.. results.Select(r => r.Payload["card_id"].StringValue)]; + List expected = [.. Enumerable.Range(0, KbShapedCorpus.Count).Select(KbShapedCorpus.Id)]; + Assert.Equal(expected, order); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - - [QdrantFact] - public async Task SearchAsync_AgainstTheNamedDenseVector_ReturnsCardsInIndexOrder() - { - using var client = QdrantServer.CreateClient(); - var collection = $"synthetic-{Guid.NewGuid():N}"; - try + [Fact] + public void Cards_DenseSimilarityToQuery_StrictlyDecreasesWithIndex() { - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - - var results = await client.QueryAsync( - collection, - query: KbShapedCorpus.QueryVector(), - usingVector: "dense", - limit: (ulong)KbShapedCorpus.Count, - payloadSelector: true, - cancellationToken: TestContext.Current.CancellationToken); - - // A wrong distance function, a wrong vector name, or a broken upsert would all still - // return 30 points -- only checking the actual order proves the server round-trip. - var order = results.Select(r => r.Payload["card_id"].StringValue).ToList(); - var expected = Enumerable.Range(0, KbShapedCorpus.Count).Select(KbShapedCorpus.Id).ToList(); - Assert.Equal(expected, order); + float[] query = KbShapedCorpus.QueryVector(); + IReadOnlyList cards = KbShapedCorpus.Cards(interleaved: true); + List similarities = [.. cards.Select(c => DotProduct(c.Vector, query))]; + + for (int i = 1; i < similarities.Count; i++) + { + Assert.True( + similarities[i] < similarities[i - 1], + $"card {i} must be strictly farther from the query than card {i - 1}, or dense rank stops equalling card index"); + } } - finally + + [Fact] + public void LookalikeIdentifierCard_RanksExactlyOneBelowItsRival() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); - } - } + IReadOnlyList cards = KbShapedCorpus.Cards(interleaved: true); + float[] query = KbShapedCorpus.QueryVector(); - [Fact] - public void Cards_DenseSimilarityToQuery_StrictlyDecreasesWithIndex() - { - var query = KbShapedCorpus.QueryVector(); - var cards = KbShapedCorpus.Cards(interleaved: true); - var similarities = cards.Select(c => DotProduct(c.Vector, query)).ToList(); + KbShapedCard e27 = cards.Single(c => c.CardId == KbShapedCorpus.Id(6)); + KbShapedCard e33 = cards.Single(c => c.CardId == KbShapedCorpus.Id(7)); - for (var i = 1; i < similarities.Count; i++) - { - Assert.True( - similarities[i] < similarities[i - 1], - $"card {i} must be strictly farther from the query than card {i - 1}, or dense rank stops equalling card index"); + Assert.Contains("e27", e27.Text, StringComparison.Ordinal); + Assert.Contains("e33", e33.Text, StringComparison.Ordinal); + + // Only a required-identifier prefetch can lift e33 above e27 on the look-alike query -- + // that is the entire point Task 8 tests. If this drifts, that test proves nothing. + Assert.True(DotProduct(e27.Vector, query) > DotProduct(e33.Vector, query)); } - } - [Fact] - public void LookalikeIdentifierCard_RanksExactlyOneBelowItsRival() - { - var cards = KbShapedCorpus.Cards(interleaved: true); - var query = KbShapedCorpus.QueryVector(); + [Fact] + public void Cards_Interleaved_SpreadsOutOfScopeCardsThroughTheRanking() + { + int maxRun = LongestRunOfInScopeCards(KbShapedCorpus.Cards(interleaved: true)); - var e27 = cards.Single(c => c.CardId == KbShapedCorpus.Id(6)); - var e33 = cards.Single(c => c.CardId == KbShapedCorpus.Id(7)); + // A single early stray followed by 27 in-scope cards would still satisfy "some out-of-scope + // card ranks above the last in-scope card" -- that is a boundary crossing, not dispersion. + // Bounding the longest unbroken run of in-scope cards anywhere in the ranking is what a + // dropped scope filter cannot hide behind: any long run means the nearest cards for a + // scope-filtered query are all in scope anyway, so the filter changes nothing observable. + Assert.True( + maxRun <= KbShapedCorpus.Count / 5, + $"the longest run of consecutive in-scope cards was {maxRun}; out-of-scope cards must be spread through the ranking, not merely present somewhere above the tail"); + } - Assert.Contains("e27", e27.Text, StringComparison.Ordinal); - Assert.Contains("e33", e33.Text, StringComparison.Ordinal); + [Fact] + public void Cards_NotInterleaved_ClustersOutOfScopeCardsAtTheTail() + { + // The negative control: interleaved:false is the trap a fixture author walks into without + // noticing, proven here (by the same metric as the positive case) so the `true` case above + // is known to test something real rather than merely "not this exact other arrangement". + int maxRun = LongestRunOfInScopeCards(KbShapedCorpus.Cards(interleaved: false)); - // Only a required-identifier prefetch can lift e33 above e27 on the look-alike query -- - // that is the entire point Task 8 tests. If this drifts, that test proves nothing. - Assert.True(DotProduct(e27.Vector, query) > DotProduct(e33.Vector, query)); - } + Assert.True( + maxRun > KbShapedCorpus.Count / 2, + $"the longest run of consecutive in-scope cards was only {maxRun}; interleaved:false should genuinely cluster out-of-scope cards at the tail"); + } - [Fact] - public void Cards_Interleaved_SpreadsOutOfScopeCardsThroughTheRanking() - { - var maxRun = LongestRunOfInScopeCards(KbShapedCorpus.Cards(interleaved: true)); - - // A single early stray followed by 27 in-scope cards would still satisfy "some out-of-scope - // card ranks above the last in-scope card" -- that is a boundary crossing, not dispersion. - // Bounding the longest unbroken run of in-scope cards anywhere in the ranking is what a - // dropped scope filter cannot hide behind: any long run means the nearest cards for a - // scope-filtered query are all in scope anyway, so the filter changes nothing observable. - Assert.True( - maxRun <= KbShapedCorpus.Count / 5, - $"the longest run of consecutive in-scope cards was {maxRun}; out-of-scope cards must be spread through the ranking, not merely present somewhere above the tail"); - } + [Fact] + public void Card0SeeAlso_PointsToTheFarthestCard() + { + IReadOnlyList cards = KbShapedCorpus.Cards(interleaved: true); - [Fact] - public void Cards_NotInterleaved_ClustersOutOfScopeCardsAtTheTail() - { - // The negative control: interleaved:false is the trap a fixture author walks into without - // noticing, proven here (by the same metric as the positive case) so the `true` case above - // is known to test something real rather than merely "not this exact other arrangement". - var maxRun = LongestRunOfInScopeCards(KbShapedCorpus.Cards(interleaved: false)); - - Assert.True( - maxRun > KbShapedCorpus.Count / 2, - $"the longest run of consecutive in-scope cards was only {maxRun}; interleaved:false should genuinely cluster out-of-scope cards at the tail"); - } + Assert.Equal([KbShapedCorpus.Id(KbShapedCorpus.Count - 1)], cards[0].SeeAlso); + Assert.All(cards.Skip(1), c => Assert.Empty(c.SeeAlso)); + } - [Fact] - public void Card0SeeAlso_PointsToTheFarthestCard() - { - var cards = KbShapedCorpus.Cards(interleaved: true); + private static int LongestRunOfInScopeCards(IReadOnlyList cards) + { + int longest = 0; + int current = 0; - Assert.Equal([KbShapedCorpus.Id(KbShapedCorpus.Count - 1)], cards[0].SeeAlso); - Assert.All(cards.Skip(1), c => Assert.Empty(c.SeeAlso)); - } + foreach (KbShapedCard card in cards) + { + current = card.Model == "ct900" ? current + 1 : 0; + longest = Math.Max(longest, current); + } - private static int LongestRunOfInScopeCards(IReadOnlyList cards) - { - var longest = 0; - var current = 0; + return longest; + } - foreach (var card in cards) + private static float DotProduct(float[] a, float[] b) { - current = card.Model == "ct900" ? current + 1 : 0; - longest = Math.Max(longest, current); - } + float sum = 0f; + for (int i = 0; i < a.Length; i++) + { + sum += a[i] * b[i]; + } - return longest; - } + return sum; + } - private static float DotProduct(float[] a, float[] b) - { - var sum = 0f; - for (var i = 0; i < a.Length; i++) + private static Filter MatchKeyword(string key, string value) { - sum += a[i] * b[i]; + Filter filter = new(); + filter.Must.Add(new Condition { Field = new FieldCondition { Key = key, Match = new Match { Keyword = value } } }); + return filter; } - - return sum; - } - - private static Filter MatchKeyword(string key, string value) - { - var filter = new Filter(); - filter.Must.Add(new Condition { Field = new FieldCondition { Key = key, Match = new Match { Keyword = value } } }); - return filter; } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantFactAttribute.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantFactAttribute.cs index 21cf3f9d..e1f49aa1 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantFactAttribute.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantFactAttribute.cs @@ -1,22 +1,23 @@ using System.Runtime.CompilerServices; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// A test that needs a live Qdrant, and skips itself when none is named. -/// See for the variable it reads. -public sealed class QdrantFactAttribute : FactAttribute +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// Creates the attribute. - /// Supplied by the compiler. - /// Supplied by the compiler. - public QdrantFactAttribute( - [CallerFilePath] string? sourceFilePath = null, - [CallerLineNumber] int sourceLineNumber = -1) - : base(sourceFilePath, sourceLineNumber) + /// A test that needs a live Qdrant, and skips itself when none is named. + /// See for the variable it reads. + public sealed class QdrantFactAttribute : FactAttribute { - Skip = QdrantServer.SkipReason; - SkipUnless = nameof(QdrantServer.IsConfigured); - SkipType = typeof(QdrantServer); + /// Creates the attribute. + /// Supplied by the compiler. + /// Supplied by the compiler. + public QdrantFactAttribute( + [CallerFilePath] string? sourceFilePath = null, + [CallerLineNumber] int sourceLineNumber = -1) + : base(sourceFilePath, sourceLineNumber) + { + Skip = QdrantServer.SkipReason; + SkipUnless = nameof(QdrantServer.IsConfigured); + SkipType = typeof(QdrantServer); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs index d3fc1dd5..59f07484 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs @@ -3,6 +3,7 @@ using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; +using AgentCore.Application.Ports; using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; @@ -11,88 +12,86 @@ using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -[Collection(QdrantServerCollection.Name)] -public sealed class QdrantKnowledgeAdapterTests : IClassFixture +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - // Width 8, matching KbShapedCorpus.Dim: every collection this file builds by hand or through - // KbShapedCorpus carries an 8-wide "dense" vector, so the dimension check must measure 8 too. - private static readonly IEmbeddingGenerator> Embeddings = - new FakeEmbeddingGenerator(new float[KbShapedCorpus.Dim]); + [Collection(QdrantServerCollection.Name)] + public sealed class QdrantKnowledgeAdapterTests(KbShapedCorpusFixture corpus) : IClassFixture + { + // Width 8, matching KbShapedCorpus.Dim: every collection this file builds by hand or through + // KbShapedCorpus carries an 8-wide "dense" vector, so the dimension check must measure 8 too. + private static readonly IEmbeddingGenerator> Embeddings = + new FakeEmbeddingGenerator(new float[KbShapedCorpus.Dim]); - private readonly KbShapedCorpusFixture _corpus; + private readonly KbShapedCorpusFixture _corpus = corpus; - public QdrantKnowledgeAdapterTests(KbShapedCorpusFixture corpus) => _corpus = corpus; + [QdrantFact] + public async Task CreateSearchAsync_CollectionMissing_FailsTheStart() + { + // A29. AgentCore never creates. If it did, it would put an empty concrete collection where + // the ingester's alias belongs, and the next ingest run then has a name it cannot claim. + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry("does-not-exist"); - [QdrantFact] - public async Task CreateSearchAsync_CollectionMissing_FailsTheStart() - { - // A29. AgentCore never creates. If it did, it would put an empty concrete collection where - // the ingester's alias belongs, and the next ingest run then has a name it cannot claim. - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry("does-not-exist"); + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); - var thrown = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + Assert.Contains("does-not-exist", thrown.Message, StringComparison.Ordinal); - Assert.Contains("does-not-exist", thrown.Message, StringComparison.Ordinal); + // The message says what to do without naming anybody's ingest tool. AgentCore does not know + // what wrote this collection, and a stranger told to "run kb sync" has nothing to run. + Assert.Contains("never creates one", thrown.Message, StringComparison.Ordinal); + Assert.DoesNotContain("kb sync", thrown.Message, StringComparison.Ordinal); + Assert.False(await ClientExists("does-not-exist")); + } - // The message says what to do without naming anybody's ingest tool. AgentCore does not know - // what wrote this collection, and a stranger told to "run kb sync" has nothing to run. - Assert.Contains("never creates one", thrown.Message, StringComparison.Ordinal); - Assert.DoesNotContain("kb sync", thrown.Message, StringComparison.Ordinal); - Assert.False(await ClientExists("does-not-exist")); - } + [QdrantFact] + public async Task CreateSearchAsync_StartupFailure_DisposesTheClient() + { + // Every throw site inside the assertion body used to leave the client -- and the gRPC + // channel behind it -- open. Reflection is used rather than asserting a specific downstream + // exception, because Grpc.Net.Client does not guarantee what a disposed channel throws. + QdrantClient? captured = null; + QdrantKnowledgeAdapter adapter = new( + _ => + { + captured = QdrantServer.CreateClient(); + return captured; + }, + Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry("does-not-exist"); - [QdrantFact] - public async Task CreateSearchAsync_StartupFailure_DisposesTheClient() - { - // Every throw site inside the assertion body used to leave the client -- and the gRPC - // channel behind it -- open. Reflection is used rather than asserting a specific downstream - // exception, because Grpc.Net.Client does not guarantee what a disposed channel throws. - QdrantClient? captured = null; - var adapter = new QdrantKnowledgeAdapter( - _ => - { - captured = QdrantServer.CreateClient(); - return captured; - }, - Embeddings); - var entry = DenseEntry("does-not-exist"); - - await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); - - Assert.NotNull(captured); - var isDisposed = typeof(QdrantClient) - .GetField("_isDisposed", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(captured); - Assert.True((bool)isDisposed!); - } + _ = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); - [QdrantFact] - public async Task CreateSearchAsync_DisposingTheReturnedPort_DisposesTheClient() - { - // The success-path counterpart to CreateSearchAsync_StartupFailure_DisposesTheClient: this is - // what actually proves the QdrantKnowledgeStore -> QdrantSearchChannel -> QdrantClient - // Dispose() forward reaches the real client, rather than a fake IDisposable standing in for - // it. A host-level test on AgentCoreBoot's Track wiring cannot tell this apart from a Dispose() - // that silently does nothing. - var collection = $"dispose-{Guid.NewGuid():N}"; - using var setup = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync(setup, collection, interleaved: true, TestContext.Current.CancellationToken); - - QdrantClient? captured = null; - var adapter = new QdrantKnowledgeAdapter( - _ => - { - captured = QdrantServer.CreateClient(); - return captured; - }, - Embeddings); - var entry = new KnowledgeProviderConfiguration + Assert.NotNull(captured); + object? isDisposed = typeof(QdrantClient) + .GetField("_isDisposed", BindingFlags.NonPublic | BindingFlags.Instance)! + .GetValue(captured); + Assert.True((bool)isDisposed!); + } + + [QdrantFact] + public async Task CreateSearchAsync_DisposingTheReturnedPort_DisposesTheClient() + { + // The success-path counterpart to CreateSearchAsync_StartupFailure_DisposesTheClient: this is + // what actually proves the QdrantKnowledgeStore -> QdrantSearchChannel -> QdrantClient + // Dispose() forward reaches the real client, rather than a fake IDisposable standing in for + // it. A host-level test on AgentCoreBoot's Track wiring cannot tell this apart from a Dispose() + // that silently does nothing. + string collection = $"dispose-{Guid.NewGuid():N}"; + using QdrantClient setup = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync(setup, collection, interleaved: true, TestContext.Current.CancellationToken); + + QdrantClient? captured = null; + QdrantKnowledgeAdapter adapter = new( + _ => + { + captured = QdrantServer.CreateClient(); + return captured; + }, + Embeddings); + KnowledgeProviderConfiguration entry = new() { Kind = "qdrant", Collection = collection, @@ -100,925 +99,954 @@ public async Task CreateSearchAsync_DisposingTheReturnedPort_DisposesTheClient() Fields = KbShapedCorpus.Fields, }; - try - { - var port = await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken); + try + { + IKnowledgeRetrievalPort port = await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken); + + Assert.NotNull(captured); + object? isDisposedBeforeConversation = typeof(QdrantClient) + .GetField("_isDisposed", BindingFlags.NonPublic | BindingFlags.Instance)! + .GetValue(captured); + Assert.False((bool)isDisposedBeforeConversation!); + + ((IDisposable)port).Dispose(); + + object? isDisposedAfterConversation = typeof(QdrantClient) + .GetField("_isDisposed", BindingFlags.NonPublic | BindingFlags.Instance)! + .GetValue(captured); + Assert.True((bool)isDisposedAfterConversation!); + } + finally + { + await setup.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - Assert.NotNull(captured); - var isDisposedBeforeConversation = typeof(QdrantClient) - .GetField("_isDisposed", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(captured); - Assert.False((bool)isDisposedBeforeConversation!); + [QdrantFact] + public async Task CreateSearchAsync_NamedVectorOverAnAnonymousCollection_FailsTheStart() + { + // A28, inverted by item 2 of the recommendation: the anonymous shape is now legal, so the + // named check fires only when the document asked for a name this collection does not carry. + string collection = $"unnamed-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await client.CreateCollectionAsync( + collection, new VectorParams { Size = 8, Distance = Distance.Cosine }, + cancellationToken: TestContext.Current.CancellationToken); + + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); - ((IDisposable)port).Dispose(); + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); - var isDisposedAfterConversation = typeof(QdrantClient) - .GetField("_isDisposed", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(captured); - Assert.True((bool)isDisposedAfterConversation!); + Assert.Contains("dense", thrown.Message, StringComparison.Ordinal); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + [QdrantFact] + public async Task CreateSearchAsync_DenseVectorIsTheWrongWidth_FailsTheStart() { - await setup.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + // Of the three checks this class exists to make, this is the one an equal-widths test like + // CreateSearchAsync_RealCollection_Opens cannot cover: a collection with a named "dense" + // vector that is NOT 8-wide, so only the size comparison -- not the name check -- can catch it. + string collection = $"wrongwidth-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection, 4); + + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); + + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + + // The surrounding phrase, not the bare digit: the message also carries a 32-character hex + // collection name, so Contains("4") and Contains("8") both pass on a chance digit in it + // even when the two widths have been swapped, or dropped from the message entirely. + Assert.Contains("of 4 dimensions", thrown.Message, StringComparison.Ordinal); + Assert.Contains($"embeds at {KbShapedCorpus.Dim}", thrown.Message, StringComparison.Ordinal); + + // Both ways out, named as document settings rather than as one repository's CLI. + Assert.Contains("providers.embeddings", thrown.Message, StringComparison.Ordinal); + Assert.DoesNotContain("kb sync", thrown.Message, StringComparison.Ordinal); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - [QdrantFact] - public async Task CreateSearchAsync_NamedVectorOverAnAnonymousCollection_FailsTheStart() - { - // A28, inverted by item 2 of the recommendation: the anonymous shape is now legal, so the - // named check fires only when the document asked for a name this collection does not carry. - var collection = $"unnamed-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, new VectorParams { Size = 8, Distance = Distance.Cosine }, - cancellationToken: TestContext.Current.CancellationToken); - - try + [QdrantFact] + public async Task CreateSearchAsync_RealCollection_Opens() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + string collection = $"adapter-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - var thrown = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); - Assert.Contains("dense", thrown.Message, StringComparison.Ordinal); + IKnowledgeRetrievalPort port = await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken); + + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + [QdrantFact] + public async Task CreateSearchAsync_TheStoreItOpens_FetchesWhatTheMostGenerousAgentMayAskFor() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + // Ruling 14(c). example.yaml gives the analyst limit: 8, the schema accepts up to 20, and the + // store this adapter opened fetched 5 -- so the analyst asked for 8, received 5, and nothing + // anywhere said so. One store serves every agent out of one fetch, so the fetch is the + // document's ceiling and not the store's own convenience default. + // + // Asserted on the options the adapter handed the store rather than on a returned card count, + // because the shipped ScoreFloor of 0.25 caps a plain query at three ranked cards whatever the + // limit is -- see QdrantKnowledgeStoreTests.SearchAsync_ScoreFloor_KeepsExactlyTheCardsAtOrAboveIt, + // which pins that boundary, and the fix report's concern about it. The behavioural half of + // this chain is already pinned by SearchAsync_LimitAboveTheDefaultPrefetchDepth_ReturnsThatMany: + // whatever Limit the store is given, it reaches Qdrant. This fact is the other half -- WHICH + // limit the adapter gives it. The reflection idiom is the one this class already uses on + // QdrantClient._isDisposed. + string collection = $"limit-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); + + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); + + QdrantKnowledgeStoreOptions options = OptionsOf(port); + + Assert.Equal(AgentKnowledgeConfiguration.MaximumLimit, options.Limit); + Assert.True( + options.Limit >= 8, + $"example.yaml's analyst asks for 8 and this store fetches {options.Limit}"); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - [QdrantFact] - public async Task CreateSearchAsync_DenseVectorIsTheWrongWidth_FailsTheStart() - { - // Of the three checks this class exists to make, this is the one an equal-widths test like - // CreateSearchAsync_RealCollection_Opens cannot cover: a collection with a named "dense" - // vector that is NOT 8-wide, so only the size comparison -- not the name check -- can catch it. - var collection = $"wrongwidth-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection, 4); - - try + [QdrantFact] + public async Task CreateSearchAsync_TheStoreItOpens_QueriesTheNamesTheStartupCheckAsserted() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + // A guard that does not guard. The startup check reads a named vector off the collection and + // refuses to boot without it, while the store used to query the options record's OWN "dense" + // and "text" literals, which that check never governed. Both agreed, so nothing was broken; + // change either one and the boot check still passes while every search misses every point, + // silently, which is the exact failure the check was built to catch. + // Asserted against the adapter's constants rather than against "dense" and "text", so this + // fact follows a renamed constant instead of pinning a spelling. Asserted on the options the + // adapter handed the store, the idiom this class already uses for Limit, because no corpus + // can tell "queried the right name" from "queried a name that happens to match". + string collection = $"names-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); - var thrown = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - // The surrounding phrase, not the bare digit: the message also carries a 32-character hex - // collection name, so Contains("4") and Contains("8") both pass on a chance digit in it - // even when the two widths have been swapped, or dropped from the message entirely. - Assert.Contains("of 4 dimensions", thrown.Message, StringComparison.Ordinal); - Assert.Contains($"embeds at {KbShapedCorpus.Dim}", thrown.Message, StringComparison.Ordinal); + QdrantKnowledgeStoreOptions options = OptionsOf(port); - // Both ways out, named as document settings rather than as one repository's CLI. - Assert.Contains("providers.embeddings", thrown.Message, StringComparison.Ordinal); - Assert.DoesNotContain("kb sync", thrown.Message, StringComparison.Ordinal); + Assert.Equal("dense", options.VectorName, StringComparer.Ordinal); + Assert.Equal("text", options.Fields!.Lexical, StringComparer.Ordinal); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + [QdrantFact] + public async Task CreateSearchAsync_PayloadHasNoBody_FailsTheStart() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + // The payload schema is owned by whatever ingests the cards, usually in another repository + // on another release cycle, so it is the likeliest half + // of this seam to drift -- and the only failure mode with no symptom: the store reads a missing + // key as an empty string, "" satisfies every `required` on KnowledgeCard, and every turn of + // every agent is then injected with blank cards. The fixture cannot catch it either; it writes + // exactly the keys the store reads, so it can only ever agree with itself. + string collection = $"nobody-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + + try + { + // Exactly the drift being guarded against: the ingester renames body to text_body. + Guid[] everyPoint = + [.. Enumerable.Range(0, KbShapedCorpus.Count).Select(i => KbShapedCorpus.PointKey(KbShapedCorpus.Id(i)))]; + _ = await client.DeletePayloadAsync( + collection, ["body"], everyPoint, cancellationToken: TestContext.Current.CancellationToken); + + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); + + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); + + Assert.Contains(collection, thrown.Message, StringComparison.Ordinal); + Assert.Contains("'body'", thrown.Message, StringComparison.Ordinal); + Assert.Contains("providers.knowledge.fields", thrown.Message, StringComparison.Ordinal); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - - [QdrantFact] - public async Task CreateSearchAsync_RealCollection_Opens() - { - var collection = $"adapter-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - try + [QdrantFact] + public async Task CreateSearchAsync_EmptyCollection_Opens() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + // The deliberate hole in the payload check, and the reason it is deliberate: a collection with + // no points has no payload contract to violate, and refusing the start would make a host + // unbootable in the window between creating the alias and the first ingest run filling it. + string collection = $"empty-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection); + + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); - var port = await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken); + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - Assert.NotNull(port); - } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - [QdrantFact] - public async Task CreateSearchAsync_TheStoreItOpens_FetchesWhatTheMostGenerousAgentMayAskFor() - { - // Ruling 14(c). example.yaml gives the analyst limit: 8, the schema accepts up to 20, and the - // store this adapter opened fetched 5 -- so the analyst asked for 8, received 5, and nothing - // anywhere said so. One store serves every agent out of one fetch, so the fetch is the - // document's ceiling and not the store's own convenience default. - // - // Asserted on the options the adapter handed the store rather than on a returned card count, - // because the shipped ScoreFloor of 0.25 caps a plain query at three ranked cards whatever the - // limit is -- see QdrantKnowledgeStoreTests.SearchAsync_ScoreFloor_KeepsExactlyTheCardsAtOrAboveIt, - // which pins that boundary, and the fix report's concern about it. The behavioural half of - // this chain is already pinned by SearchAsync_LimitAboveTheDefaultPrefetchDepth_ReturnsThatMany: - // whatever Limit the store is given, it reaches Qdrant. This fact is the other half -- WHICH - // limit the adapter gives it. The reflection idiom is the one this class already uses on - // QdrantClient._isDisposed. - var collection = $"limit-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - - try + [QdrantFact] + public async Task CreateSearchAsync_Uuid5LookupOverNumericPointKeys_FailsTheStart() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + // The id check only runs when a point actually carries a links.field value, so this fixture + // needs one such point -- with a numeric key, which no uuid5 or direct formula ever produces. + string collection = $"numeric-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection); - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); + try + { + PointStruct point = new() + { + Id = new PointId { Num = 1 }, + Vectors = new Vectors + { + Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, + }, + }; + point.Payload["card_id"] = "num-00"; + point.Payload["body"] = "numeric key card"; + point.Payload["see_also"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = "num-01" } } }, + }; - var options = OptionsOf(port); + _ = await client.UpsertAsync( + collection, [point], cancellationToken: TestContext.Current.CancellationToken); - Assert.Equal(AgentKnowledgeConfiguration.MaximumLimit, options.Limit); - Assert.True( - options.Limit >= 8, - $"example.yaml's analyst asks for 8 and this store fetches {options.Limit}"); + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = new() + { + Kind = "qdrant", + Collection = collection, + Vector = "dense", + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + Links = KbShapedCorpus.Links, + }; + + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); + + Assert.Contains("keyed by number", failure.Message, StringComparison.Ordinal); + Assert.Contains("links.lookup: filter", failure.Message, StringComparison.Ordinal); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + [QdrantTheory] + [InlineData(KnowledgeLinkLookup.Uuid5)] + [InlineData(KnowledgeLinkLookup.Direct)] + [InlineData(KnowledgeLinkLookup.Filter)] + public async Task CreateSearchAsync_EmptyCollection_OpensUnderEveryLookupMode(KnowledgeLinkLookup lookup) { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + string collection = $"empty-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection); + + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = new() + { + Kind = "qdrant", + Collection = collection, + Vector = "dense", + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + Links = KbShapedCorpus.Links with { Lookup = lookup }, + }; + + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); + + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - [QdrantFact] - public async Task CreateSearchAsync_TheStoreItOpens_QueriesTheNamesTheStartupCheckAsserted() - { - // A guard that does not guard. The startup check reads a named vector off the collection and - // refuses to boot without it, while the store used to query the options record's OWN "dense" - // and "text" literals, which that check never governed. Both agreed, so nothing was broken; - // change either one and the boot check still passes while every search misses every point, - // silently, which is the exact failure the check was built to catch. - // Asserted against the adapter's constants rather than against "dense" and "text", so this - // fact follows a renamed constant instead of pinning a spelling. Asserted on the options the - // adapter handed the store, the idiom this class already uses for Limit, because no corpus - // can tell "queried the right name" from "queried a name that happens to match". - var collection = $"names-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - - try + [Fact] + public void Kind_And_Capabilities_AreDeclared() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + QdrantKnowledgeAdapter adapter = new(_ => throw new UnreachableException(), Embeddings); - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); + Assert.Equal("qdrant", adapter.Kind); + Assert.True(adapter.CanServeSearch); + Assert.True(adapter.CanScope); + } - var options = OptionsOf(port); + // The next two tests exercise the production constructor (no injected client factory), which + // parses providers.knowledge.endpoint before ever touching the network. Neither needs a live + // Qdrant: the failure happens before BuildClientAsync would open one. - Assert.Equal("dense", options.VectorName, StringComparer.Ordinal); - Assert.Equal("text", options.Fields!.Lexical, StringComparer.Ordinal); - } - finally + [Fact] + public async Task CreateSearchAsync_NoGeneratorAnywhere_FailsAndNamesProvidersEmbeddings() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + // Ruling 17a: the failure names the block to write. It must fire before any network work, + // so the production constructor over an unreachable endpoint is safe here. + QdrantKnowledgeAdapter adapter = new(); + KnowledgeProviderConfiguration entry = new() + { + Kind = "qdrant", + Collection = "unreachable", + Endpoint = "https://cluster.example.com:6334", + Fields = KbShapedCorpus.Fields, + }; + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); + + Assert.Equal("/providers/embeddings", failure.Pointer); + Assert.Contains("providers.embeddings", failure.Message, StringComparison.Ordinal); } - } - [QdrantFact] - public async Task CreateSearchAsync_PayloadHasNoBody_FailsTheStart() - { - // The payload schema is owned by whatever ingests the cards, usually in another repository - // on another release cycle, so it is the likeliest half - // of this seam to drift -- and the only failure mode with no symptom: the store reads a missing - // key as an empty string, "" satisfies every `required` on KnowledgeCard, and every turn of - // every agent is then injected with blank cards. The fixture cannot catch it either; it writes - // exactly the keys the store reads, so it can only ever agree with itself. - var collection = $"nobody-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - - try + [QdrantFact] + public async Task CreateSearchAsync_AGeneratorPassedThroughThePort_OpensTheStore() { - // Exactly the drift being guarded against: the ingester renames body to text_body. - Guid[] everyPoint = - [.. Enumerable.Range(0, KbShapedCorpus.Count).Select(i => KbShapedCorpus.PointKey(KbShapedCorpus.Id(i)))]; - await client.DeletePayloadAsync( - collection, ["body"], everyPoint, cancellationToken: TestContext.Current.CancellationToken); + // The providers.embeddings path: no generator in any constructor, the one the host built + // arrives as the CreateSearchAsync argument. + string collection = $"portgen-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + try + { + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient()); + KnowledgeProviderConfiguration entry = DenseEntry(collection); - var thrown = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: Embeddings, requireScope: false, TestContext.Current.CancellationToken); - Assert.Contains(collection, thrown.Message, StringComparison.Ordinal); - Assert.Contains("'body'", thrown.Message, StringComparison.Ordinal); - Assert.Contains("providers.knowledge.fields", thrown.Message, StringComparison.Ordinal); + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - finally + + [Fact] + public async Task CreateSearchAsync_NoEndpoint_FailsTheLoadAndPointsAtTheField() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + QdrantKnowledgeAdapter adapter = new(Embeddings); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + new KnowledgeProviderConfiguration + { + Kind = "qdrant", + Collection = "unreachable", + Fields = KbShapedCorpus.Fields, + }, + secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + + Assert.Equal("/providers/knowledge/endpoint", failure.Pointer); } - } - [QdrantFact] - public async Task CreateSearchAsync_EmptyCollection_Opens() - { - // The deliberate hole in the payload check, and the reason it is deliberate: a collection with - // no points has no payload contract to violate, and refusing the start would make a host - // unbootable in the window between creating the alias and the first ingest run filling it. - var collection = $"empty-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection); - - try + [Fact] + public async Task CreateSearchAsync_EndpointNotAUrl_FailsTheLoadAndPointsAtTheSameField() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + QdrantKnowledgeAdapter adapter = new(Embeddings); + KnowledgeProviderConfiguration entry = new() + { + Kind = "qdrant", + Collection = "unreachable", + Endpoint = "not a url", + Fields = KbShapedCorpus.Fields, + }; - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); - Assert.NotNull(port); + Assert.Equal("/providers/knowledge/endpoint", failure.Pointer); } - finally + + [QdrantFact] + public async Task CreateSearchAsync_WrongLinkPrefix_FailsTheStartNamingBothIds() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); - } - } + KnowledgeProviderConfiguration entry = Entry() with + { + Links = KbShapedCorpus.Links with { Prefix = "wrong:" }, + }; - [QdrantFact] - public async Task CreateSearchAsync_Uuid5LookupOverNumericPointKeys_FailsTheStart() - { - // The id check only runs when a point actually carries a links.field value, so this fixture - // needs one such point -- with a numeric key, which no uuid5 or direct formula ever produces. - var collection = $"numeric-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection); + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken)); + + Assert.Contains("links.lookup", failure.Message, StringComparison.Ordinal); + Assert.Contains("prefix", failure.Message, StringComparison.Ordinal); + } - try + [QdrantFact] + public async Task CreateSearchAsync_DirectLookupOverANonGuidCardId_NamesTheIdAndPointsAtFilter() { - var point = new PointStruct + // links.lookup: direct reads neither namespace nor prefix, so the failure must not blame + // them the way the uuid5 mismatch message does -- that would send an operator chasing a + // setting this mode never looks at. + // + // A dedicated single-point collection, not the shared KbShapedCorpus: AssertPayloadAsync + // scrolls one arbitrary point, and Qdrant does not guarantee which one comes back. Every + // KbShapedCorpus card is non-GUID, so the assertion would still fire no matter which point + // the scroll returned -- but the id it names would not be predictable, and naming the right + // id is the whole point of this test. + const string cardId = "direct-01"; + string collection = $"direct-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection); + + try { - Id = new PointId { Num = 1 }, - Vectors = new Vectors + PointStruct point = DensePoint(); + point.Payload["card_id"] = cardId; + point.Payload["body"] = "direct lookup card"; + point.Payload["see_also"] = new Value { ListValue = new ListValue() }; + + _ = await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = new() { - Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, - }, - }; - point.Payload["card_id"] = "num-00"; - point.Payload["body"] = "numeric key card"; - point.Payload["see_also"] = new Value + Kind = "qdrant", + Collection = collection, + Vector = "dense", + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + Links = KbShapedCorpus.Links with { Lookup = KnowledgeLinkLookup.Direct }, + }; + + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, + TestContext.Current.CancellationToken)); + + Assert.Contains(cardId, failure.Message, StringComparison.Ordinal); + Assert.Contains("not a GUID", failure.Message, StringComparison.Ordinal); + Assert.Contains("links.lookup: filter", failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain("namespace", failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain("prefix", failure.Message, StringComparison.Ordinal); + } + finally { - ListValue = new ListValue { Values = { new Value { StringValue = "num-01" } } }, - }; - - await client.UpsertAsync( - collection, [point], cancellationToken: TestContext.Current.CancellationToken); + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration + [Fact] + public async Task CreateSearchAsync_LinksWithoutAnIdField_FailsTheLoadPointingAtFieldsId() + { + // Item 1 of the recommendation: a feature error is raised against the document, before any + // network work, so this test needs no server. + QdrantKnowledgeAdapter adapter = new(Embeddings); + KnowledgeProviderConfiguration entry = new() { Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - Links = KbShapedCorpus.Links, + Collection = "unreachable", + Endpoint = "https://cluster.example.com:6334", + Fields = new KnowledgeFieldsConfiguration { Body = "body", Id = null }, + Links = new KnowledgeLinksConfiguration { Field = "see_also" }, }; - var failure = await Assert.ThrowsAsync( + ConfigurationLoadException failure = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); - Assert.Contains("keyed by number", failure.Message, StringComparison.Ordinal); - Assert.Contains("links.lookup: filter", failure.Message, StringComparison.Ordinal); + Assert.Equal("/providers/knowledge/fields/id", failure.Pointer); + Assert.Contains("links", failure.Message, StringComparison.Ordinal); } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); - } - } - [QdrantTheory] - [InlineData(KnowledgeLinkLookup.Uuid5)] - [InlineData(KnowledgeLinkLookup.Direct)] - [InlineData(KnowledgeLinkLookup.Filter)] - public async Task CreateSearchAsync_EmptyCollection_OpensUnderEveryLookupMode(KnowledgeLinkLookup lookup) - { - var collection = $"empty-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection); - - try + [QdrantFact] + public async Task CreateSearchAsync_FilterLookupIgnoresNamespaceAndPrefix_Starts() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration + // filter derives no key, so uuid5's couplings must not be able to fail it. + KnowledgeProviderConfiguration entry = Entry() with { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - Links = KbShapedCorpus.Links with { Lookup = lookup }, + Links = KbShapedCorpus.Links with { Lookup = KnowledgeLinkLookup.Filter, Prefix = "wrong:", Namespace = "dns" }, }; - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); + IKnowledgeRetrievalPort store = await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken); - Assert.NotNull(port); + Assert.NotNull(store); + (store as IDisposable)?.Dispose(); } - finally + + [QdrantFact] + public async Task CreateSearchAsync_NoLinksBlock_SkipsTheRoundTripCheckEntirely() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + // KbShapedCorpus points DO carry see_also and uuid5 keys, but with no links: block there is + // no feature to protect and no check to run. + using IDisposable store = await Adapter().CreateSearchAsync( + Entry(), secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken) as IDisposable ?? throw new InvalidOperationException(); + + Assert.NotNull(store); } - } - [Fact] - public void Kind_And_Capabilities_AreDeclared() - { - var adapter = new QdrantKnowledgeAdapter(_ => throw new UnreachableException(), Embeddings); + [QdrantFact] + public async Task CreateSearchAsync_NoLinksFieldInPayload_SkipsTheIdCheck() + { + // The prefix is wrong AND the links field names nothing in the payload. No expansion can + // ever run, so there is nothing for the id check to protect and the start must succeed. + KnowledgeProviderConfiguration entry = Entry() with + { + Links = KbShapedCorpus.Links with { Field = "no_such_field", Prefix = "wrong:" }, + }; - Assert.Equal("qdrant", adapter.Kind); - Assert.True(adapter.CanServeSearch); - Assert.True(adapter.CanScope); - } + IKnowledgeRetrievalPort store = await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken); - // The next two tests exercise the production constructor (no injected client factory), which - // parses providers.knowledge.endpoint before ever touching the network. Neither needs a live - // Qdrant: the failure happens before BuildClientAsync would open one. + Assert.NotNull(store); + (store as IDisposable)?.Dispose(); + } - [Fact] - public async Task CreateSearchAsync_NoGeneratorAnywhere_FailsAndNamesProvidersEmbeddings() - { - // Ruling 17a: the failure names the block to write. It must fire before any network work, - // so the production constructor over an unreachable endpoint is safe here. - var adapter = new QdrantKnowledgeAdapter(); - var entry = new KnowledgeProviderConfiguration + [QdrantFact] + public async Task CreateSearchAsync_RenamedVector_FailsNamingTheConfiguredName() { - Kind = "qdrant", - Collection = "unreachable", - Endpoint = "https://cluster.example.com:6334", - Fields = KbShapedCorpus.Fields, - }; - - var failure = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); - - Assert.Equal("/providers/embeddings", failure.Pointer); - Assert.Contains("providers.embeddings", failure.Message, StringComparison.Ordinal); - } + KnowledgeProviderConfiguration entry = Entry() with { Vector = "not_dense" }; - [QdrantFact] - public async Task CreateSearchAsync_AGeneratorPassedThroughThePort_OpensTheStore() - { - // The providers.embeddings path: no generator in any constructor, the one the host built - // arrives as the CreateSearchAsync argument. - var collection = $"portgen-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken)); - try + Assert.Contains("not_dense", failure.Message, StringComparison.Ordinal); + } + + [QdrantFact] + public async Task CreateSearchAsync_RenamedBodyFieldThatIsAbsent_FailsNamingIt() { - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient()); - var entry = DenseEntry(collection); + KnowledgeProviderConfiguration entry = Entry() with + { + Fields = new KnowledgeFieldsConfiguration { Body = "no_such_body" }, + }; - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: Embeddings, requireScope: false, TestContext.Current.CancellationToken); + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken)); - Assert.NotNull(port); - } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + Assert.Contains("no_such_body", failure.Message, StringComparison.Ordinal); } - } - [Fact] - public async Task CreateSearchAsync_NoEndpoint_FailsTheLoadAndPointsAtTheField() - { - var adapter = new QdrantKnowledgeAdapter(Embeddings); + [QdrantFact] + public async Task CreateSearchAsync_UnknownAnalyzer_FailsNamingWhatIsRegistered() + { + KnowledgeProviderConfiguration entry = Entry() with { Analyzer = "clause-numbers" }; - var failure = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = "unreachable", - Fields = KbShapedCorpus.Fields, - }, - secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + Exception failure = await Assert.ThrowsAnyAsync( + async () => await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken)); - Assert.Equal("/providers/knowledge/endpoint", failure.Pointer); - } + Assert.Contains("clause-numbers", failure.Message, StringComparison.Ordinal); + Assert.Contains("none", failure.Message, StringComparison.Ordinal); + } - [Fact] - public async Task CreateSearchAsync_EndpointNotAUrl_FailsTheLoadAndPointsAtTheSameField() - { - var adapter = new QdrantKnowledgeAdapter(Embeddings); - var entry = new KnowledgeProviderConfiguration + [QdrantFact] + public async Task CreateSearchAsync_CustomAnalyzer_IsSelectedByName() { - Kind = "qdrant", - Collection = "unreachable", - Endpoint = "not a url", - Fields = KbShapedCorpus.Fields, - }; + KnowledgeProviderConfiguration entry = Entry() with { Analyzer = "always-empty" }; - var failure = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); + IKnowledgeRetrievalPort store = await Adapter() + .UseAnalyzers(new AlwaysEmptyAnalyzer()) + .CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken); - Assert.Equal("/providers/knowledge/endpoint", failure.Pointer); - } + Assert.NotNull(store); + (store as IDisposable)?.Dispose(); + } - [QdrantFact] - public async Task CreateSearchAsync_WrongLinkPrefix_FailsTheStartNamingBothIds() - { - var entry = Entry() with + [QdrantFact] + public async Task CreateSearchAsync_DocumentDeclaresAWildcard_ReachesTheStoreOptions() { - Links = KbShapedCorpus.Links with { Prefix = "wrong:" }, - }; + KnowledgeProviderConfiguration entry = Entry() with + { + Scope = KbShapedCorpus.Scope with { Wildcard = new() { Value = "*", Facets = ["model"] } }, + }; - var failure = await Assert.ThrowsAsync( - async () => await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken)); + IKnowledgeRetrievalPort port = await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: true, TestContext.Current.CancellationToken); - Assert.Contains("links.lookup", failure.Message, StringComparison.Ordinal); - Assert.Contains("prefix", failure.Message, StringComparison.Ordinal); - } + // The filter these options go on to produce is covered by QdrantWildcardScopeTests. + QdrantKnowledgeStoreOptions options = OptionsOf(port); - [QdrantFact] - public async Task CreateSearchAsync_DirectLookupOverANonGuidCardId_NamesTheIdAndPointsAtFilter() - { - // links.lookup: direct reads neither namespace nor prefix, so the failure must not blame - // them the way the uuid5 mismatch message does -- that would send an operator chasing a - // setting this mode never looks at. - // - // A dedicated single-point collection, not the shared KbShapedCorpus: AssertPayloadAsync - // scrolls one arbitrary point, and Qdrant does not guarantee which one comes back. Every - // KbShapedCorpus card is non-GUID, so the assertion would still fire no matter which point - // the scroll returned -- but the id it names would not be predictable, and naming the right - // id is the whole point of this test. - const string cardId = "direct-01"; - var collection = $"direct-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection); - - try - { - var point = DensePoint(); - point.Payload["card_id"] = cardId; - point.Payload["body"] = "direct lookup card"; - point.Payload["see_also"] = new Value { ListValue = new ListValue() }; + Assert.Equal("*", options.ScopeWildcard); + Assert.Equal(["model"], options.ScopeWildcardFacets); - await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + (port as IDisposable)?.Dispose(); + } - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration + [Fact] + public async Task CreateSearchAsync_UnknownMapper_FailsTheLoadPointingAtMapper() + { + QdrantKnowledgeAdapter adapter = new(Embeddings); + KnowledgeProviderConfiguration entry = new() { Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - Links = KbShapedCorpus.Links with { Lookup = KnowledgeLinkLookup.Direct }, + Collection = "unreachable", + Endpoint = "https://cluster.example.com:6334", + Mapper = "acme-catalog", }; - var failure = await Assert.ThrowsAsync( + ConfigurationLoadException failure = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, - TestContext.Current.CancellationToken)); + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); - Assert.Contains(cardId, failure.Message, StringComparison.Ordinal); - Assert.Contains("not a GUID", failure.Message, StringComparison.Ordinal); - Assert.Contains("links.lookup: filter", failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain("namespace", failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain("prefix", failure.Message, StringComparison.Ordinal); - } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + Assert.Equal("/providers/knowledge/mapper", failure.Pointer); + Assert.Contains("acme-catalog", failure.Message, StringComparison.Ordinal); + Assert.Contains("UseMappers", failure.Message, StringComparison.Ordinal); } - } - [Fact] - public async Task CreateSearchAsync_LinksWithoutAnIdField_FailsTheLoadPointingAtFieldsId() - { - // Item 1 of the recommendation: a feature error is raised against the document, before any - // network work, so this test needs no server. - var adapter = new QdrantKnowledgeAdapter(Embeddings); - var entry = new KnowledgeProviderConfiguration + [QdrantFact] + public async Task CreateSearchAsync_CustomMapper_OpensAndMapsEverySearchThroughIt() { - Kind = "qdrant", - Collection = "unreachable", - Endpoint = "https://cluster.example.com:6334", - Fields = new KnowledgeFieldsConfiguration { Body = "body", Id = null }, - Links = new KnowledgeLinksConfiguration { Field = "see_also" }, - }; - - var failure = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); - - Assert.Equal("/providers/knowledge/fields/id", failure.Pointer); - Assert.Contains("links", failure.Message, StringComparison.Ordinal); - } - - [QdrantFact] - public async Task CreateSearchAsync_FilterLookupIgnoresNamespaceAndPrefix_Starts() - { - // filter derives no key, so uuid5's couplings must not be able to fail it. - var entry = Entry() with - { - Links = KbShapedCorpus.Links with { Lookup = KnowledgeLinkLookup.Filter, Prefix = "wrong:", Namespace = "dns" }, - }; - - var store = await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken); + KnowledgeProviderConfiguration entry = Entry() with { Mapper = "upper-body" }; - Assert.NotNull(store); - (store as IDisposable)?.Dispose(); - } + IKnowledgeRetrievalPort port = await Adapter() + .UseMappers(new UpperBodyMapper()) + .CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken); - [QdrantFact] - public async Task CreateSearchAsync_NoLinksBlock_SkipsTheRoundTripCheckEntirely() - { - // KbShapedCorpus points DO carry see_also and uuid5 keys, but with no links: block there is - // no feature to protect and no check to run. - using var store = await Adapter().CreateSearchAsync( - Entry(), secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken) as IDisposable ?? throw new InvalidOperationException(); + IReadOnlyList cards = await port.SearchAsync("deck", null, TestContext.Current.CancellationToken); - Assert.NotNull(store); - } + Assert.NotEmpty(cards); + Assert.All(cards, card => Assert.Equal(card.Text.ToUpperInvariant(), card.Text)); + (port as IDisposable)?.Dispose(); + } - [QdrantFact] - public async Task CreateSearchAsync_NoLinksFieldInPayload_SkipsTheIdCheck() - { - // The prefix is wrong AND the links field names nothing in the payload. No expansion can - // ever run, so there is nothing for the id check to protect and the start must succeed. - var entry = Entry() with + [QdrantFact] + public async Task CreateSearchAsync_CustomMapperThatReadsBlank_FailsTheStartNamingTheMapper() { - Links = KbShapedCorpus.Links with { Field = "no_such_field", Prefix = "wrong:" }, - }; - - var store = await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken); + KnowledgeProviderConfiguration entry = Entry() with { Mapper = "blank" }; - Assert.NotNull(store); - (store as IDisposable)?.Dispose(); - } - - [QdrantFact] - public async Task CreateSearchAsync_RenamedVector_FailsNamingTheConfiguredName() - { - var entry = Entry() with { Vector = "not_dense" }; + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await Adapter() + .UseMappers(new BlankMapper()) + .CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: false, + TestContext.Current.CancellationToken)); - var failure = await Assert.ThrowsAsync( - async () => await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken)); - - Assert.Contains("not_dense", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("'blank'", failure.Message, StringComparison.Ordinal); + Assert.Contains("blank cards", failure.Message, StringComparison.Ordinal); + } - [QdrantFact] - public async Task CreateSearchAsync_RenamedBodyFieldThatIsAbsent_FailsNamingIt() - { - var entry = Entry() with + [QdrantFact] + public async Task CreateSearchAsync_IdRoleDisabled_OpensACollectionWithNoIdField() { - Fields = new KnowledgeFieldsConfiguration { Body = "no_such_body" }, - }; + // Item 1 of the recommendation: body is the only required role. This collection carries + // nothing but body, and the document says so with fields.id: null. + string collection = $"noid-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection); - var failure = await Assert.ThrowsAsync( - async () => await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken)); - - Assert.Contains("no_such_body", failure.Message, StringComparison.Ordinal); - } - - [QdrantFact] - public async Task CreateSearchAsync_UnknownAnalyzer_FailsNamingWhatIsRegistered() - { - var entry = Entry() with { Analyzer = "clause-numbers" }; - - var failure = await Assert.ThrowsAnyAsync( - async () => await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken)); + try + { + PointStruct point = DensePoint(); + point.Payload["body"] = "a card with no id concept"; + _ = await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); - Assert.Contains("clause-numbers", failure.Message, StringComparison.Ordinal); - Assert.Contains("none", failure.Message, StringComparison.Ordinal); - } + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = new() + { + Kind = "qdrant", + Collection = collection, + Vector = "dense", - [QdrantFact] - public async Task CreateSearchAsync_CustomAnalyzer_IsSelectedByName() - { - var entry = Entry() with { Analyzer = "always-empty" }; + // This collection holds one point carrying a body and nothing else, so the entry + // maps a body and nothing else. + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + }; - var store = await Adapter() - .UseAnalyzers(new AlwaysEmptyAnalyzer()) - .CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken); + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - Assert.NotNull(store); - (store as IDisposable)?.Dispose(); - } + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - [QdrantFact] - public async Task CreateSearchAsync_DocumentDeclaresAWildcard_ReachesTheStoreOptions() - { - var entry = Entry() with + [QdrantFact] + public async Task CreateSearchAsync_DefaultIdOverACollectionWithoutOne_StillFailsTheStart() { - Scope = KbShapedCorpus.Scope with { Wildcard = new() { Value = "*", Facets = ["model"] } }, - }; + // The other half of the convention: defaults are declarations. A document that never + // mentions fields.id declared card_id, and a collection without it is still drift. + string collection = $"noiddefault-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await CreateDenseCollectionAsync(client, collection); - var port = await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: true, TestContext.Current.CancellationToken); + try + { + PointStruct point = DensePoint(); + point.Payload["body"] = "a card with no id concept"; + _ = await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); - // The filter these options go on to produce is covered by QdrantWildcardScopeTests. - var options = OptionsOf(port); + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = DenseEntry(collection); - Assert.Equal("*", options.ScopeWildcard); - Assert.Equal(["model"], options.ScopeWildcardFacets); + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); - (port as IDisposable)?.Dispose(); - } + Assert.Contains("'card_id'", failure.Message, StringComparison.Ordinal); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - [Fact] - public async Task CreateSearchAsync_UnknownMapper_FailsTheLoadPointingAtMapper() - { - var adapter = new QdrantKnowledgeAdapter(Embeddings); - var entry = new KnowledgeProviderConfiguration + [QdrantFact] + public async Task CreateSearchAsync_NoVectorNamed_OpensAnAnonymousVectorCollection() { - Kind = "qdrant", - Collection = "unreachable", - Endpoint = "https://cluster.example.com:6334", - Mapper = "acme-catalog", - }; - - var failure = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); - - Assert.Equal("/providers/knowledge/mapper", failure.Pointer); - Assert.Contains("acme-catalog", failure.Message, StringComparison.Ordinal); - Assert.Contains("UseMappers", failure.Message, StringComparison.Ordinal); - } - - [QdrantFact] - public async Task CreateSearchAsync_CustomMapper_OpensAndMapsEverySearchThroughIt() - { - var entry = Entry() with { Mapper = "upper-body" }; - - var port = await Adapter() - .UseMappers(new UpperBodyMapper()) - .CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken); + // Item 2 of the recommendation, the single biggest compatibility win: the default shape the + // Qdrant client, MEVD's connector, LangChain, LlamaIndex and Spring AI all create. + string collection = $"anonadapter-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await client.CreateCollectionAsync( + collection, + new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine }, + cancellationToken: TestContext.Current.CancellationToken); + + try + { + PointStruct point = new() + { + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = new float[KbShapedCorpus.Dim], + }; + point.Payload["card_id"] = "anon-00"; + point.Payload["body"] = "anonymous vector card"; + _ = await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + + QdrantKnowledgeAdapter adapter = new(_ => QdrantServer.CreateClient(), Embeddings); + KnowledgeProviderConfiguration entry = new() + { + Kind = "qdrant", + Collection = collection, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + }; - var cards = await port.SearchAsync("deck", null, TestContext.Current.CancellationToken); + using IDisposable port = (IDisposable)await adapter.CreateSearchAsync( + entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - Assert.NotEmpty(cards); - Assert.All(cards, card => Assert.Equal(card.Text.ToUpperInvariant(), card.Text)); - (port as IDisposable)?.Dispose(); - } + Assert.NotNull(port); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } - [QdrantFact] - public async Task CreateSearchAsync_CustomMapperThatReadsBlank_FailsTheStartNamingTheMapper() - { - var entry = Entry() with { Mapper = "blank" }; + [QdrantFact] + public async Task CreateSearchAsync_NoVectorNamedOverNamedVectors_FailsTheStart() + { + KnowledgeProviderConfiguration entry = Entry() with { Vector = null }; - var failure = await Assert.ThrowsAsync( - async () => await Adapter() - .UseMappers(new BlankMapper()) - .CreateSearchAsync( + InvalidOperationException failure = await Assert.ThrowsAsync( + async () => await Adapter().CreateSearchAsync( entry, secrets: null, Embedder(), requireScope: false, TestContext.Current.CancellationToken)); - Assert.Contains("'blank'", failure.Message, StringComparison.Ordinal); - Assert.Contains("blank cards", failure.Message, StringComparison.Ordinal); - } - - [QdrantFact] - public async Task CreateSearchAsync_IdRoleDisabled_OpensACollectionWithNoIdField() - { - // Item 1 of the recommendation: body is the only required role. This collection carries - // nothing but body, and the document says so with fields.id: null. - var collection = $"noid-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection); + Assert.Contains("providers.knowledge.vector", failure.Message, StringComparison.Ordinal); + Assert.Contains("names none", failure.Message, StringComparison.Ordinal); + } - try + private sealed class AlwaysEmptyAnalyzer : IKnowledgeQueryAnalyzer { - var point = DensePoint(); - point.Payload["body"] = "a card with no id concept"; - await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + public string Name => "always-empty"; - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration + public IReadOnlyList RequiredTerms(string query) { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - - // This collection holds one point carrying a body and nothing else, so the entry - // maps a body and nothing else. - Fields = new KnowledgeFieldsConfiguration { Body = "body" }, - }; - - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - - Assert.NotNull(port); - } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + return []; + } } - } - - [QdrantFact] - public async Task CreateSearchAsync_DefaultIdOverACollectionWithoutOne_StillFailsTheStart() - { - // The other half of the convention: defaults are declarations. A document that never - // mentions fields.id declared card_id, and a collection without it is still drift. - var collection = $"noiddefault-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await CreateDenseCollectionAsync(client, collection); - try + private sealed class UpperBodyMapper : IKnowledgePointMapper { - var point = DensePoint(); - point.Payload["body"] = "a card with no id concept"; - await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + public string Name => "upper-body"; - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = DenseEntry(collection); + public KnowledgeCard? Map(KnowledgePoint point) + { + return new() + { + CardId = point.PointId, + Text = (point.Payload.TryGetValue("body", out object? body) ? body as string ?? string.Empty : string.Empty) + .ToUpperInvariant(), + ViaLink = false, + }; + } + } - var failure = await Assert.ThrowsAsync( - async () => await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken)); + private sealed class BlankMapper : IKnowledgePointMapper + { + public string Name => "blank"; - Assert.Contains("'card_id'", failure.Message, StringComparison.Ordinal); + public KnowledgeCard? Map(KnowledgePoint point) + { + return new() + { + CardId = point.PointId, + Text = string.Empty, + ViaLink = false, + }; + } } - finally + + private KnowledgeProviderConfiguration Entry() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + return new() + { + Kind = QdrantKnowledgeAdapter.ProviderKind, + Collection = _corpus.Name, + Vector = "dense", + + // The corpus describes its own payload. Nothing here is inherited: AgentCore ships no + // field names, so an entry that omits this block reads nothing off any point. + Fields = KbShapedCorpus.Fields, + Scope = KbShapedCorpus.Scope, + }; } - } - [QdrantFact] - public async Task CreateSearchAsync_NoVectorNamed_OpensAnAnonymousVectorCollection() - { - // Item 2 of the recommendation, the single biggest compatibility win: the default shape the - // Qdrant client, MEVD's connector, LangChain, LlamaIndex and Spring AI all create. - var collection = $"anonadapter-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine }, - cancellationToken: TestContext.Current.CancellationToken); - - try + /// A point carrying an 8-wide "dense" vector and no payload. The caller fills it. + private static PointStruct DensePoint() { - var point = new PointStruct + return new() { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new float[KbShapedCorpus.Dim], + Vectors = new Vectors + { + Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, + }, }; - point.Payload["card_id"] = "anon-00"; - point.Payload["body"] = "anonymous vector card"; - await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + } + + /// + /// The options the adapter handed the store. No corpus can tell "queried the right name" from + /// "queried a name that happens to match", so these facts read the store's own field. + /// + private static QdrantKnowledgeStoreOptions OptionsOf(object port) + { + return (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) + .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! + .GetValue(port)!; + } - var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration + private static KnowledgeProviderConfiguration DenseEntry(string collection) + { + return new() { Kind = "qdrant", Collection = collection, - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + Vector = "dense", + Fields = KbShapedCorpus.Fields, }; - - using var port = (IDisposable)await adapter.CreateSearchAsync( - entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - - Assert.NotNull(port); } - finally + + /// A collection carrying one named "dense" vector, the shape every fixture here uses. + private static Task CreateDenseCollectionAsync( + QdrantClient client, + string collection, + ulong size = KbShapedCorpus.Dim) { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + return client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap + { + Map = { ["dense"] = new VectorParams { Size = size, Distance = Distance.Cosine } }, + }, + cancellationToken: TestContext.Current.CancellationToken); } - } - - [QdrantFact] - public async Task CreateSearchAsync_NoVectorNamedOverNamedVectors_FailsTheStart() - { - var entry = Entry() with { Vector = null }; - - var failure = await Assert.ThrowsAsync( - async () => await Adapter().CreateSearchAsync( - entry, secrets: null, Embedder(), requireScope: false, - TestContext.Current.CancellationToken)); - - Assert.Contains("providers.knowledge.vector", failure.Message, StringComparison.Ordinal); - Assert.Contains("names none", failure.Message, StringComparison.Ordinal); - } - private sealed class AlwaysEmptyAnalyzer : IKnowledgeQueryAnalyzer - { - public string Name => "always-empty"; - - public IReadOnlyList RequiredTerms(string query) => []; - } - - private sealed class UpperBodyMapper : IKnowledgePointMapper - { - public string Name => "upper-body"; - - public KnowledgeCard? Map(KnowledgePoint point) => new() + private static QdrantKnowledgeAdapter Adapter() { - CardId = point.PointId, - Text = (point.Payload.TryGetValue("body", out var body) ? body as string ?? string.Empty : string.Empty) - .ToUpperInvariant(), - ViaLink = false, - }; - } - - private sealed class BlankMapper : IKnowledgePointMapper - { - public string Name => "blank"; + return new(_ => QdrantServer.CreateClient()); + } - public KnowledgeCard? Map(KnowledgePoint point) => new() + private static FakeEmbeddingGenerator Embedder() { - CardId = point.PointId, - Text = string.Empty, - ViaLink = false, - }; - } + return new(KbShapedCorpus.QueryVector()); + } - private KnowledgeProviderConfiguration Entry() => new() - { - Kind = QdrantKnowledgeAdapter.ProviderKind, - Collection = _corpus.Name, - Vector = "dense", - - // The corpus describes its own payload. Nothing here is inherited: AgentCore ships no - // field names, so an entry that omits this block reads nothing off any point. - Fields = KbShapedCorpus.Fields, - Scope = KbShapedCorpus.Scope, - }; - - /// A point carrying an 8-wide "dense" vector and no payload. The caller fills it. - private static PointStruct DensePoint() => new() - { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors + private static async Task ClientExists(string collection) { - Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, - }, - }; - - /// - /// The options the adapter handed the store. No corpus can tell "queried the right name" from - /// "queried a name that happens to match", so these facts read the store's own field. - /// - private static QdrantKnowledgeStoreOptions OptionsOf(object port) => - (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) - .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(port)!; - - private static KnowledgeProviderConfiguration DenseEntry(string collection) => new() - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; - - /// A collection carrying one named "dense" vector, the shape every fixture here uses. - private static Task CreateDenseCollectionAsync( - QdrantClient client, - string collection, - ulong size = KbShapedCorpus.Dim) => - client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = size, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); - - private static QdrantKnowledgeAdapter Adapter() => new(_ => QdrantServer.CreateClient()); - - private static FakeEmbeddingGenerator Embedder() => new(KbShapedCorpus.QueryVector()); - - private static async Task ClientExists(string collection) - { - using var client = QdrantServer.CreateClient(); - return await client.CollectionExistsAsync(collection, TestContext.Current.CancellationToken); + using QdrantClient client = QdrantServer.CreateClient(); + return await client.CollectionExistsAsync(collection, TestContext.Current.CancellationToken); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs index dd5c6225..2094c457 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs @@ -8,592 +8,595 @@ using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// One interleaved corpus, built once for the whole class. -/// -/// -/// Every test here only reads, so one collection serves them all. Building one per test made -/// CreatePayloadIndexAsync exceed the client's 30 s deadline against a scratch container. -/// -public sealed class KbShapedCorpusFixture : IAsyncLifetime +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// Gets the collection name. Dropped when the class finishes. - public string Name { get; } = $"store-{Guid.NewGuid():N}"; + /// + /// One interleaved corpus, built once for the whole class. + /// + /// + /// Every test here only reads, so one collection serves them all. Building one per test made + /// CreatePayloadIndexAsync exceed the client's 30 s deadline against a scratch container. + /// + public sealed class KbShapedCorpusFixture : IAsyncLifetime + { + /// Gets the collection name. Dropped when the class finishes. + public string Name { get; } = $"store-{Guid.NewGuid():N}"; - /// Gets the client the tests query through. - public QdrantClient Client { get; private set; } = null!; + /// Gets the client the tests query through. + public QdrantClient Client { get; private set; } = null!; - public async ValueTask InitializeAsync() - { - if (!QdrantServer.IsConfigured) + public async ValueTask InitializeAsync() { - return; + if (!QdrantServer.IsConfigured) + { + return; + } + + Client = QdrantServer.CreateClient(); + await KbShapedCorpus.CreateAsync( + Client, Name, interleaved: true, TestContext.Current.CancellationToken); } - Client = QdrantServer.CreateClient(); - await KbShapedCorpus.CreateAsync( - Client, Name, interleaved: true, TestContext.Current.CancellationToken); + public async ValueTask DisposeAsync() + { + if (Client is null) + { + return; + } + + try + { + await Client.DeleteCollectionAsync(Name); + } + finally + { + Client.Dispose(); + } + } } - public async ValueTask DisposeAsync() + [Collection(QdrantServerCollection.Name)] + public sealed class QdrantKnowledgeStoreTests(KbShapedCorpusFixture corpus) : IClassFixture { - if (Client is null) + private readonly KbShapedCorpusFixture _corpus = corpus; + + [QdrantFact] + public async Task SearchAsync_ScopedSearch_ReturnsOnlyThatProduct() { - return; + // Card 0 is in scope and links to card 29, which is not. So this also holds up the scope + // re-check on see_also expansion: a key lookup carries no filter of its own. + KnowledgeScope scope = new() { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; + + IReadOnlyList cards = await LinkedStore().SearchAsync(KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); + + Assert.NotEmpty(cards); + List models = await ModelsOf(cards); + Assert.All(models, model => Assert.Equal("ct900", model)); } - try + [QdrantFact] + public async Task SearchAsync_Unscoped_WouldMixProducts() { - await Client.DeleteCollectionAsync(Name); + // The negative control for the test above. Without it, a dropped scope filter is invisible. + // `scoped: false` is the design's own switch for a whole-corpus read. An empty facet map is + // not that switch, and now fails closed like an absent ambient. + IReadOnlyList cards = await Store(scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + + Assert.True((await ModelsOf(cards)).Distinct(StringComparer.Ordinal).Count() > 1); } - finally + + [QdrantFact] + public async Task SearchAsync_ScopedStoreWithNoAmbient_Throws() { - Client.Dispose(); + // A21, first door. An absent scope fails closed. It never searches every customer's cards. + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await Store().SearchAsync(KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken)); + + Assert.Contains( + "This deployment declares scoped: true and the search arrived without a KnowledgeScope", + thrown.Message, + StringComparison.Ordinal); } - } -} -[Collection(QdrantServerCollection.Name)] -public sealed class QdrantKnowledgeStoreTests : IClassFixture -{ - private readonly KbShapedCorpusFixture _corpus; + [QdrantFact] + public async Task SearchAsync_ScopedStoreWithEmptyFacets_Throws() + { + // A21, second door. A host that reads a customer record with no product on it builds this + // scope without noticing, and an empty facet map filters nothing. Same leak as no ambient + // at all, so the same refusal -- but a different message, because it is a different bug. + KnowledgeScope scope = new() { Facets = new Dictionary(StringComparer.Ordinal) }; - public QdrantKnowledgeStoreTests(KbShapedCorpusFixture corpus) => _corpus = corpus; + InvalidOperationException thrown = await Assert.ThrowsAsync( + async () => await Store().SearchAsync(KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken)); - [QdrantFact] - public async Task SearchAsync_ScopedSearch_ReturnsOnlyThatProduct() - { - // Card 0 is in scope and links to card 29, which is not. So this also holds up the scope - // re-check on see_also expansion: a key lookup carries no filter of its own. - var scope = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; + Assert.Contains("names no facets", thrown.Message, StringComparison.Ordinal); + } - var cards = await LinkedStore().SearchAsync(KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); + [Fact] + public void Options_LeftAtTheirDefaults_CarryTheValuesTheDesignNames() + { + // Every other test names a limit and a floor, so a typo in either default ships silently. + QdrantKnowledgeStoreOptions options = new() { Collection = "anything", Scoped = false }; + + // The floor rides the dense prefetch as Qdrant's score_threshold, so Qdrant does the + // comparison in float32 and no C# `>=` against a double is involved. + Assert.Equal(0.35, options.ScoreFloor); + Assert.Equal(5, options.Limit); + // Left unset, VectorName means the collection's single anonymous vector. + Assert.Null(options.VectorName); + // No corpus's field names are here to fall back to, so an options record nobody configured + // maps nothing at all -- which is why the store refuses to be built from one. + Assert.Null(options.Fields); + Assert.Null(options.ScopeTemplate); + } - Assert.NotEmpty(cards); - var models = await ModelsOf(cards); - Assert.All(models, model => Assert.Equal("ct900", model)); - } + [QdrantFact] + public async Task SearchAsync_LookalikeIdentifier_RanksTheIdentifierCardFirst() + { + // A22. Card 7 holds e33 and sits one dense rank BELOW card 6. Only the required + // prefetch lifts it. + IReadOnlyList cards = await Store(scoped: false).SearchAsync( + KbShapedCorpus.LookalikeQuery, null, TestContext.Current.CancellationToken); + Assert.Equal(KbShapedCorpus.Id(7), cards[0].CardId); + } - [QdrantFact] - public async Task SearchAsync_Unscoped_WouldMixProducts() - { - // The negative control for the test above. Without it, a dropped scope filter is invisible. - // `scoped: false` is the design's own switch for a whole-corpus read. An empty facet map is - // not that switch, and now fails closed like an absent ambient. - var cards = await Store(scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task SearchAsync_TwoIdentifiersThatCoOccurNowhere_LeavesTheDenseAnswerStanding() + { + // A22's real proof. Under `must` the leg matches nothing and the dense order stands. + // Under `should` it would match both cards and reorder. `must` and `should` are the + // SAME filter for one token, so no single-identifier test can tell them apart. + IReadOnlyList cards = await Store(scoped: false).SearchAsync( + KbShapedCorpus.TwoIdentifierQuery, null, TestContext.Current.CancellationToken); - Assert.True((await ModelsOf(cards)).Distinct(StringComparer.Ordinal).Count() > 1); - } + Assert.Equal(KbShapedCorpus.Id(0), cards[0].CardId); + } - [QdrantFact] - public async Task SearchAsync_ScopedStoreWithNoAmbient_Throws() - { - // A21, first door. An absent scope fails closed. It never searches every customer's cards. - var thrown = await Assert.ThrowsAsync( - async () => await Store().SearchAsync(KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken)); - - Assert.Contains( - "This deployment declares scoped: true and the search arrived without a KnowledgeScope", - thrown.Message, - StringComparison.Ordinal); - } + [QdrantFact] + public async Task SearchAsync_LimitAboveTheDefaultPrefetchDepth_ReturnsThatMany() + { + // A27's recall ceiling. The limit is deliberately above both Qdrant's own default prefetch + // depth (10) and the depth a hardcoded constant would use (20), so either one caps the + // result below what the caller asked for. + IReadOnlyList cards = await Store(limit: 25, scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + + Assert.True( + cards.Count(card => !card.ViaLink) >= 25, + $"expected at least 25 ranked cards, got {cards.Count(card => !card.ViaLink)}"); + } - [QdrantFact] - public async Task SearchAsync_ScopedStoreWithEmptyFacets_Throws() - { - // A21, second door. A host that reads a customer record with no product on it builds this - // scope without noticing, and an empty facet map filters nothing. Same leak as no ambient - // at all, so the same refusal -- but a different message, because it is a different bug. - var scope = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) }; + [QdrantFact] + public async Task SearchAsync_ScoreFloor_KeepsExactlyTheCardsAtOrAboveIt() + { + // Scores are cosine similarities now and Qdrant applies the floor, so the floor is chosen + // from what the corpus scores: halfway between the second and third card, which leaves two + // cards above it and the rest below, with no card sitting on the boundary itself. + IReadOnlyList all = await Store(floor: 0.0, limit: 20, scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + Assert.True(all.Count >= 3); + double floor = (all[1].Score!.Value + all[2].Score!.Value) / 2; + + IReadOnlyList floored = await Store(floor: floor, limit: 20, scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + + Assert.Equal(2, floored.Count(card => !card.ViaLink)); + Assert.All(floored.Where(card => !card.ViaLink), card => Assert.True(card.Score > floor)); + } - var thrown = await Assert.ThrowsAsync( - async () => await Store().SearchAsync(KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken)); + [QdrantFact] + public async Task SearchAsync_TopHitHasSeeAlso_PullsTheLinkedCardIn() + { + // A7. Card 0's only link is card 29, which is the FARTHEST card, so it can never be + // on the page already. Nothing is scoped here, so `InScope` is vacuously true and the link + // mechanism itself is what the assertion sees. + IReadOnlyList cards = await LinkedStore(limit: 3, scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + + KnowledgeCard linked = Assert.Single(cards, card => card.ViaLink); + Assert.Equal(KbShapedCorpus.Id(KbShapedCorpus.Count - 1), linked.CardId); + Assert.Null(linked.Score); + } - Assert.Contains("names no facets", thrown.Message, StringComparison.Ordinal); - } + [QdrantFact] + public async Task SearchAsync_ScopedOnAListFacetThatHolds_KeepsTheLinkedCard() + { + // Holds' list branch, which had no test at all while the corpus carried only scalar facets -- + // and applies_to is a real array facet in the sibling knowledge-bank design, so a deployment + // scoped on it would have dropped every linked card with no error. Every card carries + // SharedAudience, so this scope holds for card 29 too and the link survives the re-check. + KnowledgeScope scope = new() + { + Facets = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = KbShapedCorpus.SharedAudience, + }, + }; - [Fact] - public void Options_LeftAtTheirDefaults_CarryTheValuesTheDesignNames() - { - // Every other test names a limit and a floor, so a typo in either default ships silently. - var options = new QdrantKnowledgeStoreOptions { Collection = "anything", Scoped = false }; - - // The floor rides the dense prefetch as Qdrant's score_threshold, so Qdrant does the - // comparison in float32 and no C# `>=` against a double is involved. - Assert.Equal(0.35, options.ScoreFloor); - Assert.Equal(5, options.Limit); - // Left unset, VectorName means the collection's single anonymous vector. - Assert.Null(options.VectorName); - // No corpus's field names are here to fall back to, so an options record nobody configured - // maps nothing at all -- which is why the store refuses to be built from one. - Assert.Null(options.Fields); - Assert.Null(options.ScopeTemplate); - } + IReadOnlyList cards = await LinkedStore(limit: 3, floor: 0.0).SearchAsync( + KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); - [QdrantFact] - public async Task SearchAsync_LookalikeIdentifier_RanksTheIdentifierCardFirst() - { - // A22. Card 7 holds e33 and sits one dense rank BELOW card 6. Only the required - // prefetch lifts it. - var cards = await Store(scoped: false).SearchAsync( - KbShapedCorpus.LookalikeQuery, null, TestContext.Current.CancellationToken); - Assert.Equal(KbShapedCorpus.Id(7), cards[0].CardId); - } + KnowledgeCard linked = Assert.Single(cards, card => card.ViaLink); + Assert.Equal(KbShapedCorpus.Id(KbShapedCorpus.Count - 1), linked.CardId); + } - [QdrantFact] - public async Task SearchAsync_TwoIdentifiersThatCoOccurNowhere_LeavesTheDenseAnswerStanding() - { - // A22's real proof. Under `must` the leg matches nothing and the dense order stands. - // Under `should` it would match both cards and reorder. `must` and `should` are the - // SAME filter for one token, so no single-identifier test can tell them apart. - var cards = await Store(scoped: false).SearchAsync( - KbShapedCorpus.TwoIdentifierQuery, null, TestContext.Current.CancellationToken); + [QdrantFact] + public async Task SearchAsync_ScopedOnAListFacetThatDoesNot_DropsTheLinkedCard() + { + // The other half of the same branch. Card 0 is ct900 and links to card 29, which is ct900ent, + // so card 29's applies_to list does NOT hold this scope. Without this fact a list branch that + // simply answered true would pass the test above. + KnowledgeScope scope = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["applies_to"] = "ct900" }, + }; - Assert.Equal(KbShapedCorpus.Id(0), cards[0].CardId); - } + IReadOnlyList cards = await LinkedStore(limit: 3, floor: 0.0).SearchAsync( + KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); - [QdrantFact] - public async Task SearchAsync_LimitAboveTheDefaultPrefetchDepth_ReturnsThatMany() - { - // A27's recall ceiling. The limit is deliberately above both Qdrant's own default prefetch - // depth (10) and the depth a hardcoded constant would use (20), so either one caps the - // result below what the caller asked for. - var cards = await Store(limit: 25, scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - - Assert.True( - cards.Count(card => !card.ViaLink) >= 25, - $"expected at least 25 ranked cards, got {cards.Count(card => !card.ViaLink)}"); - } + Assert.NotEmpty(cards); + Assert.DoesNotContain(cards, card => card.ViaLink); + } - [QdrantFact] - public async Task SearchAsync_ScoreFloor_KeepsExactlyTheCardsAtOrAboveIt() - { - // Scores are cosine similarities now and Qdrant applies the floor, so the floor is chosen - // from what the corpus scores: halfway between the second and third card, which leaves two - // cards above it and the rest below, with no card sitting on the boundary itself. - var all = await Store(floor: 0.0, limit: 20, scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - Assert.True(all.Count >= 3); - var floor = (all[1].Score!.Value + all[2].Score!.Value) / 2; - - var floored = await Store(floor: floor, limit: 20, scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - - Assert.Equal(2, floored.Count(card => !card.ViaLink)); - Assert.All(floored.Where(card => !card.ViaLink), card => Assert.True(card.Score > floor)); - } + [QdrantFact] + public async Task SearchAsync_MapsTheNestedPayload() + { + KnowledgeScope scope = new() { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; - [QdrantFact] - public async Task SearchAsync_TopHitHasSeeAlso_PullsTheLinkedCardIn() - { - // A7. Card 0's only link is card 29, which is the FARTHEST card, so it can never be - // on the page already. Nothing is scoped here, so `InScope` is vacuously true and the link - // mechanism itself is what the assertion sees. - var cards = await LinkedStore(limit: 3, scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - - var linked = Assert.Single(cards, card => card.ViaLink); - Assert.Equal(KbShapedCorpus.Id(KbShapedCorpus.Count - 1), linked.CardId); - Assert.Null(linked.Score); - } + KnowledgeCard card = (await Store().SearchAsync(KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken))[0]; - [QdrantFact] - public async Task SearchAsync_ScopedOnAListFacetThatHolds_KeepsTheLinkedCard() - { - // Holds' list branch, which had no test at all while the corpus carried only scalar facets -- - // and applies_to is a real array facet in the sibling knowledge-bank design, so a deployment - // scoped on it would have dropped every linked card with no error. Every card carries - // SharedAudience, so this scope holds for card 29 too and the link survives the re-check. - var scope = new KnowledgeScope + Assert.StartsWith("manifest-", card.SourceRef, StringComparison.Ordinal); + Assert.Equal("p.1", card.SourceLocator); + _ = Assert.NotNull(card.Authority); + Assert.InRange(card.Authority.Value, 1, 3); + Assert.NotEmpty(card.Text); + Assert.False(card.ViaLink); + } + + [Fact] + public async Task SearchAsync_ChannelHangsPastTheDeadline_Cancels() { - Facets = new Dictionary(StringComparer.Ordinal) - { - ["applies_to"] = KbShapedCorpus.SharedAudience, - }, - }; + // The one test a real server cannot serve. This is why the seam exists. + QdrantKnowledgeStore store = new( + new HangingSearchChannel(TimeSpan.FromSeconds(30)), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Collection = "anything", + VectorName = "dense", + Scoped = false, + Fields = KbShapedCorpus.Fields, + Deadline = TimeSpan.FromMilliseconds(20), + }); - var cards = await LinkedStore(limit: 3, floor: 0.0).SearchAsync( - KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); + _ = await Assert.ThrowsAnyAsync( + async () => await store.SearchAsync("anything", null, TestContext.Current.CancellationToken)); + } - var linked = Assert.Single(cards, card => card.ViaLink); - Assert.Equal(KbShapedCorpus.Id(KbShapedCorpus.Count - 1), linked.CardId); - } + [Fact] + public async Task SearchAsync_CallerCancels_Cancels() + { + // The other one: the caller's token must be linked in, not replaced by the deadline. + QdrantKnowledgeStore store = new( + new HangingSearchChannel(TimeSpan.FromSeconds(30)), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Collection = "anything", + VectorName = "dense", + Scoped = false, + Fields = KbShapedCorpus.Fields, - [QdrantFact] - public async Task SearchAsync_ScopedOnAListFacetThatDoesNot_DropsTheLinkedCard() - { - // The other half of the same branch. Card 0 is ct900 and links to card 29, which is ct900ent, - // so card 29's applies_to list does NOT hold this scope. Without this fact a list branch that - // simply answered true would pass the test above. - var scope = new KnowledgeScope + // Longer than the channel hangs for, so nothing but the caller's own token can end + // this conversation. At the default 10 s the store's deadline ends it instead and the test + // passes whether or not the caller's token was ever linked in. + Deadline = TimeSpan.FromMinutes(5), + }); + + using CancellationTokenSource caller = new(TimeSpan.FromMilliseconds(20)); + + _ = await Assert.ThrowsAnyAsync( + async () => await store.SearchAsync("anything", null, caller.Token)); + } + + private QdrantKnowledgeStore Store(int limit = 10, double floor = 0.0, bool scoped = true) { - Facets = new Dictionary(StringComparer.Ordinal) { ["applies_to"] = "ct900" }, - }; + return new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Limit = limit, + ScoreFloor = floor, + Scoped = scoped, + Analyzer = KbShapedCorpus.Analyzer, + }); + } - var cards = await LinkedStore(limit: 3, floor: 0.0).SearchAsync( - KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); + // KbShapedCorpus keys every point uuid5, and Store() carries no Links now that the feature is + // opt-in -- so a test that exercises see_also expansion needs this instead. + private QdrantKnowledgeStore LinkedStore(int limit = 10, double floor = 0.0, bool scoped = true) + { + return new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Limit = limit, + ScoreFloor = floor, + Scoped = scoped, + Links = KbShapedCorpus.Links, + Analyzer = KbShapedCorpus.Analyzer, + }); + } - Assert.NotEmpty(cards); - Assert.DoesNotContain(cards, card => card.ViaLink); - } + private async Task> ModelsOf(IReadOnlyList cards) + { + IReadOnlyList points = await _corpus.Client.RetrieveAsync( + _corpus.Name, + [.. cards.Select(card => new PointId { Uuid = KbShapedCorpus.PointKey(card.CardId).ToString() })], + withPayload: true, + cancellationToken: TestContext.Current.CancellationToken); - [QdrantFact] - public async Task SearchAsync_MapsTheNestedPayload() - { - var scope = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; + return [.. points.Select(point => point.Payload["facets"].StructValue.Fields["model"].StringValue)]; + } - var card = (await Store().SearchAsync(KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken))[0]; + [QdrantFact] + public async Task SearchAsync_RenamedFields_ReadsThemAndIgnoresTheDefaults() + { + // The synthetic corpus writes BOTH `text` and `body` with the same string, so pointing the + // body field at `text` proves the option is read without needing a second corpus. A store + // that ignored Fields.Body would still return non-empty text and pass by accident, so the + // assertion below is on a field the corpus gives a DIFFERENT value: the citation. + KnowledgeScope scope = new() { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; + + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Scoped = true, + Limit = 10, + ScoreFloor = 0.0, + Fields = KbShapedCorpus.Fields with { Source = "card_id", Locator = "text" }, + }); - Assert.StartsWith("manifest-", card.SourceRef, StringComparison.Ordinal); - Assert.Equal("p.1", card.SourceLocator); - Assert.NotNull(card.Authority); - Assert.InRange(card.Authority.Value, 1, 3); - Assert.NotEmpty(card.Text); - Assert.False(card.ViaLink); - } + KnowledgeCard card = (await store.SearchAsync( + KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken))[0]; - [Fact] - public async Task SearchAsync_ChannelHangsPastTheDeadline_Cancels() - { - // The one test a real server cannot serve. This is why the seam exists. - var store = new QdrantKnowledgeStore( - new HangingSearchChannel(TimeSpan.FromSeconds(30)), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Collection = "anything", - VectorName = "dense", - Scoped = false, - Fields = KbShapedCorpus.Fields, - Deadline = TimeSpan.FromMilliseconds(20), - }); - - await Assert.ThrowsAnyAsync( - async () => await store.SearchAsync("anything", null, TestContext.Current.CancellationToken)); - } + Assert.Equal(card.CardId, card.SourceRef); + Assert.NotEmpty(card.SourceLocator); + Assert.DoesNotContain("manifest-", card.SourceRef, StringComparison.Ordinal); + } - [Fact] - public async Task SearchAsync_CallerCancels_Cancels() - { - // The other one: the caller's token must be linked in, not replaced by the deadline. - var store = new QdrantKnowledgeStore( - new HangingSearchChannel(TimeSpan.FromSeconds(30)), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Collection = "anything", - VectorName = "dense", - Scoped = false, - Fields = KbShapedCorpus.Fields, + [QdrantFact] + public async Task SearchAsync_IdRoleDisabled_UsesThePointKeyAsTheCardId() + { + // Audit falls back to the point key; KbShapedCorpus keys every point uuid5, so the id + // must parse as a GUID when fields.id is null. + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Scoped = false, + Limit = 3, + ScoreFloor = 0.0, + Fields = KbShapedCorpus.Fields with { Id = null }, + }); - // Longer than the channel hangs for, so nothing but the caller's own token can end - // this conversation. At the default 10 s the store's deadline ends it instead and the test - // passes whether or not the caller's token was ever linked in. - Deadline = TimeSpan.FromMinutes(5), - }); + KnowledgeCard card = (await store.SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken))[0]; - using var caller = new CancellationTokenSource(TimeSpan.FromMilliseconds(20)); + Assert.True(Guid.TryParse(card.CardId, out _), $"'{card.CardId}' is not a point key"); + Assert.NotEmpty(card.Text); + } - await Assert.ThrowsAnyAsync( - async () => await store.SearchAsync("anything", null, caller.Token)); - } + [QdrantFact] + public async Task SearchAsync_LexicalRoleDisabled_StillAnswersAnIdentifierQuery() + { + // The supported spelling of "no full-text index": no required-term leg is built, so the + // lookalike lift disappears but the dense leg still answers. + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Scoped = false, + Limit = 10, + ScoreFloor = 0.0, + Fields = KbShapedCorpus.Fields with { Lexical = null }, + }); - private QdrantKnowledgeStore Store(int limit = 10, double floor = 0.0, bool scoped = true) - => new( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Limit = limit, - ScoreFloor = floor, - Scoped = scoped, - Analyzer = KbShapedCorpus.Analyzer, - }); - - // KbShapedCorpus keys every point uuid5, and Store() carries no Links now that the feature is - // opt-in -- so a test that exercises see_also expansion needs this instead. - private QdrantKnowledgeStore LinkedStore(int limit = 10, double floor = 0.0, bool scoped = true) - => new( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Limit = limit, - ScoreFloor = floor, - Scoped = scoped, - Links = KbShapedCorpus.Links, - Analyzer = KbShapedCorpus.Analyzer, - }); - - private async Task> ModelsOf(IReadOnlyList cards) - { - var points = await _corpus.Client.RetrieveAsync( - _corpus.Name, - [.. cards.Select(card => new PointId { Uuid = KbShapedCorpus.PointKey(card.CardId).ToString() })], - withPayload: true, - cancellationToken: TestContext.Current.CancellationToken); + IReadOnlyList cards = await store.SearchAsync( + KbShapedCorpus.TwoIdentifierQuery, null, TestContext.Current.CancellationToken); - return [.. points.Select(point => point.Payload["facets"].StructValue.Fields["model"].StringValue)]; - } + Assert.NotEmpty(cards); + } - [QdrantFact] - public async Task SearchAsync_RenamedFields_ReadsThemAndIgnoresTheDefaults() - { - // The synthetic corpus writes BOTH `text` and `body` with the same string, so pointing the - // body field at `text` proves the option is read without needing a second corpus. A store - // that ignored Fields.Body would still return non-empty text and pass by accident, so the - // assertion below is on a field the corpus gives a DIFFERENT value: the citation. - var scope = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; - - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = true, - Limit = 10, - ScoreFloor = 0.0, - Fields = KbShapedCorpus.Fields with { Source = "card_id", Locator = "text" }, - }); - - var card = (await store.SearchAsync( - KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken))[0]; - - Assert.Equal(card.CardId, card.SourceRef); - Assert.NotEmpty(card.SourceLocator); - Assert.DoesNotContain("manifest-", card.SourceRef, StringComparison.Ordinal); - } + [QdrantFact] + public async Task SearchAsync_NoQueryAnalyzer_StillAnswersTheLookalikeQuery() + { + // With no required-term leg the identifier card is no longer lifted, so this asserts only + // that the single-leg path works at all -- not that ranking is unchanged. + KnowledgeScope scope = new() { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; - [QdrantFact] - public async Task SearchAsync_IdRoleDisabled_UsesThePointKeyAsTheCardId() - { - // Audit falls back to the point key; KbShapedCorpus keys every point uuid5, so the id - // must parse as a GUID when fields.id is null. - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = false, - Limit = 3, - ScoreFloor = 0.0, - Fields = KbShapedCorpus.Fields with { Id = null }, - }); - - var card = (await store.SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken))[0]; - - Assert.True(Guid.TryParse(card.CardId, out _), $"'{card.CardId}' is not a point key"); - Assert.NotEmpty(card.Text); - } + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Scoped = true, + Limit = 10, + ScoreFloor = 0.0, + Analyzer = new NoQueryAnalyzer(), + }); - [QdrantFact] - public async Task SearchAsync_LexicalRoleDisabled_StillAnswersAnIdentifierQuery() - { - // The supported spelling of "no full-text index": no required-term leg is built, so the - // lookalike lift disappears but the dense leg still answers. - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = false, - Limit = 10, - ScoreFloor = 0.0, - Fields = KbShapedCorpus.Fields with { Lexical = null }, - }); - - var cards = await store.SearchAsync( - KbShapedCorpus.TwoIdentifierQuery, null, TestContext.Current.CancellationToken); - - Assert.NotEmpty(cards); - } + IReadOnlyList cards = await store.SearchAsync( + KbShapedCorpus.LookalikeQuery, scope, TestContext.Current.CancellationToken); - [QdrantFact] - public async Task SearchAsync_NoQueryAnalyzer_StillAnswersTheLookalikeQuery() - { - // With no required-term leg the identifier card is no longer lifted, so this asserts only - // that the single-leg path works at all -- not that ranking is unchanged. - var scope = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; - - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = true, - Limit = 10, - ScoreFloor = 0.0, - Analyzer = new NoQueryAnalyzer(), - }); - - var cards = await store.SearchAsync( - KbShapedCorpus.LookalikeQuery, scope, TestContext.Current.CancellationToken); - - Assert.NotEmpty(cards); - } + Assert.NotEmpty(cards); + } - [QdrantTheory] - [InlineData(KnowledgeLinkLookup.Uuid5)] - [InlineData(KnowledgeLinkLookup.Filter)] - public async Task SearchAsync_EveryLookupMode_FollowsTheSameLink(KnowledgeLinkLookup lookup) - { - // Card 0 is nearest the query vector and links to card 29, the farthest -- so a linked card - // on the page cannot have arrived by ranking. Both modes must find the same one. - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = false, - Limit = 3, - ScoreFloor = 0.0, - Links = KbShapedCorpus.Links with { Lookup = lookup }, - }); - - var cards = await store.SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - - var linked = Assert.Single(cards, card => card.ViaLink); - Assert.Equal(KbShapedCorpus.Id(KbShapedCorpus.Count - 1), linked.CardId); - Assert.Null(linked.Score); - } + [QdrantTheory] + [InlineData(KnowledgeLinkLookup.Uuid5)] + [InlineData(KnowledgeLinkLookup.Filter)] + public async Task SearchAsync_EveryLookupMode_FollowsTheSameLink(KnowledgeLinkLookup lookup) + { + // Card 0 is nearest the query vector and links to card 29, the farthest -- so a linked card + // on the page cannot have arrived by ranking. Both modes must find the same one. + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Scoped = false, + Limit = 3, + ScoreFloor = 0.0, + Links = KbShapedCorpus.Links with { Lookup = lookup }, + }); - [QdrantFact] - public async Task SearchAsync_FilterLookupWithScopeOpen_StillDropsOutOfScopeLinks() - { - // The scope re-check must run on the scroll path too. Card 0 is ct900 and links to card 29, - // which the interleaved corpus makes ct900ent -- so the link must NOT come back. - var scope = new KnowledgeScope { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; - - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = true, - Limit = 3, - ScoreFloor = 0.0, - Links = KbShapedCorpus.Links with { Lookup = KnowledgeLinkLookup.Filter }, - }); - - var cards = await store.SearchAsync( - KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); - - Assert.All(cards, card => Assert.False(card.ViaLink)); - } + IReadOnlyList cards = await store.SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - [QdrantFact] - public async Task SearchAsync_NoLinksBlock_NeverExpands() - { - // Card 0's payload still says see_also: [syn-29]; with no links: block that is data, not behaviour. - var cards = await Store(limit: 3, scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + KnowledgeCard linked = Assert.Single(cards, card => card.ViaLink); + Assert.Equal(KbShapedCorpus.Id(KbShapedCorpus.Count - 1), linked.CardId); + Assert.Null(linked.Score); + } - Assert.NotEmpty(cards); - Assert.All(cards, card => Assert.False(card.ViaLink)); - } + [QdrantFact] + public async Task SearchAsync_FilterLookupWithScopeOpen_StillDropsOutOfScopeLinks() + { + // The scope re-check must run on the scroll path too. Card 0 is ct900 and links to card 29, + // which the interleaved corpus makes ct900ent -- so the link must NOT come back. + KnowledgeScope scope = new() { Facets = new Dictionary(StringComparer.Ordinal) { ["model"] = "ct900" } }; - [QdrantFact] - public async Task SearchAsync_NoLinksFieldInPayload_ReturnsRankedCardsOnly() - { - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Fields = KbShapedCorpus.Fields, - ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = _corpus.Name, - VectorName = "dense", - Scoped = false, - Limit = 3, - ScoreFloor = 0.0, - Links = KbShapedCorpus.Links with { Field = "no_such_field" }, - }); - - var cards = await store.SearchAsync( - KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - - Assert.NotEmpty(cards); - Assert.All(cards, card => Assert.False(card.ViaLink)); - } + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = _corpus.Name, + VectorName = "dense", + Scoped = true, + Limit = 3, + ScoreFloor = 0.0, + Links = KbShapedCorpus.Links with { Lookup = KnowledgeLinkLookup.Filter }, + }); - [QdrantFact] - public async Task SearchAsync_AnonymousVectorCollection_RanksWithoutAUsingClause() - { - var collection = $"anonstore-{Guid.NewGuid():N}"; - using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine }, - cancellationToken: TestContext.Current.CancellationToken); - - try + IReadOnlyList cards = await store.SearchAsync( + KbShapedCorpus.PlainQuery, scope, TestContext.Current.CancellationToken); + + Assert.All(cards, card => Assert.False(card.ViaLink)); + } + + [QdrantFact] + public async Task SearchAsync_NoLinksBlock_NeverExpands() { - var point = new PointStruct - { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = KbShapedCorpus.QueryVector(), - }; - point.Payload["card_id"] = "anon-00"; - point.Payload["body"] = "anonymous vector card"; - await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + // Card 0's payload still says see_also: [syn-29]; with no links: block that is data, not behaviour. + IReadOnlyList cards = await Store(limit: 3, scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); - var store = new QdrantKnowledgeStore( - new QdrantSearchChannel(QdrantServer.CreateClient()), + Assert.NotEmpty(cards); + Assert.All(cards, card => Assert.False(card.ViaLink)); + } + + [QdrantFact] + public async Task SearchAsync_NoLinksFieldInPayload_ReturnsRankedCardsOnly() + { + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(_corpus.Client), new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), new QdrantKnowledgeStoreOptions { Fields = KbShapedCorpus.Fields, ScopeTemplate = KbShapedCorpus.ScopeTemplate, - Collection = collection, + Collection = _corpus.Name, + VectorName = "dense", Scoped = false, Limit = 3, ScoreFloor = 0.0, - Analyzer = new NoQueryAnalyzer(), + Links = KbShapedCorpus.Links with { Field = "no_such_field" }, }); - using var _ = (IDisposable)store; - var card = Assert.Single(await store.SearchAsync("anonymous", null, TestContext.Current.CancellationToken)); - Assert.Equal("anonymous vector card", card.Text); + IReadOnlyList cards = await store.SearchAsync( + KbShapedCorpus.PlainQuery, null, TestContext.Current.CancellationToken); + + Assert.NotEmpty(cards); + Assert.All(cards, card => Assert.False(card.ViaLink)); } - finally + + [QdrantFact] + public async Task SearchAsync_AnonymousVectorCollection_RanksWithoutAUsingClause() { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + string collection = $"anonstore-{Guid.NewGuid():N}"; + using QdrantClient client = QdrantServer.CreateClient(); + await client.CreateCollectionAsync( + collection, + new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine }, + cancellationToken: TestContext.Current.CancellationToken); + + try + { + PointStruct point = new() + { + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = KbShapedCorpus.QueryVector(), + }; + point.Payload["card_id"] = "anon-00"; + point.Payload["body"] = "anonymous vector card"; + _ = await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); + + QdrantKnowledgeStore store = new( + new QdrantSearchChannel(QdrantServer.CreateClient()), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + Collection = collection, + Scoped = false, + Limit = 3, + ScoreFloor = 0.0, + Analyzer = new NoQueryAnalyzer(), + }); + + using IDisposable storeLifetime = store; + KnowledgeCard card = Assert.Single(await store.SearchAsync("anonymous", null, TestContext.Current.CancellationToken)); + Assert.Equal("anonymous vector card", card.Text); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantPointConverterTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantPointConverterTests.cs index b895d630..0bf26d76 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantPointConverterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantPointConverterTests.cs @@ -1,52 +1,54 @@ +using AgentCore.Application.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Google.Protobuf.Collections; using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -public sealed class QdrantPointConverterTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [Fact] - public void ToPoint_ConvertsEveryValueKindWithoutALeakedProtobufType() + public sealed class QdrantPointConverterTests { - var payload = new MapField + [Fact] + public void ToPoint_ConvertsEveryValueKindWithoutALeakedProtobufType() { - ["s"] = "text", - ["i"] = 3, - ["d"] = new Value { DoubleValue = 0.5 }, - ["b"] = true, - ["nested"] = new Value - { - StructValue = new Struct { Fields = { ["inner"] = new Value { StringValue = "deep" } } }, - }, - ["list"] = new Value + MapField payload = new() { - ListValue = new ListValue { Values = { new Value { StringValue = "a" }, new Value { IntegerValue = 2 } } }, - }, - }; + ["s"] = "text", + ["i"] = 3, + ["d"] = new Value { DoubleValue = 0.5 }, + ["b"] = true, + ["nested"] = new Value + { + StructValue = new Struct { Fields = { ["inner"] = new Value { StringValue = "deep" } } }, + }, + ["list"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = "a" }, new Value { IntegerValue = 2 } } }, + }, + }; - var point = QdrantPointConverter.ToPoint( - new PointId { Uuid = "11111111-2222-3333-4444-555555555555" }, payload, score: 0.75); + KnowledgePoint point = QdrantPointConverter.ToPoint( + new PointId { Uuid = "11111111-2222-3333-4444-555555555555" }, payload, score: 0.75); - Assert.Equal("11111111-2222-3333-4444-555555555555", point.PointId); - Assert.Equal(0.75, point.Score); - Assert.Equal("text", point.Payload["s"]); - Assert.Equal(3L, point.Payload["i"]); - Assert.Equal(0.5, point.Payload["d"]); - Assert.True((bool)point.Payload["b"]!); - var nested = Assert.IsType>(point.Payload["nested"], exactMatch: false); - Assert.Equal("deep", nested["inner"]); - var list = Assert.IsType>(point.Payload["list"], exactMatch: false); - Assert.Equal(["a", 2L], list); - } + Assert.Equal("11111111-2222-3333-4444-555555555555", point.PointId); + Assert.Equal(0.75, point.Score); + Assert.Equal("text", point.Payload["s"]); + Assert.Equal(3L, point.Payload["i"]); + Assert.Equal(0.5, point.Payload["d"]); + Assert.True((bool)point.Payload["b"]!); + IReadOnlyDictionary nested = Assert.IsType>(point.Payload["nested"], exactMatch: false); + Assert.Equal("deep", nested["inner"]); + IReadOnlyList list = Assert.IsType>(point.Payload["list"], exactMatch: false); + Assert.Equal(["a", 2L], list); + } - [Fact] - public void ToPoint_NumericPointKey_BecomesInvariantText() - { - var point = QdrantPointConverter.ToPoint(new PointId { Num = 42 }, [], score: null); + [Fact] + public void ToPoint_NumericPointKey_BecomesInvariantText() + { + KnowledgePoint point = QdrantPointConverter.ToPoint(new PointId { Num = 42 }, [], score: null); - Assert.Equal("42", point.PointId); - Assert.Null(point.Score); + Assert.Equal("42", point.PointId); + Assert.Null(point.Score); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs index 5441cd09..213bc1c4 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs @@ -1,84 +1,86 @@ using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; +using Qdrant.Client; using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -[Collection(QdrantServerCollection.Name)] -public sealed class QdrantSearchChannelTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [QdrantFact] - public async Task QueryAsync_ReturnsPointsInFusedOrder() + [Collection(QdrantServerCollection.Name)] + public sealed class QdrantSearchChannelTests { - using var client = QdrantServer.CreateClient(); - var collection = $"channel-{Guid.NewGuid():N}"; - - try + [QdrantFact] + public async Task QueryAsync_ReturnsPointsInFusedOrder() { - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - var channel = new QdrantSearchChannel(client); + using QdrantClient client = QdrantServer.CreateClient(); + string collection = $"channel-{Guid.NewGuid():N}"; - var prefetch = new PrefetchQuery + try { - Limit = 20, - Using = "dense", - Query = new Query + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + QdrantSearchChannel channel = new(client); + + PrefetchQuery prefetch = new() { - Nearest = new VectorInput + Limit = 20, + Using = "dense", + Query = new Query { - Dense = new DenseVector { Data = { KbShapedCorpus.QueryVector() } }, + Nearest = new VectorInput + { + Dense = new DenseVector { Data = { KbShapedCorpus.QueryVector() } }, + }, }, - }, - }; + }; - var points = await channel.QueryAsync( - new SearchQuery(collection, [prefetch], new Query { Fusion = Fusion.Rrf }, 5), - TestContext.Current.CancellationToken); + IReadOnlyList points = await channel.QueryAsync( + new SearchQuery(collection, [prefetch], new Query { Fusion = Fusion.Rrf }, 5), + TestContext.Current.CancellationToken); - Assert.Equal(5, points.Count); - Assert.Equal(KbShapedCorpus.Id(0), points[0].Payload["card_id"].StringValue); - } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + Assert.Equal(5, points.Count); + Assert.Equal(KbShapedCorpus.Id(0), points[0].Payload["card_id"].StringValue); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - - [QdrantFact] - public async Task RetrieveAsync_FetchesTheWholePayloadByKey() - { - using var client = QdrantServer.CreateClient(); - var collection = $"channel-{Guid.NewGuid():N}"; - try + [QdrantFact] + public async Task RetrieveAsync_FetchesTheWholePayloadByKey() { - await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); - var channel = new QdrantSearchChannel(client); + using QdrantClient client = QdrantServer.CreateClient(); + string collection = $"channel-{Guid.NewGuid():N}"; - var points = await channel.RetrieveAsync( - collection, - [KbShapedCorpus.PointKey(KbShapedCorpus.Id(3)), KbShapedCorpus.PointKey(KbShapedCorpus.Id(9))], - TestContext.Current.CancellationToken); + try + { + await KbShapedCorpus.CreateAsync(client, collection, interleaved: true, TestContext.Current.CancellationToken); + QdrantSearchChannel channel = new(client); - Assert.Equal(2, points.Count); - Assert.Contains(points, p => p.Payload["card_id"].StringValue == KbShapedCorpus.Id(3)); - Assert.True(points[0].Payload.ContainsKey("see_also")); - } - finally - { - await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + IReadOnlyList points = await channel.RetrieveAsync( + collection, + [KbShapedCorpus.PointKey(KbShapedCorpus.Id(3)), KbShapedCorpus.PointKey(KbShapedCorpus.Id(9))], + TestContext.Current.CancellationToken); + + Assert.Equal(2, points.Count); + Assert.Contains(points, p => p.Payload["card_id"].StringValue == KbShapedCorpus.Id(3)); + Assert.True(points[0].Payload.ContainsKey("see_also")); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } } - } - [QdrantFact] - public async Task QueryAsync_CancelledToken_Throws() - { - using var client = QdrantServer.CreateClient(); - var channel = new QdrantSearchChannel(client); - using var cancelled = new CancellationTokenSource(); - await cancelled.CancelAsync(); + [QdrantFact] + public async Task QueryAsync_CancelledToken_Throws() + { + using QdrantClient client = QdrantServer.CreateClient(); + QdrantSearchChannel channel = new(client); + using CancellationTokenSource cancelled = new(); + await cancelled.CancelAsync(); - await Assert.ThrowsAnyAsync(async () => await channel.QueryAsync( - new SearchQuery("anything", [], new Query { Fusion = Fusion.Rrf }, 1), cancelled.Token)); + _ = await Assert.ThrowsAnyAsync(async () => await channel.QueryAsync( + new SearchQuery("anything", [], new Query { Fusion = Fusion.Rrf }, 1), cancelled.Token)); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServer.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServer.cs index d3e44a90..2ba72684 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServer.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServer.cs @@ -1,38 +1,39 @@ using Qdrant.Client; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// The Qdrant the query tests run against, if the environment names one. -/// -/// AGENTCORE_TEST_QDRANT names host and gRPC port, for example localhost:6334. The -/// tests create and drop their own collections, so the server must be a scratch one. -/// The skip is silent: a green local run on a machine with no Qdrant means these tests did -/// not run at all. CI always sets the variable. -/// -public static class QdrantServer +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - private const string Variable = "AGENTCORE_TEST_QDRANT"; + /// The Qdrant the query tests run against, if the environment names one. + /// + /// AGENTCORE_TEST_QDRANT names host and gRPC port, for example localhost:6334. The + /// tests create and drop their own collections, so the server must be a scratch one. + /// The skip is silent: a green local run on a machine with no Qdrant means these tests did + /// not run at all. CI always sets the variable. + /// + public static class QdrantServer + { + private const string Variable = "AGENTCORE_TEST_QDRANT"; - /// Why a test skipped, when it did. - public const string SkipReason = "Set AGENTCORE_TEST_QDRANT (host:port) to run."; + /// Why a test skipped, when it did. + public const string SkipReason = "Set AGENTCORE_TEST_QDRANT (host:port) to run."; - /// The endpoint, or null when the environment names none. - public static string? Endpoint => - Environment.GetEnvironmentVariable(Variable) is { Length: > 0 } value ? value : null; + /// The endpoint, or null when the environment names none. + public static string? Endpoint => + Environment.GetEnvironmentVariable(Variable) is { Length: > 0 } value ? value : null; - /// Whether a server was named. - public static bool IsConfigured => Endpoint is not null; + /// Whether a server was named. + public static bool IsConfigured => Endpoint is not null; - /// Opens a client on the named server. - /// The client. The caller disposes it. - /// No server was named. - public static QdrantClient CreateClient() - { - var endpoint = Endpoint ?? throw new InvalidOperationException(SkipReason); - var parts = endpoint.Split(':', 2); + /// Opens a client on the named server. + /// The client. The caller disposes it. + /// No server was named. + public static QdrantClient CreateClient() + { + string endpoint = Endpoint ?? throw new InvalidOperationException(SkipReason); + string[] parts = endpoint.Split(':', 2); - // The timeout is per conversation and the connector never sets one. A schema conversation on a slow disk - // can take 20 s; a query takes single-digit milliseconds. - return new QdrantClient(parts[0], int.Parse(parts[1]), grpcTimeout: TimeSpan.FromSeconds(30)); + // The timeout is per conversation and the connector never sets one. A schema conversation on a slow disk + // can take 20 s; a query takes single-digit milliseconds. + return new QdrantClient(parts[0], int.Parse(parts[1]), grpcTimeout: TimeSpan.FromSeconds(30)); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServerCollection.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServerCollection.cs index edf7988d..4d4a597a 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServerCollection.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantServerCollection.cs @@ -1,20 +1,21 @@ using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// The collection of every class that creates a collection against the shared scratch Qdrant. -/// -/// -/// A test run gives each class a collection of its own and runs collections in parallel by default. -/// Three classes creating collections in the same millisecond against an HDD-backed container has -/// already produced a real flake: CreatePayloadIndexAsync exceeded the client's 30 s deadline -/// and took down an unrelated class with it. Naming this collection puts every Qdrant-backed test -/// class in one queue, so no two ever race the same server at once. It fixes no order among them. -/// -[CollectionDefinition(Name)] -public sealed class QdrantServerCollection +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// The name every class that talks to the shared scratch Qdrant carries. - public const string Name = "QdrantServer"; + /// + /// The collection of every class that creates a collection against the shared scratch Qdrant. + /// + /// + /// A test run gives each class a collection of its own and runs collections in parallel by default. + /// Three classes creating collections in the same millisecond against an HDD-backed container has + /// already produced a real flake: CreatePayloadIndexAsync exceeded the client's 30 s deadline + /// and took down an unrelated class with it. Naming this collection puts every Qdrant-backed test + /// class in one queue, so no two ever race the same server at once. It fixes no order among them. + /// + [CollectionDefinition(Name)] + public sealed class QdrantServerCollection + { + /// The name every class that talks to the shared scratch Qdrant carries. + public const string Name = "QdrantServer"; + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantTheoryAttribute.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantTheoryAttribute.cs index d9611a9d..a81906b9 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantTheoryAttribute.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantTheoryAttribute.cs @@ -1,22 +1,23 @@ using System.Runtime.CompilerServices; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// A theory that needs a live Qdrant, and skips itself when none is named. -/// See for the variable it reads. -public sealed class QdrantTheoryAttribute : TheoryAttribute +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// Creates the attribute. - /// Supplied by the compiler. - /// Supplied by the compiler. - public QdrantTheoryAttribute( - [CallerFilePath] string? sourceFilePath = null, - [CallerLineNumber] int sourceLineNumber = -1) - : base(sourceFilePath, sourceLineNumber) + /// A theory that needs a live Qdrant, and skips itself when none is named. + /// See for the variable it reads. + public sealed class QdrantTheoryAttribute : TheoryAttribute { - Skip = QdrantServer.SkipReason; - SkipUnless = nameof(QdrantServer.IsConfigured); - SkipType = typeof(QdrantServer); + /// Creates the attribute. + /// Supplied by the compiler. + /// Supplied by the compiler. + public QdrantTheoryAttribute( + [CallerFilePath] string? sourceFilePath = null, + [CallerLineNumber] int sourceLineNumber = -1) + : base(sourceFilePath, sourceLineNumber) + { + Skip = QdrantServer.SkipReason; + SkipUnless = nameof(QdrantServer.IsConfigured); + SkipType = typeof(QdrantServer); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs index c609f32f..56ec8ef7 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs @@ -1,138 +1,144 @@ using AgentCore.Application.Configuration.Schema; +using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; using AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; +using Google.Protobuf.Collections; using Qdrant.Client.Grpc; using Xunit; using static AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.TestScopes; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// The store's Qdrant filter under scope.wildcard: a named facet widens to -/// [value, wildcard], every other facet stays an exact match, and a card reached only -/// through a link is filtered by the same rule the query used. -/// -/// -/// is the tenant-isolation case: a -/// wildcard configured for one facet must never leak into an unnamed one sitting beside it in the -/// same scope. -/// -public sealed class QdrantWildcardScopeTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - [Fact] - public async Task Search_NoWildcardConfigured_EmitsTheKeywordCase() + /// + /// The store's Qdrant filter under scope.wildcard: a named facet widens to + /// [value, wildcard], every other facet stays an exact match, and a card reached only + /// through a link is filtered by the same rule the query used. + /// + /// + /// is the tenant-isolation case: a + /// wildcard configured for one facet must never leak into an unnamed one sitting beside it in the + /// same scope. + /// + public sealed class QdrantWildcardScopeTests { - var channel = new CapturingSearchChannel([]); - var store = StoreOver(channel, wildcard: null, wildcardFacets: []); - - await store.SearchAsync("belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); - - var condition = channel.Query!.Prefetch[0].Filter.Must[0].Field; - Assert.Equal(Match.MatchValueOneofCase.Keyword, condition.Match.MatchValueCase); - Assert.Equal("sole", condition.Match.Keyword); - } - - [Fact] - public async Task Search_NamedFacet_EmitsBothTheValueAndTheWildcard() - { - var channel = new CapturingSearchChannel([]); - var store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); - await store.SearchAsync("belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); - - var match = channel.Query!.Prefetch[0].Filter.Must[0].Field.Match; - Assert.Equal(Match.MatchValueOneofCase.Keywords, match.MatchValueCase); - Assert.Equal(["*", "sole"], match.Keywords.Strings); - } - - [Fact] - public async Task Search_FacetNotNamed_StaysExactEvenBesideANamedOne() - { - var channel = new CapturingSearchChannel([]); - var store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); - await store.SearchAsync( - "belt", Scope(("brand", "sole"), ("customer_id", "c-91")), TestContext.Current.CancellationToken); - - var conditions = channel.Query!.Prefetch[0].Filter.Must; - var tenant = conditions.Single(c => c.Field.Key.EndsWith("customer_id", StringComparison.Ordinal)); - Assert.Equal(Match.MatchValueOneofCase.Keyword, tenant.Field.Match.MatchValueCase); - } + [Fact] + public async Task Search_NoWildcardConfigured_EmitsTheKeywordCase() + { + CapturingSearchChannel channel = new([]); + QdrantKnowledgeStore store = StoreOver(channel, wildcard: null, wildcardFacets: []); - [Fact] - public async Task Search_ValueEqualsTheWildcard_EmitsOneKeyword() - { - var channel = new CapturingSearchChannel([]); - var store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); + _ = await store.SearchAsync("belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); - await store.SearchAsync("belt", Scope(("brand", "*")), TestContext.Current.CancellationToken); + FieldCondition condition = channel.Query!.Prefetch[0].Filter.Must[0].Field; + Assert.Equal(Match.MatchValueOneofCase.Keyword, condition.Match.MatchValueCase); + Assert.Equal("sole", condition.Match.Keyword); + } - var match = channel.Query!.Prefetch[0].Filter.Must[0].Field.Match; - Assert.Equal(Match.MatchValueOneofCase.Keyword, match.MatchValueCase); - Assert.Equal("*", match.Keyword); - } + [Fact] + public async Task Search_NamedFacet_EmitsBothTheValueAndTheWildcard() + { + CapturingSearchChannel channel = new([]); + QdrantKnowledgeStore store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); + _ = await store.SearchAsync("belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); - [Fact] - public async Task Search_LinkedCardTaggedWildcard_IsKept() - { - // Linked cards are fetched by id and never pass the Qdrant filter, so InScope is the only - // gate on them. It has to accept the same set the query did. - var store = StoreOver( - ChannelWithLink(linkedFacet: "*"), wildcard: "*", wildcardFacets: ["brand"], withLinks: true); - var cards = await store.SearchAsync( - "belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); - Assert.Contains(cards, card => card.ViaLink); - } + Match match = channel.Query!.Prefetch[0].Filter.Must[0].Field.Match; + Assert.Equal(Match.MatchValueOneofCase.Keywords, match.MatchValueCase); + Assert.Equal(["*", "sole"], match.Keywords.Strings); + } - [Fact] - public async Task Search_LinkedCardOutsideTheScope_IsDropped() - { - var store = StoreOver( - ChannelWithLink(linkedFacet: "spirit"), wildcard: "*", wildcardFacets: ["brand"], withLinks: true); + [Fact] + public async Task Search_FacetNotNamed_StaysExactEvenBesideANamedOne() + { + CapturingSearchChannel channel = new([]); + QdrantKnowledgeStore store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); + _ = await store.SearchAsync( + "belt", Scope(("brand", "sole"), ("customer_id", "c-91")), TestContext.Current.CancellationToken); + + RepeatedField conditions = channel.Query!.Prefetch[0].Filter.Must; + Condition tenant = conditions.Single(c => c.Field.Key.EndsWith("customer_id", StringComparison.Ordinal)); + Assert.Equal(Match.MatchValueOneofCase.Keyword, tenant.Field.Match.MatchValueCase); + } + + [Fact] + public async Task Search_ValueEqualsTheWildcard_EmitsOneKeyword() + { + CapturingSearchChannel channel = new([]); + QdrantKnowledgeStore store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); - var cards = await store.SearchAsync( - "belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); - Assert.DoesNotContain(cards, card => card.ViaLink); - } + _ = await store.SearchAsync("belt", Scope(("brand", "*")), TestContext.Current.CancellationToken); - /// A ranked point linking to one fetched point tagged on brand. - private static CapturingSearchChannel ChannelWithLink(string linkedFacet) - { - var linkedId = Guid.NewGuid(); + Match match = channel.Query!.Prefetch[0].Filter.Must[0].Field.Match; + Assert.Equal(Match.MatchValueOneofCase.Keyword, match.MatchValueCase); + Assert.Equal("*", match.Keyword); + } - var ranked = new ScoredPoint { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Score = 1f }; - ranked.Payload["card_id"] = "card-1"; - ranked.Payload["body"] = "text"; - ranked.Payload["see_also"] = new Value + [Fact] + public async Task Search_LinkedCardTaggedWildcard_IsKept() { - ListValue = new ListValue { Values = { new Value { StringValue = linkedId.ToString() } } }, - }; - - var fetched = new RetrievedPoint { Id = new PointId { Uuid = linkedId.ToString() } }; - fetched.Payload["card_id"] = "card-linked"; - fetched.Payload["body"] = "linked text"; - fetched.Payload["brand"] = linkedFacet; + // Linked cards are fetched by id and never pass the Qdrant filter, so InScope is the only + // gate on them. It has to accept the same set the query did. + QdrantKnowledgeStore store = StoreOver( + ChannelWithLink(linkedFacet: "*"), wildcard: "*", wildcardFacets: ["brand"], withLinks: true); + IReadOnlyList cards = await store.SearchAsync( + "belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); + Assert.Contains(cards, card => card.ViaLink); + } + + [Fact] + public async Task Search_LinkedCardOutsideTheScope_IsDropped() + { + QdrantKnowledgeStore store = StoreOver( + ChannelWithLink(linkedFacet: "spirit"), wildcard: "*", wildcardFacets: ["brand"], withLinks: true); - return new CapturingSearchChannel([ranked], [fetched]); - } + IReadOnlyList cards = await store.SearchAsync( + "belt", Scope(("brand", "sole")), TestContext.Current.CancellationToken); + Assert.DoesNotContain(cards, card => card.ViaLink); + } - private static QdrantKnowledgeStore StoreOver( - CapturingSearchChannel channel, - string? wildcard, - IReadOnlyList wildcardFacets, - bool withLinks = false) => new( - channel, - new FakeEmbeddingGenerator([1f]), - new QdrantKnowledgeStoreOptions + /// A ranked point linking to one fetched point tagged on brand. + private static CapturingSearchChannel ChannelWithLink(string linkedFacet) + { + Guid linkedId = Guid.NewGuid(); + + ScoredPoint ranked = new() { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Score = 1f }; + ranked.Payload["card_id"] = "card-1"; + ranked.Payload["body"] = "text"; + ranked.Payload["see_also"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = linkedId.ToString() } } }, + }; + + RetrievedPoint fetched = new() { Id = new PointId { Uuid = linkedId.ToString() } }; + fetched.Payload["card_id"] = "card-linked"; + fetched.Payload["body"] = "linked text"; + fetched.Payload["brand"] = linkedFacet; + + return new CapturingSearchChannel([ranked], [fetched]); + } + + private static QdrantKnowledgeStore StoreOver( + CapturingSearchChannel channel, + string? wildcard, + IReadOnlyList wildcardFacets, + bool withLinks = false) { - Collection = "anything", - Scoped = true, - ScopeTemplate = "{key}", - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - ScoreFloor = 0.0, - ScopeWildcard = wildcard, - ScopeWildcardFacets = wildcardFacets, - Links = withLinks - ? new KnowledgeLinksConfiguration { Field = "see_also", Lookup = KnowledgeLinkLookup.Direct } - : null, - }); + return new( + channel, + new FakeEmbeddingGenerator([1f]), + new QdrantKnowledgeStoreOptions + { + Collection = "anything", + Scoped = true, + ScopeTemplate = "{key}", + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + ScoreFloor = 0.0, + ScopeWildcard = wildcard, + ScopeWildcardFacets = wildcardFacets, + Links = withLinks + ? new KnowledgeLinksConfiguration { Field = "see_also", Lookup = KnowledgeLinkLookup.Direct } + : null, + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ScoreFloorOnPrefetchTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ScoreFloorOnPrefetchTests.cs index be2db66d..5a1a607c 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ScoreFloorOnPrefetchTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ScoreFloorOnPrefetchTests.cs @@ -1,124 +1,131 @@ using AgentCore.Application.Configuration.Schema; +using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; using AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// scoreFloor is a cosine similarity, and Qdrant applies it on the dense prefetch. It is never -/// compared against a fused score: with one leg, RRF hands back 1/(rank+1) for every query, so a -/// floor on that number is a fixed rank cut — measured 2026-09-02 on the owner's collection as exactly -/// three cards for every question, answered or not. -/// -public sealed class ScoreFloorOnPrefetchTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// What a single-leg RRF fusion returns for any five points, whatever was asked. - private static readonly float[] RankScores = [0.5f, 1f / 3f, 0.25f, 0.2f, 1f / 6f]; - - [Fact] - public async Task SearchAsync_PutsTheFloorOnEveryDensePrefetch() + /// + /// scoreFloor is a cosine similarity, and Qdrant applies it on the dense prefetch. It is never + /// compared against a fused score: with one leg, RRF hands back 1/(rank+1) for every query, so a + /// floor on that number is a fixed rank cut — measured 2026-09-02 on the owner's collection as exactly + /// three cards for every question, answered or not. + /// + public sealed class ScoreFloorOnPrefetchTests { - var channel = new CapturingSearchChannel(Points(RankScores)); + /// What a single-leg RRF fusion returns for any five points, whatever was asked. + private static readonly float[] RankScores = [0.5f, 1f / 3f, 0.25f, 0.2f, 1f / 6f]; + + [Fact] + public async Task SearchAsync_PutsTheFloorOnEveryDensePrefetch() + { + CapturingSearchChannel channel = new(Points(RankScores)); - await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); + _ = await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); - var leg = Assert.Single(channel.Query!.Prefetch); - Assert.True(leg.HasScoreThreshold, "the dense prefetch carries no score_threshold"); - Assert.Equal(0.35f, leg.ScoreThreshold); - } + PrefetchQuery leg = Assert.Single(channel.Query!.Prefetch); + Assert.True(leg.HasScoreThreshold, "the dense prefetch carries no score_threshold"); + Assert.Equal(0.35f, leg.ScoreThreshold); + } - [Fact] - public async Task SearchAsync_WithZeroFloor_EmitsNoScoreThreshold() - { - var channel = new CapturingSearchChannel(Points(RankScores)); + [Fact] + public async Task SearchAsync_WithZeroFloor_EmitsNoScoreThreshold() + { + CapturingSearchChannel channel = new(Points(RankScores)); - await Store(channel, floor: 0.0).SearchAsync("belt", null, TestContext.Current.CancellationToken); + _ = await Store(channel, floor: 0.0).SearchAsync("belt", null, TestContext.Current.CancellationToken); - var leg = Assert.Single(channel.Query!.Prefetch); - Assert.False(leg.HasScoreThreshold, "a floor of 0 means no floor, so no score_threshold should ride the prefetch"); - } + PrefetchQuery leg = Assert.Single(channel.Query!.Prefetch); + Assert.False(leg.HasScoreThreshold, "a floor of 0 means no floor, so no score_threshold should ride the prefetch"); + } - [Fact] - public async Task SearchAsync_DoesNotCutTheReturnedPointsByScore() - { - var channel = new CapturingSearchChannel(Points(RankScores)); + [Fact] + public async Task SearchAsync_DoesNotCutTheReturnedPointsByScore() + { + CapturingSearchChannel channel = new(Points(RankScores)); - var cards = await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); + IReadOnlyList cards = await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); - // Qdrant already applied the floor before these came back. Cutting again by a fused score - // would keep one of five here, and three of five at 0.25. - Assert.Equal(5, cards.Count); - } + // Qdrant already applied the floor before these came back. Cutting again by a fused score + // would keep one of five here, and three of five at 0.25. + Assert.Equal(5, cards.Count); + } - [Fact] - public async Task SearchAsync_WithOneLeg_AsksForTheNearestVectorRatherThanAFusion() - { - var channel = new CapturingSearchChannel(Points(RankScores)); + [Fact] + public async Task SearchAsync_WithOneLeg_AsksForTheNearestVectorRatherThanAFusion() + { + CapturingSearchChannel channel = new(Points(RankScores)); - await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); + _ = await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); - // One leg has nothing to fuse. A nearest query over the prefetch re-scores the same vector, - // so a card's score is its cosine similarity and the floor and the score share a scale. - Assert.Equal(Query.VariantOneofCase.Nearest, channel.Query!.Query.VariantCase); - } + // One leg has nothing to fuse. A nearest query over the prefetch re-scores the same vector, + // so a card's score is its cosine similarity and the floor and the score share a scale. + Assert.Equal(Query.VariantOneofCase.Nearest, channel.Query!.Query.VariantCase); + } - [Fact] - public async Task SearchAsync_WithOneLegOverAnAnonymousVector_NamesNoVectorAnywhere() - { - var channel = new CapturingSearchChannel(Points(RankScores)); + [Fact] + public async Task SearchAsync_WithOneLegOverAnAnonymousVector_NamesNoVectorAnywhere() + { + CapturingSearchChannel channel = new(Points(RankScores)); - await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); + _ = await Store(channel, floor: 0.35).SearchAsync("belt", null, TestContext.Current.CancellationToken); - Assert.Null(channel.Query!.Using); - Assert.Equal(string.Empty, Assert.Single(channel.Query.Prefetch).Using); - } + Assert.Null(channel.Query!.Using); + Assert.Equal(string.Empty, Assert.Single(channel.Query.Prefetch).Using); + } - [Fact] - public async Task SearchAsync_WithOneLegOverANamedVector_NamesItOnBothTheLegAndTheQuery() - { - var channel = new CapturingSearchChannel(Points(RankScores)); + [Fact] + public async Task SearchAsync_WithOneLegOverANamedVector_NamesItOnBothTheLegAndTheQuery() + { + CapturingSearchChannel channel = new(Points(RankScores)); - await Store(channel, floor: 0.35, vector: "dense").SearchAsync("belt", null, TestContext.Current.CancellationToken); + _ = await Store(channel, floor: 0.35, vector: "dense").SearchAsync("belt", null, TestContext.Current.CancellationToken); - Assert.Equal("dense", channel.Query!.Using); - Assert.Equal("dense", Assert.Single(channel.Query.Prefetch).Using); - } + Assert.Equal("dense", channel.Query!.Using); + Assert.Equal("dense", Assert.Single(channel.Query.Prefetch).Using); + } - [Fact] - public async Task SearchAsync_WithABlankVectorName_ReadsItAsTheAnonymousVector() - { - // The leg and the top-level query have to agree on which collection shape they are querying, - // and a blank name is the same shape as no name at all. - var channel = new CapturingSearchChannel(Points(RankScores)); + [Fact] + public async Task SearchAsync_WithABlankVectorName_ReadsItAsTheAnonymousVector() + { + // The leg and the top-level query have to agree on which collection shape they are querying, + // and a blank name is the same shape as no name at all. + CapturingSearchChannel channel = new(Points(RankScores)); - await Store(channel, floor: 0.35, vector: string.Empty).SearchAsync("belt", null, TestContext.Current.CancellationToken); + _ = await Store(channel, floor: 0.35, vector: string.Empty).SearchAsync("belt", null, TestContext.Current.CancellationToken); - Assert.Null(channel.Query!.Using); - Assert.Equal(string.Empty, Assert.Single(channel.Query.Prefetch).Using); - } + Assert.Null(channel.Query!.Using); + Assert.Equal(string.Empty, Assert.Single(channel.Query.Prefetch).Using); + } - private static IReadOnlyList Points(float[] scores) => - [.. scores.Select((score, i) => + private static IReadOnlyList Points(float[] scores) { - var point = new ScoredPoint { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Score = score }; - point.Payload["card_id"] = $"card-{i}"; - point.Payload["body"] = "text"; - return point; - })]; - - private static QdrantKnowledgeStore Store( - CapturingSearchChannel channel, double floor, string? vector = null) => new( - channel, - new FakeEmbeddingGenerator([1f]), - new QdrantKnowledgeStoreOptions + return [.. scores.Select((score, i) => + { + ScoredPoint point = new() { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Score = score }; + point.Payload["card_id"] = $"card-{i}"; + point.Payload["body"] = "text"; + return point; + })]; + } + + private static QdrantKnowledgeStore Store( + CapturingSearchChannel channel, double floor, string? vector = null) { - Collection = "anything", - Scoped = false, - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - ScoreFloor = floor, - VectorName = vector, - }); + return new( + channel, + new FakeEmbeddingGenerator([1f]), + new QdrantKnowledgeStoreOptions + { + Collection = "anything", + Scoped = false, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + ScoreFloor = floor, + VectorName = vector, + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/StoreNamingNeutralityTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/StoreNamingNeutralityTests.cs index a695c063..dc647c8e 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/StoreNamingNeutralityTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/StoreNamingNeutralityTests.cs @@ -7,226 +7,234 @@ using Qdrant.Client.Grpc; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// Every payload name the store uses comes from the document, and none from the framework. -/// -/// -/// -/// These run with no Qdrant. That is the point: the neutrality proof used to live entirely in -/// , which is [QdrantFact] and therefore SKIPS on a machine -/// with no server. A green dotnet test proved nothing about naming at all. -/// -/// -/// They also assert the requests themselves rather than the rows that come back. A live query that -/// returns the right rows is consistent with the store having guessed a key correctly; a captured -/// FieldCondition naming region is not. -/// -/// -public sealed class StoreNamingNeutralityTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// The one collection these tests describe: nothing shared with any other corpus. - private static KnowledgeFieldsConfiguration Foreign => new() - { - Id = "doc_id", - Body = "content", - Lexical = "content", - Source = "origin", - Locator = "page", - Authority = "trust", - }; - - [Fact] - public async Task Search_ReadsEveryRoleFromThePathTheDocumentNamed() + /// + /// Every payload name the store uses comes from the document, and none from the framework. + /// + /// + /// + /// These run with no Qdrant. That is the point: the neutrality proof used to live entirely in + /// , which is [QdrantFact] and therefore SKIPS on a machine + /// with no server. A green dotnet test proved nothing about naming at all. + /// + /// + /// They also assert the requests themselves rather than the rows that come back. A live query that + /// returns the right rows is consistent with the store having guessed a key correctly; a captured + /// FieldCondition naming region is not. + /// + /// + public sealed class StoreNamingNeutralityTests { - var channel = new CapturingSearchChannel([Point()]); + /// The one collection these tests describe: nothing shared with any other corpus. + private static KnowledgeFieldsConfiguration Foreign => new() + { + Id = "doc_id", + Body = "content", + Lexical = "content", + Source = "origin", + Locator = "page", + Authority = "trust", + }; - var card = Assert.Single(await Store(channel).SearchAsync("anything", null, TestContext.Current.CancellationToken)); + [Fact] + public async Task Search_ReadsEveryRoleFromThePathTheDocumentNamed() + { + CapturingSearchChannel channel = new([Point()]); - Assert.Equal("DOC-01", card.CardId); - Assert.Equal("the body text", card.Text); - Assert.Equal("handbook-7", card.SourceRef); - Assert.Equal("s.4", card.SourceLocator); - Assert.Equal(2, card.Authority); - } + KnowledgeCard card = Assert.Single(await Store(channel).SearchAsync("anything", null, TestContext.Current.CancellationToken)); - [Fact] - public async Task Search_AScopeFacet_BecomesThePathTheTemplateNames() - { - // The template is the whole contract. "facets.{key}" and "{key}" address different payloads, - // and a store that picked one would silently match nothing against the other. - var channel = new CapturingSearchChannel([Point()]); + Assert.Equal("DOC-01", card.CardId); + Assert.Equal("the body text", card.Text); + Assert.Equal("handbook-7", card.SourceRef); + Assert.Equal("s.4", card.SourceLocator); + Assert.Equal(2, card.Authority); + } - await Store(channel, template: "{key}", scoped: true) - .SearchAsync("anything", Scope("region", "emea"), TestContext.Current.CancellationToken); + [Fact] + public async Task Search_AScopeFacet_BecomesThePathTheTemplateNames() + { + // The template is the whole contract. "facets.{key}" and "{key}" address different payloads, + // and a store that picked one would silently match nothing against the other. + CapturingSearchChannel channel = new([Point()]); - Assert.Equal("emea", channel.DenseFilterKeywords["region"]); - } + _ = await Store(channel, template: "{key}", scoped: true) + .SearchAsync("anything", Scope("region", "emea"), TestContext.Current.CancellationToken); - [Fact] - public async Task Search_ANestedTemplate_BecomesADottedPath() - { - var channel = new CapturingSearchChannel([Point()]); - await Store(channel, template: "attributes.{key}", scoped: true) - .SearchAsync("anything", Scope("region", "emea"), TestContext.Current.CancellationToken); + Assert.Equal("emea", channel.DenseFilterKeywords["region"]); + } - Assert.Equal("emea", channel.DenseFilterKeywords["attributes.region"]); - Assert.False(channel.DenseFilterKeywords.ContainsKey("facets.region")); - } + [Fact] + public async Task Search_ANestedTemplate_BecomesADottedPath() + { + CapturingSearchChannel channel = new([Point()]); + _ = await Store(channel, template: "attributes.{key}", scoped: true) + .SearchAsync("anything", Scope("region", "emea"), TestContext.Current.CancellationToken); - [Fact] - public async Task Search_TheRequiredTermLeg_MatchesOnTheMappedLexicalField() - { - var channel = new CapturingSearchChannel([Point()]); + Assert.Equal("emea", channel.DenseFilterKeywords["attributes.region"]); + Assert.False(channel.DenseFilterKeywords.ContainsKey("facets.region")); + } - await Store(channel, analyzer: new FixedTermAnalyzer()) - .SearchAsync("the screen says e33", null, TestContext.Current.CancellationToken); + [Fact] + public async Task Search_TheRequiredTermLeg_MatchesOnTheMappedLexicalField() + { + CapturingSearchChannel channel = new([Point()]); - Assert.Equal("content", Assert.Single(channel.LexicalKeys)); - } + _ = await Store(channel, analyzer: new FixedTermAnalyzer()) + .SearchAsync("the screen says e33", null, TestContext.Current.CancellationToken); - [Fact] - public async Task Search_NoLexicalRoleMapped_SendsOneLegAndNoTextCondition() - { - // Unmapped means absent, not "fall back to a field called text". A store that guessed would - // filter on a key this collection has no index for and drop every row. - var channel = new CapturingSearchChannel([Point()]); - await Store(channel, fields: Foreign with { Lexical = null }, analyzer: new FixedTermAnalyzer()) - .SearchAsync("the screen says e33", null, TestContext.Current.CancellationToken); - - Assert.Empty(channel.LexicalKeys); - Assert.Single(channel.Query!.Prefetch); - } + Assert.Equal("content", Assert.Single(channel.LexicalKeys)); + } - [Fact] - public async Task Search_NoIdRoleMapped_FallsBackToThePointKey() - { - var key = Guid.NewGuid(); - var channel = new CapturingSearchChannel([Point(key)]); + [Fact] + public async Task Search_NoLexicalRoleMapped_SendsOneLegAndNoTextCondition() + { + // Unmapped means absent, not "fall back to a field called text". A store that guessed would + // filter on a key this collection has no index for and drop every row. + CapturingSearchChannel channel = new([Point()]); + _ = await Store(channel, fields: Foreign with { Lexical = null }, analyzer: new FixedTermAnalyzer()) + .SearchAsync("the screen says e33", null, TestContext.Current.CancellationToken); + + Assert.Empty(channel.LexicalKeys); + _ = Assert.Single(channel.Query!.Prefetch); + } + + [Fact] + public async Task Search_NoIdRoleMapped_FallsBackToThePointKey() + { + Guid key = Guid.NewGuid(); + CapturingSearchChannel channel = new([Point(key)]); - var card = Assert.Single(await Store(channel, fields: Foreign with { Id = null }) - .SearchAsync("anything", null, TestContext.Current.CancellationToken)); + KnowledgeCard card = Assert.Single(await Store(channel, fields: Foreign with { Id = null }) + .SearchAsync("anything", null, TestContext.Current.CancellationToken)); - Assert.Equal(key.ToString(), card.CardId); - } + Assert.Equal(key.ToString(), card.CardId); + } - [Fact] - public async Task Search_NoSourceOrLocatorMapped_LeavesBothEmptyRatherThanGuessing() - { - var channel = new CapturingSearchChannel([Point()]); + [Fact] + public async Task Search_NoSourceOrLocatorMapped_LeavesBothEmptyRatherThanGuessing() + { + CapturingSearchChannel channel = new([Point()]); - var card = Assert.Single(await Store(channel, fields: Foreign with { Source = null, Locator = null }) - .SearchAsync("anything", null, TestContext.Current.CancellationToken)); + KnowledgeCard card = Assert.Single(await Store(channel, fields: Foreign with { Source = null, Locator = null }) + .SearchAsync("anything", null, TestContext.Current.CancellationToken)); - Assert.Equal(string.Empty, card.SourceRef); - Assert.Equal(string.Empty, card.SourceLocator); - } + Assert.Equal(string.Empty, card.SourceRef); + Assert.Equal(string.Empty, card.SourceLocator); + } - [Fact] - public async Task Search_ALinkFilter_ReadsTheLinkFieldAndMatchesOnTheMappedId() - { - var channel = new CapturingSearchChannel([Point()]); - - await Store(channel, links: new KnowledgeLinksConfiguration + [Fact] + public async Task Search_ALinkFilter_ReadsTheLinkFieldAndMatchesOnTheMappedId() { - Field = "related", - Lookup = KnowledgeLinkLookup.Filter, - }).SearchAsync("anything", null, TestContext.Current.CancellationToken); - - var condition = Assert.Single(channel.ScrollFilter!.Must); - Assert.Equal("doc_id", condition.Field.Key); - Assert.Equal(["DOC-99"], condition.Field.Match.Keywords.Strings); - } + CapturingSearchChannel channel = new([Point()]); - [Fact] - public async Task Search_AUuid5Link_HashesWithTheNamespaceAndPrefixTheDocumentNamed() - { - var channel = new CapturingSearchChannel([Point()]); - - // links.Namespace is a NAME; the adapter resolves it to a Guid and puts that on the options, - // so a store built in code has to carry the resolved value. Setting only the name here leaves - // the store on its own default and the derived key is wrong -- which is what this assertion - // caught on the first run. - await Store( - channel, - links: new KnowledgeLinksConfiguration + _ = await Store(channel, links: new KnowledgeLinksConfiguration { Field = "related", - Lookup = KnowledgeLinkLookup.Uuid5, - Namespace = "dns", - Prefix = "doc:", - }, - linkNamespace: Uuid5PointId.Namespace("dns")) - .SearchAsync("anything", null, TestContext.Current.CancellationToken); - - Assert.Equal( - [Uuid5PointId.For("DOC-99", Uuid5PointId.Namespace("dns"), "doc:")], - Assert.Single(channel.RetrievedIds)); - } + Lookup = KnowledgeLinkLookup.Filter, + }).SearchAsync("anything", null, TestContext.Current.CancellationToken); - /// One scored point, shaped the way the foreign collection shapes one. - private static ScoredPoint Point(Guid? key = null) - { - var point = new ScoredPoint - { - Id = new PointId { Uuid = (key ?? Guid.NewGuid()).ToString() }, - Score = 1f, - }; + Condition condition = Assert.Single(channel.ScrollFilter!.Must); + Assert.Equal("doc_id", condition.Field.Key); + Assert.Equal(["DOC-99"], condition.Field.Match.Keywords.Strings); + } - point.Payload["doc_id"] = "DOC-01"; - point.Payload["content"] = "the body text"; - point.Payload["origin"] = "handbook-7"; - point.Payload["page"] = "s.4"; - point.Payload["trust"] = 2; - point.Payload["region"] = "emea"; - point.Payload["related"] = new Value + [Fact] + public async Task Search_AUuid5Link_HashesWithTheNamespaceAndPrefixTheDocumentNamed() { - ListValue = new ListValue { Values = { new Value { StringValue = "DOC-99" } } }, - }; - - return point; - } - - private static KnowledgeScope Scope(string key, string value) - => new() { Facets = new Dictionary(StringComparer.Ordinal) { [key] = value } }; + CapturingSearchChannel channel = new([Point()]); + + // links.Namespace is a NAME; the adapter resolves it to a Guid and puts that on the options, + // so a store built in code has to carry the resolved value. Setting only the name here leaves + // the store on its own default and the derived key is wrong -- which is what this assertion + // caught on the first run. + _ = await Store( + channel, + links: new KnowledgeLinksConfiguration + { + Field = "related", + Lookup = KnowledgeLinkLookup.Uuid5, + Namespace = "dns", + Prefix = "doc:", + }, + linkNamespace: Uuid5PointId.Namespace("dns")) + .SearchAsync("anything", null, TestContext.Current.CancellationToken); + + Assert.Equal( + [Uuid5PointId.For("DOC-99", Uuid5PointId.Namespace("dns"), "doc:")], + Assert.Single(channel.RetrievedIds)); + } + + /// One scored point, shaped the way the foreign collection shapes one. + private static ScoredPoint Point(Guid? key = null) + { + ScoredPoint point = new() + { + Id = new PointId { Uuid = (key ?? Guid.NewGuid()).ToString() }, + Score = 1f, + }; + + point.Payload["doc_id"] = "DOC-01"; + point.Payload["content"] = "the body text"; + point.Payload["origin"] = "handbook-7"; + point.Payload["page"] = "s.4"; + point.Payload["trust"] = 2; + point.Payload["region"] = "emea"; + point.Payload["related"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = "DOC-99" } } }, + }; - /// - /// Requires one fixed term, whatever the query says. - /// - /// - /// The lexical leg needs SOME analyzer to fire, and AgentCore ships only none, which - /// never fires. A test that borrowed a cleverer one would be asserting that analyzer's rules - /// as well as the store's naming. This one has no rules to assert. - /// - private sealed class FixedTermAnalyzer : IKnowledgeQueryAnalyzer - { - public string Name => "fixed-term"; + return point; + } - public IReadOnlyList RequiredTerms(string query) => ["e33"]; - } + private static KnowledgeScope Scope(string key, string value) + { + return new() { Facets = new Dictionary(StringComparer.Ordinal) { [key] = value } }; + } + + /// + /// Requires one fixed term, whatever the query says. + /// + /// + /// The lexical leg needs SOME analyzer to fire, and AgentCore ships only none, which + /// never fires. A test that borrowed a cleverer one would be asserting that analyzer's rules + /// as well as the store's naming. This one has no rules to assert. + /// + private sealed class FixedTermAnalyzer : IKnowledgeQueryAnalyzer + { + public string Name => "fixed-term"; - private static QdrantKnowledgeStore Store( - CapturingSearchChannel channel, - KnowledgeFieldsConfiguration? fields = null, - string? template = null, - KnowledgeLinksConfiguration? links = null, - Guid? linkNamespace = null, - IKnowledgeQueryAnalyzer? analyzer = null, - bool scoped = false) - => new( - channel, - new FakeEmbeddingGenerator([1f]), - new QdrantKnowledgeStoreOptions + public IReadOnlyList RequiredTerms(string query) { - Collection = "anything", - Scoped = scoped, - Fields = fields ?? Foreign, - ScopeTemplate = template, - Links = links, - LinkNamespace = linkNamespace ?? Uuid5PointId.Namespace(KnowledgeLinksConfiguration.DefaultNamespace), - Analyzer = analyzer ?? new NoQueryAnalyzer(), - Limit = 5, - ScoreFloor = 0.0, - }); + return ["e33"]; + } + } + + private static QdrantKnowledgeStore Store( + CapturingSearchChannel channel, + KnowledgeFieldsConfiguration? fields = null, + string? template = null, + KnowledgeLinksConfiguration? links = null, + Guid? linkNamespace = null, + IKnowledgeQueryAnalyzer? analyzer = null, + bool scoped = false) + { + return new( + channel, + new FakeEmbeddingGenerator([1f]), + new QdrantKnowledgeStoreOptions + { + Collection = "anything", + Scoped = scoped, + Fields = fields ?? Foreign, + ScopeTemplate = template, + Links = links, + LinkNamespace = linkNamespace ?? Uuid5PointId.Namespace(KnowledgeLinksConfiguration.DefaultNamespace), + Analyzer = analyzer ?? new NoQueryAnalyzer(), + Limit = 5, + ScoreFloor = 0.0, + }); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs index a5cf204c..30221c4b 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs @@ -1,12 +1,16 @@ using AgentCore.Domain.Knowledge; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// The scope a wildcard test opens, built from the facets it names. -internal static class TestScopes +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - internal static KnowledgeScope Scope(params (string Key, string Value)[] facets) => new() + /// The scope a wildcard test opens, built from the facets it names. + internal static class TestScopes { - Facets = facets.ToDictionary(facet => facet.Key, facet => facet.Value, StringComparer.Ordinal), - }; + internal static KnowledgeScope Scope(params (string Key, string Value)[] facets) + { + return new() + { + Facets = facets.ToDictionary(facet => facet.Key, facet => facet.Value, StringComparer.Ordinal), + }; + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Uuid5PointIdTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Uuid5PointIdTests.cs index f19fe4c7..c6cbe114 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Uuid5PointIdTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Uuid5PointIdTests.cs @@ -1,87 +1,104 @@ using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using Xunit; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// The uuid5 formula, and nothing about any one collection. -/// -/// -/// Every fact here passes its own namespace and its own prefix. The class used to carry a default -/// pair — the URL namespace and the literal "kb:" — so half these tests read as if one -/// ingester's parameters were the formula's own. They are the caller's, always. -/// -public sealed class Uuid5PointIdTests +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - private const string Card = "widget-a17-drive-fault"; + /// + /// The uuid5 formula, and nothing about any one collection. + /// + /// + /// Every fact here passes its own namespace and its own prefix. The class used to carry a default + /// pair — the URL namespace and the literal "kb:" — so half these tests read as if one + /// ingester's parameters were the formula's own. They are the caller's, always. + /// + public sealed class Uuid5PointIdTests + { + private const string Card = "widget-a17-drive-fault"; - [Theory] - // Pinned literals, produced by an independent implementation: - // python -c "import uuid; print(uuid.uuid5(uuid.NAMESPACE_URL, PREFIX + CARD))" - // A formula checked against itself proves nothing, and a mismatch here means every uuid5 - // lookup silently misses. - [InlineData("url", "", "459e76aa-7b3f-59aa-aef2-da90c566e47c")] - [InlineData("url", "kb:", "b0a8762f-3b73-5efe-8ce0-c889e5a37e20")] - [InlineData("dns", "kb:", "6fe7cd5c-3e48-53bc-ad5a-ac16514fc07b")] - public void For_MatchesAnIndependentUuid5(string ns, string prefix, string expected) - => Assert.Equal(Guid.Parse(expected), Uuid5PointId.For(Card, Uuid5PointId.Namespace(ns), prefix)); + [Theory] + // Pinned literals, produced by an independent implementation: + // python -c "import uuid; print(uuid.uuid5(uuid.NAMESPACE_URL, PREFIX + CARD))" + // A formula checked against itself proves nothing, and a mismatch here means every uuid5 + // lookup silently misses. + [InlineData("url", "", "459e76aa-7b3f-59aa-aef2-da90c566e47c")] + [InlineData("url", "kb:", "b0a8762f-3b73-5efe-8ce0-c889e5a37e20")] + [InlineData("dns", "kb:", "6fe7cd5c-3e48-53bc-ad5a-ac16514fc07b")] + public void For_MatchesAnIndependentUuid5(string ns, string prefix, string expected) + { + Assert.Equal(Guid.Parse(expected), Uuid5PointId.For(Card, Uuid5PointId.Namespace(ns), prefix)); + } - [Fact] - public void For_IsDeterministic() - => Assert.Equal(Key(Card), Key(Card)); + [Fact] + public void For_IsDeterministic() + { + Assert.Equal(Key(Card), Key(Card)); + } - [Theory] - [InlineData("widget-a17-drive-faul")] - [InlineData("widget-a17-drive-faults")] - [InlineData("WIDGET-A17-DRIVE-FAULT")] - public void For_NearMissId_IsADifferentGuid(string near) - => Assert.NotEqual(Key(Card), Key(near)); + [Theory] + [InlineData("widget-a17-drive-faul")] + [InlineData("widget-a17-drive-faults")] + [InlineData("WIDGET-A17-DRIVE-FAULT")] + public void For_NearMissId_IsADifferentGuid(string near) + { + Assert.NotEqual(Key(Card), Key(near)); + } - [Fact] - public void For_IsVersion5() - { - var bytes = Key(Card).ToByteArray(bigEndian: true); + [Fact] + public void For_IsVersion5() + { + byte[] bytes = Key(Card).ToByteArray(bigEndian: true); - Assert.Equal(0x50, bytes[6] & 0xF0); - Assert.Equal(0x80, bytes[8] & 0xC0); - } + Assert.Equal(0x50, bytes[6] & 0xF0); + Assert.Equal(0x80, bytes[8] & 0xC0); + } - [Fact] - public void For_DifferentPrefix_IsADifferentGuid() - => Assert.NotEqual( - Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "kb:"), - Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "doc:")); + [Fact] + public void For_DifferentPrefix_IsADifferentGuid() + { + Assert.NotEqual( + Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "kb:"), + Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "doc:")); + } - [Fact] - public void For_AnEmptyPrefix_IsADifferentGuidFromAnyPrefix() - { - // The framework's own default is now the empty prefix, so this is the pair a deployment - // gets wrong first: an ingester that hashed with a prefix and a document that names none. - Assert.NotEqual( - Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), string.Empty), - Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "kb:")); - } + [Fact] + public void For_AnEmptyPrefix_IsADifferentGuidFromAnyPrefix() + { + // The framework's own default is now the empty prefix, so this is the pair a deployment + // gets wrong first: an ingester that hashed with a prefix and a document that names none. + Assert.NotEqual( + Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), string.Empty), + Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "kb:")); + } - [Fact] - public void For_DifferentNamespace_IsADifferentGuid() - => Assert.NotEqual( - Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "kb:"), - Uuid5PointId.For(Card, Uuid5PointId.Namespace("dns"), "kb:")); + [Fact] + public void For_DifferentNamespace_IsADifferentGuid() + { + Assert.NotEqual( + Uuid5PointId.For(Card, Uuid5PointId.Namespace("url"), "kb:"), + Uuid5PointId.For(Card, Uuid5PointId.Namespace("dns"), "kb:")); + } - [Theory] - [InlineData("url", "6ba7b811-9dad-11d1-80b4-00c04fd430c8")] - [InlineData("URL", "6ba7b811-9dad-11d1-80b4-00c04fd430c8")] - [InlineData("dns", "6ba7b810-9dad-11d1-80b4-00c04fd430c8")] - [InlineData("oid", "6ba7b812-9dad-11d1-80b4-00c04fd430c8")] - [InlineData("x500", "6ba7b814-9dad-11d1-80b4-00c04fd430c8")] - [InlineData("3f2504e0-4f89-11d3-9a0c-0305e82c3301", "3f2504e0-4f89-11d3-9a0c-0305e82c3301")] - public void Namespace_ResolvesNameOrGuid(string name, string expected) - => Assert.Equal(Guid.Parse(expected), Uuid5PointId.Namespace(name)); + [Theory] + [InlineData("url", "6ba7b811-9dad-11d1-80b4-00c04fd430c8")] + [InlineData("URL", "6ba7b811-9dad-11d1-80b4-00c04fd430c8")] + [InlineData("dns", "6ba7b810-9dad-11d1-80b4-00c04fd430c8")] + [InlineData("oid", "6ba7b812-9dad-11d1-80b4-00c04fd430c8")] + [InlineData("x500", "6ba7b814-9dad-11d1-80b4-00c04fd430c8")] + [InlineData("3f2504e0-4f89-11d3-9a0c-0305e82c3301", "3f2504e0-4f89-11d3-9a0c-0305e82c3301")] + public void Namespace_ResolvesNameOrGuid(string name, string expected) + { + Assert.Equal(Guid.Parse(expected), Uuid5PointId.Namespace(name)); + } - [Fact] - public void Namespace_UnknownName_Throws() - => Assert.Throws(() => Uuid5PointId.Namespace("not-a-namespace")); + [Fact] + public void Namespace_UnknownName_Throws() + { + _ = Assert.Throws(() => Uuid5PointId.Namespace("not-a-namespace")); + } - private static Guid Key(string cardId) - => Uuid5PointId.For(cardId, Uuid5PointId.Namespace("url"), "kb:"); + private static Guid Key(string cardId) + { + return Uuid5PointId.For(cardId, Uuid5PointId.Namespace("url"), "kb:"); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs index 5ef4dfda..6f9a617d 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs @@ -1,4 +1,5 @@ using AgentCore.Application.Configuration.Schema; +using AgentCore.Domain.Knowledge; using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; using AgentCore.Infrastructure.Tests.Fakes; using Qdrant.Client; @@ -6,175 +7,177 @@ using Xunit; using static AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.TestScopes; -namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; - -/// -/// A three-point collection shaped like the spec's wildcard-scope walkthrough: a company-wide -/// card, a brand-wide card, and a card scoped to one machine. -/// -/// -/// Every test here only reads, so one collection serves them all, built once for the class. -/// -public sealed class WildcardScopeCorpusFixture : IAsyncLifetime +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant { - /// The named dense vector every point and every query use. - public const string VectorName = "dense"; - - private const int Dim = 4; - - /// The query vector, close to every point so none is dropped by the score floor. - public static float[] QueryVector() => [1f, 0f, 0f, 0f]; - - /// Gets the collection name. Dropped when the class finishes. - public string Name { get; } = $"wildcard-scope-{Guid.NewGuid():N}"; + /// + /// A three-point collection shaped like the spec's wildcard-scope walkthrough: a company-wide + /// card, a brand-wide card, and a card scoped to one machine. + /// + /// + /// Every test here only reads, so one collection serves them all, built once for the class. + /// + public sealed class WildcardScopeCorpusFixture : IAsyncLifetime + { + /// The named dense vector every point and every query use. + public const string VectorName = "dense"; - /// Gets the client the tests query through. - public QdrantClient Client { get; private set; } = null!; + private const int Dim = 4; - public async ValueTask InitializeAsync() - { - if (!QdrantServer.IsConfigured) + /// The query vector, close to every point so none is dropped by the score floor. + public static float[] QueryVector() { - return; + return [1f, 0f, 0f, 0f]; } - Client = QdrantServer.CreateClient(); + /// Gets the collection name. Dropped when the class finishes. + public string Name { get; } = $"wildcard-scope-{Guid.NewGuid():N}"; - await Client.CreateCollectionAsync( - Name, - vectorsConfig: new VectorParamsMap - { - Map = { [VectorName] = new VectorParams { Size = Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); - - await Client.CreatePayloadIndexAsync( - Name, "card_id", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); - await Client.CreatePayloadIndexAsync( - Name, "facets.brand", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); - await Client.CreatePayloadIndexAsync( - Name, "facets.applies_to", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); - - var points = new[] + /// Gets the client the tests query through. + public QdrantClient Client { get; private set; } = null!; + + public async ValueTask InitializeAsync() { - Point("policy", brand: "*", appliesTo: "*"), - Point("sole-care", brand: "sole", appliesTo: "*"), - Point("f63-belt", brand: "sole", appliesTo: "f63"), - }; + if (!QdrantServer.IsConfigured) + { + return; + } - await Client.UpsertAsync(Name, points, cancellationToken: TestContext.Current.CancellationToken); - } + Client = QdrantServer.CreateClient(); - public async ValueTask DisposeAsync() - { - if (Client is null) - { - return; + await Client.CreateCollectionAsync( + Name, + vectorsConfig: new VectorParamsMap + { + Map = { [VectorName] = new VectorParams { Size = Dim, Distance = Distance.Cosine } }, + }, + cancellationToken: TestContext.Current.CancellationToken); + + _ = await Client.CreatePayloadIndexAsync( + Name, "card_id", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); + _ = await Client.CreatePayloadIndexAsync( + Name, "facets.brand", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); + _ = await Client.CreatePayloadIndexAsync( + Name, "facets.applies_to", PayloadSchemaType.Keyword, cancellationToken: TestContext.Current.CancellationToken); + + PointStruct[] points = + [ + Point("policy", brand: "*", appliesTo: "*"), + Point("sole-care", brand: "sole", appliesTo: "*"), + Point("f63-belt", brand: "sole", appliesTo: "f63"), + ]; + + _ = await Client.UpsertAsync(Name, points, cancellationToken: TestContext.Current.CancellationToken); } - try + public async ValueTask DisposeAsync() { - await Client.DeleteCollectionAsync(Name); - } - finally - { - Client.Dispose(); + if (Client is null) + { + return; + } + + try + { + await Client.DeleteCollectionAsync(Name); + } + finally + { + Client.Dispose(); + } } - } - /// - /// One point, with facets.brand and facets.applies_to as single-element ARRAYS -- - /// the shape the real knowledge bank writes, and the shape QdrantKnowledgeStore.Holds - /// matches a keyword against. - /// - private static PointStruct Point(string cardId, string brand, string appliesTo) - { - var point = new PointStruct + /// + /// One point, with facets.brand and facets.applies_to as single-element ARRAYS -- + /// the shape the real knowledge bank writes, and the shape QdrantKnowledgeStore.Holds + /// matches a keyword against. + /// + private static PointStruct Point(string cardId, string brand, string appliesTo) { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors { Vectors_ = new NamedVectors { Vectors = { [VectorName] = QueryVector() } } }, - }; + PointStruct point = new() + { + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = new Vectors { Vectors_ = new NamedVectors { Vectors = { [VectorName] = QueryVector() } } }, + }; - point.Payload["card_id"] = cardId; - point.Payload["body"] = $"{cardId} belt maintenance text"; - point.Payload["facets"] = new Value - { - StructValue = new Struct + point.Payload["card_id"] = cardId; + point.Payload["body"] = $"{cardId} belt maintenance text"; + point.Payload["facets"] = new Value { - Fields = + StructValue = new Struct { - ["brand"] = new Value + Fields = { - ListValue = new ListValue { Values = { new Value { StringValue = brand } } }, - }, - ["applies_to"] = new Value - { - ListValue = new ListValue { Values = { new Value { StringValue = appliesTo } } }, + ["brand"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = brand } } }, + }, + ["applies_to"] = new Value + { + ListValue = new ListValue { Values = { new Value { StringValue = appliesTo } } }, + }, }, }, - }, - }; + }; - return point; + return point; + } } -} -/// -/// Proves the scope wildcard end to end against a real Qdrant: which card ids come back at each -/// step, never how many. The result is capped at _options.Limit, so a size assertion would -/// pin that cap rather than the scope. -/// -[Collection(QdrantServerCollection.Name)] -public sealed class WildcardScopeIntegrationTests : IClassFixture -{ - private readonly WildcardScopeCorpusFixture _corpus; + /// + /// Proves the scope wildcard end to end against a real Qdrant: which card ids come back at each + /// step, never how many. The result is capped at _options.Limit, so a size assertion would + /// pin that cap rather than the scope. + /// + [Collection(QdrantServerCollection.Name)] + public sealed class WildcardScopeIntegrationTests(WildcardScopeCorpusFixture corpus) : IClassFixture + { + private readonly WildcardScopeCorpusFixture _corpus = corpus; - public WildcardScopeIntegrationTests(WildcardScopeCorpusFixture corpus) => _corpus = corpus; + [QdrantFact] + public async Task Search_NothingKnown_ReturnsOnlyTheCompanyWideCard() + { + IReadOnlyList cards = await Store.SearchAsync( + "belt", Scope(("brand", "*"), ("applies_to", "*")), TestContext.Current.CancellationToken); + Assert.Equal(["policy"], cards.Select(c => c.CardId).Order(StringComparer.Ordinal)); + } - [QdrantFact] - public async Task Search_NothingKnown_ReturnsOnlyTheCompanyWideCard() - { - var cards = await Store.SearchAsync( - "belt", Scope(("brand", "*"), ("applies_to", "*")), TestContext.Current.CancellationToken); - Assert.Equal(["policy"], cards.Select(c => c.CardId).Order(StringComparer.Ordinal)); - } + [QdrantFact] + public async Task Search_BrandOnly_AdmitsBrandWideAndRefusesTheMachineCard() + { + IReadOnlyList cards = await Store.SearchAsync( + "belt", Scope(("brand", "sole"), ("applies_to", "*")), TestContext.Current.CancellationToken); + List ids = [.. cards.Select(c => c.CardId)]; - [QdrantFact] - public async Task Search_BrandOnly_AdmitsBrandWideAndRefusesTheMachineCard() - { - var cards = await Store.SearchAsync( - "belt", Scope(("brand", "sole"), ("applies_to", "*")), TestContext.Current.CancellationToken); - var ids = cards.Select(c => c.CardId).ToList(); + Assert.Contains("sole-care", ids); + Assert.Contains("policy", ids); + Assert.DoesNotContain("f63-belt", ids); + } - Assert.Contains("sole-care", ids); - Assert.Contains("policy", ids); - Assert.DoesNotContain("f63-belt", ids); - } + [QdrantFact] + public async Task Search_BrandAndMachine_AdmitsAllThree() + { + IReadOnlyList cards = await Store.SearchAsync( + "belt", Scope(("brand", "sole"), ("applies_to", "f63")), TestContext.Current.CancellationToken); + List ids = [.. cards.Select(c => c.CardId)]; - [QdrantFact] - public async Task Search_BrandAndMachine_AdmitsAllThree() - { - var cards = await Store.SearchAsync( - "belt", Scope(("brand", "sole"), ("applies_to", "f63")), TestContext.Current.CancellationToken); - var ids = cards.Select(c => c.CardId).ToList(); + Assert.Contains("f63-belt", ids); + Assert.Contains("sole-care", ids); + Assert.Contains("policy", ids); + } - Assert.Contains("f63-belt", ids); - Assert.Contains("sole-care", ids); - Assert.Contains("policy", ids); + private QdrantKnowledgeStore Store => new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(WildcardScopeCorpusFixture.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Collection = _corpus.Name, + Scoped = true, + VectorName = WildcardScopeCorpusFixture.VectorName, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + ScopeTemplate = "facets.{key}", + ScopeWildcard = "*", + ScopeWildcardFacets = ["brand", "applies_to"], + ScoreFloor = 0.0, + }); } - - private QdrantKnowledgeStore Store => new( - new QdrantSearchChannel(_corpus.Client), - new FakeEmbeddingGenerator(WildcardScopeCorpusFixture.QueryVector()), - new QdrantKnowledgeStoreOptions - { - Collection = _corpus.Name, - Scoped = true, - VectorName = WildcardScopeCorpusFixture.VectorName, - Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, - ScopeTemplate = "facets.{key}", - ScopeWildcard = "*", - ScopeWildcardFacets = ["brand", "applies_to"], - ScoreFloor = 0.0, - }); } diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs b/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs index 7507c5d5..c63dacb2 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/CapturingChatClient.cs @@ -1,36 +1,39 @@ using System.Runtime.CompilerServices; using Microsoft.Extensions.AI; -namespace AgentCore.Infrastructure.Tests.Llm; - -/// Records the options it was called with, and answers nothing. -internal sealed class CapturingChatClient : IChatClient +namespace AgentCore.Infrastructure.Tests.Llm { - public ChatOptions? Seen { get; private set; } - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) + /// Records the options it was called with, and answers nothing. + internal sealed class CapturingChatClient : IChatClient { - Seen = options; - return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); - } + public ChatOptions? Seen { get; private set; } - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - Seen = options; - await Task.Yield(); - yield return new ChatResponseUpdate(ChatRole.Assistant, "ok"); - } + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + Seen = options; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok"))); + } - public object? GetService(Type serviceType, object? serviceKey = null) - => serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + Seen = options; + await Task.Yield(); + yield return new ChatResponseUpdate(ChatRole.Assistant, "ok"); + } - public void Dispose() - { + public object? GetService(Type serviceType, object? serviceKey = null) + { + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs index 135df4be..48704c95 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiContextWindowsTests.cs @@ -1,36 +1,37 @@ using AgentCore.Infrastructure.Llm.OpenAI; using Xunit; -namespace AgentCore.Infrastructure.Tests.Llm; - -/// The built-in OpenAI context window table. -public sealed class OpenAiContextWindowsTests +namespace AgentCore.Infrastructure.Tests.Llm { - [Fact] - public void Lookup_ExactId_ReturnsItsValue() + /// The built-in OpenAI context window table. + public sealed class OpenAiContextWindowsTests { - Assert.Equal(1_050_000, OpenAiContextWindows.Lookup("gpt-6-astra")); - } + [Fact] + public void Lookup_ExactId_ReturnsItsValue() + { + Assert.Equal(1_050_000, OpenAiContextWindows.Lookup("gpt-6-astra")); + } - [Fact] - public void Lookup_DatedSnapshotId_ResolvesThroughTheBaseId() - { - Assert.Equal(1_047_576, OpenAiContextWindows.Lookup("gpt-4.1-mini-2025-04-14")); - } + [Fact] + public void Lookup_DatedSnapshotId_ResolvesThroughTheBaseId() + { + Assert.Equal(1_047_576, OpenAiContextWindows.Lookup("gpt-4.1-mini-2025-04-14")); + } - [Fact] - public void Lookup_LongerPrefixWins_OverAShorterPrefixThatAlsoMatches() - { - // "gpt-5.4" and "gpt-5.4-nano" are both entries, and both match "gpt-5.4-nano-2026-03-17". - // The two have different windows, so this proves the longer prefix wins rather than the - // first or shortest one. - Assert.NotEqual(OpenAiContextWindows.Lookup("gpt-5.4"), OpenAiContextWindows.Lookup("gpt-5.4-nano")); - Assert.Equal(400_000, OpenAiContextWindows.Lookup("gpt-5.4-nano-2026-03-17")); - } + [Fact] + public void Lookup_LongerPrefixWins_OverAShorterPrefixThatAlsoMatches() + { + // "gpt-5.4" and "gpt-5.4-nano" are both entries, and both match "gpt-5.4-nano-2026-03-17". + // The two have different windows, so this proves the longer prefix wins rather than the + // first or shortest one. + Assert.NotEqual(OpenAiContextWindows.Lookup("gpt-5.4"), OpenAiContextWindows.Lookup("gpt-5.4-nano")); + Assert.Equal(400_000, OpenAiContextWindows.Lookup("gpt-5.4-nano-2026-03-17")); + } - [Fact] - public void Lookup_UnknownId_ReturnsNull() - { - Assert.Null(OpenAiContextWindows.Lookup("gpt-does-not-exist")); + [Fact] + public void Lookup_UnknownId_ReturnsNull() + { + Assert.Null(OpenAiContextWindows.Lookup("gpt-does-not-exist")); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs index ed8086a1..49d13bc5 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiPromptCacheKeyTests.cs @@ -6,69 +6,70 @@ using OpenAI.Responses; using Xunit; -namespace AgentCore.Infrastructure.Tests.Llm; - -/// -/// The conversation id the runtime stamps under -/// reaches the vendor as prompt_cache_key, so every turn of one conversation lands on the -/// same prompt cache. Every test here runs offline. -/// -public sealed class OpenAiPromptCacheKeyTests +namespace AgentCore.Infrastructure.Tests.Llm { - [Fact] - public async Task AStampedConversationId_BecomesThePromptCacheKey() + /// + /// The conversation id the runtime stamps under + /// reaches the vendor as prompt_cache_key, so every turn of one conversation lands on the + /// same prompt cache. Every test here runs offline. + /// + public sealed class OpenAiPromptCacheKeyTests { - CapturingChatClient inner = new(); + [Fact] + public async Task AStampedConversationId_BecomesThePromptCacheKey() + { + CapturingChatClient inner = new(); - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); - await client.GetResponseAsync( - "hi", - new ChatOptions - { - AdditionalProperties = new AdditionalPropertiesDictionary + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); + _ = await client.GetResponseAsync( + "hi", + new ChatOptions { - [ChatRequestProperties.ConversationId] = "conv-42", + AdditionalProperties = new AdditionalPropertiesDictionary + { + [ChatRequestProperties.ConversationId] = "conv-42", + }, }, - }, - TestContext.Current.CancellationToken); + TestContext.Current.CancellationToken); - var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + CreateResponseOptions raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Equal("conv-42", raw.PromptCacheKey); - } + Assert.Equal("conv-42", raw.PromptCacheKey); + } - [Fact] - public async Task ARequestOutsideAConversation_SendsNoPromptCacheKey() - { - CapturingChatClient inner = new(); + [Fact] + public async Task ARequestOutsideAConversation_SendsNoPromptCacheKey() + { + CapturingChatClient inner = new(); - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); - await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); + _ = await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + CreateResponseOptions raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Null(raw.PromptCacheKey); - } + Assert.Null(raw.PromptCacheKey); + } - [Fact] - public async Task AKeyTheCallerSetItself_Wins() - { - CapturingChatClient inner = new(); - CreateResponseOptions mine = new() { PromptCacheKey = "caller-key" }; + [Fact] + public async Task AKeyTheCallerSetItself_Wins() + { + CapturingChatClient inner = new(); + CreateResponseOptions mine = new() { PromptCacheKey = "caller-key" }; - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); - await client.GetResponseAsync( - "hi", - new ChatOptions - { - RawRepresentationFactory = _ => mine, - AdditionalProperties = new AdditionalPropertiesDictionary + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort: null); + _ = await client.GetResponseAsync( + "hi", + new ChatOptions { - [ChatRequestProperties.ConversationId] = "conv-42", + RawRepresentationFactory = _ => mine, + AdditionalProperties = new AdditionalPropertiesDictionary + { + [ChatRequestProperties.ConversationId] = "conv-42", + }, }, - }, - TestContext.Current.CancellationToken); + TestContext.Current.CancellationToken); - Assert.Equal("caller-key", mine.PromptCacheKey); + Assert.Equal("caller-key", mine.PromptCacheKey); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs index c6a841c0..9a21b0c4 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs @@ -8,184 +8,188 @@ using OpenAI.Responses; using Xunit; -namespace AgentCore.Infrastructure.Tests.Llm; - -/// -/// providers.llm[].reasoningEffort, and why a document ever writes it. -/// -/// -/// -/// The adapter sends this on the /v1/responses path, which is the only path where a -/// reasoning model accepts function tools at an effort above none. The value therefore -/// reaches the vendor inside , not inside chat-completion -/// options, and these tests pin that shape. -/// -/// -/// Every test here runs offline. No request leaves the process and no key is real. -/// -/// -public sealed class OpenAiReasoningEffortTests +namespace AgentCore.Infrastructure.Tests.Llm { - [Theory] - [InlineData("none")] - [InlineData("minimal")] - [InlineData("low")] - [InlineData("medium")] - [InlineData("high")] - public async Task EveryValueTheSchemaAllows_ReachesTheRequestTheVendorSees(string effort) + /// + /// providers.llm[].reasoningEffort, and why a document ever writes it. + /// + /// + /// + /// The adapter sends this on the /v1/responses path, which is the only path where a + /// reasoning model accepts function tools at an effort above none. The value therefore + /// reaches the vendor inside , not inside chat-completion + /// options, and these tests pin that shape. + /// + /// + /// Every test here runs offline. No request leaves the process and no key is real. + /// + /// + public sealed class OpenAiReasoningEffortTests { - CapturingChatClient inner = new(); + [Theory] + [InlineData("none")] + [InlineData("minimal")] + [InlineData("low")] + [InlineData("medium")] + [InlineData("high")] + public async Task EveryValueTheSchemaAllows_ReachesTheRequestTheVendorSees(string effort) + { + CapturingChatClient inner = new(); - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort); - await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort); + _ = await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var raw = Assert.IsType( - inner.Seen!.RawRepresentationFactory!(inner)); + CreateResponseOptions raw = Assert.IsType( + inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Equal(effort, raw.ReasoningOptions!.ReasoningEffortLevel.ToString()); - } + Assert.Equal(effort, raw.ReasoningOptions!.ReasoningEffortLevel.ToString()); + } - [Fact] - public async Task TheLevelThatSendsNoReasoningAtAll_IsTheOneNamedNone() - { - // Pinned, so a vendor rename is caught here rather than as a 400 at run time against a real - // provider. The SDK marks this type for evaluation (OPENAI001); this is what watches it. - CapturingChatClient inner = new(); + [Fact] + public async Task TheLevelThatSendsNoReasoningAtAll_IsTheOneNamedNone() + { + // Pinned, so a vendor rename is caught here rather than as a 400 at run time against a real + // provider. The SDK marks this type for evaluation (OPENAI001); this is what watches it. + CapturingChatClient inner = new(); - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, "none"); - await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, "none"); + _ = await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + CreateResponseOptions raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Equal(ResponseReasoningEffortLevel.None, raw.ReasoningOptions!.ReasoningEffortLevel); - Assert.Equal("none", ResponseReasoningEffortLevel.None.ToString()); - } + Assert.Equal(ResponseReasoningEffortLevel.None, raw.ReasoningOptions!.ReasoningEffortLevel); + Assert.Equal("none", ResponseReasoningEffortLevel.None.ToString()); + } - [Fact] - public async Task RawOptionsTheCallerBuiltItself_KeepTheValuesTheyAlreadyHold() - { - // A default for the entry, not an override of the conversation. The caller's own object is the one - // the vendor sees, and every value it already carries survives. - CapturingChatClient inner = new(); - CreateResponseOptions mine = new() + [Fact] + public async Task RawOptionsTheCallerBuiltItself_KeepTheValuesTheyAlreadyHold() { - ReasoningOptions = new ResponseReasoningOptions + // A default for the entry, not an override of the conversation. The caller's own object is the one + // the vendor sees, and every value it already carries survives. + CapturingChatClient inner = new(); + CreateResponseOptions mine = new() { - ReasoningEffortLevel = ResponseReasoningEffortLevel.High, - }, - StoredOutputEnabled = true, - }; - - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, "none"); - await client.GetResponseAsync( - "hi", - new ChatOptions { RawRepresentationFactory = _ => mine }, - TestContext.Current.CancellationToken); - - Assert.Same(mine, inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Equal(ResponseReasoningEffortLevel.High, mine.ReasoningOptions!.ReasoningEffortLevel); - Assert.True(mine.StoredOutputEnabled); - } + ReasoningOptions = new ResponseReasoningOptions + { + ReasoningEffortLevel = ResponseReasoningEffortLevel.High, + }, + StoredOutputEnabled = true, + }; + + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, "none"); + _ = await client.GetResponseAsync( + "hi", + new ChatOptions { RawRepresentationFactory = _ => mine }, + TestContext.Current.CancellationToken); + + Assert.Same(mine, inner.Seen!.RawRepresentationFactory!(inner)); + Assert.Equal(ResponseReasoningEffortLevel.High, mine.ReasoningOptions!.ReasoningEffortLevel); + Assert.True(mine.StoredOutputEnabled); + } + + [Theory] + [InlineData("high")] + [InlineData(null)] + public async Task EveryRequest_TellsTheVendorNotToStoreTheConversation(string? effort) + { + // The conversation store owns the transcript. A stored response comes back with a conversation id, + // and ChatClientAgent refuses that next to the ChatHistoryProvider every agent carries. + CapturingChatClient inner = new(); - [Theory] - [InlineData("high")] - [InlineData(null)] - public async Task EveryRequest_TellsTheVendorNotToStoreTheConversation(string? effort) - { - // The conversation store owns the transcript. A stored response comes back with a conversation id, - // and ChatClientAgent refuses that next to the ChatHistoryProvider every agent carries. - CapturingChatClient inner = new(); + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort); + _ = await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort); - await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + CreateResponseOptions raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); - var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + Assert.False(raw.StoredOutputEnabled); + } - Assert.False(raw.StoredOutputEnabled); - } + [Fact] + public async Task AnEntryThatNamesNoEffort_SendsNoReasoningValueAtAll() + { + // Omitting it must not start sending a value the vendor would otherwise have chosen for + // itself. Only the store flag rides along. + CapturingChatClient inner = new(); - [Fact] - public async Task AnEntryThatNamesNoEffort_SendsNoReasoningValueAtAll() - { - // Omitting it must not start sending a value the vendor would otherwise have chosen for - // itself. Only the store flag rides along. - CapturingChatClient inner = new(); + IChatClient client = OpenAiChatClientAdapter.WithResponseDefaults(inner, null); + _ = await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, null); - await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + CreateResponseOptions raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); - var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + Assert.Null(raw.ReasoningOptions); + } - Assert.Null(raw.ReasoningOptions); - } + [Fact] + public void AValueThisVendorDoesNotKnow_FailsAndSaysWhatIsAllowed() + { + ConfigurationLoadException failure = Assert.Throws( + () => OpenAiChatClientAdapter.WithResponseDefaults(new CapturingChatClient(), "exhaustive")); - [Fact] - public void AValueThisVendorDoesNotKnow_FailsAndSaysWhatIsAllowed() - { - var failure = Assert.Throws( - () => OpenAiChatClientAdapter.WithResponseDefaults(new CapturingChatClient(), "exhaustive")); + Assert.Contains(failure.Errors, error => error.Pointer == "/providers/llm"); + Assert.Contains("exhaustive", failure.Message, StringComparison.Ordinal); + Assert.Contains("none", failure.Message, StringComparison.Ordinal); + } - Assert.Contains(failure.Errors, error => error.Pointer == "/providers/llm"); - Assert.Contains("exhaustive", failure.Message, StringComparison.Ordinal); - Assert.Contains("none", failure.Message, StringComparison.Ordinal); + [Fact] + public async Task AnEntryThatNamesNoEffort_StillCarriesTheStoreFlag() + { + MapSecretResolver secrets = new MapSecretResolver() + .With(OpenAiChatClientAdapter.ApiKeySecretName, "sk-not-a-real-key"); + + IChatClient client = await new OpenAiChatClientAdapter().CreateClientAsync( + new LlmProviderConfiguration + { + Kind = OpenAiChatClientAdapter.ProviderKind, + Model = "gpt-5.6-luna", + As = "reply", + }, + secrets, + TestContext.Current.CancellationToken); + + // A wrapped client answers GetService for the configuring middleware; a bare one does not. + Assert.NotNull(client.GetService(typeof(ConfigureOptionsChatClient))); + } } - [Fact] - public async Task AnEntryThatNamesNoEffort_StillCarriesTheStoreFlag() + /// + /// Which hosted markers openai resolves, and the operator's per-entry veto. + /// + public sealed class OpenAiHostedToolTests { - MapSecretResolver secrets = new MapSecretResolver() - .With(OpenAiChatClientAdapter.ApiKeySecretName, "sk-not-a-real-key"); - - var client = await new OpenAiChatClientAdapter().CreateClientAsync( - new LlmProviderConfiguration - { - Kind = OpenAiChatClientAdapter.ProviderKind, - Model = "gpt-5.6-luna", - As = "reply", - }, - secrets, - TestContext.Current.CancellationToken); - - // A wrapped client answers GetService for the configuring middleware; a bare one does not. - Assert.NotNull(client.GetService(typeof(ConfigureOptionsChatClient))); - } -} + [Fact] + public void ResolveHostedWebSearch_WithoutAVeto_ResolvesTheMarker() + { + OpenAiChatClientAdapter adapter = new(); + HostedWebSearchTool marker = new(); -/// -/// Which hosted markers openai resolves, and the operator's per-entry veto. -/// -public sealed class OpenAiHostedToolTests -{ - [Fact] - public void ResolveHostedWebSearch_WithoutAVeto_ResolvesTheMarker() - { - var adapter = new OpenAiChatClientAdapter(); - HostedWebSearchTool marker = new(); + Assert.Same(marker, adapter.ResolveHostedTool(marker, Entry(webSearch: null))); + } - Assert.Same(marker, adapter.ResolveHostedTool(marker, Entry(webSearch: null))); - } + [Fact] + public void ResolveHostedSearch_WithAVeto_AnswersNull() + { + OpenAiChatClientAdapter adapter = new(); - [Fact] - public void ResolveHostedSearch_WithAVeto_AnswersNull() - { - var adapter = new OpenAiChatClientAdapter(); + Assert.Null(adapter.ResolveHostedTool(new HostedWebSearchTool(), Entry(webSearch: false))); + } - Assert.Null(adapter.ResolveHostedTool(new HostedWebSearchTool(), Entry(webSearch: false))); - } + [Fact] + public void ResolveHostedTool_ForAnUnknownMarker_AnswersNull() + { + OpenAiChatClientAdapter adapter = new(); - [Fact] - public void ResolveHostedTool_ForAnUnknownMarker_AnswersNull() - { - var adapter = new OpenAiChatClientAdapter(); + Assert.Null(adapter.ResolveHostedTool(new HostedMcpServerTool("s", "https://example.com"), Entry(webSearch: null))); + } - Assert.Null(adapter.ResolveHostedTool(new HostedMcpServerTool("s", "https://example.com"), Entry(webSearch: null))); + private static LlmProviderConfiguration Entry(bool? webSearch) + { + return new() + { + Kind = OpenAiChatClientAdapter.ProviderKind, + Model = "m", + As = "reply", + WebSearch = webSearch, + }; + } } - - private static LlmProviderConfiguration Entry(bool? webSearch) => new() - { - Kind = OpenAiChatClientAdapter.ProviderKind, - Model = "m", - As = "reply", - WebSearch = webSearch, - }; } diff --git a/tests/AgentCore.Infrastructure.Tests/Secrets/SecretResolverTests.cs b/tests/AgentCore.Infrastructure.Tests/Secrets/SecretResolverTests.cs index 53eb2f17..0c42815f 100644 --- a/tests/AgentCore.Infrastructure.Tests/Secrets/SecretResolverTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Secrets/SecretResolverTests.cs @@ -3,180 +3,184 @@ using AgentCore.Infrastructure.Secrets; using Xunit; -namespace AgentCore.Infrastructure.Tests.Secrets; - -/// -/// The adapters behind , and the chain that orders them. -/// -/// -/// The chain is ordered and open: the host lists the links it wants, the first hit wins, and a new -/// store joins by adding a link. Nothing here claims a fixed number of steps. -/// -public sealed class SecretResolverTests +namespace AgentCore.Infrastructure.Tests.Secrets { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - // --------------------------------------------------------------------------------------------- - // The environment. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheEnvironmentResolver_ReadsTheNameTheDocumentWrote() + /// + /// The adapters behind , and the chain that orders them. + /// + /// + /// The chain is ordered and open: the host lists the links it wants, the first hit wins, and a new + /// store joins by adding a link. Nothing here claims a fixed number of steps. + /// + public sealed class SecretResolverTests { - EnvironmentSecretResolver resolver = new(name => name == "orders-api-key" ? "sk-1" : null); + private static CancellationToken Token => TestContext.Current.CancellationToken; - Assert.Equal("sk-1", await resolver.TryResolveAsync("orders-api-key", Token)); - } + // --------------------------------------------------------------------------------------------- + // The environment. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheEnvironmentResolver_ReadsTheNameTheDocumentWrote() + { + EnvironmentSecretResolver resolver = new(name => name == "orders-api-key" ? "sk-1" : null); - [Fact] - public async Task TheEnvironmentResolver_AlsoReadsTheShoutingForm() - { - // A shell variable is rarely called orders-api-key. The resolver tries the name first, then - // the ORDERS_API_KEY form every deployment already writes. - EnvironmentSecretResolver resolver = new(name => name == "ORDERS_API_KEY" ? "sk-2" : null); + Assert.Equal("sk-1", await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Equal("sk-2", await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheEnvironmentResolver_AlsoReadsTheShoutingForm() + { + // A shell variable is rarely called orders-api-key. The resolver tries the name first, then + // the ORDERS_API_KEY form every deployment already writes. + EnvironmentSecretResolver resolver = new(name => name == "ORDERS_API_KEY" ? "sk-2" : null); - [Fact] - public async Task TheEnvironmentResolver_AnswersNullForAnUnknownName() - { - EnvironmentSecretResolver resolver = new(_ => null); + Assert.Equal("sk-2", await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheEnvironmentResolver_AnswersNullForAnUnknownName() + { + EnvironmentSecretResolver resolver = new(_ => null); - [Fact] - public void TheEnvironmentVariableName_ShoutsAndReplacesEverySeparator() - { - Assert.Equal("ORDERS_API_KEY", EnvironmentSecretResolver.ToVariableName("orders-api-key")); - Assert.Equal("ORDERS_API_KEY", EnvironmentSecretResolver.ToVariableName("orders.api.key")); - Assert.Equal("ORDERS_API_KEY", EnvironmentSecretResolver.ToVariableName("orders/api/key")); - } + Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); + } - // --------------------------------------------------------------------------------------------- - // A directory of files, the /run/secrets convention. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheFileResolver_ReadsOneFilePerName() - { - using TemporaryDirectory directory = new(); - await File.WriteAllTextAsync(Path.Combine(directory.Path, "orders-api-key"), "sk-3\n", Token); + [Fact] + public void TheEnvironmentVariableName_ShoutsAndReplacesEverySeparator() + { + Assert.Equal("ORDERS_API_KEY", EnvironmentSecretResolver.ToVariableName("orders-api-key")); + Assert.Equal("ORDERS_API_KEY", EnvironmentSecretResolver.ToVariableName("orders.api.key")); + Assert.Equal("ORDERS_API_KEY", EnvironmentSecretResolver.ToVariableName("orders/api/key")); + } - FileSecretResolver resolver = new(directory.Path); + // --------------------------------------------------------------------------------------------- + // A directory of files, the /run/secrets convention. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheFileResolver_ReadsOneFilePerName() + { + using TemporaryDirectory directory = new(); + await File.WriteAllTextAsync(Path.Combine(directory.Path, "orders-api-key"), "sk-3\n", Token); - // The trailing newline an editor writes is not part of the credential. - Assert.Equal("sk-3", await resolver.TryResolveAsync("orders-api-key", Token)); - } + FileSecretResolver resolver = new(directory.Path); - [Fact] - public async Task TheFileResolver_AnswersNullWhenTheFileIsNotThere() - { - using TemporaryDirectory directory = new(); - FileSecretResolver resolver = new(directory.Path); + // The trailing newline an editor writes is not part of the credential. + Assert.Equal("sk-3", await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheFileResolver_AnswersNullWhenTheFileIsNotThere() + { + using TemporaryDirectory directory = new(); + FileSecretResolver resolver = new(directory.Path); - [Fact] - public async Task TheFileResolver_AnswersNullWhenTheDirectoryIsNotThere() - { - FileSecretResolver resolver = new(Path.Combine(Path.GetTempPath(), "agentcore-no-such-directory")); + Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheFileResolver_AnswersNullWhenTheDirectoryIsNotThere() + { + FileSecretResolver resolver = new(Path.Combine(Path.GetTempPath(), "agentcore-no-such-directory")); - [Theory] - [InlineData("../../../etc/passwd")] - [InlineData("nested/name")] - [InlineData("..")] - [InlineData("")] - public async Task TheFileResolver_ReadsNothingOutsideItsDirectory(string name) - { - using TemporaryDirectory directory = new(); - FileSecretResolver resolver = new(directory.Path); + Assert.Null(await resolver.TryResolveAsync("orders-api-key", Token)); + } - Assert.Null(await resolver.TryResolveAsync(name, Token)); - } + [Theory] + [InlineData("../../../etc/passwd")] + [InlineData("nested/name")] + [InlineData("..")] + [InlineData("")] + public async Task TheFileResolver_ReadsNothingOutsideItsDirectory(string name) + { + using TemporaryDirectory directory = new(); + FileSecretResolver resolver = new(directory.Path); - // --------------------------------------------------------------------------------------------- - // The chain. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheChain_TakesTheFirstHit() - { - ChainedSecretResolver chain = new( - [ - new EnvironmentSecretResolver(_ => null), - new EnvironmentSecretResolver(_ => "second"), - new EnvironmentSecretResolver(_ => "third"), - ]); - - Assert.Equal("second", await chain.TryResolveAsync("orders-api-key", Token)); - Assert.Equal(3, chain.Count); - } + Assert.Null(await resolver.TryResolveAsync(name, Token)); + } - [Fact] - public async Task TheChain_AnswersNullWhenNoLinkHoldsTheName() - { - ChainedSecretResolver chain = new([new EnvironmentSecretResolver(_ => null)]); + // --------------------------------------------------------------------------------------------- + // The chain. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheChain_TakesTheFirstHit() + { + ChainedSecretResolver chain = new( + [ + new EnvironmentSecretResolver(_ => null), + new EnvironmentSecretResolver(_ => "second"), + new EnvironmentSecretResolver(_ => "third"), + ]); + + Assert.Equal("second", await chain.TryResolveAsync("orders-api-key", Token)); + Assert.Equal(3, chain.Count); + } - Assert.Null(await chain.TryResolveAsync("orders-api-key", Token)); - } + [Fact] + public async Task TheChain_AnswersNullWhenNoLinkHoldsTheName() + { + ChainedSecretResolver chain = new([new EnvironmentSecretResolver(_ => null)]); - [Fact] - public async Task TheChain_TakesMoreLinksWithoutChanging() - { - // "Open to more links" is the whole design. A host that adds a vault adds a link. - using TemporaryDirectory directory = new(); - await File.WriteAllTextAsync(Path.Combine(directory.Path, "orders-api-key"), "from-file", Token); + Assert.Null(await chain.TryResolveAsync("orders-api-key", Token)); + } + + [Fact] + public async Task TheChain_TakesMoreLinksWithoutChanging() + { + // "Open to more links" is the whole design. A host that adds a vault adds a link. + using TemporaryDirectory directory = new(); + await File.WriteAllTextAsync(Path.Combine(directory.Path, "orders-api-key"), "from-file", Token); - ChainedSecretResolver chain = new( - [ - new EnvironmentSecretResolver(_ => null), - new FileSecretResolver(directory.Path), - ]); + ChainedSecretResolver chain = new( + [ + new EnvironmentSecretResolver(_ => null), + new FileSecretResolver(directory.Path), + ]); - Assert.Equal("from-file", await chain.TryResolveAsync("orders-api-key", Token)); - } + Assert.Equal("from-file", await chain.TryResolveAsync("orders-api-key", Token)); + } - [Fact] - public async Task TheChain_WithNoLink_AnswersNull() - { - ChainedSecretResolver chain = new([]); + [Fact] + public async Task TheChain_WithNoLink_AnswersNull() + { + ChainedSecretResolver chain = new([]); - Assert.Null(await chain.TryResolveAsync("orders-api-key", Token)); - } + Assert.Null(await chain.TryResolveAsync("orders-api-key", Token)); + } - // --------------------------------------------------------------------------------------------- - // The whole path, from the document to the header value. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AValueNeverReachesTheFailureMessage() - { - using TemporaryDirectory directory = new(); - await File.WriteAllTextAsync(Path.Combine(directory.Path, "known"), "sk-live-secret", Token); + // --------------------------------------------------------------------------------------------- + // The whole path, from the document to the header value. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AValueNeverReachesTheFailureMessage() + { + using TemporaryDirectory directory = new(); + await File.WriteAllTextAsync(Path.Combine(directory.Path, "known"), "sk-live-secret", Token); - ChainedSecretResolver chain = new([new FileSecretResolver(directory.Path)]); - var known = await chain.TryResolveAsync("known", Token); + ChainedSecretResolver chain = new([new FileSecretResolver(directory.Path)]); + string? known = await chain.TryResolveAsync("known", Token); - var failure = Assert.Throws( - () => ResolvedSecrets.Create([new KeyValuePair("known", known!)]) - .Format(Application.Configuration.Parsing.SecretTemplate.Parse("${secret:unknown}"))); + SecretResolutionException failure = Assert.Throws( + () => ResolvedSecrets.Create([new KeyValuePair("known", known!)]) + .Format(Application.Configuration.Parsing.SecretTemplate.Parse("${secret:unknown}"))); - Assert.DoesNotContain("sk-live-secret", failure.ToString(), StringComparison.Ordinal); - } + Assert.DoesNotContain("sk-live-secret", failure.ToString(), StringComparison.Ordinal); + } - /// A directory that deletes itself when the test ends. - private sealed class TemporaryDirectory : IDisposable - { - public TemporaryDirectory() + /// A directory that deletes itself when the test ends. + private sealed class TemporaryDirectory : IDisposable { - Path = System.IO.Path.Combine(System.IO.Path.GetTempPath(), "agentcore-" + Guid.NewGuid().ToString("N")); - Directory.CreateDirectory(Path); + public TemporaryDirectory() + { + Path = System.IO.Path.Combine(System.IO.Path.GetTempPath(), "agentcore-" + Guid.NewGuid().ToString("N")); + _ = Directory.CreateDirectory(Path); + } + + public string Path { get; } + + public void Dispose() + { + Directory.Delete(Path, recursive: true); + } } - - public string Path { get; } - - public void Dispose() => Directory.Delete(Path, recursive: true); } } diff --git a/tests/AgentCore.Infrastructure.Tests/Telemetry/GrafanaOtlpTelemetryAdapterTests.cs b/tests/AgentCore.Infrastructure.Tests/Telemetry/GrafanaOtlpTelemetryAdapterTests.cs index 7041d081..ae80cb9b 100644 --- a/tests/AgentCore.Infrastructure.Tests/Telemetry/GrafanaOtlpTelemetryAdapterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Telemetry/GrafanaOtlpTelemetryAdapterTests.cs @@ -1,89 +1,90 @@ using AgentCore.Infrastructure.Telemetry.Grafana; using Xunit; -namespace AgentCore.Infrastructure.Tests.Telemetry; - -/// -/// The two things about the Grafana Cloud OTLP gateway that fail silently when they are wrong. -/// -/// -/// -/// Grafana Cloud offers two ways in. The native path gives Loki, Tempo, and Mimir an endpoint and a -/// numeric user id each, so three credentials. The OTLP gateway takes all three signals at one URL -/// under one basic credential, where the instance id is the user and the access policy token is the -/// password, and fans them out on its side. This adapter uses the gateway, which is why -/// KnownSecrets holds one pair and not three. -/// -/// -/// The gateway then wants a signal path under that one URL, and the OpenTelemetry .NET exporter -/// stops appending one the moment the endpoint is assigned in code. It is a rejection at the -/// collector rather than an exception here, so nothing in the process reports it. These tests are -/// the report. -/// -/// -public sealed class GrafanaOtlpTelemetryAdapterTests +namespace AgentCore.Infrastructure.Tests.Telemetry { - private const string Gateway = "https://otlp-gateway-prod-us-east-0.grafana.net/otlp"; - - [Fact] - public void EachSignal_GetsItsOwnPathUnderTheGatewayRoot() + /// + /// The two things about the Grafana Cloud OTLP gateway that fail silently when they are wrong. + /// + /// + /// + /// Grafana Cloud offers two ways in. The native path gives Loki, Tempo, and Mimir an endpoint and a + /// numeric user id each, so three credentials. The OTLP gateway takes all three signals at one URL + /// under one basic credential, where the instance id is the user and the access policy token is the + /// password, and fans them out on its side. This adapter uses the gateway, which is why + /// KnownSecrets holds one pair and not three. + /// + /// + /// The gateway then wants a signal path under that one URL, and the OpenTelemetry .NET exporter + /// stops appending one the moment the endpoint is assigned in code. It is a rejection at the + /// collector rather than an exception here, so nothing in the process reports it. These tests are + /// the report. + /// + /// + public sealed class GrafanaOtlpTelemetryAdapterTests { - Assert.Equal( - Gateway + "/v1/traces", - GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.TracesPath)); + private const string Gateway = "https://otlp-gateway-prod-us-east-0.grafana.net/otlp"; - Assert.Equal( - Gateway + "/v1/metrics", - GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.MetricsPath)); + [Fact] + public void EachSignal_GetsItsOwnPathUnderTheGatewayRoot() + { + Assert.Equal( + Gateway + "/v1/traces", + GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.TracesPath)); - Assert.Equal( - Gateway + "/v1/logs", - GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.LogsPath)); - } + Assert.Equal( + Gateway + "/v1/metrics", + GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.MetricsPath)); - [Fact] - public void ThreeSignals_NeverShareOneUrl() - { - // The failure this guards is one signal's data arriving at another's ingest path. The - // gateway answers that with a rejection and the process carries on, so a shared URL would - // look exactly like working telemetry from inside the host. - var traces = GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.TracesPath); - var metrics = GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.MetricsPath); - var logs = GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.LogsPath); + Assert.Equal( + Gateway + "/v1/logs", + GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.LogsPath)); + } - Assert.Equal(3, new HashSet([traces, metrics, logs], StringComparer.Ordinal).Count); - } + [Fact] + public void ThreeSignals_NeverShareOneUrl() + { + // The failure this guards is one signal's data arriving at another's ingest path. The + // gateway answers that with a rejection and the process carries on, so a shared URL would + // look exactly like working telemetry from inside the host. + string traces = GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.TracesPath); + string metrics = GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.MetricsPath); + string logs = GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway, GrafanaOtlpTelemetryAdapter.LogsPath); - [Fact] - public void ATrailingSlash_DoesNotDoubleUp() - { - // The console prints the endpoint without a trailing slash and a human pastes it with one. - Assert.Equal( - Gateway + "/v1/traces", - GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway + "/", GrafanaOtlpTelemetryAdapter.TracesPath)); - } + Assert.Equal(3, new HashSet([traces, metrics, logs], StringComparer.Ordinal).Count); + } - [Fact] - public void AnEndpointThatAlreadyNamesItsSignal_IsTakenAtItsWord() - { - // A deployment reading the OpenTelemetry docs rather than the Grafana ones writes the whole - // path. Appending a second copy would post to /v1/traces/v1/traces. - Assert.Equal( - Gateway + "/v1/traces", - GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway + "/v1/traces", GrafanaOtlpTelemetryAdapter.TracesPath)); - } + [Fact] + public void ATrailingSlash_DoesNotDoubleUp() + { + // The console prints the endpoint without a trailing slash and a human pastes it with one. + Assert.Equal( + Gateway + "/v1/traces", + GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway + "/", GrafanaOtlpTelemetryAdapter.TracesPath)); + } - [Fact] - public void EverySignalPath_IsRootedSoItJoinsCleanly() - { - foreach (var path in new[] + [Fact] + public void AnEndpointThatAlreadyNamesItsSignal_IsTakenAtItsWord() { - GrafanaOtlpTelemetryAdapter.TracesPath, - GrafanaOtlpTelemetryAdapter.MetricsPath, - GrafanaOtlpTelemetryAdapter.LogsPath, - }) + // A deployment reading the OpenTelemetry docs rather than the Grafana ones writes the whole + // path. Appending a second copy would post to /v1/traces/v1/traces. + Assert.Equal( + Gateway + "/v1/traces", + GrafanaOtlpTelemetryAdapter.SignalEndpoint(Gateway + "/v1/traces", GrafanaOtlpTelemetryAdapter.TracesPath)); + } + + [Fact] + public void EverySignalPath_IsRootedSoItJoinsCleanly() { - Assert.StartsWith("/", path, StringComparison.Ordinal); + foreach (string? path in new[] + { + GrafanaOtlpTelemetryAdapter.TracesPath, + GrafanaOtlpTelemetryAdapter.MetricsPath, + GrafanaOtlpTelemetryAdapter.LogsPath, + }) + { + Assert.StartsWith("/", path, StringComparison.Ordinal); + } } } } diff --git a/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs b/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs index 362f69a3..db1d20f0 100644 --- a/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/ToolSeamTests.cs @@ -7,9 +7,7 @@ using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Ports; using AgentCore.Application.Secrets; -using AgentCore.Application.Tools; using AgentCore.Application.Tools.Builtin; using AgentCore.Infrastructure.Secrets; using AgentCore.Infrastructure.Tests.Tools; @@ -17,20 +15,20 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Infrastructure.Tests; - -/// -/// The whole seam, from the document to the conversation: secrets, then tools, then the compile table. -/// -/// -/// The worked example of section 8.1 declares all four tool kinds. This test walks the three that -/// need a source, in the order a host starts them: resolve every ${secret:name} once, build -/// the sources over the resolved values, then compile. -/// -public sealed class ToolSeamTests +namespace AgentCore.Infrastructure.Tests { - private const string Yaml = - """ + /// + /// The whole seam, from the document to the conversation: secrets, then tools, then the compile table. + /// + /// + /// The worked example of section 8.1 declares all four tool kinds. This test walks the three that + /// need a source, in the order a host starts them: resolve every ${secret:name} once, build + /// the sources over the resolved values, then compile. + /// + public sealed class ToolSeamTests + { + private const string Yaml = + """ apiVersion: agentcore/v1 tools: - id: lookup_order @@ -72,85 +70,86 @@ public sealed class ToolSeamTests tts: { kind: telnyx-relay } """; - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task TheWorkedExample_CompilesWithEveryToolBound() - { - var document = ConfigurationLoader.LoadYaml(Yaml); - - // Step one: resolve every reference the document holds, once. - ChainedSecretResolver chain = new([new EnvironmentSecretResolver(_ => "sk-live-0123456789")]); - var secrets = await ResolvedSecrets.ResolveAsync(document, chain, Token); - - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, """{"status":"shipped"}"""); - using HttpClient client = new(handler); - - ToolBindingRegistry bindings = new(); - bindings.Register("CreateCase", (arguments, cancellationToken) - => ValueTask.FromResult(JsonNode.Parse("""{"caseId":"C-1"}"""))); - - // Step two: build the sources over the resolved values. - var registry = await ToolRegistryBuilder.BuildAsync( - [ - new BuiltinToolSource(new BuiltinToolPorts(null)), - new HttpToolSource(client, secrets), - new BindingToolSource(bindings), - ], - new ToolSourceContext(document), Token); - - // Step three: compile. - using OneReplyChatClient model = new("done"); - var compiled = ConfigurationCompiler.CompileAll( - document, - new AgentCompilationContext(new RecordingChatClientFactory(model)) { Tools = registry })["main"]; - - Assert.Equal(3, compiled.Agents.Count); - - // The HTTP tool now makes its call. Before this seam existed it could not. - var lookup = Assert.IsType(registry.Resolve("lookup_order"), exactMatch: false); - - var result = await lookup.InvokeAsync( - new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) { ["orderId"] = "A-42" }), - Token); - - Assert.Equal("shipped", Assert.IsType(result)["status"]!.GetValue()); - Assert.Equal( - "Bearer sk-live-0123456789", - handler.Requests[0].Headers.GetValues("Authorization").Single()); - } - - /// An offline model that answers one line and calls no tool. - private sealed class OneReplyChatClient : IChatClient - { - private readonly string _reply; - - public OneReplyChatClient(string reply) => _reply = reply; - - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - yield return new ChatResponseUpdate(ChatRole.Assistant, _reply); - } - - public Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - => Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); - - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } - - public void Dispose() - { - // Nothing to release. - } - } - } + private static CancellationToken Token => TestContext.Current.CancellationToken; + + [Fact] + public async Task TheWorkedExample_CompilesWithEveryToolBound() + { + AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); + + // Step one: resolve every reference the document holds, once. + ChainedSecretResolver chain = new([new EnvironmentSecretResolver(_ => "sk-live-0123456789")]); + ResolvedSecrets secrets = await ResolvedSecrets.ResolveAsync(document, chain, Token); + + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, /*lang=json,strict*/ """{"status":"shipped"}"""); + using HttpClient client = new(handler); + + ToolBindingRegistry bindings = new(); + _ = bindings.Register("CreateCase", (arguments, cancellationToken) + => ValueTask.FromResult(JsonNode.Parse("""{"caseId":"C-1"}"""))); + + // Step two: build the sources over the resolved values. + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [ + new BuiltinToolSource(new BuiltinToolPorts(null)), + new HttpToolSource(client, secrets), + new BindingToolSource(bindings), + ], + new ToolSourceContext(document), Token); + + // Step three: compile. + using OneReplyChatClient model = new("done"); + CompiledAgent compiled = ConfigurationCompiler.CompileAll( + document, + new AgentCompilationContext(new RecordingChatClientFactory(model)) { Tools = registry })["main"]; + + Assert.Equal(3, compiled.Agents.Count); + + // The HTTP tool now makes its call. Before this seam existed it could not. + AIFunction lookup = Assert.IsType(registry.Resolve("lookup_order"), exactMatch: false); + + object? result = await lookup.InvokeAsync( + new AIFunctionArguments(new Dictionary(StringComparer.Ordinal) { ["orderId"] = "A-42" }), + Token); + + Assert.Equal("shipped", Assert.IsType(result)["status"]!.GetValue()); + Assert.Equal( + "Bearer sk-live-0123456789", + handler.Requests[0].Headers.GetValues("Authorization").Single()); + } + + /// An offline model that answers one line and calls no tool. + private sealed class OneReplyChatClient(string reply) : IChatClient + { + private readonly string _reply = reply; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + await Task.Yield(); + yield return new ChatResponseUpdate(ChatRole.Assistant, _reply); + } + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } + + public void Dispose() + { + // Nothing to release. + } + } + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/ControllableMcpServer.cs b/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/ControllableMcpServer.cs index ac8b920d..63b4510b 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/ControllableMcpServer.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/ControllableMcpServer.cs @@ -5,218 +5,220 @@ using ModelContextProtocol.Protocol; using ModelContextProtocol.Server; -namespace AgentCore.Infrastructure.Tests.Tools.Fakes; - -/// -/// A real MCP server that can be made to misbehave, one connection at a time. -/// -/// -/// answers one connection and never changes. The session tests need -/// the opposite: a server that refuses the first attempts, that dies between two conversations, and that -/// withdraws a tool it had offered. Each is a fresh pipe pair and a fresh -/// , which is what a real reconnect gets. -/// -internal sealed class ControllableMcpServer : IAsyncDisposable +namespace AgentCore.Infrastructure.Tests.Tools.Fakes { - private readonly List _servers = []; - - private readonly Lock _sync = new(); + /// + /// A real MCP server that can be made to misbehave, one connection at a time. + /// + /// + /// answers one connection and never changes. The session tests need + /// the opposite: a server that refuses the first attempts, that dies between two conversations, and that + /// withdraws a tool it had offered. Each is a fresh pipe pair and a fresh + /// , which is what a real reconnect gets. + /// + /// Starts a server offering the tools named. + /// The tools tools/list reports. + internal sealed class ControllableMcpServer(params string[] toolNames) : IAsyncDisposable + { + private readonly List _servers = []; - private List _tools; + private readonly Lock _sync = new(); - /// One connection: the server, and the pipes a dead process would close behind it. - private sealed record Connection(McpServer Server, Pipe ClientToServer, Pipe ServerToClient); + private List _tools = [.. toolNames]; - /// Starts a server offering the tools named. - /// The tools tools/list reports. - public ControllableMcpServer(params string[] toolNames) => _tools = [.. toolNames]; + /// One connection: the server, and the pipes a dead process would close behind it. + private sealed record Connection(McpServer Server, Pipe ClientToServer, Pipe ServerToClient); - /// Gets how many connections have been opened against this server. - public int ConnectionsOpened { get; private set; } + /// Gets how many connections have been opened against this server. + public int ConnectionsOpened { get; private set; } - /// Gets or sets how long a tool call takes before it answers. - public TimeSpan CallDelay { get; set; } - /// - /// Gets or sets whether tools/list fails, so a connection opens and then goes no further. - /// - public bool RefuseToList { get; set; } + /// Gets or sets how long a tool call takes before it answers. + public TimeSpan CallDelay { get; set; } + /// + /// Gets or sets whether tools/list fails, so a connection opens and then goes no further. + /// + public bool RefuseToList { get; set; } - /// Gets the argument names the newest conversation carried, in order. - public IReadOnlyList LastArgumentNames { get; private set; } = []; + /// Gets the argument names the newest conversation carried, in order. + public IReadOnlyList LastArgumentNames { get; private set; } = []; - /// - /// Gets or sets the one string property every offered tool declares, or - /// for tools with no schema at all. - /// - public string? SchemaProperty { get; set; } + /// + /// Gets or sets the one string property every offered tool declares, or + /// for tools with no schema at all. + /// + public string? SchemaProperty { get; set; } - /// Gets the description this server gives a tool of one name. - /// The tool name. - /// The description. - public static string DescriptionOf(string toolName) => $"The '{toolName}' tool."; + /// Gets the description this server gives a tool of one name. + /// The tool name. + /// The description. + public static string DescriptionOf(string toolName) + { + return $"The '{toolName}' tool."; + } - /// Opens a fresh transport, backed by a fresh server. - /// The transport a client connects through. - public IClientTransport NewTransport() - { - Pipe clientToServer = new(); - Pipe serverToClient = new(); + /// Opens a fresh transport, backed by a fresh server. + /// The transport a client connects through. + public IClientTransport NewTransport() + { + Pipe clientToServer = new(); + Pipe serverToClient = new(); - McpServerOptions options = new(); - options.Handlers.ListToolsHandler = (_, _) => RefuseToList - ? throw new InvalidOperationException("this server will not say what it offers") - : ValueTask.FromResult(new ListToolsResult - { - Tools = [.. Offered().Select(name => + McpServerOptions options = new(); + options.Handlers.ListToolsHandler = (_, _) => RefuseToList + ? throw new InvalidOperationException("this server will not say what it offers") + : ValueTask.FromResult(new ListToolsResult { - var tool = new Tool { Name = name, Description = DescriptionOf(name) }; - if (SchemaProperty is not null) + Tools = [.. Offered().Select(name => { - tool.InputSchema = SchemaOf(); - } + Tool tool = new() { Name = name, Description = DescriptionOf(name) }; + if (SchemaProperty is not null) + { + tool.InputSchema = SchemaOf(); + } - return tool; - })], - }); + return tool; + })], + }); - options.Handlers.CallToolHandler = async (request, ct) => - { - if (CallDelay > TimeSpan.Zero) + options.Handlers.CallToolHandler = async (request, ct) => { - await Task.Delay(CallDelay, ct); - } + if (CallDelay > TimeSpan.Zero) + { + await Task.Delay(CallDelay, ct); + } + + lock (_sync) + { + LastArgumentNames = request.Params?.Arguments is { } supplied + ? [.. supplied.Keys] + : []; + } + + return new CallToolResult { Content = [new TextContentBlock { Text = $"ran {request.Params?.Name}" }] }; + }; + + McpServer server = McpServer.Create( + new StreamServerTransport(clientToServer.Reader.AsStream(), serverToClient.Writer.AsStream()), + options); + + _ = server.RunAsync(); lock (_sync) { - LastArgumentNames = request.Params?.Arguments is { } supplied - ? [.. supplied.Keys] - : []; + _servers.Add(new Connection(server, clientToServer, serverToClient)); + ConnectionsOpened++; } - return new CallToolResult { Content = [new TextContentBlock { Text = $"ran {request.Params?.Name}" }] }; - }; - - var server = McpServer.Create( - new StreamServerTransport(clientToServer.Reader.AsStream(), serverToClient.Writer.AsStream()), - options); - - _ = server.RunAsync(); + return new StreamClientTransport(clientToServer.Writer.AsStream(), serverToClient.Reader.AsStream()); + } - lock (_sync) + /// Builds the schema every offered tool lists, when one was asked for. + private JsonElement SchemaOf() { - _servers.Add(new Connection(server, clientToServer, serverToClient)); - ConnectionsOpened++; - } + if (SchemaProperty is null) + { + return default; + } - return new StreamClientTransport(clientToServer.Writer.AsStream(), serverToClient.Reader.AsStream()); - } + JsonObject schema = new() + { + ["type"] = "object", + ["properties"] = new JsonObject + { + [SchemaProperty] = new JsonObject { ["type"] = "string" }, + }, + }; - /// Builds the schema every offered tool lists, when one was asked for. - private JsonElement SchemaOf() - { - if (SchemaProperty is null) + return JsonSerializer.SerializeToElement(schema); + } + /// Stops offering one tool, without telling anybody. + /// The tool to withdraw. + public void Withdraw(string toolName) { - return default; + lock (_sync) + { + _tools = [.. _tools.Where(name => name != toolName)]; + } } - JsonObject schema = new() + /// Tells every open connection that the tool list has changed. + /// Cancels the send. + public async ValueTask AnnounceToolChangeAsync(CancellationToken cancellationToken) { - ["type"] = "object", - ["properties"] = new JsonObject + Connection[] open; + lock (_sync) { - [SchemaProperty] = new JsonObject { ["type"] = "string" }, - }, - }; + open = [.. _servers]; + } - return JsonSerializer.SerializeToElement(schema); - } - /// Stops offering one tool, without telling anybody. - /// The tool to withdraw. - public void Withdraw(string toolName) - { - lock (_sync) - { - _tools = [.. _tools.Where(name => name != toolName)]; + foreach (Connection connection in open) + { + await connection.Server.SendNotificationAsync( + NotificationMethods.ToolListChangedNotification, cancellationToken); + } } - } - /// Tells every open connection that the tool list has changed. - /// Cancels the send. - public async ValueTask AnnounceToolChangeAsync(CancellationToken cancellationToken) - { - Connection[] open; - lock (_sync) + /// Drops the newest connection, as a crashed child process would. + public async ValueTask KillNewestConnectionAsync() { - open = [.. _servers]; - } + Connection newest; + lock (_sync) + { + newest = _servers[^1]; + _servers.RemoveAt(_servers.Count - 1); + } - foreach (var connection in open) - { - await connection.Server.SendNotificationAsync( - NotificationMethods.ToolListChangedNotification, cancellationToken); + await CloseAsync(newest); } - } - /// Drops the newest connection, as a crashed child process would. - public async ValueTask KillNewestConnectionAsync() - { - Connection newest; - lock (_sync) + /// + public async ValueTask DisposeAsync() { - newest = _servers[^1]; - _servers.RemoveAt(_servers.Count - 1); - } - - await CloseAsync(newest); - } + Connection[] open; + lock (_sync) + { + open = [.. _servers]; + _servers.Clear(); + } - /// - public async ValueTask DisposeAsync() - { - Connection[] open; - lock (_sync) - { - open = [.. _servers]; - _servers.Clear(); + foreach (Connection connection in open) + { + await CloseAsync(connection); + } } - foreach (var connection in open) + /// + /// Closes one connection the way the operating system closes a dead process's: the pipes end, + /// not just the server object. + /// + /// + /// Disposing the alone leaves both pipes open, so the client never reads + /// end-of-stream and its session never completes — it simply waits forever for a reply that is + /// not coming. A real child process cannot leave its handles open after it dies, and a fake that + /// does hides exactly the failure these tests exist to catch. + /// + private static async ValueTask CloseAsync(Connection connection) { - await CloseAsync(connection); - } - } + try + { + await connection.Server.DisposeAsync(); + } + catch + { + } - /// - /// Closes one connection the way the operating system closes a dead process's: the pipes end, - /// not just the server object. - /// - /// - /// Disposing the alone leaves both pipes open, so the client never reads - /// end-of-stream and its session never completes — it simply waits forever for a reply that is - /// not coming. A real child process cannot leave its handles open after it dies, and a fake that - /// does hides exactly the failure these tests exist to catch. - /// - private static async ValueTask CloseAsync(Connection connection) - { - try - { - await connection.Server.DisposeAsync(); + await connection.ServerToClient.Writer.CompleteAsync(); + await connection.ServerToClient.Reader.CompleteAsync(); + await connection.ClientToServer.Writer.CompleteAsync(); + await connection.ClientToServer.Reader.CompleteAsync(); } - catch - { - } - - await connection.ServerToClient.Writer.CompleteAsync(); - await connection.ServerToClient.Reader.CompleteAsync(); - await connection.ClientToServer.Writer.CompleteAsync(); - await connection.ClientToServer.Reader.CompleteAsync(); - } - private List Offered() - { - lock (_sync) + private List Offered() { - return _tools; + lock (_sync) + { + return _tools; + } } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/InProcessMcpServer.cs b/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/InProcessMcpServer.cs index 698e1045..09a34b94 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/InProcessMcpServer.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/Fakes/InProcessMcpServer.cs @@ -4,90 +4,101 @@ using ModelContextProtocol.Protocol; using ModelContextProtocol.Server; -namespace AgentCore.Infrastructure.Tests.Tools.Fakes; - -/// -/// A real MCP server, wired to a real MCP client over two in-process pipes. -/// -/// -/// McpToolSourceTests needs the real protocol — real initialization, capability negotiation, -/// and tools/list — without launching a child process. This wires -/// to over two -/// s, so nothing here is a stub of the wire format. -/// -internal sealed class InProcessMcpServer : IAsyncDisposable +namespace AgentCore.Infrastructure.Tests.Tools.Fakes { - private readonly McpServer _server; - - /// Starts a server offering one tool per name given, each with a fixed description. - /// The tools the server lists. - public InProcessMcpServer(params string[] toolNames) - : this([.. toolNames.Select(name => (name, (string?)DescriptionOf(name)))]) - { - } - - /// Starts a server offering exactly the tools given, each with its own description. - /// - /// Each tool's name and description. A description is never sent at all — - /// MCP makes it optional — which is how reproduces a - /// server that describes nothing. - /// - /// - /// A tool name to list a second time through , or - /// for none. itself refuses - /// two tools of one name, so this is the only route left to reproduce a server whose - /// tools/list answer repeats a name — uses it. - /// - private InProcessMcpServer(IReadOnlyList<(string Name, string? Description)> tools, string? duplicateToolName = null) + /// + /// A real MCP server, wired to a real MCP client over two in-process pipes. + /// + /// + /// McpToolSourceTests needs the real protocol — real initialization, capability negotiation, + /// and tools/list — without launching a child process. This wires + /// to over two + /// s, so nothing here is a stub of the wire format. + /// + internal sealed class InProcessMcpServer : IAsyncDisposable { - var clientToServer = new Pipe(); - var serverToClient = new Pipe(); - - var serverTransport = new StreamServerTransport( - clientToServer.Reader.AsStream(), serverToClient.Writer.AsStream()); + private readonly McpServer _server; - var options = new McpServerOptions { ToolCollection = [] }; - foreach (var (name, description) in tools) + /// Starts a server offering one tool per name given, each with a fixed description. + /// The tools the server lists. + public InProcessMcpServer(params string[] toolNames) + : this([.. toolNames.Select(name => (name, (string?)DescriptionOf(name)))]) { - options.ToolCollection.Add(McpServerTool.Create( - AIFunctionFactory.Create(() => "ok", name, description))); } - if (duplicateToolName is not null) + /// Starts a server offering exactly the tools given, each with its own description. + /// + /// Each tool's name and description. A description is never sent at all — + /// MCP makes it optional — which is how reproduces a + /// server that describes nothing. + /// + /// + /// A tool name to list a second time through , or + /// for none. itself refuses + /// two tools of one name, so this is the only route left to reproduce a server whose + /// tools/list answer repeats a name — uses it. + /// + private InProcessMcpServer(IReadOnlyList<(string Name, string? Description)> tools, string? duplicateToolName = null) { - options.Handlers.ListToolsHandler = (_, _) => ValueTask.FromResult(new ListToolsResult + Pipe clientToServer = new(); + Pipe serverToClient = new(); + + StreamServerTransport serverTransport = new( + clientToServer.Reader.AsStream(), serverToClient.Writer.AsStream()); + + McpServerOptions options = new() { ToolCollection = [] }; + foreach ((string? name, string? description) in tools) { - Tools = [new Tool { Name = duplicateToolName, Description = DescriptionOf(duplicateToolName) }], - }); - } + options.ToolCollection.Add(McpServerTool.Create( + AIFunctionFactory.Create(() => "ok", name, description))); + } - _server = McpServer.Create(serverTransport, options); - _ = _server.RunAsync(); + if (duplicateToolName is not null) + { + options.Handlers.ListToolsHandler = (_, _) => ValueTask.FromResult(new ListToolsResult + { + Tools = [new Tool { Name = duplicateToolName, Description = DescriptionOf(duplicateToolName) }], + }); + } - ClientTransport = new StreamClientTransport( - clientToServer.Writer.AsStream(), serverToClient.Reader.AsStream()); - } + _server = McpServer.Create(serverTransport, options); + _ = _server.RunAsync(); - /// Gets the description gives a tool of this name. - /// The tool name. - /// The description the server reports for it. - public static string DescriptionOf(string toolName) => $"The '{toolName}' tool."; + ClientTransport = new StreamClientTransport( + clientToServer.Writer.AsStream(), serverToClient.Reader.AsStream()); + } - /// Starts a server offering one tool that carries no description at all. - /// The tool's name. - /// The server. - public static InProcessMcpServer OfferingAToolWithNoDescription(string toolName) - => new([(toolName, null)]); + /// Gets the description gives a tool of this name. + /// The tool name. + /// The description the server reports for it. + public static string DescriptionOf(string toolName) + { + return $"The '{toolName}' tool."; + } - /// Starts a server whose tools/list response lists one tool name twice. - /// The name every listed tool shares. - /// The server. - public static InProcessMcpServer OfferingTheSameToolNameTwice(string toolName) - => new([(toolName, DescriptionOf(toolName))], toolName); + /// Starts a server offering one tool that carries no description at all. + /// The tool's name. + /// The server. + public static InProcessMcpServer OfferingAToolWithNoDescription(string toolName) + { + return new([(toolName, null)]); + } - /// Gets the transport a client connects through to reach this server. - public IClientTransport ClientTransport { get; } + /// Starts a server whose tools/list response lists one tool name twice. + /// The name every listed tool shares. + /// The server. + public static InProcessMcpServer OfferingTheSameToolNameTwice(string toolName) + { + return new([(toolName, DescriptionOf(toolName))], toolName); + } + + /// Gets the transport a client connects through to reach this server. + public IClientTransport ClientTransport { get; } - /// - public async ValueTask DisposeAsync() => await _server.DisposeAsync().ConfigureAwait(false); + /// + public async ValueTask DisposeAsync() + { + await _server.DisposeAsync().ConfigureAwait(false); + } + } } diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/HttpToolSourceTests.cs b/tests/AgentCore.Infrastructure.Tests/Tools/HttpToolSourceTests.cs index 4cc00b10..34f84d26 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/HttpToolSourceTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/HttpToolSourceTests.cs @@ -9,299 +9,301 @@ using Microsoft.Extensions.AI; using Xunit; -namespace AgentCore.Infrastructure.Tests.Tools; - -/// -/// The second tool kind of section 8.1: kind: http, which makes one call. -/// -/// -/// The worked example declares lookup_order. The URL holds a {orderId} placeholder the -/// arguments fill, and the header holds a ${secret:orders-api-key} reference that startup -/// already resolved. -/// -public sealed class HttpToolSourceTests +namespace AgentCore.Infrastructure.Tests.Tools { - private const string SecretName = "orders-api-key"; - private const string SecretValue = "sk-live-0123456789"; - - private static readonly ToolConfiguration LookupOrder = new() + /// + /// The second tool kind of section 8.1: kind: http, which makes one call. + /// + /// + /// The worked example declares lookup_order. The URL holds a {orderId} placeholder the + /// arguments fill, and the header holds a ${secret:orders-api-key} reference that startup + /// already resolved. + /// + public sealed class HttpToolSourceTests { - Id = "lookup_order", - Kind = ToolKind.Http, - Description = "Read one order by its identifier.", - Parameters = JsonNode.Parse("""{"type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"]}"""), - Request = new HttpRequestConfiguration + private const string SecretName = "orders-api-key"; + private const string SecretValue = "sk-live-0123456789"; + + private static readonly ToolConfiguration LookupOrder = new() { - Method = "GET", - Url = "https://api.example.com/orders/{orderId}", - Headers = new Dictionary(StringComparer.Ordinal) + Id = "lookup_order", + Kind = ToolKind.Http, + Description = "Read one order by its identifier.", + Parameters = JsonNode.Parse("""{"type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"]}"""), + Request = new HttpRequestConfiguration { - ["Authorization"] = SecretTemplate.Parse("Bearer ${secret:orders-api-key}"), + Method = "GET", + Url = "https://api.example.com/orders/{orderId}", + Headers = new Dictionary(StringComparer.Ordinal) + { + ["Authorization"] = SecretTemplate.Parse("Bearer ${secret:orders-api-key}"), + }, }, - }, - }; + }; - private static CancellationToken Token => TestContext.Current.CancellationToken; + private static CancellationToken Token => TestContext.Current.CancellationToken; - // --------------------------------------------------------------------------------------------- - // What the model reads. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task TheDeclaredSchema_ReachesTheModelUnchanged() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); - using HttpClient client = new(handler); + // --------------------------------------------------------------------------------------------- + // What the model reads. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheDeclaredSchema_ReachesTheModelUnchanged() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); + using HttpClient client = new(handler); - var function = Assert.IsType(await CreateAsync(client, LookupOrder), exactMatch: false); + AIFunction function = Assert.IsType(await CreateAsync(client, LookupOrder), exactMatch: false); - Assert.Equal("lookup_order", function.Name); - Assert.Equal("Read one order by its identifier.", function.Description); - Assert.True(JsonNode.DeepEquals(LookupOrder.Parameters, JsonNode.Parse(function.JsonSchema.GetRawText()))); - } + Assert.Equal("lookup_order", function.Name); + Assert.Equal("Read one order by its identifier.", function.Description); + Assert.True(JsonNode.DeepEquals(LookupOrder.Parameters, JsonNode.Parse(function.JsonSchema.GetRawText()))); + } - // --------------------------------------------------------------------------------------------- - // The conversation. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task ThePlaceholderTakesItsValueFromTheArguments() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, """{"status":"shipped"}"""); - using HttpClient client = new(handler); + // --------------------------------------------------------------------------------------------- + // The conversation. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ThePlaceholderTakesItsValueFromTheArguments() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, /*lang=json,strict*/ """{"status":"shipped"}"""); + using HttpClient client = new(handler); - var result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); + object? result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); - Assert.Equal(new Uri("https://api.example.com/orders/A-42"), Assert.Single(handler.Requests).RequestUri); - Assert.Equal(HttpMethod.Get, handler.Requests[0].Method); + Assert.Equal(new Uri("https://api.example.com/orders/A-42"), Assert.Single(handler.Requests).RequestUri); + Assert.Equal(HttpMethod.Get, handler.Requests[0].Method); - // The state layer reads lookup_order.status out of this, so the body stays a node tree. - Assert.Equal("shipped", Assert.IsType(result)["status"]!.GetValue()); - } + // The state layer reads lookup_order.status out of this, so the body stays a node tree. + Assert.Equal("shipped", Assert.IsType(result)["status"]!.GetValue()); + } - [Fact] - public async Task APlaceholderValueIsEscaped() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); - using HttpClient client = new(handler); + [Fact] + public async Task APlaceholderValueIsEscaped() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); + using HttpClient client = new(handler); - await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "a/../b c")); + _ = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "a/../b c")); - Assert.Equal( - "https://api.example.com/orders/a%2F..%2Fb%20c", - handler.Requests[0].RequestUri!.OriginalString); - } + Assert.Equal( + "https://api.example.com/orders/a%2F..%2Fb%20c", + handler.Requests[0].RequestUri!.OriginalString); + } - [Fact] - public async Task TheResolvedHeaderReachesTheRequest() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); - using HttpClient client = new(handler); + [Fact] + public async Task TheResolvedHeaderReachesTheRequest() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); + using HttpClient client = new(handler); - await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); + _ = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); - Assert.Equal( - "Bearer " + SecretValue, - Assert.Single(handler.Requests).Headers.GetValues("Authorization").Single()); - } + Assert.Equal( + "Bearer " + SecretValue, + Assert.Single(handler.Requests).Headers.GetValues("Authorization").Single()); + } - [Fact] - public async Task ABodyThatIsNotJson_ComesBackAsText() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "shipped", "text/plain"); - using HttpClient client = new(handler); + [Fact] + public async Task ABodyThatIsNotJson_ComesBackAsText() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "shipped", "text/plain"); + using HttpClient client = new(handler); - var result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); + object? result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); - // The framework carries every tool result as a JSON node, so a text body arrives as a string - // value rather than as an object the model would have to unwrap. - Assert.Equal("shipped", Assert.IsType(result, exactMatch: false).GetValue()); - } + // The framework carries every tool result as a JSON node, so a text body arrives as a string + // value rather than as an object the model would have to unwrap. + Assert.Equal("shipped", Assert.IsType(result, exactMatch: false).GetValue()); + } - // --------------------------------------------------------------------------------------------- - // Section 8.7: a tool returns an error result and does not throw. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AFiveHundred_BecomesAnErrorResult() - { - using var handler = StubHttpMessageHandler.Answering( - HttpStatusCode.InternalServerError, - """{"detail":"the order service is down"}"""); - using HttpClient client = new(handler); + // --------------------------------------------------------------------------------------------- + // Section 8.7: a tool returns an error result and does not throw. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AFiveHundred_BecomesAnErrorResult() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering( + HttpStatusCode.InternalServerError, + /*lang=json,strict*/ + """{"detail":"the order service is down"}"""); + using HttpClient client = new(handler); - var result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); + object? result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); - AssertError(result, "500"); - } + AssertError(result, "500"); + } - [Fact] - public async Task ATimeout_ThrowsSoTheFrameworkBudgetCountsIt() - { - using var handler = StubHttpMessageHandler.TimingOut(); - using HttpClient client = new(handler); - var tool = await CreateAsync(client, LookupOrder); - - // The endpoint did not answer at all. The model cannot fix a deadline by rewording the - // arguments, so this propagates and MaximumConsecutiveErrorsPerRequest ends the turn on the - // fallback line, per section 8.7 row six. It used to become a result the model retried - // against a dead endpoint for the whole turn. - var thrown = await Assert.ThrowsAnyAsync( - () => CallAsync(tool, ("orderId", "A-42"))); - - Assert.IsType(thrown.InnerException); - } + [Fact] + public async Task ATimeout_ThrowsSoTheFrameworkBudgetCountsIt() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.TimingOut(); + using HttpClient client = new(handler); + AITool? tool = await CreateAsync(client, LookupOrder); + + // The endpoint did not answer at all. The model cannot fix a deadline by rewording the + // arguments, so this propagates and MaximumConsecutiveErrorsPerRequest ends the turn on the + // fallback line, per section 8.7 row six. It used to become a result the model retried + // against a dead endpoint for the whole turn. + OperationCanceledException thrown = await Assert.ThrowsAnyAsync( + () => CallAsync(tool, ("orderId", "A-42"))); + + _ = Assert.IsType(thrown.InnerException); + } - [Fact] - public async Task ATransportFailure_ThrowsSoTheFrameworkBudgetCountsIt() - { - using StubHttpMessageHandler handler = new(_ => throw new HttpRequestException("no such host")); - using HttpClient client = new(handler); - var tool = await CreateAsync(client, LookupOrder); + [Fact] + public async Task ATransportFailure_ThrowsSoTheFrameworkBudgetCountsIt() + { + using StubHttpMessageHandler handler = new(_ => throw new HttpRequestException("no such host")); + using HttpClient client = new(handler); + AITool? tool = await CreateAsync(client, LookupOrder); - // The host is not resolvable. See ATimeout_ThrowsSoTheFrameworkBudgetCountsIt. - var thrown = await Assert.ThrowsAsync( - () => CallAsync(tool, ("orderId", "A-42"))); + // The host is not resolvable. See ATimeout_ThrowsSoTheFrameworkBudgetCountsIt. + HttpRequestException thrown = await Assert.ThrowsAsync( + () => CallAsync(tool, ("orderId", "A-42"))); - Assert.Equal("no such host", thrown.Message); - } + Assert.Equal("no such host", thrown.Message); + } - [Fact] - public async Task AnEndpointThatRefusedTheRequest_StillBecomesAnErrorResult() - { - // The counterpart, and the half that must not regress: the endpoint ANSWERED. What it said is - // a fact the model reads and works around, so it never spends the budget. HttpTool writes - // this result itself and never reaches the classification at all. - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.NotFound, """{"detail":"no such order"}"""); - using HttpClient client = new(handler); + [Fact] + public async Task AnEndpointThatRefusedTheRequest_StillBecomesAnErrorResult() + { + // The counterpart, and the half that must not regress: the endpoint ANSWERED. What it said is + // a fact the model reads and works around, so it never spends the budget. HttpTool writes + // this result itself and never reaches the classification at all. + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.NotFound, /*lang=json,strict*/ """{"detail":"no such order"}"""); + using HttpClient client = new(handler); - var result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); + object? result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); - AssertError(result, "404"); - } + AssertError(result, "404"); + } - [Fact] - public async Task AMissingPlaceholderArgument_BecomesAnErrorResultAndMakesNoCall() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); - using HttpClient client = new(handler); + [Fact] + public async Task AMissingPlaceholderArgument_BecomesAnErrorResultAndMakesNoCall() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); + using HttpClient client = new(handler); - var result = await CallAsync(await CreateAsync(client, LookupOrder)); + object? result = await CallAsync(await CreateAsync(client, LookupOrder)); - AssertError(result, "orderId"); - Assert.Empty(handler.Requests); - } + AssertError(result, "orderId"); + Assert.Empty(handler.Requests); + } - [Fact] - public async Task NoErrorResult_EverHoldsTheHeaderValue() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.Unauthorized, """{"detail":"no"}"""); - using HttpClient client = new(handler); + [Fact] + public async Task NoErrorResult_EverHoldsTheHeaderValue() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.Unauthorized, /*lang=json,strict*/ """{"detail":"no"}"""); + using HttpClient client = new(handler); - var result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); + object? result = await CallAsync(await CreateAsync(client, LookupOrder), ("orderId", "A-42")); - Assert.DoesNotContain(SecretValue, result!.ToString(), StringComparison.Ordinal); - } + Assert.DoesNotContain(SecretValue, result!.ToString(), StringComparison.Ordinal); + } - [Fact] - public async Task ACallerThatHangsUp_CancelsAndDoesNotBecomeAnErrorResult() - { - using var handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); - using HttpClient client = new(handler); - var function = Assert.IsType(await CreateAsync(client, LookupOrder), exactMatch: false); + [Fact] + public async Task ACallerThatHangsUp_CancelsAndDoesNotBecomeAnErrorResult() + { + using StubHttpMessageHandler handler = StubHttpMessageHandler.Answering(HttpStatusCode.OK, "{}"); + using HttpClient client = new(handler); + AIFunction function = Assert.IsType(await CreateAsync(client, LookupOrder), exactMatch: false); - using CancellationTokenSource source = new(); - await source.CancelAsync(); + using CancellationTokenSource source = new(); + await source.CancelAsync(); - await Assert.ThrowsAnyAsync( - async () => await function.InvokeAsync(Arguments(("orderId", "A-42")), source.Token)); - } + _ = await Assert.ThrowsAnyAsync( + async () => await function.InvokeAsync(Arguments(("orderId", "A-42")), source.Token)); + } - // --------------------------------------------------------------------------------------------- - // Failing at startup. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AHeaderReferenceStartupNeverResolved_FailsAtStartup() - { - using HttpClient client = new(); - HttpToolSource source = new(client, ResolvedSecrets.Empty); - var context = new ToolSourceContext(new AgentCoreConfiguration + // --------------------------------------------------------------------------------------------- + // Failing at startup. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AHeaderReferenceStartupNeverResolved_FailsAtStartup() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Tools = [LookupOrder], - }); - - // The header resolves once, when the document compiles. A tool that reached a call with an - // unresolved reference would fail on the telephone instead. - await Assert.ThrowsAsync(async () => await source.ProvideAsync(context, Token)); - } + using HttpClient client = new(); + HttpToolSource source = new(client, ResolvedSecrets.Empty); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [LookupOrder], + }); + + // The header resolves once, when the document compiles. A tool that reached a call with an + // unresolved reference would fail on the telephone instead. + _ = await Assert.ThrowsAsync(async () => await source.ProvideAsync(context, Token)); + } - [Fact] - public async Task TheHttpSource_ServesNoOtherKind() - { - using HttpClient client = new(); - Assert.Null(await CreateAsync(client, new ToolConfiguration { Id = "i", Kind = ToolKind.Agent, Agent = "a" })); - } + [Fact] + public async Task TheHttpSource_ServesNoOtherKind() + { + using HttpClient client = new(); + Assert.Null(await CreateAsync(client, new ToolConfiguration { Id = "i", Kind = ToolKind.Agent, Agent = "a" })); + } - // --------------------------------------------------------------------------------------------- - // Helpers. - // --------------------------------------------------------------------------------------------- - private static async Task CreateAsync(HttpClient client, ToolConfiguration tool) - { - HttpToolSource source = new( - client, ResolvedSecrets.Create([new KeyValuePair(SecretName, SecretValue)])); - var context = new ToolSourceContext(new AgentCoreConfiguration + // --------------------------------------------------------------------------------------------- + // Helpers. + // --------------------------------------------------------------------------------------------- + private static async Task CreateAsync(HttpClient client, ToolConfiguration tool) { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Tools = [tool], - }); - - var registrations = await source.ProvideAsync(context, Token); - return registrations.Count == 0 ? null : registrations[0].Materialise(); - } + HttpToolSource source = new( + client, ResolvedSecrets.Create([new KeyValuePair(SecretName, SecretValue)])); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [tool], + }); + + IReadOnlyList registrations = await source.ProvideAsync(context, Token); + return registrations.Count == 0 ? null : registrations[0].Materialise(); + } - [Fact] - public async Task AnHttpToolWithNoRequest_FailsTheBoot() - { - using HttpClient client = new(); - HttpToolSource source = new(client, ResolvedSecrets.Empty); - var context = new ToolSourceContext(new AgentCoreConfiguration + [Fact] + public async Task AnHttpToolWithNoRequest_FailsTheBoot() { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Tools = [new ToolConfiguration { Id = "call_api", Kind = ToolKind.Http, Description = "Call it." }], - }); + using HttpClient client = new(); + HttpToolSource source = new(client, ResolvedSecrets.Empty); + ToolSourceContext context = new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Tools = [new ToolConfiguration { Id = "call_api", Kind = ToolKind.Http, Description = "Call it." }], + }); - var failure = await Assert.ThrowsAsync(async () => - await source.ProvideAsync(context, TestContext.Current.CancellationToken)); + ConfigurationLoadException failure = await Assert.ThrowsAsync(async () => + await source.ProvideAsync(context, TestContext.Current.CancellationToken)); - Assert.Contains("call_api", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("call_api", failure.Message, StringComparison.Ordinal); + } - private static AIFunctionArguments Arguments(params (string Name, object? Value)[] arguments) - { - Dictionary values = new(StringComparer.Ordinal); - foreach (var argument in arguments) + private static AIFunctionArguments Arguments(params (string Name, object? Value)[] arguments) { - values[argument.Name] = argument.Value; - } + Dictionary values = new(StringComparer.Ordinal); + foreach ((string Name, object? Value) in arguments) + { + values[Name] = Value; + } - return new AIFunctionArguments(values); - } + return new AIFunctionArguments(values); + } - private static async Task CallAsync(AITool? tool, params (string Name, object? Value)[] arguments) - { - var function = Assert.IsType(tool, exactMatch: false); - return await function.InvokeAsync(Arguments(arguments), Token); - } + private static async Task CallAsync(AITool? tool, params (string Name, object? Value)[] arguments) + { + AIFunction function = Assert.IsType(tool, exactMatch: false); + return await function.InvokeAsync(Arguments(arguments), Token); + } - private static void AssertError(object? result, string fragment) - { - var error = Assert.IsType(result); - Assert.True(ToolErrorResult.IsError(error)); - Assert.Equal("lookup_order", error["tool"]!.GetValue()); - Assert.Contains(fragment, error["message"]!.GetValue(), StringComparison.OrdinalIgnoreCase); + private static void AssertError(object? result, string fragment) + { + JsonObject error = Assert.IsType(result); + Assert.True(ToolErrorResult.IsError(error)); + Assert.Equal("lookup_order", error["tool"]!.GetValue()); + Assert.Contains(fragment, error["message"]!.GetValue(), StringComparison.OrdinalIgnoreCase); + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/McpConnectionFactoryTests.cs b/tests/AgentCore.Infrastructure.Tests/Tools/McpConnectionFactoryTests.cs index 76fd5274..3979ca2c 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/McpConnectionFactoryTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/McpConnectionFactoryTests.cs @@ -3,225 +3,229 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Secrets; using AgentCore.Infrastructure.Tools.Mcp; +using ModelContextProtocol.Client; using Xunit; -namespace AgentCore.Infrastructure.Tests.Tools; - -/// -/// Where a credential actually goes, and whose HTTP pipeline actually carries it. -/// -/// -/// A credential has to survive the whole way to the far side: onto a request header, or into a child -/// process's environment. These drive the real transports and a real child process, so nothing here -/// is a stub of the wire. -/// -public sealed class McpConnectionFactoryTests +namespace AgentCore.Infrastructure.Tests.Tools { - private const string TokenValue = "ghp_live_0123456789"; - - private static CancellationToken Token => TestContext.Current.CancellationToken; - - // --------------------------------------------------------------------------------------------- - // stdio: the credential reaches the child's environment, resolved. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AStdioServersEnvironment_ReachesTheChildProcess_WithItsSecretResolved() - { - var written = Path.Combine(Path.GetTempPath(), $"mcp-env-{Guid.NewGuid():N}"); - try - { - // The child writes what it was given and then waits, so the handshake times out rather - // than the process vanishing before it has been observed. - await ConnectAndGiveUpAsync(new McpServerConfiguration - { - Id = "github", - Transport = McpTransport.Stdio, - Command = ["/bin/sh", "-c", $"printf '%s' \"$GITHUB_TOKEN\" > '{written}'; exec cat"], - Env = Templates(("GITHUB_TOKEN", "${secret:gh-token}")), - Allow = [new McpAllowEntry { Name = "*" }], - }); - - await WaitForFileAsync(written); - Assert.Equal(TokenValue, await File.ReadAllTextAsync(written, Token)); - } - finally - { - File.Delete(written); - } - } - /// - /// The SDK inherits by default, which would hand a third-party child process every other - /// credential, token, and proxy setting this one holds. + /// Where a credential actually goes, and whose HTTP pipeline actually carries it. /// - [Fact] - public async Task AStdioServer_DoesNotInheritThisProcessesEnvironment_UnlessTheDocumentAsks() + /// + /// A credential has to survive the whole way to the far side: onto a request header, or into a child + /// process's environment. These drive the real transports and a real child process, so nothing here + /// is a stub of the wire. + /// + public sealed class McpConnectionFactoryTests { - const string ours = "AGENTCORE_MCP_LEAK_PROBE"; - var written = Path.Combine(Path.GetTempPath(), $"mcp-leak-{Guid.NewGuid():N}"); - Environment.SetEnvironmentVariable(ours, "a-secret-this-process-holds"); + private const string TokenValue = "ghp_live_0123456789"; + + private static CancellationToken Token => TestContext.Current.CancellationToken; - try + // --------------------------------------------------------------------------------------------- + // stdio: the credential reaches the child's environment, resolved. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AStdioServersEnvironment_ReachesTheChildProcess_WithItsSecretResolved() { - await ConnectAndGiveUpAsync(new McpServerConfiguration + string written = Path.Combine(Path.GetTempPath(), $"mcp-env-{Guid.NewGuid():N}"); + try { - Id = "github", - Transport = McpTransport.Stdio, - Command = ["/bin/sh", "-c", $"printf '[%s]' \"${ours}\" > '{written}'; exec cat"], - Allow = [new McpAllowEntry { Name = "*" }], - }); - - await WaitForFileAsync(written); - Assert.Equal("[]", await File.ReadAllTextAsync(written, Token)); + // The child writes what it was given and then waits, so the handshake times out rather + // than the process vanishing before it has been observed. + await ConnectAndGiveUpAsync(new McpServerConfiguration + { + Id = "github", + Transport = McpTransport.Stdio, + Command = ["/bin/sh", "-c", $"printf '%s' \"$GITHUB_TOKEN\" > '{written}'; exec cat"], + Env = Templates(("GITHUB_TOKEN", "${secret:gh-token}")), + Allow = [new McpAllowEntry { Name = "*" }], + }); + + await WaitForFileAsync(written); + Assert.Equal(TokenValue, await File.ReadAllTextAsync(written, Token)); + } + finally + { + File.Delete(written); + } } - finally + + /// + /// The SDK inherits by default, which would hand a third-party child process every other + /// credential, token, and proxy setting this one holds. + /// + [Fact] + public async Task AStdioServer_DoesNotInheritThisProcessesEnvironment_UnlessTheDocumentAsks() { - Environment.SetEnvironmentVariable(ours, null); - File.Delete(written); - } - } + const string ours = "AGENTCORE_MCP_LEAK_PROBE"; + string written = Path.Combine(Path.GetTempPath(), $"mcp-leak-{Guid.NewGuid():N}"); + Environment.SetEnvironmentVariable(ours, "a-secret-this-process-holds"); - [Fact] - public async Task AStdioServerThatAsksToInherit_GetsThisProcessesEnvironment() - { - const string ours = "AGENTCORE_MCP_INHERIT_PROBE"; - var written = Path.Combine(Path.GetTempPath(), $"mcp-inherit-{Guid.NewGuid():N}"); - Environment.SetEnvironmentVariable(ours, "visible"); + try + { + await ConnectAndGiveUpAsync(new McpServerConfiguration + { + Id = "github", + Transport = McpTransport.Stdio, + Command = ["/bin/sh", "-c", $"printf '[%s]' \"${ours}\" > '{written}'; exec cat"], + Allow = [new McpAllowEntry { Name = "*" }], + }); + + await WaitForFileAsync(written); + Assert.Equal("[]", await File.ReadAllTextAsync(written, Token)); + } + finally + { + Environment.SetEnvironmentVariable(ours, null); + File.Delete(written); + } + } - try + [Fact] + public async Task AStdioServerThatAsksToInherit_GetsThisProcessesEnvironment() { - await ConnectAndGiveUpAsync(new McpServerConfiguration + const string ours = "AGENTCORE_MCP_INHERIT_PROBE"; + string written = Path.Combine(Path.GetTempPath(), $"mcp-inherit-{Guid.NewGuid():N}"); + Environment.SetEnvironmentVariable(ours, "visible"); + + try { - Id = "github", - Transport = McpTransport.Stdio, - Command = ["/bin/sh", "-c", $"printf '[%s]' \"${ours}\" > '{written}'; exec cat"], - InheritEnv = true, - Allow = [new McpAllowEntry { Name = "*" }], - }); - - await WaitForFileAsync(written); - Assert.Equal("[visible]", await File.ReadAllTextAsync(written, Token)); + await ConnectAndGiveUpAsync(new McpServerConfiguration + { + Id = "github", + Transport = McpTransport.Stdio, + Command = ["/bin/sh", "-c", $"printf '[%s]' \"${ours}\" > '{written}'; exec cat"], + InheritEnv = true, + Allow = [new McpAllowEntry { Name = "*" }], + }); + + await WaitForFileAsync(written); + Assert.Equal("[visible]", await File.ReadAllTextAsync(written, Token)); + } + finally + { + Environment.SetEnvironmentVariable(ours, null); + File.Delete(written); + } } - finally + + // --------------------------------------------------------------------------------------------- + // http: the header is on the request, and the request is on the host's own pipeline. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AnHttpServersHeaders_AreSentOnTheRequest_WithTheirSecretsResolved() { - Environment.SetEnvironmentVariable(ours, null); - File.Delete(written); + RecordingHandler handler = new(); + + await ConnectAndGiveUpAsync( + new McpServerConfiguration + { + Id = "jira", + Transport = McpTransport.Http, + Url = "https://mcp.example.com/", + Headers = Templates(("Authorization", "Bearer ${secret:gh-token}")), + Allow = [new McpAllowEntry { Name = "*" }], + }, + handler); + + // The transport probes more than one shape of endpoint. Every request it makes has to carry + // the credential: one that did not would be the request that gets refused. + Assert.NotEmpty(handler.Seen); + Assert.All( + handler.Seen, + request => Assert.Equal( + $"Bearer {TokenValue}", Assert.Single(request.Headers.GetValues("Authorization")))); } - } - // --------------------------------------------------------------------------------------------- - // http: the header is on the request, and the request is on the host's own pipeline. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AnHttpServersHeaders_AreSentOnTheRequest_WithTheirSecretsResolved() - { - RecordingHandler handler = new(); + /// + /// Left to itself the transport builds its own , which shares none of the + /// host's proxy settings, certificate configuration, or logging. + /// + [Fact] + public async Task AnHttpServer_IsReachedOnTheClientTheHostSupplies() + { + RecordingHandler handler = new(); - await ConnectAndGiveUpAsync( - new McpServerConfiguration - { - Id = "jira", - Transport = McpTransport.Http, - Url = "https://mcp.example.com/", - Headers = Templates(("Authorization", "Bearer ${secret:gh-token}")), - Allow = [new McpAllowEntry { Name = "*" }], - }, - handler); - - // The transport probes more than one shape of endpoint. Every request it makes has to carry - // the credential: one that did not would be the request that gets refused. - Assert.NotEmpty(handler.Seen); - Assert.All( - handler.Seen, - request => Assert.Equal( - $"Bearer {TokenValue}", Assert.Single(request.Headers.GetValues("Authorization")))); - } + await ConnectAndGiveUpAsync( + new McpServerConfiguration + { + Id = "jira", + Transport = McpTransport.Http, + Url = "https://mcp.example.com/", + Allow = [new McpAllowEntry { Name = "*" }], + }, + handler); + + Assert.NotEmpty(handler.Seen); + } - /// - /// Left to itself the transport builds its own , which shares none of the - /// host's proxy settings, certificate configuration, or logging. - /// - [Fact] - public async Task AnHttpServer_IsReachedOnTheClientTheHostSupplies() - { - RecordingHandler handler = new(); + /// Runs one connection attempt that is never going to succeed, and swallows the failure. + /// + /// Every test here asserts on what the attempt did on its way out — an environment the child was + /// launched with, a header that went onto the wire — and none of them needs a server that + /// answers. A short timeout keeps a doomed attempt from costing the suite anything. + /// + private static async Task ConnectAndGiveUpAsync( + McpServerConfiguration server, HttpMessageHandler? handler = null) + { + McpConnectionFactory factory = new( + ResolvedSecrets.Create([new KeyValuePair("gh-token", TokenValue)]), + handler is null ? null : () => new HttpClient(handler, disposeHandler: false)); - await ConnectAndGiveUpAsync( - new McpServerConfiguration + try { - Id = "jira", - Transport = McpTransport.Http, - Url = "https://mcp.example.com/", - Allow = [new McpAllowEntry { Name = "*" }], - }, - handler); - - Assert.NotEmpty(handler.Seen); - } - - /// Runs one connection attempt that is never going to succeed, and swallows the failure. - /// - /// Every test here asserts on what the attempt did on its way out — an environment the child was - /// launched with, a header that went onto the wire — and none of them needs a server that - /// answers. A short timeout keeps a doomed attempt from costing the suite anything. - /// - private static async Task ConnectAndGiveUpAsync( - McpServerConfiguration server, HttpMessageHandler? handler = null) - { - McpConnectionFactory factory = new( - ResolvedSecrets.Create([new KeyValuePair("gh-token", TokenValue)]), - handler is null ? null : () => new HttpClient(handler, disposeHandler: false)); - - try - { - await using var client = await factory.ConnectAsync(server, TimeSpan.FromSeconds(2), Token); + await using McpClient client = await factory.ConnectAsync(server, TimeSpan.FromSeconds(2), Token); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + } } - catch (Exception ex) when (ex is not OperationCanceledException) + + private static Dictionary Templates(params (string Key, string Value)[] entries) { + return entries.ToDictionary(entry => entry.Key, entry => SecretTemplate.Parse(entry.Value), StringComparer.Ordinal); } - } - - private static Dictionary Templates(params (string Key, string Value)[] entries) - => entries.ToDictionary(entry => entry.Key, entry => SecretTemplate.Parse(entry.Value), StringComparer.Ordinal); - /// Waits for the child process to have written its file. - private static async Task WaitForFileAsync(string path) - { - for (var attempt = 0; attempt < 100 && !File.Exists(path); attempt++) + /// Waits for the child process to have written its file. + private static async Task WaitForFileAsync(string path) { - await Task.Delay(20, Token); - } + for (int attempt = 0; attempt < 100 && !File.Exists(path); attempt++) + { + await Task.Delay(20, Token); + } - Assert.True(File.Exists(path), $"the child process never wrote {path}, so it was never launched."); - } + Assert.True(File.Exists(path), $"the child process never wrote {path}, so it was never launched."); + } - /// Records every request and refuses it, so no attempt reaches a real network. - private sealed class RecordingHandler : HttpMessageHandler - { - private readonly List _seen = []; + /// Records every request and refuses it, so no attempt reaches a real network. + private sealed class RecordingHandler : HttpMessageHandler + { + private readonly List _seen = []; - private readonly Lock _sync = new(); + private readonly Lock _sync = new(); - public IReadOnlyList Seen - { - get + public IReadOnlyList Seen { - lock (_sync) + get { - return [.. _seen]; + lock (_sync) + { + return [.. _seen]; + } } } - } - protected override Task SendAsync( - HttpRequestMessage request, CancellationToken cancellationToken) - { - lock (_sync) + protected override Task SendAsync( + HttpRequestMessage request, CancellationToken cancellationToken) { - _seen.Add(request); - } + lock (_sync) + { + _seen.Add(request); + } - return Task.FromResult(new HttpResponseMessage(HttpStatusCode.ServiceUnavailable)); + return Task.FromResult(new HttpResponseMessage(HttpStatusCode.ServiceUnavailable)); + } } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/McpServerSessionTests.cs b/tests/AgentCore.Infrastructure.Tests/Tools/McpServerSessionTests.cs index c747cdba..9edcb2b3 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/McpServerSessionTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/McpServerSessionTests.cs @@ -13,393 +13,404 @@ using ModelContextProtocol.Protocol; using Xunit; -namespace AgentCore.Infrastructure.Tests.Tools; - -/// -/// The connection to one mcp: server, for as long as the process runs. -/// -/// -/// Discovery is not the whole story. A server can take forever to answer, can still be warming up -/// when the boot reaches it, and can die long after it was listed. These drive a real MCP server -/// over real pipes, so nothing here is a stub of the wire. -/// -public sealed class McpServerSessionTests +namespace AgentCore.Infrastructure.Tests.Tools { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - // --------------------------------------------------------------------------------------------- - // A wedged server costs its own timeout, not the SDK's 60-second default. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AServerThatNeverSpeaks_FailsAtItsOwnTimeout() + /// + /// The connection to one mcp: server, for as long as the process runs. + /// + /// + /// Discovery is not the whole story. A server can take forever to answer, can still be warming up + /// when the boot reaches it, and can die long after it was listed. These drive a real MCP server + /// over real pipes, so nothing here is a stub of the wire. + /// + public sealed class McpServerSessionTests { - // A pipe with nothing on the far end: the transport connects and the handshake is never - // answered, which is what /usr/bin/sleep as a command: does. - await using McpToolSource source = new(_ => SilentTransport(), null); - - var watch = Stopwatch.StartNew(); - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync( - ContextFor(Wedged(connectTimeoutSeconds: 1, attempts: 1)), Token)); - watch.Stop(); - - Assert.Contains("wedged", failure.Message, StringComparison.Ordinal); - Assert.True( - watch.Elapsed < TimeSpan.FromSeconds(20), - $"the boot took {watch.Elapsed}, so the SDK's own 60s default is still what governs."); - } + private static CancellationToken Token => TestContext.Current.CancellationToken; - [Fact] - public async Task TheTimeoutMessage_TellsTheDeployerWhichKnobToTurn() - { - await using McpToolSource source = new(_ => SilentTransport(), null); + // --------------------------------------------------------------------------------------------- + // A wedged server costs its own timeout, not the SDK's 60-second default. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AServerThatNeverSpeaks_FailsAtItsOwnTimeout() + { + // A pipe with nothing on the far end: the transport connects and the handshake is never + // answered, which is what /usr/bin/sleep as a command: does. + await using McpToolSource source = new(_ => SilentTransport(), null); + + Stopwatch watch = Stopwatch.StartNew(); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync( + ContextFor(Wedged(connectTimeoutSeconds: 1, attempts: 1)), Token)); + watch.Stop(); + + Assert.Contains("wedged", failure.Message, StringComparison.Ordinal); + Assert.True( + watch.Elapsed < TimeSpan.FromSeconds(20), + $"the boot took {watch.Elapsed}, so the SDK's own 60s default is still what governs."); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync( - ContextFor(Wedged(connectTimeoutSeconds: 1, attempts: 1)), Token)); + [Fact] + public async Task TheTimeoutMessage_TellsTheDeployerWhichKnobToTurn() + { + await using McpToolSource source = new(_ => SilentTransport(), null); - Assert.Contains("connectTimeoutSeconds", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync( + ContextFor(Wedged(connectTimeoutSeconds: 1, attempts: 1)), Token)); - // The SDK runs its InitializationTimeout on the same length as the session's own deadline, so - // on a loaded machine the SDK's clock can fire first and throw its own TimeoutException. - [Fact] - public async Task WhenTheSdksOwnClockWins_TheKnobIsStillNamed() - { - await using McpServerSession session = new( - Wedged(connectTimeoutSeconds: 1, attempts: 1), - (_, _) => throw new TimeoutException("Client failed to initialize within the timeout.")); + Assert.Contains("connectTimeoutSeconds", failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - async () => await session.OpenAsync(Token)); + // The SDK runs its InitializationTimeout on the same length as the session's own deadline, so + // on a loaded machine the SDK's clock can fire first and throw its own TimeoutException. + [Fact] + public async Task WhenTheSdksOwnClockWins_TheKnobIsStillNamed() + { + await using McpServerSession session = new( + Wedged(connectTimeoutSeconds: 1, attempts: 1), + (_, _) => throw new TimeoutException("Client failed to initialize within the timeout.")); - Assert.Contains("connectTimeoutSeconds", failure.Message, StringComparison.Ordinal); - } + TimeoutException failure = await Assert.ThrowsAsync( + async () => await session.OpenAsync(Token)); - // --------------------------------------------------------------------------------------------- - // A cold start is a healthy server that answers nothing on the first try. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AServerThatIsSlowToStart_IsRetriedUntilItAnswers() - { - await using ControllableMcpServer fake = new("create_issue"); - var attempts = 0; + Assert.Contains("connectTimeoutSeconds", failure.Message, StringComparison.Ordinal); + } - await using McpToolSource source = new( - _ => - { - // The first two attempts find nothing listening, as npx fetching a package does. - attempts++; - return attempts <= 2 ? throw new IOException("connection refused") : fake.NewTransport(); - }, - null); + // --------------------------------------------------------------------------------------------- + // A cold start is a healthy server that answers nothing on the first try. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AServerThatIsSlowToStart_IsRetriedUntilItAnswers() + { + await using ControllableMcpServer fake = new("create_issue"); + int attempts = 0; + + await using McpToolSource source = new( + _ => + { + // The first two attempts find nothing listening, as npx fetching a package does. + attempts++; + return attempts <= 2 ? throw new IOException("connection refused") : fake.NewTransport(); + }, + null); + + IReadOnlyList registrations = await source.ProvideAsync( + ContextFor(Jira(attempts: 3, backoffMs: 1)), Token); + + Assert.Equal(3, attempts); + Assert.Equal("jira.create_issue", Assert.Single(registrations).Id); + } - var registrations = await source.ProvideAsync( - ContextFor(Jira(attempts: 3, backoffMs: 1)), Token); + [Fact] + public async Task AServerThatNeverAnswers_FailsAfterItsLastAttempt_AndSaysWhy() + { + int attempts = 0; + await using McpToolSource source = new( + _ => + { + attempts++; + throw new IOException("connection refused"); + }, + null); + + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(attempts: 3, backoffMs: 1)), Token)); + + Assert.Equal(3, attempts); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + Assert.Contains("connection refused", failure.Message, StringComparison.Ordinal); + } - Assert.Equal(3, attempts); - Assert.Equal("jira.create_issue", Assert.Single(registrations).Id); - } + [Fact] + public async Task AServerThatAnswersFirstTime_IsNotRetried() + { + await using ControllableMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.NewTransport(), null); - [Fact] - public async Task AServerThatNeverAnswers_FailsAfterItsLastAttempt_AndSaysWhy() - { - var attempts = 0; - await using McpToolSource source = new( - _ => - { - attempts++; - throw new IOException("connection refused"); - }, - null); + _ = await source.ProvideAsync(ContextFor(Jira()), Token); - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(attempts: 3, backoffMs: 1)), Token)); + Assert.Equal(1, fake.ConnectionsOpened); + } - Assert.Equal(3, attempts); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - Assert.Contains("connection refused", failure.Message, StringComparison.Ordinal); - } + // --------------------------------------------------------------------------------------------- + // The tool object outlives the connection it was discovered on. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AToolStillWorks_AfterTheServerItWasDiscoveredOnHasDied() + { + await using ControllableMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.NewTransport(), null); - [Fact] - public async Task AServerThatAnswersFirstTime_IsNotRetried() - { - await using ControllableMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.NewTransport(), null); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira()), Token); + AIFunction tool = (AIFunction)Assert.Single(registrations).Materialise(); - await source.ProvideAsync(ContextFor(Jira()), Token); + // The tool object was built while the first connection was alive, and is never rebuilt. + await fake.KillNewestConnectionAsync(); - Assert.Equal(1, fake.ConnectionsOpened); - } + object? result = await tool.InvokeAsync([], Token); - // --------------------------------------------------------------------------------------------- - // The tool object outlives the connection it was discovered on. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AToolStillWorks_AfterTheServerItWasDiscoveredOnHasDied() - { - await using ControllableMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.NewTransport(), null); + Assert.Equal(2, fake.ConnectionsOpened); + Assert.False(IsError(result), $"the conversation returned an error result: {result}"); - var registrations = await source.ProvideAsync(ContextFor(Jira()), Token); - var tool = (AIFunction)Assert.Single(registrations).Materialise(); + // The CallToolResult envelope is protocol and not answer, so what comes back is the text the + // server put in it and never the box it arrived in. + Assert.Equal("ran create_issue", result); + } - // The tool object was built while the first connection was alive, and is never rebuilt. - await fake.KillNewestConnectionAsync(); + [Fact] + public async Task AToolTheServerHasWithdrawn_ReturnsAnErrorResult_AndDoesNotThrow() + { + await using ControllableMcpServer fake = new("create_issue", "close_issue"); + await using McpToolSource source = new(_ => fake.NewTransport(), null); - var result = await tool.InvokeAsync([], Token); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira()), Token); + AIFunction tool = (AIFunction)registrations.Single(r => r.Id == "jira.close_issue").Materialise(); - Assert.Equal(2, fake.ConnectionsOpened); - Assert.False(IsError(result), $"the conversation returned an error result: {result}"); + fake.Withdraw("close_issue"); + await fake.AnnounceToolChangeAsync(Token); + await WaitForAsync(async () => + { + object? probe = await tool.InvokeAsync([], Token); + return IsError(probe); + }); + + object? result = await tool.InvokeAsync([], Token); + + JsonObject error = Assert.IsType(result); + Assert.True(ToolErrorResult.IsError(error)); + Assert.Contains( + "no longer offers", + error[ToolErrorResult.MessageProperty]!.GetValue(), + StringComparison.Ordinal); + } - // The CallToolResult envelope is protocol and not answer, so what comes back is the text the - // server put in it and never the box it arrived in. - Assert.Equal("ran create_issue", result); - } + /// + /// The served set is fixed at boot. allow: pinned these names and every agent's + /// tools: list was checked against the ids they became, so a tool the server adds later + /// was never allowed and does not appear. + /// + [Fact] + public async Task AToolTheServerAddsLater_IsNotServed() + { + await using ControllableMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.NewTransport(), null); - [Fact] - public async Task AToolTheServerHasWithdrawn_ReturnsAnErrorResult_AndDoesNotThrow() - { - await using ControllableMcpServer fake = new("create_issue", "close_issue"); - await using McpToolSource source = new(_ => fake.NewTransport(), null); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira()), Token); - var registrations = await source.ProvideAsync(ContextFor(Jira()), Token); - var tool = (AIFunction)registrations.Single(r => r.Id == "jira.close_issue").Materialise(); + Assert.Equal("jira.create_issue", Assert.Single(registrations).Id); + } - fake.Withdraw("close_issue"); - await fake.AnnounceToolChangeAsync(Token); - await WaitForAsync(async () => + /// + /// A connection that opens and then fails to list is a child process the retry would otherwise + /// leave running, once per attempt, with the boot failing anyway. + /// + [Fact] + public async Task AConnectionThatOpensAndThenFailsToList_IsClosedBeforeTheNextAttempt() { - var probe = await tool.InvokeAsync([], Token); - return IsError(probe); - }); - - var result = await tool.InvokeAsync([], Token); - - var error = Assert.IsType(result); - Assert.True(ToolErrorResult.IsError(error)); - Assert.Contains( - "no longer offers", - error[ToolErrorResult.MessageProperty]!.GetValue(), - StringComparison.Ordinal); - } + await using ControllableMcpServer fake = new("create_issue") { RefuseToList = true }; + List opened = []; + + await using McpToolSource source = new( + async (_, timeout, cancellationToken) => + { + McpClient client = await McpClient.CreateAsync( + fake.NewTransport(), + new McpClientOptions { InitializationTimeout = timeout }, + cancellationToken: cancellationToken); + opened.Add(client); + return client; + }, + null); + + _ = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(attempts: 3, backoffMs: 1)), Token)); + + Assert.Equal(3, opened.Count); + + // A closed client's session has completed. One still open is a connection this boot made, + // failed on, and walked away from — in production, a live child process, once per attempt. + await WaitForAsync(() => Task.FromResult(opened.TrueForAll(client => client.Completion.IsCompleted))); + Assert.All(opened, client => Assert.True(client.Completion.IsCompleted, "a failed attempt was left open.")); + } - /// - /// The served set is fixed at boot. allow: pinned these names and every agent's - /// tools: list was checked against the ids they became, so a tool the server adds later - /// was never allowed and does not appear. - /// - [Fact] - public async Task AToolTheServerAddsLater_IsNotServed() - { - await using ControllableMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.NewTransport(), null); + /// + /// The reconnect re-lists, so the tool may have gone in between. Without a second check the + /// repeat runs unguarded and the model reads a raw protocol fault. + /// + [Fact] + public async Task AToolWithdrawnWhileTheServerWasDown_ReturnsAnErrorResult() + { + await using ControllableMcpServer fake = new("create_issue", "close_issue"); + await using McpToolSource source = new(_ => fake.NewTransport(), null); - var registrations = await source.ProvideAsync(ContextFor(Jira()), Token); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira()), Token); + AIFunction tool = (AIFunction)registrations.Single(r => r.Id == "jira.close_issue").Materialise(); - Assert.Equal("jira.create_issue", Assert.Single(registrations).Id); - } + fake.Withdraw("close_issue"); + await fake.KillNewestConnectionAsync(); - /// - /// A connection that opens and then fails to list is a child process the retry would otherwise - /// leave running, once per attempt, with the boot failing anyway. - /// - [Fact] - public async Task AConnectionThatOpensAndThenFailsToList_IsClosedBeforeTheNextAttempt() - { - await using ControllableMcpServer fake = new("create_issue") { RefuseToList = true }; - List opened = []; - - await using McpToolSource source = new( - async (_, timeout, cancellationToken) => + // Closing the pipes is not instant, so a conversation made in the moment after the kill can still be + // answered by the connection that is on its way out. Calling until one of them reaches the + // dead connection is what puts the reconnect under test; every conversation after that must land on + // the same answer, which is what the assertion below checks. + object? result = null; + await WaitForAsync(async () => { - var client = await McpClient.CreateAsync( - fake.NewTransport(), - new McpClientOptions { InitializationTimeout = timeout }, - cancellationToken: cancellationToken); - opened.Add(client); - return client; - }, - null); - - await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(attempts: 3, backoffMs: 1)), Token)); - - Assert.Equal(3, opened.Count); - - // A closed client's session has completed. One still open is a connection this boot made, - // failed on, and walked away from — in production, a live child process, once per attempt. - await WaitForAsync(() => Task.FromResult(opened.TrueForAll(client => client.Completion.IsCompleted))); - Assert.All(opened, client => Assert.True(client.Completion.IsCompleted, "a failed attempt was left open.")); - } - - /// - /// The reconnect re-lists, so the tool may have gone in between. Without a second check the - /// repeat runs unguarded and the model reads a raw protocol fault. - /// - [Fact] - public async Task AToolWithdrawnWhileTheServerWasDown_ReturnsAnErrorResult() - { - await using ControllableMcpServer fake = new("create_issue", "close_issue"); - await using McpToolSource source = new(_ => fake.NewTransport(), null); - - var registrations = await source.ProvideAsync(ContextFor(Jira()), Token); - var tool = (AIFunction)registrations.Single(r => r.Id == "jira.close_issue").Materialise(); - - fake.Withdraw("close_issue"); - await fake.KillNewestConnectionAsync(); + result = await tool.InvokeAsync([], Token); + return IsError(result); + }); + + JsonObject error = Assert.IsType(result); + Assert.True(ToolErrorResult.IsError(error)); + Assert.Contains( + "no longer offers", + error[ToolErrorResult.MessageProperty]!.GetValue(), + StringComparison.Ordinal); + + // It stays gone: the guard is on the conversation, not on one unlucky moment. + Assert.True(IsError(await tool.InvokeAsync([], Token))); + } - // Closing the pipes is not instant, so a conversation made in the moment after the kill can still be - // answered by the connection that is on its way out. Calling until one of them reaches the - // dead connection is what puts the reconnect under test; every conversation after that must land on - // the same answer, which is what the assertion below checks. - object? result = null; - await WaitForAsync(async () => + // --------------------------------------------------------------------------------------------- + // Through the registry: a tool that hangs is given up on, and the model is told. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AToolThatHangs_IsGivenUpOn_AtTheServersOwnCallTimeout() { - result = await tool.InvokeAsync([], Token); - return IsError(result); - }); - - var error = Assert.IsType(result); - Assert.True(ToolErrorResult.IsError(error)); - Assert.Contains( - "no longer offers", - error[ToolErrorResult.MessageProperty]!.GetValue(), - StringComparison.Ordinal); - - // It stays gone: the guard is on the conversation, not on one unlucky moment. - Assert.True(IsError(await tool.InvokeAsync([], Token))); - } + await using ControllableMcpServer fake = new("create_issue") { CallDelay = TimeSpan.FromMinutes(5) }; + await using McpToolSource source = new(_ => fake.NewTransport(), null); - // --------------------------------------------------------------------------------------------- - // Through the registry: a tool that hangs is given up on, and the model is told. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AToolThatHangs_IsGivenUpOn_AtTheServersOwnCallTimeout() - { - await using ControllableMcpServer fake = new("create_issue") { CallDelay = TimeSpan.FromMinutes(5) }; - await using McpToolSource source = new(_ => fake.NewTransport(), null); - - var registrations = await source.ProvideAsync(ContextFor(Jira(callTimeoutSeconds: 1)), Token); - var registration = Assert.Single(registrations); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira(callTimeoutSeconds: 1)), Token); + ToolRegistration registration = Assert.Single(registrations); - Assert.Equal(TimeSpan.FromSeconds(1), registration.CallTimeout); + Assert.Equal(TimeSpan.FromSeconds(1), registration.CallTimeout); - var registry = await ToolRegistryBuilder.BuildAsync( - [new OneSource(registration)], ContextFor(Jira(callTimeoutSeconds: 1)), Token); + ToolRegistry registry = await ToolRegistryBuilder.BuildAsync( + [new OneSource(registration)], ContextFor(Jira(callTimeoutSeconds: 1)), Token); - var watch = Stopwatch.StartNew(); - var result = await ((AIFunction)registry.Resolve("jira.create_issue")) - .InvokeAsync([], Token); - watch.Stop(); + Stopwatch watch = Stopwatch.StartNew(); + object? result = await ((AIFunction)registry.Resolve("jira.create_issue")) + .InvokeAsync([], Token); + watch.Stop(); - Assert.True(ToolErrorResult.IsError(Assert.IsType(result))); - Assert.True(watch.Elapsed < TimeSpan.FromSeconds(20), $"it waited {watch.Elapsed}."); - } + Assert.True(ToolErrorResult.IsError(Assert.IsType(result))); + Assert.True(watch.Elapsed < TimeSpan.FromSeconds(20), $"it waited {watch.Elapsed}."); + } - // --------------------------------------------------------------------------------------------- - // Only what the server declared crosses the wire: the filed turn carries delegates. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task AnEntryTheServerNeverDeclared_NeverCrossesTheWire() - { - const string Declared = "message"; - const string Residue = "urn:agentcore:residue"; + // --------------------------------------------------------------------------------------------- + // Only what the server declared crosses the wire: the filed turn carries delegates. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task AnEntryTheServerNeverDeclared_NeverCrossesTheWire() + { + const string Declared = "message"; + const string Residue = "urn:agentcore:residue"; - // Arrange - await using ControllableMcpServer fake = new("echo") { SchemaProperty = Declared }; - await using McpToolSource source = new(_ => fake.NewTransport(), null); + // Arrange + await using ControllableMcpServer fake = new("echo") { SchemaProperty = Declared }; + await using McpToolSource source = new(_ => fake.NewTransport(), null); - var registrations = await source.ProvideAsync(ContextFor(Jira()), Token); - var tool = (AIFunction)registrations.Single(r => r.Id == "jira.echo").Materialise(); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira()), Token); + AIFunction tool = (AIFunction)registrations.Single(r => r.Id == "jira.echo").Materialise(); - // Act - var result = await tool.InvokeAsync( - new AIFunctionArguments { [Declared] = "hello", [Residue] = new Action(() => { }) }, - Token); + // Act + object? result = await tool.InvokeAsync( + new AIFunctionArguments { [Declared] = "hello", [Residue] = new Action(() => { }) }, + Token); - // Assert - Assert.False(IsError(result), "the conversation failed instead of reaching the server."); - Assert.Equal([Declared], fake.LastArgumentNames); - } + // Assert + Assert.False(IsError(result), "the conversation failed instead of reaching the server."); + Assert.Equal([Declared], fake.LastArgumentNames); + } - // --------------------------------------------------------------------------------------------- - // Closing a session closes the connection under it, whatever the tools are still holding. - // --------------------------------------------------------------------------------------------- - [Fact] - public async Task DisposingTheSource_LeavesTheToolReturningAnErrorResult_RatherThanThrowing() - { - await using ControllableMcpServer fake = new("create_issue"); - McpToolSource source = new(_ => fake.NewTransport(), null); + // --------------------------------------------------------------------------------------------- + // Closing a session closes the connection under it, whatever the tools are still holding. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task DisposingTheSource_LeavesTheToolReturningAnErrorResult_RatherThanThrowing() + { + await using ControllableMcpServer fake = new("create_issue"); + McpToolSource source = new(_ => fake.NewTransport(), null); - var registrations = await source.ProvideAsync(ContextFor(Jira()), Token); - var tool = (AIFunction)Assert.Single(registrations).Materialise(); + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira()), Token); + AIFunction tool = (AIFunction)Assert.Single(registrations).Materialise(); - await source.DisposeAsync(); + await source.DisposeAsync(); - var result = await tool.InvokeAsync([], Token); + object? result = await tool.InvokeAsync([], Token); - Assert.True(ToolErrorResult.IsError(Assert.IsType(result))); - } + Assert.True(ToolErrorResult.IsError(Assert.IsType(result))); + } - private static bool IsError(object? result) - => result is JsonObject map && ToolErrorResult.IsError(map); + private static bool IsError(object? result) + { + return result is JsonObject map && ToolErrorResult.IsError(map); + } - /// Waits for a condition a notification will make true, or gives up. - private static async Task WaitForAsync(Func> condition) - { - for (var attempt = 0; attempt < 50; attempt++) + /// Waits for a condition a notification will make true, or gives up. + private static async Task WaitForAsync(Func> condition) { - if (await condition()) + for (int attempt = 0; attempt < 50; attempt++) { - return; + if (await condition()) + { + return; + } + + await Task.Delay(20, Token); } + } - await Task.Delay(20, Token); + /// A transport whose far end never answers the handshake. + private static StreamClientTransport SilentTransport() + { + Pipe toNowhere = new(); + Pipe fromNowhere = new(); + return new StreamClientTransport(toNowhere.Writer.AsStream(), fromNowhere.Reader.AsStream()); } - } - /// A transport whose far end never answers the handshake. - private static StreamClientTransport SilentTransport() - { - Pipe toNowhere = new(); - Pipe fromNowhere = new(); - return new StreamClientTransport(toNowhere.Writer.AsStream(), fromNowhere.Reader.AsStream()); - } + private static ToolSourceContext ContextFor(McpServerConfiguration server) + { + return new(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Mcp = [server] }); + } - private static ToolSourceContext ContextFor(McpServerConfiguration server) - => new(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Agents = new AgentsConfiguration { Items = [] }, Entries = new Dictionary(), Mcp = [server] }); + private static McpServerConfiguration Wedged(int connectTimeoutSeconds, int attempts) + { + return new() + { + Id = "wedged", + Transport = McpTransport.Stdio, + Command = ["irrelevant"], + Allow = [new McpAllowEntry { Name = "*" }], + ConnectTimeoutSeconds = connectTimeoutSeconds, + Retry = new McpRetryConfiguration { Attempts = attempts, BackoffMs = 1 }, + }; + } - private static McpServerConfiguration Wedged(int connectTimeoutSeconds, int attempts) - => new() + private static McpServerConfiguration Jira( + int? attempts = null, int? backoffMs = null, int? callTimeoutSeconds = null) { - Id = "wedged", - Transport = McpTransport.Stdio, - Command = ["irrelevant"], - Allow = [new McpAllowEntry { Name = "*" }], - ConnectTimeoutSeconds = connectTimeoutSeconds, - Retry = new McpRetryConfiguration { Attempts = attempts, BackoffMs = 1 }, - }; - - private static McpServerConfiguration Jira( - int? attempts = null, int? backoffMs = null, int? callTimeoutSeconds = null) - => new() + return new() + { + Id = "jira", + Transport = McpTransport.Stdio, + Command = ["irrelevant"], + Allow = [new McpAllowEntry { Name = "*" }], + ConnectTimeoutSeconds = 10, + CallTimeoutSeconds = callTimeoutSeconds, + Retry = attempts is null && backoffMs is null + ? null + : new McpRetryConfiguration { Attempts = attempts, BackoffMs = backoffMs }, + }; + } + + private sealed class OneSource(ToolRegistration registration) : Application.Ports.IToolSource { - Id = "jira", - Transport = McpTransport.Stdio, - Command = ["irrelevant"], - Allow = [new McpAllowEntry { Name = "*" }], - ConnectTimeoutSeconds = 10, - CallTimeoutSeconds = callTimeoutSeconds, - Retry = attempts is null && backoffMs is null - ? null - : new McpRetryConfiguration { Attempts = attempts, BackoffMs = backoffMs }, - }; - - private sealed class OneSource(ToolRegistration registration) : Application.Ports.IToolSource - { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) - => ValueTask.FromResult>([registration]); + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + { + return ValueTask.FromResult>([registration]); + } + } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/McpToolSourceTests.cs b/tests/AgentCore.Infrastructure.Tests/Tools/McpToolSourceTests.cs index 02c31c9e..d5437ada 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/McpToolSourceTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/McpToolSourceTests.cs @@ -3,354 +3,368 @@ using System.Threading.Channels; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Tools; using AgentCore.Infrastructure.Tests.Tools.Fakes; using AgentCore.Infrastructure.Tools; using ModelContextProtocol.Client; using ModelContextProtocol.Protocol; using Xunit; -namespace AgentCore.Infrastructure.Tests.Tools; - -/// -/// Decision 13's mcp: block: connect to a declared server, list what it offers, keep only -/// what allow: pins, and serve the rest under decision 10's naming. -/// -/// -/// Test 7 of the task brief (a document's own description overriding the server's) is intentionally -/// not written. and — the whole -/// shape Task 1 built for mcp: — carry no per-tool description key for a document to write -/// into, so there is nothing to test against. This is a spec gap, not an implementation gap: the -/// server's description is the only source a kind: mcp tool ever gets, MCP makes that -/// description optional (a tool can offer none at all), and a document has no override today. The -/// owner ruled to ship without one — an empty description still fails the boot, just from -/// itself rather than from , because -/// the builder's own message tells a deployer to write a description: the mcp: shape -/// has nowhere to hold. See task-3-report.md. -/// -public sealed class McpToolSourceTests +namespace AgentCore.Infrastructure.Tests.Tools { - private static CancellationToken Token => TestContext.Current.CancellationToken; - - [Fact] - public async Task ProvideAsync_AnAllowedTool_IsServedUnderTheServerDottedName() + /// + /// Decision 13's mcp: block: connect to a declared server, list what it offers, keep only + /// what allow: pins, and serve the rest under decision 10's naming. + /// + /// + /// Test 7 of the task brief (a document's own description overriding the server's) is intentionally + /// not written. and — the whole + /// shape Task 1 built for mcp: — carry no per-tool description key for a document to write + /// into, so there is nothing to test against. This is a spec gap, not an implementation gap: the + /// server's description is the only source a kind: mcp tool ever gets, MCP makes that + /// description optional (a tool can offer none at all), and a document has no override today. The + /// owner ruled to ship without one — an empty description still fails the boot, just from + /// itself rather than from , because + /// the builder's own message tells a deployer to write a description: the mcp: shape + /// has nowhere to hold. See task-3-report.md. + /// + public sealed class McpToolSourceTests { - await using InProcessMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + private static CancellationToken Token => TestContext.Current.CancellationToken; - var registrations = await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token); + [Fact] + public async Task ProvideAsync_AnAllowedTool_IsServedUnderTheServerDottedName() + { + await using InProcessMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - var registration = Assert.Single(registrations); - Assert.Equal("jira.create_issue", registration.Id); - Assert.Equal(InProcessMcpServer.DescriptionOf("create_issue"), registration.Description); - } + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token); - [Fact] - public async Task ProvideAsync_AnAliasedTool_IsServedUnderTheAlias() - { - await using InProcessMcpServer fake = new("search_issues"); - await using McpToolSource source = new(_ => fake.ClientTransport); + ToolRegistration registration = Assert.Single(registrations); + Assert.Equal("jira.create_issue", registration.Id); + Assert.Equal(InProcessMcpServer.DescriptionOf("create_issue"), registration.Description); + } - var registrations = await source.ProvideAsync( - ContextFor(Jira([new McpAllowEntry { Name = "search_issues", As = "find_ticket" }])), Token); + [Fact] + public async Task ProvideAsync_AnAliasedTool_IsServedUnderTheAlias() + { + await using InProcessMcpServer fake = new("search_issues"); + await using McpToolSource source = new(_ => fake.ClientTransport); - var registration = Assert.Single(registrations); - Assert.Equal("find_ticket", registration.Id); - } + IReadOnlyList registrations = await source.ProvideAsync( + ContextFor(Jira([new McpAllowEntry { Name = "search_issues", As = "find_ticket" }])), Token); - [Fact] - public async Task ProvideAsync_AToolTheServerOffersButAllowDoesNot_IsNotServed() - { - await using InProcessMcpServer fake = new("create_issue", "delete_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + ToolRegistration registration = Assert.Single(registrations); + Assert.Equal("find_ticket", registration.Id); + } - var registrations = await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token); + [Fact] + public async Task ProvideAsync_AToolTheServerOffersButAllowDoesNot_IsNotServed() + { + await using InProcessMcpServer fake = new("create_issue", "delete_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - var registration = Assert.Single(registrations); - Assert.Equal("jira.create_issue", registration.Id); - } + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token); - [Fact] - public async Task ProvideAsync_AllowIsStar_ServesEveryToolTheServerOffers() - { - await using InProcessMcpServer fake = new("create_issue", "delete_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + ToolRegistration registration = Assert.Single(registrations); + Assert.Equal("jira.create_issue", registration.Id); + } - var registrations = await source.ProvideAsync(ContextFor(Jira(Allow("*"))), Token); + [Fact] + public async Task ProvideAsync_AllowIsStar_ServesEveryToolTheServerOffers() + { + await using InProcessMcpServer fake = new("create_issue", "delete_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - Assert.Equal(2, registrations.Count); - Assert.Contains(registrations, r => r.Id == "jira.create_issue"); - Assert.Contains(registrations, r => r.Id == "jira.delete_issue"); - } + IReadOnlyList registrations = await source.ProvideAsync(ContextFor(Jira(Allow("*"))), Token); - [Fact] - public async Task ProvideAsync_AnAllowEntryTheServerDoesNotOffer_FailsTheBoot() - { - await using InProcessMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + Assert.Equal(2, registrations.Count); + Assert.Contains(registrations, r => r.Id == "jira.create_issue"); + Assert.Contains(registrations, r => r.Id == "jira.delete_issue"); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(Allow("no_such_tool"))), Token)); + [Fact] + public async Task ProvideAsync_AnAllowEntryTheServerDoesNotOffer_FailsTheBoot() + { + await using InProcessMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - Assert.Contains("no_such_tool", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(Allow("no_such_tool"))), Token)); - [Fact] - public async Task ProvideAsync_AnUnreachableServer_FailsTheBootNamingTheServerAndTheCause() - { - await using McpToolSource source = new(_ => new ThrowingTransport()); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + Assert.Contains("no_such_tool", failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token)); + [Fact] + public async Task ProvideAsync_AnUnreachableServer_FailsTheBootNamingTheServerAndTheCause() + { + await using McpToolSource source = new(_ => new ThrowingTransport()); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token)); - // ToolSourceError.Fail(string) has no room for an inner exception, so the deployer only ever - // learns the real cause if it is folded into the message text itself — the SDK's own - // "Failed to connect transport." says nothing a deployer can act on. - Assert.Contains("No such file or directory", failure.Message, StringComparison.Ordinal); - } + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - /// - /// The server's own tool collection refuses a same-named second entry, so this is the one route - /// left to reproduce a tools/list answer that repeats a name: the listing itself succeeds, - /// and the client's own ToDictionary is what fails afterward. The message must say the - /// listing succeeded, not that the connection "failed before it could list what it offers" — that - /// wording would be false here. - /// - [Fact] - public async Task ProvideAsync_TheServerListsOneNameTwice_FailsTheBootSayingListingSucceeded() - { - await using var fake = InProcessMcpServer.OfferingTheSameToolNameTwice("create_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + // ToolSourceError.Fail(string) has no room for an inner exception, so the deployer only ever + // learns the real cause if it is folded into the message text itself — the SDK's own + // "Failed to connect transport." says nothing a deployer can act on. + Assert.Contains("No such file or directory", failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(Allow("*"))), Token)); + /// + /// The server's own tool collection refuses a same-named second entry, so this is the one route + /// left to reproduce a tools/list answer that repeats a name: the listing itself succeeds, + /// and the client's own ToDictionary is what fails afterward. The message must say the + /// listing succeeded, not that the connection "failed before it could list what it offers" — that + /// wording would be false here. + /// + [Fact] + public async Task ProvideAsync_TheServerListsOneNameTwice_FailsTheBootSayingListingSucceeded() + { + await using InProcessMcpServer fake = InProcessMcpServer.OfferingTheSameToolNameTwice("create_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - Assert.Contains("listed its tools", failure.Message, StringComparison.Ordinal); - Assert.DoesNotContain("failed before it could list", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(Allow("*"))), Token)); - [Fact] - public async Task DisposeAsync_AfterProvide_ClosesTheClient() - { - // Measured against the real SDK: disposing McpClient does not complete the streams a - // StreamClientTransport was given, and a conversation made on a disposed client hangs forever rather - // than failing — neither signal is observable here. - await using InProcessMcpServer fake = new("create_issue"); - DisposalObservingTransport transport = new(fake.ClientTransport); - McpToolSource source = new(_ => transport); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + Assert.Contains("listed its tools", failure.Message, StringComparison.Ordinal); + Assert.DoesNotContain("failed before it could list", failure.Message, StringComparison.Ordinal); + } - await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token); - Assert.False(transport.Disposed); + [Fact] + public async Task DisposeAsync_AfterProvide_ClosesTheClient() + { + // Measured against the real SDK: disposing McpClient does not complete the streams a + // StreamClientTransport was given, and a conversation made on a disposed client hangs forever rather + // than failing — neither signal is observable here. + await using InProcessMcpServer fake = new("create_issue"); + DisposalObservingTransport transport = new(fake.ClientTransport); + McpToolSource source = new(_ => transport); - await source.DisposeAsync(); + _ = await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token); + Assert.False(transport.Disposed); - Assert.True(transport.Disposed); - } + await source.DisposeAsync(); - [Fact] - public async Task ProvideAsync_AToolWithNoDescription_FailsTheBoot() - { - await using var fake = InProcessMcpServer.OfferingAToolWithNoDescription("create_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + Assert.True(transport.Disposed); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token)); + [Fact] + public async Task ProvideAsync_AToolWithNoDescription_FailsTheBoot() + { + await using InProcessMcpServer fake = InProcessMcpServer.OfferingAToolWithNoDescription("create_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - Assert.Contains("create_issue", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(Allow("create_issue"))), Token)); - [Fact] - public async Task ProvideAsync_StarAlongsideANamedEntry_FailsTheBoot() - { - await using InProcessMcpServer fake = new("create_issue", "search_issues"); - await using McpToolSource source = new(_ => fake.ClientTransport); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + Assert.Contains("create_issue", failure.Message, StringComparison.Ordinal); + } - McpAllowEntry[] allow = - [ - new() { Name = "*" }, - new() { Name = "search_issues", As = "find_ticket" }, - ]; + [Fact] + public async Task ProvideAsync_StarAlongsideANamedEntry_FailsTheBoot() + { + await using InProcessMcpServer fake = new("create_issue", "search_issues"); + await using McpToolSource source = new(_ => fake.ClientTransport); - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira(allow)), Token)); + McpAllowEntry[] allow = + [ + new() { Name = "*" }, + new() { Name = "search_issues", As = "find_ticket" }, + ]; - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira(allow)), Token)); - [Fact] - public async Task ProvideAsync_StarWithAnAlias_FailsTheBoot() - { - await using InProcessMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync( - ContextFor(Jira([new McpAllowEntry { Name = "*", As = "everything" }])), Token)); + [Fact] + public async Task ProvideAsync_StarWithAnAlias_FailsTheBoot() + { + await using InProcessMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync( + ContextFor(Jira([new McpAllowEntry { Name = "*", As = "everything" }])), Token)); - [Fact] - public async Task ProvideAsync_EmptyAllow_FailsTheBootNamingTheServer() - { - await using InProcessMcpServer fake = new("create_issue"); - await using McpToolSource source = new(_ => fake.ClientTransport); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + } - var failure = await Assert.ThrowsAsync( - async () => await source.ProvideAsync(ContextFor(Jira([])), Token)); + [Fact] + public async Task ProvideAsync_EmptyAllow_FailsTheBootNamingTheServer() + { + await using InProcessMcpServer fake = new("create_issue"); + await using McpToolSource source = new(_ => fake.ClientTransport); - Assert.Contains("jira", failure.Message, StringComparison.Ordinal); - } + ConfigurationLoadException failure = await Assert.ThrowsAsync( + async () => await source.ProvideAsync(ContextFor(Jira([])), Token)); - /// - /// One client's own DisposeAsync throwing must not abandon the rest, and must not stop - /// _clients.Clear() from running: the host's own shutdown calls DisposeAsync exactly - /// once, but this source's own failure path ( on a later server) already - /// disposes everything once, so a clean second call must find nothing left to re-touch. - /// - [Fact] - public async Task DisposeAsync_WhenOneClientThrows_StillDisposesTheOthersAndStaysIdempotent() - { - await using InProcessMcpServer jiraFake = new("create_issue"); - await using InProcessMcpServer githubFake = new("open_pr"); + Assert.Contains("jira", failure.Message, StringComparison.Ordinal); + } - CountingTransport throwing = new(jiraFake.ClientTransport, throwOnDispose: true); - CountingTransport clean = new(githubFake.ClientTransport); + /// + /// One client's own DisposeAsync throwing must not abandon the rest, and must not stop + /// _clients.Clear() from running: the host's own shutdown calls DisposeAsync exactly + /// once, but this source's own failure path ( on a later server) already + /// disposes everything once, so a clean second call must find nothing left to re-touch. + /// + [Fact] + public async Task DisposeAsync_WhenOneClientThrows_StillDisposesTheOthersAndStaysIdempotent() + { + await using InProcessMcpServer jiraFake = new("create_issue"); + await using InProcessMcpServer githubFake = new("open_pr"); - McpToolSource source = new(server => server.Id == "jira" ? throwing : clean); + CountingTransport throwing = new(jiraFake.ClientTransport, throwOnDispose: true); + CountingTransport clean = new(githubFake.ClientTransport); - await source.ProvideAsync( - ContextFor(Jira(Allow("create_issue")), ServerConfig("github", Allow("*"))), Token); + McpToolSource source = new(server => server.Id == "jira" ? throwing : clean); - var exception = await Record.ExceptionAsync(async () => await source.DisposeAsync()); + _ = await source.ProvideAsync( + ContextFor(Jira(Allow("create_issue")), ServerConfig("github", Allow("*"))), Token); - Assert.Null(exception); - Assert.Equal(1, throwing.DisposeCount); - Assert.Equal(1, clean.DisposeCount); + Exception? exception = await Record.ExceptionAsync(async () => await source.DisposeAsync()); - await source.DisposeAsync(); + Assert.Null(exception); + Assert.Equal(1, throwing.DisposeCount); + Assert.Equal(1, clean.DisposeCount); - Assert.Equal(1, throwing.DisposeCount); - Assert.Equal(1, clean.DisposeCount); - } + await source.DisposeAsync(); - [Fact] - public async Task ProvideAsync_TheSecondServerFails_DisposesTheFirstServersClient() - { - await using InProcessMcpServer fake = new("create_issue"); - DisposalObservingTransport firstTransport = new(fake.ClientTransport); - McpToolSource source = new(server => server.Id == "jira" ? firstTransport : new ThrowingTransport()); + Assert.Equal(1, throwing.DisposeCount); + Assert.Equal(1, clean.DisposeCount); + } - await Assert.ThrowsAsync(async () => await source.ProvideAsync( - ContextFor(Jira(Allow("create_issue")), ServerConfig("github", Allow("*"))), Token)); + [Fact] + public async Task ProvideAsync_TheSecondServerFails_DisposesTheFirstServersClient() + { + await using InProcessMcpServer fake = new("create_issue"); + DisposalObservingTransport firstTransport = new(fake.ClientTransport); + McpToolSource source = new(server => server.Id == "jira" ? firstTransport : new ThrowingTransport()); - Assert.True(firstTransport.Disposed); - } + _ = await Assert.ThrowsAsync(async () => await source.ProvideAsync( + ContextFor(Jira(Allow("create_issue")), ServerConfig("github", Allow("*"))), Token)); - private static McpServerConfiguration Jira(IReadOnlyList allow) - => ServerConfig("jira", allow); + Assert.True(firstTransport.Disposed); + } - private static McpServerConfiguration ServerConfig(string id, IReadOnlyList allow) - => new() + private static McpServerConfiguration Jira(IReadOnlyList allow) { - Id = id, - Transport = McpTransport.Stdio, - Command = [$"{id}-mcp"], - Allow = allow, - }; - - private static McpAllowEntry[] Allow(params string[] names) - => [.. names.Select(name => new McpAllowEntry { Name = name })]; + return ServerConfig("jira", allow); + } - private static ToolSourceContext ContextFor(params McpServerConfiguration[] servers) - => new(new AgentCoreConfiguration + private static McpServerConfiguration ServerConfig(string id, IReadOnlyList allow) { - ApiVersion = "agentcore/v1", - Agents = new AgentsConfiguration { Items = [] }, - Entries = new Dictionary(), - Mcp = servers, - }); - - /// - /// A transport whose connection always fails, wrapping a cause the way a real transport failure - /// (a missing stdio executable) would: the SDK's own message names no cause, and the real one — - /// here, a stand-in for "No such file or directory" — sits in . - /// - private sealed class ThrowingTransport : IClientTransport - { - public string Name => "throwing"; - - public Task ConnectAsync(CancellationToken cancellationToken) - => throw new InvalidOperationException( - "Failed to connect transport.", - new Win32Exception(2, "No such file or directory")); - } + return new() + { + Id = id, + Transport = McpTransport.Stdio, + Command = [$"{id}-mcp"], + Allow = allow, + }; + } - /// Wraps a transport to count how many times the session it connects is disposed, optionally throwing on each. - private sealed class CountingTransport(IClientTransport inner, bool throwOnDispose = false) : IClientTransport - { - public int DisposeCount { get; private set; } + private static McpAllowEntry[] Allow(params string[] names) + { + return [.. names.Select(name => new McpAllowEntry { Name = name })]; + } - public string Name => inner.Name; + private static ToolSourceContext ContextFor(params McpServerConfiguration[] servers) + { + return new(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Agents = new AgentsConfiguration { Items = [] }, + Entries = new Dictionary(), + Mcp = servers, + }); + } - public async Task ConnectAsync(CancellationToken cancellationToken) + /// + /// A transport whose connection always fails, wrapping a cause the way a real transport failure + /// (a missing stdio executable) would: the SDK's own message names no cause, and the real one — + /// here, a stand-in for "No such file or directory" — sits in . + /// + private sealed class ThrowingTransport : IClientTransport { - var session = await inner.ConnectAsync(cancellationToken).ConfigureAwait(false); - return new CountingSession(session, this, throwOnDispose); + public string Name => "throwing"; + + public Task ConnectAsync(CancellationToken cancellationToken) + { + throw new InvalidOperationException( + "Failed to connect transport.", + new Win32Exception(2, "No such file or directory")); + } } - private sealed class CountingSession(ITransport inner, CountingTransport owner, bool throwOnDispose) : ITransport + /// Wraps a transport to count how many times the session it connects is disposed, optionally throwing on each. + private sealed class CountingTransport(IClientTransport inner, bool throwOnDispose = false) : IClientTransport { - public string? SessionId => inner.SessionId; + public int DisposeCount { get; private set; } - public ChannelReader MessageReader => inner.MessageReader; + public string Name => inner.Name; - public Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken) - => inner.SendMessageAsync(message, cancellationToken); + public async Task ConnectAsync(CancellationToken cancellationToken) + { + ITransport session = await inner.ConnectAsync(cancellationToken).ConfigureAwait(false); + return new CountingSession(session, this, throwOnDispose); + } - public async ValueTask DisposeAsync() + private sealed class CountingSession(ITransport inner, CountingTransport owner, bool throwOnDispose) : ITransport { - owner.DisposeCount++; - await inner.DisposeAsync().ConfigureAwait(false); - if (throwOnDispose) + public string? SessionId => inner.SessionId; + + public ChannelReader MessageReader => inner.MessageReader; + + public Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken) + { + return inner.SendMessageAsync(message, cancellationToken); + } + + public async ValueTask DisposeAsync() { - throw new InvalidOperationException("the session failed to close."); + owner.DisposeCount++; + await inner.DisposeAsync().ConfigureAwait(false); + if (throwOnDispose) + { + throw new InvalidOperationException("the session failed to close."); + } } } } - } - /// Wraps a transport to record whether the session it connects is ever disposed. - private sealed class DisposalObservingTransport(IClientTransport inner) : IClientTransport - { - public bool Disposed { get; private set; } + /// Wraps a transport to record whether the session it connects is ever disposed. + private sealed class DisposalObservingTransport(IClientTransport inner) : IClientTransport + { + public bool Disposed { get; private set; } - public string Name => inner.Name; + public string Name => inner.Name; - public async Task ConnectAsync(CancellationToken cancellationToken) - { - var session = await inner.ConnectAsync(cancellationToken).ConfigureAwait(false); - return new ObservedSession(session, () => Disposed = true); - } + public async Task ConnectAsync(CancellationToken cancellationToken) + { + ITransport session = await inner.ConnectAsync(cancellationToken).ConfigureAwait(false); + return new ObservedSession(session, () => Disposed = true); + } - private sealed class ObservedSession(ITransport inner, Action onDisposed) : ITransport - { - public string? SessionId => inner.SessionId; + private sealed class ObservedSession(ITransport inner, Action onDisposed) : ITransport + { + public string? SessionId => inner.SessionId; - public ChannelReader MessageReader => inner.MessageReader; + public ChannelReader MessageReader => inner.MessageReader; - public Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken) - => inner.SendMessageAsync(message, cancellationToken); + public Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken) + { + return inner.SendMessageAsync(message, cancellationToken); + } - public async ValueTask DisposeAsync() - { - onDisposed(); - await inner.DisposeAsync().ConfigureAwait(false); + public async ValueTask DisposeAsync() + { + onDisposed(); + await inner.DisposeAsync().ConfigureAwait(false); + } } } } diff --git a/tests/AgentCore.Infrastructure.Tests/Tools/StubHttpMessageHandler.cs b/tests/AgentCore.Infrastructure.Tests/Tools/StubHttpMessageHandler.cs index d056bb29..afec07ae 100644 --- a/tests/AgentCore.Infrastructure.Tests/Tools/StubHttpMessageHandler.cs +++ b/tests/AgentCore.Infrastructure.Tests/Tools/StubHttpMessageHandler.cs @@ -1,40 +1,43 @@ using System.Net; -namespace AgentCore.Infrastructure.Tests.Tools; - -/// -/// A handler that answers from a script, so the HTTP tool tests reach no network. -/// -/// -/// The tool takes its from its constructor for exactly this reason. It -/// never builds one, so a test decides what the endpoint answers. -/// -internal sealed class StubHttpMessageHandler : HttpMessageHandler +namespace AgentCore.Infrastructure.Tests.Tools { - private readonly Func _answer; - - public StubHttpMessageHandler(Func answer) => _answer = answer; + /// + /// A handler that answers from a script, so the HTTP tool tests reach no network. + /// + /// + /// The tool takes its from its constructor for exactly this reason. It + /// never builds one, so a test decides what the endpoint answers. + /// + internal sealed class StubHttpMessageHandler(Func answer) : HttpMessageHandler + { + private readonly Func _answer = answer; - /// Gets every request this handler saw, in call order. - public List Requests { get; } = []; + /// Gets every request this handler saw, in call order. + public List Requests { get; } = []; - /// Builds a handler that answers one status and one body. - public static StubHttpMessageHandler Answering(HttpStatusCode status, string body, string mediaType = "application/json") - => new(_ => new HttpResponseMessage(status) + /// Builds a handler that answers one status and one body. + public static StubHttpMessageHandler Answering(HttpStatusCode status, string body, string mediaType = "application/json") { - Content = new StringContent(body, System.Text.Encoding.UTF8, mediaType), - }); + return new(_ => new HttpResponseMessage(status) + { + Content = new StringContent(body, System.Text.Encoding.UTF8, mediaType), + }); + } - /// Builds a handler that fails the way fails on a timeout. - public static StubHttpMessageHandler TimingOut() - => new(_ => throw new TaskCanceledException("The request timed out.", new TimeoutException())); + /// Builds a handler that fails the way fails on a timeout. + public static StubHttpMessageHandler TimingOut() + { + return new(_ => throw new TaskCanceledException("The request timed out.", new TimeoutException())); + } - protected override Task SendAsync( - HttpRequestMessage request, - CancellationToken cancellationToken) - { - cancellationToken.ThrowIfCancellationRequested(); - Requests.Add(request); - return Task.FromResult(_answer(request)); + protected override Task SendAsync( + HttpRequestMessage request, + CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); + Requests.Add(request); + return Task.FromResult(_answer(request)); + } } } diff --git a/tests/AgentCore.TestSupport/AssertionMethodAttribute.cs b/tests/AgentCore.TestSupport/AssertionMethodAttribute.cs new file mode 100644 index 00000000..50142b80 --- /dev/null +++ b/tests/AgentCore.TestSupport/AssertionMethodAttribute.cs @@ -0,0 +1,9 @@ +namespace AgentCore.TestSupport +{ + /// + /// Marks a method that asserts on its own, so a test whose only check is a call to it is not + /// reported as a test without assertions (SonarQube S2699 honours any attribute of this name). + /// + [AttributeUsage(AttributeTargets.Method, Inherited = false)] + public sealed class AssertionMethodAttribute : Attribute; +} diff --git a/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs b/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs index f270ea35..629c70dc 100644 --- a/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs +++ b/tests/AgentCore.TestSupport/ConversationStoreReadAll.cs @@ -1,12 +1,15 @@ using AgentCore.Application.Ports; using AgentCore.Application.Transcript; -namespace AgentCore.TestSupport; - -/// The oracle read a test wants: every row somebody said, oldest first. -public static class ConversationStoreReadAll +namespace AgentCore.TestSupport { - public static ValueTask> ReadAllAsync( - this IConversationStore store, string conversationId, CancellationToken cancellationToken = default) - => store.ReadWindowAsync(conversationId, new TranscriptWindow(null, int.MaxValue), cancellationToken); + /// The oracle read a test wants: every row somebody said, oldest first. + public static class ConversationStoreReadAll + { + public static ValueTask> ReadAllAsync( + this IConversationStore store, string conversationId, CancellationToken cancellationToken = default) + { + return store.ReadWindowAsync(conversationId, new TranscriptWindow(null, int.MaxValue), cancellationToken); + } + } } diff --git a/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs b/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs index 6c8898dc..33e1aa68 100644 --- a/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs +++ b/tests/AgentCore.TestSupport/ConversationStoreSummaryRowFacts.cs @@ -2,144 +2,156 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// What every store 1 must do with a summary row: hand it to the session's read alone, leave it out -/// of every consumer read, and take it on a truncate only when the cut reaches a row it covers. -/// Each store's test class runs these against its own instance. This project carries no test -/// framework, so a fact that fails throws naming what it saw. -/// -public static class ConversationStoreSummaryRowFacts +namespace AgentCore.TestSupport { /// - /// Seeds three plain turns (ordinals 0-5), a summary over 0-3 at ordinal 6, a fourth turn - /// (7-8), a second summary over 0-5 at ordinal 9, and a fifth turn (10-11). + /// What every store 1 must do with a summary row: hand it to the session's read alone, leave it out + /// of every consumer read, and take it on a truncate only when the cut reaches a row it covers. + /// Each store's test class runs these against its own instance. This project carries no test + /// framework, so a fact that fails throws naming what it saw. /// - public static async Task SeedAsync(IConversationStore store, CancellationToken cancellationToken) + public static class ConversationStoreSummaryRowFacts { - await store.CreateAsync("c1", cancellationToken); - await TurnAsync(store, 0, cancellationToken); - await TurnAsync(store, 1, cancellationToken); - await TurnAsync(store, 2, cancellationToken); - await SummaryAsync(store, turnIndex: 3, "first summary", coversUpTo: 3, cancellationToken); - await TurnAsync(store, 3, cancellationToken); - await SummaryAsync(store, turnIndex: 4, "second summary", coversUpTo: 5, cancellationToken); - await TurnAsync(store, 4, cancellationToken); - } + /// + /// Seeds three plain turns (ordinals 0-5), a summary over 0-3 at ordinal 6, a fourth turn + /// (7-8), a second summary over 0-5 at ordinal 9, and a fifth turn (10-11). + /// + public static async Task SeedAsync(IConversationStore store, CancellationToken cancellationToken) + { + _ = await store.CreateAsync("c1", cancellationToken); + await TurnAsync(store, 0, cancellationToken); + await TurnAsync(store, 1, cancellationToken); + await TurnAsync(store, 2, cancellationToken); + await SummaryAsync(store, turnIndex: 3, "first summary", coversUpTo: 3, cancellationToken); + await TurnAsync(store, 3, cancellationToken); + await SummaryAsync(store, turnIndex: 4, "second summary", coversUpTo: 5, cancellationToken); + await TurnAsync(store, 4, cancellationToken); + } - public static async Task SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(IConversationStore store, CancellationToken cancellationToken) - { - await SeedAsync(store, cancellationToken); + [AssertionMethod] + public static async Task SessionReadHandsBackTheNewestSummaryAndTheRowsAboveWhatItCovers(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); - var rows = await store.ReadForSessionAsync("c1", cancellationToken); + IReadOnlyList rows = await store.ReadForSessionAsync("c1", cancellationToken); - ExpectOrdinals([7, 8, 9, 10, 11], rows, "the session read"); - var summary = rows.Single(row => row.CoversUpTo is not null); - Expect("9/5/second summary", $"{summary.Ordinal}/{summary.CoversUpTo}/{summary.Content.Text}", "the summary the session read"); - } + ExpectOrdinals([7, 8, 9, 10, 11], rows, "the session read"); + ConversationMessage summary = rows.Single(row => row.CoversUpTo is not null); + Expect("9/5/second summary", $"{summary.Ordinal}/{summary.CoversUpTo}/{summary.Content.Text}", "the summary the session read"); + } - public static async Task SessionReadWithNoSummaryHandsBackEveryRow(IConversationStore store, CancellationToken cancellationToken) - { - await store.CreateAsync("c1", cancellationToken); - await TurnAsync(store, 0, cancellationToken); - await TurnAsync(store, 1, cancellationToken); + [AssertionMethod] + public static async Task SessionReadWithNoSummaryHandsBackEveryRow(IConversationStore store, CancellationToken cancellationToken) + { + _ = await store.CreateAsync("c1", cancellationToken); + await TurnAsync(store, 0, cancellationToken); + await TurnAsync(store, 1, cancellationToken); - ExpectOrdinals([0, 1, 2, 3], await store.ReadForSessionAsync("c1", cancellationToken), "the session read"); - } + ExpectOrdinals([0, 1, 2, 3], await store.ReadForSessionAsync("c1", cancellationToken), "the session read"); + } - public static async Task ConsumerReadsLeaveEverySummaryOut(IConversationStore store, CancellationToken cancellationToken) - { - await SeedAsync(store, cancellationToken); + [AssertionMethod] + public static async Task ConsumerReadsLeaveEverySummaryOut(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); - ExpectOrdinals([0, 1, 2, 3, 4, 5, 7, 8, 10, 11], await store.ReadAllAsync("c1", cancellationToken), "ReadAsync"); - ExpectOrdinals([7, 8, 10, 11], await store.ReadWindowAsync("c1", new TranscriptWindow(null, 2), cancellationToken), "ReadWindowAsync(2 turns)"); - } + ExpectOrdinals([0, 1, 2, 3, 4, 5, 7, 8, 10, 11], await store.ReadAllAsync("c1", cancellationToken), "ReadAsync"); + ExpectOrdinals([7, 8, 10, 11], await store.ReadWindowAsync("c1", new TranscriptWindow(null, 2), cancellationToken), "ReadWindowAsync(2 turns)"); + } - public static async Task TruncateUnderWhatTheSummaryCoversTakesTheSummary(IConversationStore store, CancellationToken cancellationToken) - { - await SeedAsync(store, cancellationToken); + [AssertionMethod] + public static async Task TruncateUnderWhatTheSummaryCoversTakesTheSummary(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); - // Cut at 4: rows 4-5 go, and so does the second summary (covers 5 >= 4). The first summary - // (covers 3 < 4) stays, and the session read falls back to it. - var went = await store.TruncateAsync("c1", 4, cancellationToken); + // Cut at 4: rows 4-5 go, and so does the second summary (covers 5 >= 4). The first summary + // (covers 3 < 4) stays, and the session read falls back to it. + ConversationCut went = await store.TruncateAsync("c1", 4, cancellationToken); - Expect("7", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 4 took"); - Expect("2-4", Turns(went), "turns the cut at 4 took"); - var rows = await store.ReadForSessionAsync("c1", cancellationToken); - ExpectOrdinals([6], rows, "the session read after the cut at 4"); - Expect("3", rows[0].CoversUpTo?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "what the standing summary covers"); - } + Expect("7", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 4 took"); + Expect("2-4", Turns(went), "turns the cut at 4 took"); + IReadOnlyList rows = await store.ReadForSessionAsync("c1", cancellationToken); + ExpectOrdinals([6], rows, "the session read after the cut at 4"); + Expect("3", rows[0].CoversUpTo?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "what the standing summary covers"); + } - public static async Task TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(IConversationStore store, CancellationToken cancellationToken) - { - await SeedAsync(store, cancellationToken); + [AssertionMethod] + public static async Task TruncateAboveWhatTheSummaryCoversKeepsTheSummaryWhateverItsOrdinal(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); - // Cut at 7: rows 7-8 and 10-11 go. Both summaries sit at ordinals >= 7 but cover rows < 7, so both stay. - var went = await store.TruncateAsync("c1", 7, cancellationToken); + // Cut at 7: rows 7-8 and 10-11 go. Both summaries sit at ordinals >= 7 but cover rows < 7, so both stay. + ConversationCut went = await store.TruncateAsync("c1", 7, cancellationToken); - Expect("4", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 7 took"); - Expect("3-4", Turns(went), "turns the cut at 7 took"); - ExpectOrdinals([9], await store.ReadForSessionAsync("c1", cancellationToken), "the session read after the cut at 7"); - ExpectOrdinals([0, 1, 2, 3, 4, 5], await store.ReadAllAsync("c1", cancellationToken), "ReadAsync after the cut at 7"); - } + Expect("4", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 7 took"); + Expect("3-4", Turns(went), "turns the cut at 7 took"); + ExpectOrdinals([9], await store.ReadForSessionAsync("c1", cancellationToken), "the session read after the cut at 7"); + ExpectOrdinals([0, 1, 2, 3, 4, 5], await store.ReadAllAsync("c1", cancellationToken), "ReadAsync after the cut at 7"); + } - public static async Task TruncateAboveTheSummaryLeavesEverythingUnderItAlone(IConversationStore store, CancellationToken cancellationToken) - { - await SeedAsync(store, cancellationToken); + [AssertionMethod] + public static async Task TruncateAboveTheSummaryLeavesEverythingUnderItAlone(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); - var went = await store.TruncateAsync("c1", 10, cancellationToken); + ConversationCut went = await store.TruncateAsync("c1", 10, cancellationToken); - Expect("2", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 10 took"); - Expect("4-4", Turns(went), "turns the cut at 10 took"); - ExpectOrdinals([7, 8, 9], await store.ReadForSessionAsync("c1", cancellationToken), "the session read after the cut at 10"); + Expect("2", went.Rows.ToString(System.Globalization.CultureInfo.InvariantCulture), "rows the cut at 10 took"); + Expect("4-4", Turns(went), "turns the cut at 10 took"); + ExpectOrdinals([7, 8, 9], await store.ReadForSessionAsync("c1", cancellationToken), "the session read after the cut at 10"); - // Nothing left above 10: a second cut there takes no row and names no turn. - var again = await store.TruncateAsync("c1", 10, cancellationToken); - Expect("0/none", $"{again.Rows}/{Turns(again)}", "a cut with nothing above it"); - } + // Nothing left above 10: a second cut there takes no row and names no turn. + ConversationCut again = await store.TruncateAsync("c1", 10, cancellationToken); + Expect("0/none", $"{again.Rows}/{Turns(again)}", "a cut with nothing above it"); + } - public static async Task OrdinalOfFindsASpokenRowAndNotASummary(IConversationStore store, CancellationToken cancellationToken) - { - await SeedAsync(store, cancellationToken); + [AssertionMethod] + public static async Task OrdinalOfFindsASpokenRowAndNotASummary(IConversationStore store, CancellationToken cancellationToken) + { + await SeedAsync(store, cancellationToken); - Expect("5", (await store.OrdinalOfAsync("c1", "m-2-a", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of turn 2's reply"); - Expect("null", (await store.OrdinalOfAsync("c1", "s-5", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of a summary row"); - Expect("null", (await store.OrdinalOfAsync("c1", "nobody", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of a message nobody said"); - } + Expect("5", (await store.OrdinalOfAsync("c1", "m-2-a", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of turn 2's reply"); + Expect("null", (await store.OrdinalOfAsync("c1", "s-5", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of a summary row"); + Expect("null", (await store.OrdinalOfAsync("c1", "nobody", cancellationToken))?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "null", "the ordinal of a message nobody said"); + } - private static string Turns(ConversationCut cut) - => cut.Turns is { } turns ? $"{turns.First}-{turns.Last}" : "none"; + private static string Turns(ConversationCut cut) + { + return cut.Turns is { } turns ? $"{turns.First}-{turns.Last}" : "none"; + } - private static void ExpectOrdinals(int[] expected, IReadOnlyList rows, string what) - => Expect(string.Join(",", expected), string.Join(",", rows.Select(row => row.Ordinal)), what); + private static void ExpectOrdinals(int[] expected, IReadOnlyList rows, string what) + { + Expect(string.Join(",", expected), string.Join(",", rows.Select(row => row.Ordinal)), what); + } - private static void Expect(string expected, string actual, string what) - { - if (!string.Equals(expected, actual, StringComparison.Ordinal)) + private static void Expect(string expected, string actual, string what) { - throw new InvalidOperationException($"{what}: expected [{expected}], got [{actual}]."); + if (!string.Equals(expected, actual, StringComparison.Ordinal)) + { + throw new InvalidOperationException($"{what}: expected [{expected}], got [{actual}]."); + } } - } - private static async Task TurnAsync(IConversationStore store, int turnIndex, CancellationToken cancellationToken) - { - await store.AppendAsync( - "c1", - [ - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, $"q{turnIndex}"), $"m-{turnIndex}-q"), - new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, $"a{turnIndex}"), $"m-{turnIndex}-a"), - ], - state: null, - cancellationToken); - } + private static async Task TurnAsync(IConversationStore store, int turnIndex, CancellationToken cancellationToken) + { + _ = await store.AppendAsync( + "c1", + [ + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.User, $"q{turnIndex}"), $"m-{turnIndex}-q"), + new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, $"a{turnIndex}"), $"m-{turnIndex}-a"), + ], + state: null, + cancellationToken); + } - private static async Task SummaryAsync(IConversationStore store, int turnIndex, string text, int coversUpTo, CancellationToken cancellationToken) - { - await store.AppendAsync( - "c1", - [new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, text), $"s-{coversUpTo}") { CoversUpTo = coversUpTo }], - state: null, - cancellationToken); + private static async Task SummaryAsync(IConversationStore store, int turnIndex, string text, int coversUpTo, CancellationToken cancellationToken) + { + _ = await store.AppendAsync( + "c1", + [new ConversationMessageDraft(turnIndex, new ChatMessage(ChatRole.Assistant, text), $"s-{coversUpTo}") { CoversUpTo = coversUpTo }], + state: null, + cancellationToken); + } } } diff --git a/tests/AgentCore.TestSupport/DelegatingConversationStore.cs b/tests/AgentCore.TestSupport/DelegatingConversationStore.cs index 5e753fb1..6873f3e2 100644 --- a/tests/AgentCore.TestSupport/DelegatingConversationStore.cs +++ b/tests/AgentCore.TestSupport/DelegatingConversationStore.cs @@ -4,125 +4,168 @@ using AgentCore.Application.Transcript; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// A store that forwards every call to another one, so a fake overrides only what it is testing. -/// -/// Where an un-overridden conversation goes. -public abstract class DelegatingConversationStore(IConversationStore inner) : IConversationStore +namespace AgentCore.TestSupport { - /// Gets the store behind this one. - protected IConversationStore Inner { get; } = inner; - - /// - public virtual ValueTask CreateAsync( - string conversationId, CancellationToken cancellationToken = default) - => Inner.CreateAsync(conversationId, cancellationToken); - - /// - public virtual ValueTask GetAsync( - string conversationId, CancellationToken cancellationToken = default) - => Inner.GetAsync(conversationId, cancellationToken); - - /// - public virtual ValueTask ListAsync( - string principalKey, - string? after, - int limit, - ConversationStatus? status = null, - CancellationToken cancellationToken = default) - => Inner.ListAsync(principalKey, after, limit, status, cancellationToken); - - /// - public virtual ValueTask RenameAsync( - string conversationId, string title, CancellationToken cancellationToken = default) - => Inner.RenameAsync(conversationId, title, cancellationToken); - - /// - public virtual ValueTask SetStatusAsync( - string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) - => Inner.SetStatusAsync(conversationId, status, cancellationToken); - - /// - public virtual ValueTask SetCustomAsync( - string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) - => Inner.SetCustomAsync(conversationId, custom, cancellationToken); - - /// - public virtual ValueTask SetExternalIdAsync( - string conversationId, string? externalId, CancellationToken cancellationToken = default) - => Inner.SetExternalIdAsync(conversationId, externalId, cancellationToken); - - /// - public virtual ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) - => Inner.DeleteAsync(conversationId, cancellationToken); - - /// - public virtual ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - => Inner.AppendAsync(conversationId, messages, state, cancellationToken); - - /// - public virtual ValueTask RewriteAsync( - string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) - => Inner.RewriteAsync(conversationId, messageId, content, cancellationToken); - - /// - public virtual ValueTask> ReadForSessionAsync( - string conversationId, CancellationToken cancellationToken = default) - => Inner.ReadForSessionAsync(conversationId, cancellationToken); - - /// - public virtual ValueTask> ReadWindowAsync( - string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) - => Inner.ReadWindowAsync(conversationId, window, cancellationToken); - - /// - public virtual ValueTask OrdinalOfAsync( - string conversationId, string messageId, CancellationToken cancellationToken = default) - => Inner.OrdinalOfAsync(conversationId, messageId, cancellationToken); - - /// - public virtual ValueTask TruncateAsync( - string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) - => Inner.TruncateAsync(conversationId, fromOrdinal, cancellationToken); - - /// - public virtual ValueTask EraseAsync( - string conversationId, CancellationToken cancellationToken = default) - => Inner.EraseAsync(conversationId, cancellationToken); - - /// - public virtual ValueTask SweepAsync( - TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) - => Inner.SweepAsync(retention, batchSize, cancellationToken); - - /// - public virtual ValueTask AttachPrincipalAsync( - string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) - => Inner.AttachPrincipalAsync(conversationId, principalKey, role, cancellationToken); - - /// - public virtual ValueTask DetachPrincipalAsync( - string conversationId, string principalKey, CancellationToken cancellationToken = default) - => Inner.DetachPrincipalAsync(conversationId, principalKey, cancellationToken); - - /// - public virtual ValueTask SaveContinuationAsync( - string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) - => Inner.SaveContinuationAsync(continuationId, envelope, cancellationToken); - - /// - public virtual ValueTask GetContinuationAsync( - string continuationId, CancellationToken cancellationToken = default) - => Inner.GetContinuationAsync(continuationId, cancellationToken); - - /// - public virtual ValueTask DeleteContinuationAsync( - string continuationId, CancellationToken cancellationToken = default) - => Inner.DeleteContinuationAsync(continuationId, cancellationToken); + /// + /// A store that forwards every call to another one, so a fake overrides only what it is testing. + /// + /// Where an un-overridden conversation goes. + public abstract class DelegatingConversationStore(IConversationStore inner) : IConversationStore + { + /// Gets the store behind this one. + protected IConversationStore Inner { get; } = inner; + + /// + public virtual ValueTask CreateAsync( + string conversationId, CancellationToken cancellationToken = default) + { + return Inner.CreateAsync(conversationId, cancellationToken); + } + + /// + public virtual ValueTask GetAsync( + string conversationId, CancellationToken cancellationToken = default) + { + return Inner.GetAsync(conversationId, cancellationToken); + } + + /// + public virtual ValueTask ListAsync( + string principalKey, + string? after, + int limit, + ConversationStatus? status = null, + CancellationToken cancellationToken = default) + { + return Inner.ListAsync(principalKey, after, limit, status, cancellationToken); + } + + /// + public virtual ValueTask RenameAsync( + string conversationId, string title, CancellationToken cancellationToken = default) + { + return Inner.RenameAsync(conversationId, title, cancellationToken); + } + + /// + public virtual ValueTask SetStatusAsync( + string conversationId, ConversationStatus status, CancellationToken cancellationToken = default) + { + return Inner.SetStatusAsync(conversationId, status, cancellationToken); + } + + /// + public virtual ValueTask SetCustomAsync( + string conversationId, JsonElement? custom, CancellationToken cancellationToken = default) + { + return Inner.SetCustomAsync(conversationId, custom, cancellationToken); + } + + /// + public virtual ValueTask SetExternalIdAsync( + string conversationId, string? externalId, CancellationToken cancellationToken = default) + { + return Inner.SetExternalIdAsync(conversationId, externalId, cancellationToken); + } + + /// + public virtual ValueTask DeleteAsync(string conversationId, CancellationToken cancellationToken = default) + { + return Inner.DeleteAsync(conversationId, cancellationToken); + } + + /// + public virtual ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + return Inner.AppendAsync(conversationId, messages, state, cancellationToken); + } + + /// + public virtual ValueTask RewriteAsync( + string conversationId, string messageId, ChatMessage content, CancellationToken cancellationToken = default) + { + return Inner.RewriteAsync(conversationId, messageId, content, cancellationToken); + } + + /// + public virtual ValueTask> ReadForSessionAsync( + string conversationId, CancellationToken cancellationToken = default) + { + return Inner.ReadForSessionAsync(conversationId, cancellationToken); + } + + /// + public virtual ValueTask> ReadWindowAsync( + string conversationId, TranscriptWindow window, CancellationToken cancellationToken = default) + { + return Inner.ReadWindowAsync(conversationId, window, cancellationToken); + } + + /// + public virtual ValueTask OrdinalOfAsync( + string conversationId, string messageId, CancellationToken cancellationToken = default) + { + return Inner.OrdinalOfAsync(conversationId, messageId, cancellationToken); + } + + /// + public virtual ValueTask TruncateAsync( + string conversationId, int fromOrdinal, CancellationToken cancellationToken = default) + { + return Inner.TruncateAsync(conversationId, fromOrdinal, cancellationToken); + } + + /// + public virtual ValueTask EraseAsync( + string conversationId, CancellationToken cancellationToken = default) + { + return Inner.EraseAsync(conversationId, cancellationToken); + } + + /// + public virtual ValueTask SweepAsync( + TimeSpan retention, int batchSize = 500, CancellationToken cancellationToken = default) + { + return Inner.SweepAsync(retention, batchSize, cancellationToken); + } + + /// + public virtual ValueTask AttachPrincipalAsync( + string conversationId, string principalKey, string role, CancellationToken cancellationToken = default) + { + return Inner.AttachPrincipalAsync(conversationId, principalKey, role, cancellationToken); + } + + /// + public virtual ValueTask DetachPrincipalAsync( + string conversationId, string principalKey, CancellationToken cancellationToken = default) + { + return Inner.DetachPrincipalAsync(conversationId, principalKey, cancellationToken); + } + + /// + public virtual ValueTask SaveContinuationAsync( + string continuationId, JsonElement envelope, CancellationToken cancellationToken = default) + { + return Inner.SaveContinuationAsync(continuationId, envelope, cancellationToken); + } + + /// + public virtual ValueTask GetContinuationAsync( + string continuationId, CancellationToken cancellationToken = default) + { + return Inner.GetContinuationAsync(continuationId, cancellationToken); + } + + /// + public virtual ValueTask DeleteContinuationAsync( + string continuationId, CancellationToken cancellationToken = default) + { + return Inner.DeleteContinuationAsync(continuationId, cancellationToken); + } + } } diff --git a/tests/AgentCore.TestSupport/FakeTimeProvider.cs b/tests/AgentCore.TestSupport/FakeTimeProvider.cs index b94dc228..5dc4b39a 100644 --- a/tests/AgentCore.TestSupport/FakeTimeProvider.cs +++ b/tests/AgentCore.TestSupport/FakeTimeProvider.cs @@ -1,138 +1,137 @@ -namespace AgentCore.TestSupport; - -/// -/// A clock a test owns, including every timer a production seam schedules against it. -/// -/// -/// -/// A seam that bounds a deadline with Task.Delay(delay, timeProvider, cancellationToken) — -/// the relay connection's idle deadline is the case this was written for — arms -/// its completion through , not through -/// . A fake that only overrode GetUtcNow would leave -/// that timer running on the real clock underneath it, so a test would still have to sleep for the -/// real delay. Overriding here is what lets fire a -/// due timer synchronously, with no wall-clock wait at all. -/// -/// -/// Every timer this class hands out is one-shot in practice — the idle deadline is the only -/// production caller today, and it always asks for as its -/// period — but still reschedules a periodic timer for its next due time, -/// so a future caller that does ask for a period is not silently starved. -/// -/// -public sealed class FakeTimeProvider : TimeProvider +namespace AgentCore.TestSupport { - private readonly Lock _gate = new(); - private readonly List _timers = []; - private DateTimeOffset _now; - - public FakeTimeProvider(DateTimeOffset start) => _now = start; - - public override DateTimeOffset GetUtcNow() + /// + /// A clock a test owns, including every timer a production seam schedules against it. + /// + /// + /// + /// A seam that bounds a deadline with Task.Delay(delay, timeProvider, cancellationToken) — + /// the relay connection's idle deadline is the case this was written for — arms + /// its completion through , not through + /// . A fake that only overrode GetUtcNow would leave + /// that timer running on the real clock underneath it, so a test would still have to sleep for the + /// real delay. Overriding here is what lets fire a + /// due timer synchronously, with no wall-clock wait at all. + /// + /// + /// Every timer this class hands out is one-shot in practice — the idle deadline is the only + /// production caller today, and it always asks for as its + /// period — but still reschedules a periodic timer for its next due time, + /// so a future caller that does ask for a period is not silently starved. + /// + /// + public sealed class FakeTimeProvider(DateTimeOffset start) : TimeProvider { - lock (_gate) + private readonly Lock _gate = new(); + private readonly List _timers = []; + private DateTimeOffset _now = start; + + public override DateTimeOffset GetUtcNow() { - return _now; + lock (_gate) + { + return _now; + } } - } - - public override ITimer CreateTimer(TimerCallback callback, object? state, TimeSpan dueTime, TimeSpan period) - { - ArgumentNullException.ThrowIfNull(callback); - var timer = new FakeTimer(this, callback, state); - lock (_gate) + public override ITimer CreateTimer(TimerCallback callback, object? state, TimeSpan dueTime, TimeSpan period) { - timer.DueAt = _now + dueTime; - timer.Period = period; - _timers.Add(timer); - } + ArgumentNullException.ThrowIfNull(callback); - return timer; - } + FakeTimer timer = new(this, callback, state); + lock (_gate) + { + timer.DueAt = _now + dueTime; + timer.Period = period; + _timers.Add(timer); + } - /// Moves the clock forward, and fires every timer whose due time this reaches or passes. - /// How far to move the clock. - /// - /// Firing happens outside the lock: a timer's own callback here is - /// , which can run a caller's registered - /// callback synchronously, and nothing this class does may still hold - /// when a caller's own code starts running under it. - /// - public void Advance(TimeSpan delta) - { - List due; - lock (_gate) - { - _now += delta; - due = [.. _timers.Where(timer => !timer.Disposed && timer.DueAt <= _now)]; + return timer; } - foreach (var timer in due) + /// Moves the clock forward, and fires every timer whose due time this reaches or passes. + /// How far to move the clock. + /// + /// Firing happens outside the lock: a timer's own callback here is + /// , which can run a caller's registered + /// callback synchronously, and nothing this class does may still hold + /// when a caller's own code starts running under it. + /// + public void Advance(TimeSpan delta) { - timer.Fire(); + List due; + lock (_gate) + { + _now += delta; + due = [.. _timers.Where(timer => !timer.Disposed && timer.DueAt <= _now)]; + } + + foreach (FakeTimer timer in due) + { + timer.Fire(); + } } - } - private void Remove(FakeTimer timer) - { - lock (_gate) + private void Remove(FakeTimer timer) { - _timers.Remove(timer); + lock (_gate) + { + _ = _timers.Remove(timer); + } } - } - private sealed class FakeTimer(FakeTimeProvider owner, TimerCallback callback, object? state) : ITimer - { - public DateTimeOffset DueAt { get; set; } + private sealed class FakeTimer(FakeTimeProvider owner, TimerCallback callback, object? state) : ITimer + { + public DateTimeOffset DueAt { get; set; } - public TimeSpan Period { get; set; } + public TimeSpan Period { get; set; } - public bool Disposed { get; private set; } + public bool Disposed { get; private set; } - /// Runs the callback, and reschedules only when this timer asked for a period. - public void Fire() - { - if (Disposed) + /// Runs the callback, and reschedules only when this timer asked for a period. + public void Fire() { - return; + if (Disposed) + { + return; + } + + if (Period == Timeout.InfiniteTimeSpan || Period == TimeSpan.Zero) + { + owner.Remove(this); + Disposed = true; + } + else + { + DueAt = owner.GetUtcNow() + Period; + } + + callback(state); } - if (Period == Timeout.InfiniteTimeSpan || Period == TimeSpan.Zero) + public bool Change(TimeSpan dueTime, TimeSpan period) { - owner.Remove(this); - Disposed = true; + if (Disposed) + { + return false; + } + + DueAt = owner.GetUtcNow() + dueTime; + Period = period; + return true; } - else + + public void Dispose() { - DueAt = owner.GetUtcNow() + Period; + Disposed = true; + owner.Remove(this); } - callback(state); - } - - public bool Change(TimeSpan dueTime, TimeSpan period) - { - if (Disposed) + public ValueTask DisposeAsync() { - return false; + Dispose(); + return ValueTask.CompletedTask; } - - DueAt = owner.GetUtcNow() + dueTime; - Period = period; - return true; - } - - public void Dispose() - { - Disposed = true; - owner.Remove(this); - } - - public ValueTask DisposeAsync() - { - Dispose(); - return ValueTask.CompletedTask; } } } diff --git a/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs b/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs index f8e980f1..6d9ccf79 100644 --- a/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs +++ b/tests/AgentCore.TestSupport/LambdaChatClientFactory.cs @@ -2,30 +2,34 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// A factory whose two seams are lambdas, for a test that needs one odd answer — a factory that -/// throws, or one that admits a hosted tool for one model only — without a class of its own. -/// -public sealed class LambdaChatClientFactory : IChatClientFactory +namespace AgentCore.TestSupport { - private readonly Func _client; - private readonly Func _hostedTool; - + /// + /// A factory whose two seams are lambdas, for a test that needs one odd answer — a factory that + /// throws, or one that admits a hosted tool for one model only — without a class of its own. + /// /// Answers . Omitted, every call throws. /// Answers . Omitted, no model admits a hosted tool. - public LambdaChatClientFactory( + public sealed class LambdaChatClientFactory( Func? client = null, - Func? hostedTool = null) + Func? hostedTool = null) : IChatClientFactory { - _client = client ?? (_ => throw new NotSupportedException()); - _hostedTool = hostedTool ?? ((_, _) => null); - } + private readonly Func _client = client ?? (_ => throw new NotSupportedException()); + private readonly Func _hostedTool = hostedTool ?? ((_, _) => null); - public IChatClient GetChatClient(ModelReference? model) => _client(model); + public IChatClient GetChatClient(ModelReference? model) + { + return _client(model); + } - public AITool? ResolveHostedTool(AITool marker, ModelReference? model) => _hostedTool(marker, model); + public AITool? ResolveHostedTool(AITool marker, ModelReference? model) + { + return _hostedTool(marker, model); + } - public int? GetContextWindow(ModelReference? model) => 128_000; + public int? GetContextWindow(ModelReference? model) + { + return 128_000; + } + } } diff --git a/tests/AgentCore.TestSupport/MapSecretResolver.cs b/tests/AgentCore.TestSupport/MapSecretResolver.cs index edc185e4..39f61060 100644 --- a/tests/AgentCore.TestSupport/MapSecretResolver.cs +++ b/tests/AgentCore.TestSupport/MapSecretResolver.cs @@ -1,28 +1,29 @@ using AgentCore.Application.Ports; -namespace AgentCore.TestSupport; - -/// -/// A resolver that holds a map of names to values, and remembers what it was asked for. -/// -public sealed class MapSecretResolver : ISecretResolverPort +namespace AgentCore.TestSupport { - private readonly Dictionary _values = new(StringComparer.Ordinal); + /// + /// A resolver that holds a map of names to values, and remembers what it was asked for. + /// + public sealed class MapSecretResolver : ISecretResolverPort + { + private readonly Dictionary _values = new(StringComparer.Ordinal); - /// Gets every name this resolver was asked for, in call order. - public List Asked { get; } = []; + /// Gets every name this resolver was asked for, in call order. + public List Asked { get; } = []; - /// Adds one name and its value, and returns this resolver. - public MapSecretResolver With(string name, string value) - { - _values[name] = value; - return this; - } + /// Adds one name and its value, and returns this resolver. + public MapSecretResolver With(string name, string value) + { + _values[name] = value; + return this; + } - /// - public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) - { - Asked.Add(name); - return ValueTask.FromResult(_values.TryGetValue(name, out var value) ? value : null); + /// + public ValueTask TryResolveAsync(string name, CancellationToken cancellationToken = default) + { + Asked.Add(name); + return ValueTask.FromResult(_values.TryGetValue(name, out string? value) ? value : null); + } } } diff --git a/tests/AgentCore.TestSupport/ParkingConversationStore.cs b/tests/AgentCore.TestSupport/ParkingConversationStore.cs index f14a732f..e7f1f156 100644 --- a/tests/AgentCore.TestSupport/ParkingConversationStore.cs +++ b/tests/AgentCore.TestSupport/ParkingConversationStore.cs @@ -1,43 +1,46 @@ using AgentCore.Application.Conversation; using AgentCore.Application.Conversation.Memory; using AgentCore.Application.Transcript; -using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// A store that holds its first write of words open until a test releases it. -/// -/// -/// A real store talks to a database, so a write outlives the turn that queued it. The memory store -/// every other test runs on lands a write before the next line reads it, and would let teardown drop -/// a session with a write still owing without any test noticing. -/// -public sealed class ParkingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) +namespace AgentCore.TestSupport { - private readonly TaskCompletionSource _entered = new(TaskCreationOptions.RunContinuationsAsynchronously); - private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); - private volatile bool _landed; + /// + /// A store that holds its first write of words open until a test releases it. + /// + /// + /// A real store talks to a database, so a write outlives the turn that queued it. The memory store + /// every other test runs on lands a write before the next line reads it, and would let teardown drop + /// a session with a write still owing without any test noticing. + /// + public sealed class ParkingConversationStore() : DelegatingConversationStore(new InMemoryConversationStore()) + { + private readonly TaskCompletionSource _entered = new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously); + private volatile bool _landed; - /// Gets a task that completes once the first append is parked. - public Task Parked => _entered.Task; + /// Gets a task that completes once the first append is parked. + public Task Parked => _entered.Task; - /// Gets whether the parked append has finished writing. - public bool Landed => _landed; + /// Gets whether the parked append has finished writing. + public bool Landed => _landed; - /// Lets the parked append finish. - public void Release() => _release.TrySetResult(); + /// Lets the parked append finish. + public void Release() + { + _ = _release.TrySetResult(); + } - /// - public override async ValueTask> AppendAsync( - string conversationId, - IReadOnlyList messages, - ConversationSessionState? state = null, - CancellationToken cancellationToken = default) - { - _entered.TrySetResult(); - await _release.Task.WaitAsync(cancellationToken); - _landed = true; - return await base.AppendAsync(conversationId, messages, state, cancellationToken); + /// + public override async ValueTask> AppendAsync( + string conversationId, + IReadOnlyList messages, + ConversationSessionState? state = null, + CancellationToken cancellationToken = default) + { + _ = _entered.TrySetResult(); + await _release.Task.WaitAsync(cancellationToken); + _landed = true; + return await base.AppendAsync(conversationId, messages, state, cancellationToken); + } } -} \ No newline at end of file +} diff --git a/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs b/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs index 39eb7009..31da190b 100644 --- a/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs +++ b/tests/AgentCore.TestSupport/RecordingChatClientFactory.cs @@ -2,79 +2,81 @@ using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// Records the it was asked for, and answers every request with a -/// fixed reply. -/// -public sealed class RecordingChatClientFactory : IChatClientFactory +namespace AgentCore.TestSupport { - private readonly IChatClient _client; - - /// Creates the factory. + /// + /// Records the it was asked for, and answers every request with a + /// fixed reply. + /// + /// Creates the factory. /// The client every call answers with, or for a /// stub that always replies "ok" and calls no tool. - public RecordingChatClientFactory(IChatClient? client = null) => _client = client ?? new StubChatClient(); - - /// Gets the reference the last conversation passed, or when no conversation has - /// happened yet or the last conversation asked for the host default. - public ModelReference? Asked { get; private set; } - - public IChatClient GetChatClient(ModelReference? model) + public sealed class RecordingChatClientFactory(IChatClient? client = null) : IChatClientFactory { - Asked = model; - return _client; - } + private readonly IChatClient _client = client ?? new StubChatClient(); - public int? GetContextWindow(ModelReference? model) => 128_000; + /// Gets the reference the last conversation passed, or when no conversation has + /// happened yet or the last conversation asked for the host default. + public ModelReference? Asked { get; private set; } - private sealed class StubChatClient : IChatClient - { - public IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) + public IChatClient GetChatClient(ModelReference? model) { - ArgumentNullException.ThrowIfNull(messages); - return StreamAsync(); + Asked = model; + return _client; + } - async IAsyncEnumerable StreamAsync() + public int? GetContextWindow(ModelReference? model) + { + return 128_000; + } + + private sealed class StubChatClient : IChatClient + { + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - await Task.Yield(); + ArgumentNullException.ThrowIfNull(messages); + return StreamAsync(); - var responseId = Guid.NewGuid().ToString("N"); - yield return new ChatResponseUpdate(ChatRole.Assistant, "ok") + static async IAsyncEnumerable StreamAsync() { - ResponseId = responseId, - MessageId = responseId, - }; + await Task.Yield(); + + string responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, "ok") + { + ResponseId = responseId, + MessageId = responseId, + }; + } } - } - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (var update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) + public async Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) { - updates.Add(update); - } + List updates = []; + await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) + .ConfigureAwait(false)) + { + updates.Add(update); + } - return updates.ToChatResponse(); - } + return updates.ToChatResponse(); + } - public object? GetService(Type serviceType, object? serviceKey = null) - { - ArgumentNullException.ThrowIfNull(serviceType); - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } - public void Dispose() - { + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.TestSupport/RecordingLoggerFactory.cs b/tests/AgentCore.TestSupport/RecordingLoggerFactory.cs index fb7331ac..feadafb9 100644 --- a/tests/AgentCore.TestSupport/RecordingLoggerFactory.cs +++ b/tests/AgentCore.TestSupport/RecordingLoggerFactory.cs @@ -1,90 +1,103 @@ using Microsoft.Extensions.Logging; -namespace AgentCore.TestSupport; - -/// -/// One line the library wrote, kept with its fields rather than only its formatted text. -/// -/// How serious the line is. -/// The id the source-generated method carries. -/// The formatted text. -/// The cause, when the line carried one. -/// -/// The named values behind the message. A structured sink reads these and not the text, so a test -/// that only matched the text would pass on a line that flattened every field into a string. -/// -public sealed record CapturedLine( - LogLevel Level, - int EventId, - string Message, - Exception? Exception, - IReadOnlyList> Fields) -{ - /// Reads one named field. - /// What the field is expected to hold. - /// The field name from the message template. - /// The value, or when the line carries no such field. - public T? Field(string name) - => Fields.FirstOrDefault(field => string.Equals(field.Key, name, StringComparison.Ordinal)) - .Value is T value ? value : default; -} - -/// A logger factory a test reads back, over one logger shared by every category. -/// -/// Shared rather than per-assembly, because two suites need it: the knowledge provider's own facts, -/// and the composition-root fact that the boot's factory really reaches the compiled provider. -/// -public sealed class RecordingLoggerFactory : ILoggerFactory +namespace AgentCore.TestSupport { - private readonly List _lines = []; - - /// Gets the lines the library wrote, oldest first. - public IReadOnlyList Lines => [.. _lines]; - - /// Reads back the lines of one event id. - /// The id the source-generated method carries. - /// Those lines, oldest first. - public IReadOnlyList Of(int eventId) => [.. Lines.Where(line => line.EventId == eventId)]; - - public ILogger CreateLogger(string categoryName) => new Recorder(_lines); - - public void AddProvider(ILoggerProvider provider) + /// + /// One line the library wrote, kept with its fields rather than only its formatted text. + /// + /// How serious the line is. + /// The id the source-generated method carries. + /// The formatted text. + /// The cause, when the line carried one. + /// + /// The named values behind the message. A structured sink reads these and not the text, so a test + /// that only matched the text would pass on a line that flattened every field into a string. + /// + public sealed record CapturedLine( + LogLevel Level, + int EventId, + string Message, + Exception? Exception, + IReadOnlyList> Fields) { - // Nothing routes anywhere else. + /// Reads one named field. + /// What the field is expected to hold. + /// The field name from the message template. + /// The value, or when the line carries no such field. + public T? Field(string name) + { + return Fields.FirstOrDefault(field => string.Equals(field.Key, name, StringComparison.Ordinal)) + .Value is T value ? value : default; + } } - public void Dispose() + /// A logger factory a test reads back, over one logger shared by every category. + /// + /// Shared rather than per-assembly, because two suites need it: the knowledge provider's own facts, + /// and the composition-root fact that the boot's factory really reaches the compiled provider. + /// + public sealed class RecordingLoggerFactory : ILoggerFactory { - // Nothing to release. - } + private readonly List _lines = []; - private sealed class Recorder : ILogger - { - private readonly List _lines; + /// Gets the lines the library wrote, oldest first. + public IReadOnlyList Lines => [.. _lines]; + + /// Reads back the lines of one event id. + /// The id the source-generated method carries. + /// Those lines, oldest first. + public IReadOnlyList Of(int eventId) + { + return [.. Lines.Where(line => line.EventId == eventId)]; + } - public Recorder(List lines) => _lines = lines; + public ILogger CreateLogger(string categoryName) + { + return new Recorder(_lines); + } - public IDisposable? BeginScope(TState state) - where TState : notnull => null; + public void AddProvider(ILoggerProvider provider) + { + // Nothing routes anywhere else. + } - public bool IsEnabled(LogLevel logLevel) => true; + public void Dispose() + { + // Nothing to release. + } - public void Log( - LogLevel logLevel, - EventId eventId, - TState state, - Exception? exception, - Func formatter) + private sealed class Recorder(List lines) : ILogger { - ArgumentNullException.ThrowIfNull(formatter); + private readonly List _lines = lines; - IReadOnlyList> fields = - state is IReadOnlyList> named ? [.. named] : []; + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } - lock (_lines) + public bool IsEnabled(LogLevel logLevel) { - _lines.Add(new CapturedLine( - logLevel, eventId.Id, formatter(state, exception), exception, fields)); + return true; + } + + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + ArgumentNullException.ThrowIfNull(formatter); + + IReadOnlyList> fields = + state is IReadOnlyList> named ? [.. named] : []; + + lock (_lines) + { + _lines.Add(new CapturedLine( + logLevel, eventId.Id, formatter(state, exception), exception, fields)); + } } } } diff --git a/tests/AgentCore.TestSupport/RequestCapturingChatClient.cs b/tests/AgentCore.TestSupport/RequestCapturingChatClient.cs index 98d84860..bbcbc9c5 100644 --- a/tests/AgentCore.TestSupport/RequestCapturingChatClient.cs +++ b/tests/AgentCore.TestSupport/RequestCapturingChatClient.cs @@ -1,52 +1,53 @@ using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// Wraps one and records the messages of every request it forwarded, -/// unmodified, in call order. -/// -/// -/// A production seam that is supposed to strip something before the provider sees it can only be -/// proven by reading what actually reached the client sitting where the provider would be — never by -/// reading the response, which a stub controls regardless of what was stripped. -/// -public sealed class RequestCapturingChatClient(IChatClient inner) : DelegatingChatClient(inner) +namespace AgentCore.TestSupport { - private readonly List> _requests = []; - - /// Gets the messages of each request this client forwarded, in call order. - public IReadOnlyList> Requests + /// + /// Wraps one and records the messages of every request it forwarded, + /// unmodified, in call order. + /// + /// + /// A production seam that is supposed to strip something before the provider sees it can only be + /// proven by reading what actually reached the client sitting where the provider would be — never by + /// reading the response, which a stub controls regardless of what was stripped. + /// + public sealed class RequestCapturingChatClient(IChatClient inner) : DelegatingChatClient(inner) { - get + private readonly List> _requests = []; + + /// Gets the messages of each request this client forwarded, in call order. + public IReadOnlyList> Requests { - lock (_requests) + get { - return [.. _requests]; + lock (_requests) + { + return [.. _requests]; + } } } - } - public override Task GetResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - { - Capture(messages); - return base.GetResponseAsync(messages, options, cancellationToken); - } + public override Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + Capture(messages); + return base.GetResponseAsync(messages, options, cancellationToken); + } - public override IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - { - Capture(messages); - return base.GetStreamingResponseAsync(messages, options, cancellationToken); - } + public override IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + Capture(messages); + return base.GetStreamingResponseAsync(messages, options, cancellationToken); + } - private void Capture(IEnumerable messages) - { - var snapshot = messages.ToList(); - lock (_requests) + private void Capture(IEnumerable messages) { - _requests.Add(snapshot); + List snapshot = [.. messages]; + lock (_requests) + { + _requests.Add(snapshot); + } } } } diff --git a/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs b/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs index 8691bd80..96bdd981 100644 --- a/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs +++ b/tests/AgentCore.TestSupport/RoutingChatClientFactory.cs @@ -1,38 +1,41 @@ -using System.Runtime.CompilerServices; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// Hands one client to the reply model and another to the extractor model. -/// -/// -/// providers.llm[].as names each model, and the document points extractor.model at one -/// of those names. This factory routes on that name, so a test scripts the two models apart. -/// -public sealed class RoutingChatClientFactory : IChatClientFactory +namespace AgentCore.TestSupport { - private readonly Dictionary _byName = new(StringComparer.Ordinal); - private readonly IChatClient? _fallback; - + /// + /// Hands one client to the reply model and another to the extractor model. + /// + /// + /// providers.llm[].as names each model, and the document points extractor.model at one + /// of those names. This factory routes on that name, so a test scripts the two models apart. + /// /// /// The client for a reference with no route, or to throw on one. /// - public RoutingChatClientFactory(IChatClient? fallback = null) => _fallback = fallback; - - /// Binds one client to one as name. - public RoutingChatClientFactory Route(string name, IChatClient client) + public sealed class RoutingChatClientFactory(IChatClient? fallback = null) : IChatClientFactory { - _byName[name] = client; - return this; - } + private readonly Dictionary _byName = new(StringComparer.Ordinal); + private readonly IChatClient? _fallback = fallback; + + /// Binds one client to one as name. + public RoutingChatClientFactory Route(string name, IChatClient client) + { + _byName[name] = client; + return this; + } - public IChatClient GetChatClient(ModelReference? model) - => model is not null && _byName.TryGetValue(model.Ref, out var client) - ? client - : _fallback ?? throw new KeyNotFoundException($"No offline client is routed to the model '{model?.Ref}'."); + public IChatClient GetChatClient(ModelReference? model) + { + return model is not null && _byName.TryGetValue(model.Ref, out IChatClient? client) + ? client + : _fallback ?? throw new KeyNotFoundException($"No offline client is routed to the model '{model?.Ref}'."); + } - public int? GetContextWindow(ModelReference? model) => 128_000; -} \ No newline at end of file + public int? GetContextWindow(ModelReference? model) + { + return 128_000; + } + } +} diff --git a/tests/AgentCore.TestSupport/SkillFolder.cs b/tests/AgentCore.TestSupport/SkillFolder.cs index b49d1922..6ed055fc 100644 --- a/tests/AgentCore.TestSupport/SkillFolder.cs +++ b/tests/AgentCore.TestSupport/SkillFolder.cs @@ -2,130 +2,141 @@ using Microsoft.Agents.AI; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// A temp folder of SKILL.md directories, deleted when the test finishes. The framework's -/// discovery walk stops at the first SKILL.md on a branch and gives up past two levels, so a -/// fixture normally puts each skill exactly one level below the root. -/// -public sealed class SkillFolder : IDisposable +namespace AgentCore.TestSupport { - private SkillFolder(string root) => Root = root; - - /// Gets the absolute path a host would pass to UseSkills. - public string Root { get; } - - /// Creates an empty folder. - /// The folder. - public static SkillFolder Create() - { - var root = Path.Combine( - Path.GetTempPath(), - "agentcore-skills-" + Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture)); - - Directory.CreateDirectory(root); - return new SkillFolder(root); - } - - /// Writes one skill directory. - /// Where to put it, relative to the root. May contain one '/'. - /// The name to write in the frontmatter, or null to use the directory name. - /// The description the prompt advertises. - /// This folder, so a test chains its conversations. - public SkillFolder WithSkill( - string relativePath, - string? frontmatterName = null, - string description = "A skill used by a test.") + /// + /// A temp folder of SKILL.md directories, deleted when the test finishes. The framework's + /// discovery walk stops at the first SKILL.md on a branch and gives up past two levels, so a + /// fixture normally puts each skill exactly one level below the root. + /// + public sealed class SkillFolder : IDisposable { - var directory = Path.Combine(Root, relativePath.Replace('/', Path.DirectorySeparatorChar)); - Directory.CreateDirectory(directory); - - var name = frontmatterName ?? Path.GetFileName(directory); - File.WriteAllText( - Path.Combine(directory, "SKILL.md"), - $"---\nname: {name}\ndescription: {description}\n---\n\nDo the thing.\n"); - - return this; - } + private SkillFolder(string root) + { + Root = root; + } - /// Adds a script to a skill written earlier, so a test can prove scripts stay hidden. - /// The skill's path, relative to the root. - /// The script file name. - /// This folder, so a test chains its conversations. - public SkillFolder WithScript(string relativePath, string fileName = "hello.py") - { - var scripts = Path.Combine(Root, relativePath.Replace('/', Path.DirectorySeparatorChar), "scripts"); - Directory.CreateDirectory(scripts); - File.WriteAllText(Path.Combine(scripts, fileName), "print('hi')\n"); + /// Gets the absolute path a host would pass to UseSkills. + public string Root { get; } - return this; - } + /// Creates an empty folder. + /// The folder. + public static SkillFolder Create() + { + string root = Path.Combine( + Path.GetTempPath(), + "agentcore-skills-" + Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture)); - /// Adds a reference document to a skill written earlier. - /// The skill's path, relative to the root. - /// The file name. - /// This folder, so a test chains its conversations. - public SkillFolder WithReference(string relativePath, string fileName = "notes.md") - { - var references = Path.Combine(Root, relativePath.Replace('/', Path.DirectorySeparatorChar), "references"); - Directory.CreateDirectory(references); - File.WriteAllText(Path.Combine(references, fileName), "# notes\n"); + _ = Directory.CreateDirectory(root); + return new SkillFolder(root); + } - return this; - } + /// Writes one skill directory. + /// Where to put it, relative to the root. May contain one '/'. + /// The name to write in the frontmatter, or null to use the directory name. + /// The description the prompt advertises. + /// This folder, so a test chains its conversations. + public SkillFolder WithSkill( + string relativePath, + string? frontmatterName = null, + string description = "A skill used by a test.") + { + string directory = Path.Combine(Root, relativePath.Replace('/', Path.DirectorySeparatorChar)); + _ = Directory.CreateDirectory(directory); - /// Reads exactly what load_skill would return for one skill. - /// The source to read through. - /// The skill name. - /// Cancels the read. - /// The body, including the resource and script manifests. - public static async Task LoadBodyAsync( - AgentSkillsSource source, - string name, - CancellationToken cancellationToken) - { - ArgumentNullException.ThrowIfNull(source); + string name = frontmatterName ?? Path.GetFileName(directory); + File.WriteAllText( + Path.Combine(directory, "SKILL.md"), + $"---\nname: {name}\ndescription: {description}\n---\n\nDo the thing.\n"); - using ThrowingChatClient client = new(); - ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "skill-probe" }); + return this; + } - var skills = await source.GetSkillsAsync(new AgentSkillsSourceContext(agent, null), cancellationToken); - var skill = skills.Single(candidate => string.Equals(candidate.Frontmatter.Name, name, StringComparison.Ordinal)); + /// Adds a script to a skill written earlier, so a test can prove scripts stay hidden. + /// The skill's path, relative to the root. + /// The script file name. + /// This folder, so a test chains its conversations. + public SkillFolder WithScript(string relativePath, string fileName = "hello.py") + { + string scripts = Path.Combine(Root, relativePath.Replace('/', Path.DirectorySeparatorChar), "scripts"); + _ = Directory.CreateDirectory(scripts); + File.WriteAllText(Path.Combine(scripts, fileName), "print('hi')\n"); - return await skill.GetContentAsync(cancellationToken); - } + return this; + } - /// Deletes the folder. - public void Dispose() - { - try + /// Adds a reference document to a skill written earlier. + /// The skill's path, relative to the root. + /// The file name. + /// This folder, so a test chains its conversations. + public SkillFolder WithReference(string relativePath, string fileName = "notes.md") { - Directory.Delete(Root, recursive: true); + string references = Path.Combine(Root, relativePath.Replace('/', Path.DirectorySeparatorChar), "references"); + _ = Directory.CreateDirectory(references); + File.WriteAllText(Path.Combine(references, fileName), "# notes\n"); + + return this; } - catch (DirectoryNotFoundException) + + /// Reads exactly what load_skill would return for one skill. + /// The source to read through. + /// The skill name. + /// Cancels the read. + /// The body, including the resource and script manifests. + public static async Task LoadBodyAsync( + AgentSkillsSource source, + string name, + CancellationToken cancellationToken) { - // A test may have deleted it to exercise a missing folder. - } - } + ArgumentNullException.ThrowIfNull(source); - /// - /// The framework's enumeration context refuses a null agent, and an agent needs a chat client. - /// Nothing calls the model while skills are enumerated, so both response methods throw rather - /// than answer. - /// - private sealed class ThrowingChatClient : IChatClient - { - public Task GetResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + using ThrowingChatClient client = new(); + ChatClientAgent agent = new(client, new ChatClientAgentOptions { Name = "skill-probe" }); - public IAsyncEnumerable GetStreamingResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) - => throw new NotSupportedException(); + IList skills = await source.GetSkillsAsync(new AgentSkillsSourceContext(agent, null), cancellationToken); + AgentSkill skill = skills.Single(candidate => string.Equals(candidate.Frontmatter.Name, name, StringComparison.Ordinal)); - public object? GetService(Type serviceType, object? serviceKey = null) => null; + return await skill.GetContentAsync(cancellationToken); + } + /// Deletes the folder. public void Dispose() { + try + { + Directory.Delete(Root, recursive: true); + } + catch (DirectoryNotFoundException) + { + // A test may have deleted it to exercise a missing folder. + } + } + + /// + /// The framework's enumeration context refuses a null agent, and an agent needs a chat client. + /// Nothing calls the model while skills are enumerated, so both response methods throw rather + /// than answer. + /// + private sealed class ThrowingChatClient : IChatClient + { + public Task GetResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public IAsyncEnumerable GetStreamingResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException(); + } + + public object? GetService(Type serviceType, object? serviceKey = null) + { + return null; + } + + public void Dispose() + { + } } } } diff --git a/tests/AgentCore.TestSupport/TestToolRegistry.cs b/tests/AgentCore.TestSupport/TestToolRegistry.cs index 68781f3f..5ff13f44 100644 --- a/tests/AgentCore.TestSupport/TestToolRegistry.cs +++ b/tests/AgentCore.TestSupport/TestToolRegistry.cs @@ -3,57 +3,60 @@ using AgentCore.Application.Tools.Registry; using Microsoft.Extensions.AI; -namespace AgentCore.TestSupport; - -/// -/// Wraps one per-declaration tool builder in the a compiled document -/// reads. -/// -/// -/// The builder is synchronous by contract — a test fake's own Create method, usually passed -/// as a method group — so always returns an already-completed -/// and 's state machine runs to -/// completion synchronously. Blocking on the result here never risks a deadlock. -/// -public static class TestToolRegistry +namespace AgentCore.TestSupport { - /// Builds the registry one builder serves, or when the test passed none. - /// The document the builder resolves declarations against. - /// - /// Builds the tool one declaration names, or when it does not serve that - /// declaration's kind. Pass for a test that needs no tools at all. - /// - /// Cancels the build. - public static ToolRegistry? From( - AgentCoreConfiguration document, - Func? builder, - CancellationToken cancellationToken) - => builder is null - ? null - : ToolRegistryBuilder.BuildAsync( - [new Source(builder)], new ToolSourceContext(document), cancellationToken) - .AsTask().GetAwaiter().GetResult(); - - private sealed class Source(Func builder) : IToolSource + /// + /// Wraps one per-declaration tool builder in the a compiled document + /// reads. + /// + /// + /// The builder is synchronous by contract — a test fake's own Create method, usually passed + /// as a method group — so always returns an already-completed + /// and 's state machine runs to + /// completion synchronously. Blocking on the result here never risks a deadlock. + /// + public static class TestToolRegistry { - public ValueTask> ProvideAsync( - ToolSourceContext context, CancellationToken cancellationToken = default) + /// Builds the registry one builder serves, or when the test passed none. + /// The document the builder resolves declarations against. + /// + /// Builds the tool one declaration names, or when it does not serve that + /// declaration's kind. Pass for a test that needs no tools at all. + /// + /// Cancels the build. + public static ToolRegistry? From( + AgentCoreConfiguration document, + Func? builder, + CancellationToken cancellationToken) { - ArgumentNullException.ThrowIfNull(context); + return builder is null + ? null + : ToolRegistryBuilder.BuildAsync( + [new Source(builder)], new ToolSourceContext(document), cancellationToken) + .AsTask().GetAwaiter().GetResult(); + } - List registrations = []; - foreach (var declared in context.Configuration.Tools) + private sealed class Source(Func builder) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) { - if (builder(declared) is not { } built) + ArgumentNullException.ThrowIfNull(context); + + List registrations = []; + foreach (ToolConfiguration declared in context.Configuration.Tools) { - continue; + if (builder(declared) is not { } built) + { + continue; + } + + registrations.Add(new ToolRegistration( + declared.Id, declared.Description ?? string.Empty, () => built)); } - registrations.Add(new ToolRegistration( - declared.Id, declared.Description ?? string.Empty, () => built)); + return ValueTask.FromResult>(registrations); } - - return ValueTask.FromResult>(registrations); } } } From b54a74f237b0c0ceedebaf68b18f7de43ae3a771 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sun, 20 Sep 2026 19:32:03 -0600 Subject: [PATCH 7/8] feat(compaction): enhance compaction logic with FireTokens method and update related tests --- .../Runtime/Compaction/CompactionDefaults.cs | 12 +++++- .../Compaction/CompactionStrategyFactory.cs | 19 +++------ .../Runtime/CompactionStrategyFactoryTests.cs | 41 +++++++++++++++---- 3 files changed, 48 insertions(+), 24 deletions(-) diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs index 729ce552..92eb5461 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionDefaults.cs @@ -12,7 +12,15 @@ internal static class CompactionDefaults /// Fraction of the model's context window at which compaction fires. public const double FireFraction = 0.75; - /// Fraction of the model's context window the summary stops at. - public const double TargetFraction = 0.5; + /// + /// Tokens. The fire point never goes above this, however large the window. + /// + public const int FireTokensCeiling = 200_000; + + /// The token count above which compaction fires for a window. + public static int FireTokens(int contextWindow) + { + return Math.Min((int)(contextWindow * FireFraction), FireTokensCeiling); + } } } diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs index b3386163..fb84afcc 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs @@ -6,14 +6,12 @@ namespace AgentCore.Application.Runtime.Compaction { /// - /// Builds the one fixed compaction every agent runs: cap old tool results, then summarise the - /// rest, sized off the model's own context window (D7, D9). The trigger-taking overload lets a - /// test size the same pair to fire on a handful of fixture messages. + /// Builds the one fixed compaction every agent runs. /// #pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. internal static class CompactionStrategyFactory { - /// Builds the stages off the window fractions. + /// Builds the stages off the window fraction and the token ceiling. /// The chat client the summary stage calls. This is the agent's own reply model. /// The reply model's context window, in tokens. /// A and a , on the same trigger. @@ -22,26 +20,21 @@ public static CompactionStages Create(IChatClient summariser, int contextWindow) { ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(contextWindow, 0); - return Create( - summariser, - CompactionTriggers.TokensExceed((int)(contextWindow * CompactionDefaults.FireFraction)), - CompactionTriggers.TokensBelow((int)(contextWindow * CompactionDefaults.TargetFraction))); + return Create(summariser, CompactionTriggers.TokensExceed(CompactionDefaults.FireTokens(contextWindow))); } - /// Builds the stages off explicit triggers. A test passes Always and Never here. + /// Builds the stages off an explicit trigger. A test passes Always or Never here. /// The chat client the summary stage calls. /// When a stage applies, judged over everything bound for the model. - /// Where the summary stops. Only the summary stage reads this. /// A and a , on the same trigger. - public static CompactionStages Create(IChatClient summariser, CompactionTrigger fire, CompactionTrigger target) + public static CompactionStages Create(IChatClient summariser, CompactionTrigger fire) { ArgumentNullException.ThrowIfNull(summariser); ArgumentNullException.ThrowIfNull(fire); - ArgumentNullException.ThrowIfNull(target); return new CompactionStages( new ToolResultCapProvider(fire, CompactionDefaults.Keep, CompactionDefaults.CapResultChars), - new SummarizationCompactionStrategy(summariser, fire, CompactionDefaults.Keep, target: target)); + new SummarizationCompactionStrategy(summariser, fire, CompactionDefaults.Keep, target: CompactionTriggers.Never)); } /// Builds the providers in chain order: the cap always runs, the summary needs history to persist its row. diff --git a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs index ce2584ff..9a3206c4 100644 --- a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs @@ -13,7 +13,7 @@ namespace AgentCore.Application.Tests.Runtime { /// /// : the one fixed Cap -> Summary pair (D7, D9), - /// sized off the model's window, and the compiler's refusal when the window is unknown (D14, D15). + /// fired off the model's window under the token ceiling, and the compiler's refusal when the window is unknown (D14, D15). /// #pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. public sealed class CompactionStrategyFactoryTests @@ -29,11 +29,12 @@ public void Create_AContextWindowThatIsNotPositive_Throws(int window) } [Fact] - public async Task Create_AViewAt76PercentOfTheWindow_FiresAndLandsAtOrUnderTheTarget() + public async Task Create_AViewAt76PercentOfTheWindow_FiresAndKeepsOnlyTheFourNewestGroups() { - // window = 1000: fire above 750 (75%), stop at or below 500 (50%). 20 pairs of 76-char - // messages sum to exactly 3040 UTF-8 bytes, which MAF's byte/4 estimator (no tokenizer - // supplied) reads as exactly 760 tokens - over the fire line. + // window = 1000: fire above 750 (75%). 20 pairs of 76-char messages sum to exactly 3040 + // UTF-8 bytes, which MAF's byte/4 estimator (no tokenizer supplied) reads as exactly 760 + // tokens - over the fire line. There is no token target: every group older than the + // kept four goes into the one summary. using SequencedChatClient summariser = new("summary."); CompactionStages stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1000); @@ -42,8 +43,24 @@ public async Task Create_AViewAt76PercentOfTheWindow_FiresAndLandsAtOrUnderTheTa List compacted = [.. await CompactionProvider.CompactAsync( stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; - int after = EstimatedTokens(compacted); - Assert.True(after <= 500, $"expected at or under the 500-token target, got {after}."); + AssertSummaryThenTail(view, compacted); + } + + [Fact] + public async Task Create_AOneMillionWindowAtJustOverTheCeiling_FiresAndKeepsOnlyTheFourNewestGroups() + { + // window = 1,000,000: 75% would be 750,000, but the 200,000-token ceiling wins. The + // estimator rounds down per message, so 20 pairs of 20,004-char messages read as + // 40 x 5,001 = 200,040 tokens - over the ceiling, far under 75% of the window. + using SequencedChatClient summariser = new("summary."); + CompactionStages stages = CompactionStrategyFactory.Create(summariser, contextWindow: 1_000_000); + + List view = Conversation(pairs: 20, charsPerMessage: 20_004); + + List compacted = [.. await CompactionProvider.CompactAsync( + stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; + + AssertSummaryThenTail(view, compacted); } [Fact] @@ -137,9 +154,15 @@ public void Compile_EveryAgentOfATwoAgentDocument_HasBothCompactionProviders() }); } - private static int EstimatedTokens(IReadOnlyList messages) + /// One new summary message, then the view's four newest messages, the same instances. + private static void AssertSummaryThenTail(List view, List compacted) { - return messages.Sum(message => System.Text.Encoding.UTF8.GetByteCount(message.Text)) / 4; + Assert.Equal(CompactionDefaults.Keep + 1, compacted.Count); + Assert.DoesNotContain(compacted[0], view); + for (int index = 1; index < compacted.Count; index++) + { + Assert.Same(view[view.Count - CompactionDefaults.Keep + index - 1], compacted[index]); + } } private static List Conversation(int pairs, int charsPerMessage) From 13d1274ea8fdd463fff02d95eb8bed5f9a175229 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Sun, 20 Sep 2026 21:31:38 -0600 Subject: [PATCH 8/8] refactor: replace RenderContent with SourceContent --- .../Ports/IRenderPort.cs | 11 -- .../PublicAPI.Unshipped.txt | 19 +-- .../AuditingFunctionInvokingChatClient.cs | 17 +- .../Runtime/Compaction/CompactionContent.cs | 33 ++++ .../Runtime/Compaction/CompactionStages.cs | 10 +- .../Compaction/CompactionStrategyFactory.cs | 9 +- .../Runtime/Compaction/NoticingChatClient.cs | 55 ++++++ .../Runtime/Compaction/SummaryRowProvider.cs | 90 ++++------ .../Runtime/Compaction/SummaryRowShape.cs | 58 +++++++ .../Runtime/ConversationSession.cs | 8 - .../Runtime/ConversationTurn.cs | 3 +- .../Runtime/ConversationTurnRunner.cs | 13 -- .../Runtime/ConversationTurnStream.cs | 17 +- .../Runtime/Harness/BackgroundChildAgent.cs | 9 +- .../Runtime/Turn/NoticeContent.cs | 16 ++ .../Runtime/Turn/TurnNotices.cs | 30 ++++ .../Runtime/Turn/TurnRenders.cs | 28 ---- .../Runtime/Turn/TurnUpdateMerge.cs | 107 ++++++++++++ .../Runtime/TurnInvocation.cs | 14 +- .../Transcript/ChatMessageExtensions.cs | 4 +- .../Transcript/ReaderContent.cs | 8 +- .../Transcript/RenderContent.cs | 20 --- .../Endpoints/ResponsesContracts.cs | 21 +-- .../Endpoints/ResponsesEndpoints.cs | 5 - .../Endpoints/ResponsesTurnStream.cs | 40 ++--- .../Endpoints/TurnStreamFiles.cs | 4 +- .../Endpoints/TurnStreamParts.cs | 73 +++++--- .../Compilation/CompactionCompilationTests.cs | 9 +- .../ConfigurationCompilerModelFacingTests.cs | 11 +- ...ersationTurnStreamCompactionNoticeTests.cs | 133 +++++++++++++++ .../SummaryRowProviderNoticeTests.cs | 129 ++++++++++++++ .../Runtime/CompactionStrategyFactoryTests.cs | 6 +- ...versationSessionFactoryModelFacingTests.cs | 21 ++- .../Harness/BackgroundChildAgentTests.cs | 6 +- .../Runtime/ModelFacingChatClientTests.cs | 40 +++-- .../Runtime/RuntimeFakes.cs | 12 -- .../Runtime/TurnScreenTests.cs | 157 ------------------ ...onversationSessionCompactionTestSupport.cs | 23 ++- .../ConversationSessionCompactionTests.cs | 6 +- .../ConversationSessionTranscriptTests.cs | 73 -------- .../Transcript/ConversationTranscriptTests.cs | 20 ++- .../Transcript/TranscriptJsonTests.cs | 34 ++-- .../Endpoints/CompactionWireTests.cs | 50 ++++++ .../Endpoints/ResponsesTests.cs | 127 -------------- .../Endpoints/SourceWireTests.cs | 4 - .../Endpoints/ToolWireTests.cs | 2 +- .../Endpoints/TurnStreamFilesTests.cs | 20 ++- .../PostgresConversationStoreWordsTests.cs | 25 +-- 48 files changed, 901 insertions(+), 729 deletions(-) delete mode 100644 src/AgentCore.Application/Ports/IRenderPort.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/CompactionContent.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/NoticingChatClient.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/SummaryRowShape.cs create mode 100644 src/AgentCore.Application/Runtime/Turn/NoticeContent.cs create mode 100644 src/AgentCore.Application/Runtime/Turn/TurnNotices.cs delete mode 100644 src/AgentCore.Application/Runtime/Turn/TurnRenders.cs create mode 100644 src/AgentCore.Application/Runtime/Turn/TurnUpdateMerge.cs delete mode 100644 src/AgentCore.Application/Transcript/RenderContent.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/Compaction/ConversationTurnStreamCompactionNoticeTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/Compaction/SummaryRowProviderNoticeTests.cs delete mode 100644 tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs create mode 100644 tests/AgentCore.AspNetCore.Tests/Endpoints/CompactionWireTests.cs diff --git a/src/AgentCore.Application/Ports/IRenderPort.cs b/src/AgentCore.Application/Ports/IRenderPort.cs deleted file mode 100644 index b8cd0bcf..00000000 --- a/src/AgentCore.Application/Ports/IRenderPort.cs +++ /dev/null @@ -1,11 +0,0 @@ -namespace AgentCore.Application.Ports -{ - /// - /// Carries one thing the caller should see from the tool that produced it to the host that shows it. - /// - public interface IRenderPort - { - /// Sends one thing to be shown to the caller of the running conversation. - void Publish(string name, string renderId, object data, bool transient = false); - } -} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 5ff23ea7..6a65cfd8 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -1121,8 +1121,6 @@ AgentCore.Application.Ports.IKnowledgeStoreAdapter.CanServeSearch.get -> bool AgentCore.Application.Ports.IKnowledgeStoreAdapter.CreateSearchAsync(AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, Microsoft.Extensions.AI.IEmbeddingGenerator!>? embeddings, bool requireScope, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IModerationAdapter AgentCore.Application.Ports.IModerationAdapter.CreateAsync(AgentCore.Application.Configuration.Schema.VendorProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask -AgentCore.Application.Ports.IRenderPort -AgentCore.Application.Ports.IRenderPort.Publish(string! name, string! renderId, object! data, bool transient = false) -> void AgentCore.Application.Ports.ISecretResolverPort AgentCore.Application.Ports.ISecretResolverPort.TryResolveAsync(string! name, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.ISourcePort @@ -1210,7 +1208,6 @@ AgentCore.Application.Runtime.ConversationSession.RunTurnStreamingAtOriginAsync( AgentCore.Application.Runtime.ConversationSession.Scope.get -> AgentCore.Domain.Knowledge.KnowledgeScope? AgentCore.Application.Runtime.ConversationSession.Scope.set -> void AgentCore.Application.Runtime.ConversationSession.SetDelegatedTools(string! delegatingToolId, System.Collections.Generic.IReadOnlyList! tools) -> void -AgentCore.Application.Runtime.ConversationSession.SetHasScreen(bool hasScreen) -> void AgentCore.Application.Runtime.ConversationSession.Stage.get -> string! AgentCore.Application.Runtime.ConversationSession.State.get -> AgentCore.Application.State.StateDocument! AgentCore.Application.Runtime.ConversationSession.Transcript.get -> System.Collections.Generic.IReadOnlyList! @@ -1436,14 +1433,6 @@ AgentCore.Application.Transcript.ConversationMessageDraft.MessageId.init -> void AgentCore.Application.Transcript.ConversationMessageDraft.TurnIndex.get -> int? AgentCore.Application.Transcript.ConversationMessageDraft.TurnIndex.init -> void AgentCore.Application.Transcript.ConversationMessageIds -AgentCore.Application.Transcript.RenderContent -AgentCore.Application.Transcript.RenderContent.Data.get -> System.Text.Json.JsonElement -AgentCore.Application.Transcript.RenderContent.Data.set -> void -AgentCore.Application.Transcript.RenderContent.Name.get -> string! -AgentCore.Application.Transcript.RenderContent.Name.set -> void -AgentCore.Application.Transcript.RenderContent.RenderContent() -> void -AgentCore.Application.Transcript.RenderContent.RenderId.get -> string! -AgentCore.Application.Transcript.RenderContent.RenderId.set -> void AgentCore.Application.Transcript.SourceContent AgentCore.Application.Transcript.SourceContent.CallId.get -> string! AgentCore.Application.Transcript.SourceContent.CallId.set -> void @@ -2339,3 +2328,11 @@ static AgentCore.Application.Transcript.ConversationCut.operator ==(AgentCore.Ap static AgentCore.Application.Transcript.ConversationCut.operator !=(AgentCore.Application.Transcript.ConversationCut left, AgentCore.Application.Transcript.ConversationCut right) -> bool static AgentCore.Application.Transcript.WithdrawnTurns.operator ==(AgentCore.Application.Transcript.WithdrawnTurns left, AgentCore.Application.Transcript.WithdrawnTurns right) -> bool static AgentCore.Application.Transcript.WithdrawnTurns.operator !=(AgentCore.Application.Transcript.WithdrawnTurns left, AgentCore.Application.Transcript.WithdrawnTurns right) -> bool +AgentCore.Application.Runtime.Compaction.CompactionContent +AgentCore.Application.Runtime.Turn.NoticeContent +AgentCore.Application.Runtime.Turn.NoticeContent.NoticeContent() -> void +AgentCore.Application.Runtime.Compaction.CompactionContent.CompactionContent(string! phase, string? outcome = null) -> void +AgentCore.Application.Runtime.Compaction.CompactionContent.Outcome.get -> string? +AgentCore.Application.Runtime.Compaction.CompactionContent.Phase.get -> string! +const AgentCore.Application.Runtime.Compaction.CompactionContent.EndPhase = "end" -> string! +const AgentCore.Application.Runtime.Compaction.CompactionContent.StartPhase = "start" -> string! diff --git a/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs b/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs index 0f897ae1..6c95dcf7 100644 --- a/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs +++ b/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs @@ -1,10 +1,10 @@ +using System.Collections.Concurrent; using System.Net.Sockets; using System.Security.Authentication; -using AgentCore.Domain.Audit; +using AgentCore.Application.Runtime.Turn; using AgentCore.Application.Tools; +using AgentCore.Domain.Audit; using Microsoft.Extensions.AI; -using System.Collections.Concurrent; -using AgentCore.Application.Runtime.Turn; namespace AgentCore.Application.Runtime { @@ -182,7 +182,7 @@ private static bool IsCallerCancellation(Exception failure, CancellationToken ca /// /// Builds the messages the model reads, reports every tool it could not find, and attaches - /// whatever this turn drew, cited, or published to the tool-result message it belongs to. + /// whatever this turn cited or published to the tool-result message it belongs to. /// protected override IList CreateResponseMessages(ReadOnlySpan results) { @@ -196,18 +196,11 @@ protected override IList CreateResponseMessages(ReadOnlySpanAppends what each tool result in one message drew, cited, or published. + /// Appends what each tool result in one message cited or published. private void Attach(IList contents) { - // Materialised before the loop below adds to the very list this reads: Contents is a - // List underneath, and its enumerator throws on the next MoveNext once - // anything has been appended, even where nothing further was left to enumerate. foreach (string? callId in contents.OfType().Select(r => r.CallId).ToList()) { - // A nested loop's calls drain nothing: their ids were registered under the - // stripped copy, so removing the entry without draining keeps the outer drain - // from attaching a nested drawing to a message that never reaches the caller. - // Only the outermost loop's own calls attach what they drew or cited. if (_drains.TryRemove(callId, out Drain? drain) && !drain.Nested) { foreach (AIContent attached in drain.TakeFor(callId)) diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionContent.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionContent.cs new file mode 100644 index 00000000..b8a7ef5a --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionContent.cs @@ -0,0 +1,33 @@ +using AgentCore.Application.Runtime.Turn; + +namespace AgentCore.Application.Runtime.Compaction +{ + /// + /// Tells the turn's own caller that a compaction pass is starting or has finished. + /// + public sealed class CompactionContent : NoticeContent + { + /// The value carries while the pass is running. + public const string StartPhase = "start"; + + /// The value carries once the pass has finished. + public const string EndPhase = "end"; + + /// Creates a notice for one phase of a compaction pass. + /// or . + /// How the pass went. Only set on . + public CompactionContent(string phase, string? outcome = null) + { + ArgumentException.ThrowIfNullOrEmpty(phase); + Phase = phase; + Outcome = outcome; + } + + /// Gets whether this notice opens or closes a compaction pass. + public string Phase { get; } + + /// Gets how the pass went: compacted, unchanged, or failed. + /// Always on . + public string? Outcome { get; } + } +} diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs index 238e88a8..42504d76 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStages.cs @@ -1,4 +1,5 @@ using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; namespace AgentCore.Application.Runtime.Compaction { @@ -7,8 +8,13 @@ namespace AgentCore.Application.Runtime.Compaction /// the agent's provider chain: the cap first, so the summary reads short results and counts them. /// /// Cuts old tool results. No model call. - /// The strategy runs. One model call, its output stored as a row. + /// The chat client the summary stage calls. + /// + /// Builds the strategy runs, over a client it wraps itself. One + /// call per turn: a holds only its config, so + /// building a fresh one costs nothing worth caching. + /// #pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. - internal sealed record CompactionStages(ToolResultCapProvider Cap, CompactionStrategy Summary); + internal sealed record CompactionStages(ToolResultCapProvider Cap, IChatClient Summariser, Func Summary); #pragma warning restore MAAI001 } diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs index fb84afcc..9c7fc7d5 100644 --- a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs @@ -26,7 +26,7 @@ public static CompactionStages Create(IChatClient summariser, int contextWindow) /// Builds the stages off an explicit trigger. A test passes Always or Never here. /// The chat client the summary stage calls. /// When a stage applies, judged over everything bound for the model. - /// A and a , on the same trigger. + /// A and a factory, on the same trigger. public static CompactionStages Create(IChatClient summariser, CompactionTrigger fire) { ArgumentNullException.ThrowIfNull(summariser); @@ -34,11 +34,12 @@ public static CompactionStages Create(IChatClient summariser, CompactionTrigger return new CompactionStages( new ToolResultCapProvider(fire, CompactionDefaults.Keep, CompactionDefaults.CapResultChars), - new SummarizationCompactionStrategy(summariser, fire, CompactionDefaults.Keep, target: CompactionTriggers.Never)); + summariser, + client => new SummarizationCompactionStrategy(client, fire, CompactionDefaults.Keep, target: CompactionTriggers.Never)); } /// Builds the providers in chain order: the cap always runs, the summary needs history to persist its row. - /// The cap provider and the strategy the summary provider runs. + /// The cap provider and what the summary provider builds its strategy from. /// Store 1, or when the session carries no history. /// The cap, then the summary when there is somewhere to write it. public static AIContextProvider[] BuildProviders(CompactionStages stages, AgentCoreChatHistoryProvider? history) @@ -47,7 +48,7 @@ public static AIContextProvider[] BuildProviders(CompactionStages stages, AgentC return history is null ? [stages.Cap] - : [stages.Cap, new SummaryRowProvider(history, stages.Summary)]; + : [stages.Cap, new SummaryRowProvider(history, stages.Summariser, stages.Summary)]; } } #pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/NoticingChatClient.cs b/src/AgentCore.Application/Runtime/Compaction/NoticingChatClient.cs new file mode 100644 index 00000000..6894673b --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/NoticingChatClient.cs @@ -0,0 +1,55 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Runtime.Turn; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime.Compaction +{ + /// + /// Wraps the summariser for one invocation and posts the start notice at the one point that + /// actually means "the summariser is being called": the first request this client forwards. + /// + internal sealed class NoticingChatClient : DelegatingChatClient + { + private readonly TurnNotices? _notices; + + public NoticingChatClient(IChatClient inner, TurnNotices? notices) + : base(inner) + { + _notices = notices; + } + + /// Gets whether this client has forwarded a request yet. + public bool Called { get; private set; } + + public override Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + NoteCall(); + return base.GetResponseAsync(messages, options, cancellationToken); + } + + public override async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + NoteCall(); + + await foreach (ChatResponseUpdate update in base.GetStreamingResponseAsync(messages, options, cancellationToken).ConfigureAwait(false)) + { + yield return update; + } + } + + private void NoteCall() + { + if (Called) + { + return; + } + + Called = true; + _notices?.Post(new CompactionContent(CompactionContent.StartPhase)); + } + } +} diff --git a/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs b/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs index b2ae1a05..0f9cfd27 100644 --- a/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs +++ b/src/AgentCore.Application/Runtime/Compaction/SummaryRowProvider.cs @@ -21,16 +21,21 @@ internal sealed class SummaryRowProvider : AIContextProvider { private readonly AgentCoreChatHistoryProvider _history; - private readonly CompactionStrategy _summary; + private readonly IChatClient _summariser; + + private readonly Func _summary; /// Store 1, which says what a compaction may cover and takes the row. - /// The strategy that replaces the oldest messages with one summary. One model call. - public SummaryRowProvider(AgentCoreChatHistoryProvider history, CompactionStrategy summary) + /// The chat client the strategy calls. Wrapped fresh each invocation, so the notice tracks the call it actually makes. + /// Builds the strategy that replaces the oldest messages with one summary, over the client it is handed. + public SummaryRowProvider(AgentCoreChatHistoryProvider history, IChatClient summariser, Func summary) { ArgumentNullException.ThrowIfNull(history); + ArgumentNullException.ThrowIfNull(summariser); ArgumentNullException.ThrowIfNull(summary); _history = history; + _summariser = summariser; _summary = summary; } @@ -47,7 +52,7 @@ protected override async ValueTask InvokingCoreAsync( } IReadOnlyList messages = input.Messages as IReadOnlyList ?? [.. input.Messages]; - if (!Leads(floor.Messages, messages)) + if (!SummaryRowShape.Leads(floor.Messages, messages)) { return input; } @@ -55,39 +60,46 @@ protected override async ValueTask InvokingCoreAsync( TurnInvocation? turn = TurnRegistry.For(session); ILogger logger = turn?.Logger ?? NullLogger.Instance; - // The stages before this one strip and cap by making new instances, so the view the - // strategy runs over is the model-bound prefix, not the floor's own messages; the floor - // lines up with it by index and lends it the ordinals. List view = [.. messages.Take(floor.Messages.Count)]; + NoticingChatClient client = new(_summariser, turn?.Notices); + CompactionStrategy strategy = _summary(client); + try { - List output = [.. await CompactionProvider.CompactAsync(_summary, view, logger, cancellationToken).ConfigureAwait(false)]; + List output = [.. await CompactionProvider.CompactAsync(strategy, view, logger, cancellationToken).ConfigureAwait(false)]; if (output.Count == view.Count && output.Zip(view).All(pair => ReferenceEquals(pair.First, pair.Second))) { + PostEnd(turn, client, "unchanged"); return input; } - if (Kept(view, output) is not { } kept) + if (SummaryRowShape.Kept(view, output) is not { } kept) { if (turn is not null) { Log.TranscriptCompactionUnsupported(logger, turn.ConversationId, turn.TurnIndex); } + PostEnd(turn, client, "unchanged"); return input; } int coversUpTo = floor.Messages[kept - 1].LastOrdinal; - return coversUpTo <= floor.CoversUpTo || !_history.Compact(session, output[0], coversUpTo, floor.Revision) - ? input - : new AIContext - { - Instructions = input.Instructions, - Messages = [output[0], .. messages.Skip(kept)], - Tools = input.Tools, - }; + if (coversUpTo <= floor.CoversUpTo || !_history.Compact(session, output[0], coversUpTo, floor.Revision)) + { + PostEnd(turn, client, "unchanged"); + return input; + } + + PostEnd(turn, client, "compacted"); + return new AIContext + { + Instructions = input.Instructions, + Messages = [output[0], .. messages.Skip(kept)], + Tools = input.Tools, + }; } #pragma warning disable CA1031 // A strategy that throws never ends a conversation: the session keeps the view it had. catch (Exception exception) when (exception is not OperationCanceledException) @@ -98,52 +110,18 @@ protected override async ValueTask InvokingCoreAsync( Log.TranscriptCompactionFailed(logger, turn.ConversationId, turn.TurnIndex, exception); } + PostEnd(turn, client, "failed"); return input; } } - /// Whether the floor's rows lead the model-bound list, id for id. - private static bool Leads(IReadOnlyList floor, IReadOnlyList messages) + /// Posts the end notice, but only when the summariser was actually called: no call, no flicker. + private static void PostEnd(TurnInvocation? turn, NoticingChatClient client, string outcome) { - if (floor.Count > messages.Count) - { - return false; - } - - for (int index = 0; index < floor.Count; index++) + if (client.Called) { - if (!string.Equals(floor[index].Message.MessageId, messages[index].MessageId, StringComparison.Ordinal)) - { - return false; - } + turn?.Notices?.Post(new CompactionContent(CompactionContent.EndPhase, outcome)); } - - return true; - } - - /// - /// Reads the strategy's output as one new message over a prefix of the view, and names where the - /// kept tail starts. The output must be one new message, then the view from that index on, the - /// very instances in order; anything else is not a shape one summary row can stand for. - /// - /// The index of the first kept message, or . The view's count when nothing was kept. - private static int? Kept(List view, List output) - { - if (output.Count == 0 || output.Count > view.Count || view.Any(message => ReferenceEquals(message, output[0]))) - { - return null; - } - - int kept = view.Count - (output.Count - 1); - for (int index = 1; index < output.Count; index++) - { - if (!ReferenceEquals(output[index], view[kept + index - 1])) - { - return null; - } - } - - return kept; } } #pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/SummaryRowShape.cs b/src/AgentCore.Application/Runtime/Compaction/SummaryRowShape.cs new file mode 100644 index 00000000..8652f77e --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/SummaryRowShape.cs @@ -0,0 +1,58 @@ +using AgentCore.Application.Transcript; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime.Compaction +{ + /// + /// Reads a 's output as a shape one summary row can stand for. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + internal static class SummaryRowShape + { + /// Whether the floor's rows lead the model-bound list, id for id. + internal static bool Leads(IReadOnlyList floor, IReadOnlyList messages) + { + if (floor.Count > messages.Count) + { + return false; + } + + for (int index = 0; index < floor.Count; index++) + { + if (!string.Equals(floor[index].Message.MessageId, messages[index].MessageId, StringComparison.Ordinal)) + { + return false; + } + } + + return true; + } + + /// + /// Reads the strategy's output as one new message over a prefix of the view, and names where the + /// kept tail starts. The output must be one new message, then the view from that index on, the + /// very instances in order; anything else is not a shape one summary row can stand for. + /// + /// The index of the first kept message, or . The view's count when nothing was kept. + internal static int? Kept(List view, List output) + { + if (output.Count == 0 || output.Count > view.Count || view.Any(message => ReferenceEquals(message, output[0]))) + { + return null; + } + + int kept = view.Count - (output.Count - 1); + for (int index = 1; index < output.Count; index++) + { + if (!ReferenceEquals(output[index], view[kept + index - 1])) + { + return null; + } + } + + return kept; + } + } +#pragma warning restore MAAI001 +} diff --git a/src/AgentCore.Application/Runtime/ConversationSession.cs b/src/AgentCore.Application/Runtime/ConversationSession.cs index e8bd18ed..8e5859fb 100644 --- a/src/AgentCore.Application/Runtime/ConversationSession.cs +++ b/src/AgentCore.Application/Runtime/ConversationSession.cs @@ -267,14 +267,6 @@ public void SetDelegatedTools(string delegatingToolId, IReadOnlyList too Runner.SetDelegatedTools(delegatingToolId, tools); } - /// - /// Gives this conversation the screen its tools draw on, or takes it away. - /// - public void SetHasScreen(bool hasScreen) - { - Runner.SetHasScreen(hasScreen); - } - /// /// Runs one turn end to end, and returns what it did. /// diff --git a/src/AgentCore.Application/Runtime/ConversationTurn.cs b/src/AgentCore.Application/Runtime/ConversationTurn.cs index 27a60e96..d56a694f 100644 --- a/src/AgentCore.Application/Runtime/ConversationTurn.cs +++ b/src/AgentCore.Application/Runtime/ConversationTurn.cs @@ -9,7 +9,7 @@ namespace AgentCore.Application.Runtime // The turn's working set, carried from preparation through commit. Built once per turn in // ConversationTurnRunner.BeginTurn for the same reason Activity is: ConversationTurnStream reopens the state // scope on every step of a streaming turn, and collectors built per step would lose whatever an - // earlier step drew before a later step could attach it to a message. + // earlier step cited or published before a later step could attach it to a message. internal sealed record ConversationTurn( AIAgent Agent, AgentSession Session, @@ -20,7 +20,6 @@ internal sealed record ConversationTurn( int Index, Activity? Activity, long StartedAt, - TurnRenders? Renders, TurnSources Sources, TurnResults Results, TurnFiles Files, diff --git a/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs b/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs index bafa9b6f..92ed6453 100644 --- a/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs +++ b/src/AgentCore.Application/Runtime/ConversationTurnRunner.cs @@ -19,8 +19,6 @@ internal sealed class ConversationTurnRunner private (string ToolId, IReadOnlyList Tools)? _delegatedTools; - private bool _hasScreen; - private TimeZoneInfo? _timeZone; internal ConversationTurnRunner(ConversationSession session) @@ -43,14 +41,6 @@ internal void SetDelegatedTools(string delegatingToolId, IReadOnlyList t _delegatedTools = (delegatingToolId, tools); } - /// - /// Gives this conversation the screen its tools draw on, or takes it away. - /// - internal void SetHasScreen(bool hasScreen) - { - _hasScreen = hasScreen; - } - /// /// Tells this conversation which zone the person is in, so the clock line reads their date. /// @@ -196,7 +186,6 @@ internal ConversationTurn BeginTurn(ChatMessage userInput, AgentSession session, _session.State.TurnIndex, activity, _session.Time.GetTimestamp(), - _hasScreen ? new TurnRenders() : null, new TurnSources(), new TurnResults(), new TurnFiles(), @@ -303,9 +292,7 @@ internal TurnInvocation TurnInvocationOf(ConversationTurn turn) Clarifications = _session.Clarifications, CarriesHistory = _session.SessionCarriesHistory, Logger = _session.Logger, - Screen = turn.Renders, Sources = turn.Sources, - Renders = turn.Renders, Results = turn.Results, Files = turn.Files, OnToolFailure = failure => _session.Events.RaiseToolFailure(turn.Index, failure), diff --git a/src/AgentCore.Application/Runtime/ConversationTurnStream.cs b/src/AgentCore.Application/Runtime/ConversationTurnStream.cs index ba1d556f..f00624a1 100644 --- a/src/AgentCore.Application/Runtime/ConversationTurnStream.cs +++ b/src/AgentCore.Application/Runtime/ConversationTurnStream.cs @@ -49,17 +49,20 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync List updates = []; string? toolFault = null; - TurnInvocation invocation = _session.Runner.TurnInvocationOf(turn); + TurnInvocation invocation = _session.Runner.TurnInvocationOf(turn) with { Notices = new TurnNotices() }; AgentSession runSession = await _session.Runner.OpenRunAsync(turn, cancellation.Token).ConfigureAwait(false); TurnRegistry.Set(runSession, invocation); - IAsyncEnumerator stream = turn.Agent + IAsyncEnumerable runStream = turn.Agent .RunStreamingAsync( turn.Request, runSession, invocation.RunOptions(), - cancellationToken: cancellation.Token) + cancellationToken: cancellation.Token); + + IAsyncEnumerator stream = TurnUpdateMerge + .RunAsync(runStream, invocation.Notices, cancellation.Token) .GetAsyncEnumerator(cancellation.Token); try @@ -88,9 +91,17 @@ private async IAsyncEnumerable RunTurnStreamingIteratorAsync break; } + if (update.Contents.OfType().Any()) + { + yield return update.AsChatResponseUpdate(); + + continue; + } + updates.Add(update); ChatResponseUpdate content = update.AsChatResponseUpdate(); + if (TurnMessages.CarriesContent(content) && Speaks(update)) { _session.Interruptions.RunIsAudible = true; diff --git a/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs b/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs index 20fce75f..a48d3207 100644 --- a/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs +++ b/src/AgentCore.Application/Runtime/Harness/BackgroundChildAgent.cs @@ -7,13 +7,6 @@ namespace AgentCore.Application.Runtime.Harness /// Wraps one background: child so every session it gets knows which conversation started it, /// which zone the person on that call is in, and which workspace and shells that call owns. /// - /// - /// BackgroundAgentsProvider creates the child session inside the parent's tool call, before - /// it hands the run to a task. At that moment is still the - /// parent's run, and its options carry the parent's turn. That is the only place the conversation id can - /// cross from parent to child: the provider passes the child null run options and a fresh session, - /// and its task-to-session map is private. Proven by probe P2 against Microsoft.Agents.AI 1.21.0. - /// internal sealed class BackgroundChildAgent(AIAgent inner) : DelegatingAIAgent(inner) { /// @@ -46,7 +39,7 @@ protected override async ValueTask CreateSessionCoreAsync(Cancella /// /// The part of the parent's turn a child may share: the conversation, its workspace folder, and its /// shells, so files: and shell: on the child work on the same disk. Every drain, - /// screen, tool list, and clarification stays with the parent; a child's publish reports a + /// tool list, and clarification stays with the parent; a child's publish reports a /// link in its result instead. /// private static TurnInvocation Shared(TurnInvocation parent) diff --git a/src/AgentCore.Application/Runtime/Turn/NoticeContent.cs b/src/AgentCore.Application/Runtime/Turn/NoticeContent.cs new file mode 100644 index 00000000..f7e0e27f --- /dev/null +++ b/src/AgentCore.Application/Runtime/Turn/NoticeContent.cs @@ -0,0 +1,16 @@ +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime.Turn +{ + /// + /// A content part meant for the turn's own caller, not for the model or the transcript. A notice + /// rides one merged update to the streaming consumer and nothing else: never persiste. + /// + public abstract class NoticeContent : AIContent + { + /// Creates a notice. + protected NoticeContent() + { + } + } +} diff --git a/src/AgentCore.Application/Runtime/Turn/TurnNotices.cs b/src/AgentCore.Application/Runtime/Turn/TurnNotices.cs new file mode 100644 index 00000000..5301822b --- /dev/null +++ b/src/AgentCore.Application/Runtime/Turn/TurnNotices.cs @@ -0,0 +1,30 @@ +using System.Threading.Channels; + +namespace AgentCore.Application.Runtime.Turn +{ + /// + /// One turn's out-of-band channel to its own streaming consumer. + /// + internal sealed class TurnNotices + { + private readonly Channel _channel = Channel.CreateUnbounded( + new UnboundedChannelOptions { SingleReader = true }); + + /// Gets the reader side, read only by the merge that owns this turn. + internal ChannelReader Reader => _channel.Reader; + + /// Posts one notice. Silently dropped once has run. + internal void Post(NoticeContent content) + { + ArgumentNullException.ThrowIfNull(content); + + _ = _channel.Writer.TryWrite(content); + } + + /// Completes the channel. The merge calls this once, when the turn's stream ends. + internal void Complete() + { + _ = _channel.Writer.TryComplete(); + } + } +} diff --git a/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs b/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs deleted file mode 100644 index ec5c681f..00000000 --- a/src/AgentCore.Application/Runtime/Turn/TurnRenders.cs +++ /dev/null @@ -1,28 +0,0 @@ -using System.Text.Json; -using AgentCore.Application.Ports; -using AgentCore.Application.Transcript; - -namespace AgentCore.Application.Runtime.Turn -{ - /// What a turn has drawn and not yet attached to a message. - internal sealed class TurnRenders : TurnAttachments, IRenderPort - { - /// - public void Publish(string name, string renderId, object data, bool transient = false) - { - ArgumentNullException.ThrowIfNull(name); - ArgumentNullException.ThrowIfNull(renderId); - ArgumentNullException.ThrowIfNull(data); - - if (transient || OuterCallId is not { } callId) - { - return; - } - - JsonElement element = JsonSerializer.SerializeToElement(data, data.GetType(), TranscriptJson.Options); - RenderContent content = new() { Name = name, RenderId = renderId, Data = element }; - - Attach(callId, content, existing => string.Equals(existing.RenderId, renderId, StringComparison.Ordinal)); - } - } -} diff --git a/src/AgentCore.Application/Runtime/Turn/TurnUpdateMerge.cs b/src/AgentCore.Application/Runtime/Turn/TurnUpdateMerge.cs new file mode 100644 index 00000000..07e66dfb --- /dev/null +++ b/src/AgentCore.Application/Runtime/Turn/TurnUpdateMerge.cs @@ -0,0 +1,107 @@ +using System.Runtime.CompilerServices; +using System.Threading.Channels; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime.Turn +{ + /// + /// Interleaves a turn's with the run's own update stream. + /// + internal static class TurnUpdateMerge + { + /// Runs , yielding as they arrive. + /// The run's own stream. This owns and disposes its enumerator. + /// This turn's notice channel. Completed once ends or fails. + /// Cancels the run. + internal static async IAsyncEnumerable RunAsync( + IAsyncEnumerable inner, + TurnNotices notices, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(inner); + ArgumentNullException.ThrowIfNull(notices); + + ChannelReader reader = notices.Reader; + await using IAsyncEnumerator e = inner.GetAsyncEnumerator(cancellationToken); + Task? pendingMove = null; + Task? pendingNotice = null; + + try + { + while (true) + { + pendingMove ??= e.MoveNextAsync().AsTask(); + pendingNotice ??= reader.WaitToReadAsync(cancellationToken).AsTask(); + + Task finished = await Task.WhenAny(pendingMove, pendingNotice).ConfigureAwait(false); + + if (finished == pendingNotice) + { + bool hasNotice = await pendingNotice.ConfigureAwait(false); + pendingNotice = null; + + if (hasNotice) + { + while (reader.TryRead(out NoticeContent? notice)) + { + yield return ToUpdate(notice); + } + + continue; + } + + // The channel completed with nothing queued; fall through to the inner stream. + } + + // A notice that landed while the inner update was on its way out goes first, so + // order is preserved: nothing lets an update jump ahead of a notice that beat it. + while (reader.TryRead(out NoticeContent? notice)) + { + yield return ToUpdate(notice); + } + + bool has = await pendingMove.ConfigureAwait(false); + pendingMove = null; + + if (!has) + { + break; + } + + yield return e.Current; + } + } + finally + { + notices.Complete(); + + if (pendingMove is { IsCompleted: false }) + { + // A compiler-generated async iterator cannot be disposed while suspended at an + // await (NotSupportedException); on cancellation the pending MoveNextAsync is + // already unwinding on the same token, so it is settled here first. + try + { + await pendingMove.ConfigureAwait(false); + } + catch + { + } + } + } + + // A notice a provider posts from its post-run hook lands after the inner stream reports + // completion, so whatever is left in the channel is drained once more here. + while (reader.TryRead(out NoticeContent? notice)) + { + yield return ToUpdate(notice); + } + } + + private static AgentResponseUpdate ToUpdate(NoticeContent content) + { + return new AgentResponseUpdate(ChatRole.Assistant, [content]); + } + } +} diff --git a/src/AgentCore.Application/Runtime/TurnInvocation.cs b/src/AgentCore.Application/Runtime/TurnInvocation.cs index 243eb579..0c33e1d6 100644 --- a/src/AgentCore.Application/Runtime/TurnInvocation.cs +++ b/src/AgentCore.Application/Runtime/TurnInvocation.cs @@ -1,4 +1,3 @@ -using AgentCore.Application.Ports; using AgentCore.Application.Runtime.Harness; using AgentCore.Application.Runtime.Turn; using AgentCore.Application.State; @@ -52,18 +51,17 @@ internal sealed record TurnInvocation /// Gets the conversation's logger, or to log nowhere. public ILogger? Logger { get; init; } - /// Gets the screen this conversation draws on, or when it has none. - public IRenderPort? Screen { get; init; } - /// Gets what the turn cites into. Never on a loop-built turn. public TurnSources? Sources { get; init; } - /// Gets what the turn draws into, or when it has no screen. - public TurnRenders? Renders { get; init; } - /// Gets what the turn's tools answer into. Never on a loop-built turn. public TurnResults? Results { get; init; } + /// + /// Gets the turn's out-of-band channel to its own streaming consumer, or . + /// + public TurnNotices? Notices { get; init; } + /// Gets what the turn publishes files into. Never on a loop-built turn. public TurnFiles? Files { get; init; } @@ -73,7 +71,7 @@ internal sealed record TurnInvocation /// internal IReadOnlyList Attachments() { - return [.. new ITurnAttachments?[] { Renders, Sources, Files }.OfType()]; + return [.. new ITurnAttachments?[] { Sources, Files }.OfType()]; } /// Gets the tools a delegated run of this conversation is offered, or for none. diff --git a/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs b/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs index 06a899bd..56102cfa 100644 --- a/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs +++ b/src/AgentCore.Application/Transcript/ChatMessageExtensions.cs @@ -12,7 +12,7 @@ public static ChatMessage WithoutHostContent(this ChatMessage message) { ArgumentNullException.ThrowIfNull(message); - if (!message.Contents.Any(static content => content is RenderContent or SourceContent)) + if (!message.Contents.Any(static content => content is SourceContent)) { return message; } @@ -22,7 +22,7 @@ public static ChatMessage WithoutHostContent(this ChatMessage message) // CreatedAt, RawRepresentation. return new ChatMessage( message.Role, - [.. message.Contents.Where(static content => content is not (RenderContent or SourceContent))]) + [.. message.Contents.Where(static content => content is not SourceContent)]) { AdditionalProperties = message.AdditionalProperties, MessageId = message.MessageId, diff --git a/src/AgentCore.Application/Transcript/ReaderContent.cs b/src/AgentCore.Application/Transcript/ReaderContent.cs index 61233f31..8d262c3c 100644 --- a/src/AgentCore.Application/Transcript/ReaderContent.cs +++ b/src/AgentCore.Application/Transcript/ReaderContent.cs @@ -5,14 +5,11 @@ namespace AgentCore.Application.Transcript { /// /// The content types AgentCore adds to a message for the person reading the transcript, not for - /// the model: a drawing, a citation, a published file. This is the one list of them. It decides + /// the model: a citation, a published file. This is the one list of them. It decides /// how a store encodes them and what is stripped before a message reaches the model. /// internal static class ReaderContent { - /// The discriminator a stored RenderContent is written with. It is a wire format. - private const string RenderContentTypeId = "agentcore.render"; - /// The discriminator a stored SourceContent is written with. It is a wire format. private const string SourceContentTypeId = "agentcore.source"; @@ -23,7 +20,7 @@ internal static class ReaderContent /// The content to test. public static bool Is(AIContent content) { - return content is RenderContent or SourceContent or FileContent; + return content is SourceContent or FileContent; } /// Teaches to encode and decode every reader content type. @@ -32,7 +29,6 @@ public static void Register(JsonSerializerOptions options) { ArgumentNullException.ThrowIfNull(options); - options.AddAIContentType(RenderContentTypeId); options.AddAIContentType(SourceContentTypeId); options.AddAIContentType(FileContentTypeId); } diff --git a/src/AgentCore.Application/Transcript/RenderContent.cs b/src/AgentCore.Application/Transcript/RenderContent.cs deleted file mode 100644 index 98c32565..00000000 --- a/src/AgentCore.Application/Transcript/RenderContent.cs +++ /dev/null @@ -1,20 +0,0 @@ -using System.Text.Json; -using Microsoft.Extensions.AI; - -namespace AgentCore.Application.Transcript -{ - /// Something the caller was shown, carried by the message that produced it. - public sealed class RenderContent : AIContent - { - /// The renderer the host looks up. - public required string Name { get; set; } - - /// - /// Names the thing shown. Publishing the same id again within a turn replaces it. - /// - public required string RenderId { get; set; } - - /// The payload that renderer reads. Its shape belongs to the renderer. - public required JsonElement Data { get; set; } - } -} diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs index 0d0e3f7d..8630522d 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesContracts.cs @@ -204,6 +204,17 @@ internal sealed record SourcePayload public required string Origin { get; init; } } + /// One compaction notice, as the browser reads it. + internal sealed record CompactionPayload + { + /// Gets whether this notice opens or closes a compaction pass: start or end. + public required string Phase { get; init; } + + /// Gets how an end notice's pass went: compacted, unchanged, or + /// failed. Never carried on start. + public string? Outcome { get; init; } + } + /// One file the model published from the workspace and the store kept, as the browser reads it. internal sealed record FilePayload { @@ -222,14 +233,4 @@ internal sealed record FilePayload /// Gets the link to fetch it from, or when the store has no web door. public string? Url { get; init; } } - - /// One thing a stream asks the browser to draw. - internal sealed record RenderedPayload - { - /// Gets the renderer the browser looks up. - public required string Name { get; init; } - - /// Gets the payload that renderer reads. - public required JsonElement Data { get; init; } - } } diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs index 4a6d04a8..7bf03494 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesEndpoints.cs @@ -290,11 +290,6 @@ private static async Task RunTurnAsync( bool streaming = body.TryGetProperty("stream", out JsonElement streamFlag) && streamFlag.ValueKind == JsonValueKind.True; - // Only the stream has a frame to carry a drawing, so only the stream gets a screen. Binding - // one on the whole-reply branch would let the tool report a picture the caller never sees. - // Set per request, not once: the session outlives a request and the branch can differ per turn. - turn.Conversation.SetHasScreen(streaming); - if (CallerTimeZone.Parse(http.Request.Headers[TimeZoneHeaderName]) is { } zone) { CallerTimeZone.Set(turn.Session, zone); diff --git a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs index e617463e..7da5408d 100644 --- a/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs +++ b/src/AgentCore.AspNetCore/Endpoints/ResponsesTurnStream.cs @@ -1,6 +1,7 @@ using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Conversation; +using AgentCore.Application.Runtime.Turn; using AgentCore.Application.Tools; using Microsoft.Agents.AI; using Microsoft.Agents.AI.Hosting.OpenAI; @@ -17,13 +18,6 @@ namespace AgentCore.AspNetCore.Endpoints internal static class ResponsesTurnStream { /// Runs one turn and writes one Responses event for each update, filed under its ids. - /// - /// The session is filed after the enumeration ends, because the turn commits — - /// and the session only holds the turn — once the last update has left it. - /// The framework's frames carry text alone; when the request spoke the dialect, - /// each update's browser parts ride beside them as agentcore_* members, so drawings, - /// citations, tool halves, and approval asks stream. - /// internal static async Task WriteAsync( HttpContext http, ResponsesTurn turn, @@ -56,10 +50,6 @@ internal static async Task WriteAsync( } /// Runs one streaming turn on the conversation, wrapping each update with the agent's id. - /// - /// The framework converter sees every update untouched: it ignores the contents it - /// knows nothing of, so dialect lines duplicate nothing and pure streams lose nothing. - /// private static async IAsyncEnumerable StreamAgentUpdatesAsync( HttpContext http, ResponsesTurn turn, @@ -73,6 +63,8 @@ private static async IAsyncEnumerable StreamAgentUpdatesAsy .RunTurnMessageStreamingAtOriginAsync(turn.Input, turn.Origin, cancellationToken) .ConfigureAwait(false)) { + bool isNotice = update.Contents.OfType().Any(); + if (dialect) { foreach (TurnStreamPart part in TurnStreamParts.From(update, toolNames)) @@ -80,7 +72,15 @@ private static async IAsyncEnumerable StreamAgentUpdatesAsy await WritePartLineAsync(http, part, cancellationToken).ConfigureAwait(false); } - files.Note(update); + if (!isNotice) + { + files.Note(update); + } + } + + if (isNotice) + { + continue; } yield return new AgentResponseUpdate(update) { AgentId = turn.Agent.Id }; @@ -92,7 +92,7 @@ private static async IAsyncEnumerable StreamAgentUpdatesAsy // inside it: by here the bytes are in the store or never will be. Conversations conversations = http.RequestServices.GetRequiredService(); - await foreach (TurnStreamFile? part in files.ResolveAsync(conversations, turn.Conversation.ConversationId, cancellationToken).ConfigureAwait(false)) + await foreach (TurnStreamPart part in files.ResolveAsync(conversations, turn.Conversation.ConversationId, cancellationToken).ConfigureAwait(false)) { await WritePartLineAsync(http, part, cancellationToken).ConfigureAwait(false); } @@ -103,19 +103,9 @@ private static async IAsyncEnumerable StreamAgentUpdatesAsy private static async Task WritePartLineAsync( HttpContext http, TurnStreamPart part, CancellationToken cancellationToken) { - JsonObject line = part switch + JsonObject line = new() { - TurnStreamRender render - => new JsonObject { ["agentcore_data"] = JsonSerializer.SerializeToNode(render.Payload, ResponsesJson.Options) }, - TurnStreamSource source - => new JsonObject { ["agentcore_source"] = JsonSerializer.SerializeToNode(source.Payload, ResponsesJson.Options) }, - TurnStreamTool tool - => new JsonObject { ["agentcore_tool"] = JsonSerializer.SerializeToNode(tool.Payload, ResponsesJson.Options) }, - TurnStreamApproval approval - => new JsonObject { ["agentcore_approval"] = JsonSerializer.SerializeToNode(approval.Payload, ResponsesJson.Options) }, - TurnStreamFile file - => new JsonObject { ["agentcore_file"] = JsonSerializer.SerializeToNode(file.Payload, ResponsesJson.Options) }, - _ => throw new InvalidOperationException($"Unknown stream part: {part.GetType()}."), + [part.Member] = JsonSerializer.SerializeToNode(part.Payload, part.Payload.GetType(), ResponsesJson.Options), }; await http.Response.WriteAsync("data: ", cancellationToken).ConfigureAwait(false); diff --git a/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs b/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs index addb2dd7..ba030a51 100644 --- a/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs +++ b/src/AgentCore.AspNetCore/Endpoints/TurnStreamFiles.cs @@ -25,7 +25,7 @@ internal void Note(ChatResponseUpdate update) /// The conversation that owns the files. /// Cancels the lookups. /// One part for each file the store holds. - internal async IAsyncEnumerable ResolveAsync( + internal async IAsyncEnumerable ResolveAsync( Conversations conversations, string conversationId, [EnumeratorCancellation] CancellationToken cancellationToken) @@ -41,7 +41,7 @@ internal async IAsyncEnumerable ResolveAsync( foreach ((BlobRef? blob, Uri? url) in links) { - yield return new TurnStreamFile(new FilePayload + yield return new TurnStreamPart(TurnStreamPart.File, new FilePayload { Name = blob.Name, Title = _files.LastOrDefault(file => string.Equals(file.Name, blob.Name, StringComparison.Ordinal))?.Title, diff --git a/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs b/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs index 915e369a..7d80cd58 100644 --- a/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs +++ b/src/AgentCore.AspNetCore/Endpoints/TurnStreamParts.cs @@ -1,4 +1,6 @@ using System.Text.Json.Nodes; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Runtime.Turn; using AgentCore.Application.Tools; using AgentCore.Application.Transcript; using AgentCore.Domain.Sources; @@ -10,33 +12,28 @@ namespace AgentCore.AspNetCore.Endpoints /// The non-text parts of one streaming update, read once for every text endpoint. /// /// - /// A drawing, a citation, a tool half, and an approval ask ride ChatResponseUpdate - /// contents that no OpenAI shape carries. Each endpoint frames them its own way, but what - /// they mean — and what the browser reads — is one mapping, kept here so a new content - /// kind lands in one place. Text stays endpoint-side: completions deltas it, Responses - /// leaves it to the framework converter. + /// A citation, a tool half, an approval ask, and a notice ride ChatResponseUpdate + /// contents that no OpenAI shape carries. Each endpoint frames them its own way, but what they + /// mean — and what the browser reads — is one mapping, kept here so a new content kind lands in + /// one place: one case below, one payload record. Text stays endpoint-side: completions + /// deltas it, Responses leaves it to the framework converter. /// internal static class TurnStreamParts { - /// Reads one update's browser parts, in wire order: renders, sources, tools, approvals. + /// Reads one update's browser parts, in wire order: sources, tools, approvals, notices. /// One update of the stream. /// The pairing of call id to tool name for this turn, written and read here. /// One part for each browser payload the update carries, possibly none. internal static IEnumerable From(ChatResponseUpdate update, ToolCallNames toolNames) { - foreach (RenderContent drawn in update.Contents.OfType()) - { - yield return new TurnStreamRender(new RenderedPayload { Name = drawn.Name, Data = drawn.Data }); - } - foreach (SourceContent cited in update.Contents.OfType()) { - yield return new TurnStreamSource(SourcePayloadOf(cited)); + yield return new TurnStreamPart(TurnStreamPart.Source, SourcePayloadOf(cited)); } foreach (ToolPayload tool in ToolPayloadsOf(update, toolNames)) { - yield return new TurnStreamTool(tool); + yield return new TurnStreamPart(TurnStreamPart.Tool, tool); } foreach (ToolApprovalRequestContent asked in update.Contents.OfType()) @@ -45,7 +42,7 @@ internal static IEnumerable From(ChatResponseUpdate update, Tool // empty-text skip below and the caller never learns a tool waits on them. if (asked.ToolCall is FunctionCallContent call) { - yield return new TurnStreamApproval(new ApprovalPayload + yield return new TurnStreamPart(TurnStreamPart.Approval, new ApprovalPayload { RequestId = asked.RequestId, Tool = call.Name, @@ -53,6 +50,25 @@ internal static IEnumerable From(ChatResponseUpdate update, Tool }); } } + + foreach (NoticeContent notice in update.Contents.OfType()) + { + if (NoticePartOf(notice) is { } part) + { + yield return part; + } + } + } + + /// Frames one notice for the browser, or for a kind it does not show. + private static TurnStreamPart? NoticePartOf(NoticeContent notice) + { + return notice switch + { + CompactionContent compaction + => new TurnStreamPart(TurnStreamPart.Compaction, new CompactionPayload { Phase = compaction.Phase, Outcome = compaction.Outcome }), + _ => null, + }; } /// Reads the tool facts one update carries, in the order they appear on it. @@ -128,21 +144,24 @@ private static SourcePayload SourcePayloadOf(SourceContent cited) } } - /// One browser payload of a streaming update. - internal abstract record TurnStreamPart; - - /// One thing a chunk asks the browser to draw. - internal sealed record TurnStreamRender(RenderedPayload Payload) : TurnStreamPart; + /// One browser payload of a streaming update: the dialect member it goes out under, and its value. + /// The agentcore_* member name, one of the constants on this record. + /// The value serialized under , by its runtime type. + internal sealed record TurnStreamPart(string Member, object Payload) + { + /// Where one answer came from: a . + public const string Source = "agentcore_source"; - /// Where one answer came from, as the browser reads it. - internal sealed record TurnStreamSource(SourcePayload Payload) : TurnStreamPart; + /// One half of one tool call: a . + public const string Tool = "agentcore_tool"; - /// One half of one tool call, as the browser reads it. - internal sealed record TurnStreamTool(ToolPayload Payload) : TurnStreamPart; + /// One tool call waiting on the caller: an . + public const string Approval = "agentcore_approval"; - /// One tool call waiting on the caller, as the browser reads it. - internal sealed record TurnStreamApproval(ApprovalPayload Payload) : TurnStreamPart; + /// One compaction notice: a . + public const string Compaction = "agentcore_compaction"; - /// One file the turn produced, as the browser reads it. - internal sealed record TurnStreamFile(FilePayload Payload) : TurnStreamPart; + /// One file the turn produced: a . + public const string File = "agentcore_file"; + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs index af24ae94..d33fc24d 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/CompactionCompilationTests.cs @@ -1,4 +1,3 @@ -using System.Text.Json; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -51,12 +50,6 @@ public async Task Compile_AnAgent_KeepsReaderContentOutOfTheModelRequest() ChatMessage published = new(ChatRole.Tool, [new FunctionResultContent("call-1", "published")]); published.Contents.Add(new FileContent { Name = "report.md", FileId = "out/report.md", Kept = true }); - published.Contents.Add(new RenderContent - { - Name = "card", - RenderId = "card-1", - Data = JsonSerializer.SerializeToElement(new { title = "Report" }), - }); published.Contents.Add(new SourceContent { Source = new SourceReference { SourceId = "doc-1", Kind = SourceKind.Document, Title = "Doc", Origin = "knowledge" }, @@ -74,7 +67,7 @@ public async Task Compile_AnAgent_KeepsReaderContentOutOfTheModelRequest() Assert.DoesNotContain( reply.Requests[^1].SelectMany(message => message.Contents), - content => content is FileContent or RenderContent or SourceContent); + content => content is FileContent or SourceContent); } private static CompiledAgent CompileOneAgent(SequencedChatClient reply) diff --git a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs index eb289f8c..3e93bd9d 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Compilation/ConfigurationCompilerModelFacingTests.cs @@ -6,6 +6,7 @@ using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Tools.Binding; using AgentCore.Application.Transcript; +using AgentCore.Domain.Sources; using AgentCore.TestSupport; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; @@ -35,10 +36,10 @@ public sealed class ConfigurationCompilerModelFacingTests """; [Fact] - public async Task TheSecondRoundOfACompiledAgent_NeverForwardsARenderContentTheFirstRoundsToolAttached() + public async Task TheSecondRoundOfACompiledAgent_NeverForwardsASourceContentTheFirstRoundsToolAttached() { - TurnRenders renders = new(); - TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", Renders = renders }; + TurnSources sources = new(); + TurnInvocation turn = new() { ConversationId = "conversation", TurnIndex = 0, Stage = "", Sources = sources }; RequestCapturingChatClient recorder = new(new ToolCallingChatClient("done.")); AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); @@ -62,7 +63,7 @@ [new ChatMessage(ChatRole.User, "draw me a card")], Assert.Equal(2, recorder.Requests.Count); Assert.DoesNotContain( recorder.Requests[1], - message => message.Contents.Any(content => content is RenderContent)); + message => message.Contents.Any(content => content is SourceContent)); } private static AIFunction DrawCard() @@ -70,7 +71,7 @@ private static AIFunction DrawCard() return AIFunctionFactory.Create( (TurnInvocation? turn) => { - turn!.Renders!.Publish("card", "card-1", new { text = "hi" }); + turn!.Sources!.Publish(new SourceReference { SourceId = "card-1", Kind = SourceKind.Document, Title = "hi", Origin = "test.draw" }); return "drawn."; }, new AIFunctionFactoryOptions diff --git a/tests/AgentCore.Application.Tests/Runtime/Compaction/ConversationTurnStreamCompactionNoticeTests.cs b/tests/AgentCore.Application.Tests/Runtime/Compaction/ConversationTurnStreamCompactionNoticeTests.cs new file mode 100644 index 00000000..d9c69605 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/Compaction/ConversationTurnStreamCompactionNoticeTests.cs @@ -0,0 +1,133 @@ +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Transcript; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Xunit; +using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; + +namespace AgentCore.Application.Tests.Runtime.Compaction +{ + /// + /// D6: the streaming merge surfaces a compaction notice while the summariser's own model call is + /// still in flight, in order, and a cancel mid-wait ends the stream rather than hanging it. The + /// summariser is gated rather than delayed, so "the notice arrived before the summariser finished" + /// is a fact the test controls directly instead of a race against a clock. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class ConversationTurnStreamCompactionNoticeTests + { + [Fact] + public async Task TheStartNotice_ArrivesFirst_WhileTheSummariserIsStillBlocked() + { + InMemoryConversationStore store = await SeededStoreAsync(); + + TaskCompletionSource reachedSummariser = new(TaskCreationOptions.RunContinuationsAsynchronously); + TaskCompletionSource releaseSummariser = new(TaskCreationOptions.RunContinuationsAsynchronously); + CapturingChatClient summariser = new( + async callIndex => + { + _ = reachedSummariser.TrySetResult(); + await releaseSummariser.Task; + }, + "the gist of it"); + + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), + store, + conversationId: "c1", + compaction: Summary(summariser, minimumPreservedGroups: 0)); + + IAsyncEnumerator stream = session + .RunTurnStreamingAsync("q3", TestContext.Current.CancellationToken) + .GetAsyncEnumerator(TestContext.Current.CancellationToken); + await using (stream) + { + // The first update the caller sees is the start notice, and it arrives while the + // summariser is still blocked on its own gate — proof the merge does not wait for the + // provider's model call before surfacing what it already posted. + Assert.True(await stream.MoveNextAsync()); + CompactionContent start = Assert.Single(stream.Current.Contents.OfType()); + Assert.Equal(CompactionContent.StartPhase, start.Phase); + + // The summariser's own model call is still blocked on its gate at this point: the + // start notice above did not wait for it to finish, only for it to begin. + await reachedSummariser.Task.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken); + _ = releaseSummariser.TrySetResult(); + + Assert.True(await stream.MoveNextAsync()); + CompactionContent end = Assert.Single(stream.Current.Contents.OfType()); + Assert.Equal(CompactionContent.EndPhase, end.Phase); + Assert.Equal("compacted", end.Outcome); + + Assert.True(await stream.MoveNextAsync()); + Assert.Equal("a3", stream.Current.Text); + } + } + + [Fact] + public async Task ACancelWhileTheSummariserIsBlocked_EndsTheStreamWithOperationCanceled_AndDoesNotHang() + { + InMemoryConversationStore store = await SeededStoreAsync(); + + GatedChatClient summariser = new(); + + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), + store, + conversationId: "c1", + compaction: Summary(summariser, minimumPreservedGroups: 0)); + + using CancellationTokenSource cts = new(); + List seen = []; + + Task run = Task.Run(async () => + { + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("q3", cts.Token)) + { + seen.Add(update.Contents.OfType().FirstOrDefault()?.Phase ?? "text"); + if (seen.Count == 1) + { + cts.Cancel(); + } + } + }, TestContext.Current.CancellationToken); + + Task finished = await Task.WhenAny(run, Task.Delay(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken)); + + Assert.Same(run, finished); + _ = await Assert.ThrowsAnyAsync(() => run); + Assert.Equal([CompactionContent.StartPhase], seen); + } + + /// + /// A summariser that blocks until the run's own cancellation token fires, the way a real HTTP + /// call would. 's hook carries no token to block on, so it + /// cannot stand in for a provider that actually respects cancellation. + /// + private sealed class GatedChatClient : IChatClient + { + public async Task GetResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken); + return new ChatResponse(new ChatMessage(ChatRole.Assistant, "unreachable")); + } + + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotSupportedException("Summarisation runs the buffered path only."); + } + + public object? GetService(Type serviceType, object? serviceKey = null) => null; + + public void Dispose() + { + } + } + } +#pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Runtime/Compaction/SummaryRowProviderNoticeTests.cs b/tests/AgentCore.Application.Tests/Runtime/Compaction/SummaryRowProviderNoticeTests.cs new file mode 100644 index 00000000..566c87e2 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/Compaction/SummaryRowProviderNoticeTests.cs @@ -0,0 +1,129 @@ +using AgentCore.Application.Conversation.Memory; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Transcript; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Xunit; +using static AgentCore.Application.Tests.Transcript.ConversationSessionCompactionTestSupport; + +namespace AgentCore.Application.Tests.Runtime.Compaction +{ + /// + /// D2: a start notice goes out only when the summariser model is actually called, and an end + /// notice always follows it with the outcome the pass had. Every fact here comes from a real + /// streaming turn, so the notice count is read off the wire the caller would see, not off an + /// internal hook. + /// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.21.0. + public sealed class SummaryRowProviderNoticeTests + { + [Fact] + public async Task ATriggerThatNeverFires_CallsTheSummariserZeroTimes_AndPostsNoNotice() + { + InMemoryConversationStore store = await SeededStoreAsync(); + CapturingChatClient summariser = new(_ => Task.CompletedTask, "unused"); + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), + store, + conversationId: "c1", + compaction: SummaryOnly(summariser, client => new SummarizationCompactionStrategy(client, CompactionTriggers.Never, minimumPreservedGroups: 0))); + + List updates = await RunAsync(session); + + Assert.Empty(summariser.Requests); + Assert.Empty(NoticesIn(updates)); + } + + [Fact] + public async Task ATriggerThatAlwaysFires_CallsTheSummariserOnce_AndPostsStartThenEndCompacted() + { + InMemoryConversationStore store = await SeededStoreAsync(); + CapturingChatClient summariser = new(_ => Task.CompletedTask, "the gist of it"); + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), + store, + conversationId: "c1", + compaction: Summary(summariser, minimumPreservedGroups: 0)); + + List updates = await RunAsync(session); + + _ = Assert.Single(summariser.Requests); + Assert.Equal([(CompactionContent.StartPhase, null), (CompactionContent.EndPhase, "compacted")], NoticesIn(updates)); + } + + [Fact] + public async Task ASummariserThatThrows_PostsStartThenEndUnchanged_AndTheReplyStillRuns() + { + // SummarizationCompactionStrategy swallows its own client's exception and reports no + // compaction, so the provider sees a called summariser and an untouched view: "unchanged", + // not "failed". + InMemoryConversationStore store = await SeededStoreAsync(); + CapturingChatClient summariser = new(_ => Task.FromException(new IOException("summariser down")), "unused"); + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), + store, + conversationId: "c1", + compaction: Summary(summariser, minimumPreservedGroups: 0)); + + List updates = await RunAsync(session); + + _ = Assert.Single(summariser.Requests); + Assert.Equal([(CompactionContent.StartPhase, null), (CompactionContent.EndPhase, "unchanged")], NoticesIn(updates)); + Assert.Equal("a3", ReplyIn(updates)); + } + + [Fact] + public async Task AStrategyThatThrowsAfterTheCall_PostsStartThenEndFailed_AndTheReplyStillRuns() + { + // No shipped strategy throws past its own guard; this one does, to reach the provider's + // catch and prove the rule it exists for: a failed pass never ends the turn. + InMemoryConversationStore store = await SeededStoreAsync(); + ConversationSession session = CreateSession( + new ScriptedChatClient("a3"), + store, + conversationId: "c1", + compaction: SummaryOnly(new ScriptedChatClient("unused"), client => new CallsThenThrowsStrategy(client))); + + List updates = await RunAsync(session); + + Assert.Equal([(CompactionContent.StartPhase, null), (CompactionContent.EndPhase, "failed")], NoticesIn(updates)); + Assert.Equal("a3", ReplyIn(updates)); + } + + private static async Task> RunAsync(ConversationSession session) + { + List updates = []; + await foreach (ChatResponseUpdate update in session.RunTurnStreamingAsync("q3", TestContext.Current.CancellationToken)) + { + updates.Add(update); + } + + return updates; + } + + private static IEnumerable<(string Phase, string? Outcome)> NoticesIn(IEnumerable updates) + { + return updates + .SelectMany(update => update.Contents.OfType()) + .Select(notice => (notice.Phase, notice.Outcome)); + } + + private static string ReplyIn(IEnumerable updates) + { + return string.Concat(updates.Where(update => !update.Contents.OfType().Any()).Select(update => update.Text)); + } + + private sealed class CallsThenThrowsStrategy(IChatClient client) : CompactionStrategy(CompactionTriggers.Always) + { + protected override async ValueTask CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken) + { + _ = await client.GetResponseAsync([], cancellationToken: cancellationToken).ConfigureAwait(false); + throw new InvalidOperationException("boom"); + } + } + } +#pragma warning restore MAAI001 +} diff --git a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs index 9a3206c4..8a21c381 100644 --- a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs @@ -41,7 +41,7 @@ public async Task Create_AViewAt76PercentOfTheWindow_FiresAndKeepsOnlyTheFourNew List view = Conversation(pairs: 20, charsPerMessage: 76); List compacted = [.. await CompactionProvider.CompactAsync( - stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; + stages.Summary(stages.Summariser), view, cancellationToken: TestContext.Current.CancellationToken)]; AssertSummaryThenTail(view, compacted); } @@ -58,7 +58,7 @@ public async Task Create_AOneMillionWindowAtJustOverTheCeiling_FiresAndKeepsOnly List view = Conversation(pairs: 20, charsPerMessage: 20_004); List compacted = [.. await CompactionProvider.CompactAsync( - stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; + stages.Summary(stages.Summariser), view, cancellationToken: TestContext.Current.CancellationToken)]; AssertSummaryThenTail(view, compacted); } @@ -75,7 +75,7 @@ public async Task Create_AViewAt74PercentOfTheWindow_ComesBackUnchanged() List view = Conversation(pairs: 20, charsPerMessage: 74); List compacted = [.. await CompactionProvider.CompactAsync( - stages.Summary, view, cancellationToken: TestContext.Current.CancellationToken)]; + stages.Summary(stages.Summariser), view, cancellationToken: TestContext.Current.CancellationToken)]; Assert.Equal(view.Count, compacted.Count); for (int index = 0; index < view.Count; index++) diff --git a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs index daf905cc..438bfc29 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ConversationSessionFactoryModelFacingTests.cs @@ -1,4 +1,3 @@ -using System.Text.Json; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; @@ -6,6 +5,7 @@ using AgentCore.Application.State; using AgentCore.Application.Tests.Fakes; using AgentCore.Application.Transcript; +using AgentCore.Domain.Sources; using AgentCore.TestSupport; using Microsoft.Extensions.AI; using Xunit; @@ -14,9 +14,9 @@ namespace AgentCore.Application.Tests.Runtime { /// /// ConversationSessionFactory.CreateExtractor is the third site that must strip a - /// before a model reads it — ConversationSession.ExtractAsync hands the + /// before a model reads it — ConversationSession.ExtractAsync hands the /// extractor [turn.Spoken, .. response.Messages], and response.Messages is exactly the - /// list a drawing tool attaches to. This proves the extractor builds, + /// list a citing tool attaches to. This proves the extractor builds, /// not a hand-constructed ModelFacingChatClient. /// public sealed class ConversationSessionFactoryModelFacingTests @@ -38,7 +38,7 @@ public sealed class ConversationSessionFactoryModelFacingTests """; [Fact] - public async Task TheExtractorTheFactoryBuilds_NeverForwardsARenderContentTheTurnAttached() + public async Task TheExtractorTheFactoryBuilds_NeverForwardsASourceContentTheTurnAttached() { AgentCoreConfiguration document = ConfigurationLoader.LoadYaml(Yaml); CompiledAgent compiled = ConfigurationCompiler.CompileAll( @@ -52,20 +52,23 @@ public async Task TheExtractorTheFactoryBuilds_NeverForwardsARenderContentTheTur Assert.NotNull(extractor); - JsonElement payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); - ChatMessage drew = new(ChatRole.Assistant, + ChatMessage cited = new(ChatRole.Assistant, [ new TextContent("here's the order."), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = payload }, + new SourceContent + { + Source = new SourceReference { SourceId = "order-41", Kind = SourceKind.Document, Title = "Order #41", Origin = "knowledge" }, + CallId = "call-1", + }, ]); _ = await extractor!.ExtractAsync( new StateDocument(compiled.Configuration), - [new ChatMessage(ChatRole.User, "show me the order"), drew], + [new ChatMessage(ChatRole.User, "show me the order"), cited], TestContext.Current.CancellationToken); IReadOnlyList forwarded = Assert.Single(recorder.Requests); - Assert.DoesNotContain(forwarded, message => message.Contents.Any(content => content is RenderContent)); + Assert.DoesNotContain(forwarded, message => message.Contents.Any(content => content is SourceContent)); } } } diff --git a/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs b/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs index 679afb92..2cc38f58 100644 --- a/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/Harness/BackgroundChildAgentTests.cs @@ -67,14 +67,14 @@ public async Task CreateSessionAsync_InsideTheParentsRun_FilesTheParentsWorkspac BackgroundChildAgent child = new(new ChatClientAgent(new ScriptedChatClient("child"))); SessionCreatingProvider creating = new(child); ChatClientAgent parent = new(new ScriptedChatClient("parent"), new ChatClientAgentOptions { AIContextProviders = [creating] }); - TurnRenders renders = new(); + TurnSources sources = new(); TurnInvocation turn = new() { ConversationId = "conversation-9", TurnIndex = 0, Stage = "s", Workspace = "/work/conversation-9", - Renders = renders, + Sources = sources, }; // Act @@ -87,7 +87,7 @@ public async Task CreateSessionAsync_InsideTheParentsRun_FilesTheParentsWorkspac Assert.Equal("/work/conversation-9", filed.Workspace); Assert.Equal("conversation-9", filed.ConversationId); Assert.True(filed.Nested); - Assert.Null(filed.Renders); + Assert.Null(filed.Sources); } [Fact] diff --git a/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs b/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs index e08c8109..0ef539b6 100644 --- a/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/ModelFacingChatClientTests.cs @@ -1,63 +1,67 @@ -using System.Text.Json; using AgentCore.Application.Runtime; using AgentCore.Application.Transcript; +using AgentCore.Domain.Sources; using Microsoft.Extensions.AI; using Xunit; namespace AgentCore.Application.Tests.Runtime { /// - /// is the only seam that strips a + /// is the only seam that strips a /// before the model reads it. Every assertion here is against what the fake inner /// received, never against the returned response, because the strip must /// happen to the outgoing request and nothing else. /// public sealed class ModelFacingChatClientTests { - private static readonly JsonElement Payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); + private static readonly SourceContent Citation = new() + { + Source = new SourceReference { SourceId = "order-41", Kind = SourceKind.Document, Title = "Order #41", Origin = "knowledge" }, + CallId = "call-1", + }; [Fact] - public async Task GetResponseAsync_StripsRenderContentBeforeTheInnerClientSeesIt() + public async Task GetResponseAsync_StripsSourceContentBeforeTheInnerClientSeesIt() { SequencedChatClient inner = new("ok"); ModelFacingChatClient client = new(inner); - ChatMessage drew = new(ChatRole.Assistant, + ChatMessage cited = new(ChatRole.Assistant, [ new TextContent("here you go"), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, + Citation, ]); - _ = await client.GetResponseAsync([drew], cancellationToken: TestContext.Current.CancellationToken); + _ = await client.GetResponseAsync([cited], cancellationToken: TestContext.Current.CancellationToken); List forwarded = Assert.Single(inner.Requests); ChatMessage message = Assert.Single(forwarded); - Assert.DoesNotContain(message.Contents, c => c is RenderContent); + Assert.DoesNotContain(message.Contents, c => c is SourceContent); _ = Assert.Single(message.Contents.OfType()); } [Fact] - public async Task GetStreamingResponseAsync_StripsRenderContentBeforeTheInnerClientSeesIt() + public async Task GetStreamingResponseAsync_StripsSourceContentBeforeTheInnerClientSeesIt() { SequencedChatClient inner = new("ok"); ModelFacingChatClient client = new(inner); - ChatMessage drew = new(ChatRole.Assistant, + ChatMessage cited = new(ChatRole.Assistant, [ new TextContent("here you go"), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, + Citation, ]); await foreach (ChatResponseUpdate _ in client.GetStreamingResponseAsync( - [drew], cancellationToken: TestContext.Current.CancellationToken)) + [cited], cancellationToken: TestContext.Current.CancellationToken)) { } List forwarded = Assert.Single(inner.Requests); ChatMessage message = Assert.Single(forwarded); - Assert.DoesNotContain(message.Contents, c => c is RenderContent); + Assert.DoesNotContain(message.Contents, c => c is SourceContent); } [Fact] - public async Task GetResponseAsync_PassesAMessageWithNoRenderContentThroughByReference() + public async Task GetResponseAsync_PassesAMessageWithNoSourceContentThroughByReference() { SequencedChatClient inner = new("ok"); ModelFacingChatClient client = new(inner); @@ -70,7 +74,7 @@ public async Task GetResponseAsync_PassesAMessageWithNoRenderContentThroughByRef } [Fact] - public async Task GetStreamingResponseAsync_PassesAMessageWithNoRenderContentThroughByReference() + public async Task GetStreamingResponseAsync_PassesAMessageWithNoSourceContentThroughByReference() { SequencedChatClient inner = new("ok"); ModelFacingChatClient client = new(inner); @@ -90,9 +94,9 @@ public async Task GetResponseAsync_RebuiltMessageCarriesAdditionalPropertiesAndI { SequencedChatClient inner = new("ok"); ModelFacingChatClient client = new(inner); - ChatMessage drew = new(ChatRole.Assistant, + ChatMessage cited = new(ChatRole.Assistant, [ - new RenderContent { Name = "order-card", RenderId = "order-41", Data = Payload }, + Citation, ]) { MessageId = "msg-1", @@ -101,7 +105,7 @@ public async Task GetResponseAsync_RebuiltMessageCarriesAdditionalPropertiesAndI AdditionalProperties = new AdditionalPropertiesDictionary { ["k"] = "v" }, }; - _ = await client.GetResponseAsync([drew], cancellationToken: TestContext.Current.CancellationToken); + _ = await client.GetResponseAsync([cited], cancellationToken: TestContext.Current.CancellationToken); ChatMessage forwarded = Assert.Single(Assert.Single(inner.Requests)); Assert.Equal("msg-1", forwarded.MessageId); diff --git a/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs b/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs index ef799eee..d15516ff 100644 --- a/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs +++ b/tests/AgentCore.Application.Tests/Runtime/RuntimeFakes.cs @@ -1,7 +1,6 @@ using System.Runtime.CompilerServices; using System.Text.Json; using AgentCore.Application.Configuration.Schema; -using AgentCore.Application.Ports; using AgentCore.Application.Tools; using Microsoft.Extensions.AI; @@ -603,17 +602,6 @@ public void Dispose() } } - /// A screen that records everything it was asked to show, in the order it was shown. - internal sealed class RecordingRenderPort : IRenderPort - { - public List<(string Name, string RenderId, object Data, bool Transient)> Published { get; } = []; - - public void Publish(string name, string renderId, object data, bool transient = false) - { - Published.Add((name, renderId, data, transient)); - } - } - /// /// A model that calls a scripted list of tools by name, one per request, then answers in words. /// diff --git a/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs b/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs deleted file mode 100644 index 298f9d97..00000000 --- a/tests/AgentCore.Application.Tests/Runtime/TurnScreenTests.cs +++ /dev/null @@ -1,157 +0,0 @@ -using AgentCore.Application.Configuration.Compilation; -using AgentCore.Application.Configuration.Parsing; -using AgentCore.Application.Configuration.Validation; -using AgentCore.Application.Ports; -using AgentCore.Application.Runtime; -using AgentCore.Application.Runtime.Turn; -using AgentCore.Application.Tests.Fakes; -using AgentCore.Application.Tools.Binding; -using AgentCore.TestSupport; -using Microsoft.Extensions.AI; -using Xunit; - -namespace AgentCore.Application.Tests.Runtime -{ - /// - /// The turn reaches its tools: the screen the loop builds arriving at the tool that publishes. - /// - public sealed class TurnScreenTests - { - private const string DelegationYaml = """ - apiVersion: agentcore/v1 - tools: - - { id: ask_specialist, kind: agent, agent: specialist, description: Ask the specialist. } - agents: - defaults: - model: { ref: reply } - items: - - { id: greeter, instructions: "greet the caller", tools: [ ask_specialist ] } - - { id: specialist, model: { ref: specialist }, instructions: "answer the greeter" } - entries: - main: - policy: - initial: greeting - stages: - - { id: greeting, agent: greeter, terminal: true } - """; - - [Fact] - public async Task ATurnThatDoesNotStream_ShowsItsToolsTheScreen() - { - (ConversationSession? session, ScreenProbe? probe) = NewConversation(); - - _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - // The screen a tool finds must be the SAME recorder the turn publishes into, not merely - // some TurnRenders or other: a regression that handed the tool a different instance would - // still publish, and would still lose the render, since the drain reads the turn's own. - _ = Assert.IsType(probe.Seen); - Assert.Same(probe.TurnRenders, probe.Seen); - } - - [Fact] - public async Task ATurnThatStreams_ShowsItsToolsTheScreenToo() - { - // The hazard this pins. An async iterator restores its caller's execution context at every - // yield, and the framework streams the tool-call update BEFORE it invokes the function, so a - // scope opened once reaches no round at all. Only the per-round re-entry in - // RunTurnStreamingAsync keeps the screen alive across it. - (ConversationSession? session, ScreenProbe? probe) = NewConversation(); - - await foreach (ChatResponseUpdate _ in session.RunTurnStreamingAsync("hi", TestContext.Current.CancellationToken)) - { - } - - _ = Assert.IsType(probe.Seen); - Assert.Same(probe.TurnRenders, probe.Seen); - } - - [Fact] - public async Task AConversationThatWasGivenNoScreen_ShowsItsToolsNone() - { - // The voice path. The tool reads the null and tells the model it cannot show anything, - // rather than claiming a picture a telephone caller will never see. - (ConversationSession? session, ScreenProbe? probe) = NewConversation(withScreen: false); - - _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.True(probe.Ran); - Assert.Null(probe.Seen); - } - - [Fact] - public async Task AScreenTakenBackBeforeATurn_LeavesTheToolWithNone() - { - // A host sets this per request, and the whole-reply branch of the chat endpoint sets none. - // Taking it back has to reach the tool, or a session that streamed once keeps a screen the - // next answer has nowhere to write. - (ConversationSession? session, ScreenProbe? probe) = NewConversation(); - - session.SetHasScreen(false); - - _ = await session.RunTurnAsync("hi", TestContext.Current.CancellationToken); - - Assert.True(probe.Ran); - Assert.Null(probe.Seen); - } - - /// Opens a conversation whose specialist is handed one tool that reports the screen it found. - private static (ConversationSession Session, ScreenProbe Probe) NewConversation(bool withScreen = true) - { - ToolCallingChatClient greeter = new( - "hello there.", - new Dictionary(StringComparer.Ordinal) { ["query"] = "check the order system" }); - ToolCallingChatClient specialist = new("the specialist answer"); - - RoutingChatClientFactory chatClients = new(greeter); - _ = chatClients.Route("reply", greeter); - _ = chatClients.Route("specialist", specialist); - - CompiledAgent compiled = ConfigurationCompiler.CompileAll( - ConfigurationLoader.LoadYaml(DelegationYaml), new AgentCompilationContext(chatClients))["main"]; - - ConversationSession session = new ConversationSessionFactory( - compiled, - new GuardEvaluator(compiled.Configuration.Guards), - extractor: null).Create(); - - ScreenProbe probe = new(); - - session.SetHasScreen(withScreen); - session.SetDelegatedTools("ask_specialist", [probe.Tool]); - - return (session, probe); - } - - /// A tool that reports the screen and the recorder it found, from wherever it ran. - private sealed class ScreenProbe - { - public ScreenProbe() - { - Tool = AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - Ran = true; - Seen = turn?.Screen; - TurnRenders = turn?.Renders; - return "shown."; - }, - new AIFunctionFactoryOptions - { - Name = "build_ui", - Description = "Show something on the caller's screen.", - ConfigureParameterBinding = ToolParameterBindings.For, - }); - } - - public AIFunction Tool { get; } - - public bool Ran { get; private set; } - - public IRenderPort? Seen { get; private set; } - - /// What the turn drew into at the same moment was read. - public TurnRenders? TurnRenders { get; private set; } - } - } -} diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs index 1dfb3209..47f7931b 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTestSupport.cs @@ -53,13 +53,30 @@ internal static ConversationSession CreateSession( /// Stages whose cap never fires and whose summary always does. internal static CompactionStages Summary(IChatClient summariser, int minimumPreservedGroups) { - return SummaryOnly(new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups)); + return SummaryOnly(summariser, client => new SummarizationCompactionStrategy(client, CompactionTriggers.Always, minimumPreservedGroups)); } - /// Stages whose cap never fires. + /// Stages whose cap never fires, over a bespoke strategy that answers no client of its own. internal static CompactionStages SummaryOnly(CompactionStrategy summary) { - return new(new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 1), summary); + return SummaryOnly(new ScriptedChatClient("unused"), _ => summary); + } + + /// Stages whose cap never fires, built from the summariser and the strategy factory the provider itself wraps. + internal static CompactionStages SummaryOnly(IChatClient summariser, Func summary) + { + return new(new ToolResultCapProvider(CompactionTriggers.Never, keepTurns: 0, maxResultChars: 1), summariser, summary); + } + + /// A store holding conversation c1 with three plain turns, enough for a summary pass to have something to fold. + internal static async Task SeededStoreAsync() + { + InMemoryConversationStore store = new(); + _ = await store.CreateAsync("c1", TestContext.Current.CancellationToken); + await SeedPlainTurnAsync(store, 0, "q0", "a0"); + await SeedPlainTurnAsync(store, 1, "q1", "a1"); + await SeedPlainTurnAsync(store, 2, "q2", "a2"); + return store; } /// Seeds one turn of a plain question and reply, two rows. diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs index bce9e062..9c0bfdff 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionCompactionTests.cs @@ -89,7 +89,8 @@ public async Task TheSummary_ReadsTheCappedResults_AndCoversTheirRows() CapturingChatClient summariser = new(_ => Task.CompletedTask, "the gist of it"); CompactionStages stages = new( new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), - new SummarizationCompactionStrategy(summariser, CompactionTriggers.Always, minimumPreservedGroups: 3)); + summariser, + client => new SummarizationCompactionStrategy(client, CompactionTriggers.Always, minimumPreservedGroups: 3)); ConversationSession session = CreateSession(new ScriptedChatClient("a3"), store, conversationId: "c1", compaction: stages); _ = await session.RunTurnAsync("q3", TestContext.Current.CancellationToken); @@ -114,7 +115,8 @@ public async Task ACapOnlyStage_WritesNoRow_AndTheRequestCarriesTheCappedResults CapturingChatClient reply = new(_ => Task.CompletedTask, "a2"); CompactionStages stages = new( new ToolResultCapProvider(CompactionTriggers.Always, keepTurns: 0, maxResultChars: 3), - new SummarizationCompactionStrategy(new ScriptedChatClient("never"), CompactionTriggers.Never)); + new ScriptedChatClient("never"), + client => new SummarizationCompactionStrategy(client, CompactionTriggers.Never)); ConversationSession session = CreateSession(reply, store, conversationId: "c1", compaction: stages); _ = await session.RunTurnAsync("q2", TestContext.Current.CancellationToken); diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs index 92f73efa..0c802ca8 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationSessionTranscriptTests.cs @@ -130,79 +130,6 @@ public async Task InterruptAfterTheTurnEnded_ToolTurnWithProse_StoresTheHeardWor rows.Select(row => row.Content.Text).Where(text => text.Length > 0)); } - /// - /// A barge-in rewrites the assistant reply in place, but a render rides the tool-result - /// message from earlier in the same turn — a different row entirely. Correcting the reply must - /// leave that row, and what it carries, alone. - /// - [Fact] - public async Task InterruptAfterTheTurnEnded_ToolTurnThatRendered_LeavesTheRenderContentOnTheToolResultRow() - { - // Arrange - RecordingConversationStore store = new(); - using ProseThenReplyChatClient reply = new("the price is fifty"); - ConversationSession session = CreateSession(ToolYaml, reply, store, RenderTool); - session.SetHasScreen(true); - await DrainAsync(session.RunTurnStreamingAsync("how much?", TestContext.Current.CancellationToken)); - - // Act - bool recorded = session.Interrupt("the price", TimeSpan.FromMilliseconds(400)); - - // Assert - Assert.True(recorded); - await session.FlushTranscriptAsync(); - IReadOnlyList rows = store.Live(session.ConversationId); - Assert.Equal( - ["how much?", "the price"], - rows.Select(row => row.Content.Text).Where(text => text.Length > 0)); - - ConversationMessage toolResultRow = Assert.Single(rows, row => row.Content.Contents.OfType().Any()); - RenderContent render = Assert.Single(toolResultRow.Content.Contents.OfType()); - Assert.Equal("chart-1", render.RenderId); - } - - /// - /// Drives a real turn end to end through , with a screen bound and a - /// real tool that publishes through it, and reads what store 1 actually kept. Every other render - /// test in this suite hand-rolls collectors, so none of them would notice a broken wire between - /// the turn's invocation and its renders — this is the one test that goes through that wire - /// itself. - /// - [Fact] - public async Task ATurnThatRendersWithAScreenBound_StoresTheRenderContentOnTheToolResultRow() - { - // Arrange - RecordingConversationStore store = new(); - ToolCallingChatClient reply = new("drew it."); - ConversationSession session = CreateSession(ToolYaml, reply, store, RenderTool); - session.SetHasScreen(true); - - // Act - _ = await session.RunTurnAsync("how much?", TestContext.Current.CancellationToken); - - // Assert - await session.FlushTranscriptAsync(); - IReadOnlyList rows = store.Live(session.ConversationId); - Assert.Contains(rows.SelectMany(row => row.Content.Contents), content => content is RenderContent); - } - - /// Builds a real tool that publishes through the turn's screen, for . - private static AITool? RenderTool(ToolConfiguration tool) - { - return AIFunctionFactory.Create( - (TurnInvocation? turn) => - { - turn!.Screen!.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); - return "drew it."; - }, - new AIFunctionFactoryOptions - { - Name = tool.Id, - Description = tool.Description ?? tool.Id, - ConfigureParameterBinding = ToolParameterBindings.For, - }); - } - /// /// Step 1's second failure mode: a cut that reached back a turn would replace a sentence the /// caller heard in full, and nothing would detect it. The guard is ConversationSession's, so this diff --git a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs index a6cd558d..6dbb6b82 100644 --- a/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/ConversationTranscriptTests.cs @@ -1,5 +1,5 @@ -using System.Text.Json; using AgentCore.Application.Transcript; +using AgentCore.Domain.Sources; using Microsoft.Extensions.AI; using Xunit; @@ -8,17 +8,19 @@ namespace AgentCore.Application.Tests.Transcript /// Pins the rules of store 1: ordinals, which reply a barge-in cuts, and what a cut keeps. public sealed class ConversationTranscriptTests { - private static readonly JsonElement Payload = JsonDocument.Parse("""{"x":1}""").RootElement.Clone(); - [Fact] - public void Append_ToolResultCarriesARender_RowKeepsItAndMessagesStripsIt() + public void Append_ToolResultCarriesASource_RowKeepsItAndMessagesStripsIt() { // Arrange ConversationTranscript transcript = new() { ConversationId = "conversation-1" }; - RenderContent render = new() { Name = "order-card", RenderId = "order-41", Data = Payload }; + SourceContent cited = new() + { + Source = new SourceReference { SourceId = "order-41", Kind = SourceKind.Document, Title = "Order #41", Origin = "knowledge" }, + CallId = "conversation-1", + }; ChatMessage toolResult = new( ChatRole.Tool, - [new FunctionResultContent("conversation-1", "50"), render]); + [new FunctionResultContent("conversation-1", "50"), cited]); ChatMessage plain = Assistant("the price is fifty"); // Act @@ -28,12 +30,12 @@ public void Append_ToolResultCarriesARender_RowKeepsItAndMessagesStripsIt() ChatMessage storedToolResult = transcript.Messages[0].Message; // The row is untouched: Append never rebuilds the message it hands to the store, so the - // row is the exact original object, drawing and tool result both. + // row is the exact original object, citation and tool result both. Assert.Same(toolResult, rows[0].Content); - Assert.Contains(render, rows[0].Content.Contents); + Assert.Contains(cited, rows[0].Content.Contents); _ = Assert.Single(rows[0].Content.Contents.OfType()); - Assert.DoesNotContain(storedToolResult.Contents, content => content is RenderContent); + Assert.DoesNotContain(storedToolResult.Contents, content => content is SourceContent); _ = Assert.Single(storedToolResult.Contents.OfType()); Assert.Equal(rows[0].Content.Role, storedToolResult.Role); Assert.Equal(rows[0].Ordinal, transcript.Messages[0].Ordinal); diff --git a/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs b/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs index 3c458d4d..4ae1572e 100644 --- a/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs +++ b/tests/AgentCore.Application.Tests/Transcript/TranscriptJsonTests.cs @@ -1,6 +1,7 @@ using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Transcript; +using AgentCore.Domain.Sources; using Microsoft.Extensions.AI; using Xunit; @@ -15,20 +16,23 @@ public sealed class TranscriptJsonTests [Fact] public void Options_RoundTripsAMessageWithOutOfOrderTypeDiscriminators() { - // Arrange - JsonElement data = JsonSerializer.SerializeToElement(new - { - orderId = "41", - widget = new Dictionary { ["$type"] = "custom-widget", ["label"] = "Order #41" }, - }); - + // Arrange — the nested "$type" key inside the tool result is unrelated user data, and must + // survive reordering untouched, alongside the outer array's own discriminators. ChatMessage message = new(ChatRole.Assistant, [ new TextContent("here's your order"), new FunctionCallContent("conversation-1", "lookup_order", new Dictionary { ["orderId"] = "41" }), - new FunctionResultContent("conversation-1", new { status = "shipped" }), + new FunctionResultContent("conversation-1", new + { + status = "shipped", + widget = new Dictionary { ["$type"] = "custom-widget", ["label"] = "Order #41" }, + }), new UsageContent(new UsageDetails { InputTokenCount = 10, OutputTokenCount = 5 }), - new RenderContent { Name = "order-card", RenderId = "order-41", Data = data }, + new SourceContent + { + Source = new SourceReference { SourceId = "order-41", Kind = SourceKind.Document, Title = "Order #41", Origin = "knowledge" }, + CallId = "conversation-1", + }, ]); string json = JsonSerializer.Serialize(message, TranscriptJson.Options); @@ -40,10 +44,14 @@ public void Options_RoundTripsAMessageWithOutOfOrderTypeDiscriminators() // Assert Assert.Equal(5, result.Contents.Count); - RenderContent render = Assert.Single(result.Contents.OfType()); - Assert.Equal("order-card", render.Name); - Assert.Equal("order-41", render.RenderId); - Assert.True(JsonNode.DeepEquals(JsonNode.Parse(data.GetRawText()), JsonNode.Parse(render.Data.GetRawText()))); + SourceContent source = Assert.Single(result.Contents.OfType()); + Assert.Equal("order-41", source.Source.SourceId); + Assert.Equal("conversation-1", source.CallId); + + FunctionResultContent tool = Assert.Single(result.Contents.OfType()); + JsonNode? toolResult = JsonSerializer.SerializeToNode(tool.Result); + Assert.Equal("shipped", toolResult!["status"]!.GetValue()); + Assert.Equal("custom-widget", toolResult["widget"]!["$type"]!.GetValue()); } /// Rewrites every object in the tree so a $type key, if present, comes back last. diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/CompactionWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/CompactionWireTests.cs new file mode 100644 index 00000000..49bc18cf --- /dev/null +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/CompactionWireTests.cs @@ -0,0 +1,50 @@ +using System.Text.Json; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Tools; +using AgentCore.AspNetCore.Endpoints; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.AspNetCore.Tests.Endpoints +{ + /// + /// D8: a compaction notice rides the dialect as its own agentcore_compaction part, with the + /// same null-omitting JSON every other payload uses. + /// + /// + /// D7 — the notice update never reaches the framework converter — lives in + /// ResponsesTurnStream.StreamAgentUpdatesAsync, which the YAML-driven host used by + /// ToolWireTests cannot drive: compaction is not a document-configurable feature. The + /// converter's split, and why the drop matters, is recorded in + /// docs/probes/CompactionNoticeWireProbe; nothing here re-proves the framework. + /// + public sealed class CompactionWireTests + { + [Fact] + public void ACompactionNotice_MapsToOneCompactionPart() + { + ChatResponseUpdate update = new(ChatRole.Assistant, [new CompactionContent(CompactionContent.EndPhase, "compacted")]); + + TurnStreamPart part = Assert.Single(TurnStreamParts.From(update, new ToolCallNames())); + + Assert.Equal(TurnStreamPart.Compaction, part.Member); + CompactionPayload payload = Assert.IsType(part.Payload); + Assert.Equal(CompactionContent.EndPhase, payload.Phase); + Assert.Equal("compacted", payload.Outcome); + } + + [Fact] + public void AStartNotice_SerializesWithNoOutcomeMember() + { + CompactionPayload start = new() { Phase = CompactionContent.StartPhase }; + CompactionPayload end = new() { Phase = CompactionContent.EndPhase, Outcome = "unchanged" }; + + Assert.Equal( + """{"phase":"start"}""", + JsonSerializer.Serialize(start, ResponsesJson.Options)); + Assert.Equal( + """{"phase":"end","outcome":"unchanged"}""", + JsonSerializer.Serialize(end, ResponsesJson.Options)); + } + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs index e9b4b1fe..da69be58 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/ResponsesTests.cs @@ -338,53 +338,6 @@ public async Task EditAtAnEarlierMessage_WithdrawsTheWordsAfterIt() Assert.Contains(thirdRequest, m => m.Text.Contains("corrected question", StringComparison.Ordinal)); } - [Fact] - public async Task DialectStream_WritesRendersAsTheirOwnEvents() - { - await using ResponsesHost host = await ResponsesHost.StartAsync( - RenderYaml, - new RenderChatClient(), - configure: options => options.Bind("DrawIt", (Application.Runtime.TurnInvocation? turn) => - { - turn?.Screen?.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); - return ValueTask.FromResult("drew a Card; buttons: none"); - })); - - using HttpResponseMessage response = await host.PostAsync( - /*lang=json,strict*/ - """{ "stream": true, "input": "show me revenue", "agentcore": { "message_id": "m1" } }"""); - List events = await ResponsesHost.ReadEventsAsync(response); - - List chunks = [.. events.Select(text => JsonDocument.Parse(text).RootElement)]; - JsonElement drawing = Assert.Single(chunks, static chunk => chunk.TryGetProperty("agentcore_data", out JsonElement data) - && data.ValueKind != JsonValueKind.Null); - Assert.Equal("generative-ui", drawing.GetProperty("agentcore_data").GetProperty("name").GetString()); - Assert.Equal( - "Q3 revenue", - drawing.GetProperty("agentcore_data").GetProperty("data").GetProperty("title").GetString()); - } - - [Fact] - public async Task PureStream_WritesNoDialectEvents() - { - await using ResponsesHost host = await ResponsesHost.StartAsync( - RenderYaml, - new RenderChatClient(), - configure: options => options.Bind("DrawIt", (Application.Runtime.TurnInvocation? turn) => - { - turn?.Screen?.Publish("generative-ui", "chart-1", new { title = "Q3 revenue" }); - return ValueTask.FromResult("drew a Card; buttons: none"); - })); - - using HttpResponseMessage response = await host.PostAsync(/*lang=json,strict*/ """{ "stream": true, "input": "show me revenue" }"""); - Assert.Equal(HttpStatusCode.OK, response.StatusCode); - List events = await ResponsesHost.ReadEventsAsync(response); - - Assert.DoesNotContain(events - .Select(text => JsonDocument.Parse(text).RootElement), - static chunk => chunk.TryGetProperty("agentcore_data", out JsonElement data) - && data.ValueKind != JsonValueKind.Null); - } private const string TerminalYaml = """ apiVersion: agentcore/v1 @@ -428,36 +381,6 @@ public async Task PureStream_WritesNoDialectEvents() agent: greeter """; - private const string RenderYaml = - """ - apiVersion: agentcore/v1 - tools: - - id: draw_it - kind: binding - binds: DrawIt - description: Draw something for the caller. - agents: - defaults: - model: { ref: reply } - items: - - { id: greeter, instructions: "greet the caller", tools: [ draw_it ] } - - { id: closer, instructions: "close the conversation", tools: [ draw_it ] } - entries: - main: - policy: - initial: greeting - stages: - - { id: greeting, agent: greeter, to: [ { stage: close } ] } - - { id: close, agent: closer, to: [ { stage: greeting } ] } - providers: - conversation: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } - """; - private static ApprovalRequiredAIFunction GatedSendEmail(Action onSend) { return new(AIFunctionFactory.Create( @@ -533,56 +456,6 @@ public void Dispose() } } - /// Calls the first tool it is offered, once, then answers in words. - private sealed class RenderChatClient : IChatClient - { - public async IAsyncEnumerable GetStreamingResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default) - { - await Task.Yield(); - - bool alreadyDrew = messages.Any(message => message.Contents.OfType().Any()); - - if (!alreadyDrew && options?.Tools?.OfType().FirstOrDefault() is { } tool) - { - yield return new ChatResponseUpdate( - ChatRole.Assistant, - [new FunctionCallContent( - "conversation_1", - tool.Name, - new Dictionary(StringComparer.Ordinal) { ["what"] = "a card" })]); - yield break; - } - - yield return new ChatResponseUpdate(ChatRole.Assistant, "here it is."); - } - - public async Task GetResponseAsync( - IEnumerable messages, - ChatOptions? options = null, - CancellationToken cancellationToken = default) - { - List updates = []; - await foreach (ChatResponseUpdate? update in GetStreamingResponseAsync(messages, options, cancellationToken) - .ConfigureAwait(false)) - { - updates.Add(update); - } - - return updates.ToChatResponse(); - } - - public object? GetService(Type serviceType, object? serviceKey = null) - { - return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; - } - - public void Dispose() - { - } - } } /// Reads what one Responses answer carries. diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs index eb083014..5297f7a2 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/SourceWireTests.cs @@ -161,10 +161,6 @@ private static Task PostStreamAsync(ResponsesHost host, str } /// Calls the first tool it is offered, once, then answers in words. - /// - /// Copied from the render chat client in ResponsesTests — that class is private to its own file, - /// so this test needs its own copy of the same shape rather than sharing the type. - /// private sealed class SourceCitingChatClient : IChatClient { public async IAsyncEnumerable GetStreamingResponseAsync( diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs index 4b7cf185..c2e364c9 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/ToolWireTests.cs @@ -13,7 +13,7 @@ namespace AgentCore.AspNetCore.Tests.Endpoints /// /// /// This endpoint owns the tool loop, so the caller never runs a tool and must never be asked to. - /// The facts of the loop ride their own agentcore_tool field, beside agentcore_data, + /// The facts of the loop ride their own agentcore_tool field, beside the other dialect fields, /// where a client that does not know the field ignores it and the browser that does can draw the loop. /// /// diff --git a/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs b/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs index 024f923f..471d02dc 100644 --- a/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/Endpoints/TurnStreamFilesTests.cs @@ -36,14 +36,16 @@ public async Task ResolveAsync_NotedFileTheCaptureKept_YieldsOnePartWithTheLink( files.Note(UpdateWith(refused)); // Act - List parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); + List parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); // Assert: once, linked, and the refused file is not there. - TurnStreamFile part = Assert.Single(parts); - Assert.Equal("chart.png", part.Payload.Name); - Assert.Equal("image/png", part.Payload.MediaType); - Assert.Equal(48213, part.Payload.Length); - Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", part.Payload.Url); + TurnStreamPart part = Assert.Single(parts); + Assert.Equal(TurnStreamPart.File, part.Member); + FilePayload payload = Assert.IsType(part.Payload); + Assert.Equal("chart.png", payload.Name); + Assert.Equal("image/png", payload.MediaType); + Assert.Equal(48213, payload.Length); + Assert.Equal("https://blobs.test/conversation-1/chart.png?ttl=900", payload.Url); } [Fact] @@ -55,10 +57,10 @@ public async Task ResolveAsync_StoreWithNoWebDoor_YieldsThePartWithoutAUrl() files.Note(UpdateWith(Kept("rows.csv", "text/csv", 8))); // Act - List parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); + List parts = await files.ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); // Assert - Assert.Null(Assert.Single(parts).Payload.Url); + Assert.Null(Assert.IsType(Assert.Single(parts).Payload).Url); } [Fact] @@ -68,7 +70,7 @@ public async Task ResolveAsync_NothingNoted_YieldsNothing() Conversations conversations = new(new InMemoryConversationStore(), blobs: null); // Act - List parts = await new TurnStreamFiles().ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); + List parts = await new TurnStreamFiles().ResolveAsync(conversations, "conversation-1", TestContext.Current.CancellationToken).ToListAsync(TestContext.Current.CancellationToken); // Assert Assert.Empty(parts); diff --git a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs index 3b3e0861..95b0479c 100644 --- a/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Conversation/Postgres/PostgresConversationStoreWordsTests.cs @@ -1,8 +1,8 @@ -using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Conversation; using AgentCore.Application.Transcript; using AgentCore.Domain.Audit; +using AgentCore.Domain.Sources; using AgentCore.Infrastructure.Audit.Postgres; using AgentCore.Infrastructure.Conversation.Postgres; using AgentCore.Infrastructure.Tests.Database.Postgres; @@ -334,13 +334,13 @@ public async Task ReadSpokenTurnsAsync_AToolCallingTurn_MatchesTheHashTheChainHo } [PostgresFact] - public async Task ReadSpokenTurnsAsync_AToolCallingTurnThatAlsoDrew_MatchesTheHashTheChainHolds() + public async Task ReadSpokenTurnsAsync_AToolCallingTurnThatAlsoCited_MatchesTheHashTheChainHolds() { - // Arrange — a RenderContent rides the tool-result message alongside its FunctionResultContent. + // Arrange — a SourceContent rides the tool-result message alongside its FunctionResultContent. // The verify query never looks at that row's role, but jsonb round-tripping a second content // type on it must not upset the DISTINCT ON guard or the hash comparison. PostgresConversationStore store = await OpenAsync(); - _ = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday.", drew: true); + _ = await WriteToolCallingTurnAsync(store, "C1", turnIndex: 0, spoken: "Order 41 ships Friday.", cited: true); // Act IReadOnlyList turns = await store.ReadSpokenTurnsAsync("C1", Token); @@ -400,16 +400,21 @@ private static ConversationMessageDraft[] Turn(int turnIndex, int idSeed) /// Writes a tool-calling turn to store 1 and its turn.completed row to store 3. private async Task WriteToolCallingTurnAsync( - PostgresConversationStore store, string conversationId, int turnIndex, string spoken, bool drew = false) + PostgresConversationStore store, string conversationId, int turnIndex, string spoken, bool cited = false) { List toolResultContents = [new FunctionResultContent("id1", "Friday")]; - if (drew) + if (cited) { - toolResultContents.Add(new RenderContent + toolResultContents.Add(new SourceContent { - Name = "generative-ui", - RenderId = "chart-1", - Data = JsonSerializer.SerializeToElement(new { title = "Q3 revenue" }), + Source = new SourceReference + { + SourceId = "card-42", + Kind = SourceKind.Document, + Title = "Order lookup", + Origin = "knowledge", + }, + CallId = "id1", }); }